feat(llm-exports): MDX template overrides and declarative page sections by dcramer · Pull Request #16417 · getsentry/sentry-docs

dcramer · 2026-02-17T20:49:08Z

Improve the LLM markdown export pipeline (generate-md-exports.mjs) with
structured page customization. Previously, custom pages like index.md
were built entirely from JS string concatenation (~30+ line builder
functions), and two separate override registries with incompatible
interfaces handled content vs. navigation overrides.

This introduces a two-layer architecture:

MDX templates (md-overrides/) for pages needing fully custom content.
Templates use React components (PlatformList, FrameworkGroups,
DocSectionList) that close over docTree and render to HTML. The
rendered HTML flows through the existing worker pipeline — link rewriting,
caching, and R2 sync all work automatically with no special handling.

Declarative pageOverrides table for appended navigation sections.
Each entry declares {heading, items} pairs instead of imperative builder
functions. Shared utilities (nodeLinks, childLinks,
siblingGuideLinks) handle the common patterns. A build escape hatch
remains for complex cases like the grouped platforms page.

This replaces ~10 builder functions and merges the two override registries
into a single unified system. The spec at specs/llm-friendly-docs.md is
updated to document the new architecture.

Closes #16413

…gation Load public/doctree.json to replace raw slug names with proper titles in generated .md files. Adds a sectionOverrides registry for clean per-page customization of appended navigation sections. Changes: - Root index.md: platforms by title, frameworks grouped by platform, doc sections by title - platforms.md: structured Platforms + Frameworks sections - Platform pages (e.g. platforms/javascript.md): "Frameworks" with proper titles, sorted "Topics" - Guide pages (e.g. platforms/javascript/guides/nextjs.md): "Other Frameworks" + "Topics" - All other section pages: titles and sidebar_order from doctree - Graceful fallback to slug-based output if doctree unavailable Closes #16413 Co-Authored-By: Claude <noreply@anthropic.com>

- Refactor root index.md generation to use contentOverrides registry (same pattern as sectionOverrides but for full page replacement) - Track content override results for proper R2 upload handling - Add specs/llm-friendly-docs.md documenting the content negotiation system, override architecture, and page customization patterns Co-Authored-By: Claude <noreply@anthropic.com>

…ports Replace imperative JS builder functions with two-layer customization: - MDX templates in md-overrides/ for full-page content (like root index.md) with custom components (PlatformList, FrameworkGroups, DocSectionList) - Declarative pageOverrides table for appended navigation sections MDX templates are rendered to HTML via React SSR, then flow through the existing HTML→MD worker pipeline automatically getting link rewriting, caching, and R2 sync. This replaces ~10 builder functions and two separate override registries with a unified architecture. Co-Authored-By: Claude <noreply@anthropic.com>

vercel · 2026-02-17T20:49:14Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview, Comment	Feb 17, 2026 10:33pm
sentry-docs	Ready	Preview, Comment	Feb 17, 2026 10:33pm

scripts/generate-md-exports.mjs

Use non-recursive readdir for md-overrides/ so that dev/ subdirectory files are not discovered during production builds. Co-Authored-By: Claude <noreply@anthropic.com>

…ms.md - index.md now shows full sitemap: platforms, frameworks, and every top-level section with its children expanded (via SectionTree component) - platforms.md gets MDX override with curated platforms/frameworks listing, doc sections, and quick links - Add SectionTree component that renders doctree sections with children Co-Authored-By: Claude <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

md-overrides/platforms.mdx

The H1 already comes from the frontmatter title, so the H2 was redundant. Co-Authored-By: Claude <noreply@anthropic.com>

Replace "/platforms" link (which points to itself) with a link back to the root documentation index. Co-Authored-By: Claude <noreply@anthropic.com>

sentry · 2026-02-17T22:06:36Z

scripts/generate-md-exports.mjs

      await mkdir(targetDir, {recursive: true});
      const targetPath = path.join(targetDir, dirent.name.slice(0, -5) + '.md');
      const relativePath = path.relative(OUTPUT_DIR, targetPath);
