Guide Platform · CI-0010

Automated Guide Generation

Build one consistent GitHub Pages site from canonical sources, shared navigation data, templates, and deterministic generator logic.

Open canonical Markdown Open reference

Generation chain

Canonical Markdown→Guide Sources→Templates + Data→Generator→Validation→GitHub Pages

Source of each concern

MeaningGovernance/ canonical Markdown

Page contentguide/*.html source pages

Navigation dataguide/data/navigation.json

Navigation templateguide/templates/navigation.html

Build logicscripts/build_guide.py

Generated site_site/, never canonical

Local build

python scripts/build_guide.py --output _site

The generator copies publishable Guide files, excludes build inputs, renders page-relative shared navigation, validates navigation targets, and emits a build manifest.

Change workflow

1. Change sources

Update canonical Markdown, guide source pages, templates, or structured data according to the type of change.

2. Generate and inspect

Run the generator. Any missing page, invalid data, or malformed navigation block stops the build.

3. Publish and verify

Push or merge source changes to main. GitHub Actions generates _site/, deploys it, and the published result is verified separately.

Maintenance rule: when the same Guide edit is required in multiple pages, extract it into shared data, a template, or generator logic rather than duplicating it manually.