markdownlint 0.35.0 → 0.36.1

package/doc/CustomRules.md

@@ -14,9 +14,8 @@ built-in rules.
 For simple requirements like disallowing certain characters or patterns,
 the community-developed
 [markdownlint-rule-search-replace][markdownlint-rule-search-replace]
-plug-in can be used.
-This plug-in allows anyone to create a set of simple text-replacement rules in
-JSON without needing to write any code.
+plug-in can be used. This plug-in allows anyone to create a set of simple
+text-replacement rules without needing to write code.
 
 [markdownlint-rule-search-replace]: https://www.npmjs.com/package/markdownlint-rule-search-replace
 
@@ -27,29 +26,62 @@ to more information, one or more tags, and a function that implements the rule's
 behavior. That function is called once for each file/string input and is passed
 the parsed input and a function to log any violations.
 
-A simple rule implementation looks like:
+Custom rules can (should) operate on a structured set of tokens based on the
+[`micromark`][micromark] `parser` (this is preferred). Alternatively, custom
+rules can operate on a structured set of tokens based on the
+[`markdown-it`][markdown-it] `parser` (legacy support). Finally, custom rules
+can operate directly on text with the `none` `parser`.
+
+A simple rule implementation using the `micromark` parser to report a violation
+for any use of blockquotes might look like:
 
 ```javascript
 /** @type import("markdownlint").Rule */
 module.exports = {
-  "names": [ "any-blockquote" ],
+  "names": [ "any-blockquote-micromark" ],
+  "description": "Rule that reports an error for any blockquote",
+  "information": new URL("https://example.com/rules/any-blockquote"),
+  "tags": [ "test" ],
+  "parser": "micromark",
+  "function": (params, onError) => {
+    const blockquotes = params.parsers.micromark.tokens
+      .filter((token) => token.type === "blockQuote");
+    for (const blockquote of blockquotes) {
+      const lines = blockquote.endLine - blockquote.startLine + 1;
+      onError({
+        "lineNumber": blockquote.startLine,
+        "detail": "Blockquote spans " + lines + " line(s).",
+        "context": params.lines[blockquote.startLine - 1]
+      });
+    }
+  }
+}
+```
+
+That same rule implemented using the `markdown-it` parser might look like:
+
+```javascript
+/** @type import("markdownlint").Rule */
+module.exports = {
+  "names": [ "any-blockquote-markdown-it" ],
   "description": "Rule that reports an error for any blockquote",
   "information": new URL("https://example.com/rules/any-blockquote"),
   "tags": [ "test" ],
   "parser": "markdownit",
-  "function": function rule(params, onError) {
-    params.parsers.markdownit.tokens.filter(function filterToken(token) {
-      return token.type === "blockquote_open";
-    }).forEach(function forToken(blockquote) {
-      var lines = blockquote.map[1] - blockquote.map[0];
+  "function": (params, onError) => {
+    const blockquotes = params.parsers.markdownit.tokens
+      .filter((token) => token.type === "blockquote_open");
+    for (const blockquote of blockquotes) {
+      const [ startIndex, endIndex ] = blockquote.map;
+      const lines = endIndex - startIndex;
       onError({
         "lineNumber": blockquote.lineNumber,
         "detail": "Blockquote spans " + lines + " line(s).",
-        "context": blockquote.line.substr(0, 7)
+        "context": blockquote.line
       });
-    });
+    }
   }
-};
+}
 ```
 
 A rule is implemented as an `Object`:
@@ -62,9 +94,8 @@ A rule is implemented as an `Object`:
   about the rule.
 - `tags` is a required `Array` of `String` values that groups related rules for
   easier customization.
-- `parser` is a required `String` value `"markdownit" | "none"` that specifies
-  the parser data used via `params.parsers` (see below).
-  - Note: The value `"micromark"` is valid but is NOT currently supported.
+- `parser` is a required `String` value `"markdownit" | "micromark" | "none"`
+  that specifies the parser data used via `params.parsers` (see below).
 - `asynchronous` is an optional `Boolean` value that indicates whether the rule
   returns a `Promise` and runs asynchronously.
 - `function` is a required `Function` that implements the rule and is passed two
@@ -79,12 +110,17 @@ A rule is implemented as an `Object`:
         - `tokens` is an `Array` of [`markdown-it` `Token`s][markdown-it-token]
           with added `line` and `lineNumber` properties. (This property was
           previously on the `params` object.)
