Skip to content
contextlint

REF-005 Anchors

Overview

Section titled “Overview”

Validates that anchor fragments embedded in Markdown links (the part after # in ./file.md#section or #section) point to a heading that actually exists in the target file. If no matching heading is found, an error is reported. Anchors are derived from headings using the same slug rules as GitHub.

Why it matters

Section titled “Why it matters”

When the text of a section heading changes, anchor links pointing to it break silently. The target file itself still exists, so REF-001 Broken links does not catch the issue. AI-generated documents can also introduce anchors that never existed. Anchor validity cannot be detected by file-existence checks alone, so a separate rule is needed.

Options

Section titled “Options”
FieldTypeRequiredDescription
filesstring—Glob of files this rule applies to

The rule works even with no options at all.

Bad example

Section titled “Bad example”
docs/architecture.md:
## System layout


...


docs/overview.md:
See [system overview](./architecture.md#system-overview) for details.

./architecture.md has ## System layout but not ## System overview, which triggers a violation.

docs/overview.md
  line 1  error  Anchor "#system-overview" does not match any heading in ./architecture.md  REF-005

After fix

Section titled “After fix”

Update the link to match an existing heading.

docs/overview.md:
See [system layout](./architecture.md#system-layout) for details.

Configuration example

Section titled “Configuration example”
{
  "rule": "ref005",
  "options": {
    "files": "docs/**/*.md"
  }
}
Section titled “Related rules”