Skip to content

docs: replace MkDocs with Zensical - #3073

Merged
maxisbey merged 30 commits into
mainfrom
claude/replace-mkdocs-zensical-5m0ltl
Jul 10, 2026
Merged

docs: replace MkDocs with Zensical#3073
maxisbey merged 30 commits into
mainfrom
claude/replace-mkdocs-zensical-5m0ltl

docs: fix the sidebar rule cascade and print scheme scoping

7d3d1dd
Select commit
Loading
Failed to load commit list.
Claude / Claude Code Review completed Jul 9, 2026 in 17m 12s

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

See this annotation in the file changed.

@claude 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

See this annotation in the file changed.

@claude 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

See this annotation in the file changed.

@claude 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