markdownlint 0.33.0 → 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>.
@@ -2035,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>
@@ -2070,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>
@@ -2100,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 `_`):
@@ -2122,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.
@@ -2135,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>
 

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/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/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/v0.33.0/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/v0.33.0/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/v0.33.0/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",

package/helpers/micromark.cjs

@@ -4,27 +4,18 @@
 
 // @ts-ignore
 const {
-  directive, gfmAutolinkLiteral, gfmFootnote, gfmTable, math, parse,
-  postprocess, preprocess
+  directive, gfmAutolinkLiteral, gfmFootnote, gfmTable, math,
+  parse, postprocess, preprocess
   // @ts-ignore
 } = require("markdownlint-micromark");
 const { newLineRe } = require("./shared.js");
 
 const flatTokensSymbol = Symbol("flat-tokens");
 
-/**
- * Markdown token.
- *
- * @typedef {Object} Token
- * @property {string} type Token type.
- * @property {number} startLine Start line (1-based).
- * @property {number} startColumn Start column (1-based).
- * @property {number} endLine End line (1-based).
- * @property {number} endColumn End column (1-based).
- * @property {string} text Token text.
- * @property {Token[]} children Child tokens.
- * @property {Token | null} parent Parent token.
- */
+/** @typedef {import("markdownlint-micromark").Event} Event */
+/** @typedef {import("markdownlint-micromark").ParseOptions} ParseOptions */
+/** @typedef {import("markdownlint-micromark").TokenType} TokenType */
+/** @typedef {import("../lib/markdownlint.js").MicromarkToken} Token */
 
 /**
  * Returns whether a token is an htmlFlow type containing an HTML comment.
@@ -59,9 +50,9 @@ function isHtmlFlowComment(token) {
  * Parses a Markdown document and returns Micromark events.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [micromarkOptions] Options for micromark.
+ * @param {ParseOptions} [micromarkOptions] Options for micromark.
  * @param {boolean} [referencesDefined] Treat references as defined.
- * @returns {Object[]} Micromark events.
+ * @returns {Event[]} Micromark events.
  */
 function getMicromarkEvents(
   markdown,
@@ -96,7 +87,7 @@ function getMicromarkEvents(
  * Parses a Markdown document and returns (frozen) tokens.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} micromarkOptions Options for micromark.
+ * @param {ParseOptions} micromarkOptions Options for micromark.
  * @param {boolean} referencesDefined Treat references as defined.
  * @param {number} lineDelta Offset to apply to start/end line.
  * @param {Token} [ancestor] Parent of top-most tokens.
@@ -119,7 +110,7 @@ function micromarkParseWithOffset(
   let flatTokens = [];
   /** @type {Token} */
   const root = {
-    "type": "ROOT",
+    "type": "data",
     "startLine": -1,
     "startColumn": -1,
     "endLine": -1,
@@ -130,6 +121,8 @@ function micromarkParseWithOffset(
   };
   const history = [ root ];
   let current = root;
+  // eslint-disable-next-line jsdoc/valid-types
+  /** @type ParseOptions | null */
   let reparseOptions = null;
   let lines = null;
   let skipHtmlFlowChildren = false;
@@ -207,7 +200,7 @@ function micromarkParseWithOffset(
  * Parses a Markdown document and returns (frozen) tokens.
  *
  * @param {string} markdown Markdown document.
- * @param {Object} [micromarkOptions] Options for micromark.
+ * @param {ParseOptions} [micromarkOptions] Options for micromark.
  * @param {boolean} [referencesDefined] Treat references as defined.
  * @returns {Token[]} Micromark tokens (frozen).
  */
@@ -283,7 +276,7 @@ function filterByPredicate(tokens, allowed, transformChildren) {
  * Filter a list of Micromark tokens by type.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {string[]} types Types to allow.
+ * @param {TokenType[]} types Types to allow.
  * @returns {Token[]} Filtered tokens.
  */
 function filterByTypes(tokens, types) {
@@ -316,11 +309,19 @@ function getHeadingLevel(heading) {
   return level;
 }
 
+/**
+ * HTML tag information.
+ *
+ * @typedef {Object} HtmlTagInfo
+ * @property {boolean} close True iff close tag.
+ * @property {string} name Tag name.
+ */
+
 /**
  * Gets information about the tag in an HTML token.
  *
  * @param {Token} token Micromark token.
- * @returns {Object | null} HTML tag information.
+ * @returns {HtmlTagInfo | null} HTML tag information.
  */
 function getHtmlTagInfo(token) {
   const htmlTagNameRe = /^<([^!>][^/\s>]*)/;
@@ -342,7 +343,7 @@ function getHtmlTagInfo(token) {
  * Gets the nearest parent of the specified type for a Micromark token.
  *
  * @param {Token} token Micromark token.
- * @param {string[]} types Types to allow.
+ * @param {TokenType[]} types Types to allow.
  * @returns {Token | null} Parent token.
  */
 function getTokenParentOfType(token, types) {
@@ -358,7 +359,7 @@ function getTokenParentOfType(token, types) {
  * Get the text of the first match from a list of Micromark tokens by type.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {string} type Types to match.
+ * @param {TokenType} type Type to match.
  * @returns {string | null} Text of token.
  */
 function getTokenTextByType(tokens, type) {
@@ -380,8 +381,8 @@ function inHtmlFlow(token) {
  * Determines a list of Micromark tokens matches and returns a subset.
  *
  * @param {Token[]} tokens Micromark tokens.
- * @param {string[]} matchTypes Types to match.
- * @param {string[]} [resultTypes] Types to return.
+ * @param {TokenType[]} matchTypes Types to match.
+ * @param {TokenType[]} [resultTypes] Types to return.
  * @returns {Token[] | null} Matching tokens.
  */
 function matchAndGetTokensByType(tokens, matchTypes, resultTypes) {
@@ -405,13 +406,28 @@ function matchAndGetTokensByType(tokens, matchTypes, resultTypes) {
  * Returns the specified token iff it is of the desired type.
  *
  * @param {Token} token Micromark token candidate.
- * @param {string} type Desired type.
+ * @param {TokenType} type Desired type.
  * @returns {Token | null} Token instance.
  */
 function tokenIfType(token, type) {
   return (token && (token.type === type)) ? token : null;
 }
 
+/**
+ * Set containing token types that do not contain content.
+ *
+ * @type {Set<TokenType>}
+ */
+const nonContentTokens = new Set([
+  "blockQuoteMarker",
+  "blockQuotePrefix",
+  "blockQuotePrefixWhitespace",
+  "lineEnding",
+  "lineEndingBlank",
+  "linePrefix",
+  "listItemIndent"
+]);
+
 module.exports = {
   "parse": micromarkParse,
   filterByPredicate,
@@ -422,6 +438,8 @@ module.exports = {
   getTokenParentOfType,
   getTokenTextByType,
   inHtmlFlow,
+  isHtmlFlowComment,
   matchAndGetTokensByType,
+  nonContentTokens,
   tokenIfType
 };

package/helpers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdownlint-rule-helpers",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "A collection of markdownlint helper functions for custom rules",
   "main": "./helpers.js",
   "exports": "./helpers.js",
@@ -14,7 +14,7 @@
   "bugs": "https://github.com/DavidAnson/markdownlint/issues",
   "funding": "https://github.com/sponsors/DavidAnson",
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "dependencies": {
     "markdownlint-micromark": "0.1.2"