Skip to content

Publishing the Docs Site

Purpose

Document how the documentation site is built, validated, and published.

This page is operational, not contractual. The source of truth for behavior remains the current repository code and CI workflow.

Scope

This page covers docs-site build and publishing mechanics. Public behavior contracts live in the reference/ and concepts/ pages and in the repository code (the legacy book/ tree has been removed). For integration distribution (storefront sync), see Releasing & storefront sync.

Current stack

  • Site generator: Zensical
  • Theme: Zensical built-in theme (Material-derived)
  • Docs root: docs/
  • Site config: zensical.toml
  • Publish workflow: .github/workflows/docs.yml

What gets published

The published site contains:

  • the public documentation tree (concepts, guides, integrations, reference, and troubleshooting pages)
  • a live sample report for the current repository build under Examples / Sample Report

Repository/agent-facing content lives in a separate, unpublished internal tree and is not part of the built site.

Build flow

The docs workflow (.github/workflows/docs.yml) follows this order:

  1. install project dependencies
  2. build the site with uv run --with zensical==0.0.46 zensical build --clean --strict
  3. generate a live sample report into site/examples/report/live
  4. upload the built site as a GitHub Pages artifact
  5. deploy on pushes to main

Admonition indentation (!!! / ??? body must be indented 4 spaces) is enforced in the main test workflow via tests/test_docs_build_contract.py, not in docs.yml. Repair locally with python3 scripts/lint_admonitions.py docs/ --fix.

Relevant files:

  • zensical.toml
  • .github/workflows/docs.yml
  • scripts/build_docs_example_report.py

Generated output only

site/ is a generated artifact. It is used for local preview and GitHub Pages deployment, but it should not be committed.

Sample report generation

The sample report is generated from the current codeclone repository tree.

Generated artifacts:

  • site/examples/report/live/index.html
  • site/examples/report/live/report.json
  • site/examples/report/live/report.sarif
  • site/examples/report/live/manifest.json

The sample report is generated during docs publishing and is not committed to git. site/ remains ignored.

Local preview

Run the same local preview sequence as the publishing workflow:

Build docs and generate the live sample report
uv run --with zensical==0.0.46 zensical build --clean --strict
uv run python scripts/build_docs_example_report.py --output-dir site/examples/report/live

For docs-only validation, run the first command alone.

Then open:

  • site/index.html
  • site/examples/report/live/index.html

Maintenance rules

  • Keep docs/ as the single source tree for site content.
  • Do not commit generated site/ artifacts.
  • Keep docs publishing deterministic: no timestamps in published docs paths.
  • Keep the sample report generated from the same commit as the site itself.
  • Prefer documenting docs-site mechanics here, not inside contract chapters unless a public contract is affected.

When to update this page

Update this page when you change:

  • zensical.toml
  • .github/workflows/docs.yml
  • scripts/build_docs_example_report.py
  • the site navigation model
  • the sample report publishing path/layout