Make broken documentation links and anchors fail CI on pull requests

[danbaruka]

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

1. Ensure CI runs npm ci + npm run build on PRs that touch website/** (if not already present).
2. Tighten Docusaurus config so critical broken links/anchors fail the build in CI (document any intentional exceptions).
3. Fix remaining known bad anchors/hrefs so the baseline is green.
4. 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.

[sadSanta-07]

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 ?