ci(docs): build the MkDocs site with --strict in CI (refs #173) #189

Merged

not merged 3 commits from ci/173-mkdocs-build into main 2026-09-28 13:25:41 +00:00

Conversation 0 Commits 3 Files Changed 4

+28 -3

not commented 2026-09-28 12:57:29 +00:00

Contributor

Copy Link

Copy Source

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

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)

not added this to the Iteration 6 — Production Posture milestone 2026-09-28 12:57:29 +00:00

not added 2 commits 2026-09-28 12:57:29 +00:00

ci(docs): build the MkDocs site with --strict in CI (refs #173) ... beeecf28ee

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>

fix(docs): drop the link out of docs_dir so the strict build passes (refs #173) ... c9dcbd6174

MkDocs can't resolve links outside docs/, so the stryker-config.json path is
now plain code. The CI runbook lists the new docs job.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

not added the type:chorearea:docs labels 2026-09-28 12:57:31 +00:00

not added 1 commit 2026-09-28 13:03:36 +00:00

Merge branch 'main' into ci/173-mkdocs-build 19ac99b0a0

not merged commit b444e0c680 into main 2026-09-28 13:25:41 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

area:acl

area:bff

area:docs

area:domain

area:event-subscriber

area:infra

area:portal-behandel

area:portal-beheer

area:portal-openbaar

area:portal-self-service

area:projection

area:workflow

type:adr-proposal

type:bug

type:chore

type:slice

No labels area:docs type:chore

Milestone

No items

No Milestone Iteration 6 — Production Posture

Projects

Clear projects

No projects

Assignees

Clear assignees

eho (Edwin van den Houdt)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: eho/register-referentie#189