markdownlint 0.26.2 → 0.27.0

package/doc/md020.md

@@ -0,0 +1,29 @@
+# `MD020` - No space inside hashes on closed atx style heading
+
+Tags: `atx_closed`, `headers`, `headings`, `spaces`
+
+Aliases: `no-missing-space-closed-atx`
+
+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:
+
+```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 ##
+```
+
+Note: this rule will fire if either side of the heading is missing spaces.
+
+Rationale: Violations of this rule can lead to improperly rendered content.

package/doc/md021.md

@@ -0,0 +1,31 @@
+# `MD021` - Multiple spaces inside hashes on closed atx style heading
+
+Tags: `atx_closed`, `headers`, `headings`, `spaces`
+
+Aliases: `no-multiple-space-closed-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 a closed 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 ##
+```
+
+Note: this rule will fire if either side of the heading contains multiple
+spaces.
+
+Rationale: Extra space has no purpose and does not affect the rendering of
+content.

package/doc/md022.md

@@ -0,0 +1,46 @@
+# `MD022` - Headings should be surrounded by blank lines
+
+Tags: `blank_lines`, `headers`, `headings`
+
+Aliases: `blanks-around-headers`, `blanks-around-headings`
+
+Parameters:
+
+- `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:
+
+```markdown
+# Heading 1
+Some text
+
+Some more text
+## Heading 2
+```
+
+To fix this, ensure that all headings have a blank line both before and after
+(except where the heading is at the beginning or end of the document):
+
+```markdown
+# Heading 1
+
+Some text
+
+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.
+
+Note: If `lines_above` or `lines_below` are configured to require more than one
+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.

package/doc/md023.md

@@ -0,0 +1,26 @@
+# `MD023` - Headings must start at the beginning of the line
+
+Tags: `headers`, `headings`, `spaces`
+
+Aliases: `header-start-left`, `heading-start-left`
+
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when a heading is indented by one or more spaces:
+
+```markdown
+Some text
+
+  # Indented heading
+```
+
+To fix this, ensure that all headings start at the beginning of the line:
+
+```markdown
+Some text
+
+# Heading
+```
+
+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

@@ -0,0 +1,47 @@
+# `MD024` - Multiple headings with the same content
+
+Tags: `headers`, `headings`
+
+Aliases: `no-duplicate-header`, `no-duplicate-heading`
+
+Parameters:
+
+- `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:
+
+```markdown
+# Some text
+
+## Some text
+```
+
+To fix this, ensure that the content of each heading is different:
+
+```markdown
+# Some text
+
+## Some more text
+```
+
+If the parameter `siblings_only` (alternatively `allow_different_nesting`) is
+set to `true`, heading duplication is allowed for non-sibling headings (common
+in changelogs):
+
+```markdown
+# Change log
+
+## 1.0.0
+
+### Features
+
+## 2.0.0
+
+### Features
+```
+
+Rationale: Some Markdown parsers generate anchors for headings based on the
+heading name; headings with the same content can cause problems with that.

package/doc/md025.md

@@ -0,0 +1,49 @@
+# `MD025` - Multiple top-level headings in the same document
+
+Tags: `headers`, `headings`
+
+Aliases: `single-h1`, `single-title`
+
+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
+document:
+
+```markdown
+# Top level heading
+
+# Another top-level heading
+```
+
+To fix, structure your document so there is a single h1 heading that is
+the title for the document. Subsequent headings must be
+lower-level headings (h2, h3, etc.):
+
+```markdown
+# Title
+
+## Heading
+
+## Another heading
+```
+
+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`.
+
+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.

package/doc/md026.md

