markdownlint 0.32.1 → 0.34.0

package/doc/CustomRules.md

@@ -28,11 +28,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 +50,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 +60,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 +70,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
@@ -122,7 +131,6 @@ exception.
 - [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]
 - [Custom rules from the webhintio/hint repository][hint]
 
 ## References
@@ -145,7 +153,7 @@ Yields the `params` object:
 ```json
 {
   "name": "doc/example.md",
-  "tokens": [
+  "parsers.markdownit.tokens": [
     {
       "type": "heading_open",
       "tag": "h1",
@@ -364,7 +372,6 @@ Yields the `params` object:
 ```
 
 [commonmark]: https://commonmark.org/
-[docs-util]: https://github.com/axibase/docs-util/tree/master/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

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>.
@@ -801,8 +802,6 @@ Aliases: `no-duplicate-heading`
 
 Parameters:
 
-- `allow_different_nesting`: Only check sibling headings (`boolean`, default
-  `false`)
 - `siblings_only`: Only check sibling headings (`boolean`, default `false`)
 
 This rule is triggered if there are multiple headings in the document that have
@@ -822,9 +821,8 @@ To fix this, ensure that the content of each heading is different:
 ## Some more text
 ```
 
-If the parameter `siblings_only` (alternatively `allow_different_nesting`) is
-set to `true`, heading duplication is allowed for non-sibling headings (common
-in changelogs):
+If the parameter `siblings_only` is set to `true`, duplication is allowed for
+headings with different parents (as is common in changelogs):
 
 ```markdown
 # Change log
@@ -2038,6 +2036,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>
@@ -2073,6 +2074,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>
@@ -2103,6 +2107,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 `_`):
@@ -2125,6 +2139,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.
@@ -2138,6 +2167,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>
 
@@ -2326,6 +2356,103 @@ Inline links and images can include descriptive text, but take up more space in
 Markdown form. Reference links and images can be easier to read and manipulate
 in Markdown form, but require a separate link reference definition.
 
+<a name="md055"></a>
+
+## `MD055` - Table pipe style
+
+Tags: `table`
+
+Aliases: `table-pipe-style`
+
+Parameters:
+
+- `style`: Table pipe style (`string`, default `consistent`, values
+  `consistent` / `leading_and_trailing` / `leading_only` /
+  `no_leading_or_trailing` / `trailing_only`)
+
+This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
+is inconsistent about its use of leading and trailing pipe characters (`|`).
+
+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.
+
+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
+pipe:
+
+```markdown
+| Header | Header |
+| ------ | ------
+  Cell   | Cell   |
+```
+
+To fix these issues, make sure there is a pipe character at the beginning and
+end of every row:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+```
+
+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 may also
+trigger this rule:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+This text is part of the table
+```
+
+Rationale: Some parsers have difficulty with tables that are missing their
+leading or trailing pipe characters. The use of leading/trailing pipes can also
+help provide visual clarity.
+
+[gfm-table-055]: https://github.github.com/gfm/#tables-extension-
+
+<a name="md056"></a>
+
+## `MD056` - Table column count
+
+Tags: `table`
+
+Aliases: `table-column-count`
+
+This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-056]
+does not have the same number of cells in every row.
+
+This table's second data row has too few cells and its third data row has too
+many cells:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+| Cell   |
+| Cell   | Cell   | Cell   |
+```
+
+To fix these issues, ensure every row has the same number of cells:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+| Cell   | Cell   |
+| Cell   | Cell   |
+```
+
+Note that a table's header row and its delimiter row must have the same number
+of cells or it will not be recognized as a table (per specification).
+
+Rationale: Extra cells in a row are usually not shown, so their data is lost.
+Missing cells in a row create holes in the table and suggest an omission.
+
+[gfm-table-056]: https://github.github.com/gfm/#tables-extension-
+
 <!-- 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/md024.md

@@ -6,8 +6,6 @@ Aliases: `no-duplicate-heading`
 
 Parameters:
 
-- `allow_different_nesting`: Only check sibling headings (`boolean`, default
-  `false`)
 - `siblings_only`: Only check sibling headings (`boolean`, default `false`)
 
 This rule is triggered if there are multiple headings in the document that have
@@ -27,9 +25,8 @@ To fix this, ensure that the content of each heading is different:
 ## Some more text
 ```
 
-If the parameter `siblings_only` (alternatively `allow_different_nesting`) is
-set to `true`, heading duplication is allowed for non-sibling headings (common
-in changelogs):
+If the parameter `siblings_only` is set to `true`, duplication is allowed for
+headings with different parents (as is common in changelogs):
 
 ```markdown
 # Change log

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

