From 30353cc733561af72bf5d226105429c07b43a666 Mon Sep 17 00:00:00 2001 From: David Anson Date: Sat, 5 Nov 2022 16:49:38 -0700 Subject: [PATCH] Edit description of MD051/link-fragments to clarify that it implements the GitHub algorithm for creating section links (which converts to lowercase) (refs #591). --- doc-build/md051.md | 33 +++++++++++++++++++++++---------- doc/Rules.md | 33 +++++++++++++++++++++++---------- doc/md051.md | 33 +++++++++++++++++++++++---------- 3 files changed, 69 insertions(+), 30 deletions(-) diff --git a/doc-build/md051.md b/doc-build/md051.md index 59ce3b4c..0fd96efa 100644 --- a/doc-build/md051.md +++ b/doc-build/md051.md @@ -1,5 +1,5 @@ -This rule is triggered when a link fragment does not correspond to a heading -in the document: +This rule is triggered when a link fragment does not match any of the fragments +that are automatically generated for headings in a document: ```markdown # Title @@ -7,23 +7,36 @@ in the document: [Link](#fragment) ``` -To fix the issue, change the fragment to reference an existing heading: +To fix this issue, change the link fragment to reference an existing heading: ```markdown +# Title + [Link](#title) ``` -Alternatively, an HTML `a` tag with an `id` (or a `name`) attribute defines a -valid anchor: +Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to +define a fragment: ```markdown - + + +[Link](#bookmark) ``` -Some platforms (e.g., [GitHub][github-section-links]) automatically create HTML -anchors for every heading. This makes it easy to link to different sections in -a document. These internal links can break over time as headings are renamed. +An `a` tag can be useful in scenarios where a heading is not appropriate or for +control over the text of the fragment identifier. -Note: Creating anchors for headings is not part of the CommonMark specification. +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. 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][github-heading-algorithm] which is: +convert heading to lowercase, remove punctuation, convert spaces to dashes, 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/main/lib/html/pipeline/toc_filter.rb diff --git a/doc/Rules.md b/doc/Rules.md index 3ddc1b0e..817d6889 100644 --- a/doc/Rules.md +++ b/doc/Rules.md @@ -2077,8 +2077,8 @@ Tags: `links` Aliases: `link-fragments` -This rule is triggered when a link fragment does not correspond to a heading -in the document: +This rule is triggered when a link fragment does not match any of the fragments +that are automatically generated for headings in a document: ```markdown # Title @@ -2086,26 +2086,39 @@ in the document: [Link](#fragment) ``` -To fix the issue, change the fragment to reference an existing heading: +To fix this issue, change the link fragment to reference an existing heading: ```markdown +# Title + [Link](#title) ``` -Alternatively, an HTML `a` tag with an `id` (or a `name`) attribute defines a -valid anchor: +Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to +define a fragment: ```markdown - + + +[Link](#bookmark) ``` -Some platforms (e.g., [GitHub][github-section-links]) automatically create HTML -anchors for every heading. This makes it easy to link to different sections in -a document. These internal links can break over time as headings are renamed. +An `a` tag can be useful in scenarios where a heading is not appropriate or for +control over the text of the fragment identifier. -Note: Creating anchors for headings is not part of the CommonMark specification. +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. 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][github-heading-algorithm] which is: +convert heading to lowercase, remove punctuation, convert spaces to dashes, 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/main/lib/html/pipeline/toc_filter.rb diff --git a/doc/md051.md b/doc/md051.md index c0f7b55d..a3686060 100644 --- a/doc/md051.md +++ b/doc/md051.md @@ -4,8 +4,8 @@ Tags: `links` Aliases: `link-fragments` -This rule is triggered when a link fragment does not correspond to a heading -in the document: +This rule is triggered when a link fragment does not match any of the fragments +that are automatically generated for headings in a document: ```markdown # Title @@ -13,23 +13,36 @@ in the document: [Link](#fragment) ``` -To fix the issue, change the fragment to reference an existing heading: +To fix this issue, change the link fragment to reference an existing heading: ```markdown +# Title + [Link](#title) ``` -Alternatively, an HTML `a` tag with an `id` (or a `name`) attribute defines a -valid anchor: +Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to +define a fragment: ```markdown - + + +[Link](#bookmark) ``` -Some platforms (e.g., [GitHub][github-section-links]) automatically create HTML -anchors for every heading. This makes it easy to link to different sections in -a document. These internal links can break over time as headings are renamed. +An `a` tag can be useful in scenarios where a heading is not appropriate or for +control over the text of the fragment identifier. -Note: Creating anchors for headings is not part of the CommonMark specification. +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. 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][github-heading-algorithm] which is: +convert heading to lowercase, remove punctuation, convert spaces to dashes, 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/main/lib/html/pipeline/toc_filter.rb