Skip to content

ADR-0020: Documentation with Starlight at /docs

  • Status: Accepted
  • Date: 2026-11-15

The product needs two public documentations, readable without an account: a user guide and the system documentation. Both must keep up with the product as new areas are released.

Where does the documentation live, and how is it published?

  • Documentation changes in the same review as the code it describes.
  • No new infrastructure to publish it.
  • Search, light and dark themes, and diagrams written as text.
  • The same visual identity as the product.
  1. Astro with Starlight, in a new app of the repository, apps/docs.
  2. Another documentation generator, or a hosted documentation service. Common market alternatives, listed for comparison.

Chosen option: 1. The repository already uses Astro for the landing site and the careers site (ADR-0008), so no new tool chain is added.

apps/docs builds a static site with base: '/docs'. The sidebar is generated from the folders of src/content/docs and from the sidebar.order of each page. Search is the one built into Starlight. Diagrams are Mermaid code blocks, drawn in the browser. Colours, fonts and radii come from the tokens of packages/ui, mapped to the theme variables in one stylesheet (ADR-0010).

Publishing uses the landing site: its build depends on the documentation build and copies the output into its own docs/ folder, so whatever serves ochema.app serves ochema.app/docs.

The structure follows public standards: arc42 for the system documentation, the C4 model for structure diagrams, MADR for these decision records and Diátaxis for the user guide.

  • Good, because a change in a screen and the change in its guide page can be one commit.
  • Good, because the documentation needs no service of its own.
  • Bad, because a documentation fix is published only with a build of the landing site.
  • Bad, because there is one version: the site describes the current product, with no archive per release.
  • Bad, because diagrams need JavaScript in the browser to be drawn.
  • apps/docs/astro.config.ts: site, sidebar, search and Mermaid.
  • apps/docs/src/styles/theme.css and apps/docs/test/theme.test.ts: the tokens in the theme, and the test that keeps direct colours out.
  • turbo.json (@ochema/landing#build) and apps/landing/scripts/copy-docs.ts: the publication step.
  • Concept page: Design system.
  • System documentation explains how these pages are organized.