chore(gates): check docs internal links and heading anchors

[thymikee]

Summary

Adds pnpm check:doc-links and a docs-links gate. They fail when a link on the docs site, or a README link into it, points to a page or heading that rspress didn't render, or when a page renders the same heading ID twice. rspress's production build already fails on links to missing pages, but it builds #fragment links to missing headings without complaint. Pages moving between files (#3397, #3399) and dedup passes like #3295 can break those silently.

Design: check the built site. The gate runs pnpm --dir website build (about 3 s warm), then scripts/check-doc-links.ts, which reads website/doc_build/**/*.html:

• Heading IDs: taken from the IDs rspress rendered, so there is no copy of its slugger, heading-text extraction, or link rewriting, and no Markdown parser. The PR adds no dependencies, and the lockfile is unchanged.
• Internal links: each must name a built page, and its fragment must be an ID on that page. External URLs are skipped; there are no network calls.
• Site base: read from the build (rspress serves its entry script under assetPrefix, which defaults to base). The script also checks the home link, so a misread base fails instead of making every link look external. It doesn't force a base with RSPRESS_BASE, because rspack's build cache ignores that variable and would serve stale output.
• README: its https://oss.callstack.com/agent-device/docs/... URLs (Markdown links and bare URLs) are checked against the same build.
• Errors name the built page, the link, and the source file, e.g. docs/quick-start: link "/agent-device/docs/sessions#find-a-session-logs" → no heading "find-a-session-logs" (website/docs/docs/quick-start.md).

Why not an rspress plugin: a rehype or afterBuild plugin would read the same rendered IDs. But it would have to collect links across pages inside rspress hooks, couple the gate to the website config, and still leave README to a separate script. Scanning the HTML after the build checks the same output with less coupling.

Wiring: registered in check-affected (checks.ts/model.ts). Changes to website docs, website/package.json, rspress.config.ts or README.md select it. It's also part of check:tooling, and the docs-links.yml workflow runs it because ci.yml ignores docs paths. website/doc_build/ is added to .gitignore.

Validation

• pnpm check:affected --run passed on ea62cf2.
• The checker's tests pass (7/7): fixture builds for a missing page, a missing fragment, a same-page fragment, a duplicate heading ID, external and asset links, and good and bad README URLs.
• pnpm check:doc-links passes on current main docs, which include docs(agent-setup): keep one canonical agent rule #3396–docs: split integrator material into a Build an integration page #3399.
• A planted bad anchor in quick-start.md and one in a README bare URL each failed and were named.
• Tooling only, so no device runs.

🤖 Generated with Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.17 MB	5.17 MB	+276 B
Package (unpacked)	5.17 MB	5.17 MB	+276 B
Package (download)	1.55 MB	1.55 MB	+41 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.3 ms	26.1 ms	-0.2 ms
CLI --help	77.9 ms	76.1 ms	-1.7 ms

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-3401/
Built to branch gh-pages at 2026-10-11 11:27 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[cubic-dev-ai]

All reported issues were addressed across 8 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

At 72d3dac the code looks sound and all 23 checks pass, but I have not run the checker, its tests, or an rspress build. The claims that 226 heading IDs from a real build match and that #3396-#3399 pass are unverified on my side, and I only compared against the @rspress/core 2.0.12 sources, not the @callstack/rspress-preset plugins. Please show the checker output from a real build, then this is ready to merge. I have no code changes to require.

Not blocking, and you can take or leave these: parsePage parses without the GFM extension that rspress applies first, so a bare published URL with a bad anchor in README or a docs page is never checked, and one test with such a URL would cover it. Relative links resolve against the route in sitePath, while rspress joins from the source file's directory, so ./a.md from docs/guide/index.md resolves to /docs/a here and /docs/guide/a in rspress. escapeHeadingIds copies rspress's own function, which you can import with the same createRequire path you use for the slugger.

Is a standalone checker the smallest design? rspress already fails a production build on dead page links, and pr-preview.yml runs that build on every website PR. A rehype plugin in website/rspress.config.ts could read the IDs rspress assigned and check link hashes during that build. That would drop the heading-text extraction, the escape copy, the route mapping and the mdast dependencies, and a small script would still cover README and frontmatter links. The fast, build-free gate is a fair reason to keep this design, so could the PR body say why build-time checking was rejected?

The five cubic-dev-ai threads (CI job inputs, URL boundary, per-page slugger, website/package.json input, MDX parsing) are fixed at this head, so you can resolve them.

[thymikee]

72d3dac now conflicts with main after today's merges, so it needs a rebase. The code verdict and the open question from my earlier comment are unchanged.

[thymikee]

Thanks. I took the design question further: the checker now reads the built site instead of re-deriving rspress, in a58fc4c (rebased onto main and squashed).

• What changed: the gate builds the site, then checks every internal href against the page files and heading IDs rspress rendered in doc_build. The mdast and micromark dependencies (5) are gone, as are the slugger and escapeHeadingIds imports, heading-text extraction, and source-route mapping. The lockfile is unchanged against main. Your GFM, relative-link and escape-copy points no longer apply, because the build does that work.
• Real-build output on current main docs: doc links: every internal link resolves (base /agent-device/). Planted failures each failed and were named:
  • docs/quick-start: link "/agent-device/docs/sessions#find-a-session-logs" → no heading "find-a-session-logs" (website/docs/docs/quick-start.md)
  • README.md:214: link "https://oss.callstack.com/agent-device/docs/sessions#no-such-anchor" → no heading "no-such-anchor"
• Timing: about 3 s, nearly all of it the site build; the scan itself takes 0.08 s.
• Why not an rspress plugin: the PR body has the reason. In short, the HTML scan reads the same rendered output without putting cross-page aggregation inside rspress hooks, and README needs a script either way.
• Design note: I tried forcing RSPRESS_BASE=/ to avoid reading the base from the build. rspack's build cache ignores that variable and served stale /agent-device/ output, so the checker reads the base from the build.

[thymikee]

The PR is ready at ea62cf2. The earlier conflict is resolved, and all 23 checks pass, including the docs-links job, which ran on this head.

Not blocking, and fine to take or leave: isLinkedDoc in model.ts does not match website/docs/docs/_meta.json, website/docs/_nav.json, or the public/ assets. rspress renders the hard-coded links in those two files as sidebar and nav hrefs on every page, and the checker checks those hrefs and <link href> assets. So a change to only one of them selects no checks, and model.test.ts asserts that public/logo.svg selects nothing. Routing every file under website/docs/ to docs-links, as the workflow filter does, would close this, along with a test update.

The five earlier cubic-dev-ai P2 threads are fixed at this head, so they can be resolved: the rspress config in both workflow filters (#3401 (comment)), the /agent-device/docs/ README URL check (#3401 (comment)), the slugger removal (#3401 (comment)), website/package.json in the inputs (#3401 (comment)), and MDX pages checked through built HTML (#3401 (comment)).

I did not run the rspress build, pnpm check:doc-links, or the checker tests. The real-build pass and the planted-failure output come from the author's comment. The unit tests use handwritten HTML, so only the CI job proves the builtBase() regex against rspress's generated script tag, and it passed there. Nothing else must happen before merge.