Previously the linter only flagged bare relative links (no .md/.mdx
extension). The Docusaurus build catches the other two classes
(`onBrokenMarkdownLinks: 'throw'`), but only after a multi-minute
compile. Now the source-level lint catches all three:
bare `[X](../foo)` (skips file resolver entirely)
missing-target `[X](./gone.md)` (target file doesn't exist)
wrong-extension `[X](./foo.md)` w/ .mdx (the .md vs .mdx mismatch
that broke the previous
CI run on this branch)
Implementation:
- classifyLink() resolves the link target against the source file's
directory. If it exists → ok. If not but the other extension does →
wrong-extension (reports which extension is actually on disk). If
neither exists → missing-target.
- Output groups findings by kind with category-specific explanations
so the developer immediately knows whether to add an extension, fix
one, or chase a real missing target.
Verified end-to-end by injecting one of each failure mode in turn
and confirming the linter reports the right file:line / category;
restoring the file always returns the lint to green.
Build-time `onBrokenMarkdownLinks: 'throw'` stays in place — defense
in depth. The lint just makes the same finding visible in seconds
rather than minutes.
Copilot flagged two stragglers on editors.md where the previous
file-by-file conversion stopped halfway. Sweeping for the same
pattern across the active content tree found 76 bare relative
internal links total — 14 in this PR's already-modified files
(Copilot's two plus twelve more) and 62 in unchanged files.
Why the build doesn't catch this
─────────────────────────────────
`onBrokenLinks: 'throw'` (set in this PR) only validates *file-based*
markdown references — links whose URL ends in `.md` / `.mdx`. Those
go through Docusaurus's file resolver, which can prove the target
exists. Bare relative URL paths like `[Foo](../foo)` skip that
resolver entirely; Docusaurus emits them as raw hrefs. The browser
then resolves them against the *current* page URL, and for
trailing-slash routes that almost always lands in the wrong
directory. Page navigates client-side and 404s. The linkinator job
in CI *can* catch these, but it's `continue-on-error: true` so
findings are advisory.
What this commit does
──────────────────────
1. Fix all 76 bare relative internal links across the active docs
tree by appending `.md` to each one (preserving anchors / query
strings). All 76 targets resolved to real files; no link
targets changed, only the form of the reference.
2. Fix the component-page generator. 54 of the 76 bare links lived
in two auto-generated index files (`components/ui/index.mdx`
and `components/design-system/index.mdx`). The next regeneration
would have undone the manual fixes without this. The two
emission sites in `generate-superset-components.mjs` now emit
`.md`-suffixed links; comment at the call site explains why.
3. Add `docs/scripts/lint-docs-links.mjs` — fast source-level
linter that scans `.md`/`.mdx` files under the active content
trees (skipping `versioned_docs/` snapshots) and fails if it
finds any markdown link whose URL starts with `./` or `../` and
does not end in `.md`/`.mdx`. Excludes asset paths (.png,
.json, etc.) and ignores fenced code blocks. Wired up as
`yarn lint:docs-links`.
4. Add a `Lint docs links` step to `superset-docs-verify.yml`,
running before the build step so PRs that introduce the pattern
fail in seconds rather than at build-time / not at all. Blocking,
not advisory — exactly the gap linkinator's `continue-on-error`
leaves open.
Verified
────────
- `yarn lint:docs-links` exits 0 on the cleaned tree
- Re-introducing one bare link makes the linter report the exact
file:line with the offending URL, exit code 1
- All 76 originally-flagged targets resolved to real `.md` / `.mdx`
files; only the form of the reference changed
