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.

Refresh and cache policy

• Development auto-refresh is built into docs/js/main.js.
• Enable it by opening any page with ?dev-refresh=1&refresh=5 to reload every 5 seconds.
• While dev auto-refresh is enabled, the docs service worker is unregistered to avoid stale local cache during editing.
• Production cache headers for static hosting live in docs/_headers: HTML, CSS, JS, search indexes, and SVGs are all forced to revalidate so the site does not stay pinned to stale browser cache.
• docs/_headers is honored by hosts such as Netlify, Cloudflare Pages, and many custom static servers; GitHub Pages may ignore it, so query-versioned assets still matter there.

Editable vs generated

Ownership map