ADR-0013: Docs subsite — Astro Starlight on Cloudflare Pages

Status: Accepted
Date: 2026-07-30
Supersedes: —
Superseded by: —

Context

Collaborators need to read the architecture, decisions, standards and backlog without a checkout — at a URL, with search and navigation.

Decision

Build the subsite with Astro Starlight as apps/docs, deployed to Cloudflare Pages.

Single-sourcing rule: all authored markdown lives under docs/ at the repo root — docs/decisions/, docs/standards/, docs/work/, docs/architecture.md. Starlight reads it through an Astro content-collection loader, glob({ base: '../../docs' }).

No symlinks, no duplicated files, no copy step.

Rationale

Zero new stack decisions: Astro is already chosen for web (ADR-0009) and Cloudflare for hosting (ADR-0001).
Starlight gives search, nav and dark mode with essentially no configuration, at £0.
The glob loader means editing an ADR updates the site in the same commit, with no second edit anywhere. Documentation that requires a second step is documentation that rots.
Living in the monorepo means docs ship in the same PR as the feature — enforced by the docs-diff gate step.

Consequences

Markdown under docs/ needs Starlight-compatible frontmatter (title, description). This is the cost of the single-source approach and it is small.
A symlink-based approach was explicitly rejected: symlinks are painful on Windows and across the WSL boundary (ADR-0014).
docs/architecture.md stays where it is and is rendered by the site rather than moved into it.

Alternatives considered

Docusaurus. Most mature docs framework with strong versioning. Rejected: pulls React and its own build toolchain into a repo that deliberately avoided React on the web side.

MkDocs Material. Excellent output, least config. Rejected: adds Python to a pnpm/Turborepo toolchain — a second CI runtime for agents to manage.

Plain markdown on GitHub. Zero build step. Rejected: no search, no nav, and no URL for anyone who isn’t a repo collaborator.