Docs Architecture

Single source pipeline for static docs, grammar artefacts, and SEO/security outputs.

Pipeline (exact)

  1. tools/build_docs_site.py
  2. tools/build_grammar_extras.py
  3. tools/sync_ebnf_memory_pages.py
  4. tools/build_static_extras.py

Sources

  • docs/*.html (EN root editable pages)
  • src/vitte/grammar/vitte.ebnf (source of truth)
  • docs/css/*, docs/js/*

Example

Edit the HTML page directly in docs/ to update the site. The build pipeline then injects canonical metadata, refreshes the SEO metadata, and updates the search index automatically.

Generated outputs

  • docs/search-index*.json
  • docs/sitemap.xml, docs/robots.txt
  • docs/build-manifest.json, docs/status.json
  • docs/grammar/rules*.json, docs/grammar/grammar.sha256

Assets policy

  • Local docs assets (docs/css/*, docs/js/*) must not carry integrity= or crossorigin= attributes.
  • Enforced by tools/docs/check_assets_policy.py and CI docs-quality.
  • Automatic cleanup tool: tools/docs/refresh_assets_policy.py.

Editable vs generated

EditableGenerated
docs/*.html, docs/css/*, docs/js/*, src/vitte/grammar/vitte.ebnf search-index*.json, sitemap.xml, build-manifest.json, checksums.txt, *.sha256

Ownership map

ArtifactUpdater
Header/footer/nav + core search indextools/build_docs_site.py
Grammar toolbox/diff/status/rules APItools/build_grammar_extras.py
EBNF memory pages + checksumtools/sync_ebnf_memory_pages.py
SEO/CSP/checksums/health/static extras + asset policy cleanuptools/build_static_extras.py
Doctor checks and fix suggestionstools/docs_doctor.py
No-SRI policy gate for local assetstools/docs/check_assets_policy.py