markdownlint 0.30.0 → 0.31.1

package/doc/Rules.md

@@ -354,13 +354,11 @@ line with the start of the content of the parent list when a single space is
 used after the list marker. Indenting by 4 spaces is consistent with code blocks
 and simpler for editors to implement. Additionally, this can be a compatibility
 issue for other Markdown parsers, which require 4-space indents. More
-information: [Markdown Style Guide][markdown-style-guide] and [Marked app\
-support][marked-app-support].
+information: [Markdown Style Guide][markdown-style-guide].
 
 Note: See [Prettier.md](Prettier.md) for compatibility information.
 
 [markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists
-[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting
 
 <a name="md009"></a>
 
@@ -1349,31 +1347,48 @@ followed by a blank line:
 
 ```markdown
 Some text
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
-Some text
+1. List item
+2. List item
+***
 ```
 
-To fix this, ensure that all lists have a blank line both before and after
-(except where the block is at the beginning or end of the document):
+In the first case above, text immediately precedes the unordered list. In the
+second case above, a thematic break immediately follows the ordered list. To fix
+violations of this rule, ensure that all lists have a blank line both before and
+after (except when the list is at the very beginning or end of the document):
 
 ```markdown
 Some text
 
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
+1. List item
+2. List item
 
-Some text
+***
 ```
 
-Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
-not parse lists that don't have blank lines before and after them.
+Note that the following case is **not** a violation of this rule:
+
+```markdown
+1. List item
+   More item 1
+2. List item
+More item 2
+```
+
+Although it is not indented, the text "More item 2" is referred to as a
+[lazy continuation line][lazy-continuation] and considered part of the second
+list item.
+
+Rationale: In addition to aesthetic reasons, some parsers, including kramdown,
+will not parse lists that don't have blank lines before and after them.
+
+[lazy-continuation]: https://spec.commonmark.org/0.30/#lazy-continuation-line
 
 <a name="md033"></a>
 
@@ -2216,6 +2231,10 @@ Tags: `images`, `links`
 
 Aliases: `reference-links-images`
 
+Parameters:
+
+- `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
+
 Links and images in Markdown can provide the link destination or image source
 at the time of use or can define it elsewhere and use a label for reference.
 The reference format is convenient for keeping paragraph text clutter-free
@@ -2236,13 +2255,16 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+A link or image renders correctly when the corresponding label is defined, but
+displays as text with brackets when the label is not present. By default, this
+rule warns of undefined labels for "full" and "collapsed" reference syntax but
+not for "shortcut" syntax because it is ambiguous.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+The text `[example]` could be a shortcut link or the text "example" in brackets,
+so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
+the `include_shortcut` parameter to `true`. Note that doing so produces warnings
+for *all* text in the document that *could* be a shortcut. If bracketed text is
+intentional, brackets can be escaped with the `\` character: `\[example\]`.
 
 <a name="md053"></a>
 

package/doc/md007.md

@@ -46,10 +46,8 @@ line with the start of the content of the parent list when a single space is
 used after the list marker. Indenting by 4 spaces is consistent with code blocks
 and simpler for editors to implement. Additionally, this can be a compatibility
 issue for other Markdown parsers, which require 4-space indents. More
-information: [Markdown Style Guide][markdown-style-guide] and [Marked app\
-support][marked-app-support].
+information: [Markdown Style Guide][markdown-style-guide].
 
 Note: See [Prettier.md](Prettier.md) for compatibility information.
 
 [markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists
-[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting

package/doc/md032.md

@@ -11,28 +11,45 @@ followed by a blank line:
 
 ```markdown
 Some text
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
-Some text
+1. List item
+2. List item
+***
 ```
 
-To fix this, ensure that all lists have a blank line both before and after
-(except where the block is at the beginning or end of the document):
+In the first case above, text immediately precedes the unordered list. In the
+second case above, a thematic break immediately follows the ordered list. To fix
+violations of this rule, ensure that all lists have a blank line both before and
+after (except when the list is at the very beginning or end of the document):
 
 ```markdown
 Some text
 
-* Some
-* List
+* List item
+* List item
 
-1. Some
-2. List
+1. List item
+2. List item
 
-Some text
+***
+```
+
+Note that the following case is **not** a violation of this rule:
+
+```markdown
+1. List item
+   More item 1
+2. List item
+More item 2
 ```
 
-Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
-not parse lists that don't have blank lines before and after them.
+Although it is not indented, the text "More item 2" is referred to as a
+[lazy continuation line][lazy-continuation] and considered part of the second
+list item.
+
+Rationale: In addition to aesthetic reasons, some parsers, including kramdown,
+will not parse lists that don't have blank lines before and after them.
+
+[lazy-continuation]: https://spec.commonmark.org/0.30/#lazy-continuation-line

package/doc/md052.md

@@ -4,6 +4,10 @@ Tags: `images`, `links`
 
 Aliases: `reference-links-images`
 
+Parameters:
+
+- `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
+
 Links and images in Markdown can provide the link destination or image source
 at the time of use or can define it elsewhere and use a label for reference.
 The reference format is convenient for keeping paragraph text clutter-free
@@ -24,10 +28,13 @@ Shortcut: ![image]
 [image]: https://example.com/image
 ```
 
-A link or image renders correctly when a corresponding label is defined, but
-the text displays with brackets if the label is not present. This rule warns
-of undefined labels for "full" and "collapsed" reference syntax.
+A link or image renders correctly when the corresponding label is defined, but
+displays as text with brackets when the label is not present. By default, this
+rule warns of undefined labels for "full" and "collapsed" reference syntax but
+not for "shortcut" syntax because it is ambiguous.
 
-> "Shortcut" syntax is ambiguous and a missing label will not generate an
-  error. For example, `[shortcut]` could be a shortcut link or the text
-  "shortcut" in brackets.
+The text `[example]` could be a shortcut link or the text "example" in brackets,
+so "shortcut" syntax is ignored by default. To include "shortcut" syntax, set
+the `include_shortcut` parameter to `true`. Note that doing so produces warnings
+for *all* text in the document that *could* be a shortcut. If bracketed text is
+intentional, brackets can be escaped with the `\` character: `\[example\]`.

package/helpers/helpers.js

@@ -322,12 +322,18 @@ module.exports.unorderedListStyleFor = function unorderedListStyleFor(token) {
   }
 };
 
+/**
+ * @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 {Function} handler Callback function.
+ * @param {TokenCallback} handler Callback function.
  * @returns {void}
  */
 function filterTokens(params, type, handler) {
@@ -339,8 +345,17 @@ function filterTokens(params, type, handler) {
 }
 module.exports.filterTokens = filterTokens;
 
-// Get line metadata array
-module.exports.getLineMetadata = function getLineMetadata(params) {
+/**
+ * @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 ]
   );
@@ -372,18 +387,32 @@ module.exports.getLineMetadata = function getLineMetadata(params) {
     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 {Object} lineMetadata Line metadata object.
- * @param {Function} handler Function taking (line, lineIndex, inCode, onFence,
- * inTable, inItem, inBreak).
+ * @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);
   }
 }
@@ -454,12 +483,21 @@ module.exports.forEachHeading = function forEachHeading(params, handler) {
   }
 };
 
+/**
+ * @callback InlineCodeSpanCallback
+ * @param {string} code Code content.
+ * @param {number} lineIndex Line index (0-based).
+ * @param {number} columnIndex Column index (0-based).
+ * @param {number} ticks Count of backticks.
+ * @returns {void}
+ */
+
 /**
  * Calls the provided function for each inline code span's content.
  *
  * @param {string} input Markdown content.
- * @param {Function} handler Callback function taking (code, lineIndex,
- * columnIndex, ticks).
+ * @param {InlineCodeSpanCallback} handler Callback function taking (code,
+ * lineIndex, columnIndex, ticks).
  * @returns {void}
  */
 function forEachInlineCodeSpan(input, handler) {
@@ -945,3 +983,23 @@ function expandTildePath(file, os) {
   return homedir ? file.replace(/^~($|\/|\\)/, `${homedir}$1`) : file;
 }
 module.exports.expandTildePath = expandTildePath;
+
+// Copied from markdownlint.js to avoid TypeScript compiler import() issue.
+/**
+ * @typedef {Object} MarkdownItToken
+ * @property {string[][]} attrs HTML attributes.
+ * @property {boolean} block Block-level token.
+ * @property {MarkdownItToken[]} children Child nodes.
+ * @property {string} content Tag contents.
+ * @property {boolean} hidden Ignore element.
+ * @property {string} info Fence info.
+ * @property {number} level Nesting level.
+ * @property {number[]} map Beginning/ending line numbers.
+ * @property {string} markup Markup text.
+ * @property {Object} meta Arbitrary data.
+ * @property {number} nesting Level change.
+ * @property {string} tag HTML tag name.
+ * @property {string} type Token type.
+ * @property {number} lineNumber Line number (1-based).
+ * @property {string} line Line content.
+ */

package/helpers/micromark.cjs

@@ -10,6 +10,8 @@ const {
 } = require("markdownlint-micromark");
 const { newLineRe } = require("./shared.js");
 
+const flatTokensSymbol = Symbol("flat-tokens");
+
 /**
  * Markdown token.
  *
@@ -21,9 +23,32 @@ const { newLineRe } = require("./shared.js");
  * @property {number} endColumn End column (1-based).
  * @property {string} text Token text.
  * @property {Token[]} children Child tokens.
- * @property {Token[]} [htmlFlowChildren] Child tokens for htmlFlow.
  */
 
+/**
+ * Returns whether a token is an htmlFlow type containing an HTML comment.
+ *
+ * @param {Token} token Micromark token.
+ * @returns {boolean} True iff token is htmlFlow containing a comment.
+ */
+function isHtmlFlowComment(token) {
+  const { text, type } = token;
+  if (
+    (type === "htmlFlow") &&
+    text.startsWith("<!--") &&
+    text.endsWith("-->")
+  ) {
+    const comment = text.slice(4, -3);
+    return (
+      !comment.startsWith(">") &&
+      !comment.startsWith("->") &&
+      !comment.endsWith("-") &&
+      !comment.includes("--")
+    );
+  }
+  return false;
+}
+
 /**
  * Parses a Markdown document and returns Micromark events.
  *
@@ -82,19 +107,21 @@ function micromarkParseWithOffset(
 
   // Create Token objects
   const document = [];
+  let flatTokens = [];
   let current = {
     "children": document
   };
   const history = [ current ];
   let reparseOptions = null;
   let lines = null;
+  let skipHtmlFlowChildren = false;
   for (const event of events) {
     const [ kind, token, context ] = event;
     const { type, start, end } = token;
     const { "column": startColumn, "line": startLine } = start;
     const { "column": endColumn, "line": endLine } = end;
     const text = context.sliceSerialize(token);
-    if (kind === "enter") {
+    if ((kind === "enter") && !skipHtmlFlowChildren) {
       const previous = current;
       history.push(previous);
       current = {
@@ -106,7 +133,11 @@ function micromarkParseWithOffset(
         text,
         "children": []
       };
-      if (current.type === "htmlFlow") {
+      previous.children.push(current);
+      flatTokens.push(current);
+      // @ts-ignore
+      if ((current.type === "htmlFlow") && !isHtmlFlowComment(current)) {
+        skipHtmlFlowChildren = true;
         if (!reparseOptions || !lines) {
           reparseOptions = {
             ...micromarkOptions,
@@ -123,23 +154,32 @@ function micromarkParseWithOffset(
         const reparseMarkdown = lines
           .slice(current.startLine - 1, current.endLine)
           .join("\n");
-        current.htmlFlowChildren = micromarkParseWithOffset(
+        const tokens = micromarkParseWithOffset(
           reparseMarkdown,
           reparseOptions,
           referencesDefined,
           current.startLine - 1
         );
+        current.children = tokens;
+        // Avoid stack overflow of Array.push(...spread)
+        // eslint-disable-next-line unicorn/prefer-spread
+        flatTokens = flatTokens.concat(tokens[flatTokensSymbol]);
       }
-      previous.children.push(current);
     } else if (kind === "exit") {
-      Object.freeze(current.children);
-      Object.freeze(current);
-      // @ts-ignore
-      current = history.pop();
+      if (type === "htmlFlow") {
+        skipHtmlFlowChildren = false;
+      }
+      if (!skipHtmlFlowChildren) {
+        Object.freeze(current.children);
+        Object.freeze(current);
+        // @ts-ignore
+        current = history.pop();
+      }
     }
   }
 
   // Return document
+  Object.defineProperty(document, flatTokensSymbol, { "value": flatTokens });
   Object.freeze(document);
   return document;
 }
@@ -166,83 +206,73 @@ function micromarkParse(
 }
 
 /**
- * Filter a list of Micromark tokens by predicate.
- *
- * @param {Token[]} tokens Micromark tokens.
- * @param {Function} allowed Allowed token predicate.
- * @param {Function} [transformChildren] Transform children predicate.
- * @returns {Token[]} Filtered tokens.
+ * @callback AllowedPredicate
+ * @param {Token} token Micromark token.
+ * @returns {boolean} True iff allowed.
  */
-function filterByPredicate(tokens, allowed, transformChildren) {
-  const result = [];
-  const pending = [ ...tokens ];
-  let token = null;
-  while ((token = pending.shift())) {
-    if (allowed(token)) {
-      result.push(token);
-    }
-    if (token.children.length > 0) {
-      const transformed =
-        transformChildren ? transformChildren(token) : token.children;
-      pending.unshift(...transformed);
-    }
-  }
-  return result;
-}
 
 /**
- * Filter a list of Micromark tokens by type.
- *
- * @param {Token[]} tokens Micromark tokens.
- * @param {string[]} allowed Types to allow.
- * @returns {Token[]} Filtered tokens.
+ * @callback TransformPredicate
+ * @param {Token} token Micromark token.
+ * @returns {Token[]} Child tokens.
  */
-function filterByTypes(tokens, allowed) {
-  return filterByPredicate(
-    tokens,
-    (token) => allowed.includes(token.type)
-  );
-}
 
 /**
- * Filter a list of Micromark tokens for HTML tokens.
+ * Filter a list of Micromark tokens by predicate.
  *
  * @param {Token[]} tokens Micromark tokens.
+ * @param {AllowedPredicate} allowed Allowed token predicate.
+ * @param {TransformPredicate} [transformChildren] Transform predicate.
  * @returns {Token[]} Filtered tokens.
  */
-function filterByHtmlTokens(tokens) {
+function filterByPredicate(tokens, allowed, transformChildren) {
   const result = [];
-  const pending = [ tokens ];
-  let current = null;
-  while ((current = pending.shift())) {
-    for (const token of filterByTypes(current, [ "htmlFlow", "htmlText" ])) {
-      if (token.type === "htmlText") {
+  const queue = [
+    {
+      "array": tokens,
+      "index": 0
+    }
+  ];
+  while (queue.length > 0) {
+    const current = queue[queue.length - 1];
+    const { array, index } = current;
+    if (index < array.length) {
+      const token = array[current.index++];
+      if (allowed(token)) {
         result.push(token);
-      } else {
-        // token.type === "htmlFlow"
-        // @ts-ignore
-        pending.push(token.htmlFlowChildren);
       }
+      const { children } = token;
+      if (children.length > 0) {
+        const transformed =
+          transformChildren ? transformChildren(token) : children;
+        queue.push(
+          {
+            "array": transformed,
+            "index": 0
+          }
+        );
+      }
+    } else {
+      queue.pop();
     }
   }
   return result;
 }
 
 /**
- * Returns a list of all nested child tokens.
+ * Filter a list of Micromark tokens by type.
  *
- * @param {Token} parent Micromark token.
- * @returns {Token[]} Flattened children.
+ * @param {Token[]} tokens Micromark tokens.
+ * @param {string[]} allowed Types to allow.
+ * @returns {Token[]} Filtered tokens.
  */
-function flattenedChildren(parent) {
-  const result = [];
-  const pending = [ ...parent.children ];
-  let token = null;
-  while ((token = pending.shift())) {
-    result.push(token);
-    pending.unshift(...token.children);
+function filterByTypes(tokens, allowed) {
+  const predicate = (token) => allowed.includes(token.type);
+  const flatTokens = tokens[flatTokensSymbol];
+  if (flatTokens) {
+    return flatTokens.filter(predicate);
   }
-  return result;
+  return filterByPredicate(tokens, predicate);
 }
 
 /**
@@ -338,10 +368,8 @@ function tokenIfType(token, type) {
 
 module.exports = {
   "parse": micromarkParse,
-  filterByHtmlTokens,
   filterByPredicate,
   filterByTypes,
-  flattenedChildren,
   getHeadingLevel,
   getHtmlTagInfo,
   getMicromarkEvents,

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.js",
   "exports": "./helpers.js",
@@ -9,7 +9,7 @@
   "homepage": "https://github.com/DavidAnson/markdownlint",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DavidAnson/markdownlint.git"
+    "url": "git+https://github.com/DavidAnson/markdownlint.git"
   },
   "bugs": "https://github.com/DavidAnson/markdownlint/issues",
   "engines": {

package/lib/constants.js

@@ -11,4 +11,4 @@ module.exports.fixableRuleNames = [
   "MD044", "MD047", "MD049", "MD050", "MD051", "MD053"
 ];
 module.exports.homepage = "https://github.com/DavidAnson/markdownlint";
-module.exports.version = "0.30.0";
+module.exports.version = "0.31.1";

package/lib/markdownlint.d.ts

@@ -8,7 +8,7 @@ export = markdownlint;
  */
 declare function markdownlint(options: Options | null, callback: LintCallback): void;
 declare namespace markdownlint {
-    export { markdownlintSync as sync, readConfig, readConfigSync, getVersion, promises, RuleFunction, RuleParams, MarkdownItToken, RuleOnError, RuleOnErrorInfo, RuleOnErrorFixInfo, Rule, Options, Plugin, ToStringCallback, LintResults, LintError, FixInfo, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback, ResolveConfigExtendsCallback };
+    export { markdownlintSync as sync, readConfig, readConfigSync, getVersion, promises, RuleFunction, RuleParams, MarkdownItToken, RuleOnError, RuleOnErrorInfo, RuleOnErrorFixInfo, Rule, Options, Plugin, ToStringCallback, LintResults, LintError, FixInfo, LintContentCallback, LintCallback, Configuration, RuleConfiguration, ConfigurationParser, ReadConfigCallback, ResolveConfigExtendsCallback };
 }
 /**
  * Configuration options.
@@ -64,7 +64,7 @@ type Options = {
 /**
  * Called with the result of the lint function.
  */
-type LintCallback = (err: Error | null, results?: LintResults) => void;
+type LintCallback = (error: Error | null, results?: LintResults) => void;
 /**
  * Lint specified Markdown files synchronously.
  *
@@ -353,6 +353,10 @@ type FixInfo = {
      */
     insertText?: string;
 };
+/**
+ * Called with the result of linting a string or document.
+ */
+type LintContentCallback = (error: Error | null, result?: LintError[]) => void;
 /**
  * Configuration object for linting rules. For a detailed schema, see
  * {@link  ../schema/markdownlint-config-schema.json}.