Repository navigation
Make broken documentation links and anchors fail CI on pull requests #268
Description
Problem
Docusaurus is configured to throw on broken markdown links in some cases, but broken anchors have historically only warned at build time (for example CIP contribute targets on the repositories page). Without a pull_request build gate and stricter link/anchor checks, dead navigation can still reach main and production.
This is a release-quality blocker for a documentation site.
Proposed solution
- Ensure CI runs
npm ci+npm run buildon PRs that touchwebsite/**(if not already present). - Tighten Docusaurus config so critical broken links/anchors fail the build in CI (document any intentional exceptions).
- Fix remaining known bad anchors/hrefs so the baseline is green.
- Add a short note in
CONTRIBUTING.md(or equivalent) that docs PRs must pass the site build.
Acceptance criteria
- PR builds for
website/**changes run and must pass before merge (or this issue tracks completing that gate) - Broken anchor/link policy is explicit and fails CI for new regressions
- Existing known broken anchors/hrefs are fixed or allowlisted with justification
- Contributors know how to validate locally (
cd website && npm run build)
Context
Part of maintainer work: Address any critical bugs or blockers.
Related health findings: duplicate deploy workflows / missing PR CI noted in the Aug 2026 repo health review.
Activity
sadSanta-07 commentedon Aug 6, 2026
hey @danbaruka i'd love to take this on. i can configure the docusaurus setting to throw errors on broken links /anchors and update the CI workflows to ensure npm run build blocks any docs or pr's that fail. could u assign this to me ?
github-actions commentedon Sep 11, 2026
Is this issue abandoned? It had no activity for 30 days. It has been marked stale and will be closed in 14 days if no further activity occurs. Add an update to keep it open. See TRIAGE.md for our triage cadence.
IanoNjuguna commentedon Sep 15, 2026
Hi — wanted to connect two related pieces of work to this issue:
docusaurus.config.tsfortrailingSlash: true..agents/skills/docusaurus-linkingskill that documents the linking rules for this repo (trailing-slash awareness, never linking toreadme.mddirectly, when to use absolute vs relative paths, etc.).The skill should help contributors avoid the kinds of regressions described here, but it doesn't replace a CI gate. The acceptance criteria in this issue (PR build check, stricter anchor/link policy, CONTRIBUTING note) still need a separate workflow/config change.
IanoNjuguna commentedon Sep 15, 2026
Opened PR #308 to address this:
npm ci && npm run buildonwebsite/**changes.onBrokenAnchors: "throw"in Docusaurus config.CONTRIBUTING.md.As noted in the PR description, it depends on #304 to fix the existing broken Markdown links before the new CI gate will pass.