markdownlint 0.34.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
 
@@ -129,8 +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
+- [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
@@ -372,6 +375,9 @@ Yields the `params` object:
 ```
 
 [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
@@ -380,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

@@ -1354,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:
 
@@ -1829,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
@@ -2453,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/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/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,32 +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");
-
-/** @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) => {
-      const lineNumber = lineIndex + 1;
-      if ((lineNumber % n) === 0) {
-        onError({
-          "lineNumber": lineNumber,
-          "detail": "Line number " + lineNumber
-        });
-      }
-    });
-  }
-};
-```
-
 ### Applying Recommended Fixes
 
 ```javascript
@@ -64,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.34.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.34.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.34.0/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/Rules.md

package/helpers/helpers.js

@@ -18,10 +18,6 @@ const inlineCommentStartRe =
   /(<!--\s*markdownlint-(disable|enable|capture|restore|disable-file|enable-file|disable-line|disable-next-line|configure-file))(?:\s|-->)/gi;
 module.exports.inlineCommentStartRe = inlineCommentStartRe;
 
-// Regular expressions for range matching
-module.exports.listItemMarkerRe = /^([\s>]*)(?:[*+-]|\d+[.)])\s+/;
-module.exports.orderedListItemMarkerRe = /^[\s>]*0*(\d+)[.)]/;
-
 // Regular expression for blockquote prefixes
 const blockquotePrefixRe = /^[>\s]*/;
 module.exports.blockquotePrefixRe = blockquotePrefixRe;
@@ -143,7 +139,6 @@ function isBlankLine(line) {
   const startComment = "<!--";
   const endComment = "-->";
   const removeComments = (s) => {
-    // eslint-disable-next-line no-constant-condition
     while (true) {
       const start = s.indexOf(startComment);
       const end = s.indexOf(endComment);
@@ -170,35 +165,6 @@ function isBlankLine(line) {
 }
 module.exports.isBlankLine = isBlankLine;
 
-/**
- * Compare function for Array.prototype.sort for ascending order of numbers.
- *
- * @param {number} a First number.
- * @param {number} b Second number.
- * @returns {number} Positive value if a>b, negative value if b<a, 0 otherwise.
- */
-module.exports.numericSortAscending = function numericSortAscending(a, b) {
-  return a - b;
-};
-
-// Returns true iff the sorted array contains the specified element
-module.exports.includesSorted = function includesSorted(array, element) {
-  let left = 0;
-  let right = array.length - 1;
-  while (left <= right) {
-    // eslint-disable-next-line no-bitwise
-    const mid = (left + right) >> 1;
-    if (array[mid] < element) {
-      left = mid + 1;
-    } else if (array[mid] > element) {
-      right = mid - 1;
-    } else {
-      return true;
-    }
-  }
-  return false;
-};
-
 // Replaces the content of properly-formatted CommonMark comments with "."
 // This preserves the line/column information for the rest of the document
 // https://spec.commonmark.org/0.29/#html-blocks
@@ -289,208 +255,6 @@ module.exports.emphasisOrStrongStyleFor =
     }
   };
 
-/**
- * Return the number of characters of indent for a token.
- *
- * @param {Object} token MarkdownItToken instance.
- * @returns {number} Characters of indent.
- */
-function indentFor(token) {
-  const line = token.line.replace(/^[\s>]*(> |>)/, "");
-  return line.length - line.trimStart().length;
-}
-module.exports.indentFor = indentFor;
-
-// Returns the heading style for a heading token
-module.exports.headingStyleFor = function headingStyleFor(token) {
-  if ((token.map[1] - token.map[0]) === 1) {
-    if (/[^\\]#\s*$/.test(token.line)) {
-      return "atx_closed";
-    }
-    return "atx";
-  }
-  return "setext";
-};
-
-/**
- * Return the string representation of an unordered list marker.
- *
- * @param {Object} token MarkdownItToken instance.
- * @returns {"asterisk" | "dash" | "plus"} String representation.
- */
-module.exports.unorderedListStyleFor = function unorderedListStyleFor(token) {
-  switch (token.markup) {
-    case "-":
-      return "dash";
-    case "+":
-      return "plus";
-    // case "*":
-    default:
-      return "asterisk";
-  }
-};
-
-/**
- * @callback TokenCallback
- * @param {MarkdownItToken} token Current token.
- * @returns {void}
- */
-
-/**
- * Calls the provided function for each matching token.
- *
- * @param {Object} params RuleParams instance.
- * @param {string} type Token type identifier.
- * @param {TokenCallback} handler Callback function.
- * @returns {void}
- */
-function filterTokens(params, type, handler) {
-  for (const token of params.parsers.markdownit.tokens) {
-    if (token.type === type) {
-      handler(token);
-    }
-  }
-}
-module.exports.filterTokens = filterTokens;
-
-/**
- * @typedef {Array} LineMetadata
- */
-
-/**
- * Gets a line metadata array.
- *
- * @param {Object} params RuleParams instance.
- * @returns {LineMetadata} Line metadata.
- */
-function getLineMetadata(params) {
-  const lineMetadata = params.lines.map(
-    (line, index) => [ line, index, false, 0, false, false, false ]
-  );
-  filterTokens(params, "fence", (token) => {
-    lineMetadata[token.map[0]][3] = 1;
-    lineMetadata[token.map[1] - 1][3] = -1;
-    for (let i = token.map[0] + 1; i < token.map[1] - 1; i++) {
-      lineMetadata[i][2] = true;
-    }
-  });
-  filterTokens(params, "code_block", (token) => {
-    for (let i = token.map[0]; i < token.map[1]; i++) {
-      lineMetadata[i][2] = true;
-    }
-  });
-  filterTokens(params, "table_open", (token) => {
-    for (let i = token.map[0]; i < token.map[1]; i++) {
-      lineMetadata[i][4] = true;
-    }
-  });
-  filterTokens(params, "list_item_open", (token) => {
-    let count = 1;
-    for (let i = token.map[0]; i < token.map[1]; i++) {
-      lineMetadata[i][5] = count;
-      count++;
-    }
-  });
-  filterTokens(params, "hr", (token) => {
-    lineMetadata[token.map[0]][6] = true;
-  });
-  return lineMetadata;
-}
-module.exports.getLineMetadata = getLineMetadata;
-
-/**
- * @callback EachLineCallback
- * @param {string} line Line content.
- * @param {number} lineIndex Line index (0-based).
- * @param {boolean} inCode Iff in a code block.
- * @param {number} onFence + if open, - if closed, 0 otherwise.
- * @param {boolean} inTable Iff in a table.
- * @param {boolean} inItem Iff in a list item.
- * @param {boolean} inBreak Iff in semantic break.
- * @returns {void}
- */
-
-/**
- * Calls the provided function for each line.
- *
- * @param {LineMetadata} lineMetadata Line metadata object.
- * @param {EachLineCallback} handler Function taking (line, lineIndex, inCode,
- * onFence, inTable, inItem, inBreak).
- * @returns {void}
- */
-function forEachLine(lineMetadata, handler) {
-  for (const metadata of lineMetadata) {
-    // @ts-ignore
-    handler(...metadata);
-  }
-}
-module.exports.forEachLine = forEachLine;
-
-// Returns (nested) lists as a flat array (in order)
-module.exports.flattenLists = function flattenLists(tokens) {
-  const flattenedLists = [];
-  const stack = [];
-  let current = null;
-  let nesting = 0;
-  const nestingStack = [];
-  let lastWithMap = { "map": [ 0, 1 ] };
-  for (const token of tokens) {
-    if ((token.type === "bullet_list_open") ||
-        (token.type === "ordered_list_open")) {
-      // Save current context and start a new one
-      stack.push(current);
-      current = {
-        "unordered": (token.type === "bullet_list_open"),
-        "parentsUnordered": !current ||
-          (current.unordered && current.parentsUnordered),
-        "open": token,
-        "indent": indentFor(token),
-        "parentIndent": (current && current.indent) || 0,
-        "items": [],
-        "nesting": nesting,
-        "lastLineIndex": -1,
-        "insert": flattenedLists.length
-      };
-      nesting++;
-    } else if ((token.type === "bullet_list_close") ||
-               (token.type === "ordered_list_close")) {
-      // Finalize current context and restore previous
-      current.lastLineIndex = lastWithMap.map[1];
-      flattenedLists.splice(current.insert, 0, current);
-      delete current.insert;
-      current = stack.pop();
-      nesting--;
-    } else if (token.type === "list_item_open") {
-      // Add list item
-      current.items.push(token);
-    } else if (token.type === "blockquote_open") {
-      nestingStack.push(nesting);
-      nesting = 0;
-    } else if (token.type === "blockquote_close") {
-      nesting = nestingStack.pop() || 0;
-    }
-    if (token.map) {
-      // Track last token with map
-      lastWithMap = token;
-    }
-  }
-  return flattenedLists;
-};
-
-// Calls the provided function for each heading's content
-module.exports.forEachHeading = function forEachHeading(params, handler) {
-  let heading = null;
-  for (const token of params.parsers.markdownit.tokens) {
-    if (token.type === "heading_open") {
-      heading = token;
-    } else if (token.type === "heading_close") {
-      heading = null;
-    } else if ((token.type === "inline") && heading) {
-      handler(heading, token.content, token);
-    }
-  }
-};
-
 /**
  * @callback InlineCodeSpanCallback
  * @param {string} code Code content.
@@ -596,8 +360,20 @@ function addError(onError, lineNumber, detail, context, range, fixInfo) {
 }
 module.exports.addError = addError;
 
-// Adds an error object with details conditionally via the onError callback
-module.exports.addErrorDetailIf = function addErrorDetailIf(
+/**
+ * Adds an error object with details conditionally via the onError callback.
+ *
+ * @param {Object} onError RuleOnError instance.
+ * @param {number} lineNumber Line number.
+ * @param {Object} expected Expected value.
+ * @param {Object} actual Actual value.
+ * @param {string} [detail] Error details.
+ * @param {string} [context] Error context.
+ * @param {number[]} [range] Column and length of error.
+ * @param {Object} [fixInfo] RuleOnErrorFixInfo instance.
+ * @returns {void}
+ */
+function addErrorDetailIf(
   onError, lineNumber, expected, actual, detail, context, range, fixInfo) {
   if (expected !== actual) {
     addError(
@@ -609,51 +385,55 @@ module.exports.addErrorDetailIf = function addErrorDetailIf(
       range,
       fixInfo);
   }
-};
+}
+module.exports.addErrorDetailIf = addErrorDetailIf;
 
-// Adds an error object with context via the onError callback
-module.exports.addErrorContext = function addErrorContext(
-  onError, lineNumber, context, left, right, range, fixInfo) {
-  context = ellipsify(context, left, right);
+/**
+ * Adds an error object with context via the onError callback.
+ *
+ * @param {Object} onError RuleOnError instance.
+ * @param {number} lineNumber Line number.
+ * @param {string} context Error context.
+ * @param {boolean} [start] True iff the start of the text is important.
+ * @param {boolean} [end] True iff the end of the text is important.
+ * @param {number[]} [range] Column and length of error.
+ * @param {Object} [fixInfo] RuleOnErrorFixInfo instance.
+ * @returns {void}
+ */
+function addErrorContext(
+  onError, lineNumber, context, start, end, range, fixInfo) {
+  context = ellipsify(context, start, end);
   addError(onError, lineNumber, undefined, context, range, fixInfo);
-};
+}
+module.exports.addErrorContext = addErrorContext;
 
 /**
- * Returns an array of code block and span content ranges.
+ * Adds an error object with context for a construct missing a blank line.
  *
- * @param {Object} params RuleParams instance.
- * @param {Object} lineMetadata Line metadata object.
- * @returns {number[][]} Array of ranges (lineIndex, columnIndex, length).
+ * @param {Object} onError RuleOnError instance.
+ * @param {string[]} lines Lines of Markdown content.
+ * @param {number} lineIndex Line index of line.
+ * @param {number} [lineNumber] Line number for override.
+ * @returns {void}
  */
-module.exports.codeBlockAndSpanRanges = (params, lineMetadata) => {
-  const exclusions = [];
-  // Add code block ranges (excludes fences)
-  forEachLine(lineMetadata, (line, lineIndex, inCode, onFence) => {
-    if (inCode && !onFence) {
-      exclusions.push([ lineIndex, 0, line.length ]);
-    }
-  });
-  // Add code span ranges (excludes ticks)
-  filterTokens(params, "inline", (token) => {
-    if (token.children.some((child) => child.type === "code_inline")) {
-      const tokenLines = params.lines.slice(token.map[0], token.map[1]);
-      forEachInlineCodeSpan(
-        tokenLines.join("\n"),
-        (code, lineIndex, columnIndex) => {
-          const codeLines = code.split(newLineRe);
-          for (const [ i, line ] of codeLines.entries()) {
-            exclusions.push([
-              token.lineNumber - 1 + lineIndex + i,
-              i ? 0 : columnIndex,
-              line.length
-            ]);
-          }
-        }
-      );
+function addErrorContextForLine(onError, lines, lineIndex, lineNumber) {
+  const line = lines[lineIndex];
+  // @ts-ignore
+  const quotePrefix = line.match(blockquotePrefixRe)[0].trimEnd();
+  addErrorContext(
+    onError,
+    lineIndex + 1,
+    line.trim(),
+    undefined,
+    undefined,
+    undefined,
+    {
+      lineNumber,
+      "insertText": `${quotePrefix}\n`
     }
-  });
-  return exclusions;
-};
+  );
+}
+module.exports.addErrorContextForLine = addErrorContextForLine;
 
 /**
  * Determines whether the specified range is within another range.
@@ -673,18 +453,6 @@ const withinAnyRange = (ranges, lineIndex, index, length) => (
 );
 module.exports.withinAnyRange = withinAnyRange;
 
-// Returns a range object for a line by applying a RegExp
-module.exports.rangeFromRegExp = function rangeFromRegExp(line, regexp) {
-  let range = null;
-  const match = line.match(regexp);
-  if (match) {
-    const column = match.index + 1;
-    const length = match[0].length;
-    range = [ column, length ];
-  }
-  return range;
-};
-
 // Determines if the front matter includes a title
 module.exports.frontMatterHasTitle =
   function frontMatterHasTitle(frontMatterLines, frontMatterTitlePattern) {