Astro & Starlight

This documentation site is built with Astro and the Starlight documentation theme. Astro produces a static site at build time; Starlight provides the documentation UI (sidebar, search via Pagefind, theming, frontmatter).

• Astro version: ^5.18.0.
• Starlight version: ^0.37.6.
• Repository: documentation/.

Architecture in this codebase

• Single content collection: docs, defined in src/content.config.ts. The schema extends Starlight’s base with description (required, 40–300 chars), author, tags, domain, maturity, lastVerified, source, supersedes, downstream-tracking. Frontmatter is enforced at build time — invalid pages fail astro build.
• Custom remark plugins under plugins/:
  • remark-resolve-md-links.mjs — rewrites .md-style internal links to the rendered URL.
  • remark-plantuml.mjs — renders fenced PlantUML blocks server-side.
  • remark-apply-base-path.mjs — applies the deploy-target base path (/documentation in preview, / in production).
• Component overrides in src/components/overrides/ (Footer, MarkdownContent).
• Files prefixed with _ are excluded from the content collection (Astro’s docsLoader pattern is **/[^_]*.{md,mdx}).

Authoring entry points

• Authoring guide — the canonical starting point for any author.
• Templates — start from a template before writing from scratch.
• knowledge-base/ — repo-specific gotchas (frontmatter, link resolution, MDX, PlantUML).

Authoritative references

• Astro documentation — framework reference.
• Starlight documentation — theme reference.
• Starlight plugin catalogue — community plugins.

Build commands

Command	Purpose
make dev	Local dev server at http://localhost:4321
make build	Production build to dist/
make preview	Build + preview the rendered site locally
make pr-checks	Full pre-push gate (lint, build, link check, smoke)