Describe what the link checker actually does now - #59
Merged
Conversation
The Broken Links dashboard gained real HTTP status detection, but the user documentation still described the old browser-side reachability check, telling readers that a valid link merely means "a connection could be established" and that warnings come from "aggressive CORS/CORP policies that do not respect no-cors settings". None of that is true any more, and it told people the opposite of what the tool now does. docs/guides/dashboards.mdx now explains that the check reads real HTTP status, that broken means the server returned an error, and that unverified means no answer came back and needs a human. It also covers where the results come from — `yarn check-links`, not the page itself, because a browser cannot read the status of a cross-origin link — and documents `--strict` for CI, verified to exit 1 on the one broken link currently in docs/ and to ignore unverified ones. The dashboard's own explanatory note is removed. It duplicated all of this, and the page already explains itself: the cards are labelled OK / Broken / Unverified / Not checked, every problem link prints its own reason such as "vale.mdx (line 6) - HTTP 404", the header states when the check last ran, and the Help button links to the guide. The conditional "N links have never been checked" alert stays, since it is actionable rather than explanatory and only appears when there is something to do about it. The four translated copies of this guide now describe removed behaviour. Their lastmod already trails the English source, so the XLIFF export will pick them up as stale — they need retranslating through the normal workflow rather than by hand here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
https://vale.sh/docs/vale-cli/installation/ returns 404. Vale moved its documentation to docs.vale.sh and the redirect for this page no longer lands anywhere: it forwards to docs.vale.sh/vale-cli/installation, which also 404s. This is the one genuinely broken link the new checker found. Now points at https://docs.vale.sh/topics/installation, which returns 200 directly with no redirect. Checked that the page still supports the surrounding sentence — it documents Homebrew, apt, Chocolatey and binary download, as the text claims. Also updates the styles link in the same file. It was not broken, but it reached docs.vale.sh only via a redirect from the old vale.sh/docs structure — the same redirect chain that has already stopped working for the installation page. Pointing at the canonical URL removes that dependency. Both links were repeated verbatim in all four translations, so they are corrected there too. A URL is not a translation: the surrounding prose is untouched, so this does not pre-empt the XLIFF workflow. Worth noting the checker never saw those four copies. It scans docs/ only, so the same dead link survived in i18n/ where nothing was looking. Widening the scan is a separate change. Verified: `yarn check-links --strict` now exits 0 with 0 broken links, where it exited 1 before. Build exits 0 across all five locales with the broken-link count unchanged at 989. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Audited all 57 English docs against the code. Most of the set is
accurate; the problems clustered in two places and one of them turned
out to be a bug in the product rather than in the prose.
Broken RelatedTopics links (the real defect)
generate-docs-metadata.js derived each URL from the file path alone, so
docs-metadata.json disagreed with the routes Docusaurus actually
creates. RelatedTopics renders `/docs${path}` from that file and appears
on 52 pages, so every card pointing at an affected document was a 404 on
the live site. Three rules were missing:
- `slug` front matter, which overrides the path entirely.
context-help.mdx sets slug: "/context-help" and is served there, not
at /docs/guides/markdown-features/context-help.
- the readme index convention. Only `index` was handled, so
wiki/readme.mdx was recorded as /wiki/readme when it is served
at /wiki.
- case. Docusaurus routes are case-sensitive, and lowercasing invents
a URL that does not exist. Latent today because the only
capitalised filenames are unpublished drafts.
Both live URLs verified against production (200), and the two wrong ones
verified as 404 before the fix. 9 tests cover the rules.
Also fixes the one hand-written link that had the same problem:
markdown-features/intro.mdx pointed at `context-help` relative to its
own directory. It now uses a URL-relative link, which resolves correctly
in every locale — a `.mdx` file link does not, it broke the es build.
Stale pasted-from-repo content
Only two docs paste repo files, and both had drifted, which is exactly
the staleness worth designing out:
- cli.mdx reproduced the whole package.json scripts block: six scripts
missing and four wrong, including check-links, which is user-facing.
The paste is gone. The file now points at package.json as the
authoritative list and documents the commands by purpose, which is
what the rest of it already did well.
- react.mdx pasted MDXComponents.jsx without Comment or RelatedTopics,
and referenced `src/themes/MDXComponents.jsx` and
`src/themes/tempate.jsx` — the directory is src/theme and the file is
template.jsx. Paths corrected, block resynced, and a stray slash in
`@site/src/components`/ fixed.
Smaller corrections
- mcp-server.mdx asked for Node 18. The root package requires >=22 and
installation.mdx says 22, and since the MCP server needs a running
docStatic dev server, 18 was never achievable.
- installation.mdx gains the "Clear the Docs folder" step, which
existed only in the two unpublished drafts. Without it a new site
publishes docStatic's own manual as its content.
Not changed: `/docs/context-help#help-example` is still reported as a
broken anchor. It is a false positive — the target is `<a id=...>`,
which is present in the built HTML; Docusaurus only indexes heading
anchors.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
The dashboard gained real HTTP status detection, but the user documentation was never updated with it.
docs/guides/dashboards.mdxstill described the old browser-side reachability check.What the docs were telling people
None of that is true any more. Worse, it told readers the opposite of what the tool now does — that a "valid" link only means something answered, when it now means the server returned a success status.
What it says now
That the check reads real HTTP status; that broken means the server returned an error such as 404 or 500; and that unverified means no answer came back and a human needs to look. It explains where results come from (
yarn check-links, not the page itself, because a browser cannot read the status of a cross-origin link), why internal links and localhost addresses are skipped, and documents--strictfor CI.I verified the
--strictclaim rather than assuming it: it exits 1 on the one broken link currently indocs/, and its condition isstats.broken > 0, so unverified links cannot fail a build on a flaky network.The dashboard's own note is removed
It duplicated all of the above, and the page already explains itself:
vale.mdx (line 6) - HTTP 404The conditional "N external links have never been checked" alert stays — it's actionable rather than explanatory, and only appears when there's something to act on.
Translations need a follow-up
The four translated copies of this guide now describe removed behaviour — the German still reads "Gültige Links, bei denen eine Verbindung hergestellt werden konnte". Their
lastmodalready trails the English source, so the XLIFF export will pick them up as stale. They should be retranslated through the normal workflow rather than hand-edited here.Verification
yarn docusaurus buildexits 0 across all five locales with the broken-link count unchanged at 989 (all pre-existing i18n warnings); esbuild bundles the component Tina-style; 55/55 tests; biome clean; template in sync; note confirmed gone in the browser against a live dev server.🤖 Generated with Claude Code