markdownlint 0.26.2 → 0.28.0

package/doc/Rules.md

@@ -7,11 +7,11 @@ deprecated, but still provided for backward-compatibility.
 
 <a name="md001"></a>
 
-## MD001 - Heading levels should only increment by one level at a time
+## `MD001` - Heading levels should only increment by one level at a time
 
-Tags: headings, headers
+Tags: `headers`, `headings`
 
-Aliases: heading-increment, header-increment
+Aliases: `header-increment`, `heading-increment`
 
 This rule is triggered when you skip heading levels in a Markdown document, for
 example:
@@ -47,16 +47,20 @@ when skipped - especially for accessibility scenarios. More information:
 
 <a name="md002"></a>
 
-## ~~MD002 - First heading should be a top-level heading~~
+## ~~`MD002` - First heading should be a top-level heading~~
 
-Tags: headings, headers
+> This rule is deprecated and provided for backward-compatibility
 
-Aliases: first-heading-h1, first-header-h1
+Tags: `headers`, `headings`
 
-Parameters: level (number; default 1)
+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) offers an improved implementation.
+> [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:
@@ -83,17 +87,20 @@ information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
 
 <a name="md003"></a>
 
-## MD003 - Heading style
+## `MD003` - Heading style
 
-Tags: headings, headers
+Tags: `headers`, `headings`
 
-Aliases: heading-style, header-style
+Aliases: `header-style`, `heading-style`
 
-Parameters: style ("consistent", "atx", "atx_closed", "setext",
-"setext_with_atx", "setext_with_atx_closed"; default "consistent")
+Parameters:
 
-This rule is triggered when different heading styles (atx, setext, and 'closed'
-atx) are used in the same document:
+- `style`: Heading style (`string`, default `consistent`, values `atx` /
+  `atx_closed` / `consistent` / `setext` / `setext_with_atx` /
+  `setext_with_atx_closed`)
+
+This rule is triggered when different heading styles are used in the same
+document:
 
 ```markdown
 # ATX style H1
@@ -104,7 +111,7 @@ Setext style H1
 ===============
 ```
 
-Be consistent with the style of heading used in a document:
+To fix the issue, use consistent heading styles throughout the document:
 
 ```markdown
 # ATX style H1
@@ -112,8 +119,9 @@ Be consistent with the style of heading used in a document:
 ## ATX style H2
 ```
 
-The setext_with_atx and setext_with_atx_closed doc styles allow atx-style
-headings of level 3 or more in documents with setext style headings:
+The `setext_with_atx` and `setext_with_atx_closed` settings allow ATX-style
+headings of level 3 or more in documents with setext-style headings (which only
+support level 1 and 2 headings):
 
 ```markdown
 Setext style H1
@@ -125,24 +133,34 @@ Setext style H2
 ### ATX style H3
 ```
 
-Note: the configured heading style can be a specific style to use (atx,
-atx_closed, setext, setext_with_atx, setext_with_atx_closed), or simply require
-that the usage is consistent within the document.
+Note: The configured heading style can be a specific style to require (`atx`,
+`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may
+just require that usage is consistent within the document via `consistent`.
+
+Note: The placement of a horizontal rule directly below a line of text can
+trigger this rule by turning that text into a level 2 setext-style heading:
+
+```markdown
+A line of text followed by a horizontal rule becomes a heading
+---
+```
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md004"></a>
 
-## MD004 - Unordered list style
+## `MD004` - Unordered list style
 
-Tags: bullet, ul
+Tags: `bullet`, `ul`
 
-Aliases: ul-style
+Aliases: `ul-style`
 
-Parameters: style ("consistent", "asterisk", "plus", "dash", "sublist"; default
-"consistent")
+Parameters:
 
-Fixable: Most violations can be fixed by tooling
+- `style`: List style (`string`, default `consistent`, values `asterisk` /
+  `consistent` / `dash` / `plus` / `sublist`)
+
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when the symbols used in the document for unordered
 list items do not match the configured unordered list style:
@@ -162,13 +180,13 @@ document:
 * Item 3
 ```
 
-The configured list style can be a specific symbol to use (asterisk, plus, dash),
-to ensure that all list styling is consistent, or to ensure that each
+The configured list style can be a specific symbol to use (asterisk, plus,
+dash), to ensure that all list styling is consistent, or to ensure that each
 sublist has a consistent symbol that differs from its parent list.
 
-For example, the following is valid for the `sublist` style because the outer-most
-indent uses asterisk, the middle indent uses plus, and the inner-most indent uses
-dash:
+For example, the following is valid for the `sublist` style because the
+outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
+indent uses dash:
 
 ```markdown
 * Item 1
@@ -183,13 +201,13 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md005"></a>
 
-## MD005 - Inconsistent indentation for list items at the same level
+## `MD005` - Inconsistent indentation for list items at the same level
 
-Tags: bullet, ul, indentation
+Tags: `bullet`, `indentation`, `ul`
 
-Aliases: list-indent
+Aliases: `list-indent`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when list items are parsed as being at the same level,
 but don't have the same indentation:
@@ -239,13 +257,15 @@ 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~~
+## ~~`MD006` - Consider starting bulleted lists at the beginning of the line~~
+
+> This rule is deprecated and provided for backward-compatibility
 
-Tags: bullet, ul, indentation
+Tags: `bullet`, `indentation`, `ul`
 
-Aliases: ul-start-left
+Aliases: `ul-start-left`
 
-Fixable: Most violations can be fixed by tooling
+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:
@@ -286,19 +306,21 @@ characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
 
 <a name="md007"></a>
 
-## MD007 - Unordered list indentation
+## `MD007` - Unordered list indentation
 
-Tags: bullet, ul, indentation
+Tags: `bullet`, `indentation`, `ul`
 
-Aliases: ul-indent
+Aliases: `ul-indent`
 
-<!-- markdownlint-disable line-length -->
+Parameters:
 
-Parameters: indent, start_indented, start_indent (number; default 2, boolean; default false, number; defaults to indent)
-
-<!-- markdownlint-restore -->
+- `indent`: Spaces for indent (`integer`, default `2`)
+- `start_indent`: Spaces for first level indent (when start_indented is set)
+  (`integer`, default `2`)
+- `start_indented`: Whether to indent the first level of the list (`boolean`,
+  default `false`)
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when list items are not indented by the configured
 number of spaces (default: 2).
@@ -323,38 +345,42 @@ 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).
+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 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>.
+issue for other Markdown parsers, which require 4-space indents. More
+information: [Markdown Style Guide][markdown-style-guide] and [Marked app\
+support][marked-app-support].
 
 Note: See [Prettier.md](Prettier.md) for compatibility information.
 
-<a name="md009"></a>
+[markdown-style-guide]: https://cirosantilli.com/markdown-style-guide#indentation-of-content-inside-lists
+[marked-app-support]: http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting
 
-## MD009 - Trailing spaces
+<a name="md009"></a>
 
-Tags: whitespace
+## `MD009` - Trailing spaces
 
-Aliases: no-trailing-spaces
+Tags: `whitespace`
 
-<!-- markdownlint-disable line-length -->
+Aliases: `no-trailing-spaces`
 
-Parameters: br_spaces, list_item_empty_lines, strict (number; default 2, boolean; default false, boolean; default false)
+Parameters:
 
-<!-- markdownlint-restore -->
+- `br_spaces`: Spaces for line break (`integer`, default `2`)
+- `list_item_empty_lines`: Allow spaces for empty lines in list items
+  (`boolean`, default `false`)
+- `strict`: Include unnecessary breaks (`boolean`, default `false`)
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
-This rule is triggered on any lines that end with unexpected whitespace. To fix this,
-remove the trailing space from the end of the line.
+This rule is triggered on any lines that end with unexpected whitespace. To fix
+this, remove the trailing space from the end of the line.
 
 Note: Trailing space is allowed in indented and fenced code blocks because some
 languages require it.
@@ -363,12 +389,14 @@ The `br_spaces` parameter allows an exception to this rule for a specific number
 of trailing spaces, typically used to insert an explicit line break. The default
 value allows 2 spaces to indicate a hard break (\<br> element).
 
-Note: You must set `br_spaces` to a value >= 2 for this parameter to take effect.
-Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing spaces.
+Note: You must set `br_spaces` to a value >= 2 for this parameter to take
+effect. Setting `br_spaces` to 1 behaves the same as 0, disallowing any trailing
+spaces.
 
-By default, this rule will not trigger when the allowed number of spaces is used,
-even when it doesn't create a hard break (for example, at the end of a paragraph).
-To report such instances as well, set the `strict` parameter to `true`.
+By default, this rule will not trigger when the allowed number of spaces is
+used, even when it doesn't create a hard break (for example, at the end of a
+paragraph). To report such instances as well, set the `strict` parameter to
+`true`.
 
 ```markdown
 Text text text
@@ -390,15 +418,20 @@ has no purpose and does not affect the rendering of content.
 
 <a name="md010"></a>
 
-## MD010 - Hard tabs
+## `MD010` - Hard tabs
 
-Tags: whitespace, hard_tab
+Tags: `hard_tab`, `whitespace`
 
-Aliases: no-hard-tabs
+Aliases: `no-hard-tabs`
 
-Parameters: code_blocks, ignore_code_languages, spaces_per_tab (boolean; default true, array of string; default empty, number; default 1)
+Parameters:
 
-Fixable: Most violations can be fixed by tooling
+- `code_blocks`: Include code blocks (`boolean`, default `true`)
+- `ignore_code_languages`: Fenced code languages to ignore (`string[]`, default
+  `[]`)
+- `spaces_per_tab`: Number of spaces for each hard tab (`integer`, default `1`)
+
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered by any lines that contain hard tab characters instead
 of using spaces for indentation. To fix this, replace any hard tab characters
@@ -444,13 +477,13 @@ can be harder to work with than spaces.
 
 <a name="md011"></a>
 
-## MD011 - Reversed link syntax
+## `MD011` - Reversed link syntax
 
-Tags: links
+Tags: `links`
 
-Aliases: no-reversed-links
+Aliases: `no-reversed-links`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when text that appears to be a link is encountered, but
 where the syntax appears to have been reversed (the `[]` and `()` are
@@ -477,15 +510,17 @@ Rationale: Reversed links are not rendered as usable links.
 
 <a name="md012"></a>
 
-## MD012 - Multiple consecutive blank lines
+## `MD012` - Multiple consecutive blank lines
+
+Tags: `blank_lines`, `whitespace`
 
-Tags: whitespace, blank_lines
+Aliases: `no-multiple-blanks`
 
-Aliases: no-multiple-blanks
+Parameters:
 
-Parameters: maximum (number; default 1)
+- `maximum`: Consecutive blank lines (`integer`, default `1`)
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when there are multiple consecutive blank lines in the
 document:
@@ -516,17 +551,25 @@ affect the rendering of content.
 
 <a name="md013"></a>
 
-## MD013 - Line length
+## `MD013` - Line length
 
-Tags: line_length
+Tags: `line_length`
 
-Aliases: line-length
+Aliases: `line-length`
 
-<!-- markdownlint-disable line-length -->
+Parameters:
 
-Parameters: line_length, heading_line_length, code_block_line_length, code_blocks, tables, headings, headers, strict, stern (number; default 80 for *_length, boolean; default true (except strict/stern which default false))
-
-<!-- markdownlint-restore -->
+- `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`)
+- `line_length`: Number of characters (`integer`, default `80`)
+- `stern`: Stern length checking (`boolean`, default `false`)
+- `strict`: Strict length checking (`boolean`, default `false`)
+- `tables`: Include tables (`boolean`, default `true`)
 
 > If `headings` is not provided, `headers` (deprecated) will be used.
 
@@ -537,11 +580,11 @@ up into multiple lines. To set a different maximum length for headings, use
 `code_block_line_length`
 
 This rule has an exception when there is no whitespace beyond the configured
-line length. This allows you to still include items such as long URLs without
-being forced to break them in the middle. To disable this exception, set the
-`strict` parameter to `true` to report an issue when any line is too long.
-To warn for lines that are too long and could be fixed but allow lines without
-spaces, set the `stern` parameter to `true`.
+line length. This allows you to include items such as long URLs without being
+forced to break them in the middle. To disable this exception, set the `strict`
+parameter to `true` and an issue will be reported when any line is too long. To
+warn for lines that are too long and could be fixed but allow long lines
+without spaces, set the `stern` parameter to `true`.
 
 For example (assuming normal behavior):
 
@@ -562,18 +605,22 @@ 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.
+
 Rationale: Extremely long lines can be difficult to work with in some editors.
 More information: <https://cirosantilli.com/markdown-style-guide#line-wrapping>.
 
 <a name="md014"></a>
 
-## MD014 - Dollar signs used before commands without showing output
+## `MD014` - Dollar signs used before commands without showing output
 
-Tags: code
+Tags: `code`
 
-Aliases: commands-show-output
+Aliases: `commands-show-output`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when there are code blocks showing shell commands to be
 typed, and *all* of the shell commands are preceded by dollar signs ($):
@@ -624,13 +671,13 @@ for more information.
 
 <a name="md018"></a>
 
-## MD018 - No space after hash on atx style heading
+## `MD018` - No space after hash on atx style heading
 
-Tags: headings, headers, atx, spaces
+Tags: `atx`, `headers`, `headings`, `spaces`
 
-Aliases: no-missing-space-atx
+Aliases: `no-missing-space-atx`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when spaces are missing after the hash characters
 in an atx style heading:
@@ -654,13 +701,13 @@ Rationale: Violations of this rule can lead to improperly rendered content.
 
 <a name="md019"></a>
 
-## MD019 - Multiple spaces after hash on atx style heading
+## `MD019` - Multiple spaces after hash on atx style heading
 
-Tags: headings, headers, atx, spaces
+Tags: `atx`, `headers`, `headings`, `spaces`
 
-Aliases: no-multiple-space-atx
+Aliases: `no-multiple-space-atx`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when more than one space is used to separate the
 heading text from the hash characters in an atx style heading:
@@ -685,13 +732,13 @@ content.
 
 <a name="md020"></a>
 
-## MD020 - No space inside hashes on closed atx style heading
+## `MD020` - No space inside hashes on closed atx style heading
 
-Tags: headings, headers, atx_closed, spaces
+Tags: `atx_closed`, `headers`, `headings`, `spaces`
 
-Aliases: no-missing-space-closed-atx
+Aliases: `no-missing-space-closed-atx`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when spaces are missing inside the hash characters
 in a closed atx style heading:
@@ -717,13 +764,13 @@ Rationale: Violations of this rule can lead to improperly rendered content.
 
 <a name="md021"></a>
 
-## MD021 - Multiple spaces inside hashes on closed atx style heading
+## `MD021` - Multiple spaces inside hashes on closed atx style heading
 
-Tags: headings, headers, atx_closed, spaces
+Tags: `atx_closed`, `headers`, `headings`, `spaces`
 
-Aliases: no-multiple-space-closed-atx
+Aliases: `no-multiple-space-closed-atx`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when more than one space is used to separate the
 heading text from the hash characters in a closed atx style heading:
@@ -751,15 +798,18 @@ content.
 
 <a name="md022"></a>
 
-## MD022 - Headings should be surrounded by blank lines
+## `MD022` - Headings should be surrounded by blank lines
 
-Tags: headings, headers, blank_lines
+Tags: `blank_lines`, `headers`, `headings`
 
-Aliases: blanks-around-headings, blanks-around-headers
+Aliases: `blanks-around-headers`, `blanks-around-headings`
 
-Parameters: lines_above, lines_below (number; default 1)
+Parameters:
 
-Fixable: Most violations can be fixed by tooling
+- `lines_above`: Blank lines above heading (`integer`, default `1`)
+- `lines_below`: Blank lines below heading (`integer`, default `1`)
+
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when headings (any style) are either not preceded or not
 followed by at least one blank line:
@@ -785,25 +835,25 @@ Some more text
 ## Heading 2
 ```
 
-The `lines_above` and `lines_below` parameters can be used to specify a different
-number of blank lines (including 0) above or below each heading.
+The `lines_above` and `lines_below` parameters can be used to specify a
+different number of blank lines (including 0) above or below each heading.
 
 Note: If `lines_above` or `lines_below` are configured to require more than one
-blank line, [MD012/no-multiple-blanks](#md012) should also be customized.
+blank line, [MD012/no-multiple-blanks](md012.md) should also be customized.
 
-Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`, will
-not parse headings that don't have a blank line before, and will parse them as
-regular text.
+Rationale: Aside from aesthetic reasons, some parsers, including `kramdown`,
+will not parse headings that don't have a blank line before, and will parse them
+as regular text.
 
 <a name="md023"></a>
 
-## MD023 - Headings must start at the beginning of the line
+## `MD023` - Headings must start at the beginning of the line
 
-Tags: headings, headers, spaces
+Tags: `headers`, `headings`, `spaces`
 
-Aliases: heading-start-left, header-start-left
+Aliases: `header-start-left`, `heading-start-left`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when a heading is indented by one or more spaces:
 
@@ -826,13 +876,17 @@ parsed as headings, and will instead appear as regular text.
 
 <a name="md024"></a>
 
-## MD024 - Multiple headings with the same content
+## `MD024` - Multiple headings with the same content
+
+Tags: `headers`, `headings`
 
-Tags: headings, headers
+Aliases: `no-duplicate-header`, `no-duplicate-heading`
 
-Aliases: no-duplicate-heading, no-duplicate-header
+Parameters:
 
-Parameters: siblings_only, allow_different_nesting (boolean; default `false`)
+- `allow_different_nesting`: Only check sibling headings (`boolean`, default
+  `false`)
+- `siblings_only`: Only check sibling headings (`boolean`, default `false`)
 
 This rule is triggered if there are multiple headings in the document that have
 the same text:
@@ -872,13 +926,17 @@ heading name; headings with the same content can cause problems with that.
 
 <a name="md025"></a>
 
-## MD025 - Multiple top-level headings in the same document
+## `MD025` - Multiple top-level headings in the same document
 
-Tags: headings, headers
+Tags: `headers`, `headings`
 
-Aliases: single-title, single-h1
+Aliases: `single-h1`, `single-title`
 
-Parameters: level, front_matter_title (number; default 1, string; default "^\s*"?title"?\s*[:=]")
+Parameters:
+
+- `front_matter_title`: RegExp for matching title in front matter (`string`,
+  default `^\s*title\s*[:=]`)
+- `level`: Heading level (`integer`, default `1`)
 
 This rule is triggered when a top-level heading is in use (the first line of
 the file is an h1 heading), and more than one h1 heading is in use in the
@@ -905,29 +963,33 @@ lower-level headings (h2, h3, etc.):
 Note: The `level` parameter can be used to change the top-level (ex: to h2) in
 cases where an h1 is added externally.
 
-If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and contains
-a `title` property (commonly used with blog posts), this rule treats that as a top
-level heading and will report a violation for any subsequent top-level headings.
-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`.
+If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+contains a `title` property (commonly used with blog posts), this rule treats
+that as a top level heading and will report a violation for any subsequent
+top-level headings. 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`.
 
 Rationale: A top-level heading is an h1 on the first line of the file, and
 serves as the title for the document. If this convention is in use, then there
-can not be more than one title for the document, and the entire document
-should be contained within this heading.
+can not be more than one title for the document, and the entire document should
+be contained within this heading.
 
 <a name="md026"></a>
 
-## MD026 - Trailing punctuation in heading
+## `MD026` - Trailing punctuation in heading
+
+Tags: `headers`, `headings`
 
-Tags: headings, headers
+Aliases: `no-trailing-punctuation`
 
-Aliases: no-trailing-punctuation
+Parameters:
 
-Parameters: punctuation (string; default ".,;:!。，；：！")
+- `punctuation`: Punctuation characters not allowed at end of headings
+  (`string`, default `.,;:!。，；：！`)
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered on any heading that has one of the specified normal or
 full-width punctuation characters as the last character in the line:
@@ -945,26 +1007,28 @@ To fix this, remove the trailing punctuation:
 Note: The `punctuation` parameter can be used to specify what characters count
 as punctuation at the end of a heading. For example, you can change it to
 `".,;:"` to allow headings that end with an exclamation point. `?` is
-allowed by default because of how common it is in headings of FAQ-style documents.
-Setting the `punctuation` parameter to `""` allows all characters - and is
-equivalent to disabling the rule.
+allowed by default because of how common it is in headings of FAQ-style
+documents. Setting the `punctuation` parameter to `""` allows all characters -
+and is equivalent to disabling the rule.
 
-Note: The trailing semicolon of
-[HTML entity references](https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references)
+Note: The trailing semicolon of [HTML entity references][html-entity-references]
 like `&copy;`, `&#169;`, and `&#x000A9;` is ignored by this rule.
 
 Rationale: Headings are not meant to be full sentences. More information:
-<https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers>
+[Punctuation at the end of headers][end-punctuation].
+
+[end-punctuation]: https://cirosantilli.com/markdown-style-guide#punctuation-at-the-end-of-headers
+[html-entity-references]: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
 
 <a name="md027"></a>
 
-## MD027 - Multiple spaces after blockquote symbol
+## `MD027` - Multiple spaces after blockquote symbol
 
-Tags: blockquote, whitespace, indentation
+Tags: `blockquote`, `indentation`, `whitespace`
 
-Aliases: no-multiple-space-blockquote
+Aliases: `no-multiple-space-blockquote`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when blockquotes have more than one space after the
 blockquote (`>`) symbol:
@@ -985,11 +1049,11 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md028"></a>
 
-## MD028 - Blank line inside blockquote
+## `MD028` - Blank line inside blockquote
 
-Tags: blockquote, whitespace
+Tags: `blockquote`, `whitespace`
 
-Aliases: no-blanks-blockquote
+Aliases: `no-blanks-blockquote`
 
 This rule is triggered when two blockquote blocks are separated by nothing
 except for a blank line:
@@ -1028,13 +1092,16 @@ separate blockquotes.
 
 <a name="md029"></a>
 
-## MD029 - Ordered list item prefix
+## `MD029` - Ordered list item prefix
+
+Tags: `ol`
 
-Tags: ol
+Aliases: `ol-prefix`
 
-Aliases: ol-prefix
+Parameters:
 
-Parameters: style ("one", "ordered", "one_or_ordered", "zero"; default "one_or_ordered")
+- `style`: List style (`string`, default `one_or_ordered`, values `one` /
+  `one_or_ordered` / `ordered` / `zero`)
 
 This rule is triggered for ordered lists that do not either start with '1.' or
 do not have a prefix that increases in numerical order (depending on the
@@ -1126,15 +1193,23 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md030"></a>
 
-## MD030 - Spaces after list markers
+## `MD030` - Spaces after list markers
 
-Tags: ol, ul, whitespace
+Tags: `ol`, `ul`, `whitespace`
 
-Aliases: list-marker-space
+Aliases: `list-marker-space`
 
-Parameters: ul_single, ol_single, ul_multi, ol_multi (number; default 1)
+Parameters:
 
-Fixable: Most violations can be fixed by tooling
+- `ol_multi`: Spaces for multi-line ordered list items (`integer`, default `1`)
+- `ol_single`: Spaces for single-line ordered list items (`integer`, default
+  `1`)
+- `ul_multi`: Spaces for multi-line unordered list items (`integer`, default
+  `1`)
+- `ul_single`: Spaces for single-line unordered list items (`integer`, default
+  `1`)
+
+Fixable: Some violations can be fixed by tooling
 
 This rule checks for the number of spaces between a list marker (e.g. '`-`',
 '`*`', '`+`' or '`1.`') and the text of the list item.
@@ -1203,15 +1278,17 @@ Note: See [Prettier.md](Prettier.md) for compatibility information.
 
 <a name="md031"></a>
 
-## MD031 - Fenced code blocks should be surrounded by blank lines
+## `MD031` - Fenced code blocks should be surrounded by blank lines
+
+Tags: `blank_lines`, `code`
 
-Tags: code, blank_lines
+Aliases: `blanks-around-fences`
 
-Aliases: blanks-around-fences
+Parameters:
 
-Parameters: list_items (boolean; default true)
+- `list_items`: Include list items (`boolean`, default `true`)
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when fenced code blocks are either not preceded or not
 followed by a blank line:
@@ -1254,13 +1331,13 @@ not parse fenced code blocks that don't have blank lines before and after them.
 
 <a name="md032"></a>
 
-## MD032 - Lists should be surrounded by blank lines
+## `MD032` - Lists should be surrounded by blank lines
 
-Tags: bullet, ul, ol, blank_lines
+Tags: `blank_lines`, `bullet`, `ol`, `ul`
 
-Aliases: blanks-around-lists
+Aliases: `blanks-around-lists`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when lists (of any kind) are either not preceded or not
 followed by a blank line:
@@ -1295,13 +1372,15 @@ not parse lists that don't have blank lines before and after them.
 
 <a name="md033"></a>
 
-## MD033 - Inline HTML
+## `MD033` - Inline HTML
 
-Tags: html
+Tags: `html`
 
-Aliases: no-inline-html
+Aliases: `no-inline-html`
 
-Parameters: allowed_elements (array of string; default empty)
+Parameters:
+
+- `allowed_elements`: Allowed elements (`string[]`, default `[]`)
 
 This rule is triggered whenever raw HTML is used in a Markdown document:
 
@@ -1323,61 +1402,68 @@ who are rendering Markdown documents into something other than HTML.
 
 <a name="md034"></a>
 
-## MD034 - Bare URL used
+## `MD034` - Bare URL used
 
-Tags: links, url
+Tags: `links`, `url`
 
-Aliases: no-bare-urls
+Aliases: `no-bare-urls`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
-This rule is triggered whenever a URL is given that isn't surrounded by angle
-brackets:
+This rule is triggered whenever a URL or email address appears without
+surrounding angle brackets:
 
 ```markdown
-For more information, see https://www.example.com/.
+For more info, visit https://www.example.com/ or email user@example.com.
 ```
 
-To fix this, add angle brackets around the URL:
+To fix this, add angle brackets around the URL or email address:
 
 ```markdown
-For more information, see <https://www.example.com/>.
+For more info, visit <https://www.example.com/> or email <user@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:
+Note: To include a bare URL or email without it being converted into a link,
+wrap it in a code span:
 
 ```markdown
-`https://www.example.com`
+Not a clickable link: `https://www.example.com`
 ```
 
-Note: The following scenario does *not* trigger this rule to avoid conflicts
-with `MD011`/`no-reversed-links`:
+Note: The following scenario does not trigger this rule because it could be a
+shortcut link:
 
 ```markdown
 [https://www.example.com]
 ```
 
-The use of quotes around a bare link will *not* trigger this rule, either:
+Note: The following syntax triggers this rule because the nested link could be
+a shortcut link (which takes precedence):
 
 ```markdown
-"https://www.example.com"
-'https://www.example.com'
+[text [shortcut] text](https://example.com)
 ```
 
-Rationale: Without angle brackets, the URL isn't converted into a link by many
-Markdown parsers.
+To avoid this, escape both inner brackets:
+
+```markdown
+[link \[text\] link](https://example.com)
+```
+
+Rationale: Without angle brackets, a bare URL or email isn't converted into a
+link by some Markdown parsers.
 
 <a name="md035"></a>
 
-## MD035 - Horizontal rule style
+## `MD035` - Horizontal rule style
 
-Tags: hr
+Tags: `hr`
 
-Aliases: hr-style
+Aliases: `hr-style`
 
-Parameters: style ("consistent", "---", "***", "___", or other string specifying
-the horizontal rule; default "consistent")
+Parameters:
+
+- `style`: Horizontal rule style (`string`, default `consistent`)
 
 This rule is triggered when inconsistent styles of horizontal rules are used
 in the document:
@@ -1414,13 +1500,15 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md036"></a>
 
-## MD036 - Emphasis used instead of a heading
+## `MD036` - Emphasis used instead of a heading
+
+Tags: `emphasis`, `headers`, `headings`
 
-Tags: headings, headers, emphasis
+Aliases: `no-emphasis-as-header`, `no-emphasis-as-heading`
 
-Aliases: no-emphasis-as-heading, no-emphasis-as-header
+Parameters:
 
-Parameters: punctuation (string; default ".,;:!?。，；：！？")
+- `punctuation`: Punctuation characters (`string`, default `.,;:!?。，；：！？`)
 
 This check looks for instances where emphasized (i.e. bold or italic) text is
 used to separate sections, where a heading should be used instead:
@@ -1460,13 +1548,13 @@ the structure of a document. More information:
 
 <a name="md037"></a>
 
-## MD037 - Spaces inside emphasis markers
+## `MD037` - Spaces inside emphasis markers
 
-Tags: whitespace, emphasis
+Tags: `emphasis`, `whitespace`
 
-Aliases: no-space-in-emphasis
+Aliases: `no-space-in-emphasis`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when emphasis markers (bold, italic) are used, but they
 have spaces between the markers and the text:
@@ -1500,13 +1588,13 @@ intended by the author.
 
 <a name="md038"></a>
 
-## MD038 - Spaces inside code span elements
+## `MD038` - Spaces inside code span elements
 
-Tags: whitespace, code
+Tags: `code`, `whitespace`
 
-Aliases: no-space-in-code
+Aliases: `no-space-in-code`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered for code span elements that have spaces adjacent to the
 backticks:
@@ -1524,30 +1612,32 @@ To fix this, remove any spaces adjacent to the backticks:
 ```
 
 Note: A single leading and trailing space is allowed by the specification and
-automatically trimmed (to allow for embedded backticks):
+automatically trimmed (in order to allow for code spans that embed backticks):
 
 ```markdown
 `` `backticks` ``
 ```
 
-Note: A single leading or trailing space is allowed if used to separate code span
-markers from an embedded 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):
 
 ```markdown
 `` ` embedded backtick``
 ```
 
-Rationale: Violations of this rule can lead to improperly rendered content.
+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.
 
 <a name="md039"></a>
 
-## MD039 - Spaces inside link text
+## `MD039` - Spaces inside link text
 
-Tags: whitespace, links
+Tags: `links`, `whitespace`
 
-Aliases: no-space-in-links
+Aliases: `no-space-in-links`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered on links that have spaces surrounding the link text:
 
@@ -1565,11 +1655,16 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md040"></a>
 
-## MD040 - Fenced code blocks should have a language specified
+## `MD040` - Fenced code blocks should have a language specified
+
+Tags: `code`, `language`
 
-Tags: code, language
+Aliases: `fenced-code-language`
 
-Aliases: fenced-code-language
+Parameters:
+
+- `allowed_languages`: List of languages (`string[]`, default `[]`)
+- `language_only`: Require language only (`boolean`, default `false`)
 
 This rule is triggered when fenced code blocks are used, but a language isn't
 specified:
@@ -1598,19 +1693,34 @@ Plain text in a code block
 ```
 ````
 
+You can configure the `allowed_languages` parameter to specify a list of
+languages code blocks could use. Languages are case sensitive. The default value
+is `[]` which means any language specifier is valid.
+
+You can prevent extra data from being present in the info string of fenced code
+blocks. To do so, set the `language_only` parameter to `true`.
+
+<!-- markdownlint-disable-next-line no-space-in-code -->
+Info strings with leading/trailing whitespace (ex: `js `) or other content (ex:
+`ruby startline=3`) will trigger this rule.
+
 Rationale: Specifying a language improves content rendering by using the
 correct syntax highlighting for code. More information:
 <https://cirosantilli.com/markdown-style-guide#option-code-fenced>.
 
 <a name="md041"></a>
 
-## MD041 - First line in a file should be a top-level heading
+## `MD041` - First line in a file should be a top-level heading
 
-Tags: headings, headers
+Tags: `headers`, `headings`
 
-Aliases: first-line-heading, first-line-h1
+Aliases: `first-line-h1`, `first-line-heading`
 
-Parameters: level, front_matter_title (number; default 1, string; default "^\s*"?title"?\s*[:=]")
+Parameters:
+
+- `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:
@@ -1637,25 +1747,26 @@ permitted by this rule. For example:
 This is a file 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.
+Note: The `level` parameter can be used to change the top-level (ex: to h2) in
+cases where an h1 is added externally.
 
 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`.
+To disable the use of front matter by this rule, specify `""` for
+`front_matter_title`.
 
 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="md042"></a>
 
-## MD042 - No empty links
+## `MD042` - No empty links
 
-Tags: links
+Tags: `links`
 
-Aliases: no-empty-links
+Aliases: `no-empty-links`
 
 This rule is triggered when an empty link is encountered:
 
@@ -1681,17 +1792,22 @@ But non-empty fragments will not:
 [a valid fragment](#fragment)
 ```
 
-Rationale: Empty links do not lead anywhere and therefore don't function as links.
+Rationale: Empty links do not lead anywhere and therefore don't function as
+links.
 
 <a name="md043"></a>
 
-## MD043 - Required heading structure
+## `MD043` - Required heading structure
+
+Tags: `headers`, `headings`
 
-Tags: headings, headers
+Aliases: `required-headers`, `required-headings`
 
-Aliases: required-headings, required-headers
+Parameters:
 
-Parameters: headings, headers (array of string; default `null` for disabled)
+- `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.
 
@@ -1744,31 +1860,40 @@ special value `"+"` meaning "one or more unspecified headings" and set the
 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).
 
-Note that while the `headings` parameter uses the "## Text" ATX heading style for
-simplicity, a file may use any supported heading style.
+Note that while the `headings` parameter uses the "## Text" ATX heading style
+for simplicity, a file may use any supported heading style.
+
+By default, the case of headings in the document is not required to match that
+of `headings`. To require that case match exactly, set the `match_case`
+parameter to `true`.
 
 Rationale: Projects may wish to enforce a consistent document structure across
 a set of similar content.
 
 <a name="md044"></a>
 
-## MD044 - Proper names should have the correct capitalization
+## `MD044` - Proper names should have the correct capitalization
+
+Tags: `spelling`
 
-Tags: spelling
+Aliases: `proper-names`
 
-Aliases: proper-names
+Parameters:
 
-Parameters: names, code_blocks, html_elements (string array; default `null`, boolean; default `true`, boolean; default `true`)
+- `code_blocks`: Include code blocks (`boolean`, default `true`)
+- `html_elements`: Include HTML elements (`boolean`, default `true`)
+- `names`: List of proper names (`string[]`, default `[]`)
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when any of the strings in the `names` array do not have
 the specified capitalization. It can be used to enforce a standard letter case
 for the names of projects and products.
 
 For example, the language "JavaScript" is usually written with both the 'J' and
-'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To enforce
-the proper capitalization, specify the desired letter case in the `names` array:
+'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To
+enforce the proper capitalization, specify the desired letter case in the
+`names` array:
 
 ```json
 [
@@ -1785,13 +1910,14 @@ Rationale: Incorrect capitalization of proper names is usually a mistake.
 
 <a name="md045"></a>
 
-## MD045 - Images should have alternate text (alt text)
+## `MD045` - Images should have alternate text (alt text)
 
-Tags: accessibility, images
+Tags: `accessibility`, `images`
 
-Aliases: no-alt-text
+Aliases: `no-alt-text`
 
-This rule is triggered when an image is missing alternate text (alt text) information.
+This rule is triggered when an image is missing alternate text (alt text)
+information.
 
 Alternate text is commonly specified inline as:
 
@@ -1809,27 +1935,34 @@ Or with reference syntax as:
 [ref]: image.jpg "Optional title"
 ```
 
-Guidance for writing alternate text is available from the [W3C](https://www.w3.org/WAI/alt/),
-[Wikipedia](https://en.wikipedia.org/wiki/Alt_attribute), and
-[other locations](https://www.phase2technology.com/blog/no-more-excuses).
+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.
 
+[phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
+[w3c]: https://www.w3.org/WAI/alt/
+[wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute
+
 <a name="md046"></a>
 
-## MD046 - Code block style
+## `MD046` - Code block style
+
+Tags: `code`
 
-Tags: code
+Aliases: `code-block-style`
 
-Aliases: code-block-style
+Parameters:
 
-Parameters: style ("consistent", "fenced", "indented"; default "consistent")
+- `style`: Block style (`string`, default `consistent`, values `consistent` /
+  `fenced` / `indented`)
 
 This rule is triggered when unwanted or different code block styles are used in
 the same document.
 
-In the default configuration this rule reports a violation for the following document:
+In the default configuration this rule reports a violation for the following
+document:
 
 <!-- markdownlint-disable code-block-style -->
 
@@ -1857,13 +1990,13 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md047"></a>
 
-## MD047 - Files should end with a single newline character
+## `MD047` - Files should end with a single newline character
 
-Tags: blank_lines
+Tags: `blank_lines`
 
-Aliases: single-trailing-newline
+Aliases: `single-trailing-newline`
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some violations can be fixed by tooling
 
 This rule is triggered when there is not a single newline character at the end
 of a file.
@@ -1886,17 +2019,24 @@ This file ends with a newline.
 ```
 
 Rationale: Some programs have trouble with files that do not end with a newline.
-More information: <https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file>.
+
+More information: [What's the point in adding a new line to the end of a
+file?][stack-exchange]
+
+[stack-exchange]: https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file
 
 <a name="md048"></a>
 
-## MD048 - Code fence style
+## `MD048` - Code fence style
+
+Tags: `code`
 
-Tags: code
+Aliases: `code-fence-style`
 
-Aliases: code-fence-style
+Parameters:
 
-Parameters: style ("consistent", "tilde", "backtick"; default "consistent")
+- `style`: Code fence style (`string`, default `consistent`, values `backtick`
+  / `consistent` / `tilde`)
 
 This rule is triggered when the symbols used in the document for fenced code
 blocks do not match the configured code fence style:
@@ -1931,15 +2071,18 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md049"></a>
 
-## MD049 - Emphasis style should be consistent
+## `MD049` - Emphasis style should be consistent
 
-Tags: emphasis
+Tags: `emphasis`
 
-Aliases: emphasis-style
+Aliases: `emphasis-style`
 
-Parameters: style ("consistent", "asterisk", "underscore"; default "consistent")
+Parameters:
 
-Fixable: Most violations can be fixed by tooling
+- `style`: Emphasis style should be consistent (`string`, default `consistent`,
+  values `asterisk` / `consistent` / `underscore`)
+
+Fixable: Some 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:
@@ -1963,15 +2106,18 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md050"></a>
 
-## MD050 - Strong style should be consistent
+## `MD050` - Strong style should be consistent
+
+Tags: `emphasis`
 
-Tags: emphasis
+Aliases: `strong-style`
 
-Aliases: strong-style
+Parameters:
 
-Parameters: style ("consistent", "asterisk", "underscore"; default "consistent")
+- `style`: Strong style should be consistent (`string`, default `consistent`,
+  values `asterisk` / `consistent` / `underscore`)
 
-Fixable: Most violations can be fixed by tooling
+Fixable: Some 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:
@@ -1995,14 +2141,16 @@ Rationale: Consistent formatting makes it easier to understand a document.
 
 <a name="md051"></a>
 
-## MD051 - Link fragments should be valid
+## `MD051` - Link fragments should be valid
 
-Tags: links
+Tags: `links`
 
-Aliases: link-fragments
+Aliases: `link-fragments`
 
-This rule is triggered when a link fragment does not correspond to a heading
-in the document:
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when a link fragment does not match any of the fragments
+that are automatically generated for headings in a document:
 
 ```markdown
 # Title
@@ -2010,34 +2158,47 @@ in the document:
 [Link](#fragment)
 ```
 
-To fix the issue, change the fragment to reference an existing heading:
+To fix this issue, change the link fragment to reference an existing heading:
 
 ```markdown
+# Title
+
 [Link](#title)
 ```
 
-Alternatively, an HTML `a` tag with an `id` (or a `name`) attribute defines a
-valid anchor:
+Alternatively, an HTML `a` tag with an `id` or a `name` attribute can be used to
+define a fragment:
 
 ```markdown
-<a id="fragment"></a>
+<a id="bookmark"></a>
+
+[Link](#bookmark)
 ```
 
-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.
+An `a` tag can be useful in scenarios where a heading is not appropriate or for
+control over the text of the fragment identifier.
+
+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.
+However, section links change if headings are renamed or removed. This rule
+helps identify broken section links within a document.
 
-Note: Creating anchors for headings is not part of the CommonMark specification.
+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.
 
 [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
 
 <a name="md052"></a>
 
-## MD052 - Reference links and images should use a label that is defined
+## `MD052` - Reference links and images should use a label that is defined
 
-Tags: images, links
+Tags: `images`, `links`
 
-Aliases: reference-links-images
+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.
@@ -2069,15 +2230,17 @@ of undefined labels for "full" and "collapsed" reference syntax.
 
 <a name="md053"></a>
 
-## MD053 - Link and image reference definitions should be needed
+## `MD053` - Link and image reference definitions should be needed
 
-Tags: images, links
+Tags: `images`, `links`
 
-Aliases: link-image-reference-definitions
+Aliases: `link-image-reference-definitions`
 
-Parameters: ignored_definitions (array of string; default [ "//" ])
+Parameters:
 
-Fixable: Most violations can be fixed by tooling
+- `ignored_definitions`: Ignored definitions (`string[]`, default `["//"]`)
+
+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.
@@ -2090,7 +2253,7 @@ 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
+2. 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
@@ -2102,7 +2265,7 @@ 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:
 
-```md
+```markdown
 [//]: # (This behaves like a comment)
 ```