markdownlint 0.34.0 → 0.36.0

package/doc/CustomRules.md

@@ -1,20 +1,21 @@
 # Custom Rules
 
 In addition to its built-in rules, `markdownlint` lets you enhance the linting
-experience by passing a list of custom rules using the [`options.customRules`
+experience by passing an array of custom rules using the [`options.customRules`
 property][options-custom-rules]. Custom rules can do everything the built-in
 rules can and are defined inline or imported from another package ([keyword
-`markdownlint-rule` on npm][markdownlint-rule]). Custom rules can be disabled,
-enabled, and customized using the same syntax as built-in rules.
+`markdownlint-rule` on npm][markdownlint-rule]). When defined by a file or
+package, the export can be a single rule object (see below) or an array of them.
+Custom rules can be disabled, enabled, and customized using the same syntax as
+built-in rules.
 
 ## Implementing Simple 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
 
@@ -25,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`:
@@ -60,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
@@ -77,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
@@ -129,8 +167,9 @@ exception.
 
 - [Simple rules used by the project's test cases][test-rules]
 - [Code for all `markdownlint` built-in rules][lib]
-- [Package configuration for publishing to npm][test-rules-npm]
-  - Packages should export a single rule object or an `Array` of rule objects
+- [Complete example rule including npm configuration][extended-ascii]
+- [Custom rules from the github/docs repository][github-docs]
+- [Custom rules from the electron/lint-roller repository][electron]
 - [Custom rules from the webhintio/hint repository][hint]
 
 ## References
@@ -138,246 +177,18 @@ 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
+[github-docs]: https://github.com/github/docs/tree/main/src/content-linter/lib/linting-rules
 [hint]: https://github.com/webhintio/hint/blob/main/scripts/lint-markdown.js
 [lib]: ../lib
 [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
-[test-rules-npm]: ../test/rules/npm
+[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
@@ -1354,6 +1355,11 @@ To fix this, add angle brackets around the URL or email address:
 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
+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,
 wrap it in a code span:
 
@@ -1411,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
 ---
@@ -1420,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.
 
@@ -1829,6 +1830,16 @@ enforce the proper capitalization, specify the desired letter case in the
 ]
 ```
 
+Sometimes a proper name is capitalized differently in certain contexts. In such
+cases, add both forms to the `names` array:
+
+```json
+[
+    "GitHub",
+    "github.com"
+]
+```
+
 Set the `code_blocks` parameter to `false` to disable this rule for code blocks
 and spans. Set the `html_elements` parameter to `false` to disable this rule
 for HTML elements and attributes (such as when using a proper name as part of
@@ -1917,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.
 
@@ -1998,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.
 
@@ -2033,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.
@@ -2071,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.
 
@@ -2087,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
@@ -2107,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
@@ -2117,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 `_`):
@@ -2374,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
@@ -2453,6 +2475,57 @@ Missing cells in a row create holes in the table and suggest an omission.
 
 [gfm-table-056]: https://github.github.com/gfm/#tables-extension-
 
+<a name="md058"></a>
+
+## `MD058` - Tables should be surrounded by blank lines
+
+Tags: `table`
+
+Aliases: `blanks-around-tables`
+
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when tables are either not preceded or not followed by a
+blank line:
+
+```markdown
+Some text
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+> Blockquote
+```
+
+To fix violations of this rule, ensure that all tables have a blank line both
+before and after (except when the table is at the very beginning or end of the
+document):
+
+```markdown
+Some text
+
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+
+> Blockquote
+```
+
+Note that text immediately following a table (i.e., not separated by an empty
+line) is treated as part of the table (per the specification) and will not
+trigger this rule:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+This text is part of the table and the next line is blank
+
+Some text
+```
+
+Rationale: In addition to aesthetic reasons, some parsers will incorrectly parse
+tables that don't have blank lines before and after them.
+
 <!-- markdownlint-configure-file {
   "no-inline-html": {
     "allowed_elements": [

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/md034.md

@@ -19,6 +19,11 @@ To fix this, add angle brackets around the URL or email address:
 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
+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,
 wrap it in a code span: