S259 — fix 8 dead TOC anchors that have kept the docs site unpublished since fd77141 - #97
Merged
Merged
Conversation
VitePress prefixes a heading id with `_` when the slug would start with a
digit, so `## 1. Architectural Rule` emits `id="_1-architectural-rule"`. The
Table of Contents at docs/dev/client-windows.md:14-21 linked the un-prefixed
form for all eight numbered sections, so every TOC entry on the page was dead.
The convention is already established in this repo — docs/dev/client-roku.md:8-18
uses `#_1-overview` … `#_11-device-verification-status` for the same heading
style, and .claude/rules/docs-authoring.md documents the rule explicitly
("## 1. Overview -> id=\"_1-overview\""). The windows page simply diverged from
it. Fixed to match, verified against the emitted ids in the built HTML rather
than derived by hand.
Scope is the whole defect class, not just the reported instance: a repo-wide
sweep for markdown links to a digit-leading fragment
(grep -rnE '\]\(#[0-9]' plus the cross-page form) returns exactly these eight
links and nothing else, so no other page needs the same correction. Pages with
numbered headings that already use the `#_N-` form were left alone.
This unblocks publishing. `Build Docs` and `Deploy Docs` have both been failing
on master for three commits (c4619dd, 75f7139, 376fbad), so the site has not
deployed since fd77141 — the anchor breakage starts at 75f7139; c4619dd was an
unrelated Pages deploy timeout.
Verified: npm run docs:build exits 0, anchor gate reports
"157 page(s), 3463 unique #fragment link(s) checked" and "0 dead anchor(s)
found" in a clean tracked-files-only worktree (the corpus CI sees).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Not up to standards ⛔🔴 Issues
|
| Category | Results |
|---|---|
| ErrorProne | 8 medium |
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
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
1 participant
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.
S259 — turn the docs pipeline green again
masterhas been red for three commits and both jobs fail —Build DocsandDeploy Docs. SinceDeploy Docsis the GitHub Pages publishing path, the live site has not updated sincefd77141: the roku rewrite (c4619dd) and both windows commits (75f7139,376fbad) are merged but unpublished.The defect
VitePress prefixes an emitted heading id with
_when the slug would start with a digit. The built HTML hasid="_1-architectural-rule"…id="_8-building-and-releasing"; the TOC atdocs/dev/client-windows.md:14-21linked#1-……#8-…. Eight dead anchors, one missing underscore each.This was a divergence from a convention already written down in this repo —
.claude/rules/docs-authoring.mddocuments## 1. Overview -> id="_1-overview"verbatim, anddocs/dev/client-roku.md:8-18already follows it.Evidence
Both figures from a clean worktree (tracked files only, as CI checks out), exit code read from an unpiped command:
376fbadcontrolff9d29bthis PRThe gate prints its own corpus, so the zero is not a gate that inspected nothing:
It also hard-fails with "The scanner is broken, not the docs" when the candidate set is empty, so a zero-corpus run cannot pass silently.
Two accounting notes
header-anchorlink per heading and the gate keys on(file, href), so each corrected TOC href is now byte-identical to the generated one and dedupes.href="#_1-architectural-rule"occurs 2× in the built page — positive evidence the TOC now targets exactly what VitePress generates.docs/old/holds 2 pages absent from a fresh checkout. Every figure above is from a clean worktree for that reason.Scope
grep -rnE '\]\(#[0-9]'returns exactly these 8 hits repo-wide; the cross-page form returns zero. No other page needed the change and none was touched — pages already using#_N-were left alone.Deliberately shipped alone rather than folded into the MCP-docs branch, so the red→green flip on
Build Docsis attributable.🤖 Generated with Claude Code