markdownlint 0.37.4 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.38.0
+
+- Add MD059/descriptive-link-text
+- Improve MD025/MD027/MD036/MD038/MD041/MD043/MD045/MD051/MD052
+- `markdown-it` parser no longer a production dependency (breaking change)
+  - Add `markdownItFactory` option, remove `markdownItPlugins` option
+- Remove support for end-of-life Node version 18
+- Improve performance
+- Update dependencies
+
 ## 0.37.4
 
 - Stop using `module.createRequire`, export `resolveModule`

package/CONTRIBUTING.md

@@ -14,8 +14,8 @@ Match the coding style of the files you edit. Although everyone has their own
 preferences and opinions, a pull request is not the right forum to debate them.
 
 Do not add new [`dependencies` to `package.json`][dependencies]. The Markdown
-parsers [`markdown-it`][markdown-it] and [`micromark`][micromark] are the
-project's only dependencies.
+parser [`micromark`][micromark] (and its extensions) is this project's only
+dependency.
 
 Package versions for `dependencies` and `devDependencies` should be specified
 exactly (also known as "pinning"). The short explanation is that doing otherwise
@@ -85,7 +85,6 @@ Thank you!
 [custom-rules]: doc/CustomRules.md
 [dependencies]: https://docs.npmjs.com/files/package.json#dependencies
 [example-com]: https://en.wikipedia.org/wiki/Example.com
-[markdown-it]: https://www.npmjs.com/package/markdown-it
 [micromark]: https://www.npmjs.com/package/micromark
 [new-rule]: https://github.com/DavidAnson/markdownlint/labels/new%20rule
 [npm-scripts]: https://docs.npmjs.com/misc/scripts

package/README.md

@@ -24,7 +24,7 @@ for Markdown files. It was inspired by - and heavily influenced by - Mark
 Harrison's [markdownlint][markdownlint-ruby] for Ruby. The initial rules, rule
 documentation, and test cases came from that project.
 
-`markdownlint` uses the [`micromark`][micromark] parser and honors the
+`markdownlint` uses the [`micromark` parser][micromark] and honors the
 [CommonMark][commonmark] specification for Markdown. It additionally supports
 popular [GitHub Flavored Markdown (GFM)][gfm] syntax like autolinks and tables
 as well as directives, footnotes, and math syntax - all implemented by
@@ -55,6 +55,7 @@ as well as directives, footnotes, and math syntax - all implemented by
   - [vscode-markdownlint extension for VS Code][vscode-markdownlint]
   - [Sublime Text markdownlint for Sublime Text][sublimelinter]
   - [coc-markdownlint extension for Vim/Neovim][coc]
+  - [flymake-markdownlint-cli2 extension for Emacs][emacs-flymake]
 - Tooling
   - [eslint-plugin-markdownlint for the ESLint analyzer][eslint-plugin]
   - [grunt-markdownlint for the Grunt task runner][grunt-markdownlint]
@@ -65,6 +66,7 @@ as well as directives, footnotes, and math syntax - all implemented by
 
 [cake]: https://github.com/cake-contrib/Cake.Markdownlint
 [coc]: https://github.com/fannheyward/coc-markdownlint
