Skip to content

Decision record · ADR

ADR-0019: Build the public site with Astro and Starlight in the monorepo

Status: accepted | Date: 2026-07-17

References: RFC-0011, ADR-0008

RFC-0011 requires one public, searchable product and documentation site whose published facts remain owned by the repository’s public documentation projection. ADR-0008 already establishes a two-repository publication topology: the private development repository is authoritative, while the public GitHub repository receives operator-reviewed filtered snapshots and contains no raw governance tree.

InferLab needs more visual and narrative freedom than a documentation-only theme provides, but a bespoke frontend would recreate navigation, search, accessibility, Markdown rendering, and documentation information architecture. The site source must live with the authoritative development content, survive the existing filtered export, consume only public-snapshot inputs at build time, remain entirely static, and deploy automatically under the GitHub Pages project base path after the operator has pushed a snapshot to public main.

The first site is current-only and does not need documentation versioning. Product pages and documentation must share one visual system and one deployment artifact. Private governance validation and public Rust, Python, and website CI keep their existing distinct ownership across ADR-0008’s publication boundary. The repository’s Pixi rule requires pixi.lock to remain the environment lock authority, so the website design must assign the Node/npm runtime environment to Pixi while assigning JavaScript package declarations and resolution to the native website manifests without overlapping dependency facts. The site must not require a runtime backend, deployment secret, CMS, or hosted search service. Content scope, snapshot authority, current-only publication, monotonic deployment, and the GitHub Pages project path are obligations inherited from RFC-0011, not decisions introduced here.

We will build the public product and documentation site with Astro and Starlight inside the InferLab development monorepo because it provides a purpose-built static documentation experience while leaving the product surface free to use custom Astro layouts and components. The website source is part of ADR-0008’s filtered export and therefore appears unchanged in each public snapshot; no third repository or website-only content pipeline is introduced.

The site will use custom Astro pages for product narrative, Starlight for documentation navigation and search, and one build-time projection for the authoritative Markdown files already present in the public snapshot. That projection consumes README.md, selected public files under docs/, and the already-rendered and changelog-stripped docs/rfc and docs/adr trees. It adds presentation metadata and route placement, mechanically maps relative link destinations to website or public-source routes, preserves authoritative prose and link labels, and never reads sources outside the closed public content set.

Website dependency authority is split without overlap: pixi.toml and pixi.lock own the Node/npm runtime environment used locally and in CI; website/package.json owns direct JavaScript package requirements and website commands; website/package-lock.json owns the resolved JavaScript dependency graph. JavaScript packages are not repeated as Pixi dependencies, and CI invokes the website commands through the Pixi environment.

The public repository’s main-branch CI workflow will own Pages publication. Public pull requests validate the website production build. Once the operator has completed the local governance validation, private render, filter, scan, review, and snapshot push required by ADR-0008, public main CI builds one site artifact from that public revision; deployment waits for the public Rust, Python, and website jobs for the same revision. All public main runs share a workflow-level supersession group with cancellation enabled, so arrival of a newer revision cancels the entire older validation-and-deployment run instead of allowing it to reach deployment later. Governance validation is not added to the public repository, and the automatic Pages consequence does not perform or authorize the private-to-public snapshot act.

