MD022 - Headers should be surrounded by blank lines

Tags: headers, blank_lines

Aliases: blanks-around-headers

This rule is triggered when headers (any style) are either not preceded or not followed by a blank line:

# Header 1
Some text

Some more text
## Header 2

To fix this, ensure that all headers have a blank line both before and after (except where the header is at the beginning or end of the document):

# Header 1

Some text

Some more text

## Header 2

Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will not parse headers that don't have a blank line before, and will parse them as regular text.

MD026 - Trailing punctuation in header

Tags: headers

Aliases: no-trailing-punctuation

Parameters: punctuation (string; default ".,;:!?")

This rule is triggered on any header that has a punctuation character as the last character in the line:

# This is a header.

To fix this, remove any trailing punctuation:

# This is a header

Note: The punctuation parameter can be used to specify what characters class as punctuation at the end of the header. For example, you can set it to '.,;:!' to allow headers with question marks in them, such as might be used in an FAQ.

MD005 - Inconsistent indentation for list items at the same level

Tags: bullet, ul, indentation

Aliases: list-indent

This rule is triggered when list items are parsed as being at the same level, but don't have the same indentation:

* 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:

* Item 1
  * Nested Item 1
  * Nested Item 2
  * Nested Item 3

MD005 - Inconsistent indentation for list items at the same level

Tags: bullet, ul, indentation

Aliases: list-indent

This rule is triggered when list items are parsed as being at the same level, but don't have the same indentation:

* 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:

* Item 1
  * Nested Item 1
  * Nested Item 2
  * Nested Item 3

MD007 - Unordered list indentation

Tags: bullet, ul, indentation

Aliases: ul-indent

Parameters: indent (number; default 2)

This rule is triggered when list items are not indented by the configured number of spaces (default: 2).

Example:

* List item
   * Nested list item indented by 3 spaces

Corrected Example:

* List item
  * Nested list item indented by 2 spaces

Rationale (2 space indent): 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.

Rationale (4 space indent): Same indent as code blocks, simpler for editors to implement. See http://www.cirosantilli.com/markdown-styleguide/#indented-lists for more information.

In addition, this is a compatibility issue with multi-markdown parsers, which require a 4 space indents. See http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting for a description of the problem.

Limit all lines to a maximum of 79 characters.

There are still many devices around that are limited to 80 character
lines; plus, limiting windows to 80 characters makes it possible to
have several windows side-by-side.  The default wrapping on such
devices looks ugly.  Therefore, please limit all lines to a maximum
of 79 characters. For flowing long blocks of text (docstrings or
comments), limiting the length to 72 characters is recommended.

Reports error E501.

Limit all lines to a maximum of 79 characters.

There are still many devices around that are limited to 80 character
lines; plus, limiting windows to 80 characters makes it possible to
have several windows side-by-side.  The default wrapping on such
devices looks ugly.  Therefore, please limit all lines to a maximum
of 79 characters. For flowing long blocks of text (docstrings or
comments), limiting the length to 72 characters is recommended.

Reports error E501.

Limit all lines to a maximum of 79 characters.

There are still many devices around that are limited to 80 character
lines; plus, limiting windows to 80 characters makes it possible to
have several windows side-by-side.  The default wrapping on such
devices looks ugly.  Therefore, please limit all lines to a maximum
of 79 characters. For flowing long blocks of text (docstrings or
comments), limiting the length to 72 characters is recommended.

Reports error E501.

MD041 - First line in file should be a top level header

Tags: headers

Aliases: first-line-h1

Parameters: level (number; default 1)

This rule is triggered when the first line in the file isn't a top level (h1) header:

```
This is a file without a header
```

To fix this, add a header to the top of your file:

```
# File with header

This is a file with a top level header
```

Note: The level parameter can be used to change the top level (ex: to h2) in cases where an h1 is added externally.

MD029 - Ordered list item prefix

Tags: ol

Aliases: ol-prefix

Parameters: style ("one", "ordered"; default "one")

This rule is triggered on 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, which defaults to 'one').

Example valid list if the style is configured as 'one':

1. Do this.
1. Do that.
1. Done.

Example valid list if the style is configured as 'ordered':

1. Do this.
2. Do that.
3. Done.

