ci(docs): build the MkDocs site with --strict in CI (refs #173) (#189)
CI / k8s (push) Successful in 10s
CI / build (push) Successful in 1m22s
CI / lint (push) Successful in 2m5s
CI / docs (push) Successful in 1m1s
CI / unit (push) Successful in 1m29s
CI / frontend (push) Successful in 2m31s
Deploy to Talos / deploy (push) Successful in 2m36s
CI / mutation (push) Successful in 5m9s
CI / verify-stack (push) Canceled after 8m47s

refs #173. This is the minimum step from the issue: the site is now **built** in CI, not **published**. Publishing still needs an ADR (Gitea has no built-in Pages) or a CLAUDE.md §12 correction, so the issue stays open.

- `make docs`: creates a throwaway `.venv-docs`, installs pinned `mkdocs==1.6.1` and `mkdocs-material==9.7.7`, then runs `mkdocs build --strict`. The target is also added to `make ci`.
- New `docs` job in `ci.yaml` (`setup-python@v5`, then `make docs`).
- Red, then green: the first commit fails on a link from `runbooks/ci.md` to a file outside `docs/`; the second turns that link into plain code.

**Dependency (§13):** mkdocs and mkdocs-material were already the site's declared toolchain (`mkdocs.yml`) but were never installed anywhere. They give a strict link/nav/theme check. Replacing them means writing our own Markdown link checker, and `check-docs-nav.py` already covers only the nav half. Risk: Material warns that MkDocs 2.0 drops its plugin/theme system, so both are pinned exactly. No ADR, since this adds no new decision beyond what `mkdocs.yml` already assumes.

Verified locally: `make docs` → `Documentation built in 0.87 seconds`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #189
This commit was merged in pull request #189.
This commit is contained in:
not
2026-09-28 13:25:40 +00:00
parent 733ba71173
commit b444e0c680
4 changed files with 28 additions and 3 deletions
+2 -1
View File
@@ -19,6 +19,7 @@ and CI cannot drift:
| `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
| `unit` | `make unit` → `dotnet test … -c Release --filter "Category!=Integration"` | .NET 10 SDK |
| `frontend` | `make frontend` → Nx lint/test/build for the four portals | pnpm + Node |
| `docs` | `make docs` → `mkdocs build --strict` in a pinned venv (fails on a broken link or nav entry; the site is not published yet, #173) | Python 3 |
| `k8s` | `make k8s-lint` (render + schema-check the Helm chart) → `make k8s-drift` (chart still describes the same stack as `infra/docker-compose.yml`) | pinned `helm` binary + `docker compose` |
| `mutation` | `make mutation` → `dotnet tool restore` → `dotnet stryker` (ACL); uploads the HTML report as an artifact | .NET 10 SDK |
| `verify-stack` | **push to `main` only, skipped on PRs** (#182) — the single live-stack stage — steps: `make verify-up` (full stack up + health, the DoD smoke) → `make verify-acl` (ACL ↔ OpenZaak) → `make verify-nrc` (OpenZaak → NRC delivery) → `make down` | container engine + egress (base images, nuget, `selectielijst.openzaak.nl`) |
@@ -57,7 +58,7 @@ dotnet tool (`.config/dotnet-tools.json`), so it runs identically locally and in
make mutation # dotnet tool restore + dotnet stryker on the ACL
```
Config lives in [`services/acl/stryker-config.json`](../../services/acl/stryker-config.json).
Config lives in `services/acl/stryker-config.json`.
It runs in **solution mode** against `Acl.slnx`, mutating the two projects under test
(`Acl.Application`, `Acl.Infrastructure`); `Acl.Api` has no tests and is skipped.
`Acl.slnx` leaves out `Acl.IntegrationTests`: it needs a live OpenZaak, and Stryker