feat: add automatic markdown alternate links for docs pages

[Kinfe123]

Summary by cubic

Adds automatic text/markdown alternate links for docs pages across frameworks to improve discoverability and agent tooling, without changing page URLs or content. Alternates now preserve the active locale when present.

• New Features

  • Added toDocsMarkdownUrl in @farming-labs/docs to build .md URLs (preserves query/hash; appends lang when missing).
  • Astro, Nuxt, and Svelte themes emit <link rel="alternate" type="text/markdown"> for docs pages when not staticExport, preserving the current locale.
  • Next.js: added @farming-labs/next/mdx-plugins/remark-markdown-alternate to inject markdown alternates via frontmatter; enabled by withDocs, skipped if custom alternates exist.
  • @farming-labs/theme createPageMetadata now sets alternates.types["text/markdown"] when a page url is provided and not staticExport, preserving locale.
  • TanStack Start templates add the alternate link in head using loaderData.url and loaderData.locale when not staticExport.
  • Docs servers (astro, nuxt, svelte, tanstack-start) now include url in load results.

• Migration

  • If you have a custom docs server or loader, include url in the returned page data.
  • To disable alternates: set staticExport: true in docs config, or pass { enabled: false } to the Next remark plugin.

^{Written for commit 714de85. Summary will update on new commits.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	May 8, 2026 10:55pm

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[pkg-pr-new]

Open in StackBlitz

@farming-labs/astro

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/astro@168

@farming-labs/astro-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/astro-theme@168

@farming-labs/docs

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/docs@168

@farming-labs/theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/theme@168

@farming-labs/next

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/next@168

@farming-labs/nuxt

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/nuxt@168

@farming-labs/nuxt-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/nuxt-theme@168

@farming-labs/svelte

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/svelte@168

@farming-labs/svelte-theme

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/svelte-theme@168

@farming-labs/tanstack-start

pnpm add https://pkg.pr.new/farming-labs/docs/@farming-labs/tanstack-start@168

commit: 714de85

[cubic-dev-ai]

1 issue found across 19 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/fumadocs/src/docs-layout.tsx">

<violation number="1" location="packages/fumadocs/src/docs-layout.tsx:627">
P2: Preserve the page locale when generating the markdown alternate URL; otherwise i18n pages will point crawlers to the wrong .md route.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}