Skip to content
contextlint

REF-001 Broken links

Overview

Section titled “Overview”

Validates that relative links inside Markdown (links of the form [text](./file.md)) point to files that actually exist. If the target does not exist, an error is reported. Anchor fragments (#section) are excluded from the file existence check — their validity is the responsibility of REF-005 Anchors.

Why it matters

Section titled “Why it matters”

Renaming, deleting, or moving files is the most common way Markdown documents decay over time. AI-generated content can also introduce links to files that never existed. Broken links pass markdownlint and CI silently, so detecting them mechanically is essential.

Options

Section titled “Options”
FieldTypeRequiredDescription
excludestring[]—Array of glob patterns whose link targets are excluded from validation

The rule works even with no options at all. Use exclude for cases where you intentionally link to documents or generated artifacts outside the include set.

Bad example

Section titled “Bad example”
See [architecture](./architecture.md) for details.

If ./architecture.md does not exist, this triggers a violation.

docs/overview.md
  line 1  error  Link target "./architecture.md" does not exist  REF-001

After fix

Section titled “After fix”
See [architecture](./architecture.md) for details.

Either create the target file architecture.md or update the link to the correct path.

Configuration example

Section titled “Configuration example”
{
  "rule": "ref001",
  "options": {
    "exclude": ["generated/**/*.md"]
  }
}
Section titled “Related rules”