MD009 - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters: br_spaces (number; default: 0)

This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.

The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.

Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.

MD009 - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters: br_spaces (number; default: 0)

This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.

The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.

Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.

MD014 - Dollar signs used before commands without showing output

Tags: code

Aliases: commands-show-output

This rule is triggered when there are code blocks showing shell commands to be typed, and the shell commands are preceded by dollar signs ($):

$ ls
$ cat foo
$ less bar

The dollar signs are unnecessary in the above situation, and should not be included:

ls
cat foo
less bar

However, an exception is made when there is a need to distinguish between typed commands and command output, as in the following example:

$ ls
foo bar
$ cat foo
Hello world
$ cat bar
baz

Rationale: it is easier to copy and paste and less noisy if the dollar signs are omitted when they are not needed. See http://www.cirosantilli.com/markdown-styleguide/#dollar-signs-in-shell-code for more information.

MD033 - Inline HTML

Tags: html

Aliases: no-inline-html

This rule is triggered whenever raw HTML is used in a markdown document:

Inline HTML header

To fix this, use 'pure' markdown instead of including raw HTML:

# Markdown header

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 in something other than HTML.

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.

MD009 - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters: br_spaces (number; default: 0)

This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.

The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.

Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.

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.

MD013 - Line length

Tags: line_length

Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)

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.

This rule has an exception where 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.

You also have the option to exclude this rule for code blocks and tables. To do this, set the code_blocks and/or tables parameters 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.

MD014 - Dollar signs used before commands without showing output

Tags: code

Aliases: commands-show-output

This rule is triggered when there are code blocks showing shell commands to be typed, and the shell commands are preceded by dollar signs ($):

$ ls
$ cat foo
$ less bar

The dollar signs are unnecessary in the above situation, and should not be included:

ls
cat foo
less bar

However, an exception is made when there is a need to distinguish between typed commands and command output, as in the following example:

$ ls
foo bar
$ cat foo
Hello world
$ cat bar
baz

Rationale: it is easier to copy and paste and less noisy if the dollar signs are omitted when they are not needed. See http://www.cirosantilli.com/markdown-styleguide/#dollar-signs-in-shell-code for more information.

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.

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.

MD009 - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters: br_spaces (number; default: 0)

This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.

The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.

Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.

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.

MD009 - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters: br_spaces (number; default: 0)

This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.

The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.

Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.

MD009 - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters: br_spaces (number; default: 0)

This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.

The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.

Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.

MD014 - Dollar signs used before commands without showing output

Tags: code

Aliases: commands-show-output

This rule is triggered when there are code blocks showing shell commands to be typed, and the shell commands are preceded by dollar signs ($):

$ ls
$ cat foo
$ less bar

The dollar signs are unnecessary in the above situation, and should not be included:

ls
cat foo
less bar

However, an exception is made when there is a need to distinguish between typed commands and command output, as in the following example:

$ ls
foo bar
$ cat foo
Hello world
$ cat bar
baz

Rationale: it is easier to copy and paste and less noisy if the dollar signs are omitted when they are not needed. See http://www.cirosantilli.com/markdown-styleguide/#dollar-signs-in-shell-code for more information.

MD033 - Inline HTML

Tags: html

Aliases: no-inline-html

This rule is triggered whenever raw HTML is used in a markdown document:

Inline HTML header

To fix this, use 'pure' markdown instead of including raw HTML:

# Markdown header

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 in something other than HTML.

MD009 - Trailing spaces

Tags: whitespace

Aliases: no-trailing-spaces

Parameters: br_spaces (number; default: 0)

This rule is triggered on any lines that end with whitespace. To fix this, find the line that is triggered and remove any trailing spaces from the end.

The brspaces parameter allows an exception to this rule for a specific amount of trailing spaces used to insert an explicit line break/br element. For example, set brspaces to 2 to allow exactly 2 spaces at the end of a line.

Note: you have to set brspaces to 2 or higher for this exception to take effect - you can't insert a br element with just a single trailing space, so if you set brspaces to 1, the exception will be disabled, just as if it was set to the default of 0.

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.

MD013 - Line length

Tags: line_length

Aliases: line-length Parameters: linelength, codeblocks, tables (number; default 80, boolean; default true)

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.

This rule has an exception where 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.

You also have the option to exclude this rule for code blocks and tables. To do this, set the code_blocks and/or tables parameters 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.