@@ -0,0 +1,54 @@
+# `MD055` - Table pipe style
+
+Tags: `table`
+
+Aliases: `table-pipe-style`
+
+Parameters:
+
+- `style`: Table pipe style (`string`, default `consistent`, values
+  `consistent` / `leading_and_trailing` / `leading_only` /
+  `no_leading_or_trailing` / `trailing_only`)
+
+This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
+is inconsistent about its use of leading and trailing pipe characters (`|`).
+
+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.
+
+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
+pipe:
+
+```markdown
+| Header | Header |
+| ------ | ------
+  Cell   | Cell   |
+```
+
+To fix these issues, make sure there is a pipe character at the beginning and
+end of every row:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+```
+
+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 may also
+trigger this rule:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+This text is part of the table
+```
+
+Rationale: Some parsers have difficulty with tables that are missing their
+leading or trailing pipe characters. The use of leading/trailing pipes can also
+help provide visual clarity.
+
+[gfm-table-055]: https://github.github.com/gfm/#tables-extension-

package/doc/md056.md

@@ -0,0 +1,37 @@
+# `MD056` - Table column count
+
+Tags: `table`
+
+Aliases: `table-column-count`
+
+This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-056]
+does not have the same number of cells in every row.
+
+This table's second data row has too few cells and its third data row has too
+many cells:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+| Cell   |
+| Cell   | Cell   | Cell   |
+```
+
+To fix these issues, ensure every row has the same number of cells:
+
+```markdown
+| Header | Header |
+| ------ | ------ |
+| Cell   | Cell   |
+| Cell   | Cell   |
+| Cell   | Cell   |
+```
+
+Note that a table's header row and its delimiter row must have the same number
+of cells or it will not be recognized as a table (per specification).
+
+Rationale: Extra cells in a row are usually not shown, so their data is lost.
+Missing cells in a row create holes in the table and suggest an omission.
+
+[gfm-table-056]: https://github.github.com/gfm/#tables-extension-

package/helpers/README.md

@@ -24,10 +24,12 @@ be useful to custom rule authors and may avoid duplicating code.
 ```javascript
 const { forEachLine, getLineMetadata } = require("markdownlint-rule-helpers");
 
+/** @type import("markdownlint").Rule */
 module.exports = {
   "names": [ "every-n-lines" ],
   "description": "Rule that reports an error every N lines",
   "tags": [ "test" ],
+  "parser": "none",
   "function": (params, onError) => {
     const n = params.config.n || 2;
     forEachLine(getLineMetadata(params), (line, lineIndex) => {
@@ -62,9 +64,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/main/doc/CustomRules.md
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/CustomRules.md
 [jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
-[lib]: https://github.com/DavidAnson/markdownlint/tree/main/lib
+[lib]: https://github.com/DavidAnson/markdownlint/tree/v0.34.0/lib
 [markdown]: https://en.wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/Rules.md

package/helpers/helpers.js

@@ -277,7 +277,7 @@ module.exports.fencedCodeBlockStyleFor =
  * Return the string representation of a emphasis or strong markup character.
  *
  * @param {string} markup Emphasis or strong string.
- * @returns {string} String representation.
+ * @returns {"asterisk" | "underscore"} String representation.
  */
 module.exports.emphasisOrStrongStyleFor =
   function emphasisOrStrongStyleFor(markup) {
@@ -316,7 +316,7 @@ module.exports.headingStyleFor = function headingStyleFor(token) {
  * Return the string representation of an unordered list marker.
  *
  * @param {Object} token MarkdownItToken instance.
- * @returns {string} String representation.
+ * @returns {"asterisk" | "dash" | "plus"} String representation.
  */
 module.exports.unorderedListStyleFor = function unorderedListStyleFor(token) {
   switch (token.markup) {
@@ -702,10 +702,10 @@ module.exports.frontMatterHasTitle =
 /**
  * Returns an object with information about reference links and images.
  *
- * @param {Object} params RuleParams instance.
+ * @param {import("../helpers/micromark.cjs").Token[]} tokens Micromark tokens.
  * @returns {Object} Reference link/image data.
  */
-function getReferenceLinkImageData(params) {
+function getReferenceLinkImageData(tokens) {
   const normalizeReference = (s) => s.toLowerCase().trim().replace(/\s+/g, " ");
   const definitions = new Map();
   const definitionLineIndices = [];
@@ -714,7 +714,7 @@ function getReferenceLinkImageData(params) {
   const shortcuts = new Map();
   const filteredTokens =
     micromark.filterByTypes(
-      params.parsers.micromark.tokens,
+      tokens,
       [
         // definitionLineIndices
         "definition", "gfmFootnoteDefinition",