From 846475f20306ea90021323024e55d5896e3f9db8 Mon Sep 17 00:00:00 2001 From: David Anson Date: Sun, 16 Nov 2025 15:36:12 -0800 Subject: [PATCH] Update documentation for MD051/link-fragments to mention encodeURIComponent (refs #1858). --- doc-build/md051.md | 13 +++++++++---- doc/Rules.md | 13 +++++++++---- doc/md051.md | 13 +++++++++---- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/doc-build/md051.md b/doc-build/md051.md index 955c9017..9584bfd5 100644 --- a/doc-build/md051.md +++ b/doc-build/md051.md @@ -86,11 +86,16 @@ 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. +Note: Section links are **not** part of the CommonMark specification; this rule +enforces the [GitHub heading algorithm][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][encodeURIComponent] the result + +[encodeURIComponent]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent [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-linking-to-content]: 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 diff --git a/doc/Rules.md b/doc/Rules.md index 15c4dd18..e938844a 100644 --- a/doc/Rules.md +++ b/doc/Rules.md @@ -2284,11 +2284,16 @@ 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. +Note: Section links are **not** part of the CommonMark specification; this rule +enforces the [GitHub heading algorithm][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][encodeURIComponent] the result + +[encodeURIComponent]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent [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-linking-to-content]: 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 diff --git a/doc/md051.md b/doc/md051.md index 78bfe804..8c8228c1 100644 --- a/doc/md051.md +++ b/doc/md051.md @@ -100,11 +100,16 @@ 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. +Note: Section links are **not** part of the CommonMark specification; this rule +enforces the [GitHub heading algorithm][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][encodeURIComponent] the result + +[encodeURIComponent]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent [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-linking-to-content]: 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