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.
Sources
Section titled “Sources”Source links point to the main repository’s dev branch. A build uses
whichever commit it checked out.
| Page | Generated from |
|---|---|
| API reference | app/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 schema | app/schema.sql, a schema-only dump of a database built from the migrations: parsed by generate-schema-docs.mjs |
| Install config table on Installing | docs/install/config/aa.env.example: parsed by sync-install-config.mjs. Only uncommented variables become rows; commented-out optional settings aren’t listed. |
| Roadmap | src/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 |
Regenerating
Section titled “Regenerating”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:
scripts/sync-adrs.mjsparses 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.scripts/sync-openapi.mjscopiesapp/api/openapi.yamltopublic/openapi.yaml, wherestarlight-openapireads it, pointing the spec’s relative links at the matching source files on the way. The copy is also published at/openapi.yaml.scripts/generate-schema-docs.mjsparsesapp/schema.sqland writes thedevelopers/database/pages (an overview, one page per table and the schema visualizer) and theschema.jsonthe visualizer reads.scripts/sync-install-config.mjsparsesdocs/install/config/aa.env.exampleinto a Starlight partial that the install guide imports.scripts/sync-roadmap.mjswrites the Roadmap page, which renders the curatedsrc/content/roadmap/roadmap.jsonfrom this repository. It is the one step that reads nothing from the main repository.scripts/sync-screenshots.mjscopies the product screenshots the landing page uses fromdocs/screenshots/intosrc/assets/screenshots/so Astro can optimise them.
Adding another generation step means adding it to both the prebuild
and predev chains.