fix(docs): upstream the harness docs-site fixes — nested anchors, dead graph links, baseUrl, ADR casing

[joestump]

Upstreams four fixes that stump.wtf/harness made in its vendored copy of sdd-content and never sent back, so every other consumer still carries them. Reconciles the template against harness's copy end to end — what is left diverging is harness's own homepage hero (branding, not a fix) and #222's spec-keying changes going the other way.

Stacked on #222 — its spec-references.test.js is the suite these tests extend. GitHub retargets this to main when #222 merges.

1. Nested anchors (the reported bug)

transformSpecReferences / transformAdrReferences rewrote every ADR-NNNN / SPEC-NNNN match on a line, including matches already inside inline code, a markdown link, or an anchor from an earlier pass. [ADR-0006](adr-0006-thing.md) had its label wrapped a second time:

<a href="/specs/gamma/spec#adr-0001"><a href="/decisions/ADR-0001-example">ADR-0001</a></a>

Invalid HTML; some minifiers reject it rather than repair it. Ports protectedRanges() / matchOffset() / isProtected() into all three copies. The guard is span-scoped, so a bare mention elsewhere on a protected line still resolves.

One deliberate change from harness: whole <a>…</a> elements are ranged as well as bare tags. <[^>]+> alone protects an ID sitting in an href but not one sitting in the link text — and the link text is the half that actually nests. Worth pulling back into harness.

2. Dead ADR-0023 / SPEC-0018 links

Those are the plugin's own artifacts. Three call sites linked them unconditionally, so any consumer repo without them got dead links on every ADR page, every index page, and the graph page. onBrokenLinks defaults to warn, so builds stayed green.

citeGraphArtifacts() links them when present and names them as plain text otherwise. Both lookups go by content — the ADR's filename slug, the spec's directory — rather than by number, so a repo that renumbered them still gets links.

Not applied to templates/integration/sync-spec-docs: that copy already emits plain text, and its pages are written under a pathPrefix these site-absolute links would not respect, so adding it there would introduce the dead links.

3. baseUrl never resolved — 944 broken links in this repo

Both readers looked for a baseUrl: '...' literal in docusaurus.config.ts and fell back to ''. Neither ever matched: this repo's config and templates/docusaurus's both assign baseUrl: BASE_URL from a const. Every cross-reference chip was emitted at the host root.

Measured on main before the fix, then after:

$ grep -rho 'href="[^"]*" className="rfc-ref"' docs-generated/ | grep -c '^.*"/claude-plugin-sdd'
before: 0 of 944
after:  944 of 944

Nothing caught it. The dev server and npm run serve both mount at baseUrl, so it looks right locally, and onBrokenLinks does not inspect raw href attributes, so CI stayed green. Markdown links masked it further — Docusaurus resolves those against baseUrl itself; the raw <a href> chips these transforms emit are not resolved and need the prefix baked in.

Two fixes, because the readers have different information:

