Update MD051/link-fragments to support GitHub-style line/column range syntax in URLs (refs #1117).

This commit is contained in:
Théo LUDWIG 2024-02-07 20:45:56 +01:00 committed by David Anson
parent ece0ccf269
commit 242b35f98f
8 changed files with 329 additions and 26 deletions

View file

@ -5470,7 +5470,9 @@ module.exports = {
startColumn
} = definition;
const text = unescapeStringTokenText(definition);
if (text.length > 1 && text.startsWith("#") && !fragments.has(text) && !fragments.has(`#${encodeURIComponent(text.slice(1))}`)) {
const encodedText = `#${encodeURIComponent(text.slice(1))}`;
const lineFragmentRe = /^#L\d+(?:C\d+)?(?:-L\d+(?:C\d+)?)?$/;
if (text.length > 1 && text.startsWith("#") && !fragments.has(encodedText) && !lineFragmentRe.test(encodedText)) {
// eslint-disable-next-line no-undef-init
let context = undefined;
// eslint-disable-next-line no-undef-init

View file

@ -16,6 +16,16 @@ generated name (see below):
[Link](#heading-name)
```
Furthermore, this rule mandates the use of lowercase for link fragments.
Thus, even though the link points to the correct fragment, the following example
will still trigger this rule:
```markdown
# 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 `_`):
@ -38,6 +48,28 @@ attribute can be used to define a fragment:
An `a` tag can be useful in scenarios where a heading is not appropriate or for
control over the text of the fragment identifier.
GitHub supports links to [specific lines][github-lines-links].
For example, to link to line 12 of current Markdown file:
```markdown
[Go to line 12](#L12)
```
GitHub also allows to specify a column number:
```markdown
[Go to line 12, column 34](#L12-L34)
```
Or a range of lines/columns:
```markdown
[Go to lines 12-34](#L12-L34)
```
So this rule will not report violations when this syntax is used.
Rationale: [GitHub section links][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.
@ -51,3 +83,4 @@ append an incrementing integer as needed for uniqueness.
[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
[github-lines-links]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown#linking-to-markdown

View file

@ -2100,6 +2100,16 @@ generated name (see below):
[Link](#heading-name)
```
Furthermore, this rule mandates the use of lowercase for link fragments.
Thus, even though the link points to the correct fragment, the following example
will still trigger this rule:
```markdown
# 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 `_`):
@ -2122,6 +2132,28 @@ attribute can be used to define a fragment:
An `a` tag can be useful in scenarios where a heading is not appropriate or for
control over the text of the fragment identifier.
GitHub supports links to [specific lines][github-lines-links].
For example, to link to line 12 of current Markdown file:
```markdown
[Go to line 12](#L12)
```
GitHub also allows to specify a column number:
```markdown
[Go to line 12, column 34](#L12-L34)
```
Or a range of lines/columns:
```markdown
[Go to lines 12-34](#L12-L34)
```
So this rule will not report violations when this syntax is used.
Rationale: [GitHub section links][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.
@ -2135,6 +2167,7 @@ append an incrementing integer as needed for uniqueness.
[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
[github-lines-links]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown#linking-to-markdown
<a name="md052"></a>

View file

@ -24,6 +24,16 @@ generated name (see below):
[Link](#heading-name)
```
Furthermore, this rule mandates the use of lowercase for link fragments.
Thus, even though the link points to the correct fragment, the following example
will still trigger this rule:
```markdown
# 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 `_`):
@ -46,6 +56,28 @@ attribute can be used to define a fragment:
An `a` tag can be useful in scenarios where a heading is not appropriate or for
control over the text of the fragment identifier.
GitHub supports links to [specific lines][github-lines-links].
For example, to link to line 12 of current Markdown file:
```markdown
[Go to line 12](#L12)
```
GitHub also allows to specify a column number:
```markdown
[Go to line 12, column 34](#L12-L34)
```
Or a range of lines/columns:
```markdown
[Go to lines 12-34](#L12-L34)
```
So this rule will not report violations when this syntax is used.
Rationale: [GitHub section links][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.
@ -59,3 +91,4 @@ append an incrementing integer as needed for uniqueness.
[github-section-links]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links
[github-heading-algorithm]: https://github.com/gjtorikian/html-pipeline/blob/f13a1534cb650ba17af400d1acd3a22c28004c09/lib/html/pipeline/toc_filter.rb
[github-lines-links]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet#linking-to-markdown#linking-to-markdown

View file

@ -119,11 +119,13 @@ module.exports = {
for (const definition of definitions) {
const { endColumn, startColumn } = definition;
const text = unescapeStringTokenText(definition);
const encodedText = `#${encodeURIComponent(text.slice(1))}`;
const lineFragmentRe = /^#L\d+(?:C\d+)?(?:-L\d+(?:C\d+)?)?$/;
if (
(text.length > 1) &&
text.startsWith("#") &&
!fragments.has(text) &&
!fragments.has(`#${encodeURIComponent(text.slice(1))}`)
!fragments.has(encodedText) &&
!lineFragmentRe.test(encodedText)
) {
// eslint-disable-next-line no-undef-init
let context = undefined;

View file

@ -86,6 +86,22 @@
[Valid][escapedref]
[Valid](#L7)
[Valid](#L123)
[Valid](#L30C11-L31C9)
[Valid](#L30C11)
[Valid](#L30C11-L31)
[Valid](#L30C11-L31)
[Valid](#L30-L31)
[Valid](#l12-abc)
### Valid H3 Heading
Text
@ -171,6 +187,8 @@ Text
### Valid Heading\-With\_Embedded\_Escaping
### L12 ABC
<a name="namedlink"></a>
<a id = idlink></a>
@ -280,6 +298,22 @@ Valid Setext Heading with Named Fragment {#setext}
[Invalid](#uppercase) {MD051}
[Invalid](#l7) {MD051}
[Invalid](#L12-abc) {MD051}
[Invalid](#L7abc) {MD051}
[Invalid](#L) {MD051}
[Invalid](#L30C) {MD051}
[Invalid](#L30L12) {MD051}
[Invalid](#L30C11-) {MD051}
[Invalid](#L30C11-L31C) {MD051}
<!-- markdownlint-configure-file {
"emphasis-style": false,
"heading-style": false,

View file

@ -23678,7 +23678,7 @@ Generated by [AVA](https://avajs.dev).
37,
],
fixInfo: null,
lineNumber: 196,
lineNumber: 214,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23694,7 +23694,7 @@ Generated by [AVA](https://avajs.dev).
31,
],
fixInfo: null,
lineNumber: 198,
lineNumber: 216,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23710,7 +23710,7 @@ Generated by [AVA](https://avajs.dev).
36,
],
fixInfo: null,
lineNumber: 200,
lineNumber: 218,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23726,7 +23726,7 @@ Generated by [AVA](https://avajs.dev).
28,
],
fixInfo: null,
lineNumber: 202,
lineNumber: 220,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23742,7 +23742,7 @@ Generated by [AVA](https://avajs.dev).
18,
],
fixInfo: null,
lineNumber: 204,
lineNumber: 222,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23762,7 +23762,7 @@ Generated by [AVA](https://avajs.dev).
editColumn: 11,
insertText: '#HREFandID',
},
lineNumber: 206,
lineNumber: 224,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23778,7 +23778,7 @@ Generated by [AVA](https://avajs.dev).
34,
],
fixInfo: null,
lineNumber: 208,
lineNumber: 226,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23794,7 +23794,7 @@ Generated by [AVA](https://avajs.dev).
34,
],
fixInfo: null,
lineNumber: 210,
lineNumber: 228,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23810,7 +23810,7 @@ Generated by [AVA](https://avajs.dev).
39,
],
fixInfo: null,
lineNumber: 212,
lineNumber: 230,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23823,7 +23823,7 @@ Generated by [AVA](https://avajs.dev).
errorDetail: null,
errorRange: null,
fixInfo: null,
lineNumber: 214,
lineNumber: 232,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23839,7 +23839,7 @@ Generated by [AVA](https://avajs.dev).
28,
],
fixInfo: null,
lineNumber: 219,
lineNumber: 237,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23859,7 +23859,7 @@ Generated by [AVA](https://avajs.dev).
editColumn: 9,
insertText: '#valid-fragments',
},
lineNumber: 223,
lineNumber: 241,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23879,7 +23879,7 @@ Generated by [AVA](https://avajs.dev).
editColumn: 12,
insertText: '#namedlink',
},
lineNumber: 225,
lineNumber: 243,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23892,7 +23892,7 @@ Generated by [AVA](https://avajs.dev).
errorDetail: 'Expected: #namedlink; Actual: #NAMEDLINK',
errorRange: null,
fixInfo: null,
lineNumber: 227,
lineNumber: 245,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23912,7 +23912,7 @@ Generated by [AVA](https://avajs.dev).
editColumn: 13,
insertText: '#idlink',
},
lineNumber: 232,
lineNumber: 250,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23928,7 +23928,7 @@ Generated by [AVA](https://avajs.dev).
26,
],
fixInfo: null,
lineNumber: 267,
lineNumber: 285,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23944,7 +23944,7 @@ Generated by [AVA](https://avajs.dev).
26,
],
fixInfo: null,
lineNumber: 269,
lineNumber: 287,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23960,7 +23960,7 @@ Generated by [AVA](https://avajs.dev).
20,
],
fixInfo: null,
lineNumber: 271,
lineNumber: 289,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23976,7 +23976,7 @@ Generated by [AVA](https://avajs.dev).
23,
],
fixInfo: null,
lineNumber: 273,
lineNumber: 291,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -23992,7 +23992,7 @@ Generated by [AVA](https://avajs.dev).
22,
],
fixInfo: null,
lineNumber: 275,
lineNumber: 293,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -24008,7 +24008,7 @@ Generated by [AVA](https://avajs.dev).
42,
],
fixInfo: null,
lineNumber: 277,
lineNumber: 295,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -24024,7 +24024,7 @@ Generated by [AVA](https://avajs.dev).
21,
],
fixInfo: null,
lineNumber: 279,
lineNumber: 297,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -24040,7 +24040,139 @@ Generated by [AVA](https://avajs.dev).
21,
],
fixInfo: null,
lineNumber: 281,
lineNumber: 299,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#l7)',
errorDetail: null,
errorRange: [
1,
14,
],
fixInfo: null,
lineNumber: 301,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#L12-abc)',
errorDetail: 'Expected: #l12-abc; Actual: #L12-abc',
errorRange: [
1,
19,
],
fixInfo: {
deleteCount: 8,
editColumn: 11,
insertText: '#l12-abc',
},
lineNumber: 303,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#L7abc)',
errorDetail: null,
errorRange: [
1,
17,
],
fixInfo: null,
lineNumber: 305,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#L)',
errorDetail: null,
errorRange: [
1,
13,
],
fixInfo: null,
lineNumber: 307,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#L30C)',
errorDetail: null,
errorRange: [
1,
16,
],
fixInfo: null,
lineNumber: 309,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#L30L12)',
errorDetail: null,
errorRange: [
1,
18,
],
fixInfo: null,
lineNumber: 311,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#L30C11-)',
errorDetail: null,
errorRange: [
1,
19,
],
fixInfo: null,
lineNumber: 313,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
'MD051',
'link-fragments',
],
},
{
errorContext: '[Invalid](#L30C11-L31C)',
errorDetail: null,
errorRange: [
1,
23,
],
fixInfo: null,
lineNumber: 315,
ruleDescription: 'Link fragments should be valid',
ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md051.md',
ruleNames: [
@ -24137,6 +24269,22 @@ Generated by [AVA](https://avajs.dev).
[Valid][escapedref]␊
[Valid](#L7)␊
[Valid](#L123)␊
[Valid](#L30C11-L31C9)␊
[Valid](#L30C11)␊
[Valid](#L30C11-L31)␊
[Valid](#L30C11-L31)␊
[Valid](#L30-L31)␊
[Valid](#l12-abc)␊
### Valid H3 Heading␊
Text␊
@ -24222,6 +24370,8 @@ Generated by [AVA](https://avajs.dev).
### Valid Heading\\-With\\_Embedded\\_Escaping␊
### L12 ABC␊
<a name="namedlink"></a>
<a id = idlink></a>
@ -24331,6 +24481,22 @@ Generated by [AVA](https://avajs.dev).
[Invalid](#uppercase) {MD051}␊
[Invalid](#l7) {MD051}␊
[Invalid](#l12-abc) {MD051}␊
[Invalid](#L7abc) {MD051}␊
[Invalid](#L) {MD051}␊
[Invalid](#L30C) {MD051}␊
[Invalid](#L30L12) {MD051}␊
[Invalid](#L30C11-) {MD051}␊
[Invalid](#L30C11-L31C) {MD051}␊
<!-- markdownlint-configure-file {␊
"emphasis-style": false,␊
"heading-style": false,␊