markdownlint 0.41.1 → 0.42.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.42.0
+
+- Improve MD011/MD018/MD020/MD043/MD051/MD055/MD060
+- Add regular expression denial of service protection
+- Add support for reporting issues with front matter
+- Update dependencies
+
 ## 0.41.1
 
 - Improve MD029
@@ -533,3 +540,14 @@
 
 - Initial release
 - Includes tests MD001-MD032
+
+<!-- markdownlint-configure-file {
+  "required-headings": {
+    "headings": [
+      "# Changelog",
+      "^",
+      "%% ^\\d+\\.\\d+\\.\\d+$",
+      "^"
+    ]
+  }
+} -->

package/CONTRIBUTING.md

@@ -3,90 +3,75 @@
 Interested in contributing? Great! Here are some suggestions to make it a good
 experience:
 
-Start by [opening an issue](https://github.com/DavidAnson/markdownlint/issues),
-whether to identify a problem or outline a change. That issue should be used to
-discuss the situation and agree on a plan of action before writing code or
-sending a pull request. Maybe the problem isn't really a problem, or maybe there
-are more things to consider. If so, it's best to realize that before spending
-time and effort writing code that may not get used.
+Start by [opening an issue][issues], whether to identify a problem or outline a
+change. That issue should be used to discuss the situation and agree on a plan
+of action before writing code or sending a pull request. Maybe the problem isn't
+really a problem, or maybe there are more things to consider. If so, it's best
+to realize that before spending time and effort writing code that gets rejected.
 
 Match the coding style of the files you edit. Although everyone has their own
 preferences and opinions, a pull request is not the right forum to debate them.
 
-Do not add new [`dependencies` to `package.json`][dependencies]. The Markdown
-parser [`micromark`][micromark] (and its extensions) is this project's only
-dependency.
+Do not add new [`dependencies` to `package.json`][deps].
 
 Package versions for `dependencies` and `devDependencies` should be specified
-exactly (also known as "pinning"). The short explanation is that doing otherwise
-eventually leads to inconsistent behavior and broken functionality. (See [Why I
-pin dependency versions in Node.js packages][version-pinning] for a longer
-explanation.)
-
-If developing a new rule, start by creating a [custom rule][custom-rules] in its
-own project. Once written, published, and tested in real world scenarios, open
-an issue to consider adding it to this project. For rule ideas, see [issues
-tagged with the `new rule` label][new-rule].
-
-Add tests for all new/changed functionality. Test positive and negative
-scenarios. Try to break the new code now, or else it will get broken later.
-
-Run tests before sending a pull request via `npm test` in the [usual
-manner][npm-scripts]. Tests should all pass on all platforms. The test runner is
-[AVA][ava] and test cases are located in `test/markdownlint-test*.js`. When
-running tests, `test/*.md` files are enumerated, linted, and fail if any
-violations are missing a corresponding `{MD###}` marker in the test file. For
-example, the line `### Heading {MD001}` is expected to trigger the rule `MD001`.
-For cases where the marker text can not be present on the same line, the syntax
-`{MD###:#}` can be used to include a line number. If `some-test.md` needs custom
-configuration, a `some-test.json` is used to provide a custom `options.config`
-for that scenario. Tests run by `markdownlint-test-scenarios.js` use [AVA's
-snapshot feature][ava-snapshots]. To update snapshots (for example, after
-modifying a test file), run `npm run update-snapshots` and include the updated
-files with the pull request.
-
-Lint before sending a pull request by running `npm run lint`. There should be no
-issues.
-
-Run a full continuous integration pass before sending a pull request via `npm
-run ci`. Code coverage should always be 100%. As part of a continuous
-integration run, generated files may get updated and fail the run - commit them
-to the repository and rerun continuous integration.
-
-Pull requests should contain a single commit. If necessary, squash multiple
-commits before creating the pull request and when making changes. (See [Git
-Tools - Rewriting History][rewriting-history] for details.)
-
-Open pull requests against the `next` branch. That's where the latest changes
-are staged for the next release. Include the text "(fixes #??)" at the end of
+exactly (also known as "pinning"). Doing otherwise causes inconsistent behavior
+and broken functionality. (See [Why I pin dependency versions in Node.js
+packages][pinning] for a longer explanation.)
+
+Add tests for all new/changed functionality. Test both positive and negative
+scenarios. Try to break the new code now, or it will get broken later. This
+project maintains 100% code coverage.
+
+Run tests before sending a pull request via `npm test`. Tests need to pass on
+all platforms. Test cases are implemented in `test/*.mjs`. As part of testing,
+`test/*.md` files are enumerated, linted, and fail if any violations are missing
+a corresponding `{MD###}` marker in the test file. For cases where a marker can
+not be present on the corresponding line, the syntax `{MD###:#}`can be used. To
+update test snapshots (for example, after modifying a test file), use `npm run
+update-snapshots` and include the updated snapshot files with the pull request.
+
+Run a full continuous integration pass before opening a pull request via `npm
+run ci`. As part of the continuous integration run, generated files may get
+updated and fail the run - commit those changes and rerun.
+
+Pull requests should contain a single commit with a commit message that is a
+brief sentence with punctuation. Include the text "(fixes #??)" at the end of
 the commit message so the pull request will be associated with the relevant
-issue. End commit messages with a period (`.`). Once accepted, the tag `fixed in
-next` will be added to the issue. When the commit is merged to the main branch
-during the release process, the issue will be closed automatically. (See
-[Closing issues using keywords][closing-keywords] for details.)
-
-Please refrain from using slang or meaningless placeholder words. Sample content
-can be "text", "code", "heading", or the like. Sample URLs should use
-[example.com][example-com] which is safe for this purpose. Profanity is not
-allowed.
-
-In order to maintain the permissive MIT license this project uses, all
-contributions must be your own and released under that license. Code you add
-should be an original work and should not be copied from elsewhere. Taking code
-from a different project, Stack Overflow, or the like is not allowed. The use of
-tools such as GitHub Copilot, ChatGPT, LLMs (large language models), etc. that
-incorporate code from other projects is not allowed.
+issue. Squash multiple commits before creating the pull request or when making
+updates. (See [Git Tools - Rewriting History][rewriting] for details.)
+
+Create all pull requests for the `next` branch which contains the latest changes
+ready for release.  Once accepted, the tag `fixed in next` will be added to the
+issue. When that commit is merged to the `main` branch during the release
+process, the issue will be closed automatically.
+
+Refrain from using slang or meaningless placeholder text in code, documentation,
+or tests. Sample content can be "text", "code", "heading", etc.. URLs should use
+[example.com][example]. Profanity is not allowed.
+
+When considering a new rule, start by creating a [custom rule][custom] in a
+dedicated repository. Once it has been written, published, and tested in real-
+world scenarios, open an issue to discuss adding it to this project. For rule
+ideas, see [issues tagged with the `new rule` label][new]. Not all rules make
+sense to include.
+
+In order to maintain the permissive [MIT license][mit] this project has, all
+contributions must be your own and released under the MIT license. Code you add
+should be an original work and should not be copied from elsewhere. Reusing code
+from a different project, Stack Overflow, etc. is not allowed. The use of tools
+such as Copilot, ChatGPT, Claude, etc. that produce output from a [large
+language model (LLM)][llm] is not allowed because LLMs reuse code from other
+projects.
 
 Thank you!
 
-[ava]: https://github.com/avajs/ava
-[ava-snapshots]: https://github.com/avajs/ava/blob/main/docs/04-snapshot-testing.md
-[closing-keywords]: https://help.github.com/articles/closing-issues-using-keywords/
-[custom-rules]: doc/CustomRules.md
-[dependencies]: https://docs.npmjs.com/cli/v11/configuring-npm/package-json#dependencies
-[example-com]: https://wikipedia.org/wiki/Example.com
-[micromark]: https://www.npmjs.com/package/micromark
-[new-rule]: https://github.com/DavidAnson/markdownlint/labels/new%20rule
-[npm-scripts]: https://docs.npmjs.com/misc/scripts
-[rewriting-history]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
-[version-pinning]: https://dlaa.me/blog/post/versionpinning
+[custom]: doc/CustomRules.md
+[deps]: https://docs.npmjs.com/cli/v11/configuring-npm/package-json#dependencies
+[example]: https://wikipedia.org/wiki/Example.com
+[issues]: https://github.com/DavidAnson/markdownlint/issues
+[llm]: https://wikipedia.org/wiki/Large_language_model
+[mit]: https://choosealicense.com/licenses/mit/
+[new]: https://github.com/DavidAnson/markdownlint/labels/new%20rule
+[rewriting]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
+[pinning]: https://dlaa.me/blog/post/versionpinning

package/README.md

@@ -1,6 +1,6 @@
 # markdownlint
 
-> A Node.js style checker and lint tool for Markdown/CommonMark files.
+> A Node.js style checker and lint tool for Markdown/CommonMark files
 
 [![npm version][npm-image]][npm-url]
 [![License][license-image]][license-url]
@@ -574,7 +574,7 @@ ones.
 For example:
 
 ```javascript
-[ JSON.parse, require("toml").parse, require("js-yaml").load ]
+[ JSON.parse, require("smol-toml").parse, require("js-yaml").load ]
 ```
 
 ##### options.customRules
@@ -830,7 +830,7 @@ parsers should come before flexible parsers.
 For example:
 
 ```javascript
-[ JSON.parse, require("toml").parse, require("js-yaml").load ]
+[ JSON.parse, require("smol-toml").parse, require("js-yaml").load ]
 ```
 
 #### fs
@@ -970,7 +970,7 @@ All of which return an object like:
     { "lineNumber": 3,
       "ruleNames": [ "MD010", "no-hard-tabs" ],
       "ruleDescription": "Hard tabs",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.1/doc/md010.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.42.0/doc/md010.md",
       "errorDetail": "Column: 17",
       "errorContext": null,
       "errorRange": [ 17, 1 ],
@@ -979,7 +979,7 @@ All of which return an object like:
     { "lineNumber": 1,
       "ruleNames": [ "MD018", "no-missing-space-atx" ],
       "ruleDescription": "No space after hash on atx style heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.1/doc/md018.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.42.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
       "errorRange": [ 1, 2 ],
@@ -988,7 +988,7 @@ All of which return an object like:
     { "lineNumber": 3,
       "ruleNames": [ "MD018", "no-missing-space-atx" ],
       "ruleDescription": "No space after hash on atx style heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.1/doc/md018.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.42.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#This file fails\tsome rules.",
       "errorRange": [ 1, 2 ],
@@ -997,7 +997,7 @@ All of which return an object like:
     { "lineNumber": 1,
       "ruleNames": [ "MD041", "first-line-heading", "first-line-h1" ],
       "ruleDescription": "First line in a file should be a top-level heading",
-      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.1/doc/md041.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.42.0/doc/md041.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
       "errorRange": null,

package/doc/CustomRules.md

@@ -117,12 +117,14 @@ A rule is implemented as an `Object`:
     - `lines` is an `Array` of `String` values corresponding to the lines of the
       input file/string.
     - `frontMatterLines` is an `Array` of `String` values corresponding to any
-      front matter (not present in `lines`).
+      lines of front matter (not present in the `lines` `Array`).
     - `config` is an `Object` corresponding to the rule's entry in
       `options.config` (if present).
     - `version` is a `String` that corresponds to the version of `markdownlint`
   - `onError` is a function that takes a single `Object` parameter with one
-    required and four optional properties:
+    required and various optional properties:
+    - `frontMatter` is an optional `Boolean` value specifying whether the error
+      refers to `frontMatterLines` (instead of `lines` which is the default)
     - `lineNumber` is a required `Number` specifying the 1-based line number of
       the error.
     - `detail` is an optional `String` with information about what caused the
@@ -147,8 +149,8 @@ A rule is implemented as an `Object`:
         is the platform-independent way to add a line break; line breaks should
         be added at the beginning of a line instead of at the end.
 
-The collection of helper functions shared by the built-in rules is available for
-use by custom rules in the [markdownlint-rule-helpers package][rule-helpers].
+A collection of helper functions (formerly) used by built-in rules is available
+for custom rules in the [markdownlint-rule-helpers package][rule-helpers].
 
 ### Asynchronous Rules
 

package/doc/Rules.md

@@ -400,7 +400,6 @@ More information:
 
 - <https://agiletribe.wordpress.com/2011/10/27/18-dont-use-tab-characters/>
 - <https://www.jwz.org/doc/tabs-vs-spaces.html>
-- <https://adamspiers.org/computing/why_no_tabs.html>
 
 <a name="md011"></a>
 
@@ -860,7 +859,7 @@ If the parameter `siblings_only` is set to `true`, duplication is allowed for
 headings with different parents (as is common in changelogs):
 
 ```markdown
-# Change log
+# Changelog
 
 ## 1.0.0
 
@@ -1841,7 +1840,7 @@ Aliases: `required-headings`
 
 Parameters:
 
-- `headings`: List of headings (`string[]`, default `[]`)
+- `headings`: List of headings (`string[]|null`, default `null`)
 - `match_case`: Match case of headings (`boolean`, default `false`)
 
 This rule is triggered when the headings in a file do not match the array of
@@ -1872,13 +1871,15 @@ To allow optional headings as with the following structure:
 # Heading
 ## Item
 ### Detail (optional)
+### Example (optional)
 ## Foot
 ### Notes (optional)
 ```
 
-Use the special value `"*"` meaning "zero or more unspecified headings" or the
-special value `"+"` meaning "one or more unspecified headings" and set the
-`headings` parameter to:
+Use the special value `*` meaning "zero or more unspecified headings", the
+special value `+` meaning "one or more unspecified headings", or the special
+value `?` meaning "exactly one unspecified heading" and set the `headings`
+parameter to something like:
 
 ```json
 [
@@ -1886,28 +1887,64 @@ special value `"+"` meaning "one or more unspecified headings" and set the
     "## Item",
     "*",
     "## Foot",
-    "*"
+    "+"
 ]
 ```
 
-To allow a single required heading to vary as with a project name:
+To require a heading with a specific level and text matching a specific pattern
+(for example, a one-word project name):
 
 ```markdown
-# Project Name
+# Project
 ## Description
 ## Examples
 ```
 
-Use the special value `"?"` meaning "exactly one unspecified heading":
+Replace the `#` prefix character(s) with `%` and specify a regular expression;
+the following example requires a level 1 heading with a single word made up of
+at least 4 letters:
 
 ```json
 [
-    "?",
+    "% [a-zA-Z]{4,}",
     "## Description",
     "## Examples"
 ]
 ```
 
+To handle repeating heading sections (common in `CHANGELOG` files) such as the
+following:
+
+```markdown
+# Changelog
+## 1.0.0
+### Fixes
+### Features
+## 2.0.0
+### Fixes
+### Features
+```
+
+Use the special value `^` meaning "if the next heading does not match, loop
+back to the previous matching marker":
+
+```json
+[
+    "# Changelog",
+    "^",
+    "%% ^\\d+\\.\\d+\\.\\d+$",
+    "### Fixes",
+    "### Features",
+    "^"
+]
+```
+
+The simple form shown above is enough for most scenarios; if multiple loops are
+needed, matching pairs of `^^`, `^^^`, etc. can be used in conjunction. The
+prefix `%` and the special value `?` are supported with loops, but `*` and `+`
+are not and will result in undefined behavior. To avoid infinite looping, a
+violation is reported if the rule loops more than 1,000 times.
+
 When an error is detected, this rule outputs the line number of the first
 problematic heading (otherwise, it outputs the last line number of the file).
 
@@ -2239,7 +2276,7 @@ Parameters:
 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:
+that are automatically generated by GitHub for headings in the document:
 
 ```markdown
 # Heading Name
@@ -2257,8 +2294,9 @@ generated name (see below):
 ```
 
 For consistency, this rule requires fragments to exactly match the [GitHub
-heading algorithm][github-heading-algorithm] which converts letters to
-lowercase. Therefore, the following example is reported as a violation:
+algorithm for section links][github-section-links] which (among other things)
+converts letters to lowercase. Therefore, the following is reported as a
+violation:
 
 ```markdown
 # Heading Name
@@ -2270,9 +2308,9 @@ 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 `_`):
+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 `_`); that is allowed by this rule:
 
 ```markdown
 # Heading Name {#custom-name}
@@ -2289,8 +2327,8 @@ attribute can be used to define a fragment:
 [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.
+Using 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][html-top-fragment]. This
 rule allows that syntax (using lower-case for consistency):
@@ -2299,16 +2337,15 @@ 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][github-linking-to-content].
-
-For example, this link to line 20:
+This rule supports the fragment syntax used by GitHub to highlight [specific
+lines/sections of a document][github-linking-to-content]. For example, this link
+to line 20:
 
 ```markdown
 [Link](#L20)
 ```
 
-And this link to content starting within line 19 running into line 21:
+And this link to content starting within line 19 running partly through line 21:
 
 ```markdown
 [Link](#L19C5-L21C11)
@@ -2317,8 +2354,8 @@ And this link to content starting within line 19 running into line 21:
 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][RegEx] parameter to a pattern that
-matches (e.g., `^figure-`).
+`ignored_pattern` [regular expression][RegEx] parameter to a suitable pattern
+(e.g., `^figure-`).
 
 Rationale: [GitHub section links][github-section-links] are created
 automatically for every heading when Markdown content is displayed on GitHub.
@@ -2327,17 +2364,17 @@ 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][github-heading-algorithm]:
+enforces the GitHub algorithm. Basically:
 
 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
+4. Remove HTML comments
+5. Append dash+incrementing integer if needed for uniqueness
+6. [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
 [html-top-fragment]: https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment
 [RegEx]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
@@ -2553,15 +2590,18 @@ Parameters:
 
 - `style`: Table pipe style (`string`, default `consistent`, values
   `consistent` / `leading_and_trailing` / `leading_only` /
-  `no_leading_or_trailing` / `trailing_only`)
+  `no_leading_or_trailing` / `per_table` / `trailing_only`)
 
 This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
-is inconsistent about its use of leading and trailing pipe characters (`|`).
+is inconsistent with its use of leading and trailing pipe characters (`|`).
 
 By default (`consistent` style), the header row of the first table in a document
 is used to determine the style that is enforced for every table in the document.
 A specific style can be used instead (`leading_and_trailing`, `leading_only`,
-`no_leading_or_trailing`, `trailing_only`).
+`no_leading_or_trailing`, `trailing_only`) to require all tables in a document
+have the same approach. The style `per_table` can be used to require the rows of
+each table use the same approach (based on its header row) while allowing tables
+in a document to differ from each other.
 
 This table's header row has leading and trailing pipes, but its delimiter row is
 missing the trailing pipe and its first row of cells is missing the leading
@@ -2765,7 +2805,8 @@ The `aligned` style ignores cell content, so the following is also valid:
 |     N     |      No |
 ```
 
-Style `compact` avoids extra padding with a single space around cell content:
+Style `compact` avoids extra padding with a single space before and after cell
+content (or just a single space for cells without content):
 
 ```markdown
 | Character | Meaning |
@@ -2774,7 +2815,7 @@ Style `compact` avoids extra padding with a single space around cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding at all for cell content:
+Style `tight` uses no padding at all (for cells with or without content):
 
 ```markdown
 |Character|Meaning|

package/doc/md010.md

@@ -59,4 +59,3 @@ More information:
 
 - <https://agiletribe.wordpress.com/2011/10/27/18-dont-use-tab-characters/>
 - <https://www.jwz.org/doc/tabs-vs-spaces.html>
-- <https://adamspiers.org/computing/why_no_tabs.html>

package/doc/md024.md

@@ -29,7 +29,7 @@ If the parameter `siblings_only` is set to `true`, duplication is allowed for
 headings with different parents (as is common in changelogs):
 
 ```markdown
-# Change log
+# Changelog
 
 ## 1.0.0
 

package/doc/md043.md

@@ -6,7 +6,7 @@ Aliases: `required-headings`
 
 Parameters:
 
-- `headings`: List of headings (`string[]`, default `[]`)
+- `headings`: List of headings (`string[]|null`, default `null`)
 - `match_case`: Match case of headings (`boolean`, default `false`)
 
 This rule is triggered when the headings in a file do not match the array of
@@ -37,13 +37,15 @@ To allow optional headings as with the following structure:
 # Heading
 ## Item
 ### Detail (optional)
+### Example (optional)
 ## Foot
 ### Notes (optional)
 ```
 
-Use the special value `"*"` meaning "zero or more unspecified headings" or the
-special value `"+"` meaning "one or more unspecified headings" and set the
-`headings` parameter to:
+Use the special value `*` meaning "zero or more unspecified headings", the
+special value `+` meaning "one or more unspecified headings", or the special
+value `?` meaning "exactly one unspecified heading" and set the `headings`
+parameter to something like:
 
 ```json
 [
@@ -51,28 +53,64 @@ special value `"+"` meaning "one or more unspecified headings" and set the
     "## Item",
     "*",
     "## Foot",
-    "*"
+    "+"
 ]
 ```
 
-To allow a single required heading to vary as with a project name:
+To require a heading with a specific level and text matching a specific pattern
+(for example, a one-word project name):
 
 ```markdown
-# Project Name
+# Project
 ## Description
 ## Examples
 ```
 
-Use the special value `"?"` meaning "exactly one unspecified heading":
+Replace the `#` prefix character(s) with `%` and specify a regular expression;
+the following example requires a level 1 heading with a single word made up of
+at least 4 letters:
 
 ```json
 [
-    "?",
+    "% [a-zA-Z]{4,}",
     "## Description",
     "## Examples"
 ]
 ```
 
+To handle repeating heading sections (common in `CHANGELOG` files) such as the
+following:
+
+```markdown
+# Changelog
+## 1.0.0
+### Fixes
+### Features
+## 2.0.0
+### Fixes
+### Features
+```
+
+Use the special value `^` meaning "if the next heading does not match, loop
+back to the previous matching marker":
+
+```json
+[
+    "# Changelog",
+    "^",
+    "%% ^\\d+\\.\\d+\\.\\d+$",
+    "### Fixes",
+    "### Features",
+    "^"
+]
+```
+
+The simple form shown above is enough for most scenarios; if multiple loops are
+needed, matching pairs of `^^`, `^^^`, etc. can be used in conjunction. The
+prefix `%` and the special value `?` are supported with loops, but `*` and `+`
+are not and will result in undefined behavior. To avoid infinite looping, a
+violation is reported if the rule loops more than 1,000 times.
+
 When an error is detected, this rule outputs the line number of the first
 problematic heading (otherwise, it outputs the last line number of the file).