markdownlint 0.26.2 → 0.28.0

package/doc/md001.md

@@ -0,0 +1,37 @@
+# `MD001` - Heading levels should only increment by one level at a time
+
+Tags: `headers`, `headings`
+
+Aliases: `header-increment`, `heading-increment`
+
+This rule is triggered when you skip heading levels in a Markdown document, for
+example:
+
+```markdown
+# Heading 1
+
+### Heading 3
+
+We skipped out a 2nd level heading in this document
+```
+
+When using multiple heading levels, nested headings should increase by only one
+level at a time:
+
+```markdown
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+
+#### Heading 4
+
+## Another Heading 2
+
+### Another Heading 3
+```
+
+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/>.

package/doc/md002.md

@@ -0,0 +1,37 @@
+# ~~`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>.

package/doc/md003.md

@@ -0,0 +1,59 @@
+# `MD003` - Heading style
+
+Tags: `headers`, `headings`
+
+Aliases: `header-style`, `heading-style`
+
+Parameters:
+
+- `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
+
+## Closed ATX style H2 ##
+
+Setext style H1
+===============
+```
+
+To fix the issue, use consistent heading styles throughout the document:
+
+```markdown
+# ATX style H1
+
+## ATX style H2
+```
+
+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
+===============
+
+Setext style H2
+---------------
+
+### ATX style H3
+```
+
+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.

package/doc/md004.md

@@ -0,0 +1,49 @@
+# `MD004` - Unordered list style
+
+Tags: `bullet`, `ul`
+
+Aliases: `ul-style`
+
+Parameters:
+
+- `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:
+
+```markdown
+* Item 1
++ Item 2
+- Item 3
+```
+
+To fix this issue, use the configured style for list items throughout the
+document:
+
+```markdown
+* Item 1
+* Item 2
+* 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
+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:
+
+```markdown
+* Item 1
+  + Item 2
+    - Item 3
+  + Item 4
+* Item 4
+  + Item 5
+```
+
+Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md005.md

@@ -0,0 +1,53 @@
+# `MD005` - Inconsistent indentation for list items at the same level
+
+Tags: `bullet`, `indentation`, `ul`
+
+Aliases: `list-indent`
+
+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:
+
+```markdown
+* Item 1
+  * Nested Item 1
+  * Nested Item 2
+   * A misaligned item
+```
+
+Usually, this rule will be triggered because of a typo. Correct the indentation
+for the list to fix it:
+
+```markdown
+* Item 1
+  * Nested Item 1
+  * Nested Item 2
+  * Nested Item 3
+```
+
+Sequentially-ordered list markers are usually left-aligned such that all items
+have the same starting column:
+
+```markdown
+...
+8. Item
+9. Item
+10. Item
+11. Item
+...
+```
+
+This rule also supports right-alignment of list markers such that all items have
+the same ending column:
+
+```markdown
+...
+ 8. Item
+ 9. Item
+10. Item
+11. Item
+...
+```
+
+Rationale: Violations of this rule can lead to improperly rendered content.

package/doc/md006.md

@@ -0,0 +1,46 @@
+# ~~`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).

package/doc/md007.md

@@ -0,0 +1,55 @@
+# `MD007` - Unordered list indentation
+
+Tags: `bullet`, `indentation`, `ul`
+
+Aliases: `ul-indent`
+
+Parameters:
+
+- `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: 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).
+
+Example:
+
+```markdown
+* List item
+   * Nested list item indented by 3 spaces
+```
+
+Corrected Example:
+
+```markdown
+* List item
+  * Nested list item indented by 2 spaces
+```
+
+Note: This rule applies to a sublist only if its parent lists are all also
+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).
+
+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: [Markdown Style Guide][markdown-style-guide] and [Marked app\
+support][marked-app-support].
+
+Note: See [Prettier.md](Prettier.md) for compatibility information.
+
+[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

package/doc/md009.md

@@ -0,0 +1,51 @@
+# `MD009` - Trailing spaces
+
+Tags: `whitespace`
+
+Aliases: `no-trailing-spaces`
+
+Parameters:
+
+- `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: 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.
+
+Note: Trailing space is allowed in indented and fenced code blocks because some
+languages require it.
+
+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.
+
+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
+text[2 spaces]
+```
+
+Using spaces to indent blank lines inside a list item is usually not necessary,
+but some parsers require it. Set the `list_item_empty_lines` parameter to `true`
+to allow this (even when `strict` is `true`):
+
+```markdown
+- list item text
+  [2 spaces]
+  list item text
+```
+
+Rationale: Except when being used to create a line break, trailing whitespace
+has no purpose and does not affect the rendering of content.

package/doc/md010.md

@@ -0,0 +1,56 @@
+# `MD010` - Hard tabs
+
+Tags: `hard_tab`, `whitespace`
+
+Aliases: `no-hard-tabs`
+
+Parameters:
+
+- `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
+with spaces instead.
+
+Example:
+
+<!-- markdownlint-disable no-hard-tabs -->
+
+```markdown
+Some text
+
+	* hard tab character used to indent the list item
+```
+
+<!-- markdownlint-restore -->
+
+Corrected example:
+
+```markdown
+Some text
+
+    * Spaces used to indent the list item instead
+```
+
+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.
+
+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.

package/doc/md011.md

@@ -0,0 +1,30 @@
+# `MD011` - Reversed link syntax
+
+Tags: `links`
+
+Aliases: `no-reversed-links`
+
+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
+reversed):
+
+```markdown
+(Incorrect link syntax)[https://www.example.com/]
+```
+
+To fix this, swap the `[]` and `()` around:
+
+```markdown
+[Correct link syntax](https://www.example.com/)
+```
+
+Note: [Markdown Extra](https://en.wikipedia.org/wiki/Markdown_Extra)-style
+footnotes do not trigger this rule:
+
+```markdown
+For (example)[^1]
+```
+
+Rationale: Reversed links are not rendered as usable links.

package/doc/md012.md

@@ -0,0 +1,38 @@
+# `MD012` - Multiple consecutive blank lines
+
+Tags: `blank_lines`, `whitespace`
+
+Aliases: `no-multiple-blanks`
+
+Parameters:
+
+- `maximum`: Consecutive blank lines (`integer`, default `1`)
+
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when there are multiple consecutive blank lines in the
+document:
+
+```markdown
+Some text here
+
+
+Some more text here
+```
+
+To fix this, delete the offending lines:
+
+```markdown
+Some text here
+
+Some more text here
+```
+
+Note: this rule will not be triggered if there are multiple consecutive blank
+lines inside code blocks.
+
+Note: The `maximum` parameter can be used to configure the maximum number of
+consecutive blank lines.
+
+Rationale: Except in a code block, blank lines serve no purpose and do not
+affect the rendering of content.

package/doc/md013.md

@@ -0,0 +1,60 @@
+# `MD013` - Line length
+
+Tags: `line_length`
+
+Aliases: `line-length`
+
+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`)
+- `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.
+
+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
+`heading_line_length`. To set a different maximum length for code blocks, use
+`code_block_line_length`
+
+This rule has an exception when there is no whitespace beyond the configured
+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):
+
+```markdown
+IF THIS LINE IS THE MAXIMUM LENGTH
+This line is okay because there are-no-spaces-beyond-that-length
+And this line is a violation because there are
+This-line-is-also-okay-because-there-are-no-spaces
+```
+
+In `strict` or `stern` modes, the two middle lines above are a violation. The
+third line is a violation in `strict` mode but allowed in `stern` mode.
+
+You have the option to exclude this rule for code blocks, tables, or headings.
+To do so, set the `code_blocks`, `tables`, or `headings` parameter(s) to false.
+
+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>.

package/doc/md014.md

@@ -0,0 +1,54 @@
+# `MD014` - Dollar signs used before commands without showing output
+
+Tags: `code`
+
+Aliases: `commands-show-output`
+
+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 ($):
+
+<!-- markdownlint-disable commands-show-output -->
+
+```markdown
+$ ls
+$ cat foo
+$ less bar
+```
+
+<!-- markdownlint-restore -->
+
+The dollar signs are unnecessary in this situation, and should not be
+included:
+
+```markdown
+ls
+cat foo
+less bar
+```
+
+Showing output for commands preceded by dollar signs does not trigger this rule:
+
+```markdown
+$ ls
+foo bar
+$ cat foo
+Hello world
+$ cat bar
+baz
+```
+
+Because some commands do not produce output, it is not a violation if *some*
+commands do not have output:
+
+```markdown
+$ mkdir test
+mkdir: created directory 'test'
+$ ls test
+```
+
+Rationale: It is easier to copy/paste and less noisy if the dollar signs
+are omitted when they are not needed. See
+<https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code>
+for more information.

package/doc/md018.md

@@ -0,0 +1,27 @@
+# `MD018` - No space after hash on atx style heading
+
+Tags: `atx`, `headers`, `headings`, `spaces`
+
+Aliases: `no-missing-space-atx`
+
+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:
+
+```markdown
+#Heading 1
+
+##Heading 2
+```
+
+To fix this, separate the heading text from the hash character by a single
+space:
+
+```markdown
+# Heading 1
+
+## Heading 2
+```
+
+Rationale: Violations of this rule can lead to improperly rendered content.

package/doc/md019.md

@@ -0,0 +1,28 @@
+# `MD019` - Multiple spaces after hash on atx style heading
+
+Tags: `atx`, `headers`, `headings`, `spaces`
+
+Aliases: `no-multiple-space-atx`
+
+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:
+
+```markdown
+#  Heading 1
+
+##  Heading 2
+```
+
+To fix this, separate the heading text from the hash character by a single
+space:
+
+```markdown
+# Heading 1
+
+## Heading 2
+```
+
+Rationale: Extra space has no purpose and does not affect the rendering of
+content.