+[emacs-flymake]: https://github.com/ewilderj/flymake-markdownlint-cli2
 [eslint-plugin]: https://github.com/paweldrozd/eslint-plugin-markdownlint
 [grunt-markdownlint]: https://github.com/sagiegurari/grunt-markdownlint
 [markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli
@@ -146,6 +148,7 @@ playground for learning and exploring.
 - **[MD055](doc/md055.md)** *table-pipe-style* - Table pipe style
 - **[MD056](doc/md056.md)** *table-column-count* - Table column count
 - **[MD058](doc/md058.md)** *blanks-around-tables* - Tables should be surrounded by blank lines
+- **[MD059](doc/md059.md)** *descriptive-link-text* - Link text should be descriptive
 
 <!-- markdownlint-restore -->
 
@@ -165,7 +168,7 @@ To implement your own rules, refer to [CustomRules.md](doc/CustomRules.md).
 Tags group related rules and can be used to enable/disable multiple
 rules at once.
 
-- **`accessibility`** - `MD045`
+- **`accessibility`** - `MD045`, `MD059`
 - **`atx`** - `MD018`, `MD019`
 - **`atx_closed`** - `MD020`, `MD021`
 - **`blank_lines`** - `MD012`, `MD022`, `MD031`, `MD032`, `MD047`
@@ -183,7 +186,7 @@ rules at once.
 - **`language`** - `MD040`
 - **`line_length`** - `MD013`
 - **`links`** - `MD011`, `MD034`, `MD039`, `MD042`, `MD051`, `MD052`, `MD053`,
-  `MD054`
+  `MD054`, `MD059`
 - **`ol`** - `MD029`, `MD030`, `MD032`
 - **`spaces`** - `MD018`, `MD019`, `MD020`, `MD021`, `MD023`
 - **`spelling`** - `MD044`
@@ -418,9 +421,9 @@ object.
 See [ValidatingConfiguration.md](schema/ValidatingConfiguration.md) for ways to
 use the JSON Schema to validate configuration.
 
-For more advanced scenarios, styles can reference and extend other styles.
-The `readConfig` and `readConfigSync` functions can be used to read such
-styles.
+For more advanced scenarios, styles can reference and build upon other styles
+via the `extends` keyword and a file path or (installed) package name. The
+`readConfig` function can be used to read such aggregate styles from code.
 
 For example, assuming a `base.json` configuration file:
 
@@ -567,28 +570,43 @@ This setting can be useful in the presence of (custom) rules that encounter
 unexpected syntax and fail. By enabling this option, the linting process
 is allowed to continue and report any violations that were found.
 
-##### options.markdownItPlugins
+##### options.markdownItFactory
 
-Type: `Array` of `Array` of `Function` and plugin parameters
+Type: `Function` returning an instance of a [`markdown-it` parser][markdown-it]
 
-Specifies additional [`markdown-it` plugins][markdown-it-plugin] to use when
-parsing input. Plugins can be used to support additional syntax and features for
-advanced scenarios. *Deprecated.*
+Provides a factory function for creating instances of the `markdown-it` parser.
 
-[markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
+Previous versions of the `markdownlint` library declared `markdown-it` as a
+direct dependency. This function makes it possible to avoid that dependency
+entirely. In cases where `markdown-it` is needed, the caller is responsible for
+declaring the dependency and returning an instance from this factory. If any
+[`markdown-it` plugins][markdown-it-plugin] are needed, they should be `use`d by
+the caller before returning the `markdown-it` instance.
+
+For compatibility with previous versions of `markdownlint`, this function should
+be similar to:
+
+```javascript
+import markdownIt from "markdown-it";
+const markdownItFactory = () => markdownIt({ "html": true });
+```
 
-Each item in the top-level `Array` should be of the form:
+When an asynchronous implementation of `lint` is being invoked (e.g., via
+`markdownlint/async` or `markdownlint/promise`), this function can return a
+`Promise` in order to defer the import of `markdown-it`:
 
 ```javascript
-[ require("markdown-it-plugin"), plugin_param_0, plugin_param_1, ... ]
+const markdownItFactory = () => import("markdown-it").then((module) => module.default({ "html": true }));
 ```
 
-> Note that `markdown-it` plugins are only called when the `markdown-it` parser
-> is invoked. None of the built-in rules use the `markdown-it` parser, so
-> `markdown-it` plugins will only be invoked when one or more
-> [custom rules][custom-rules] that use the `markdown-it` parser are present.
+> Note that this function is only invoked when a `markdown-it` parser is
+> needed. None of the built-in rules use the `markdown-it` parser, so it is only
+> invoked when one or more [custom rules][custom-rules] are present that use the
+> `markdown-it` parser.
 
 [custom-rules]: #custom-rules
+[markdown-it]: https://github.com/markdown-it/markdown-it
+[markdown-it-plugin]: https://www.npmjs.com/search?q=keywords:markdown-it-plugin
 
 ##### options.noInlineConfig
 
@@ -660,9 +678,9 @@ uses rule aliases (ex: `no-hard-tabs`) instead of names (ex: `MD010`).
 ### Config
 
 The `options.config` configuration object is simple and can be stored in a file
-for readability and easy reuse. The `readConfig` and `readConfigSync` functions
-load configuration settings and support the `extends` keyword for referencing
-other files (see above).
+for readability and easy reuse. The `readConfig` function loads configuration
+settings and supports the `extends` keyword for referencing files or packages
+(see above).
 
 By default, configuration files are parsed as JSON (and named
 `.markdownlint.json`). Custom parsers can be provided to handle other formats

package/doc/Rules.md

@@ -943,6 +943,10 @@ Tags: `blockquote`, `indentation`, `whitespace`
 
 Aliases: `no-multiple-space-blockquote`
 
+Parameters:
+
+- `list_items`: Include list items (`boolean`, default `true`)
+
 Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when blockquotes have more than one space after the
@@ -960,6 +964,10 @@ To fix, remove any extraneous space:
 > indentation.
 ```
 
+Inferring intended list indentation within a blockquote can be challenging;
+setting the `list_items` parameter to `false` disables this rule for ordered
+and unordered list items.
+
 Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md028"></a>
@@ -1528,38 +1536,50 @@ Aliases: `no-space-in-code`
 
 Fixable: Some violations can be fixed by tooling
 
-This rule is triggered for code span elements that have spaces adjacent to the
-backticks:
+This rule is triggered for code spans containing content with unnecessary space
+next to the beginning or ending backticks:
 
 ```markdown
 `some text `
 
 ` some text`
+
+`   some text   `
 ```
 
-To fix this, remove any spaces adjacent to the backticks:
+To fix this, remove the extra space characters from the beginning and ending:
 
 ```markdown
 `some text`
 ```
 
-Note: A single leading and trailing space is allowed by the specification and
-automatically trimmed (in order to allow for code spans that embed backticks):
+Note: A single leading *and* trailing space is allowed by the specification and
+trimmed by the parser to support code spans that begin or end with a backtick:
 
 ```markdown
 `` `backticks` ``
+
+`` backtick` ``
+```
+
+Note: When single-space padding is present in the input, it will be preserved
+(even if unnecessary):
+
+```markdown
+` code `
 ```
 
-Note: A single leading or trailing space is allowed if used to separate code
-span markers from an embedded backtick (though the space is not trimmed):
+Note: Code spans containing only spaces are allowed by the specification and are
+also preserved:
 
 ```markdown
-`` ` embedded backtick``
+` `
+
+`   `
 ```
 
-Rationale: Violations of this rule are usually unintentional and may lead to
-improperly-rendered content. If spaces beside backticks are intentional, this
-rule can be disabled for that line or file.
+Rationale: Violations of this rule are usually unintentional and can lead to
+improperly-rendered content.
 
 <a name="md039"></a>
 
@@ -1650,48 +1670,63 @@ Aliases: `first-line-h1`, `first-line-heading`
 
 Parameters:
 
+- `allow_preamble`: Allow content before first heading (`boolean`, default
+  `false`)
 - `front_matter_title`: RegExp for matching title in front matter (`string`,
   default `^\s*title\s*[:=]`)
 - `level`: Heading level (`integer`, default `1`)
 
 This rule is intended to ensure documents have a title and is triggered when
-the first line in the file isn't a top-level (h1) heading:
+the first line in a document is not a top-level ([HTML][HTML] `h1`) heading:
 
 ```markdown
-This is a file without a heading
+This is a document without a heading
 ```
 
-To fix this, add a top-level heading to the beginning of the file:
+To fix this, add a top-level heading to the beginning of the document:
 
 ```markdown
-# File with heading
+# Document Heading
 
-This is a file with a top-level heading
+This is a document with a top-level heading
 ```
 
 Because it is common for projects on GitHub to use an image for the heading of
-`README.md` and that is not well-supported by Markdown, HTML headings are also
-permitted by this rule. For example:
+`README.md` and that pattern is not well-supported by Markdown, HTML headings
+are also permitted by this rule. For example:
 
 ```markdown
 <h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
 
-This is a file with a top-level HTML heading
+This is a document with a top-level HTML heading
 ```
 
-Note: The `level` parameter can be used to change the top-level (ex: to h2) in
-cases where an h1 is added externally.
+In some cases, a document's title heading may be preceded by text like a table
+of contents. This is not ideal for accessibility, but can be allowed by setting
+the `allow_preamble` parameter to `true`.
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
-contains a `title` property (commonly used with blog posts), this rule will not
-report a violation. To use a different property name in the front matter,
-specify the text of a regular expression via the `front_matter_title` parameter.
-To disable the use of front matter by this rule, specify `""` for
-`front_matter_title`.
+```markdown
+This is a document with preamble text
+
+# Document Heading
+```
+
+If [YAML][YAML] front matter is present and contains a `title` property
+(commonly used with blog posts), this rule will not report a violation. To use a
+different property name in the front matter, specify the text of a [regular
+expression][RegExp] via the `front_matter_title` parameter. To disable the use
+of front matter by this rule, specify `""` for `front_matter_title`.
+
+The `level` parameter can be used to change the top-level heading (ex: to `h2`)
+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
+[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
+[YAML]: https://en.wikipedia.org/wiki/YAML
+
 <a name="md042"></a>
 
 ## `MD042` - No empty links
@@ -1747,7 +1782,7 @@ structure for a set of files.
 To require exactly the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail
 ```
@@ -1756,7 +1791,7 @@ Set the `headings` parameter to:
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "### Detail"
 ]
@@ -1765,7 +1800,7 @@ Set the `headings` parameter to:
 To allow optional headings as with the following structure:
 
 ```markdown
-# Head
+# Heading
 ## Item
 ### Detail (optional)
 ## Foot
@@ -1778,7 +1813,7 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 
 ```json
 [
-    "# Head",
+    "# Heading",
     "## Item",
     "*",
     "## Foot",
@@ -1786,6 +1821,24 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 ]
 ```
 
+To allow a single required heading to vary as with a project name:
+
+```markdown
+# Project Name
+## Description
+## Examples
+```
+
+Use the special value `"?"` meaning "exactly one unspecified heading":
+
+```json
+[
+    "?",
+    "## Description",
+    "## Examples"
+]
+```
+
 When an error is detected, this rule outputs the line number of the first
 problematic heading (otherwise, it outputs the last line number of the file).
 
@@ -1855,7 +1908,7 @@ Tags: `accessibility`, `images`
 
 Aliases: `no-alt-text`
 
-This rule is triggered when an image is missing alternate text (alt text)
+This rule reports a violation when an image is missing alternate text (alt text)
 information.
 
 Alternate text is commonly specified inline as:
@@ -1880,12 +1933,20 @@ Or with HTML as:
 <img src="image.jpg" alt="Alternate text" />
 ```
 
+Note: If the [HTML `aria-hidden` attribute][aria-hidden] is used to hide the
+image from assistive technology, this rule does not report a violation:
+
+```html
+<img src="image.jpg" aria-hidden="true" />
+```
+
 Guidance for writing alternate text is available from the [W3C][w3c],
 [Wikipedia][wikipedia], and [other locations][phase2technology].
 
 Rationale: Alternate text is important for accessibility and describes the
 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
@@ -2103,6 +2164,8 @@ Aliases: `link-fragments`
 Parameters:
 
 - `ignore_case`: Ignore case of fragments (`boolean`, default `false`)
+- `ignored_pattern`: Pattern for ignoring additional fragments (`string`,
+  default ``)
 
 Fixable: Some violations can be fixed by tooling
 
@@ -2160,6 +2223,13 @@ 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.
 
+[HTML links to `#top` scroll to the top of a document][html-top-fragment]. This
+rule allows that syntax (using lower-case for consistency):
+
+```markdown
+[Link](#top)
+```
+
 This rule also recognizes the custom fragment syntax used by GitHub to highlight
 [specific content in a document][github-linking-to-content].
 
@@ -2175,6 +2245,12 @@ And this link to content starting within line 19 running into line 21:
 [Link](#L19C5-L21C11)
 ```
 
+Some Markdown generators dynamically create and insert headings when building
+documents, for example by combining a fixed prefix like `figure-` and an
+incrementing numeric counter. To ignore such generated fragments, set the
+`ignored_pattern` [regular expression][RegEx] parameter to a pattern that
+matches (e.g., `^figure-`).
+
 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.
@@ -2189,6 +2265,8 @@ 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
+[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
 
 <a name="md052"></a>
 
@@ -2200,6 +2278,7 @@ Aliases: `reference-links-images`
 
 Parameters:
 
+- `ignored_labels`: Ignored link labels (`string[]`, default `["x"]`)
 - `shortcut_syntax`: Include shortcut syntax (`boolean`, default `false`)
 
 Links and images in Markdown can provide the link destination or image source
@@ -2233,6 +2312,17 @@ 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\]`.
 
+If there are link labels that are deliberately unreferenced, they can be ignored
+by setting the `ignored_labels` parameter to the list of strings to ignore. The
+default value of this parameter ignores the checkbox syntax used by
+[GitHub Flavored Markdown task list items][gfm-tasklist]:
+
+```markdown
+- [x] Checked task list item
+```
+
+[gfm-tasklist]: https://github.github.com/gfm/#task-list-items-extension-
+
 <a name="md053"></a>
 
 ## `MD053` - Link and image reference definitions should be needed
@@ -2266,9 +2356,9 @@ reference has the corresponding label. The "full", "collapsed", and "shortcut"
 formats are all supported.
 
 If there are reference definitions that are deliberately unreferenced, they can
-be ignored by setting the `ignored_definitions` parameter. The default value of
-this parameter ignores the following convention for adding non-HTML comments to
-Markdown:
+be ignored by setting the `ignored_definitions` parameter to the list of strings
+to ignore. The default value of this parameter ignores the following convention
+for adding non-HTML comments to Markdown:
 
 ```markdown
 [//]: # (This behaves like a comment)
@@ -2526,6 +2616,39 @@ Some text
 Rationale: In addition to aesthetic reasons, some parsers will incorrectly parse
 tables that don't have blank lines before and after them.
 
+<a name="md059"></a>
+
+## `MD059` - Link text should be descriptive
+
+Tags: `accessibility`, `links`
+
+Aliases: `descriptive-link-text`
+
+Parameters:
+
+- `prohibited_texts`: Prohibited link texts (`string[]`, default `["click
+  here","here","link","more"]`)
+
+This rule is triggered when a link has generic text like `[click here](...)` or
+`[link](...)`.
+
+Link text should be descriptive and communicate the purpose of the link (e.g.,
+`[Download the budget document](...)` or `[CommonMark Specification](...)`).
+This is especially important for screen readers which sometimes present links
+without context.
+
+By default, this rule prohibits a small number of common English words/phrases.
+To customize that list of words/phrases, set the `prohibited_texts` parameter to
+an `Array` of `string`s.
+
+Note: For languages other than English, use the `prohibited_texts` parameter to
+customize the list for that language. It is *not* a goal for this rule to have
+translations for every language.
+
+Note: This rule checks Markdown links; HTML links are ignored.
+
+More information: <https://webaim.org/techniques/hypertext/>
+
 <!-- markdownlint-configure-file {
   "no-inline-html": {
     "allowed_elements": [

package/doc/md027.md

@@ -4,6 +4,10 @@ Tags: `blockquote`, `indentation`, `whitespace`
 
 Aliases: `no-multiple-space-blockquote`
 
+Parameters:
+
+- `list_items`: Include list items (`boolean`, default `true`)
+
 Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when blockquotes have more than one space after the
@@ -21,4 +25,8 @@ To fix, remove any extraneous space:
 > indentation.
 ```
 
+Inferring intended list indentation within a blockquote can be challenging;
+setting the `list_items` parameter to `false` disables this rule for ordered
+and unordered list items.
+
 Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md038.md

@@ -6,35 +6,47 @@ Aliases: `no-space-in-code`
 
 Fixable: Some violations can be fixed by tooling
 
-This rule is triggered for code span elements that have spaces adjacent to the
-backticks:
+This rule is triggered for code spans containing content with unnecessary space
+next to the beginning or ending backticks:
 
 ```markdown
 `some text `
 
 ` some text`
+
+`   some text   `
 ```
 
-To fix this, remove any spaces adjacent to the backticks:
+To fix this, remove the extra space characters from the beginning and ending:
 
 ```markdown
 `some text`
 ```
 
-Note: A single leading and trailing space is allowed by the specification and
-automatically trimmed (in order to allow for code spans that embed backticks):
+Note: A single leading *and* trailing space is allowed by the specification and
+trimmed by the parser to support code spans that begin or end with a backtick:
 
 ```markdown
 `` `backticks` ``
+
+`` backtick` ``
 ```
 
-Note: A single leading or trailing space is allowed if used to separate code
-span markers from an embedded backtick (though the space is not trimmed):
+Note: When single-space padding is present in the input, it will be preserved
+(even if unnecessary):
 
 ```markdown
-`` ` embedded backtick``
+` code `
+```
+
+Note: Code spans containing only spaces are allowed by the specification and are
+also preserved:
+
+```markdown
+` `
+
+`   `
 ```
 
-Rationale: Violations of this rule are usually unintentional and may lead to
-improperly-rendered content. If spaces beside backticks are intentional, this
-rule can be disabled for that line or file.
+Rationale: Violations of this rule are usually unintentional and can lead to
+improperly-rendered content.