Building and publishing the documentation

docs/antora/ is the published Antora component. Its modules/ROOT/pages/ directory holds the AsciiDoc pages, nav.adoc defines navigation, and antora.yml defines one unversioned component. The playbook reads the current checkout, including local edits.

The architecture and ADR pages are the canonical sources. The former locations under docs/architecture point here. Evidence reports and protocol specifications remain in the repository and are linked from the site; they are not copied into the search index. Private planning files, device backups and local configuration are outside the published component.

Mermaid sources live in modules/ROOT/attachments/diagrams/; their checked-in SVG renders live in modules/ROOT/images/. Keep both together when changing a diagram. Mermaid CLI can regenerate an image with mmdc -i diagram.mmd -o diagram.svg -b white. Publishing uses the SVGs, so diagrams do not require a browser-side Mermaid renderer. Each diagram links to its source.

From the repository root, using the repository’s Node and pnpm versions:

Open http://localhost:8080. The generated site and cache are ignored by Git. The build fails on warnings, including unresolved Antora cross-references. Check navigation, diagrams, narrow-screen layout, and search after changing them. For example, searching autosave or ADR-008 should return relevant page sections. No application services, database, Android build or device installation is needed.

The official @antora/lunr-extension indexes page text and headings during the build. The default Antora UI loads that index and performs searches in the browser. Dependencies are pinned in the root package manifest and pnpm lockfile. The default UI bundle is vendored under ui/default.zip; see ui/README.adoc for its source, license and checksum. Supplemental UI files replace the sample product menus, label the search input and apply SpareThought’s colors.

.github/workflows/deploy-docs.yaml handles pushes that change docs/antora/** or that workflow itself. Eligible non-release pushes publish automatically; release delivery and tag pushes do not publish this site. Application-only changes do not deploy the docs. Existing app and release workflows retain their own independent triggers.

All eligible deployments publish to the same docs.sparethought.dev site. The latest successful deployment wins. Publication is serialized; GitHub may replace an older pending run with a newer pending run while another is running. The workflow configuration defines the exact publication filters and Cloudflare destination.

The workflow installs locked dependencies, builds Antora, and directly uploads the static files to the sparethought-docs Pages project. Wrangler runs in the Antora directory so the web application’s configuration is not discovered. It uses the existing repository secrets CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN; the token needs Pages write access for the account. The custom domain is attached to that project with a proxied CNAME to sparethought-docs.pages.dev. There are no Pages Functions, database bindings or application credentials in this site.

When changing Antora dependencies in the root manifest/lockfile, also update this component (for example its build documentation) to trigger publication. Unrelated lockfile changes deliberately do not deploy documentation. Standard GitHub skip-CI directives also skip this push workflow.