All published-content boundaries are inherited directly from RFC-0011:C-CONTENT-AUTHORITY, and all current-only, validation, monotonic-deployment, and Pages-path constraints are inherited from RFC-0011:C-DELIVERY. Product presentation may add site-owned visual components and assets. Starlight’s public extension points and standalone Astro pages are preferred over broad internal theme overrides.

  • Product storytelling and technical documentation share one domain, navigation system, search experience, and deployment artifact.
  • Static output requires no website backend, CMS, hosted search service, operator-maintained long-lived credential, or deployment secret.
  • Repository-backed content loading preserves one authority for current user documentation, RFCs, and ADRs.
  • The same-public-revision CI gate prevents a successful website deployment from bypassing failing product checks.
  • Workflow-level supersession prevents a slower older main run from deploying after a newer successful revision.
  • Pixi pins the website runtime environment while the native JavaScript manifests pin the package graph, leaving one owner for each dependency fact.
  • The monorepo gains a Node/npm runtime feature plus a committed website package manifest and lockfile (mitigation: keep environment packages in Pixi, JavaScript packages in the website manifests, and expose a small fixed Pixi task surface).
  • Existing Markdown was not authored for Starlight’s default content directory and schema (mitigation: use one explicit build-time adapter and validate all selected documents in the production build).
  • GitHub Pages project hosting requires base-path-aware links and assets (mitigation: derive and validate the case-sensitive base from the canonical repository identity).
  • Starlight upgrades can change theme extension behavior (mitigation: use documented public components and avoid internal theme forks).
  • A broken website dependency or build can block repository CI and main-branch publication, while website releases cannot advance independently of main (mitigation: keep the static build deterministic, bounded, and isolated in its own CI job so failures are attributable).
  • A new public main revision cancels still-running validation for the previous revision (mitigation: this deliberately favors the only revision still eligible for publication, and pull requests retain their own revision-scoped validation runs).
  • Historical documentation remains available through repository tags and commits rather than through a version selector on the public site.
  • A later custom domain or versioned-documentation requirement would reopen this decision instead of being predesigned into the first release.

Astro with Starlight in this monorepo: use custom Astro pages for the product surface, Starlight for documentation, repository-backed content loaders, and one static GitHub Pages artifact. (accepted)

Section titled “Astro with Starlight in this monorepo: use custom Astro pages for the product surface, Starlight for documentation, repository-backed content loaders, and one static GitHub Pages artifact. (accepted)”
  • Pros: Strong product-page design freedom with low default client JavaScript, Built-in documentation navigation, local search, SEO, i18n readiness, and accessible defaults, One repository revision can validate code, documentation authorities, and the deployed site together
  • Cons: Introduces a Node dependency graph and website lockfile to the monorepo, Existing repository Markdown requires an explicit content adapter instead of Starlight’s default directory-only loader

Docusaurus in this monorepo: use React pages and the Docusaurus documentation plugin for the combined site. (rejected)

Section titled “Docusaurus in this monorepo: use React pages and the Docusaurus documentation plugin for the combined site. (rejected)”
  • Pros: Mature React and MDX ecosystem, First-class documentation versioning if that later becomes necessary
  • Cons: Carries a heavier client and theme model than the current static content needs, Its strongest differentiator, built-in versioning, is explicitly out of scope
  • Rejected because: Without documentation versioning or existing React components to reuse, Docusaurus adds complexity without a corresponding current workflow benefit.

VitePress in this monorepo: extend its default Vue documentation theme into a product website. (rejected)

Section titled “VitePress in this monorepo: extend its default Vue documentation theme into a product website. (rejected)”
  • Pros: Small, fast documentation-oriented foundation with local search
  • Cons: A distinctive product surface would require maintaining a larger custom Vue theme, The solution starts from a documentation shell rather than a product site with an embedded documentation system
  • Rejected because: The required product identity would shift too much long-term ownership into custom theme code.

Keep the product website in a third, website-only repository and import or copy InferLab documentation during deployment. (rejected)

Section titled “Keep the product website in a third, website-only repository and import or copy InferLab documentation during deployment. (rejected)”
  • Pros: Independent frontend release cadence and dependency graph
  • Cons: A third repository introduces a second revision authority and requires a pinned cross-repository revision or digest protocol to prove which site source corresponds to each public InferLab snapshot, Content import or copying creates synchronization and preview complexity
  • Rejected because: The separation cannot retain RFC-0011’s one-public-revision build and gate model without either replacing it with a two-revision coordination protocol or copying the website source back into the InferLab public snapshot.

Astro without Starlight: build a custom documentation shell alongside the product pages. (rejected)

Section titled “Astro without Starlight: build a custom documentation shell alongside the product pages. (rejected)”
  • Pros: Maximum control over product and documentation presentation with one rendering framework, No dependency on Starlight theme extension contracts
  • Cons: InferLab would own sidebar navigation, search integration, documentation accessibility, table-of-contents behavior, Markdown affordances, and their long-term maintenance, More site code would encode generic documentation mechanics instead of InferLab product value
  • Rejected because: The additional ownership has no demonstrated InferLab-specific requirement and recreates mature documentation infrastructure.