Platform Choice
Decision
Astro Starlight is the platform
The manual needs a fast documentation product, not a SaaS docs account or a generic markdown dump. Starlight gives strong documentation defaults and enough component flexibility for figures, scorecards, and generated publication artifacts.
Chosen: Astro Starlight, because it is static, MDX-native, searchable by default, accessible, dark-mode capable, and friendly to generated content.
| Candidate | Decision | Rationale |
|---|---|---|
| Astro Starlight | Chosen | Best fit for generated static docs with MDX, built-in Pagefind search, dark mode, accessible defaults, custom Astro components, and low operational complexity. |
| Docusaurus | Strong but heavier | Excellent mature docs framework, but React-first and heavier than this source-generated publication needs. |
| Nextra | Good but app-shaped | Elegant Next.js MDX docs, but the Next runtime/app model is unnecessary for a static manual product. |
| MkDocs Material | Excellent reference docs | Fast and polished for Python/Markdown docs, but less natural for custom product mockups and component-rich MDX surfaces. |
| Mintlify | Not chosen | Beautiful hosted docs experience, but weaker fit for local generation, print artifacts, and avoiding proprietary/SaaS coupling. |
Implementation implications
Section titled “Implementation implications”- One source:
docs/OPERATING_MANUAL.mdremains canonical prose. - Generated site: chapter pages, reader paths, product mockups, cards, and concept maps are generated.
- Generated artifacts: publication Markdown, DOCX, and PDF are produced under
docs-product/dist/publication/. - No architecture change: presentation metadata adds navigation and visual explanations only.