markdownlint 0.24.0 → 0.26.0

package/doc/CustomRules.md

@@ -41,7 +41,8 @@ A rule is implemented as an `Object` with one optional and four required propert
 - `description` is a required `String` value that describes the rule in output messages.
 - `information` is an optional (absolute) `URL` of a link to more information about the rule.
 - `tags` is a required `Array` of `String` values that groups related rules for easier customization.
-- `function` is a required synchronous `Function` that implements the rule and is passed two parameters:
+- `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 parameters:
   - `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` objects](https://markdown-it.github.io/markdown-it/#Token)
@@ -51,7 +52,7 @@ A rule is implemented as an `Object` with one optional and four required propert
     - `config` is an `Object` corresponding to the rule's entry in `options.config` (if present).
   - `onError` is a function that takes a single `Object` parameter with one required and four optional properties:
     - `lineNumber` is a required `Number` specifying the 1-based line number of the error.
-    - `details` is an optional `String` with information about what caused the error.
+    - `detail` is an optional `String` with information about what caused the error.
     - `context` is an optional `String` with relevant text surrounding the error location.
     - `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 error (all properties are optional, but
@@ -66,15 +67,25 @@ A rule is implemented as an `Object` with one optional and four required propert
 The collection of helper functions shared by the built-in rules is available for use by custom rules in the
 [markdownlint-rule-helpers package](https://www.npmjs.com/package/markdownlint-rule-helpers).
 
+### Asynchronous Rules
+
+If a rule needs to perform asynchronous operations (such as fetching a network resource), it can specify the value `true` for its `asynchronous` property.
+Asynchronous rules should return a `Promise` from their `function` implementation that is resolved when the rule completes.
+(The value passed to `resolve(...)` is ignored.)
+Linting violations from asynchronous rules are reported via the `onError` function just like for synchronous rules.
+
+**Note**: Asynchronous rules cannot be referenced in a synchronous calling context (i.e., `markdownlint.sync(...)`).
+Attempting to do so throws an exception.
+
 ## Examples
 
 - [Simple rules used by the project's test cases](../test/rules)
 - [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 Microsoft/vscode-docs-authoring repository](https://github.com/microsoft/vscode-docs-authoring/tree/master/packages/docs-linting/markdownlint-custom-rules)
+- [Custom rules from the Microsoft/vscode-docs-authoring repository](https://github.com/microsoft/vscode-docs-authoring/tree/main/packages/docs-linting/markdownlint-custom-rules)
 - [Custom rules from the axibase/docs-util repository](https://github.com/axibase/docs-util/tree/master/linting-rules)
-- [Custom rules from the webhintio/hint repository](https://github.com/webhintio/hint/blob/master/scripts/lint-markdown.js)
+- [Custom rules from the webhintio/hint repository](https://github.com/webhintio/hint/blob/main/scripts/lint-markdown.js)
 
 ## References
 

package/doc/Rules.md

@@ -13,7 +13,7 @@ Tags: headings, headers
 
 Aliases: heading-increment, header-increment
 
-This rule is triggered when you skip heading levels in a markdown document, for
+This rule is triggered when you skip heading levels in a Markdown document, for
 example:
 
 ```markdown
@@ -292,7 +292,11 @@ Tags: bullet, ul, indentation
 
 Aliases: ul-indent
 
-Parameters: indent, start_indented (number; default 2, boolean; default false)
+<!-- markdownlint-disable line-length -->
+
+Parameters: indent, start_indented, start_indent (number; default 2, boolean; default false, number; defaults to indent)
+
+<!-- markdownlint-restore -->
 
 Fixable: Most violations can be fixed by tooling
 
@@ -319,13 +323,15 @@ rule).
 
 The `start_indented` parameter allows the first level of lists to be indented by
 the configured number of spaces rather than starting at zero (the inverse of
-MD006).
+MD006). The `start_indent` parameter allows the first level of lists to be indented
+by a different number of spaces than the rest (ignored when `start_indented` is not
+set).
 
 Rationale: Indenting by 2 spaces allows the content of a nested list to be in
 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 multi-markdown parsers, which require 4-space indents. More information:
+issue for other Markdown parsers, which require 4-space indents. More information:
 <https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists>
 and <http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>.
 
@@ -390,7 +396,7 @@ Tags: whitespace, hard_tab
 
 Aliases: no-hard-tabs
 
-Parameters: code_blocks, spaces_per_tab (boolean; default true, number; default 1)
+Parameters: code_blocks, ignore_code_languages, spaces_per_tab (boolean; default true, array of string; default empty, number; default 1)
 
 Fixable: Most violations can be fixed by tooling
 
@@ -418,12 +424,20 @@ Some text
     * Spaces used to indent the list item instead
 ```
 
-You have the option to exclude this rule for code blocks. To do so, set the
-`code_blocks` parameter to `false`. Code blocks are included by default since
-handling of tabs by tools is often inconsistent (ex: using 4 vs. 8 spaces).
+You have the option to exclude this rule for code blocks and spans. To do so,
+set the `code_blocks` parameter to `false`. Code blocks and spans are included
+by default since handling of tabs by Markdown tools can be inconsistent (e.g.,
+using 4 vs. 8 spaces).
+
+When code blocks are scanned (e.g., by default or if `code_blocks` is `true`),
+the `ignore_code_languages` parameter can be set to a list of languages that
+should be ignored (i.e., hard tabs will be allowed, though not required). This
+makes it easier for documents to include code for languages that require hard
+tabs.
 
-If you would like the fixer to change tabs to x spaces, then configure the `spaces_per_tab`
-parameter to the number x. The default value would be 1.
+By default, violations of this rule are fixed by replacing the tab with 1 space
+character. To use a different number of spaces, set the `spaces_per_tab`
+parameter to the desired value.
 
 Rationale: Hard tabs are often rendered inconsistently by different editors and
 can be harder to work with than spaces.
@@ -853,7 +867,7 @@ in changelogs):
 ### Features
 ```
 
-Rationale: Some markdown parsers generate anchors for headings based on the
+Rationale: Some Markdown parsers generate anchors for headings based on the
 heading name; headings with the same content can cause problems with that.
 
 <a name="md025"></a>
@@ -1008,7 +1022,7 @@ blockquote symbol at the beginning of the blank line:
 > This is the same blockquote.
 ```
 
-Rationale: Some markdown parsers will treat two blockquotes separated by one
+Rationale: Some Markdown parsers will treat two blockquotes separated by one
 or more blank lines as the same blockquote, while others will treat them as
 separate blockquotes.
 
@@ -1289,13 +1303,13 @@ Aliases: no-inline-html
 
 Parameters: allowed_elements (array of string; default empty)
 
-This rule is triggered whenever raw HTML is used in a markdown document:
+This rule is triggered whenever raw HTML is used in a Markdown document:
 
 ```markdown
 <h1>Inline HTML heading</h1>
 ```
 
-To fix this, use 'pure' markdown instead of including raw HTML:
+To fix this, use 'pure' Markdown instead of including raw HTML:
 
 ```markdown
 # Markdown heading
@@ -1303,9 +1317,9 @@ To fix this, use 'pure' markdown instead of including raw HTML:
 
 Note: To allow specific HTML elements, use the 'allowed_elements' parameter.
 
-Rationale: Raw HTML is allowed in markdown, but this rule is included for
-those who want their documents to only include "pure" markdown, or for those
-who are rendering markdown documents in something other than HTML.
+Rationale: Raw HTML is allowed in Markdown, but this rule is included for
+those who want their documents to only include "pure" Markdown, or for those
+who are rendering Markdown documents into something other than HTML.
 
 <a name="md034"></a>
 
@@ -1331,20 +1345,20 @@ For more information, see <https://www.example.com/>.
 ```
 
 Note: To use a bare URL without it being converted into a link, enclose it in
-a code block, otherwise in some markdown parsers it _will_ be converted:
+a code block, otherwise in some Markdown parsers it *will* be converted:
 
 ```markdown
 `https://www.example.com`
 ```
 
-Note: The following scenario does _not_ trigger this rule to avoid conflicts
+Note: The following scenario does *not* trigger this rule to avoid conflicts
 with `MD011`/`no-reversed-links`:
 
 ```markdown
 [https://www.example.com]
 ```
 
-The use of quotes around a bare link will _not_ trigger this rule, either:
+The use of quotes around a bare link will *not* trigger this rule, either:
 
 ```markdown
 "https://www.example.com"
@@ -1352,7 +1366,7 @@ The use of quotes around a bare link will _not_ trigger this rule, either:
 ```
 
 Rationale: Without angle brackets, the URL isn't converted into a link by many
-markdown parsers.
+Markdown parsers.
 
 <a name="md035"></a>
 
@@ -1362,8 +1376,8 @@ Tags: hr
 
 Aliases: hr-style
 
-Parameters: style ("consistent", "---", "***", or other string specifying the
-horizontal rule; default "consistent")
+Parameters: style ("consistent", "---", "***", "___", or other string specifying
+the horizontal rule; default "consistent")
 
 This rule is triggered when inconsistent styles of horizontal rules are used
 in the document:
@@ -1421,7 +1435,7 @@ _Another section_
 Consectetur adipiscing elit, sed do eiusmod.
 ```
 
-To fix this, use markdown headings instead of emphasized text to denote
+To fix this, use Markdown headings instead of emphasized text to denote
 sections:
 
 ```markdown
@@ -1744,7 +1758,7 @@ Tags: spelling
 
 Aliases: proper-names
 
-Parameters: names, code_blocks (string array; default `null`, boolean; default `true`)
+Parameters: names, code_blocks, html_elements (string array; default `null`, boolean; default `true`, boolean; default `true`)
 
 Fixable: Most violations can be fixed by tooling
 
@@ -1762,7 +1776,10 @@ the proper capitalization, specify the desired letter case in the `names` array:
 ]
 ```
 
-Set the `code_blocks` parameter to `false` to disable this rule for code blocks.
+Set the `code_blocks` parameter to `false` to disable this rule for code blocks
+and spans. Set the `html_elements` parameter to `false` to disable this rule
+for HTML elements and attributes (such as when using a proper name as part of
+a path for `a`/`href` or `img`/`src`).
 
 Rationale: Incorrect capitalization of proper names is usually a mistake.
 
@@ -1911,3 +1928,177 @@ The configured list style can be a specific symbol to use (backtick, tilde), or
 can require that usage be consistent within the document.
 
 Rationale: Consistent formatting makes it easier to understand a document.
+
+<a name="md049"></a>
+
+## MD049 - Emphasis style should be consistent
+
+Tags: emphasis
+
+Aliases: emphasis-style
+
+Parameters: style ("consistent", "asterisk", "underscore"; default "consistent")
+
+Fixable: Most violations can be fixed by tooling
+
+This rule is triggered when the symbols used in the document for emphasis do not
+match the configured emphasis style:
+
+```markdown
+*Text*
+_Text_
+```
+
+To fix this issue, use the configured emphasis style throughout the document:
+
+```markdown
+*Text*
+*Text*
+```
+
+The configured emphasis style can be a specific symbol to use ("asterisk",
+"underscore"), or can require that usage be consistent within the document.
+
+Rationale: Consistent formatting makes it easier to understand a document.
+
+<a name="md050"></a>
+
+## MD050 - Strong style should be consistent
+
+Tags: emphasis
+
+Aliases: strong-style
+
+Parameters: style ("consistent", "asterisk", "underscore"; default "consistent")
+
+Fixable: Most violations can be fixed by tooling
+
+This rule is triggered when the symbols used in the document for strong do not
+match the configured strong style:
+
+```markdown
+**Text**
+__Text__
+```
+
+To fix this issue, use the configured strong style throughout the document:
+
+```markdown
+**Text**
+**Text**
+```
+
+The configured strong style can be a specific symbol to use ("asterisk",
+"underscore"), or can require that usage be consistent within the document.
+
+Rationale: Consistent formatting makes it easier to understand a document.
+
+<a name="md051"></a>
+
+## MD051 - Link fragments should be valid
+
+Tags: links
+
+Aliases: link-fragments
+
+This rule is triggered when a link fragment does not correspond to a heading
+in the document:
+
+```markdown
+# Title
+
+[Link](#fragment)
+```
+
+To fix the issue, change the fragment to reference an existing heading:
+
+```markdown
+[Link](#title)
+```
+
+Alternatively, an HTML `a` tag with an `id` (or a `name`) attribute defines a
+valid anchor:
+
+```markdown
+<a id="fragment"></a>
+```
+
+Some platforms (e.g., [GitHub][github-section-links]) automatically create HTML
+anchors for every heading. This makes it easy to link to different sections in
+a document. These internal links can break over time as headings are renamed.
+
+Note: Creating anchors for headings is not part of the CommonMark specification.
+
+[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
+
+<a name="md052"></a>
+
+## MD052 - Reference links and images should use a label that is defined
+
+Tags: images, links
+
+Aliases: reference-links-images
+
+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
+and makes it easy to reuse the same URL in multiple places.
+
+There are three kinds of reference links and images:
+
+```markdown
+Full: [text][label]
+Collapsed: [label][]
+Shortcut: [label]
+
+Full: ![text][image]
+Collapsed: ![image][]
+Shortcut: ![image]
+
+[label]: https://example.com/label
+[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.
+
+> "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.
+
+<a name="md053"></a>
+
+## MD053 - Link and image reference definitions should be needed
+
+Tags: images, links
+
+Aliases: link-image-reference-definitions
+
+Fixable: Most violations can be fixed by tooling
+
+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
+and makes it easy to reuse the same URL in multiple places.
+
+Because link and image reference definitions are located separately from
+where they are used, there are two scenarios where a definition can be
+unnecessary:
+
+1. If a label is not referenced by any link or image in a document, that
+   definition is unused and can be deleted.
+1. If a label is defined multiple times in a document, the first definition is
+   used and the others can be deleted.
+
+This rule considers a reference definition to be used if any link or image
+reference has the corresponding label. "Full", "collapsed", and "shortcut"
+formats are all supported.
+
+<!-- markdownlint-configure-file {
+  "no-inline-html": {
+    "allowed_elements": [
+      "a"
+    ]
+  }
+} -->

package/helpers/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2021 David Anson
+Copyright (c) 2015-2022 David Anson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal