Skip to content

Reference

Most of this section is generated when the site is built: the API reference, the database schema pages, the install configuration table and the architecture decision records. A few pages are written by hand:

  • 3D preview pipeline: how posters, turntables, sprite sheets and reference views are rendered for 3D assets.
  • Sprite-tool batch API: how to drive the sprite tool’s frame layout, tags and variants over the HTTP API from a script or batch job. Exports stay in the browser.

When a generated page is wrong, fix it where the problem starts. For OSS-backed reference pages, that means the OpenAPI spec, database migrations, configuration template or ADR in the main repository. The Roadmap comes from this site’s curated src/content/roadmap/roadmap.json; a scheduled drift check compares it with the GitHub release and milestone evidence recorded in the site’s data. Layout or parsing problems belong in this site’s generator scripts.

Source links point to the main repository’s dev branch. A build uses whichever commit it checked out.

PageGenerated from
API referenceapp/api/openapi.yaml: copied into the site by sync-openapi.mjs and rendered by starlight-openapi. The Go server’s API types are generated from the same file by oapi-codegen in the main repository; the site doesn’t run it.
Database schemaapp/schema.sql, a schema-only dump of a database built from the migrations: parsed by generate-schema-docs.mjs
Install config table on Installingdocs/install/config/aa.env.example: parsed by sync-install-config.mjs. Only uncommented variables become rows; commented-out optional settings aren’t listed.
Roadmapsrc/content/roadmap/roadmap.json in this site’s repository, curated by hand: sync-roadmap.mjs writes the page that renders it. A scheduled check compares it with the GitHub releases and milestones recorded in the site’s data.
Architecture Decisions (sidebar)docs/adr/*.md: validated and copied by sync-adrs.mjs

pnpm build and pnpm dev run the generation steps first, through the prebuild and predev scripts in package.json, so the generated pages reflect the main repository as it was checked out at that moment. Running astro build or astro dev directly skips them. The steps run in this order:

  1. scripts/sync-adrs.mjs parses and validates each ADR’s YAML frontmatter (docs/adr/*.md), checks cross-references between ADRs, and writes the ADR pages plus the data the catalogue uses.
  2. scripts/sync-openapi.mjs copies app/api/openapi.yaml to public/openapi.yaml, where starlight-openapi reads it, pointing the spec’s relative links at the matching source files on the way. The copy is also published at /openapi.yaml.
  3. scripts/generate-schema-docs.mjs parses app/schema.sql and writes the developers/database/ pages (an overview, one page per table and the schema visualizer) and the schema.json the visualizer reads.
  4. scripts/sync-install-config.mjs parses docs/install/config/aa.env.example into a Starlight partial that the install guide imports.
  5. scripts/sync-roadmap.mjs writes the Roadmap page, which renders the curated src/content/roadmap/roadmap.json from this repository. It is the one step that reads nothing from the main repository.
  6. scripts/sync-screenshots.mjs copies the product screenshots the landing page uses from docs/screenshots/ into src/assets/screenshots/ so Astro can optimise them.

Adding another generation step means adding it to both the prebuild and predev chains.