MD051 - Link anchors should exist¶
Aliases: link-fragments
What this rule does¶
Ensures that link anchors (the part after #) point to actual headings that exist. This includes both same-document anchors (like #introduction) and cross-file fragment links (like
file.md#heading) when linting multiple files together.
Why this matters¶
- Navigation: Broken internal links frustrate readers trying to jump to sections
- Maintenance: Helps you catch links that break when headings are renamed
- User experience: Ensures smooth document navigation
Examples¶
β Correct¶
# Introduction
## Getting Started
See the [Introduction](#introduction) for background.
Jump to [Getting Started](#getting-started) to begin.
## Working with **bold** and *italic*
Link to [formatted heading](#working-with-bold-and-italic)
<!-- Cross-file fragment links are also validated -->
See [external documentation](README.md#setup) for setup instructions.
β Incorrect¶
# Introduction
## Getting Started
[Jump to Installation](#installation) <!-- No "Installation" heading exists -->
[See Overview](#overview) <!-- No "Overview" heading exists -->
π§ Fixed¶
This rule cannot automatically fix missing anchors - you need to either:
- Add the missing heading
- Update the link to point to an existing heading
- Remove the broken link
Configuration¶
This rule supports configuring the anchor generation style to match different Markdown processors:
[MD051]
# Anchor generation style (default: "github")
# - "github": Preserves Unicode, underscores, and consecutive hyphens
# - "kramdown": ASCII-only with normalization, removes underscores
# - "kramdown-gfm" / "jekyll": Kramdown with GFM input (Jekyll/GitHub Pages)
# - "python-markdown" / "mkdocs": Python-Markdown style (collapses separators, ASCII-only)
anchor-style = "github"
# Match link fragments against headings case-insensitively.
# rumdl defaults to true (permissive). markdownlint defaults to false; set
# this to false for strict markdownlint parity.
ignore-case = true
# Optional regex applied to the fragment text (without the leading '#').
# Fragments that match are skipped β useful for runtime-generated anchors
# such as footnote IDs or build-time slugs.
# ignored-pattern = "^fn:"
ignore-case¶
Controls whether link fragments are matched against headings case-insensitively.
true(rumdl default):[link](#MY-HEADING)resolves to# My Heading.false(markdownlint default): the fragment must exactly match the generated anchor (e.g.,#my-heading). Useful when targeting strict markdownlint parity.
ignored-pattern¶
A regular expression matched against the fragment text (without the leading
#). Any fragment that matches is skipped β neither validated nor reported.
Use this for runtime-generated anchors that aren't visible in the source:
An invalid regex is treated as if ignored-pattern were unset (no fragment is
silently ignored).
When using --flavor mkdocs, the anchor style automatically defaults to python-markdown (unless explicitly overridden). This matches MkDocs's use of Python-Markdown's toc extension for anchor
generation.
check-frontmatter¶
When enabled, path-shaped values in the document's frontmatter are checked the same way body links are. Disabled by default.
| Value | Behavior |
|---|---|
false (default) |
Frontmatter values are not checked |
true |
A fragment in a frontmatter value must name an existing anchor |
It is off by default because frontmatter has no syntax marking a value as a
link: a path-shaped value is only a guess at one. Static site generators also
resolve frontmatter paths from the site root rather than the document's own
directory, so checking them like body links reports working paths as broken.
Enable it for projects whose frontmatter links really are relative to the
document, and list the keys that are not under ignore-frontmatter-fields.
A fragment-only value is resolved against this document's own headings. A value carrying a path resolves against the target file, exactly like a cross-file body link:
---
anchor: '#setup' # must match a heading in this document
guide: ./install.md#setup # must match a heading in install.md
canonical: https://example.com/a.md#setup # external, not checked
title: Node.js # prose, not read as a link
---
ignore-case and ignored-pattern apply to frontmatter fragments exactly as
they do to body links.
ignore-frontmatter-fields¶
Top-level frontmatter keys whose values are never checked. Matched
case-insensitively, and a parent key excludes its whole subtree. Applies only
when check-frontmatter is enabled.
Use it for the keys a generator resolves from somewhere other than the document's directory, such as theme assets or site-root media paths.
Anchor style differences¶
| Heading | GitHub | Python-Markdown | kramdown |
|---|---|---|---|
Hello World |
#hello-world |
#hello-world |
#hello-world |
respect_gitignore |
#respect_gitignore |
#respect_gitignore |
#respectgitignore |
The End - yay |
#the-end---yay |
#the-end-yay |
#the-end---yay |
CI/CD Migration |
#cicd-migration |
#cicd-migration |
#cicd-migration |
CafΓ© au Lait |
#cafΓ©-au-lait |
#cafe-au-lait |
#cafe-au-lait |
δ½ ε₯½δΈη |
#δ½ ε₯½δΈη |
(empty / #_1) |
#section |
Key differences:
- GitHub: Preserves Unicode, underscores, and consecutive hyphens (e.g.,
---) - Python-Markdown (MkDocs): ASCII-only, collapses consecutive separators (e.g.,
---β-), preserves underscores - kramdown: ASCII-only, removes underscores, preserves consecutive hyphens
Automatic fixes¶
This rule does not provide automatic fixes since it cannot guess which heading you meant to link to.
How heading anchors work¶
When you create a heading like ## Getting Started, Markdown automatically creates an anchor #getting-started that you can link to. The conversion follows these rules:
- Convert to lowercase:
Getting Startedβgetting started - Replace spaces with hyphens:
getting startedβgetting-started - Remove special characters:
FAQ's & Tips!βfaqs-tips - Strip formatting:
**Bold** Textβbold-text
Learn more¶
- CommonMark anchors - How link anchors work
- GitHub heading IDs - GitHub's approach to heading anchors