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

Introduces a clean markdown surface for each docs page and links to it from HTML.

• Add <link rel="alternate" type="text/markdown"> in app/layout.tsx for all non-root pages, pointing to .../<path>.md
• Implement MDX→Markdown compilation in app/api/markdown/[[...slug]]/route.ts:
  • Preserves frontmatter; strips imports/exports and JSX (extracts text from JSX children)
  • Protects code blocks, normalizes indentation, removes excessive blank lines
  • Provides fallback markdown (title/description/link) for component-only pages
  • Sets response headers to Content-Type: text/markdown and returns 404 for missing pages

^{Written by Cursor Bugbot for commit b0682e8. 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 20, 2026 7:53pm

[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.

[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.}