docs: replace MkDocs with Zensical - #3073
Code review found 7 potential issues
Found 5 candidates, confirmed 7. See review comments for details.
Details
| Severity | Count |
|---|---|
| 🔴 Important | 0 |
| 🟡 Nit | 7 |
| 🟣 Pre-existing | 0 |
| Severity | File:Line | Issue |
|---|---|---|
| 🟡 Nit | .github/workflows/shared.yml:142-148 |
shared.yml docs-job comment misattributes missing-nav-target detection to zensical --strict |
| 🟡 Nit | scripts/docs/llms_txt.py:50 |
_ASSET_LINK regex silently skips asset extensions longer than 4 characters |
| 🟡 Nit | scripts/docs/llms_txt.py:186-194 |
llms_txt.py mishandles YAML frontmatter: misleading H1 build failure and silently dropped description feature |
Annotations
Check warning on line 148 in .github/workflows/shared.yml
claude / Claude Code Review
shared.yml docs-job comment misattributes missing-nav-target detection to zensical --strict
This rewritten comment credits `zensical build --strict` with failing on missing nav targets, but the PR's own empirical finding (documented in `build_config.py`'s `_missing_nav_pages` docstring) is the opposite: Zensical 0.0.48 ships a nav entry for a nonexistent page as a broken link with no diagnostic even under `--strict` — `build_config.py` is the actual enforcement point. Consider rewording to attribute each failure class to its actual owner, e.g. "scripts/docs/build.sh fails on broken lin
Check warning on line 50 in scripts/docs/llms_txt.py
claude / Claude Code Review
_ASSET_LINK regex silently skips asset extensions longer than 4 characters
The `_ASSET_LINK` regex caps the file extension at `[a-zA-Z0-9]{1,4}`, so a relative link to an asset with a 5+ character extension (`.jsonl`, `.woff2`, `.webmanifest`, ...) matches neither `_ASSET_LINK` nor `_MD_LINK` and is never existence-checked — and per the PR description this validator is the sole guard for non-markdown link targets, so such a broken link would ship as a silent 404. Widening the quantifier (or dropping the cap and relying on the `(?!md...)` lookahead) closes the hole; not
Check warning on line 194 in scripts/docs/llms_txt.py
claude / Claude Code Review
llms_txt.py mishandles YAML frontmatter: misleading H1 build failure and silently dropped description feature
The new `llms_txt.py` reads raw page source and never strips YAML frontmatter, unlike the deleted hook which ran at `on_page_markdown` (post-frontmatter-extraction) — so a prose page with valid `---` frontmatter (a pattern this PR's own generated `api/` stubs use) fails the anchored H1 check with the misleading error "does not start with an H1", and the old hook's `page.meta description` tail in llms.txt index entries is silently dropped without appearing in the PR's inventory of dropped capabil