Skip to content

Serve a Markdown twin of every docs page and post, linked from llms.txt - #202

Merged
cargopete merged 3 commits into
mainfrom
pete/markdown-twins
Nov 18, 2026
Merged

cargopete merged 3 commits into
mainfrom
pete/markdown-twins

Conversation

@cargopete

Copy link
Copy Markdown
Collaborator

Every docs page and blog post now has a Markdown twin at its path plus .md, built from the same collection entry the HTML page renders, so it cannot drift: /docs/ai/mcp.md, /blog/.md, and /docs.md listing every docs twin. Site-relative links inside a twin point at other twins or absolute URLs. Each HTML page links its twin with rel=alternate, and llms.txt, llms-full.txt and robots.txt point at the twins.

The site is static Astro on Vercel. Vercel cannot negotiate a static file by Accept, but its routing middleware can, and middleware.ts already runs for /subgraphs; it now answers a docs or blog request carrying Accept: text/markdown with the twin, Vary: Accept. vercel.json sets text/markdown on .md files. Neither was tried on Vercel: the middleware was driven locally with a stubbed fetch through ten cases.

A new build step fails if a sitemap docs or blog page lacks a twin or llms.txt links an HTML docs URL. It caught the sitemap listing /docs/book/index, a 404, fixed here. Not done: /agents has no twin (it is not Markdown), and the version line is still hand-written, though version-check already fails CI on it.

npm run build and astro check exit 0.

Part of nuthatch-org/nuthatch#2980.

@cargopete
cargopete merged commit 8272fb5 into main Nov 18, 2026
1 check passed
@cargopete
cargopete deleted the pete/markdown-twins branch November 18, 2026 06:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant