docs(nav): publish every ADR and runbook, gated by a nav check (closes #169) #172

2026-09-10T09:04:10Z

not commented

2026-09-10 09:04:10 +00:00

What & why

docs/ is the source of truth (CLAUDE.md §12), but only pages listed in mkdocs.yml's nav
are published — and mkdocs' own validation.nav.omitted_files: warn keeps the build green
while dropping the rest. So the site had quietly stopped at ADR-0010 and
runbooks/ci.md: 31 pages, including every ADR from 0011 to 0034, six of the seven
runbooks, and synthetic-data.md, existed in the repo and nowhere else.

infra/check-docs-nav.py fails when a page under docs/ is not in the nav. It runs in
make lint, so the existing CI job gates it — python3 only, no new tooling, and no
mkdocs install needed to check it.
The nav now lists all 34 ADRs, all 7 runbooks and synthetic-data.md.
ADR-0033's Slice: header said "none yet"; #25 closed it.
The landing page gained a pointer to the Talos runbook.

Closes #169

Definition of Done

Linked Gitea issue (above).
Failing test committed before the fix — the red commit lists all 31 missing pages.
Implementation makes the test pass.
Conventional Commits referencing the issue (refs #169).
CI green — awaiting the run on this PR (python3 infra/check-docs-nav.py passes locally;
make lint also needs the .NET SDK, which CI has).
docker compose up unaffected — docs and mkdocs.yml only, plus one make lint line.
Docs updated — that is the change.
No ADR needed: no dependency, no boundary, no §8 rule touched.
Not user-visible, so no demo note.

Notes for reviewers

The check is a substring test, not a YAML parse (there's a ponytail: note in the
script): a page's path either appears in mkdocs.yml or it doesn't. That keeps it
dependency-free — mkdocs.yml can't be read by yaml.safe_load anyway, it carries a
!!python/name: tag for the mermaid fence. It does not check that an entry points at a
file that exists; mkdocs' not_found: warn covers that direction.
ADR labels in the nav are shortened by hand ("ADR-0013: Behandel-portal wiring"), since
several H1s are a full sentence.

Known gap, not fixed here: CLAUDE.md §12 says the site is "published via a Gitea Actions
workflow to Gitea Pages", and no such workflow exists — mkdocs build is never run, by CI or
by any make target. Gitea has no built-in Pages, so publishing needs a decision (a
gitea-pages server, an artifact, or a static host) rather than a patch. Worth its own issue
if the published site is actually wanted; until then this PR makes the nav correct for whoever
runs mkdocs serve.

## What & why `docs/` is the source of truth (CLAUDE.md §12), but only pages listed in `mkdocs.yml`'s nav are published — and mkdocs' own `validation.nav.omitted_files: warn` keeps the build green while dropping the rest. So the site had quietly stopped at **ADR-0010** and **`runbooks/ci.md`**: 31 pages, including every ADR from 0011 to 0034, six of the seven runbooks, and `synthetic-data.md`, existed in the repo and nowhere else. - `infra/check-docs-nav.py` fails when a page under `docs/` is not in the nav. It runs in `make lint`, so the existing CI job gates it — python3 only, no new tooling, and no mkdocs install needed to check it. - The nav now lists all 34 ADRs, all 7 runbooks and `synthetic-data.md`. - ADR-0033's `Slice:` header said "none yet"; #25 closed it. - The landing page gained a pointer to the Talos runbook. Closes #169 ## Definition of Done - [x] Linked Gitea issue (above). - [x] Failing test committed before the fix — the red commit lists all 31 missing pages. - [x] Implementation makes the test pass. - [x] Conventional Commits referencing the issue (`refs #169`). - [x] CI green — awaiting the run on this PR (`python3 infra/check-docs-nav.py` passes locally; `make lint` also needs the .NET SDK, which CI has). - [x] `docker compose up` unaffected — docs and `mkdocs.yml` only, plus one `make lint` line. - [x] Docs updated — that is the change. - [x] No ADR needed: no dependency, no boundary, no §8 rule touched. - [x] Not user-visible, so no demo note. ## Notes for reviewers - The check is a **substring test**, not a YAML parse (there's a `ponytail:` note in the script): a page's path either appears in `mkdocs.yml` or it doesn't. That keeps it dependency-free — `mkdocs.yml` can't be read by `yaml.safe_load` anyway, it carries a `!!python/name:` tag for the mermaid fence. It does not check that an entry *points at a file that exists*; mkdocs' `not_found: warn` covers that direction. - ADR labels in the nav are shortened by hand (`"ADR-0013: Behandel-portal wiring"`), since several H1s are a full sentence. **Known gap, not fixed here:** CLAUDE.md §12 says the site is "published via a Gitea Actions workflow to Gitea Pages", and no such workflow exists — `mkdocs build` is never run, by CI or by any make target. Gitea has no built-in Pages, so publishing needs a decision (a `gitea-pages` server, an artifact, or a static host) rather than a patch. Worth its own issue if the published site is actually wanted; until then this PR makes the nav correct for whoever runs `mkdocs serve`.

not added this to the Iteration 6 — Production Posture milestone 2026-09-10 09:04:10 +00:00

not added the type:chore area:docs labels 2026-09-10 09:04:10 +00:00

not added 3 commits 2026-09-10 09:04:11 +00:00

test(docs): fail when a page under docs/ is missing from the nav (refs #169 ) 8df3faf979

Only the pages listed in mkdocs.yml's nav are published, and mkdocs' own
`omitted_files: warn` keeps the build green while dropping the rest — so nothing
ever said that the site had quietly stopped at ADR-0010 and runbooks/ci.md.

Runs in `make lint` (python3 only, no new tooling), so it gates every PR through
the existing job.

Red: 31 pages are missing — ADR-0011 through ADR-0034, six of the seven runbooks,
and synthetic-data.md.

docs(nav): publish every ADR and runbook, not just the first ten (refs #169 ) 16509a399c

ADR-0011 through ADR-0034, six of the seven runbooks (OpenZaak, Open Notificaties,
Keycloak, Flowable, Kubernetes-on-Talos, Gitea Actions gotchas) and synthetic-data.md
are now in mkdocs.yml's nav, which makes `make lint` green again.

Also fills in ADR-0033's `Slice:` header, which said "none yet" — #25 closed it.

docs(nav): point the landing page at the Kubernetes runbook (refs #169 )

CI / build (pull_request) Successful in 4m45s

Details

CI / lint (pull_request) Successful in 5m4s

Details

CI / unit (pull_request) Successful in 1m0s

Details

CI / frontend (pull_request) Successful in 1m56s

Details

CI / mutation (pull_request) Successful in 3m10s

Details

CI / verify-stack (pull_request) Successful in 6m8s

Details

ab4392320a

not referenced this pull request

2026-09-10 09:04:29 +00:00

docs are never built or published — no mkdocs workflow exists #173

not merged commit 17f1f2f809 into main

2026-09-18 12:55:21 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: eho/register-referentie#172