markdownlint 0.39.0 → 0.41.0

package/doc/md035.md

@@ -8,8 +8,8 @@ Parameters:
 
 - `style`: Horizontal rule style (`string`, default `consistent`)
 
-This rule is triggered when inconsistent styles of horizontal rules are used
-in the document:
+This rule is triggered when inconsistent styles of horizontal rules (also known
+as "thematic breaks") are used in a document:
 
 ```markdown
 ---
@@ -23,15 +23,22 @@ in the document:
 ****
 ```
 
-To fix this, use the same horizontal rule everywhere:
+To fix this, use the same horizontal rule syntax everywhere:
 
 ```markdown
 ---
 
+---
+
 ---
 ```
 
-The configured style can ensure all horizontal rules use a specific string or it
-can ensure all horizontal rules match the first horizontal rule (`consistent`).
+The `style` parameter's default value `consistent` ensures all horizontal rules
+in a document match the first horizontal rule in that document. To enforce a
+specific pattern of characters, set the `style` parameter to that string (e.g.,
+`"* * *"`).
+
+Note: In order to be recognized as a horizontal rule, a line must contain three
+or more matching `-`, `_`, or `*` characters with optional space between.
 
 Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md041.md

@@ -59,6 +59,6 @@ in cases where an `h1` is added externally.
 Rationale: The top-level heading often acts as the title of a document. More
 information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
 