• The plugin reads context.siteConfig.baseUrl / .title. Docusaurus hands every plugin the fully-evaluated config; scraping the file was never the supported path. (Harness's fix.)
• The docs-site/scripts run outside Docusaurus and have no siteConfig, so they keep parsing the file — through a shared readBaseUrl() that follows a const to its declaration.

templates/integration/sync-spec-docs already read context.siteConfig.baseUrl.

4. Lowercase ADR filenames, and the crash they were hiding

Repos name ADRs either ADR-0001-thing.md or adr-0001-thing.md. Every filename regex was case-sensitive, so a lowercase-naming repo silently lost all ADR graph nodes (hence all edges, every mini-DAG, and the graph page entirely), the badge header on every ADR page, and every ADR link mapping.

That third failure masked a fourth: the badge header renders decision-makers, which the MADR template writes as a list and YAML hands back as an array — escapeJsxAttr called .replace on it. Fixing the casing alone converts a silent omission into str.replace is not a function at build time, so toDisplayString() lands with it. Arrays join; Dates render as YYYY-MM-DD rather than gaining a midnight-UTC time the author never wrote.

Beyond harness: status.toUpperCase() gets the same coercion, since it crashes on a non-string status one call before escapeJsxAttr would.

Verification

• make test lint scan green. Docs site builds; the only broken links reported are two pre-existing /skills/index ones, unchanged by this branch.
• Test count 22 → 51.
• Each fix was confirmed to fail without it: 9 tests fail without the anchor guard, 5 without the filename/frontmatter fix, and readBaseUrl's const case fails against the old regex.
• New suites: base-url.test.js, adr-filenames.test.js. Both exercise every copy that has the defect, as spec-references.test.js already does.

[github-actions]

Skill Eval Results

Mode: quick | No eval results found.

ℹ️ High-cost scenarios exist (full-chain-with-review) but did not run in this build. They run only on release PRs or manual pipeline dispatch.

[joestump]

Code review — /code-review --fix

Reviewed all four commits, rebased onto main (this branch was stacked on #222 and needed #223's changes underneath), resolved a fixture collision with #223, and pushed one fix. make test-unit is at 63 passing locally, npm run build-content clean.

Finding: citeGraphArtifacts hardcodes the nested spec route

docs-site/scripts/graph-data.js:325, templates/docusaurus/plugins/sdd-content/index.js:350

const specRef = spec ? `[${spec.id}](/specs/${spec.dir}/spec)` : 'SPEC-0018';

#223 (merged since this branch was cut) made /specs/<dir>/spec conditional — a domain holding only spec.md renders flat at /specs/<dir>, and every other consumer now reads getSpecLayout instead of assuming. This one still assumes, so in a project whose artifact-graph domain carries no design.md, the citation emits a route nothing writes.

That lands on every ADR page (mini-DAG), both index pages (hierarchy section) and the graph page — and it is the exact failure mode this commit exists to remove: onBrokenLinks is warn by default and these are markdown links, so the build stays green and nobody notices. Routed through getSpecLayout in both copies (spec.path is <specsSource>/<dir>/spec.md, so its grandparent is the specs root), with a regression test covering nested and flat.

Rebase resolution worth knowing about

#223 and this branch both added a delta fixture domain to spec-references.test.js, for different purposes — #223's is deliberately design-less (to pin the flat route), this one's needs to be nested (its assertions read /specs/delta/spec.mdx). Merging them into one domain would have quietly destroyed one of the two tests. Kept #223's delta as-is and moved this PR's linkifier fixture to epsilon / SPEC-0005. Both tests now pass together.

Verified, no change needed

Each of these looked like a possible defect and turned out not to be:

• matchOffset(args) → args[args.length - 2] is correct for both call sites. String.prototype.replace appends (offset, whole) after the capture groups, and neither specPattern nor adrPattern uses named groups — which would append a groups object and shift the offset to length - 3.
• toDisplayString applied only to the plugin template, not docs-site/scripts/ is right, not an oversight. The plugin parses frontmatter with a real YAML parser (lib-artifact-transforms), so decision-makers: [Alice, Bob] arrives as an array; docs-site/scripts/transform-adrs.js uses a regex extractor (/^decision-makers:\s*"?([^"\n]+)"?/m then .trim()) that can only ever yield a string. The crash is genuinely plugin-only. The PR's reasoning about why the casing fix would otherwise convert a silent omission into a build failure checks out.
• readBaseUrl follows a const only within the same file and returns '' otherwise. That is the pre-existing fallback, and the plugin path no longer depends on it at all now that it reads context.siteConfig. Covered by the "unresolvable or missing config" test.
• protectedRanges ranges whole <a>…</a> elements separately from bare tags — necessary, and the comment says why: <[^>]+> alone covers an ID in an href but not one in the link text, which is the half that actually nests.
• citeGraphArtifacts looks artifacts up by content (ADR filename slug, spec directory) rather than by number, so a consuming repo that renumbered them still links correctly, and one that lacks them degrades to plain text instead of a dead link.
• .toUpperCase() on the matched ADR id in generateDecisionsIndex and transformAdr — needed, since the graph keys nodes by a constructed ADR-NNNN, so a lowercase filename must normalise or the mini-DAG lookup silently misses.

Follow-up worth its own issue (not blocking)

docs-site has 58 npm advisories, 1 critical (websocket-driver, via the dev-server tree). Out of scope here — see #225 for the shell-quote half.

🤖 Posted on behalf of @joestump by claude-opus-5 using Claude Code.