From beeecf28eeb60bed2e986e8f63df6fc386f2a454 Mon Sep 17 00:00:00 2001
From: Niek Otten <not@respellion.nl>
Date: Mon, 28 Sep 2026 14:56:52 +0200
Subject: [PATCH] ci(docs): build the MkDocs site with --strict in CI (refs
 #173)

Red: the strict build currently fails on a link out of docs_dir in
runbooks/ci.md.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .gitea/workflows/ci.yaml | 11 +++++++++++
 .gitignore               |  4 ++++
 Makefile                 | 13 +++++++++++--
 3 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml
index f3a91fc..d8e13f8 100644
--- a/.gitea/workflows/ci.yaml
+++ b/.gitea/workflows/ci.yaml
@@ -98,6 +98,17 @@ jobs:
           [ -n "${GITHUB_STEP_SUMMARY:-}" ] || exit 0
           python3 infra/trx-summary.py TestResults >> "$GITHUB_STEP_SUMMARY"
 
+  # The docs site must build with --strict (#173). setup-python so `make docs` can
+  # create its venv regardless of what the runner image ships.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+      - uses: https://github.com/actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: make docs
+
   # Frontend (Nx/Angular) lane: install with pnpm, then Nx lint + test + build.
   frontend:
     runs-on: ubuntu-latest
diff --git a/.gitignore b/.gitignore
index b8d2203..cc50a76 100644
--- a/.gitignore
+++ b/.gitignore
@@ -61,3 +61,7 @@ __pycache__/
 TestResults/
 test-output/
 tests/e2e/playwright-report.json
+
+# MkDocs build (`make docs`)
+.venv-docs/
+site/
diff --git a/Makefile b/Makefile
index 9c76f3b..c6d3828 100644
--- a/Makefile
+++ b/Makefile
@@ -43,11 +43,11 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif
 
-.PHONY: ci lint build unit mutation frontend integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-observability verify-tracing verify-metrics verify-objecttypen verify-objecten verify-registerrecord verify-objecten-notifications verify-notifications smoke up down local verify-local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down k8s-lint k8s-drift k8s-registry k8s-images k8s-seed k8s-up k8s-reseed k8s-portals k8s-down k8s-purge help
+.PHONY: ci lint build unit mutation frontend docs integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-observability verify-tracing verify-metrics verify-objecttypen verify-objecten verify-registerrecord verify-objecten-notifications verify-notifications smoke up down local verify-local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down k8s-lint k8s-drift k8s-registry k8s-images k8s-seed k8s-up k8s-reseed k8s-portals k8s-down k8s-purge help
 
 ## ci: run the full pipeline — lint, build, unit, mutation, frontend, verify (mirrors Gitea Actions)
 ## `verify` is the live-stack stage (full stack up once → ACL + notification checks).
-ci: lint build unit mutation frontend verify
+ci: lint build unit mutation frontend docs verify
 
 ## frontend: install deps and run the Nx lint/test/build for the portals (pnpm + Node required)
 # Tests run in their own phase, ahead of the build. The @angular/build:unit-test
@@ -81,6 +81,15 @@ unit:
 	python3 infra/test_playwright_summary.py
 	python3 infra/test_portal_caddyfiles.py
 
+## docs: build the MkDocs site with --strict (a broken link or nav entry fails)
+# Pinned in a throwaway venv: Material 9.7 is the last line on MkDocs 1.x, and MkDocs
+# 2.0 drops the plugin/theme system this site relies on. Publishing is a separate
+# decision (#173); this only proves the site builds.
+docs:
+	python3 -m venv .venv-docs
+	.venv-docs/bin/pip install --quiet mkdocs==1.6.1 mkdocs-material==9.7.7
+	.venv-docs/bin/mkdocs build --strict
+
 ## mutation: run the Stryker.NET ratchet on each service with branching logic (fails below baseline)
 # Stryker is pinned as a local dotnet tool (.config/dotnet-tools.json); `tool restore`
 # makes `make mutation` work from a fresh clone. Each service owns its config + break