## 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`). - [ ] 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`.Reviewed-on: #172
This commit was merged in pull request #172.
This commit is contained in:
@@ -64,6 +64,9 @@ frontend:
|
||||
## lint: verify formatting (no changes)
|
||||
lint:
|
||||
dotnet format $(SLN) --verify-no-changes
|
||||
# Only pages in mkdocs.yml's nav are published, and mkdocs keeps a build green
|
||||
# when one is missing — so the nav is checked here rather than not at all.
|
||||
python3 infra/check-docs-nav.py
|
||||
|
||||
## build: release build
|
||||
build:
|
||||
|
||||
Reference in New Issue
Block a user