markdownlint 0.28.2 → 0.30.0

package/doc/CustomRules.md

@@ -82,6 +82,8 @@ properties:
       error.
     - `context` is an optional `String` with relevant text surrounding the error
       location.
+    - `information` is an optional (absolute) `URL` of a link to override the
+      same-named value provided by the rule definition. (Uncommon)
     - `range` is an optional `Array` with two `Number` values identifying the
       1-based column and length of the error.
     - `fixInfo` is an optional `Object` with information about how to fix the

package/doc/Rules.md

@@ -806,8 +806,8 @@ Aliases: `blanks-around-headers`, `blanks-around-headings`
 
 Parameters:
 
-- `lines_above`: Blank lines above heading (`integer`, default `1`)
-- `lines_below`: Blank lines below heading (`integer`, default `1`)
+- `lines_above`: Blank lines above heading (`integer|integer[]`, default `1`)
+- `lines_below`: Blank lines below heading (`integer|integer[]`, default `1`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -836,10 +836,16 @@ Some more text
 ```
 
 The `lines_above` and `lines_below` parameters can be used to specify a
-different number of blank lines (including 0) above or below each heading.
+different number of blank lines (including `0`) above or below each heading.
+If the value `-1` is used for either parameter, any number of blank lines is
+allowed. To customize the number of lines above or below each heading level
+individually, specify a `number[]` where values correspond to heading levels
+1-6 (in order).
 
-Note: If `lines_above` or `lines_below` are configured to require more than one
-blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
+Notes: If `lines_above` or `lines_below` are configured to require more than one
+blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. This
+rule checks for *at least* as many blank lines as specified; any extra blank
+lines are ignored.
 
 Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
 will not parse headings that don't have a blank line before, and will parse them
@@ -986,8 +992,7 @@ Aliases: `no-trailing-punctuation`
 
 Parameters:
 
-- `punctuation`: Punctuation characters not allowed at end of headings
-  (`string`, default `.,;:!。，；：！`)
+- `punctuation`: Punctuation characters (`string`, default `.,;:!。，；：！`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -2079,8 +2084,8 @@ Aliases: `emphasis-style`
 
 Parameters:
 
-- `style`: Emphasis style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Emphasis style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -2114,8 +2119,8 @@ Aliases: `strong-style`
 
 Parameters:
 
-- `style`: Strong style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Strong style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -2153,21 +2158,32 @@ This rule is triggered when a link fragment does not match any of the fragments
 that are automatically generated for headings in a document:
 
 ```markdown
-# Title
+# Heading Name
 
 [Link](#fragment)
 ```
 
-To fix this issue, change the link fragment to reference an existing heading:
+To fix this issue, change the link fragment to reference an existing heading's
+generated name (see below):
 
 ```markdown
-# Title
+# 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 `_`):
+
+```markdown
+# Heading Name {#custom-name}
 
-[Link](#title)
+[Link](#custom-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
 
 ```markdown
 <a id="bookmark"></a>

package/doc/md022.md

@@ -6,8 +6,8 @@ Aliases: `blanks-around-headers`, `blanks-around-headings`
 
 Parameters:
 
-- `lines_above`: Blank lines above heading (`integer`, default `1`)
-- `lines_below`: Blank lines below heading (`integer`, default `1`)
+- `lines_above`: Blank lines above heading (`integer|integer[]`, default `1`)
+- `lines_below`: Blank lines below heading (`integer|integer[]`, default `1`)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -36,10 +36,16 @@ Some more text
 ```
 
 The `lines_above` and `lines_below` parameters can be used to specify a
-different number of blank lines (including 0) above or below each heading.
-
-Note: If `lines_above` or `lines_below` are configured to require more than one
-blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
+different number of blank lines (including `0`) above or below each heading.
+If the value `-1` is used for either parameter, any number of blank lines is
+allowed. To customize the number of lines above or below each heading level
+individually, specify a `number[]` where values correspond to heading levels
+1-6 (in order).
+
+Notes: If `lines_above` or `lines_below` are configured to require more than one
+blank line, [MD012/no-multiple-blanks](md012.md) should also be customized. This
+rule checks for *at least* as many blank lines as specified; any extra blank
+lines are ignored.
 
 Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
 will not parse headings that don't have a blank line before, and will parse them

package/doc/md026.md

@@ -6,8 +6,7 @@ Aliases: `no-trailing-punctuation`
 
 Parameters:
 
-- `punctuation`: Punctuation characters not allowed at end of headings
-  (`string`, default `.,;:!。，；：！`)
+- `punctuation`: Punctuation characters (`string`, default `.,;:!。，；：！`)
 
 Fixable: Some violations can be fixed by tooling
 

package/doc/md049.md

@@ -6,8 +6,8 @@ Aliases: `emphasis-style`
 
 Parameters:
 
-- `style`: Emphasis style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Emphasis style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 

package/doc/md050.md

@@ -6,8 +6,8 @@ Aliases: `strong-style`
 
 Parameters:
 
-- `style`: Strong style should be consistent (`string`, default `consistent`,
-  values `asterisk` / `consistent` / `underscore`)
+- `style`: Strong style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `underscore`)
 
 Fixable: Some violations can be fixed by tooling
 

package/doc/md051.md

@@ -10,21 +10,32 @@ This rule is triggered when a link fragment does not match any of the fragments
 that are automatically generated for headings in a document:
 
 ```markdown
-# Title
+# Heading Name
 
 [Link](#fragment)
 ```
 
-To fix this issue, change the link fragment to reference an existing heading:
+To fix this issue, change the link fragment to reference an existing heading's
+generated name (see below):
 
 ```markdown
-# Title
+# Heading Name
 
-[Link](#title)
+[Link](#heading-name)
 ```
 
-Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
-define a fragment:
+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 `_`):
+
+```markdown
+# Heading Name {#custom-name}
+
+[Link](#custom-name)
+```
+
+Alternatively, any HTML tag with an `id` attribute or an `a` tag with a `name`
+attribute can be used to define a fragment:
 
 ```markdown
 <a id="bookmark"></a>

package/helpers/helpers.js

@@ -4,9 +4,7 @@
 
 const micromark = require("./micromark.cjs");
 
-// Regular expression for matching common newline characters
-// See NEWLINES_RE in markdown-it/lib/rules_core/normalize.js
-const newLineRe = /\r\n?|\n/g;
+const { newLineRe } = require("./shared.js");
 module.exports.newLineRe = newLineRe;
 
 // Regular expression for matching common front matter (YAML and TOML)
@@ -20,17 +18,10 @@ 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 expression for matching HTML elements
-const htmlElementRe = /<(([A-Za-z][A-Za-z\d-]*)(?:\s[^`>]*)?)\/?>/g;
-module.exports.htmlElementRe = htmlElementRe;
-
 // Regular expressions for range matching
 module.exports.listItemMarkerRe = /^([\s>]*)(?:[*+-]|\d+[.)])\s+/;
 module.exports.orderedListItemMarkerRe = /^[\s>]*0*(\d+)[.)]/;
 
-// Regular expression for all instances of emphasis markers
-const emphasisMarkersRe = /[_*]/g;
-
 // Regular expression for blockquote prefixes
 const blockquotePrefixRe = /^[>\s]*/;
 module.exports.blockquotePrefixRe = blockquotePrefixRe;
@@ -39,6 +30,16 @@ module.exports.blockquotePrefixRe = blockquotePrefixRe;
 const linkReferenceDefinitionRe = /^ {0,3}\[([^\]]*[^\\])\]:/;
 module.exports.linkReferenceDefinitionRe = linkReferenceDefinitionRe;
 
+// Regular expression for identifying an HTML entity at the end of a line
+module.exports.endOfLineHtmlEntityRe =
+  // eslint-disable-next-line max-len
+  /&(?:#\d+|#[xX][\da-fA-F]+|[a-zA-Z]{2,31}|blk\d{2}|emsp1[34]|frac\d{2}|sup\d|there4);$/;
+
+// Regular expression for identifying a GitHub emoji code at the end of a line
+module.exports.endOfLineGemojiCodeRe =
+  // eslint-disable-next-line max-len
+  /:(?:[abmovx]|[-+]1|100|1234|(?:1st|2nd|3rd)_place_medal|8ball|clock\d{1,4}|e-mail|non-potable_water|o2|t-rex|u5272|u5408|u55b6|u6307|u6708|u6709|u6e80|u7121|u7533|u7981|u7a7a|[a-z]{2,15}2?|[a-z]{1,14}(?:_[a-z\d]{1,16})+):$/;
+
 // All punctuation characters (normal and full-width)
 const allPunctuation = ".,;:!?。，；：！？";
 module.exports.allPunctuation = allPunctuation;
@@ -46,25 +47,82 @@ module.exports.allPunctuation = allPunctuation;
 // All punctuation characters without question mark (normal and full-width)
 module.exports.allPunctuationNoQuestion = allPunctuation.replace(/[?？]/gu, "");
 
-// Returns true iff the input is a number
-module.exports.isNumber = function isNumber(obj) {
+/**
+ * Returns true iff the input is a Number.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is a Number.
+ */
+function isNumber(obj) {
   return typeof obj === "number";
-};
+}
+module.exports.isNumber = isNumber;
 
-// Returns true iff the input is a string
-module.exports.isString = function isString(obj) {
+/**
+ * Returns true iff the input is a String.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is a String.
+ */
+function isString(obj) {
   return typeof obj === "string";
-};
+}
+module.exports.isString = isString;
 
-// Returns true iff the input string is empty
-module.exports.isEmptyString = function isEmptyString(str) {
+/**
+ * Returns true iff the input String is empty.
+ *
+ * @param {string} str String of unknown length.
+ * @returns {boolean} True iff the input String is empty.
+ */
+function isEmptyString(str) {
   return str.length === 0;
-};
+}
+module.exports.isEmptyString = isEmptyString;
 
-// Returns true iff the input is an object
-module.exports.isObject = function isObject(obj) {
-  return (obj !== null) && (typeof obj === "object") && !Array.isArray(obj);
-};
+/**
+ * Returns true iff the input is an Object.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is an Object.
+ */
+function isObject(obj) {
+  return !!obj && (typeof obj === "object") && !Array.isArray(obj);
+}
+module.exports.isObject = isObject;
+
+/**
+ * Returns true iff the input is a URL.
+ *
+ * @param {Object} obj Object of unknown type.
+ * @returns {boolean} True iff obj is a URL.
+ */
+function isUrl(obj) {
+  return !!obj && (Object.getPrototypeOf(obj) === URL.prototype);
+}
+module.exports.isUrl = isUrl;
+
+/**
+ * Clones the input if it is an Array.
+ *
+ * @param {Object} arr Object of unknown type.
+ * @returns {Object} Clone of obj iff obj is an Array.
+ */
+function cloneIfArray(arr) {
+  return Array.isArray(arr) ? [ ...arr ] : arr;
+}
+module.exports.cloneIfArray = cloneIfArray;
+
+/**
+ * Clones the input if it is a URL.
+ *
+ * @param {Object} url Object of unknown type.
+ * @returns {Object} Clone of obj iff obj is a URL.
+ */
+function cloneIfUrl(url) {
+  return isUrl(url) ? new URL(url) : url;
+}
+module.exports.cloneIfUrl = cloneIfUrl;
 
 /**
  * Returns true iff the input line is blank (contains nothing, whitespace, or
@@ -281,25 +339,10 @@ function filterTokens(params, type, handler) {
 }
 module.exports.filterTokens = filterTokens;
 
-/**
- * Returns whether a token is a math block (created by markdown-it-texmath).
- *
- * @param {Object} token MarkdownItToken instance.
- * @returns {boolean} True iff token is a math block.
- */
-function isMathBlock(token) {
-  return (
-    ((token.tag === "$$") || (token.tag === "math")) &&
-    token.type.startsWith("math_block") &&
-    !token.type.endsWith("_end")
-  );
-}
-module.exports.isMathBlock = isMathBlock;
-
 // Get line metadata array
 module.exports.getLineMetadata = function getLineMetadata(params) {
   const lineMetadata = params.lines.map(
-    (line, index) => [ line, index, false, 0, false, false, false, false ]
+    (line, index) => [ line, index, false, 0, false, false, false ]
   );
   filterTokens(params, "fence", (token) => {
     lineMetadata[token.map[0]][3] = 1;
@@ -328,11 +371,6 @@ module.exports.getLineMetadata = function getLineMetadata(params) {
   filterTokens(params, "hr", (token) => {
     lineMetadata[token.map[0]][6] = true;
   });
-  for (const token of params.parsers.markdownit.tokens.filter(isMathBlock)) {
-    for (let i = token.map[0]; i < token.map[1]; i++) {
-      lineMetadata[i][7] = true;
-    }
-  }
   return lineMetadata;
 };
 
@@ -341,7 +379,7 @@ module.exports.getLineMetadata = function getLineMetadata(params) {
  *
  * @param {Object} lineMetadata Line metadata object.
  * @param {Function} handler Function taking (line, lineIndex, inCode, onFence,
- * inTable, inItem, inBreak, inMath).
+ * inTable, inItem, inBreak).
  * @returns {void}
  */
 function forEachLine(lineMetadata, handler) {
@@ -402,23 +440,6 @@ module.exports.flattenLists = function flattenLists(tokens) {
   return flattenedLists;
 };
 
-/**
- * Calls the provided function for each specified inline child token.
- *
- * @param {Object} params RuleParams instance.
- * @param {string} type Token type identifier.
- * @param {Function} handler Callback function.
- * @returns {void}
- */
-function forEachInlineChild(params, type, handler) {
-  filterTokens(params, "inline", (token) => {
-    for (const child of token.children.filter((c) => c.type === type)) {
-      handler(child, token);
-    }
-  });
-}
-module.exports.forEachInlineChild = forEachInlineChild;
-
 // Calls the provided function for each heading's content
 module.exports.forEachHeading = function forEachHeading(params, handler) {
   let heading = null;
@@ -588,51 +609,6 @@ module.exports.codeBlockAndSpanRanges = (params, lineMetadata) => {
   return exclusions;
 };
 
-/**
- * Returns an array of HTML element ranges.
- *
- * @param {Object} params RuleParams instance.
- * @param {Object} lineMetadata Line metadata object.
- * @returns {number[][]} Array of ranges (lineIndex, columnIndex, length).
- */
-module.exports.htmlElementRanges = (params, lineMetadata) => {
-  const exclusions = [];
-  // Match with htmlElementRe
-  forEachLine(lineMetadata, (line, lineIndex, inCode) => {
-    let match = null;
-    // eslint-disable-next-line no-unmodified-loop-condition
-    while (!inCode && ((match = htmlElementRe.exec(line)) !== null)) {
-      exclusions.push([ lineIndex, match.index, match[0].length ]);
-    }
-  });
-  // Match with html_inline
-  forEachInlineChild(params, "html_inline", (token, parent) => {
-    const parentContent = parent.content;
-    let tokenContent = token.content;
-    const parentIndex = parentContent.indexOf(tokenContent);
-    let deltaLines = 0;
-    let indent = 0;
-    for (let i = parentIndex - 1; i >= 0; i--) {
-      if (parentContent[i] === "\n") {
-        deltaLines++;
-      } else if (deltaLines === 0) {
-        indent++;
-      }
-    }
-    let lineIndex = token.lineNumber - 1 + deltaLines;
-    do {
-      const index = tokenContent.indexOf("\n");
-      const length = (index === -1) ? tokenContent.length : index;
-      exclusions.push([ lineIndex, indent, length ]);
-      tokenContent = tokenContent.slice(length + 1);
-      lineIndex++;
-      indent = 0;
-    } while (tokenContent.length > 0);
-  });
-  // Return results
-  return exclusions;
-};
-
 /**
  * Determines whether the specified range is within another range.
  *
@@ -677,129 +653,6 @@ module.exports.frontMatterHasTitle =
       frontMatterLines.some((line) => frontMatterTitleRe.test(line));
   };
 
-/**
- * Calls the provided function for each link.
- *
- * @param {string} line Line of Markdown input.
- * @param {Function} handler Function taking (index, link, text, destination).
- * @returns {void}
- */
-function forEachLink(line, handler) {
-  // Helper to find matching close symbol for link text/destination
-  const findClosingSymbol = (index) => {
-    const begin = line[index];
-    const end = (begin === "[") ? "]" : ")";
-    let nesting = 0;
-    let escaping = false;
-    let pointy = false;
-    for (let i = index + 1; i < line.length; i++) {
-      const current = line[i];
-      if (current === "\\") {
-        escaping = !escaping;
-      } else if (!escaping && (current === begin)) {
-        nesting++;
-      } else if (!escaping && (current === end)) {
-        if (nesting > 0) {
-          nesting--;
-        } else if (!pointy) {
-          // Return index after matching close symbol
-          return i + 1;
-        }
-      } else if ((i === index + 1) && (begin === "(") && (current === "<")) {
-        pointy = true;
-      } else if (!escaping && pointy && current === ">") {
-        pointy = false;
-        nesting = 0;
-      } else {
-        escaping = false;
-      }
-    }
-    // No match found
-    return -1;
-  };
-  // Scan line for unescaped "[" character
-  let escaping = false;
-  for (let i = 0; i < line.length; i++) {
-    const current = line[i];
-    if (current === "\\") {
-      escaping = !escaping;
-    } else if (!escaping && (current === "[")) {
-      // Scan for matching close "]" of link text
-      const textEnd = findClosingSymbol(i);
-      if (textEnd !== -1) {
-        if ((line[textEnd] === "(") || (line[textEnd] === "[")) {
-          // Scan for matching close ")" or "]" of link destination
-          const destEnd = findClosingSymbol(textEnd);
-          if (destEnd !== -1) {
-            // Call handler with link text and destination
-            const link = line.slice(i, destEnd);
-            const text = line.slice(i, textEnd);
-            const dest = line.slice(textEnd, destEnd);
-            handler(i, link, text, dest);
-            i = destEnd;
-          }
-        }
-        if (i < textEnd) {
-          // Call handler with link text only
-          const text = line.slice(i, textEnd);
-          handler(i, text, text);
-          i = textEnd;
-        }
-      }
-    } else {
-      escaping = false;
-    }
-  }
-}
-module.exports.forEachLink = forEachLink;
-
-/**
- * Returns a list of emphasis markers in code spans and links.
- *
- * @param {Object} params RuleParams instance.
- * @returns {number[][]} List of markers.
- */
-function emphasisMarkersInContent(params) {
-  const { lines } = params;
-  const byLine = new Array(lines.length);
-  // Search links
-  for (const [ tokenLineIndex, tokenLine ] of lines.entries()) {
-    const inLine = [];
-    forEachLink(tokenLine, (index, match) => {
-      let markerMatch = null;
-      while ((markerMatch = emphasisMarkersRe.exec(match))) {
-        inLine.push(index + markerMatch.index);
-      }
-    });
-    byLine[tokenLineIndex] = inLine;
-  }
-  // Search code spans
-  filterTokens(params, "inline", (token) => {
-    const { children, lineNumber, map } = token;
-    if (children.some((child) => child.type === "code_inline")) {
-      const tokenLines = lines.slice(map[0], map[1]);
-      forEachInlineCodeSpan(
-        tokenLines.join("\n"),
-        (code, lineIndex, column, tickCount) => {
-          const codeLines = code.split(newLineRe);
-          for (const [ codeLineIndex, codeLine ] of codeLines.entries()) {
-            const byLineIndex = lineNumber - 1 + lineIndex + codeLineIndex;
-            const inLine = byLine[byLineIndex];
-            const codeLineOffset = codeLineIndex ? 0 : column - 1 + tickCount;
-            let match = null;
-            while ((match = emphasisMarkersRe.exec(codeLine))) {
-              inLine.push(codeLineOffset + match.index);
-            }
-            byLine[byLineIndex] = inLine;
-          }
-        }
-      );
-    }
-  });
-  return byLine;
-}
-module.exports.emphasisMarkersInContent = emphasisMarkersInContent;
-
 /**
  * Returns an object with information about reference links and images.
  *
@@ -1080,66 +933,6 @@ function applyFixes(input, errors) {
 }
 module.exports.applyFixes = applyFixes;
 
-/**
- * Gets the range and fixInfo values for reporting an error if the expected
- * text is found on the specified line.
- *
- * @param {string[]} lines Lines of Markdown content.
- * @param {number} lineIndex Line index to check.
- * @param {string} search Text to search for.
- * @param {string} replace Text to replace with.
- * @param {number} [instance] Instance on the line (1-based).
- * @returns {Object} Range and fixInfo wrapper.
- */
-module.exports.getRangeAndFixInfoIfFound =
-  (lines, lineIndex, search, replace, instance = 1) => {
-    let range = null;
-    let fixInfo = null;
-    let searchIndex = -1;
-    while (instance > 0) {
-      searchIndex = lines[lineIndex].indexOf(search, searchIndex + 1);
-      instance--;
-    }
-    if (searchIndex !== -1) {
-      const column = searchIndex + 1;
-      const length = search.length;
-      range = [ column, length ];
-      fixInfo = {
-        "editColumn": column,
-        "deleteCount": length,
-        "insertText": replace
-      };
-    }
-    return {
-      range,
-      fixInfo
-    };
-  };
-
-/**
- * Gets the next (subsequent) child token if it is of the expected type.
- *
- * @param {Object} parentToken Parent token.
- * @param {Object} childToken Child token basis.
- * @param {string} nextType Token type of next token.
- * @param {string} nextNextType Token type of next-next token.
- * @returns {Object} Next token.
- */
-function getNextChildToken(parentToken, childToken, nextType, nextNextType) {
-  const { children } = parentToken;
-  const index = children.indexOf(childToken);
-  if (
-    (index !== -1) &&
-    (children.length > index + 2) &&
-    (children[index + 1].type === nextType) &&
-    (children[index + 2].type === nextNextType)
-  ) {
-    return children[index + 1];
-  }
-  return null;
-}
-module.exports.getNextChildToken = getNextChildToken;
-
 /**
  * Expands a path with a tilde to an absolute path.
  *