ADR-0001: Use Astro/Starlight For Documentation
Status
Section titled “Status”Accepted
Context
Section titled “Context”The homelab needs a public documentation site that is attractive, operationally precise and technical enough for senior engineers. The documentation supports ADRs, runbooks, postmortems, diagrams, frontmatter validation and freshness metrics.
Decision
Section titled “Decision”Use Astro with Starlight as the documentation platform. Keep the site in the dedicated
portfolio-docs repository so documentation has its own CI policy, publishing lifecycle and
review cadence.
Consequences
Section titled “Consequences”- Starlight provides documentation navigation, search, accessibility and frontmatter validation.
- Astro content collections allow Zod schemas for typed documentation metadata.
- Tailwind CSS can customize the visual identity without replacing Starlight.
- The site publishes cleanly to GitHub Pages or Cloudflare Pages.
- Mermaid rendering needs a separate security and build-performance decision before adding a runtime renderer dependency.