markdownlint 0.31.1 → 0.32.1

package/doc/Rules.md

@@ -2,16 +2,15 @@
 
 This document contains a description of all rules, what they are checking for,
 as well as examples of documents that break the rule and corrected
-versions of the examples. Any rule whose heading is ~~struck through~~ is
-deprecated, but still provided for backward-compatibility.
+versions of the examples.
 
 <a name="md001"></a>
 
 ## `MD001` - Heading levels should only increment by one level at a time
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `header-increment`, `heading-increment`
+Aliases: `heading-increment`
 
 This rule is triggered when you skip heading levels in a Markdown document, for
 example:
@@ -45,53 +44,13 @@ Rationale: Headings represent the structure of a document and can be confusing
 when skipped - especially for accessibility scenarios. More information:
 <https://www.w3.org/WAI/tutorials/page-structure/headings/>.
 
-<a name="md002"></a>
-
-## ~~`MD002` - First heading should be a top-level heading~~
-
-> This rule is deprecated and provided for backward-compatibility
-
-Tags: `headers`, `headings`
-
-Aliases: `first-header-h1`, `first-heading-h1`
-
-Parameters:
-
-- `level`: Heading level (`integer`, default `1`)
-
-> Note: *MD002 has been deprecated and is disabled by default.*
-> [MD041/first-line-heading](md041.md) offers an improved implementation.
-
-This rule is intended to ensure document headings start at the top level and
-is triggered when the first heading in the document isn't an h1 heading:
-
-```markdown
-## This isn't an H1 heading
-
-### Another heading
-```
-
-The first heading in the document should be an h1 heading:
-
-```markdown
-# Start with an H1 heading
-
-## Then use an H2 for subsections
-```
-
-Note: The `level` parameter can be used to change the top-level (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>.
-
 <a name="md003"></a>
 
 ## `MD003` - Heading style
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `header-style`, `heading-style`
+Aliases: `heading-style`
 
 Parameters:
 
@@ -255,55 +214,6 @@ the same ending column:
 
 Rationale: Violations of this rule can lead to improperly rendered content.
 
-<a name="md006"></a>
-
-## ~~`MD006` - Consider starting bulleted lists at the beginning of the line~~
-
-> This rule is deprecated and provided for backward-compatibility
-
-Tags: `bullet`, `indentation`, `ul`
-
-Aliases: `ul-start-left`
-
-Fixable: Some violations can be fixed by tooling
-
-This rule is triggered when top-level lists don't start at the beginning of a
-line:
-
-```markdown
-Some text
-
-  * List item
-  * List item
-```
-
-To fix, ensure that top-level list items are not indented:
-
-```markdown
-Some test
-
-* List item
-* List item
-```
-
-Note: This rule is triggered for the following scenario because the unordered
-sublist is not recognized as such by the parser. Not being nested 3 characters
-as required by the outer ordered list, it creates a top-level unordered list
-instead.
-
-```markdown
-1. List item
-  - List item
-  - List item
-1. List item
-```
-
-Rationale: Starting lists at the beginning of the line means that nested list
-items can all be indented by the same amount when an editor's indent function
-or the tab key is used to indent. Starting a list 1 space in means that the
-indent of the first nested list is less than the indent of the second level (3
-characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
-
 <a name="md007"></a>
 
 ## `MD007` - Unordered list indentation
@@ -344,10 +254,9 @@ unordered (otherwise, extra indentation of ordered lists interferes with the
 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). 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).
+the configured number of spaces rather than starting at zero. 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
@@ -560,7 +469,6 @@ Parameters:
 - `code_block_line_length`: Number of characters for code blocks (`integer`,
   default `80`)
 - `code_blocks`: Include code blocks (`boolean`, default `true`)
-- `headers`: Include headings (`boolean`, default `true`)
 - `heading_line_length`: Number of characters for headings (`integer`, default
   `80`)
 - `headings`: Include headings (`boolean`, default `true`)
@@ -569,8 +477,6 @@ Parameters:
 - `strict`: Strict length checking (`boolean`, default `false`)
 - `tables`: Include tables (`boolean`, default `true`)
 
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 This rule is triggered when there are lines that are longer than the
 configured `line_length` (default: 80 characters). To fix this, split the line
 up into multiple lines. To set a different maximum length for headings, use
@@ -671,7 +577,7 @@ for more information.
 
 ## `MD018` - No space after hash on atx style heading
 
-Tags: `atx`, `headers`, `headings`, `spaces`
+Tags: `atx`, `headings`, `spaces`
 
 Aliases: `no-missing-space-atx`
 
@@ -701,7 +607,7 @@ Rationale: Violations of this rule can lead to improperly rendered content.
 
 ## `MD019` - Multiple spaces after hash on atx style heading
 
-Tags: `atx`, `headers`, `headings`, `spaces`
+Tags: `atx`, `headings`, `spaces`
 
 Aliases: `no-multiple-space-atx`
 
@@ -732,7 +638,7 @@ content.
 
 ## `MD020` - No space inside hashes on closed atx style heading
 
-Tags: `atx_closed`, `headers`, `headings`, `spaces`
+Tags: `atx_closed`, `headings`, `spaces`
 
 Aliases: `no-missing-space-closed-atx`
 
@@ -764,7 +670,7 @@ Rationale: Violations of this rule can lead to improperly rendered content.
 
 ## `MD021` - Multiple spaces inside hashes on closed atx style heading
 
-Tags: `atx_closed`, `headers`, `headings`, `spaces`
+Tags: `atx_closed`, `headings`, `spaces`
 
 Aliases: `no-multiple-space-closed-atx`
 
@@ -798,9 +704,9 @@ content.
 
 ## `MD022` - Headings should be surrounded by blank lines
 
-Tags: `blank_lines`, `headers`, `headings`
+Tags: `blank_lines`, `headings`
 
-Aliases: `blanks-around-headers`, `blanks-around-headings`
+Aliases: `blanks-around-headings`
 
 Parameters:
 
@@ -853,9 +759,9 @@ as regular text.
 
 ## `MD023` - Headings must start at the beginning of the line
 
-Tags: `headers`, `headings`, `spaces`
+Tags: `headings`, `spaces`
 
-Aliases: `header-start-left`, `heading-start-left`
+Aliases: `heading-start-left`
 
 Fixable: Some violations can be fixed by tooling
 
@@ -875,6 +781,13 @@ Some text
 # Heading
 ```
 
+Note that scenarios like block quotes "indent" the start of the line, so the
+following is also correct:
+
+```markdown
+> # Heading in Block Quote
+```
+
 Rationale: Headings that don't start at the beginning of the line will not be
 parsed as headings, and will instead appear as regular text.
 
@@ -882,9 +795,9 @@ parsed as headings, and will instead appear as regular text.
 
 ## `MD024` - Multiple headings with the same content
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `no-duplicate-header`, `no-duplicate-heading`
+Aliases: `no-duplicate-heading`
 
 Parameters:
 
@@ -932,7 +845,7 @@ heading name; headings with the same content can cause problems with that.
 
 ## `MD025` - Multiple top-level headings in the same document
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `single-h1`, `single-title`
 
@@ -984,7 +897,7 @@ be contained within this heading.
 
 ## `MD026` - Trailing punctuation in heading
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `no-trailing-punctuation`
 
@@ -1522,9 +1435,9 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 ## `MD036` - Emphasis used instead of a heading
 
-Tags: `emphasis`, `headers`, `headings`
+Tags: `emphasis`, `headings`
 
-Aliases: `no-emphasis-as-header`, `no-emphasis-as-heading`
+Aliases: `no-emphasis-as-heading`
 
 Parameters:
 
@@ -1732,7 +1645,7 @@ correct syntax highlighting for code. More information:
 
 ## `MD041` - First line in a file should be a top-level heading
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `first-line-h1`, `first-line-heading`
 
@@ -1819,18 +1732,15 @@ links.
 
 ## `MD043` - Required heading structure
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `required-headers`, `required-headings`
+Aliases: `required-headings`
 
 Parameters:
 
-- `headers`: List of headings (`string[]`, default `[]`)
 - `headings`: List of headings (`string[]`, default `[]`)
 - `match_case`: Match case of headings (`boolean`, default `false`)
 
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 This rule is triggered when the headings in a file do not match the array of
 headings passed to the rule. It can be used to enforce a standard heading
 structure for a set of files.
@@ -1955,6 +1865,12 @@ Or with reference syntax as:
 [ref]: image.jpg "Optional title"
 ```
 
+Or with HTML as:
+
+```html
+<img src="image.jpg" alt="Alternate text" />
+```
+
 Guidance for writing alternate text is available from the [W3C][w3c],
 [Wikipedia][wikipedia], and [other locations][phase2technology].
 
@@ -2091,7 +2007,7 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md049"></a>
 
-## `MD049` - Emphasis style should be consistent
+## `MD049` - Emphasis style
 
 Tags: `emphasis`
 
@@ -2126,7 +2042,7 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md050"></a>
 
-## `MD050` - Strong style should be consistent
+## `MD050` - Strong style
 
 Tags: `emphasis`
 
@@ -2281,9 +2197,9 @@ Parameters:
 Fixable: Some 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.
+at the time of use or can use a label to reference a definition elsewhere in
+the document. The latter 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
@@ -2307,6 +2223,109 @@ Markdown:
 [//]: # (This behaves like a comment)
 ```
 
+<a name="md054"></a>
+
+## `MD054` - Link and image style
+
+Tags: `images`, `links`
+
+Aliases: `link-image-style`
+
+Parameters:
+
+- `autolink`: Allow autolinks (`boolean`, default `true`)
+- `collapsed`: Allow collapsed reference links and images (`boolean`, default
+  `true`)
+- `full`: Allow full reference links and images (`boolean`, default `true`)
+- `inline`: Allow inline links and images (`boolean`, default `true`)
+- `shortcut`: Allow shortcut reference links and images (`boolean`, default
+  `true`)
+- `url_inline`: Allow URLs as inline links (`boolean`, default `true`)
+
+Fixable: Some 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 use a label to reference a definition elsewhere in the
+document. The three reference formats are convenient for keeping paragraph text
+clutter-free and make it easy to reuse the same URL in multiple places.
+
+By default, this rule allows all link/image styles.
+
+Setting the `autolink` parameter to `false` disables autolinks:
+
+```markdown
+<https://example.com>
+```
+
+Setting the `inline` parameter to `false` disables inline links and images:
+
+```markdown
+[link](https://example.com)
+
+![image](https://example.com)
+```
+
+Setting the `full` parameter to `false` disables full reference links and
+images:
+
+```markdown
+[link][url]
+
+![image][url]
+
+[url]: https://example.com
+```
+
+Setting the `collapsed` parameter to `false` disables collapsed reference links
+and images:
+
+```markdown
+[url][]
+
+![url][]
+
+[url]: https://example.com
+```
+
+Setting the `shortcut` parameter to `false` disables shortcut reference links
+and images:
+
+```markdown
+[url]
+
+![url]
+
+[url]: https://example.com
+```
+
+To fix violations of this rule, change the link or image to use an allowed
+style. This rule can automatically fix violations when a link or image can be
+converted to the `inline` style (preferred) or a link can be converted to the
+`autolink` style (which does not support images and must be an absolute URL).
+This rule does *not* fix scenarios that require converting a link or image to
+the `full`, `collapsed`, or `shortcut` reference styles because that involves
+naming the reference and determining where to insert it in the document.
+
+Setting the `url_inline` parameter to `false` prevents the use of inline links
+with the same absolute URL text/destination and no title because such links can
+be converted to autolinks:
+
+```markdown
+[https://example.com](https://example.com)
+```
+
+To fix `url_inline` violations, use the simpler autolink syntax instead:
+
+```markdown
+<https://example.com>
+```
+
+Rationale: Consistent formatting makes it easier to understand a document.
+Autolinks are concise, but appear as URLs which can be long and confusing.
+Inline links and images can include descriptive text, but take up more space in
+Markdown form. Reference links and images can be easier to read and manipulate
+in Markdown form, but require a separate link reference definition.
+
 <!-- markdownlint-configure-file {
   "no-inline-html": {
     "allowed_elements": [

package/doc/md001.md

@@ -1,8 +1,8 @@
 # `MD001` - Heading levels should only increment by one level at a time
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `header-increment`, `heading-increment`
+Aliases: `heading-increment`
 
 This rule is triggered when you skip heading levels in a Markdown document, for
 example:

package/doc/md003.md

@@ -1,8 +1,8 @@
 # `MD003` - Heading style
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `header-style`, `heading-style`
+Aliases: `heading-style`
 
 Parameters:
 

package/doc/md007.md

@@ -36,10 +36,9 @@ unordered (otherwise, extra indentation of ordered lists interferes with the
 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). 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).
+the configured number of spaces rather than starting at zero. 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

package/doc/md013.md

@@ -9,7 +9,6 @@ Parameters:
 - `code_block_line_length`: Number of characters for code blocks (`integer`,
   default `80`)
 - `code_blocks`: Include code blocks (`boolean`, default `true`)
-- `headers`: Include headings (`boolean`, default `true`)
 - `heading_line_length`: Number of characters for headings (`integer`, default
   `80`)
 - `headings`: Include headings (`boolean`, default `true`)
@@ -18,8 +17,6 @@ Parameters:
 - `strict`: Strict length checking (`boolean`, default `false`)
 - `tables`: Include tables (`boolean`, default `true`)
 
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 This rule is triggered when there are lines that are longer than the
 configured `line_length` (default: 80 characters). To fix this, split the line
 up into multiple lines. To set a different maximum length for headings, use

package/doc/md018.md

@@ -1,6 +1,6 @@
 # `MD018` - No space after hash on atx style heading
 
-Tags: `atx`, `headers`, `headings`, `spaces`
+Tags: `atx`, `headings`, `spaces`
 
 Aliases: `no-missing-space-atx`
 

package/doc/md019.md

@@ -1,6 +1,6 @@
 # `MD019` - Multiple spaces after hash on atx style heading
 
-Tags: `atx`, `headers`, `headings`, `spaces`
+Tags: `atx`, `headings`, `spaces`
 
 Aliases: `no-multiple-space-atx`
 

package/doc/md020.md

@@ -1,6 +1,6 @@
 # `MD020` - No space inside hashes on closed atx style heading
 
-Tags: `atx_closed`, `headers`, `headings`, `spaces`
+Tags: `atx_closed`, `headings`, `spaces`
 
 Aliases: `no-missing-space-closed-atx`
 

package/doc/md021.md

@@ -1,6 +1,6 @@
 # `MD021` - Multiple spaces inside hashes on closed atx style heading
 
-Tags: `atx_closed`, `headers`, `headings`, `spaces`
+Tags: `atx_closed`, `headings`, `spaces`
 
 Aliases: `no-multiple-space-closed-atx`
 

package/doc/md022.md

@@ -1,8 +1,8 @@
 # `MD022` - Headings should be surrounded by blank lines
 
-Tags: `blank_lines`, `headers`, `headings`
+Tags: `blank_lines`, `headings`
 
-Aliases: `blanks-around-headers`, `blanks-around-headings`
+Aliases: `blanks-around-headings`
 
 Parameters:
 

package/doc/md023.md

@@ -1,8 +1,8 @@
 # `MD023` - Headings must start at the beginning of the line
 
-Tags: `headers`, `headings`, `spaces`
+Tags: `headings`, `spaces`
 
-Aliases: `header-start-left`, `heading-start-left`
+Aliases: `heading-start-left`
 
 Fixable: Some violations can be fixed by tooling
 
@@ -22,5 +22,12 @@ Some text
 # Heading
 ```
 
+Note that scenarios like block quotes "indent" the start of the line, so the
+following is also correct:
+
+```markdown
+> # Heading in Block Quote
+```
+
 Rationale: Headings that don't start at the beginning of the line will not be
 parsed as headings, and will instead appear as regular text.

package/doc/md024.md

@@ -1,8 +1,8 @@
 # `MD024` - Multiple headings with the same content
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `no-duplicate-header`, `no-duplicate-heading`
+Aliases: `no-duplicate-heading`
 
 Parameters:
 

package/doc/md025.md

@@ -1,6 +1,6 @@
 # `MD025` - Multiple top-level headings in the same document
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `single-h1`, `single-title`
 

package/doc/md026.md

@@ -1,6 +1,6 @@
 # `MD026` - Trailing punctuation in heading
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `no-trailing-punctuation`
 

package/doc/md036.md

@@ -1,8 +1,8 @@
 # `MD036` - Emphasis used instead of a heading
 
-Tags: `emphasis`, `headers`, `headings`
+Tags: `emphasis`, `headings`
 
-Aliases: `no-emphasis-as-header`, `no-emphasis-as-heading`
+Aliases: `no-emphasis-as-heading`
 
 Parameters:
 

package/doc/md041.md

@@ -1,6 +1,6 @@
 # `MD041` - First line in a file should be a top-level heading
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
 Aliases: `first-line-h1`, `first-line-heading`
 

package/doc/md043.md

@@ -1,17 +1,14 @@
 # `MD043` - Required heading structure
 
-Tags: `headers`, `headings`
+Tags: `headings`
 
-Aliases: `required-headers`, `required-headings`
+Aliases: `required-headings`
 
 Parameters:
 
-- `headers`: List of headings (`string[]`, default `[]`)
 - `headings`: List of headings (`string[]`, default `[]`)
 - `match_case`: Match case of headings (`boolean`, default `false`)
 
-> If `headings` is not provided, `headers` (deprecated) will be used.
-
 This rule is triggered when the headings in a file do not match the array of
 headings passed to the rule. It can be used to enforce a standard heading
 structure for a set of files.

package/doc/md045.md

@@ -23,6 +23,12 @@ Or with reference syntax as:
 [ref]: image.jpg "Optional title"
 ```
 
+Or with HTML as:
+
+```html
+<img src="image.jpg" alt="Alternate text" />
+```
+
 Guidance for writing alternate text is available from the [W3C][w3c],
 [Wikipedia][wikipedia], and [other locations][phase2technology].
 

package/doc/md049.md

@@ -1,4 +1,4 @@
-# `MD049` - Emphasis style should be consistent
+# `MD049` - Emphasis style
 
 Tags: `emphasis`
 

package/doc/md050.md

@@ -1,4 +1,4 @@
-# `MD050` - Strong style should be consistent
+# `MD050` - Strong style
 
 Tags: `emphasis`