Header levels should only increment by one level at a time Open
### Milestone 1: CF Applications -> Endpoint mgmt and Application views (Complete in Sprint 22)
- Read upRead up
- Exclude checks
MD001 - Header levels should only increment by one level at a time
Tags: headers
Aliases: header-increment
This rule is triggered when you skip header levels in a markdown document, for example:
# Header 1
### Header 3
We skipped out a 2nd level header in this document
When using multiple header levels, nested headers should increase by only one level at a time:
# Header 1
## Header 2
### Header 3
#### Header 4
## Another Header 2
### Another Header 3
Multiple top level headers in the same document Open
# Migration Milestones
- Read upRead up
- Exclude checks
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.
Spaces after list markers Open
- Cloud Foundry View (excluding "assign users")
- Read upRead up
- Exclude checks
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.
Lists should be surrounded by blank lines Open
- Back-end stays the same (folder structure will most likely be moved around)
- Read upRead up
- Exclude checks
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
Trailing punctuation in header Open
### To be scheduled into Milestones:
- Read upRead up
- Exclude checks
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.
Multiple consecutive blank lines Open
- Read upRead up
- Exclude checks
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.