Add markdown alternate links for LLM training data discovery

[nearestnabors]

Summary

• Add <link rel="alternate" type="text/markdown"> to all page headers, pointing to the .md version of each page
• Improve the MDX-to-markdown compilation so .md URLs return clean, readable markdown instead of raw MDX
• Add fallback content for component-only pages (like the landing page) that shows the title, description, and link to the full interactive page

This enables LLM crawlers and training pipelines to discover and consume the markdown versions of our documentation, similar to what Vercel does with their docs.

Test plan

• Visit any page and check the HTML source for <link rel="alternate" type="text/markdown" href="...">
• Visit https://docs.arcade.dev/en/get-started/quickstarts/call-tool-agent.md - should return clean markdown with code blocks preserved
• Visit https://docs.arcade.dev/en/home.md - should return fallback content with title/description and link to full page

🤖 Generated with Claude Code

---

Note

Enables discovery and consumption of Markdown-rendered docs alongside MDX pages.

• New app/api/markdown/[[...slug]]/route.ts compiles MDX to clean Markdown: preserves frontmatter, strips imports/exports and JSX, converts Image to ![alt](url), maps internal links to .md, normalizes indentation, and provides fallback title/description for component-only pages
• GET handler now reads page.mdx, compiles via compileMdxToMarkdown, and serves text/markdown
• app/layout.tsx: injects <link rel="alternate" type="text/markdown" href="https://docs.arcade.dev{pathname}.md"> on all non-root pages

^{Written by Cursor Bugbot for commit c43e842. This will update automatically on new commits. Configure here.}

[vercel]

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

Project	Deployment	Review	Updated (UTC)
docs	Ready	Preview, Comment	Jan 23, 2026 9:50pm

[evantahler]

On https://docs-git-feature-add-md-alternate-links-arcade-ai.vercel.app/en/get-started/quickstarts/call-tool-agent.md, there's something weird with the insertion of new codeblocks. The "```" I think needs to be at the start of the line

[nearestnabors]

@evantahler Got a minute to have a second look?

[evantahler]

I like the <link rel="alternate" type="text/markdown"> idea a lot that this PR introducdes, but I'm curious as to why the MDX needed to 'rendered' to MD? Were the react components harming LLM legibility? There are still HTML elements in the pages (e.g. https://docs-git-feature-add-md-alternate-links-arcade-ai.vercel.app/en/get-started/setup/api-keys.md). Are HTML fragments OK?

If the goal is to keep html fragments, buy 0-out react, I'd suggest an alternative approach:

• make a new MDX renderer in app/api/markdown/[[...slug]]/route.ts
• pass a wildcard react component that returns "</>"
• rather than using regular expressions, render the mdx to md "for real", preserving anything that wasn't react.

[nearestnabors]

@evantahler Dammit!

So when agents parse markdown, HTML and MDX getting mixed in there make it hard on them. IIIRC from the friend who did this, the entire thing needs rendering down to markdown.

What approach do you recommend in light of this?

[nearestnabors]

Actually, let me just try parsing the HTML back into Markdown. We have some complex MDX.

[teallarson]

@nearestnabors I looked at the deploy preview and am not seeing the <link rel="alternate" type="text/markdown"> (here's the page I was on: https://docs-j0lo97vmm-arcade-ai.vercel.app/en/get-started/quickstarts/call-tool-client). I should see that, right?

I visited the .md version of the page, and I see components and imports, but they are rendering as text not as whatever the .mdx would spit out, so maybe that's the intention here.

[cursor]

Bugbot Autofix resolved the bug found in the latest run.

• ✅ Fixed: JSX expression regex fails with nested braces
  • Replaced simple regex with existing BRACE_PATTERN that properly handles up to 3 levels of nested braces, fixing issues with expressions like {obj || {default: true}} and {items.map(x => ({a: x}))}.

[cursor]

Bugbot Autofix resolved all 3 bugs found in the markdown API route regex patterns.

• ✅ Fixed: IMAGE_COMPONENT_REGEX fails on > in attributes
  • Updated IMAGE_COMPONENT_REGEX to use JSX_ATTRS_PATTERN which properly handles > characters inside quoted attributes.
• ✅ Fixed: Internal links with fragments get .md placed incorrectly
  • Modified INTERNAL_LINK_REGEX to capture path and fragment separately, ensuring .md is inserted before the fragment.
• ✅ Fixed: Image alt/src with apostrophes get truncated
  • Updated IMAGE_ALT_REGEX and IMAGE_SRC_REGEX to match quote types separately, preventing apostrophes from truncating values.

[cursor]

Bugbot Autofix resolved the bug found in the latest run.

• ✅ Fixed: Code block state tracking fails on embedded fences
  • Modified normalizeIndentation to track opening fence indentation and only treat ``` lines as closing fences when not indented more than the opening fence, preventing false toggles for embedded fence markers.

[cursor]

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

^{Bugbot Autofix is ON. A Cloud Agent has been kicked off to fix the reported issue.}

[cursor]

Bugbot Autofix resolved the bug found in the latest run.

• ✅ Fixed: Wrong operation order causes incorrect indentation in extracted content
  • Swapped operation order from dedent(content.trim()) to dedent(content).trim() at all four occurrences (lines 256, 260, 264, and 300) to ensure dedent calculates minimum indentation correctly before trimming.