eho/register-referentie
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

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

New Issue
Open
opened 2026-09-10 09:04:29 +00:00 by not · 0 comments
not commented 2026-09-10 09:04:29 +00:00
Contributor
Copy Link
Copy Source

CLAUDE.md §12 says docs/ is "published via a Gitea Actions workflow to Gitea Pages", and docs/index.md says the site is built with mkdocs build. Neither is true: .gitea/workflows/ holds only ci.yaml, there is no docs make target, and nothing in CI runs mkdocs build — so a broken link, a bad nav entry or a theme error is only ever found by someone running mkdocs serve locally.

#172 added infra/check-docs-nav.py (every page is in the nav), which is the cheap half. The rest needs a decision, not a patch: Gitea has no built-in Pages, so publishing means picking a target — a gitea-pages server, a build artifact per run, or an external static host — and the answer belongs in an ADR or in CLAUDE.md §12 if the claim is simply retired.

Minimum useful step, independent of that decision: a CI job that runs mkdocs build --strict so the site is at least known to build.

CLAUDE.md §12 says `docs/` is "published via a Gitea Actions workflow to Gitea Pages", and `docs/index.md` says the site is built with `mkdocs build`. Neither is true: `.gitea/workflows/` holds only `ci.yaml`, there is no `docs` make target, and nothing in CI runs `mkdocs build` — so a broken link, a bad nav entry or a theme error is only ever found by someone running `mkdocs serve` locally. #172 added `infra/check-docs-nav.py` (every page is in the nav), which is the cheap half. The rest needs a decision, not a patch: **Gitea has no built-in Pages**, so publishing means picking a target — a `gitea-pages` server, a build artifact per run, or an external static host — and the answer belongs in an ADR or in CLAUDE.md §12 if the claim is simply retired. Minimum useful step, independent of that decision: a CI job that runs `mkdocs build --strict` so the site is at least known to build.
not added this to the Iteration 6 — Production Posture milestone 2026-09-10 09:04:29 +00:00
not added the type:chorearea:docs labels 2026-09-10 09:04:29 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
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
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: eho/register-referentie#173