Tags: links
Aliases: link-fragments
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)Link fragments may be handled case-sensitively, so this rule requires fragments to exactly match the GitHub heading algorithm. Therefore, the following example is reported as a violation:
# Heading Name
[Link](#Heading-Name)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.
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)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.
Section links are not part of the CommonMark specification. This rule enforces the GitHub heading algorithm which is: convert heading to lowercase, remove punctuation, convert spaces to dashes, append an incrementing integer as needed for uniqueness.