ADR-021 — Documentation site at /docs/ via VitePress

Status · Accepted Date · 2026-04-29 TA anchor · §stack

Context

The project's docs/ directory contains 50+ markdown files spanning concept package (00–05), ADRs (TA + 19 + this one), RFCs, PRDs, UXSes, plus six prototype HTMLs. Until now these were viewed only on GitHub. As the project approached v1, two needs emerged:

1. The docs are the project's single best onboarding surface — a public-facing docs site improves discoverability and shareability.
2. The prototypes are HTML files referenced throughout the docs; serving them at predictable URLs makes the cross-references actually clickable.

Scope expansion landed late April 2026: build the docs into a static site and publish alongside the main app on GitHub Pages.

Decision

VitePress as the static site generator, deployed at /orrery/docs/ (sibling of the main app at /orrery/).

Stack choice

Considered	Result
VitePress	✅ Chosen. Same Vite ecosystem we already run; markdown-first; auto-sidebar via vitepress-sidebar; lightweight (~1MB output); first-class search; clean URLs.
MkDocs / MkDocs Material	Rejected. Adds Python toolchain.
mdBook	Rejected. Adds Rust toolchain.
Docusaurus	Rejected. React-based; heavier than needed for engineering docs.
Astro Starlight	Plausible, more flexible than VitePress but heavier; deferred.

Layout

• Source: docs/ (existing markdown + docs/.vitepress/{config.ts,theme/})
• Build output: docs/.vitepress/dist/ (gitignored)
• Deploy: copied into the main build/docs/ artifact in CI; both app and docs ship via the same peaceiris/actions-gh-pages@v3 step
• URLs:
  • chipi.github.io/orrery/ — main app
  • chipi.github.io/orrery/docs/ — docs site
  • chipi.github.io/orrery/docs/prototypes/P0X_*.html — prototypes (copied verbatim from docs/prototypes/ during docs:build)

Theme

Default VitePress theme with one custom override: --vp-c-brand-1: #4466ff matching src/lib/styles/tokens.css --color-accent. Auto-sidebar from vitepress-sidebar. Local search (no Algolia dependency). No other branding — engineering docs prioritise readability over identity.

Linkage between app and docs

• Docs nav has an "↗ Live App" link to chipi.github.io/orrery/
• Main app does not link to docs (per user direction: docs is separate from product)

Rationale

VitePress reuses the Vite/SvelteKit ecosystem we already operate, avoiding a second toolchain. Markdown-first means the 50+ existing docs need no rewrites. Auto-sidebar keeps the burden low as we add docs over time. Static export integrates with the existing peaceiris/actions-gh-pages deploy in one extra step. The site is fast (build < 2 s, page-load < 200 ms typical) and the entire docs pipeline adds ~120 KB to the deployed artifact.

Alternatives considered

• Embed docs into the SvelteKit app (e.g., via mdsvex) — couples docs build to app build; bloats the app bundle with markdown content; harder to navigate. Rejected.
• Separate gh-pages-docs repo — clean separation but separate URL hurts discovery; an extra repo to maintain. Rejected.
• No docs site, just GitHub view — current state pre-2026-04-29; works but offers no search, no nav, no public link. Replaced by this decision.

Consequences

Positive:

• Public docs at a stable URL; markdown stays the source of truth
• Prototypes accessible at predictable URLs from anywhere in the docs
• One deploy pipeline; one artifact; one gh-pages branch
• Search works out of the box

Negative:

• Two npm dependencies added (vitepress, vitepress-sidebar) — both small and well-maintained
• Build time grows by ~2s for the docs step in CI

Implementation notes

• Config: docs/.vitepress/config.ts (auto-sidebar via vitepress-sidebar.generateSidebar)
• Theme override: docs/.vitepress/theme/{index.ts,custom.css}
• npm scripts: docs:dev, docs:build, docs:preview
• CI: preview.yml runs docs:build with DOCS_BASE=/orrery/docs/, then cp -R docs/.vitepress/dist build/docs
• ESLint ignores docs/.vitepress/{dist,cache}/