@@ -0,0 +1,41 @@
+# `MD026` - Trailing punctuation in heading
+
+Tags: `headers`, `headings`
+
+Aliases: `no-trailing-punctuation`
+
+Parameters:
+
+- `punctuation`: Punctuation characters not allowed at end of headings
+  (`string`, default `.,;:!。，；：！`)
+
+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:
+
+```markdown
+# This is a heading.
+```
+
+To fix this, remove the trailing punctuation:
+
+```markdown
+# This is a heading
+```
+
+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.
+
+Note: The trailing semicolon of [HTML entity references][html-entity-references]
+like `©`, `©`, and `©` is ignored by this rule.
+
+Rationale: Headings are not meant to be full sentences. More information:
+[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

package/doc/md027.md

@@ -0,0 +1,24 @@
+# `MD027` - Multiple spaces after blockquote symbol
+
+Tags: `blockquote`, `indentation`, `whitespace`
+
+Aliases: `no-multiple-space-blockquote`
+
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered when blockquotes have more than one space after the
+blockquote (`>`) symbol:
+
+```markdown
+>  This is a blockquote with bad indentation
+>  there should only be one.
+```
+
+To fix, remove any extraneous space:
+
+```markdown
+> This is a blockquote with correct
+> indentation.
+```
+
+Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md028.md

@@ -0,0 +1,40 @@
+# `MD028` - Blank line inside blockquote
+
+Tags: `blockquote`, `whitespace`
+
+Aliases: `no-blanks-blockquote`
+
+This rule is triggered when two blockquote blocks are separated by nothing
+except for a blank line:
+
+```markdown
+> This is a blockquote
+> which is immediately followed by
+
+> this blockquote. Unfortunately
+> In some parsers, these are treated as the same blockquote.
+```
+
+To fix this, ensure that any blockquotes that are right next to each other
+have some text in between:
+
+```markdown
+> This is a blockquote.
+
+And Jimmy also said:
+
+> This too is a blockquote.
+```
+
+Alternatively, if they are supposed to be the same quote, then add the
+blockquote symbol at the beginning of the blank line:
+
+```markdown
+> This is a blockquote.
+>
+> This is the same blockquote.
+```
+
+Rationale: Some Markdown parsers will treat two blockquotes separated by one
+or more blank lines as the same blockquote, while others will treat them as
+separate blockquotes.

package/doc/md029.md

@@ -0,0 +1,98 @@
+# `MD029` - Ordered list item prefix
+
+Tags: `ol`
+
+Aliases: `ol-prefix`
+
+Parameters:
+
+- `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
+configured style). The less-common pattern of using '0.' as a first prefix or
+for all prefixes is also supported.
+
+Example valid list if the style is configured as 'one':
+
+```markdown
+1. Do this.
+1. Do that.
+1. Done.
+```
+
+Examples of valid lists if the style is configured as 'ordered':
+
+```markdown
+1. Do this.
+2. Do that.
+3. Done.
+```
+
+```markdown
+0. Do this.
+1. Do that.
+2. Done.
+```
+
+All three examples are valid when the style is configured as 'one_or_ordered'.
+
+Example valid list if the style is configured as 'zero':
+
+```markdown
+0. Do this.
+0. Do that.
+0. Done.
+```
+
+Example invalid list for all styles:
+
+```markdown
+1. Do this.
+3. Done.
+```
+
+This rule supports 0-prefixing ordered list items for uniform indentation:
+
+```markdown
+...
+08. Item
+09. Item
+10. Item
+11. Item
+...
+```
+
+Note: This rule will report violations for cases like the following where an
+improperly-indented code block (or similar) appears between two list items and
+"breaks" the list in two:
+
+<!-- markdownlint-disable code-fence-style -->
+
+~~~markdown
+1. First list
+
+```text
+Code block
+```
+
+1. Second list
+~~~
+
+The fix is to indent the code block so it becomes part of the preceding list
+item as intended:
+
+~~~markdown
+1. First list
+
+   ```text
+   Code block
+   ```
+
+2. Still first list
+~~~
+
+<!-- markdownlint-restore -->
+
+Rationale: Consistent formatting makes it easier to understand a document.

package/doc/md030.md

@@ -0,0 +1,82 @@
+# `MD030` - Spaces after list markers
+
+Tags: `ol`, `ul`, `whitespace`
+
+Aliases: `list-marker-space`
+
+Parameters:
+
+- `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.
+
+The number of spaces checked for depends on the document style in use, but the
+default is 1 space after any list marker:
+
+```markdown
+* Foo
+* Bar
+* Baz
+
+1. Foo
+1. Bar
+1. Baz
+
+1. Foo
+   * Bar
+1. Baz
+```
+
+A document style may change the number of spaces after unordered list items
+and ordered list items independently, as well as based on whether the content
+of every item in the list consists of a single paragraph or multiple
+paragraphs (including sub-lists and code blocks).
+
+For example, the style guide at
+<https://cirosantilli.com/markdown-style-guide#spaces-after-list-marker>
+specifies that 1 space after the list marker should be used if every item in
+the list fits within a single paragraph, but to use 2 or 3 spaces (for ordered
+and unordered lists respectively) if there are multiple paragraphs of content
+inside the list:
+
+```markdown
+* Foo
+* Bar
+* Baz
+```
+
+vs.
+
+```markdown
+*   Foo
+
+    Second paragraph
+
+*   Bar
+```
+
+or
+
+```markdown
+1.  Foo
+
+    Second paragraph
+
+1.  Bar
+```
+
+To fix this, ensure the correct number of spaces are used after the list marker
+for your selected document style.
+
+Rationale: Violations of this rule can lead to improperly rendered content.
+
+Note: See [Prettier.md](Prettier.md) for compatibility information.

package/doc/md031.md

@@ -0,0 +1,50 @@
+# `MD031` - Fenced code blocks should be surrounded by blank lines
+
+Tags: `blank_lines`, `code`
+
+Aliases: `blanks-around-fences`
+
+Parameters:
+
+- `list_items`: Include list items (`boolean`, default `true`)
+
+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:
+
+````markdown
+Some text
+```
+Code block
+```
+
+```
+Another code block
+```
+Some more text
+````
+
+To fix this, ensure that all fenced code blocks have a blank line both before
+and after (except where the block is at the beginning or end of the document):
+
+````markdown
+Some text
+
+```
+Code block
+```
+
+```
+Another code block
+```
+
+Some more text
+````
+
+Set the `list_items` parameter to `false` to disable this rule for list items.
+Disabling this behavior for lists can be useful if it is necessary to create a
+[tight](https://spec.commonmark.org/0.29/#tight) list containing a code fence.
+
+Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
+not parse fenced code blocks that don't have blank lines before and after them.

package/doc/md032.md

@@ -0,0 +1,38 @@
+# `MD032` - Lists should be surrounded by blank lines
+
+Tags: `blank_lines`, `bullet`, `ol`, `ul`
+
+Aliases: `blanks-around-lists`
+
+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:
+
+```markdown
+Some text
+* Some
+* List
+
+1. Some
+2. List
+Some text
+```
+
+To fix this, ensure that all lists have a blank line both before and after
+(except where the block is at the beginning or end of the document):
+
+```markdown
+Some text
+
+* Some
+* List
+
+1. Some
+2. List
+
+Some text
+```
+
+Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
+not parse lists that don't have blank lines before and after them.

package/doc/md033.md

@@ -0,0 +1,27 @@
+# `MD033` - Inline HTML
+
+Tags: `html`
+
+Aliases: `no-inline-html`
+
+Parameters:
+
+- `allowed_elements`: Allowed elements (`string[]`, default `[]`)
+
+This rule is triggered whenever raw HTML is used in a Markdown document:
+
+```markdown
+<h1>Inline HTML heading</h1>
+```
+
+To fix this, use 'pure' Markdown instead of including raw HTML:
+
+```markdown
+# Markdown heading
+```
+
+Note: To allow specific HTML elements, use the `allowed_elements` parameter.
+
+Rationale: Raw HTML is allowed in Markdown, but this rule is included for
+those who want their documents to only include "pure" Markdown, or for those
+who are rendering Markdown documents into something other than HTML.

package/doc/md034.md

@@ -0,0 +1,44 @@
+# `MD034` - Bare URL used
+
+Tags: `links`, `url`
+
+Aliases: `no-bare-urls`
+
+Fixable: Some violations can be fixed by tooling
+
+This rule is triggered whenever a URL is given that isn't surrounded by angle
+brackets:
+
+```markdown
+For more information, see https://www.example.com/.
+```
+
+To fix this, add angle brackets around the URL:
+
+```markdown
+For more information, see <https://www.example.com/>.
+```
+
+Note: To use a bare URL without it being converted into a link, enclose it in
+a code block, otherwise in some Markdown parsers it *will* be converted:
+
+```markdown
+`https://www.example.com`
+```
+
+Note: The following scenario does *not* trigger this rule to avoid conflicts
+with `MD011`/`no-reversed-links`:
+
+```markdown
+[https://www.example.com]
+```
+
+The use of quotes around a bare link will *not* trigger this rule, either:
+
+```markdown
+"https://www.example.com"
+'https://www.example.com'
+```
+
+Rationale: Without angle brackets, the URL isn't converted into a link by many
+Markdown parsers.