markdownlint/doc/md051.md

MD051 - Link fragments should be valid

Tags: links

Aliases: link-fragments

Parameters:

• ignore_case: Ignore case of fragments (boolean, default false)
• ignored_pattern: Pattern for ignoring additional fragments (string, default ``)

Fixable: Some violations can be fixed by tooling

This rule is triggered when a link fragment does not match any of the fragments that are automatically generated for headings in a document:

# Heading Name

[Link](#fragment)

To fix this issue, change the link fragment to reference an existing heading's generated name (see below):

# Heading Name

[Link](#heading-name)

For consistency, this rule requires fragments to exactly match the GitHub heading algorithm which converts letters to lowercase. Therefore, the following example is reported as a violation:

# Heading Name

[Link](#Heading-Name)

To ignore case when comparing fragments with heading names, the ignore_case parameter can be set to true. In this configuration, the previous example is not reported as a violation.

Alternatively, some platforms allow the syntax {#named-anchor} to be used within a heading to provide a specific name (consisting of only lower-case letters, numbers, -, and _):

# Heading Name {#custom-name}

[Link](#custom-name)

Alternatively, any HTML tag with an id attribute or an a tag with a name attribute can be used to define a fragment:

<a id="bookmark"></a>

[Link](#bookmark)

An a tag can be useful in scenarios where a heading is not appropriate or for control over the text of the fragment identifier.

HTML links to #top scroll to the top of a document. This rule allows that syntax (using lower-case for consistency):

[Link](#top)

This rule also recognizes the custom fragment syntax used by GitHub to highlight specific content in a document.

For example, this link to line 20:

[Link](#L20)

And this link to content starting within line 19 running into line 21:

[Link](#L19C5-L21C11)

Some Markdown generators dynamically create and insert headings when building documents, for example by combining a fixed prefix like figure- and an incrementing numeric counter. To ignore such generated fragments, set the ignored_pattern regular expression parameter to a pattern that matches (e.g., ^figure-).

Rationale: GitHub section links are created automatically for every heading when Markdown content is displayed on GitHub. This makes it easy to link directly to different sections within a document. However, section links change if headings are renamed or removed. This rule helps identify broken section links within a document.

Note: Section links are not part of the CommonMark specification; this rule enforces the GitHub heading algorithm:

1. Convert text to lowercase
2. Remove punctuation characters
3. Convert spaces to dashes
4. Append an incrementing integer (as needed for uniqueness)
5. URI-encode the result