fix(docs): fix 72 broken links/anchors against the assembled site tree - #2121
Merged
Conversation
#2118) A local `mkdocs build` against the assembled `_mkdocs_src` tree (what `mkdocs build`/`gh-deploy` actually publishes) found 72 broken relative links and drifted anchors, unrelated to #2113's own fix. Every one of the 63 broken-link targets was verified to still exist in the real repo — none were genuinely deleted or renamed, contrary to #2118's filing-time guess — so the root cause is the same as #2113/#2103: assemble-docs.sh only copies each plugin's own docs/ and README/CHANGELOG, never skills/agents/commands/knowledge/hooks/scripts, tests/, evals/, reports/, .claude/, .github/, or repo-root CLAUDE.md. Converted every one to a GitHub source link, same pattern as #2113. The remaining 9 were anchor drift: a hand-written TOC/cross-reference anchor used a double hyphen where the heading's "&"/"—" collapses to a single hyphen once MkDocs slugifies it — corrected each to the actual generated heading id. mkdocs.yml's `validation.links.not_found`/`anchors` stay `warn`: this MkDocs version's schema only accepts warn/info/ignore for those two options (no `error`), confirmed against the installed `mkdocs.config.defaults._LogLevel` validator. Comment updated to explain why, so the next reader doesn't try `error` again. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01URnco7Z5bKfKBMdNiZGQL4
Closed
3 tasks
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mkdocs buildagainst the assembled_mkdocs_srctree (whatmkdocs build/gh-deployactually publishes) found 72 broken relative links and drifted anchors, unrelated to docs: hand-written docs pages have ~134 more cross-tree links that 404 on the published site #2113's own fix.scripts/assemble-docs.shonly copies each plugin's owndocs/+ README/CHANGELOG, neverskills/agents/commands/knowledge/hooks/scripts,tests/,evals/,reports/,.claude/,.github/, or repo-rootCLAUDE.md. Converted every one to a GitHub source link, same pattern as docs: hand-written docs pages have ~134 more cross-tree links that 404 on the published site #2113.&/—collapses to a single hyphen once MkDocs slugifies it. Corrected each to the actual generated heading id (verified against the built HTML).mkdocs.yml'svalidation.links.not_found/anchorsstaywarnwith an updated comment: this installed MkDocs version's schema only accepts warn/info/ignore for those two options (noerror— confirmed againstmkdocs.config.defaults._LogLevel).Not included in this PR — blocked on permissions
A second, prepared commit hardens
.github/workflows/link-check.yml'snav-integrityjob to runmkdocs build --strict(verified locally: passes clean, and fails with exit 1 on a deliberately reintroduced broken link) now that this PR clears the broken-link backlog. It cannot be pushed from this session —git pushand the GitHub API both reject writes to.github/workflows/*.ymlwithout the OAuthworkflowscope, which this session's credentials don't have. Tracked in #2118 and #2120; will land in a follow-up once that scope is available or a maintainer applies it.Test Plan
bash scripts/assemble-docs.sh && mkdocs build --site-dir /tmp/site— 0 "not found"/anchor warnings (was 72)python3 scripts/check_nav_integrity.py— passespython3 -m pytest tests/repo/test_required_status_checks.py -q— passesbash scripts/ci-local.sh— full local CI gate passesCloses #2118
🤖 Generated with Claude Code
https://claude.ai/code/session_01URnco7Z5bKfKBMdNiZGQL4
Generated by Claude Code