+      // Use MDX override HTML if available, otherwise use Next.js build HTML
+      const mdxOverride = mdxOverrides.get(relativePath);
      workerTasks[workerIdx].push({
-        sourcePath,
+        sourcePath: mdxOverride ? mdxOverride.htmlPath : sourcePath,
        targetPath,
        relativePath,
        r2Hash: existingFilesOnR2 ? existingFilesOnR2.get(relativePath) : null,


Bug: MDX overrides are silently ignored if their corresponding Next.js-generated HTML file is missing, with no warning or error logged to indicate the override was not applied.
_{Severity: MEDIUM}

Suggested Fix

After the file discovery loop finishes, iterate through the mdxOverrides map. For each override that was rendered, check if it was consumed and processed by a worker. If any overrides were not used, log a warning to the console indicating which MDX files were ignored. This will alert developers to configuration issues or typos.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: scripts/generate-md-exports.mjs#L600-L609 Potential issue: The script processes MDX overrides by first looking for corresponding `.html` files generated by Next.js in the `.next/server/app/` directory. A worker task to process an MDX override is only created if a matching HTML file is found. If a developer adds an MDX override file (e.g., `new-page.mdx`) but Next.js fails to generate the corresponding HTML file (e.g., due to a typo or a configuration issue), the override will be silently ignored. The script logs that the override was rendered to an intermediate HTML file, but provides no warning or error that it was never actually used, which could lead to confusion and outdated content being deployed.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

Prevents silent failures when an override file has a typo or its corresponding page doesn't exist in the build output. Co-Authored-By: Claude <noreply@anthropic.com>

sergical

lgtm apart from the yarn.lock not being part of this, but idk if its already a dependency there and there are no changes because you're just explicitly adding the dependency that was already there from mdx-js

package.json

dcramer and others added 3 commits February 17, 2026 11:25

dcramer changed the title ~~feat: MDX template overrides and declarative page sections for LLM exports~~ feat(llm-exports): MDX template overrides and declarative page sections Feb 17, 2026

vercel bot deployed to Preview – develop-docs February 17, 2026 20:55 View deployment

vercel bot deployed to Preview – sentry-docs February 17, 2026 20:58 View deployment

cursor bot reviewed Feb 17, 2026

View reviewed changes

scripts/generate-md-exports.mjs Outdated Show resolved Hide resolved

fix: prevent dev MDX overrides from leaking into production builds

c2b2eb3

Use non-recursive readdir for md-overrides/ so that dev/ subdirectory files are not discovered during production builds. Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview – develop-docs February 17, 2026 21:10 View deployment

vercel bot deployed to Preview – sentry-docs February 17, 2026 21:14 View deployment

vercel bot deployed to Preview – develop-docs February 17, 2026 21:27 View deployment

vercel bot deployed to Preview – sentry-docs February 17, 2026 21:30 View deployment

cursor bot reviewed Feb 17, 2026

View reviewed changes

md-overrides/platforms.mdx Outdated Show resolved Hide resolved

fix: remove duplicate Platforms heading in platforms.md

61fa729

The H1 already comes from the frontmatter title, so the H2 was redundant. Co-Authored-By: Claude <noreply@anthropic.com>

dcramer force-pushed the improve-llm-md-exports branch from 13af8b8 to 61fa729 Compare February 17, 2026 21:44

vercel bot deployed to Preview – develop-docs February 17, 2026 21:49 View deployment

vercel bot deployed to Preview – sentry-docs February 17, 2026 21:53 View deployment

dcramer mentioned this pull request Feb 17, 2026

Optimize .md exports for LLM agent page-relevance heuristics #16420

Open

fix: remove self-referential link in platforms.md quick links

dbd34de

Replace "/platforms" link (which points to itself) with a link back to the root documentation index. Co-Authored-By: Claude <noreply@anthropic.com>

vercel bot deployed to Preview – develop-docs February 17, 2026 22:05 View deployment

sentry bot reviewed Feb 17, 2026

View reviewed changes

vercel bot deployed to Preview – sentry-docs February 17, 2026 22:09 View deployment

dcramer and others added 2 commits February 17, 2026 14:24

fix: warn when MDX overrides don't match any HTML file

17bbbcf

Prevents silent failures when an override file has a typo or its corresponding page doesn't exist in the build output. Co-Authored-By: Claude <noreply@anthropic.com>

[getsentry/action-github-commit] Auto commit

f1830d2

vercel bot deployed to Preview – develop-docs February 17, 2026 22:30 View deployment

vercel bot deployed to Preview – sentry-docs February 17, 2026 22:33 View deployment

sergical approved these changes Feb 17, 2026

View reviewed changes

package.json Show resolved Hide resolved

dcramer merged commit 0131176 into master Feb 17, 2026
15 checks passed

dcramer deleted the improve-llm-md-exports branch February 17, 2026 23:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(llm-exports): MDX template overrides and declarative page sections#16417

feat(llm-exports): MDX template overrides and declarative page sections#16417
dcramer merged 9 commits intomasterfrom
improve-llm-md-exports

dcramer commented Feb 17, 2026 •

edited

Loading

Uh oh!

vercel bot commented Feb 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

sentry bot Feb 17, 2026

Uh oh!

sergical left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

dcramer commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sentry bot Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

sergical left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dcramer commented Feb 17, 2026 •

edited

Loading

vercel bot commented Feb 17, 2026 •

edited

Loading