MD031 - Fenced code blocks should be surrounded by blank lines

Tags: code, blank_lines

Aliases: blanks-around-fences

This rule is triggered when fenced code blocks are either not preceded or not followed by a blank line:

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):

Some text

```
Code block
```

```
Another code block
```

Some more text

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.

MD032 - Lists should be surrounded by blank lines

Tags: bullet, ul, ol, blank_lines

Aliases: blanks-around-lists

This rule is triggered when lists (of any kind) are either not preceded or not followed by a blank line:

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):

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.

Note: List items without hanging indents are a violation of this rule; list items with hanging indents are okay:

* This is
not okay

* This is
  okay

Limit all lines to a maximum of 79 characters.

There are still many devices around that are limited to 80 character
lines; plus, limiting windows to 80 characters makes it possible to
have several windows side-by-side.  The default wrapping on such
devices looks ugly.  Therefore, please limit all lines to a maximum
of 79 characters. For flowing long blocks of text (docstrings or
comments), limiting the length to 72 characters is recommended.

Reports error E501.

Limit all lines to a maximum of 79 characters.

There are still many devices around that are limited to 80 character
lines; plus, limiting windows to 80 characters makes it possible to
have several windows side-by-side.  The default wrapping on such
devices looks ugly.  Therefore, please limit all lines to a maximum
of 79 characters. For flowing long blocks of text (docstrings or
comments), limiting the length to 72 characters is recommended.

Reports error E501.

Limit all lines to a maximum of 79 characters.

There are still many devices around that are limited to 80 character
lines; plus, limiting windows to 80 characters makes it possible to
have several windows side-by-side.  The default wrapping on such
devices looks ugly.  Therefore, please limit all lines to a maximum
of 79 characters. For flowing long blocks of text (docstrings or
comments), limiting the length to 72 characters is recommended.

Reports error E501.

MD012 - Multiple consecutive blank lines

Tags: whitespace, blank_lines

Aliases: no-multiple-blanks

This rule is triggered when there are multiple consecutive blank lines in the document:

Some text here


Some more text here

To fix this, delete the offending lines:

Some text here

Some more text here

Note: this rule will not be triggered if there are multiple consecutive blank lines inside code blocks.

MD034 - Bare URL used

Tags: links, url

Aliases: no-bare-urls

This rule is triggered whenever a URL is given that isn't surrounded by angle brackets:

For more information, see http://www.example.com/.

To fix this, add angle brackets around the URL:

For more information, see <http:></http:>.

Rationale: Without angle brackets, the URL isn't converted into a link in many markdown parsers.

Note: if you do want 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:

`http://www.example.com`

MD004 - Unordered list style

Tags: bullet, ul

Aliases: ul-style

Parameters: style ("consistent", "asterisk", "plus", "dash"; default "consistent")

This rule is triggered when the symbols used in the document for unordered list items do not match the configured unordered list style:

* Item 1
+ Item 2
- Item 3

To fix this issue, use the configured style for list items throughout the document:

* Item 1
* Item 2
* Item 3

Note: the configured list style can be a specific symbol to use (asterisk, plus, dash), or simply require that the usage be consistent within the document.

MD007 - Unordered list indentation

Tags: bullet, ul, indentation

Aliases: ul-indent

Parameters: indent (number; default 2)

This rule is triggered when list items are not indented by the configured number of spaces (default: 2).

Example:

* List item
   * Nested list item indented by 3 spaces

Corrected Example:

* List item
  * Nested list item indented by 2 spaces

Rationale (2 space indent): 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.

Rationale (4 space indent): Same indent as code blocks, simpler for editors to implement. See http://www.cirosantilli.com/markdown-styleguide/#indented-lists for more information.

In addition, this is a compatibility issue with multi-markdown parsers, which require a 4 space indents. See http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting for a description of the problem.

MD012 - Multiple consecutive blank lines

Tags: whitespace, blank_lines

Aliases: no-multiple-blanks

This rule is triggered when there are multiple consecutive blank lines in the document:

Some text here


Some more text here

To fix this, delete the offending lines:

Some text here

Some more text here

Note: this rule will not be triggered if there are multiple consecutive blank lines inside code blocks.