Admin and engineering

How this site is built, and the rules it keeps.

The chain

python3 admin/build/gen_map.py           # admin/content/map.json from v1/content/ and the authored reading
python3 admin/build/gen_contributors.py  # admin/content/contributors.json from admin/content/github/
python3 admin/build/build.py       # every page, the manifest, the frozen markdown, llms.txt, the sitemap
node admin/build/validate.js       # the gate: version, links, canonical, key leak, manifest, sitemap, map

The rules

• v1/ is frozen. v1/content/ is the 2018 book as released; build.py stops if the frozen text changes without a new entry in admin/content/book/versions.json, and validate.js stops if a page no longer matches its markdown.
• Markdown is the source of truth. Every chapter page, brief and role page is a projection of a markdown file; v1/book/manifest.json records the hashes.
• Every release is narrated in the release history, and the version in admin/build/version.txt must match the commit subject site vX.Y.Z: ....
• No private key in the tree. The gate refuses any string with sgit's private-key prefix. The public read key on the vault page is public by design.
• The repository holds the official versions; the vault holds the working versions.

Where things are

• v1/content/, v1/images/: the 2018 book. v1/book/: its pages. v1/versions/: the frozen markdown and the versions page.
• admin/content/: the authored data (map, briefs, versions, vault). admin/build/: the generators, page_versions.py from the newsroom, validate.js.
• team/: the roles, their issues, briefs and debriefs. vault/: how to open the working vault.
• .github/workflows/deploy-pages.yml: validate, tag, deploy to GitHub Pages, the same pipeline as the sibling sites.

Release history · the repository