+      - `micromark` is an `Object` that provides access to output from the
+        [`micromark`][micromark] parser.
+        - `tokens` is an `Array` of [`MicromarkToken`][micromark-token] objects.
+      - Samples for both `tokens` are available via [test snapshots][tokens].
     - `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`).
     - `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:
     - `lineNumber` is a required `Number` specifying the 1-based line number of
@@ -141,239 +177,6 @@ exception.
 - [CommonMark documentation and specification][commonmark]
 - [`markdown-it` Markdown parser project page][markdown-it]
 
-## Params
-
-The Markdown document:
-
-```markdown
-# Title
-
-Text *text* text.
-```
-
-Yields the `params` object:
-
-```json
-{
-  "name": "doc/example.md",
-  "parsers.markdownit.tokens": [
-    {
-      "type": "heading_open",
-      "tag": "h1",
-      "attrs": null,
-      "map": [ 0, 1 ],
-      "nesting": 1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "#",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "# Title",
-      "lineNumber": 1
-    },
-    {
-      "type": "inline",
-      "tag": "",
-      "attrs": null,
-      "map": [ 0, 1 ],
-      "nesting": 0,
-      "level": 1,
-      "children": [
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 0,
-          "children": null,
-          "content": "Title",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 1,
-          "line": "# Title"
-        }
-      ],
-      "content": "Title",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "# Title",
-      "lineNumber": 1
-    },
-    {
-      "type": "heading_close",
-      "tag": "h1",
-      "attrs": null,
-      "map": null,
-      "nesting": -1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "#",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false
-    },
-    {
-      "type": "paragraph_open",
-      "tag": "p",
-      "attrs": null,
-      "map": [ 2, 3 ],
-      "nesting": 1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "Text *text* text.",
-      "lineNumber": 3
-    },
-    {
-      "type": "inline",
-      "tag": "",
-      "attrs": null,
-      "map": [ 2, 3 ],
-      "nesting": 0,
-      "level": 1,
-      "children": [
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 0,
-          "children": null,
-          "content": "Text ",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "em_open",
-          "tag": "em",
-          "attrs": null,
-          "map": null,
-          "nesting": 1,
-          "level": 1,
-          "children": null,
-          "content": "",
-          "markup": "*",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 1,
-          "children": null,
-          "content": "text",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "em_close",
-          "tag": "em",
-          "attrs": null,
-          "map": null,
-          "nesting": -1,
-          "level": 0,
-          "children": null,
-          "content": "",
-          "markup": "*",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        },
-        {
-          "type": "text",
-          "tag": "",
-          "attrs": null,
-          "map": null,
-          "nesting": 0,
-          "level": 0,
-          "children": null,
-          "content": " text.",
-          "markup": "",
-          "info": "",
-          "meta": null,
-          "block": false,
-          "hidden": false,
-          "lineNumber": 3,
-          "line": "Text *text* text."
-        }
-      ],
-      "content": "Text *text* text.",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false,
-      "line": "Text *text* text.",
-      "lineNumber": 3
-    },
-    {
-      "type": "paragraph_close",
-      "tag": "p",
-      "attrs": null,
-      "map": null,
-      "nesting": -1,
-      "level": 0,
-      "children": null,
-      "content": "",
-      "markup": "",
-      "info": "",
-      "meta": null,
-      "block": true,
-      "hidden": false
-    }
-  ],
-  "lines": [
-    "# Title",
-    "",
-    "Text *text* text.",
-    ""
-  ],
-  "frontMatterLines": [],
-  "config": {
-    "customValue1": "abc",
-    "customValue2": 123
-  }
-}
-```
-
 [commonmark]: https://commonmark.org/
 [electron]: https://github.com/electron/lint-roller/tree/main/markdownlint-rules
 [extended-ascii]: https://github.com/DavidAnson/markdownlint-rule-extended-ascii
@@ -383,6 +186,9 @@ Yields the `params` object:
 [markdown-it]: https://github.com/markdown-it/markdown-it
 [markdown-it-token]: https://markdown-it.github.io/markdown-it/#Token
 [markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule
+[micromark]: https://github.com/micromark/micromark
+[micromark-token]: ../lib/markdownlint.d.ts
 [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.js.md

package/doc/Rules.md

@@ -93,8 +93,8 @@ Setext style H2
 ```
 
 Note: The configured heading style can be a specific style to require (`atx`,
-`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may
-just require that usage is consistent within the document via `consistent`.
+`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or can
+require that all heading styles match the first heading style via `consistent`.
 
 Note: The placement of a horizontal rule directly below a line of text can
 trigger this rule by turning that text into a level 2 setext-style heading:
@@ -139,9 +139,10 @@ document:
 * Item 3
 ```
 
-The configured list style can be a specific symbol to use (asterisk, plus,
-dash), to ensure that all list styling is consistent, or to ensure that each
-sublist has a consistent symbol that differs from its parent list.
+The configured list style can ensure all list styling is a specific symbol
+(`asterisk`, `plus`, `dash`), ensure each sublist has a consistent symbol that
+differs from its parent list (`sublist`), or ensure all list styles match the
+first list style (`consistent`).
 
 For example, the following is valid for the `sublist` style because the
 outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
@@ -1416,8 +1417,7 @@ in the document:
 ****
 ```
 
-To fix this, ensure any horizontal rules used in the document are consistent,
-or match the given style if the rule is so configured:
+To fix this, use the same horizontal rule everywhere:
 
 ```markdown
 ---
@@ -1425,12 +1425,8 @@ or match the given style if the rule is so configured:
 ---
 ```
 
-Note: by default, this rule is configured to just require that all horizontal
-rules in the document are the same and will trigger if any of the horizontal
-rules are different than the first one encountered in the document. If you
-want to configure the rule to match a specific style, the parameter given to
-the 'style' option is a string containing the exact horizontal rule text that
-is allowed.
+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`).
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
@@ -1932,8 +1928,8 @@ document:
 To fix violations of this rule, use a consistent style (either indenting or code
 fences).
 
-The specified style can be specific (`fenced`, `indented`) or simply require
-that usage be consistent within the document (`consistent`).
+The configured code block style can be specific (`fenced`, `indented`) or can
+require all code blocks match the first code block (`consistent`).
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
@@ -2013,8 +2009,9 @@ document:
 ```
 ````
 
-The configured list style can be a specific symbol to use (backtick, tilde), or
-can require that usage be consistent within the document.
+The configured code fence style can be a specific symbol to use (`backtick`,
+`tilde`) or it can require all code fences match the first code fence
+(`consistent`).
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
@@ -2048,10 +2045,11 @@ To fix this issue, use the configured emphasis style throughout the document:
 *Text*
 ```
 
-The configured emphasis style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+The configured emphasis style can be a specific symbol to use (`asterisk`,
+`underscore`) or can require all emphasis matches the first emphasis
+(`consistent`).
 
-Note: Emphasis within a word is restricted to "asterisk" in order to avoid
+Note: Emphasis within a word is restricted to `asterisk` in order to avoid
 unwanted emphasis for words containing internal underscores like_this_one.
 
 Rationale: Consistent formatting makes it easier to understand a document.
@@ -2086,11 +2084,11 @@ To fix this issue, use the configured strong style throughout the document:
 **Text**
 ```
 
-The configured strong style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+The configured strong style can be a specific symbol to use (`asterisk`,
+`underscore`) or can require all strong matches the first strong (`consistent`).
 
-Note: Emphasis within a word is restricted to "asterisk" in order to avoid
-unwanted emphasis for words containing internal underscores like_this_one.
+Note: Emphasis within a word is restricted to `asterisk` in order to avoid
+unwanted emphasis for words containing internal underscores like__this__one.
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
@@ -2102,6 +2100,10 @@ Tags: `links`
 
 Aliases: `link-fragments`
 
+Parameters:
+
+- `ignore_case`: Ignore case of fragments (`boolean`, default `false`)
+
 Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when a link fragment does not match any of the fragments
@@ -2122,9 +2124,9 @@ generated name (see below):
 [Link](#heading-name)
 ```
 
-Link fragments may be handled case-sensitively, so this rule requires fragments
-to exactly match the [GitHub heading algorithm][github-heading-algorithm].
-Therefore, the following example is reported as a violation:
+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:
 
 ```markdown
 # Heading Name
@@ -2132,6 +2134,10 @@ Therefore, the following example is reported as a violation:
 [Link](#Heading-Name)
 ```
 
+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 `_`):
@@ -2389,8 +2395,9 @@ This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
 is inconsistent about 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 all tables in that document.
-A specific style can be required by setting the `style` parameter accordingly.
+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`).
 
 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

package/doc/md003.md

@@ -45,8 +45,8 @@ Setext style H2
 ```
 
 Note: The configured heading style can be a specific style to require (`atx`,
-`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may
-just require that usage is consistent within the document via `consistent`.
+`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or can
+require that all heading styles match the first heading style via `consistent`.
 
 Note: The placement of a horizontal rule directly below a line of text can
 trigger this rule by turning that text into a level 2 setext-style heading:

package/doc/md004.md

@@ -29,9 +29,10 @@ document:
 * Item 3
 ```
 
-The configured list style can be a specific symbol to use (asterisk, plus,
-dash), to ensure that all list styling is consistent, or to ensure that each
-sublist has a consistent symbol that differs from its parent list.
+The configured list style can ensure all list styling is a specific symbol
+(`asterisk`, `plus`, `dash`), ensure each sublist has a consistent symbol that
+differs from its parent list (`sublist`), or ensure all list styles match the
+first list style (`consistent`).
 
 For example, the following is valid for the `sublist` style because the
 outer-most indent uses asterisk, the middle indent uses plus, and the inner-most

package/doc/md035.md

@@ -23,8 +23,7 @@ in the document:
 ****
 ```
 
-To fix this, ensure any horizontal rules used in the document are consistent,
-or match the given style if the rule is so configured:
+To fix this, use the same horizontal rule everywhere:
 
 ```markdown
 ---
@@ -32,11 +31,7 @@ or match the given style if the rule is so configured:
 ---
 ```
 
-Note: by default, this rule is configured to just require that all horizontal
-rules in the document are the same and will trigger if any of the horizontal
-rules are different than the first one encountered in the document. If you
-want to configure the rule to match a specific style, the parameter given to
-the 'style' option is a string containing the exact horizontal rule text that
-is allowed.
+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`).
 
 Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md046.md

@@ -34,7 +34,7 @@ document:
 To fix violations of this rule, use a consistent style (either indenting or code
 fences).
 
-The specified style can be specific (`fenced`, `indented`) or simply require
-that usage be consistent within the document (`consistent`).
+The configured code block style can be specific (`fenced`, `indented`) or can
+require all code blocks match the first code block (`consistent`).
 
 Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md048.md

@@ -35,7 +35,8 @@ document:
 ```
 ````
 
-The configured list style can be a specific symbol to use (backtick, tilde), or
-can require that usage be consistent within the document.
+The configured code fence style can be a specific symbol to use (`backtick`,
+`tilde`) or it can require all code fences match the first code fence
+(`consistent`).
 
 Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md049.md

@@ -26,10 +26,11 @@ To fix this issue, use the configured emphasis style throughout the document:
 *Text*
 ```
 
-The configured emphasis style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+The configured emphasis style can be a specific symbol to use (`asterisk`,
+`underscore`) or can require all emphasis matches the first emphasis
+(`consistent`).
 
-Note: Emphasis within a word is restricted to "asterisk" in order to avoid
+Note: Emphasis within a word is restricted to `asterisk` in order to avoid
 unwanted emphasis for words containing internal underscores like_this_one.
 
 Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md050.md

@@ -26,10 +26,10 @@ To fix this issue, use the configured strong style throughout the document:
 **Text**
 ```
 
-The configured strong style can be a specific symbol to use ("asterisk",
-"underscore"), or can require that usage be consistent within the document.
+The configured strong style can be a specific symbol to use (`asterisk`,
+`underscore`) or can require all strong matches the first strong (`consistent`).
 
-Note: Emphasis within a word is restricted to "asterisk" in order to avoid
-unwanted emphasis for words containing internal underscores like_this_one.
+Note: Emphasis within a word is restricted to `asterisk` in order to avoid
+unwanted emphasis for words containing internal underscores like__this__one.
 
 Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md051.md

@@ -4,6 +4,10 @@ Tags: `links`
 
 Aliases: `link-fragments`
 
+Parameters:
+
+- `ignore_case`: Ignore case of fragments (`boolean`, default `false`)
+
 Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when a link fragment does not match any of the fragments
@@ -24,9 +28,9 @@ generated name (see below):
 [Link](#heading-name)
 ```
 
-Link fragments may be handled case-sensitively, so this rule requires fragments
-to exactly match the [GitHub heading algorithm][github-heading-algorithm].
-Therefore, the following example is reported as a violation:
+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:
 
 ```markdown
 # Heading Name
@@ -34,6 +38,10 @@ Therefore, the following example is reported as a violation:
 [Link](#Heading-Name)
 ```
 
+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 `_`):

package/doc/md055.md

@@ -14,8 +14,9 @@ This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
 is inconsistent about 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 all tables in that document.
-A specific style can be required by setting the `style` parameter accordingly.
+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`).
 
 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