Docs Platform
Context
Section titled “Context”The initial candidates were Zola, Astro Starlight, and Fumadocs. The docs site needs to be easy to host on Cloudflare, friendly to Markdown contributors, capable of explaining both civic and technical material, and light enough that documentation work does not become application work.
Similar repositories discovered
Section titled “Similar repositories discovered”Repository data was checked on 2026-05-16.
| Repository | Description | Stars | Notes |
|---|---|---|---|
facebook/docusaurus | Open source documentation websites. | 64,928 | Mature React docs framework with large ecosystem. |
docsifyjs/docsify | Documentation site generator. | 31,204 | Static-host friendly, runtime-rendered Markdown. |
squidfunk/mkdocs-material | MkDocs theme and documentation framework. | 26,729 | Strong Markdown docs option with Python toolchain. |
vuejs/vitepress | Vite and Vue powered static site generator. | 17,720 | Strong Vue ecosystem fit. |
getzola/zola | Single-binary static site generator. | 17,062 | Fast Rust SSG, broad static site features. |
shuding/nextra | Next.js site generation framework. | 13,796 | Good for teams already centered on Next.js. |
fuma-nama/fumadocs | React docs framework. | 11,864 | Flexible, strong for Next.js and React framework composition. |
withastro/starlight | Documentation websites with Astro. | 8,491 | Static-first docs framework, built for Markdown and MDX. |
sphinx-doc/sphinx | Documentation generator. | 7,834 | Strong for Python and reStructuredText-heavy docs. |
web-infra-dev/rspress | Rsbuild-based static site generator. | 2,225 | Modern MDX docs option with smaller ecosystem. |
Options considered
Section titled “Options considered”| Option | Strength | Concern |
|---|---|---|
| Zola | Single binary, fast builds, simple static hosting path. | More theme and template work before it feels like a full docs product. |
| Fumadocs | Flexible React docs system with strong MDX and component model. | Best fit when the project already wants a React or Next.js app surface. Static export requires framework-specific configuration. |
| Astro Starlight | Documentation-focused, static-first, Markdown friendly, and deployable as a Cloudflare-hosted static site. | Less headless than Fumadocs if the site becomes a custom app later. |
Decision
Section titled “Decision”Use Astro Starlight for the first docs site.
The deciding factors are static Cloudflare hosting, a docs-first information architecture, built-in navigation and search, Markdown-first authoring, and a small implementation surface. This repository is still at the seed and discovery stage. The site should make the thinking navigable before it becomes a custom web app.
Consequences
Section titled “Consequences”- The site builds with
npm run build. - Cloudflare deployment is declared in
alchemy.run.ts. - Content lives under
src/content/docs/. - Architecture diagrams live as D2 source in
diagrams/and rendered SVG inpublic/diagrams/. - If the project later needs application-like docs or embedded product UI, Fumadocs can be reconsidered from this decision record.