markdownlint 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.41.0
+
+- Improve MD022/MD028/MD035/MD042/MD051/MD060
+- Remove handling of inline directive syntax (frequent false positives)
+- Remove deprecated `Options.resultVersion` (breaking change)
+- Remove deprecated `LintResults.toString` (breaking change)
+- Remove support for end-of-life Node version 20
+- Update dependencies
+
+## 0.40.0
+
+- Improve MD011/MD013/MD051/MD060
+- Update dependencies
+
 ## 0.39.0
 
 - Add MD060/table-column-style

package/CONTRIBUTING.md

@@ -83,8 +83,8 @@ Thank you!
 [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/files/package.json#dependencies
-[example-com]: https://en.wikipedia.org/wiki/Example.com
+[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

package/README.md

@@ -28,16 +28,17 @@ documentation, and test cases came from that project.
 [CommonMark][commonmark] specification for Markdown. It additionally supports
 popular [GitHub Flavored Markdown (GFM)][gfm] syntax like autolinks and tables
 as well as directives, footnotes, and math syntax - all implemented by
-[`micromark` extensions][micromark-extensions].
+[`micromark` extensions][micromark-extensions]. (Note that inline directives are
+not supported to avoid confusion due to over-matching.)
 
 [commonmark]: https://commonmark.org/
 [gfm]: https://github.github.com/gfm/
-[markdown]: https://en.wikipedia.org/wiki/Markdown
+[markdown]: https://wikipedia.org/wiki/Markdown
 [markdownlint-ruby]: https://github.com/markdownlint/markdownlint
 [micromark]: https://github.com/micromark/micromark
 [micromark-extensions]: https://github.com/micromark/micromark?tab=readme-ov-file#list-of-extensions
 [nodejs]: https://nodejs.org/
-[static-analysis]: https://en.wikipedia.org/wiki/Static_program_analysis
+[static-analysis]: https://wikipedia.org/wiki/Static_program_analysis
 
 ### Related
 
@@ -206,11 +207,10 @@ issues reported. Two kinds of text are ignored by most rules:
 - [Front matter](https://jekyllrb.com/docs/frontmatter/) (see
   `options.frontMatter` below)
 
-Rules can be enabled, disabled, and configured via `options.config`
-(described below) to define the expected behavior for a set of inputs.
-To enable or disable rules at a particular location within a file, add
-one of these markers to the appropriate place (HTML comments don't
-appear in the final markup):
+All rules are enabled by default. Rules can be enabled, disabled, and configured
+for each call to the `lint` API by passing an `options.config` object (described
+below). To enable or disable rules within a file, use one of the following HTML
+comments (which are not rendered):
 
 - Disable all rules: `<!-- markdownlint-disable -->`
 - Enable all rules: `<!-- markdownlint-enable -->`
@@ -490,7 +490,7 @@ See [.markdownlint.jsonc](schema/.markdownlint.jsonc) and/or
 configuration object with all properties set to the default value.
 
 Sets of rules (known as a "style") can be stored separately and loaded
-as [JSON](https://en.wikipedia.org/wiki/JSON).
+as [JSON](https://wikipedia.org/wiki/JSON).
 
 Example of referencing a built-in style from JavaScript:
 
@@ -605,7 +605,7 @@ Type: `Array` of `String`
 List of files to lint.
 
 Each array element should be a single file (via relative or absolute path);
-[globbing](https://en.wikipedia.org/wiki/Glob_%28programming%29) is the
+[globbing](https://wikipedia.org/wiki/Glob_%28programming%29) is the
 caller's responsibility.
 
 Example: `[ "one.md", "dir/two.md" ]`
@@ -627,9 +627,9 @@ The default value:
 /((^---[^\S\r\n\u2028\u2029]*$[\s\S]+?^---\s*)|(^\+\+\+[^\S\r\n\u2028\u2029]*$[\s\S]+?^(\+\+\+|\.\.\.)\s*)|(^\{[^\S\r\n\u2028\u2029]*$[\s\S]+?^\}\s*))(\r\n|\r|\n|$)/m
 ```
 
-Ignores [YAML](https://en.wikipedia.org/wiki/YAML),
-[TOML](https://en.wikipedia.org/wiki/TOML), and
-[JSON](https://en.wikipedia.org/wiki/JSON) front matter such as:
+Ignores [YAML](https://wikipedia.org/wiki/YAML),
+[TOML](https://wikipedia.org/wiki/TOML), and
+[JSON](https://wikipedia.org/wiki/JSON) front matter such as:
 
 ```text
 ---
@@ -716,16 +716,6 @@ By default, properly-formatted inline comments can be used to create exceptions
 for parts of a document. Setting `noInlineConfig` to `true` ignores all such
 comments.
 
-##### ~~options.resultVersion~~
-
-This property is *deprecated* and should be removed. The default format of the
-`result` object remains the same as setting `resultVersion` to `3`. For
-continued access to other (previously *deprecated*) formats:
-
-```javascript
-import { convertToResultVersion0, convertToResultVersion1, convertToResultVersion2 } from "markdownlint/helpers";
-```
-
 ##### options.strings
 
 Type: `Object` mapping `String` to `String`
@@ -980,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.0.0/doc/md010.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md010.md",
       "errorDetail": "Column: 17",
       "errorContext": null,
       "errorRange": [ 17, 1 ],
@@ -989,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.0.0/doc/md018.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
       "errorRange": [ 1, 2 ],
@@ -998,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.0.0/doc/md018.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md018.md",
       "errorDetail": null,
       "errorContext": "#This file fails\tsome rules.",
       "errorRange": [ 1, 2 ],
@@ -1007,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.0.0/doc/md041.md",
+      "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/md041.md",
       "errorDetail": null,
       "errorContext": "#bad.md",
       "errorRange": null,
@@ -1059,7 +1049,6 @@ following projects or one of the tools in the [Related section](#related):
 - [Garden React Components][garden] ([Search repository][garden-search])
 - [MDN Web Docs][mdn] ([Search repository][mdn-search])
 - [MkDocs][mkdocs] ([Search repository][mkdocs-search])
-- [Mocha][mocha] ([Search repository][mocha-search])
 - [Pi-hole documentation][pi-hole] ([Search repository][pi-hole-search])
 - [Reactable][reactable] ([Search repository][reactable-search])
 - [V8][v8] ([Search repository][v8-search])
@@ -1092,8 +1081,6 @@ For more advanced integration scenarios:
 [mdn-search]: https://github.com/mdn/content/search?q=markdownlint
 [mkdocs]: https://www.mkdocs.org/
 [mkdocs-search]: https://github.com/mkdocs/mkdocs/search?q=markdownlint
-[mocha]: https://mochajs.org/
-[mocha-search]: https://github.com/mochajs/mocha/search?q=markdownlint
 [pi-hole]: https://docs.pi-hole.net
 [pi-hole-search]: https://github.com/pi-hole/docs/search?q=markdownlint
 [reactable]: https://glittershark.github.io/reactable/

package/doc/CustomRules.md

@@ -191,4 +191,4 @@ throws an exception.
 [rule-helpers]: https://www.npmjs.com/package/markdownlint-rule-helpers
 [options-custom-rules]: ../README.md#optionscustomrules
 [test-rules]: ../test/rules
-[tokens]: ../test/snapshots/markdownlint-test-custom-rules.mjs.md
+[tokens]: ../test/markdownlint-test-custom-rules.mjs.snapshot

package/doc/Rules.md

@@ -45,7 +45,7 @@ level at a time:
 ### Another Heading 3
 ```
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+If [YAML](https://wikipedia.org/wiki/YAML) front matter is present and
 contains a `title` property (commonly used with blog posts), this rule treats
 that as a top level heading and will report a violation if the actual first
 heading is not a level 2 heading. To use a different property name in the
@@ -426,7 +426,7 @@ To fix this, swap the `[]` and `()` around:
 [Correct link syntax](https://www.example.com/)
 ```
 
-Note: [Markdown Extra](https://en.wikipedia.org/wiki/Markdown_Extra)-style
+Note: [Markdown Extra](https://wikipedia.org/wiki/Markdown_Extra)-style
 footnotes do not trigger this rule:
 
 ```markdown
@@ -731,6 +731,8 @@ Aliases: `blanks-around-headings`
 
 Parameters:
 
+- `include_front_matter`: Include front matter content (`boolean`, default
+  `false`)
 - `lines_above`: Blank lines above heading (`integer|integer[]`, default `1`)
 - `lines_below`: Blank lines below heading (`integer|integer[]`, default `1`)
 
@@ -772,6 +774,19 @@ blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. This
 rule checks for *at least* as many blank lines as specified; any extra blank
 lines are ignored.
 
+By default, [YAML](https://wikipedia.org/wiki/YAML) front matter is ignored, so
+the following document reports no violations:
+
+```markdown
+---
+title: Title
+---
+## Heading
+```
+
+To require the configured number of blank lines between front matter content and
+a document's first heading, set the `include_front_matter` parameter to `true`.
+
 Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
 will not parse headings that don't have a blank line before, and will parse them
 as regular text.
@@ -898,7 +913,7 @@ lower-level headings (h2, h3, etc.):
 Note: The `level` parameter can be used to change the top-level (ex: to h2) in
 cases where an h1 is added externally.
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+If [YAML](https://wikipedia.org/wiki/YAML) front matter is present and
 contains a `title` property (commonly used with blog posts), this rule treats
 that as a top level heading and will report a violation for any subsequent
 top-level headings. To use a different property name in the front matter,
@@ -952,7 +967,7 @@ Rationale: Headings are not meant to be full sentences. More information:
 [Punctuation at the end of headers][end-punctuation].
 
 [end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
-[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
+[html-entity-references]: https://wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
 
 <a name="md027"></a>
 
@@ -998,29 +1013,33 @@ Tags: `blockquote`, `whitespace`
 Aliases: `no-blanks-blockquote`
 
 This rule is triggered when two blockquote blocks are separated by nothing
-except for a blank line:
+but a blank line:
 
 ```markdown
 > This is a blockquote
 > which is immediately followed by
 
-> this blockquote. Unfortunately
-> In some parsers, these are treated as the same blockquote.
+> this blockquote. In some cases,
+> these may be merged into one blockquote.
 ```
 
-To fix this, ensure that any blockquotes that are right next to each other
-have some text in between:
+To fix this, ensure that consecutive blockquotes have text (or an HTML comment)
+in between:
 
 ```markdown
 > This is a blockquote.
 
-And Jimmy also said:
+This is paragraph text.
+
+> This is a second blockquote.
 
-> This too is a blockquote.
+<!-- This is an HTML comment -->
+
+> This is a third blockquote.
 ```
 
-Alternatively, if they are supposed to be the same quote, then add the
-blockquote symbol at the beginning of the blank line:
+If they are meant to be a single quote, add the blockquote symbol at the
+beginning of the blank line:
 
 ```markdown
 > This is a blockquote.
@@ -1392,7 +1411,7 @@ For more info, visit <https://www.example.com/> or email <user@example.com>.
 
 If a URL or email address contains non-ASCII characters, it may be not be
 handled as intended even when angle brackets are present. In such cases,
-[percent-encoding](https://en.m.wikipedia.org/wiki/Percent-encoding) can be used
+[percent-encoding](https://wikipedia.org/wiki/Percent-encoding) can be used
 to comply with the required syntax for URL and email.
 
 Note: To include a bare URL or email without it being converted into a link,
@@ -1437,8 +1456,8 @@ Parameters:
 
 - `style`: Horizontal rule style (`string`, default `consistent`)
 
-This rule is triggered when inconsistent styles of horizontal rules are used
-in the document:
+This rule is triggered when inconsistent styles of horizontal rules (also known
+as "thematic breaks") are used in a document:
 
 ```markdown
 ---
@@ -1452,16 +1471,23 @@ in the document:
 ****
 ```
 
-To fix this, use the same horizontal rule everywhere:
+To fix this, use the same horizontal rule syntax everywhere:
 
 ```markdown
 ---
 
+---
+
 ---
 ```
 
-The configured style can ensure all horizontal rules use a specific string or it
-can ensure all horizontal rules match the first horizontal rule (`consistent`).
+The `style` parameter's default value `consistent` ensures all horizontal rules
+in a document match the first horizontal rule in that document. To enforce a
+specific pattern of characters, set the `style` parameter to that string (e.g.,
+`"* * *"`).
+
+Note: In order to be recognized as a horizontal rule, a line must contain three
+or more matching `-`, `_`, or `*` characters with optional space between.
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
@@ -1750,9 +1776,9 @@ in cases where an `h1` is added externally.
 Rationale: The top-level heading often acts as the title of a document. More
 information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
 
-[HTML]: https://en.wikipedia.org/wiki/HTML
+[HTML]: https://wikipedia.org/wiki/HTML
 [RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
-[YAML]: https://en.wikipedia.org/wiki/YAML
+[YAML]: https://wikipedia.org/wiki/YAML
 
 <a name="md042"></a>
 
@@ -1778,6 +1804,10 @@ Empty fragments will trigger this rule:
 
 ```markdown
 [an empty fragment](#)
+
+[an empty link definition][empty]
+
+[empty]: #
 ```
 
 But non-empty fragments will not:
@@ -1786,6 +1816,8 @@ But non-empty fragments will not:
 [a valid fragment](#fragment)
 ```
 
+Empty link definitions
+
 Rationale: Empty links do not lead anywhere and therefore don't function as
 links.
 
@@ -1976,7 +2008,7 @@ content of an image for people who may not be able to see it.
 [aria-hidden]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
 [phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
 [w3c]: https://www.w3.org/WAI/alt/
-[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute
+[wikipedia]: https://wikipedia.org/wiki/Alt_attribute
 
 <a name="md046"></a>
 
@@ -2284,14 +2316,19 @@ 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#linking-to-markdown
+[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
 
@@ -2689,15 +2726,18 @@ Aliases: `table-column-style`
 
 Parameters:
 
+- `aligned_delimiter`: Aligned delimiter columns (`boolean`, default `false`)
 - `style`: Table column style (`string`, default `any`, values `aligned` /
   `any` / `compact` / `tight`)
 
-This rule is triggered when the column separators of a
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when the column separator pipe characters (`|`) of a
 [GitHub Flavored Markdown table][gfm-table-060] are used inconsistently.
 
-This rule recognizes three table column styles based on popular use:
+This rule recognizes three table column styles based on popular use.
 
-Style `aligned` looks the most like a table:
+Style `aligned` ensures pipe characters are vertically aligned:
 
 ```markdown
 | Character | Meaning |
@@ -2706,7 +2746,16 @@ Style `aligned` looks the most like a table:
 | N         | No      |
 ```
 
-Style `compact` uses a single space to pad cell content:
+The `aligned` style ignores cell content, so the following is also valid:
+
+```markdown
+| Character | Meaning |
+|-----------|---------|
+|     Y     |     Yes |
+|     N     |      No |
+```
+
+Style `compact` avoids extra padding with a single space around cell content:
 
 ```markdown
 | Character | Meaning |
@@ -2715,7 +2764,7 @@ Style `compact` uses a single space to pad cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding for cell content:
+Style `tight` uses no padding at all for cell content:
 
 ```markdown
 |Character|Meaning|
@@ -2725,16 +2774,61 @@ Style `tight` uses no padding for cell content:
 ```
 
 When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
-every table must match the corresponding pattern and errors will be reported for
-any violations. By default, or when the `any` style is used, each table is
-analyzed to see if it satisfies any supported style. If so, no errors are
-reported. If not, errors are be reported for whichever style would produce the
-*fewest* errors (i.e., whichever style is the closest match).
+every table must match the corresponding pattern and any violations will be
+reported. By default, or when the `any` style is used, each table is analyzed to
+see if it satisfies any supported style. If so, no violations are reported. If
+not, violations are be reported for whichever style would produce the *fewest*
+issues (i.e., whichever style is the closest match).
+
+Setting the `aligned_delimiter` parameter to `true` requires pipe characters in
+the delimiter row to align with those in the header row. This can be used with
+`compact` and `tight` tables to make the header text more obvious. (It's already
+required for tables with style `aligned`.)
+
+Style `compact` with `aligned_delimiter`:
+
+```markdown
+| Character | Meaning |
+| --------- | ------- |
+| Y | Yes |
+| N | No |
+```
+
+Style `tight` with `aligned_delimiter`:
+
+```markdown
+|Character|Meaning|
+|---------|-------|
+|Y|Yes|
+|N|No|
+```
+
+Violations for styles `compact` and `tight` are simple/independent and can be
+fixed automatically. However, fixing even single violations for style `aligned`
+may require modifying the entire table, and therefore are not automatic:
+
+```markdown
+|Alpha |Delta|
+|------|-----|
+|Charlie|Beta|
+```
+
+**Note**: This rule does not require leading/trailing pipe characters, so this
+is also a valid table for style `compact`:
+
+```markdown
+Character | Meaning
+--- | ---
+Y | Yes
+N | No
+```
 
-Note: Pipe alignment for the `aligned` style is based on character count, so
-wide characters and multi-character encodings can produce unexpected results.
-The following table is correctly aligned based on character count, though some
-editors render the emoji wider:
+**Note**: Pipe alignment for the `aligned` style is based on visual appearance
+and not character count. Because editors typically render [emoji][emoji] and
+[CJK characters][cjk-characters] at *twice* the width of
+[Latin characters][latin-script], this rule takes that into account for tables
+using the `aligned` style. The following table is correctly formatted and will
+appear aligned in most editors and monospaced fonts:
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable extended-ascii -->
@@ -2742,15 +2836,18 @@ editors render the emoji wider:
 ```markdown
 | Response | Emoji |
 | -------- | ----- |
-| Yes      | ✅     |
-| No       | ❎     |
+| Yes      | ✅    |
+| No       | ❎    |
 ```
 
 <!-- markdownlint-restore -->
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
+[cjk-characters]: https://wikipedia.org/wiki/CJK_characters
+[emoji]: https://wikipedia.org/wiki/Emoji
 [gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
+[latin-script]: https://wikipedia.org/wiki/Latin_script
 
 <!-- markdownlint-configure-file {
   "no-inline-html": {

package/doc/md001.md

@@ -37,7 +37,7 @@ level at a time:
 ### Another Heading 3
 ```
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+If [YAML](https://wikipedia.org/wiki/YAML) front matter is present and
 contains a `title` property (commonly used with blog posts), this rule treats
 that as a top level heading and will report a violation if the actual first
 heading is not a level 2 heading. To use a different property name in the

package/doc/md011.md

@@ -20,7 +20,7 @@ To fix this, swap the `[]` and `()` around:
 [Correct link syntax](https://www.example.com/)
 ```
 
-Note: [Markdown Extra](https://en.wikipedia.org/wiki/Markdown_Extra)-style
+Note: [Markdown Extra](https://wikipedia.org/wiki/Markdown_Extra)-style
 footnotes do not trigger this rule:
 
 ```markdown

package/doc/md022.md

@@ -6,6 +6,8 @@ Aliases: `blanks-around-headings`
 
 Parameters:
 
+- `include_front_matter`: Include front matter content (`boolean`, default
+  `false`)
 - `lines_above`: Blank lines above heading (`integer|integer[]`, default `1`)
 - `lines_below`: Blank lines below heading (`integer|integer[]`, default `1`)
 
@@ -47,6 +49,19 @@ blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. This
 rule checks for *at least* as many blank lines as specified; any extra blank
 lines are ignored.
 
+By default, [YAML](https://wikipedia.org/wiki/YAML) front matter is ignored, so
+the following document reports no violations:
+
+```markdown
+---
+title: Title
+---
+## Heading
+```
+
+To require the configured number of blank lines between front matter content and
+a document's first heading, set the `include_front_matter` parameter to `true`.
+
 Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
 will not parse headings that don't have a blank line before, and will parse them
 as regular text.

package/doc/md025.md

@@ -35,7 +35,7 @@ lower-level headings (h2, h3, etc.):
 Note: The `level` parameter can be used to change the top-level (ex: to h2) in
 cases where an h1 is added externally.
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+If [YAML](https://wikipedia.org/wiki/YAML) front matter is present and
 contains a `title` property (commonly used with blog posts), this rule treats
 that as a top level heading and will report a violation for any subsequent
 top-level headings. To use a different property name in the front matter,

package/doc/md026.md

@@ -37,4 +37,4 @@ Rationale: Headings are not meant to be full sentences. More information:
 [Punctuation at the end of headers][end-punctuation].
 
 [end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
-[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
+[html-entity-references]: https://wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

package/doc/md028.md

@@ -5,29 +5,33 @@ Tags: `blockquote`, `whitespace`
 Aliases: `no-blanks-blockquote`
 
 This rule is triggered when two blockquote blocks are separated by nothing
-except for a blank line:
+but a blank line:
 
 ```markdown
 > This is a blockquote
 > which is immediately followed by
 
-> this blockquote. Unfortunately
-> In some parsers, these are treated as the same blockquote.
+> this blockquote. In some cases,
+> these may be merged into one blockquote.
 ```
 
-To fix this, ensure that any blockquotes that are right next to each other
-have some text in between:
+To fix this, ensure that consecutive blockquotes have text (or an HTML comment)
+in between:
 
 ```markdown
 > This is a blockquote.
 
-And Jimmy also said:
+This is paragraph text.
 
-> This too is a blockquote.
+> This is a second blockquote.
+
+<!-- This is an HTML comment -->
+
+> This is a third blockquote.
 ```
 
-Alternatively, if they are supposed to be the same quote, then add the
-blockquote symbol at the beginning of the blank line:
+If they are meant to be a single quote, add the blockquote symbol at the
+beginning of the blank line:
 
 ```markdown
 > This is a blockquote.

package/doc/md034.md

@@ -21,7 +21,7 @@ For more info, visit <https://www.example.com/> or email <user@example.com>.
 
 If a URL or email address contains non-ASCII characters, it may be not be
 handled as intended even when angle brackets are present. In such cases,
-[percent-encoding](https://en.m.wikipedia.org/wiki/Percent-encoding) can be used
+[percent-encoding](https://wikipedia.org/wiki/Percent-encoding) can be used
 to comply with the required syntax for URL and email.
 
 Note: To include a bare URL or email without it being converted into a link,