DOCS: the program renders as a site with navigation and search

.github/workflows/ci.yml

@@ -48,6 +48,17 @@ jobs:
         run: |
           ! grep -rnIE "\b(TODO|FIXME|HACK|XXX)\b" --exclude-dir=.git --exclude-dir=.github --exclude=.pre-commit-config.yaml .
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: every document is a page and every anchor resolves
+        run: python3 -m unittest discover -s tests
+      - name: the pages generate
+        run: python3 scripts/build_docs.py
+
   links:
     runs-on: ubuntu-latest
     steps:
@@ -63,7 +74,7 @@ jobs:
       # Offline on purpose: the pipeline checks the cross-references
       # inside this repository and fetches nothing.
       - name: check internal links
-        run: git ls-files -z "*.md" "*.html" | xargs -0 "$RUNNER_TEMP/lychee-x86_64-unknown-linux-gnu/lychee" --offline --no-progress --include-fragments
+        run: git ls-files -z "*.md" | xargs -0 "$RUNNER_TEMP/lychee-x86_64-unknown-linux-gnu/lychee" --offline --no-progress --include-fragments
 
   doctrine:
     runs-on: ubuntu-latest
@@ -74,7 +85,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: tltaylor1/build-doctrine
-          ref: 110a64984ad306f4c502b571a6d359afb5cd4c81
+          ref: a235068d87c618bc7d8b70cf83a52c071056df80
           path: doctrine
           persist-credentials: false
       - name: no retired project name in active text

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+# The documentation site, published to GitHub Pages from the same
+# documents the gates check. The pages are generated at build time by
+# scripts/build_docs.py from the root documents, then rendered by the
+# generator installed from the hash-pinned docs tree, in strict mode,
+# so a broken link or anchor fails here before it can reach a reader.
+# Runs when a document it renders changes on main.
+name: docs
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "*.md"
+      - "diagrams/**"
+      - "images/**"
+      - "mkdocs.yml"
+      - "scripts/build_docs.py"
+      - "requirements-docs.txt"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: install the docs tree, hashes enforced
+        run: |
+          python3 -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/pip" install --no-cache-dir --require-hashes -r requirements-docs.txt
+      - name: generate the pages from the documents
+        run: python3 scripts/build_docs.py
+      - name: render the site, strictly
+        run: '"$RUNNER_TEMP/venv/bin/mkdocs" build --strict'
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.gitignore

@@ -0,0 +1,8 @@
+# The documentation site, generated at build time and never committed
+docs/site/
+site/
+
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/

README.md

@@ -59,8 +59,10 @@ It will have:
 secure-expense-mvp is a small application built before the program as
 a learning exercise, kept as a reference.
 
-The rendered site is this repository, served at
-https://tltaylor1.github.io.
+This repository is the program's home. Its documents render as a site
+with side navigation and search at
+<https://tltaylor1.github.io/control-plane/>, generated from these files
+at build time; the account's own page is at <https://tltaylor1.github.io>.
 
 ## The parts
 

mkdocs.yml

@@ -0,0 +1,44 @@
+# The documentation site: generated pages under docs/site, produced by
+# scripts/build_docs.py from the root documents at build time, so the
+# site has no source of its own to drift. Strict mode turns a broken
+# link or anchor into a failed build.
+site_name: control-plane
+site_description: A security engineering program built in public, its rulebook, its application, and its cloud deployment
+site_url: https://tltaylor1.github.io/control-plane/
+repo_url: https://github.com/tltaylor1/control-plane
+repo_name: tltaylor1/control-plane
+docs_dir: docs/site
+site_dir: site
+strict: true
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - navigation.footer
+    - search.highlight
+    - content.code.copy
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - tables
+  - attr_list
+  - pymdownx.superfences
+
+validation:
+  anchors: warn
+  absolute_links: warn
+  unrecognized_links: warn

requirements-docs.in

@@ -0,0 +1,2 @@
+mkdocs
+mkdocs-material