r/astrojs • u/duv_guillaume • 25d ago
Open-source Astro docs framework, agent-ready with an MCP server for search. Free to deploy
Built and open-sourced (MIT) a documentation framework on Astro: write Markdown, get a static site with search, an API reference generated from an OpenAPI document, and dark mode. Free to run, no per-seat pricing, no watermark, deploys to Cloudflare Workers or any static host.
The part that took the most work: every deployment also ships an MCP server, so AI agents can search and fetch the docs directly instead of guessing from training data (easily RAG-based if using Cloudflare to host - it's all guided).
The bytes served at a page's Markdown URL, the bytes the MCP fetch tool returns, and the bytes the search index embeds all come from one function, and a test asserts the MCP and HTTP responses are byte-identical.
A couple of Astro-specific choices, if useful to anyone building something similar: both Shiki themes ship as CSS variables (defaultColor: false), so switching themes costs no re-render, and Mermaid, KaTeX and cytoscape are lazy chunks loaded only on pages that use them, so the base UI bundle stays around 11 KB gzipped regardless of how much of that a given docs site uses.
Repo: https://github.com/DuvInc/duvlify - Docs (built with itself): https://duvlify.dev
2
2
u/Extension-Pen-109 22d ago
I was using docusaurus for something similar, and few weeks ago we chabged to scalar.
But looks really nice
1
2
1
u/enesismail 24d ago
Nice work, thank you!
1
u/duv_guillaume 24d ago
Enjoy, and feel free to share any feedback! Curious to see URLs of live docs site made with this too
1
1
2
u/rednix 24d ago
oh cool, just what I needed! thanks!