markdownlint 0.33.0 → 0.35.0

package/doc/CustomRules.md

@@ -1,11 +1,13 @@
 # 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
 
@@ -28,11 +30,13 @@ the parsed input and a function to log any violations.
 A simple rule implementation looks like:
 
 ```javascript
+/** @type import("markdownlint").Rule */
 module.exports = {
   "names": [ "any-blockquote" ],
   "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";
@@ -48,8 +52,7 @@ module.exports = {
 };
 ```
 
-A rule is implemented as an `Object` with one optional and four required
-properties:
+A rule is implemented as an `Object`:
 
 - `names` is a required `Array` of `String` values that identify the rule in
   output messages and config.
@@ -59,6 +62,9 @@ properties:
   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.
 - `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
@@ -66,8 +72,13 @@ properties:
   - `params` is an `Object` with properties that describe the content being
     analyzed:
     - `name` is a `String` that identifies the input file/string.
-    - `tokens` is an `Array` of [`markdown-it` `Token`s][markdown-it-token] with
-      added `line` and `lineNumber` properties.
+    - `parsers` is an `Object` with properties corresponding to the value of
+      `parser` in the rule definition (see above).
+      - `markdownit` is an `Object` that provides access to output from the
+        [`markdown-it`][markdown-it] parser.
+        - `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.)
     - `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
@@ -120,9 +131,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
-- [Custom rules from the axibase/docs-util repository][docs-util]
+- [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
@@ -145,7 +156,7 @@ Yields the `params` object:
 ```json
 {
   "name": "doc/example.md",
-  "tokens": [
+  "parsers.markdownit.tokens": [
     {
       "type": "heading_open",
       "tag": "h1",
@@ -364,7 +375,9 @@ Yields the `params` object:
 ```
 
 [commonmark]: https://commonmark.org/
-[docs-util]: https://github.com/axibase/docs-util/tree/master/linting-rules
+[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
@@ -373,4 +386,3 @@ Yields the `params` object:
 [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

package/doc/Rules.md

@@ -495,12 +495,12 @@ For example (assuming normal behavior):
 ```markdown
 IF THIS LINE IS THE MAXIMUM LENGTH
 This line is okay because there are-no-spaces-beyond-that-length
-And this line is a violation because there are
-This-line-is-also-okay-because-there-are-no-spaces
+This line is a violation because there are spaces beyond that length
+This-line-is-okay-because-there-are-no-spaces-anywhere-within
 ```
 
-In `strict` or `stern` modes, the two middle lines above are a violation. The
-third line is a violation in `strict` mode but allowed in `stern` mode.
+In `strict` mode, the last three lines above are all violations. In `stern`
+mode, the middle two lines above are both violations, but the last is okay.
 
 You have the option to exclude this rule for code blocks, tables, or headings.
 To do so, set the `code_blocks`, `tables`, or `headings` parameter(s) to false.
@@ -509,9 +509,10 @@ Code blocks are included in this rule by default since it is often a
 requirement for document readability, and tentatively compatible with code
 rules. Still, some languages do not lend themselves to short lines.
 
-Lines with link/image reference definitions are always exempted from this rule
-(even in `strict` mode) because there is generally no way to split such lines
-without breaking the URL.
+Lines with link/image reference definitions and standalone lines (i.e., not part
+of a paragraph) with only a link/image (possibly using (strong) emphasis) are
+always exempted from this rule (even in `strict` mode) because there is often no
+way to split such lines without breaking the URL.
 
 Rationale: Extremely long lines can be difficult to work with in some editors.
 More information: <https://cirosantilli.com/markdown-style-guide#line-wrapping>.
@@ -1353,6 +1354,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:
 
@@ -1828,6 +1834,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
@@ -2035,6 +2051,9 @@ To fix this issue, use the configured emphasis style throughout the document:
 The configured emphasis style can be a specific symbol to use ("asterisk",
 "underscore"), or can require that usage be consistent within the document.
 
+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.
 
 <a name="md050"></a>
@@ -2070,6 +2089,9 @@ To fix this issue, use the configured strong style throughout the document:
 The configured strong style can be a specific symbol to use ("asterisk",
 "underscore"), or can require that usage be consistent within the document.
 
+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.
 
 <a name="md051"></a>
@@ -2100,6 +2122,16 @@ 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:
+
+```markdown
+# Heading Name
+
+[Link](#Heading-Name)
+```
+
 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 `_`):
@@ -2122,6 +2154,21 @@ attribute can be used to define a fragment:
 An `a` tag can be useful in scenarios where a heading is not appropriate or for
 control over the text of the fragment identifier.
 
+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:
+
+```markdown
+[Link](#L20)
+```
+
+And this link to content starting within line 19 running into line 21:
+
+```markdown
+[Link](#L19C5-L21C11)
+```
+
 Rationale: [GitHub section links][github-section-links] are created
 automatically for every heading when Markdown content is displayed on GitHub.
 This makes it easy to link directly to different sections within a document.
@@ -2135,6 +2182,7 @@ append an incrementing integer as needed for uniqueness.
 
 [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
 
 <a name="md052"></a>
 
@@ -2420,6 +2468,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/md013.md

@@ -35,12 +35,12 @@ For example (assuming normal behavior):
 ```markdown
 IF THIS LINE IS THE MAXIMUM LENGTH
 This line is okay because there are-no-spaces-beyond-that-length
-And this line is a violation because there are
-This-line-is-also-okay-because-there-are-no-spaces
+This line is a violation because there are spaces beyond that length
+This-line-is-okay-because-there-are-no-spaces-anywhere-within
 ```
 
-In `strict` or `stern` modes, the two middle lines above are a violation. The
-third line is a violation in `strict` mode but allowed in `stern` mode.
+In `strict` mode, the last three lines above are all violations. In `stern`
+mode, the middle two lines above are both violations, but the last is okay.
 
 You have the option to exclude this rule for code blocks, tables, or headings.
 To do so, set the `code_blocks`, `tables`, or `headings` parameter(s) to false.
@@ -49,9 +49,10 @@ Code blocks are included in this rule by default since it is often a
 requirement for document readability, and tentatively compatible with code
 rules. Still, some languages do not lend themselves to short lines.
 
-Lines with link/image reference definitions are always exempted from this rule
-(even in `strict` mode) because there is generally no way to split such lines
-without breaking the URL.
+Lines with link/image reference definitions and standalone lines (i.e., not part
+of a paragraph) with only a link/image (possibly using (strong) emphasis) are
+always exempted from this rule (even in `strict` mode) because there is often no
+way to split such lines without breaking the URL.
 
 Rationale: Extremely long lines can be difficult to work with in some editors.
 More information: <https://cirosantilli.com/markdown-style-guide#line-wrapping>.

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:
 

package/doc/md044.md

@@ -27,6 +27,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

package/doc/md049.md

@@ -29,4 +29,7 @@ To fix this issue, use the configured emphasis style throughout the document:
 The configured emphasis style can be a specific symbol to use ("asterisk",
 "underscore"), or can require that usage be consistent within the document.
 
+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

@@ -29,4 +29,7 @@ To fix this issue, use the configured strong style throughout the document:
 The configured strong style can be a specific symbol to use ("asterisk",
 "underscore"), or can require that usage be consistent within the document.
 
+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

@@ -24,6 +24,16 @@ 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:
+
+```markdown
+# Heading Name
+
+[Link](#Heading-Name)
+```
+
 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 `_`):
@@ -46,6 +56,21 @@ attribute can be used to define a fragment:
 An `a` tag can be useful in scenarios where a heading is not appropriate or for
 control over the text of the fragment identifier.
 
+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:
+
+```markdown
+[Link](#L20)
+```
+
+And this link to content starting within line 19 running into line 21:
+
+```markdown
+[Link](#L19C5-L21C11)
+```
+
 Rationale: [GitHub section links][github-section-links] are created
 automatically for every heading when Markdown content is displayed on GitHub.
 This makes it easy to link directly to different sections within a document.
@@ -59,3 +84,4 @@ append an incrementing integer as needed for uniqueness.
 
 [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

package/doc/md058.md

@@ -0,0 +1,48 @@
+# `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.

package/helpers/README.md

@@ -19,30 +19,6 @@ be useful to custom rule authors and may avoid duplicating code.
 
 ## Examples
 
-### Using Helpers from a Custom Rule
-
-```javascript
-const { forEachLine, getLineMetadata } = require("markdownlint-rule-helpers");
-
-module.exports = {
-  "names": [ "every-n-lines" ],
-  "description": "Rule that reports an error every N lines",
-  "tags": [ "test" ],
-  "function": (params, onError) => {
-    const n = params.config.n || 2;
-    forEachLine(getLineMetadata(params), (line, lineIndex) => {
-      const lineNumber = lineIndex + 1;
-      if ((lineNumber % n) === 0) {
-        onError({
-          "lineNumber": lineNumber,
-          "detail": "Line number " + lineNumber
-        });
-      }
-    });
-  }
-};
-```
-
 ### Applying Recommended Fixes
 
 ```javascript
@@ -62,9 +38,9 @@ See also: [`markdownlint` built-in rule implementations][lib].
 *None* - The entire body of code is tested to 100% coverage by the core
 `markdownlint` project, so there are no additional tests here.
 
-[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/CustomRules.md
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/CustomRules.md
 [jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
-[lib]: https://github.com/DavidAnson/markdownlint/tree/v0.33.0/lib
+[lib]: https://github.com/DavidAnson/markdownlint/tree/v0.35.0/lib
 [markdown]: https://en.wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/Rules.md