Skip to content
Principal AI Engineer Handbook

ADR-0001: Use Astro + Starlight for the documentation platform

Listen to this page02:58
Read the transcript

1. The problem with hand-written HTML at scale

Host: So let’s start at the beginning: why does a documentation project even need an architecture decision record for its own website? Walk us through what this handbook actually looked like before any of this.

Guest: It started as hand-written HTML — an index.html, a folder per module, each with its own index.html, plain CSS and a little JS. That’s totally fine for two modules, but there’s no content model, no search, no versioning, and every single new page means re-writing navigation, head tags, and responsive layout by hand again. The project’s actual goal is to become the reference documentation system for Principal AI Engineers over years and hundreds of pages, so whatever we picked had to hold up at that scale, not just look okay for the first ten pages.

2. Weighing the framework field

Host: So static HTML was out. What else did the project actually put on the table before landing on Astro and Starlight?

Guest: Three real contenders. Docusaurus is the obvious mature choice, plugin-rich and React-based, but that React-everywhere model means a heavier runtime and slower builds than Astro’s island architecture, which is a bad trade for a site that’s mostly static content. Then VitePress and Nextra, both fast, both fine for API-reference docs, but neither has the ecosystem this project needs around ADR templates, printable cheat sheets, or a shared component library across a monorepo of labs.

Host: And Astro plus Starlight cleared all three of those bars at once?

Guest: Pretty much — Astro ships zero JS by default and only hydrates the specific components that need interactivity, like the theme toggle or the Mermaid renderer, so it stays fast even as the page count grows. Starlight layers content collections with Zod schema validation, Pagefind search, dark mode, and an accessible component set right on top of that, which is more docs-framework completeness than VitePress or Nextra offer out of the box. And since the two projects version in lockstep, we weren’t betting on a fragile pairing.

3. The decision and what it costs going forward

Host: So let’s land the plane — what did the team actually commit to, and where does it bite them later?

Guest: Astro 7 with Starlight, content in the docs collection validated by a schema, and a Tailwind v4 theme layered over Starlight’s CSS variables for the custom look. The cost is real: a missing frontmatter field now fails the build instead of shipping, search and nav and dark mode are inherited rather than hand-tuned, and anything that isn’t a folder of Markdown with frontmatter needs a custom page outside the collection — which is exactly what ADR-0004 has to solve for new content types. But it’s accepted, it’s live, and it’s the site you’re reading this on.

Generated from this page by Claude Sonnet 5 on , spoken by Kokoro-82M running locally. Two synthetic voices, not a recorded conversation. Every claim is drawn from this page — where it differs from the text above, the text is correct.

ADR-0001acceptedAugust 4, 2026

Status

Section titled “Status”

Accepted. The site you’re reading this on is built with it.

Context

Section titled “Context”

The handbook started as a hand-written static HTML site (index.html, modules/*/index.html, plain CSS/JS) — reasonable for two modules, but it has no content model, no search, no versioning, and every new page means hand-writing navigation, head tags, and responsive layout again. The project’s stated goal is to become the reference documentation system for Principal AI Engineers over multiple years and hundreds of pages, which means the platform decision made now has to hold up at that scale, not just for the first ten pages.

Problem

Section titled “Problem”

Which documentation framework gives us content collections with schema validation, built-in offline-capable search, dark mode, accessible navigation, and a component model for reusable elements (callouts, diagrams, ADR templates) — without locking the project into a narrow plugin ecosystem or a slow build for hundreds of pages?

Options

Section titled “Options”
  • Keep hand-written static HTML. Zero framework risk, but no content model, no search, and every structural change (like adding the versioning fields this platform requires) means editing every page by hand. Doesn’t scale past the two modules that already existed.
  • Docusaurus. Mature, plugin-rich, React-based. Heavier runtime and slower builds at scale than Astro’s island architecture; MDX support is solid but the React-everywhere model works against a content-heavy, mostly-static site.
  • VitePress / Nextra. Fast, Vue- or Next-based respectively. Both are strong for API-reference style docs but have a smaller ecosystem for the specific things this project needs: ADR templates, printable cheat sheets, and a component library shared with a monorepo of labs. Neither has a docs-framework layer as complete as Starlight’s out of the box (sidebar autogeneration from content collections, built-in Pagefind search, i18n, accessible components audited against WCAG).
  • Astro + Starlight. Astro ships zero JS by default and only hydrates the components that need it (the theme toggle, the Mermaid renderer); Starlight adds content collections with Zod schema validation, Pagefind search, dark mode, and an accessible component set on top. Both are actively maintained and version in lockstep with each other.

Decision

Section titled “Decision”

Build the platform on Astro 7 with the @astrojs/starlight integration. Content lives in Starlight’s docs content collection (validated by the schema in apps/handbook/src/content.config.ts); site chrome, search, and navigation come from Starlight; custom visual identity comes from a Tailwind v4 theme layered over Starlight’s CSS variables (see packages/ui/src/tokens.css).

Consequences

Section titled “Consequences”
  • Content authors write MDX with frontmatter validated at build time — a missing required field fails the build instead of shipping a broken page.
  • Search, dark mode, and accessible navigation are inherited from Starlight rather than hand-maintained, which is less flexible than a fully custom site but removes an entire category of bugs this project doesn’t need to own.
  • The project is coupled to Starlight’s content collection model: sections that don’t map cleanly onto “a folder of Markdown/MDX pages with frontmatter” (there aren’t any today) would need a custom Astro page outside the collection.
  • Every new content type still needs its own required-frontmatter contract; ADR-0004 covers how that’s enforced without fragmenting Starlight’s single collection schema.

References

Section titled “References”