Description
A clone contains Markdown and a docs.toml navigation fragment but not the externally generated Zensical configuration or a supported local preview command. Give contributors and agents a repository-local way to validate navigation, links, and rendered pages.
Acceptance Criteria
- #1 The repository either builds/serves the docs site locally with pinned dependencies or documents and automates the external hub contract without requiring private context
- #2 A documented command validates docs.toml navigation, all relative links, and expected special pages such as 404.md
- #3 The docs validation runs in CI or the authoritative docs-sync workflow
- #4 A fresh clone can preview or validate a documentation change using only public dependencies
Definition of Done
- #1 make gate (build vet test race rw-proto-check spdx-check forbidden-words)
- #2 make blueprint-schema (only if a blueprint field or construct/workload config struct changed)
- #3 DRY_RUN=true go run ./cmd/synthkit -once -dump — inventory diffed against signals/
Implementation Plan
-
Implement a public-dependency repository-local documentation validation/preview path that understands docs.toml.
-
Validate navigation, relative links, and expected special pages, then wire the check into the authoritative CI path.
-
Document fresh-clone usage and verify it from an isolated checkout.
Implementation Notes
Added a Python 3.11+ standard-library docs validator covering docs.toml navigation, authored-page coverage, relative Markdown/HTML links, and docs/404.md. Added make docs-check, wired it before docs dispatch, and documented the external-hub boundary. Focused tests, deliberate broken fixtures, fresh-clone validation, and diff checks passed; external Zensical rendering remains hub-owned.
Integrated CodeRabbit review found malformed-site handling and Python-version enforcement gaps. Added a clear non-table site error, fixture coverage, a local 3.11+ check, and pinned CI Python 3.11. Wave integration make gate and dry-run inventories passed; no blueprint schema regeneration was required.
Final Summary
Landed in e98411b: public-dependency docs validation for navigation, authored-page reachability, links, and 404, enforced locally and before docs sync. Verified with four fixtures, deliberate failure cases, Python 3.9/3.13 checks, fresh-clone simulation, CodeRabbit, make gate, and inventories.