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.

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

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

MD030 - Spaces after list markers

Tags: ol, ul, whitespace

Aliases: list-marker-space

Parameters: ulsingle, olsingle, ulmulti, olmulti (number, default 1)

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:

* 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 http://www.cirosantilli.com/markdown-styleguide/#spaces-after-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:

* Foo
* Bar
* Baz

vs.

*   Foo

    Second paragraph

*   Bar

or

1.  Foo

    Second paragraph

1.  Bar

To fix this, ensure the correct number of spaces are used after list marker for your selected document style.

MD030 - Spaces after list markers

Tags: ol, ul, whitespace

Aliases: list-marker-space

Parameters: ulsingle, olsingle, ulmulti, olmulti (number, default 1)

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:

* 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 http://www.cirosantilli.com/markdown-styleguide/#spaces-after-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:

* Foo
* Bar
* Baz

vs.

*   Foo

    Second paragraph

*   Bar

or

1.  Foo

    Second paragraph

1.  Bar

To fix this, ensure the correct number of spaces are used after list marker for your selected document style.

MD025 - Multiple top level headers in the same document

Tags: headers

Aliases: single-h1

Parameters: level (number; default 1)

This rule is triggered when a top level header is in use (the first line of the file is a h1 header), and more than one h1 header is in use in the document:

# Top level header

# Another top level header

To fix, structure your document so that there is a single h1 header that is the title for the document, and all later headers are h2 or lower level headers:

# Title

## Header

## Another header

Rationale: A top level header is a 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 header.

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

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

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

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

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

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

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