CI: check root repository docs for broken links #138

New issue

Closed

opened 2026-04-19 15:13:48 +00:00 by pokebedrock-bot · 0 comments

pokebedrock-bot commented

2026-04-19 15:13:48 +00:00

(Migrated from github.com)

Summary

npm run lint:links only crawls docs/**/*.{md,mdx}, so broken relative links in root repository docs (README.md, CONTRIBUTING.md, DOCUMENTATION.md) currently ship without CI signal.

Evidence

Current script on main: linkinator "docs/**/*.{md,mdx}" --config linkinator.config.json
Local repro on current main:
1. Add a temporary broken relative link to README.md
2. Run npm run lint:links
3. Command still exits 0 after scanning only the docs tree
Observed output:
- linkinator "docs/**/*.{md,mdx}" --config linkinator.config.json
- Successfully scanned 36 links
- exit code 0

Impact

Contributor-facing docs can accumulate stale local links even though CI appears green.
DOCUMENTATION.md is meant to be the living inventory for the repo, so broken references there are especially easy to miss.

Acceptance criteria

npm run lint:links validates root Markdown docs in addition to docs/**/*.{md,mdx}.
npm run ci fails when README.md, CONTRIBUTING.md, or DOCUMENTATION.md contains a broken relative link.
Contributor-facing docs describe the expanded link-check scope accurately.

## Summary `npm run lint:links` only crawls `docs/**/*.{md,mdx}`, so broken relative links in root repository docs (`README.md`, `CONTRIBUTING.md`, `DOCUMENTATION.md`) currently ship without CI signal. ## Evidence - Current script on `main`: `linkinator "docs/**/*.{md,mdx}" --config linkinator.config.json` - Local repro on current `main`: 1. Add a temporary broken relative link to `README.md` 2. Run `npm run lint:links` 3. Command still exits 0 after scanning only the docs tree - Observed output: - `linkinator "docs/**/*.{md,mdx}" --config linkinator.config.json` - `Successfully scanned 36 links` - exit code `0` ## Impact - Contributor-facing docs can accumulate stale local links even though CI appears green. - `DOCUMENTATION.md` is meant to be the living inventory for the repo, so broken references there are especially easy to miss. ## Acceptance criteria - `npm run lint:links` validates root Markdown docs in addition to `docs/**/*.{md,mdx}`. - `npm run ci` fails when `README.md`, `CONTRIBUTING.md`, or `DOCUMENTATION.md` contains a broken relative link. - Contributor-facing docs describe the expanded link-check scope accurately.