Skip to main content

Internal cross-references resolve

ab-001009 · developer-documentation.maintenance.no-broken-links
Severity: mediumactive

Why it matters

Broken internal links are a reference-integrity defect: a README that points at docs/api.md after the file moved to docs/reference/api.md tells users the documentation is out of date and unreliable. Dead anchor links, missing image badges, and links to source files that were renamed in a refactor all accumulate after restructures. Each broken link is a dead end in the user's journey, and at scale they collectively destroy the navigability of the docs.

Severity rationale

Medium because broken links cause dead ends but most users find alternate paths.

Remediation

Run a link checker across all documentation files and fix every broken internal reference. Wire the check into CI so new breakage fails the build. Example:

npx markdown-link-check README.md
npx markdown-link-check 'docs/**/*.md'

Update stale paths or delete links whose targets are gone. For anchor links, verify the heading slug still matches after any rename.

Detection

  • ID: developer-documentation.maintenance.no-broken-links

  • Severity: medium

  • What to look for: Check internal documentation links -- links from README to docs/ pages, links between doc pages, anchor links within pages, and links to source code files. Also check that image references resolve (badges, diagrams, screenshots). Do not check external URLs (those change outside the project's control). Count every hyperlink in the documentation and enumerate broken vs. working links. Report: X of Y links are valid.

  • Pass criteria: All internal documentation links (between docs pages, from README to docs, anchor links) resolve to existing targets. Image references load correctly. Report the count of total links checked and confirmed valid even on pass. At least 1 implementation must be confirmed.

  • Fail criteria: Any internal link points to a file or anchor that doesn't exist. Common patterns: docs restructured but links not updated, links to moved files, badge images referencing old branch names.

  • Skip (N/A) when: Documentation has no internal links (single README with no cross-references).

  • Detail on fail: Example: "README links to docs/api.md but that file doesn't exist (moved to docs/reference/api.md)" or "3 internal links in docs/ point to pages that were removed in a restructure"

  • Remediation: Run a link checker to find all broken internal links:

    # Using markdown-link-check
npx markdown-link-check README.md
npx markdown-link-check docs/**/*.md

    Fix broken links by updating paths or removing links to deleted content.

Taxons

reference-integrity

History