-[HTML]: https://en.wikipedia.org/wiki/HTML
+[HTML]: https://wikipedia.org/wiki/HTML
 [RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
-[YAML]: https://en.wikipedia.org/wiki/YAML
+[YAML]: https://wikipedia.org/wiki/YAML

package/doc/md042.md

@@ -20,6 +20,10 @@ Empty fragments will trigger this rule:
 
 ```markdown
 [an empty fragment](#)
+
+[an empty link definition][empty]
+
+[empty]: #
 ```
 
 But non-empty fragments will not:
@@ -28,5 +32,7 @@ But non-empty fragments will not:
 [a valid fragment](#fragment)
 ```
 
+Empty link definitions
+
 Rationale: Empty links do not lead anywhere and therefore don't function as
 links.

package/doc/md045.md

@@ -45,4 +45,4 @@ content of an image for people who may not be able to see it.
 [aria-hidden]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
 [phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
 [w3c]: https://www.w3.org/WAI/alt/
-[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute
+[wikipedia]: https://wikipedia.org/wiki/Alt_attribute

package/doc/md051.md

@@ -100,13 +100,18 @@ This makes it easy to link directly to different sections within a document.
 However, section links change if headings are renamed or removed. This rule
 helps identify broken section links within a document.
 
-Section links are **not** part of the CommonMark specification. This rule
-enforces the [GitHub heading algorithm][github-heading-algorithm] which is:
-convert heading to lowercase, remove punctuation, convert spaces to dashes,
-append an incrementing integer as needed for uniqueness.
+Note: Section links are **not** part of the CommonMark specification; this rule
+enforces the [GitHub heading algorithm][github-heading-algorithm]:
 
+1. Convert text to lowercase
+2. Remove punctuation characters
+3. Convert spaces to dashes
+4. Append an incrementing integer (as needed for uniqueness)
+5. [URI-encode][encodeURIComponent] the result
+
+[encodeURIComponent]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent
 [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
+[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
 [html-top-fragment]: https://html.spec.whatwg.org/multipage/browsing-the-web.html#scrolling-to-a-fragment
 [RegEx]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions

package/doc/md060.md

@@ -6,15 +6,18 @@ Aliases: `table-column-style`
 
 Parameters:
 
+- `aligned_delimiter`: Aligned delimiter columns (`boolean`, default `false`)
 - `style`: Table column style (`string`, default `any`, values `aligned` /
   `any` / `compact` / `tight`)
 
-This rule is triggered when the column separators of a
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when the column separator pipe characters (`|`) of a
 [GitHub Flavored Markdown table][gfm-table-060] are used inconsistently.
 
-This rule recognizes three table column styles based on popular use:
+This rule recognizes three table column styles based on popular use.
 
-Style `aligned` looks the most like a table:
+Style `aligned` ensures pipe characters are vertically aligned:
 
 ```markdown
 | Character | Meaning |
@@ -23,7 +26,16 @@ Style `aligned` looks the most like a table:
 | N         | No      |
 ```
 
-Style `compact` uses a single space to pad cell content:
+The `aligned` style ignores cell content, so the following is also valid:
+
+```markdown
+| Character | Meaning |
+|-----------|---------|
+|     Y     |     Yes |
+|     N     |      No |
+```
+
+Style `compact` avoids extra padding with a single space around cell content:
 
 ```markdown
 | Character | Meaning |
@@ -32,7 +44,7 @@ Style `compact` uses a single space to pad cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding for cell content:
+Style `tight` uses no padding at all for cell content:
 
 ```markdown
 |Character|Meaning|
@@ -42,16 +54,61 @@ Style `tight` uses no padding for cell content:
 ```
 
 When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
-every table must match the corresponding pattern and errors will be reported for
-any violations. By default, or when the `any` style is used, each table is
-analyzed to see if it satisfies any supported style. If so, no errors are
-reported. If not, errors are be reported for whichever style would produce the
-*fewest* errors (i.e., whichever style is the closest match).
+every table must match the corresponding pattern and any violations will be
+reported. By default, or when the `any` style is used, each table is analyzed to
+see if it satisfies any supported style. If so, no violations are reported. If
+not, violations are be reported for whichever style would produce the *fewest*
+issues (i.e., whichever style is the closest match).
+
+Setting the `aligned_delimiter` parameter to `true` requires pipe characters in
+the delimiter row to align with those in the header row. This can be used with
+`compact` and `tight` tables to make the header text more obvious. (It's already
+required for tables with style `aligned`.)
+
+Style `compact` with `aligned_delimiter`:
+
+```markdown
+| Character | Meaning |
+| --------- | ------- |
+| Y | Yes |
+| N | No |
+```
+
+Style `tight` with `aligned_delimiter`:
+
+```markdown
+|Character|Meaning|
+|---------|-------|
+|Y|Yes|
+|N|No|
+```
+
+Violations for styles `compact` and `tight` are simple/independent and can be
+fixed automatically. However, fixing even single violations for style `aligned`
+may require modifying the entire table, and therefore are not automatic:
+
+```markdown
+|Alpha |Delta|
+|------|-----|
+|Charlie|Beta|
+```
+
+**Note**: This rule does not require leading/trailing pipe characters, so this
+is also a valid table for style `compact`:
+
+```markdown
+Character | Meaning
+--- | ---
+Y | Yes
+N | No
+```
 
-Note: Pipe alignment for the `aligned` style is based on character count, so
-wide characters and multi-character encodings can produce unexpected results.
-The following table is correctly aligned based on character count, though some
-editors render the emoji wider:
+**Note**: Pipe alignment for the `aligned` style is based on visual appearance
+and not character count. Because editors typically render [emoji][emoji] and
+[CJK characters][cjk-characters] at *twice* the width of
+[Latin characters][latin-script], this rule takes that into account for tables
+using the `aligned` style. The following table is correctly formatted and will
+appear aligned in most editors and monospaced fonts:
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable extended-ascii -->
@@ -59,12 +116,15 @@ editors render the emoji wider:
 ```markdown
 | Response | Emoji |
 | -------- | ----- |
-| Yes      | ✅     |
-| No       | ❎     |
+| Yes      | ✅    |
+| No       | ❎    |
 ```
 
 <!-- markdownlint-restore -->
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
+[cjk-characters]: https://wikipedia.org/wiki/CJK_characters
+[emoji]: https://wikipedia.org/wiki/Emoji
 [gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
+[latin-script]: https://wikipedia.org/wiki/Latin_script

package/helpers/README.md

@@ -22,8 +22,8 @@ be useful to custom rule authors and may avoid duplicating code.
 *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.39.0/doc/CustomRules.md
-[jsdoc]: https://en.m.wikipedia.org/wiki/JSDoc
-[markdown]: https://en.wikipedia.org/wiki/Markdown
+[custom-rules]: https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/CustomRules.md
+[jsdoc]: https://wikipedia.org/wiki/JSDoc
+[markdown]: https://wikipedia.org/wiki/Markdown
 [markdownlint]: https://github.com/DavidAnson/markdownlint
-[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.39.0/doc/Rules.md
+[rules]: https://github.com/DavidAnson/markdownlint/blob/v0.41.0/doc/Rules.md

package/helpers/helpers.cjs

@@ -4,9 +4,9 @@
 
 const micromark = require("./micromark-helpers.cjs");
 
-const { newLineRe, nextLinesRe } = require("./shared.cjs");
+const { newlineRe, nextLinesRe } = require("./shared.cjs");
 
-module.exports.newLineRe = newLineRe;
+module.exports.newLineRe = newlineRe;
 module.exports.nextLinesRe = nextLinesRe;
 
 /** @typedef {import("../lib/exports.mjs").RuleOnError} RuleOnError */
@@ -311,7 +311,7 @@ module.exports.addErrorDetailIf = addErrorDetailIf;
  */
 function addErrorContext(onError, lineNumber, context, start, end, range, fixInfo) {
   // Normalize new line characters so Linux and Windows trim consistently
-  context = ellipsify(context.replace(newLineRe, "\n"), start, end);
+  context = ellipsify(context.replace(newlineRe, "\n"), start, end);
   addError(onError, lineNumber, undefined, context, range, fixInfo);
 }
 module.exports.addErrorContext = addErrorContext;
@@ -438,59 +438,59 @@ function getReferenceLinkImageData(tokens) {
       case "gfmFootnoteDefinitionLabelString":
         labelPrefix = "^";
       case "definitionLabelString": // eslint-disable-line no-fallthrough
-        {
-          // definitions and definitionLineIndices
-          const reference = normalizeReference(`${labelPrefix}${token.text}`);
-          if (definitions.has(reference)) {
-            duplicateDefinitions.push([ reference, token.startLine - 1 ]);
-          } else {
-            const parent =
-              micromark.getParentOfType(token, [ "definition" ]);
-            const destinationString = parent &&
-              micromark.getDescendantsByType(parent, [ "definitionDestination", "definitionDestinationRaw", "definitionDestinationString" ])[0]?.text;
-            definitions.set(
-              reference,
-              [ token.startLine - 1, destinationString || "" ]
-            );
-          }
+      {
+        // definitions and definitionLineIndices
+        const reference = normalizeReference(`${labelPrefix}${token.text}`);
+        if (definitions.has(reference)) {
+          duplicateDefinitions.push([ reference, token.startLine - 1 ]);
+        } else {
+          const parent =
+            micromark.getParentOfType(token, [ "definition" ]);
+          const destinationString = parent &&
+            micromark.getDescendantsByType(parent, [ "definitionDestination", "definitionDestinationRaw", "definitionDestinationString" ])[0]?.text;
+          definitions.set(
+            reference,
+            [ token.startLine - 1, destinationString || "" ]
+          );
         }
         break;
+      }
       case "gfmFootnoteCall":
       case "image":
       case "link":
-        {
-          // Identify if shortcut or full/collapsed
-          let isShortcut = (token.children.length === 1);
-          const isFullOrCollapsed = (token.children.length === 2) && !token.children.some((t) => t.type === "resource");
-          const [ labelText ] = micromark.getDescendantsByType(token, [ "label", "labelText" ]);
-          const [ referenceString ] = micromark.getDescendantsByType(token, [ "reference", "referenceString" ]);
-          let label = getText(labelText);
-          // Identify if footnote
-          if (!isShortcut && !isFullOrCollapsed) {
-            const [ footnoteCallMarker, footnoteCallString ] = token.children.filter(
-              (t) => [ "gfmFootnoteCallMarker", "gfmFootnoteCallString" ].includes(t.type)
-            );
-            if (footnoteCallMarker && footnoteCallString) {
-              label = `${footnoteCallMarker.text}${footnoteCallString.text}`;
-              isShortcut = true;
-            }
-          }
-          // Track link (handle shortcuts separately due to ambiguity in "text [text] text")
-          if (isShortcut || isFullOrCollapsed) {
-            addReferenceToDictionary(token, getText(referenceString) || label, isShortcut);
+      {
+        // Identify if shortcut or full/collapsed
+        let isShortcut = (token.children.length === 1);
+        const isFullOrCollapsed = (token.children.length === 2) && !token.children.some((t) => t.type === "resource");
+        const [ labelText ] = micromark.getDescendantsByType(token, [ "label", "labelText" ]);
+        const [ referenceString ] = micromark.getDescendantsByType(token, [ "reference", "referenceString" ]);
+        let label = getText(labelText);
+        // Identify if footnote
+        if (!isShortcut && !isFullOrCollapsed) {
+          const [ footnoteCallMarker, footnoteCallString ] = token.children.filter(
+            (t) => [ "gfmFootnoteCallMarker", "gfmFootnoteCallString" ].includes(t.type)
+          );
+          if (footnoteCallMarker && footnoteCallString) {
+            label = `${footnoteCallMarker.text}${footnoteCallString.text}`;
+            isShortcut = true;
           }
         }
+        // Track link (handle shortcuts separately due to ambiguity in "text [text] text")
+        if (isShortcut || isFullOrCollapsed) {
+          addReferenceToDictionary(token, getText(referenceString) || label, isShortcut);
+        }
         break;
+      }
       case "undefinedReferenceCollapsed":
       case "undefinedReferenceFull":
       case "undefinedReferenceShortcut":
-        {
-          const undefinedReference = micromark.getDescendantsByType(token, [ "undefinedReference" ])[0];
-          const label = undefinedReference.children.map((t) => t.text).join("");
-          const isShortcut = (token.type === "undefinedReferenceShortcut");
-          addReferenceToDictionary(token, label, isShortcut);
-        }
+      {
+        const undefinedReference = micromark.getDescendantsByType(token, [ "undefinedReference" ])[0];
+        const label = undefinedReference.children.map((t) => t.text).join("");
+        const isShortcut = (token.type === "undefinedReferenceShortcut");
+        addReferenceToDictionary(token, label, isShortcut);
         break;
+      }
     }
   }
   return {
@@ -514,7 +514,7 @@ function getPreferredLineEnding(input, os) {
   let cr = 0;
   let lf = 0;
   let crlf = 0;
-  const endings = input.match(newLineRe) || [];
+  const endings = input.match(newlineRe) || [];
   for (const ending of endings) {
     // eslint-disable-next-line default-case
     switch (ending) {
@@ -630,7 +630,6 @@ function convertLintErrorsVersion2To0(errors) {
 function copyAndTransformResults(results, transform) {
   /** @type {Object.<string, LintErrors>} */
   const newResults = {};
-  Object.defineProperty(newResults, "toString", { "value": results.toString });
   for (const key of Object.keys(results)) {
     const arr = results[key].map((r) => ({ ...r }));
     newResults[key] = transform(arr);

package/helpers/micromark-helpers.cjs

@@ -2,7 +2,7 @@
 
 "use strict";
 
-const { flatTokensSymbol, htmlFlowSymbol, newLineRe } = require("./shared.cjs");
+const { flatTokensSymbol, htmlFlowSymbol, newlineRe } = require("./shared.cjs");
 
 // eslint-disable-next-line jsdoc/valid-types
 /** @typedef {import("micromark-util-types", { with: { "resolution-mode": "import" } }).TokenType} TokenType */
@@ -152,7 +152,6 @@ function getBlockQuotePrefixText(tokens, lineNumber, count = 1) {
     .map((prefix) => prefix.text)
     .join("")
     .trimEnd()
-    // eslint-disable-next-line unicorn/prefer-spread
     .concat("\n")
     .repeat(count);
 };
@@ -224,7 +223,7 @@ function getHeadingText(heading) {
     .flatMap((descendant) => descendant.children.filter((child) => child.type !== "htmlText"))
     .map((data) => data.text)
     .join("")
-    .replace(newLineRe, " ");
+    .replace(newlineRe, " ");
 }
 
 /**
@@ -285,7 +284,9 @@ function isDocfxTab(heading) {
   // See https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#tabs
   if (heading?.type === "atxHeading") {
     const headingTexts = getDescendantsByType(heading, [ "atxHeadingText" ]);
+    // eslint-disable-next-line unicorn/better-dom-traversing
     if ((headingTexts.length === 1) && (headingTexts[0].children.length === 1) && (headingTexts[0].children[0].type === "link")) {
+      // eslint-disable-next-line unicorn/better-dom-traversing
       const resourceDestinationStrings = filterByTypes(headingTexts[0].children[0].children, [ "resourceDestinationString" ]);
       return (resourceDestinationStrings.length === 1) && docfxTabSyntaxRe.test(resourceDestinationStrings[0].text);
     }

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.cjs",
   "exports": {
@@ -17,7 +17,7 @@
   "bugs": "https://github.com/DavidAnson/markdownlint/issues",
   "funding": "https://github.com/sponsors/DavidAnson",
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "keywords": [
     "markdownlint",

package/helpers/shared.cjs

@@ -10,7 +10,7 @@ module.exports.htmlFlowSymbol = Symbol("html-flow");
 
 // Regular expression for matching common newline characters
 // See NEWLINES_RE in markdown-it/lib/rules_core/normalize.js
-module.exports.newLineRe = /\r\n?|\n/g;
+module.exports.newlineRe = /\r\n?|\n/g;
 
 // Regular expression for matching next lines
 module.exports.nextLinesRe = /[\r\n][\s\S]*$/;