Split rule documentation into separate files

README.md

@@ -45,48 +45,46 @@ playground for learning and exploring.
 
 ## Rules / Aliases
 
-* **MD001** *header-increment* - Header levels should only increment by one level at a time
-* **MD002** *first-header-h1* - First header should be a top level header
-* **MD003** *header-style* - Header style
-* **MD004** *ul-style* - Unordered list style
-* **MD005** *list-indent* - Inconsistent indentation for list items at the same level
-* **MD006** *ul-start-left* - Consider starting bulleted lists at the beginning of the line
-* **MD007** *ul-indent* - Unordered list indentation
-* **MD009** *no-trailing-spaces* - Trailing spaces
-* **MD010** *no-hard-tabs* - Hard tabs
-* **MD011** *no-reversed-links* - Reversed link syntax
-* **MD012** *no-multiple-blanks* - Multiple consecutive blank lines
-* **MD013** *line-length* - Line length
-* **MD014** *commands-show-output* - Dollar signs used before commands without showing output
-* **MD018** *no-missing-space-atx* - No space after hash on atx style header
-* **MD019** *no-multiple-space-atx* - Multiple spaces after hash on atx style header
-* **MD020** *no-missing-space-closed-atx* - No space inside hashes on closed atx style header
-* **MD021** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style header
-* **MD022** *blanks-around-headers* - Headers should be surrounded by blank lines
-* **MD023** *header-start-left* - Headers must start at the beginning of the line
-* **MD024** *no-duplicate-header* - Multiple headers with the same content
-* **MD025** *single-h1* - Multiple top level headers in the same document
-* **MD026** *no-trailing-punctuation* - Trailing punctuation in header
-* **MD027** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol
-* **MD028** *no-blanks-blockquote* - Blank line inside blockquote
-* **MD029** *ol-prefix* - Ordered list item prefix
-* **MD030** *list-marker-space* - Spaces after list markers
-* **MD031** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines
-* **MD032** *blanks-around-lists* - Lists should be surrounded by blank lines
-* **MD033** *no-inline-html* - Inline HTML
-* **MD034** *no-bare-urls* - Bare URL used
-* **MD035** *hr-style* - Horizontal rule style
-* **MD036** *no-emphasis-as-header* - Emphasis used instead of a header
-* **MD037** *no-space-in-emphasis* - Spaces inside emphasis markers
-* **MD038** *no-space-in-code* - Spaces inside code span elements
-* **MD039** *no-space-in-links* - Spaces inside link text
-* **MD040** *fenced-code-language* - Fenced code blocks should have a language specified
-* **MD041** *first-line-h1* - First line in file should be a top level header
-* **MD042** *no-empty-links* - No empty links
-* **MD043** *required-headers* - Required header structure
-* **MD044** *proper-names* - Proper names should have the correct capitalization
-
-See [Rules.md](doc/Rules.md) for more details.
+* **[MD001](doc/MD001.md)** *header-increment* - Header levels should only increment by one level at a time
+* **[MD002](doc/MD002.md)** *first-header-h1* - First header should be a top level header
+* **[MD003](doc/MD003.md)** *header-style* - Header style
+* **[MD004](doc/MD004.md)** *ul-style* - Unordered list style
+* **[MD005](doc/MD005.md)** *list-indent* - Inconsistent indentation for list items at the same level
+* **[MD006](doc/MD006.md)** *ul-start-left* - Consider starting bulleted lists at the beginning of the line
+* **[MD007](doc/MD007.md)** *ul-indent* - Unordered list indentation
+* **[MD009](doc/MD009.md)** *no-trailing-spaces* - Trailing spaces
+* **[MD010](doc/MD010.md)** *no-hard-tabs* - Hard tabs
+* **[MD011](doc/MD011.md)** *no-reversed-links* - Reversed link syntax
+* **[MD012](doc/MD012.md)** *no-multiple-blanks* - Multiple consecutive blank lines
+* **[MD013](doc/MD013.md)** *line-length* - Line length
+* **[MD014](doc/MD014.md)** *commands-show-output* - Dollar signs used before commands without showing output
+* **[MD018](doc/MD018.md)** *no-missing-space-atx* - No space after hash on atx style header
+* **[MD019](doc/MD019.md)** *no-multiple-space-atx* - Multiple spaces after hash on atx style header
+* **[MD020](doc/MD020.md)** *no-missing-space-closed-atx* - No space inside hashes on closed atx style header
+* **[MD021](doc/MD021.md)** *no-multiple-space-closed-atx* - Multiple spaces inside hashes on closed atx style header
+* **[MD022](doc/MD022.md)** *blanks-around-headers* - Headers should be surrounded by blank lines
+* **[MD023](doc/MD023.md)** *header-start-left* - Headers must start at the beginning of the line
+* **[MD024](doc/MD024.md)** *no-duplicate-header* - Multiple headers with the same content
+* **[MD025](doc/MD025.md)** *single-h1* - Multiple top level headers in the same document
+* **[MD026](doc/MD026.md)** *no-trailing-punctuation* - Trailing punctuation in header
+* **[MD027](doc/MD027.md)** *no-multiple-space-blockquote* - Multiple spaces after blockquote symbol
+* **[MD028](doc/MD028.md)** *no-blanks-blockquote* - Blank line inside blockquote
+* **[MD029](doc/MD029.md)** *ol-prefix* - Ordered list item prefix
+* **[MD030](doc/MD030.md)** *list-marker-space* - Spaces after list markers
+* **[MD031](doc/MD031.md)** *blanks-around-fences* - Fenced code blocks should be surrounded by blank lines
+* **[MD032](doc/MD032.md)** *blanks-around-lists* - Lists should be surrounded by blank lines
+* **[MD033](doc/MD033.md)** *no-inline-html* - Inline HTML
+* **[MD034](doc/MD034.md)** *no-bare-urls* - Bare URL used
+* **[MD035](doc/MD035.md)** *hr-style* - Horizontal rule style
+* **[MD036](doc/MD036.md)** *no-emphasis-as-header* - Emphasis used instead of a header
+* **[MD037](doc/MD037.md)** *no-space-in-emphasis* - Spaces inside emphasis markers
+* **[MD038](doc/MD038.md)** *no-space-in-code* - Spaces inside code span elements
+* **[MD039](doc/MD039.md)** *no-space-in-links* - Spaces inside link text
+* **[MD040](doc/MD040.md)** *fenced-code-language* - Fenced code blocks should have a language specified
+* **[MD041](doc/MD041.md)** *first-line-h1* - First line in file should be a top level header
+* **[MD042](doc/MD042.md)** *no-empty-links* - No empty links
+* **[MD043](doc/MD043.md)** *required-headers* - Required header structure
+* **[MD044](doc/MD044.md)** *proper-names* - Proper names should have the correct capitalization
 
 ## Tags
 

doc/MD001.md

@@ -0,0 +1,29 @@
+# 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

doc/MD002.md

@@ -0,0 +1,22 @@
+# MD002 - First header should be a top level header
+
+Tags: headers
+
+Aliases: first-header-h1
+
+Parameters: level (number; default 1)
+
+This rule is triggered when the first header in the document isn't a h1 header:
+
+    ## This isn't a H1 header
+
+    ### Another header
+
+The first header in the document should be a h1 header:
+
+    # Start with a H1 header
+
+    ## Then use a H2 for subsections
+
+Note: The `level` parameter can be used to change the top level (ex: to h2) in
+cases where an h1 is added externally.

doc/MD003.md

@@ -0,0 +1,39 @@
+# MD003 - Header style
+
+Tags: headers
+
+Aliases: header-style
+
+Parameters: style ("consistent", "atx", "atx_closed", "setext",
+"setext_with_atx", "setext_with_atx_closed"; default "consistent")
+
+This rule is triggered when different header styles (atx, setext, and 'closed'
+atx) are used in the same document:
+
+    # ATX style H1
+
+    ## Closed ATX style H2 ##
+
+    Setext style H1
+    ===============
+
+Be consistent with the style of header used in a document:
+
+    # ATX style H1
+
+    ## ATX style H2
+
+The setext_with_atx and settext_with_atx_closed doc styles allow atx-style
+headers of level 3 or more in documents with setext style headers:
+
+    Setext style H1
+    ===============
+
+    Setext style H2
+    ---------------
+
+    ### ATX style H3
+
+Note: the configured header style can be a specific style to use (atx,
+atx_closed, setext, setext_with_atx, setext_with_atx_closed), or simply require
+that the usage be consistent within the document.

doc/MD004.md

@@ -0,0 +1,36 @@
+# MD004 - Unordered list style
+
+Tags: bullet, ul
+
+Aliases: ul-style
+
+Parameters: style ("consistent", "asterisk", "plus", "dash", "sublist"; 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
+
+The configured list style can be a specific symbol to use (asterisk, plus, dash),
+can require that usage be consistent within the document, or can require that each
+sublist have a consistent symbol that is different from its parent list.
+
+For example, the following is valid for the `sublist` style because the outer-most
+indent uses asterisk, the middle indent uses plus, and the inner-most indent uses dash:
+
+    * Item 1
+      + Item 2
+        - Item 3
+      + Item 4
+    * Item 4
+      + Item 5

doc/MD005.md

@@ -0,0 +1,21 @@
+# 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

doc/MD006.md

@@ -0,0 +1,36 @@
+# MD006 - Consider starting bulleted lists at the beginning of the line
+
+Tags: bullet, ul, indentation
+
+Aliases: ul-start-left
+
+This rule is triggered when top level lists don't start at the beginning of a
+line:
+
+    Some text
+
+      * List item
+      * List item
+
+To fix, ensure that top level list items are not indented:
+
+    Some test
+
+    * List item
+    * List item
+
+Rationale: Starting lists at the beginning of the line means that nested list
+items can all be indented by the same amount when an editor's indent function
+or the tab key is used to indent. Starting a list 1 space in means that the
+indent of the first nested list is less than the indent of the second level (3
+characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
+
+Note: This rule is triggered for the following scenario because the unordered
+sublist is not recognized as such by the parser. Not being nested 3 characters
+as required by the outer ordered list, it creates a top-level unordered list
+instead.
+
+    1. List item
+      - List item
+      - List item
+    1. List item

doc/MD007.md

@@ -0,0 +1,38 @@
+# 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.
+
+Note: This rule applies to a sublist only if its parent lists are all also
+unordered (otherwise, extra indentation of ordered lists interferes with the
+rule).

doc/MD009.md

@@ -0,0 +1,19 @@
+# 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 br_spaces 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 br_spaces to 2 to allow exactly 2 spaces at the end of a line.
+
+Note: you have to set br_spaces 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 br_spaces to 1, the exception will be disabled, just as if it was
+set to the default of 0.

doc/MD010.md

@@ -0,0 +1,27 @@
+# MD010 - Hard tabs
+
+Tags: whitespace, hard_tab
+
+Aliases: no-hard-tabs
+
+Parameters: code_blocks (boolean; default true)
+
+This rule is triggered by any lines that contain hard tab characters instead
+of using spaces for indentation. To fix this, replace any hard tab characters
+with spaces instead.
+
+Example:
+
+    Some text
+
+    	* hard tab character used to indent the list item
+
+Corrected example:
+
+    Some text
+
+        * Spaces used to indent the list item instead
+
+You have the option to exclude this rule for code blocks. To do so, set the
+`code_blocks` parameter to `false`. Code blocks are included by default since
+handling of tabs by tools is often inconsistent (ex: using 4 vs. 8 spaces).

doc/MD011.md

@@ -0,0 +1,19 @@
+# MD011 - Reversed link syntax
+
+Tags: links
+
+Aliases: no-reversed-links
+
+This rule is triggered when text that appears to be a link is encountered, but
+where the syntax appears to have been reversed (the `[]` and `()` are
+reversed):
+
+    (Incorrect link syntax)[http://www.example.com/]
+
+To fix this, swap the `[]` and `()` around:
+
+    [Correct link syntax](http://www.example.com/)
+
+Note: [Markdown Extra](https://en.wikipedia.org/wiki/Markdown_Extra)-style footnotes do not trigger this rule:
+
+    For (example)[^1]

doc/MD012.md

@@ -0,0 +1,27 @@
+# MD012 - Multiple consecutive blank lines
+
+Tags: whitespace, blank_lines
+
+Aliases: no-multiple-blanks
+
+Parameters: maximum (number; default 1)
+
+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.
+
+Note: The `maximum` parameter can be used to configure the maximum number of
+consecutive blank lines.

doc/MD013.md

@@ -0,0 +1,22 @@
+# MD013 - Line length
+
+Tags: line_length
+
+Aliases: line-length
+
+Parameters: line_length, code_blocks, tables, headers (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 have the option to exclude this rule for code blocks, tables, or headers.
+To do so, set the `code_blocks`, `tables`, or `headers` parameter(s) 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.

doc/MD014.md

@@ -0,0 +1,34 @@
+# 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.

doc/MD018.md

@@ -0,0 +1,19 @@
+# MD018 - No space after hash on atx style header
+
+Tags: headers, atx, spaces
+
+Aliases: no-missing-space-atx
+
+This rule is triggered when spaces are missing after the hash characters
+in an atx style header:
+
+    #Header 1
+
+    ##Header 2
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+    # Header 1
+
+    ## Header 2

doc/MD019.md

@@ -0,0 +1,19 @@
+# MD019 - Multiple spaces after hash on atx style header
+
+Tags: headers, atx, spaces
+
+Aliases: no-multiple-space-atx
+
+This rule is triggered when more than one space is used to separate the
+header text from the hash characters in an atx style header:
+
+    #  Header 1
+
+    ##  Header 2
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+    # Header 1
+
+    ## Header 2

doc/MD020.md

@@ -0,0 +1,21 @@
+# MD020 - No space inside hashes on closed atx style header
+
+Tags: headers, atx_closed, spaces
+
+Aliases: no-missing-space-closed-atx
+
+This rule is triggered when spaces are missing inside the hash characters
+in a closed atx style header:
+
+    #Header 1#
+
+    ##Header 2##
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+    # Header 1 #
+
+    ## Header 2 ##
+
+Note: this rule will fire if either side of the header is missing spaces.

doc/MD021.md

@@ -0,0 +1,22 @@
+# MD021 - Multiple spaces inside hashes on closed atx style header
+
+Tags: headers, atx_closed, spaces
+
+Aliases: no-multiple-space-closed-atx
+
+This rule is triggered when more than one space is used to separate the
+header text from the hash characters in a closed atx style header:
+
+    #  Header 1  #
+
+    ##  Header 2  ##
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+    # Header 1 #
+
+    ## Header 2 ##
+
+Note: this rule will fire if either side of the header contains multiple
+spaces.

doc/MD022.md

@@ -0,0 +1,29 @@
+# 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.

doc/MD023.md

@@ -0,0 +1,20 @@
+# MD023 - Headers must start at the beginning of the line
+
+Tags: headers, spaces
+
+Aliases: header-start-left
+
+This rule is triggered when a header is indented by one or more spaces:
+
+    Some text
+
+      # Indented header
+
+To fix this, ensure that all headers start at the beginning of the line:
+
+    Some text
+
+    # Header
+
+Rationale: Headers that don't start at the beginning of the line will not be
+parsed as headers, and will instead appear as regular text.

doc/MD024.md

@@ -0,0 +1,22 @@
+# MD024 - Multiple headers with the same content
+
+Tags: headers
+
+Aliases: no-duplicate-header
+
+This rule is triggered if there are multiple headers in the document that have
+the same text:
+
+    # Some text
+
+    ## Some text
+
+To fix this, ensure that the content of each header is different:
+
+    # Some text
+
+    ## Some more text
+
+Rationale: Some markdown parses generate anchors for headers based on the
+header name, and having headers with the same content can cause problems with
+this.

doc/MD025.md

@@ -0,0 +1,33 @@
+# 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.

doc/MD026.md

@@ -0,0 +1,21 @@
+# 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.

doc/MD027.md

@@ -0,0 +1,16 @@
+# MD027 - Multiple spaces after blockquote symbol
+
+Tags: blockquote, whitespace, indentation
+
+Aliases: no-multiple-space-blockquote
+
+This rule is triggered when blockquotes have more than one space after the
+blockquote (`>`) symbol:
+
+    >  This is a block quote with bad indentation
+    >  there should only be one.
+
+To fix, remove any extraneous space:
+
+    > This is a blockquote with correct
+    > indentation.

doc/MD028.md

@@ -0,0 +1,34 @@
+# 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:
+
+    > 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:
+
+    > 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:
+
+    > 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.

doc/MD029.md

@@ -0,0 +1,23 @@
+# 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.

doc/MD030.md

@@ -0,0 +1,60 @@
+# MD030 - Spaces after list markers
+
+Tags: ol, ul, whitespace
+
+Aliases: list-marker-space
+
+Parameters: ul_single, ol_single, ul_multi, ol_multi (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.

doc/MD031.md

@@ -0,0 +1,36 @@
+# 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.

doc/MD032.md

@@ -0,0 +1,41 @@
+# 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

doc/MD033.md

@@ -0,0 +1,21 @@
+# MD033 - Inline HTML
+
+Tags: html
+
+Aliases: no-inline-html
+
+Parameters: allowed_elements (array of string; default empty)
+
+This rule is triggered whenever raw HTML is used in a markdown document:
+
+    <h1>Inline HTML header</h1>
+
+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.
+
+Note: To allow specific HTML elements, use the 'allowed_elements' parameter.

doc/MD034.md

@@ -0,0 +1,23 @@
+# 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://www.example.com/>.
+
+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`

doc/MD035.md

@@ -0,0 +1,35 @@
+# MD035 - Horizontal rule style
+
+Tags: hr
+
+Aliases: hr-style
+
+Parameters: style ("consistent", "---", "***", or other string specifying the
+horizontal rule; default "consistent")
+
+This rule is triggered when inconsistent styles of horizontal rules are used
+in the document:
+
+    ---
+
+    - - -
+
+    ***
+
+    * * *
+
+    ****
+
+To fix this, ensure any horizontal rules used in the document are consistent,
+or match the given style if the rule is so configured:
+
+    ---
+
+    ---
+
+Note: by default, this rule is configured to just require that all horizontal
+rules in the document are the same, and will trigger if any of the horizontal
+rules are different than the first one encountered in the document. If you
+want to configure the rule to match a specific style, the parameter given to
+the 'style' option is a string containing the exact horizontal rule text that
+is allowed.

doc/MD036.md

@@ -0,0 +1,35 @@
+# MD036 - Emphasis used instead of a header
+
+Tags: headers, emphasis
+
+Aliases: no-emphasis-as-header
+
+Parameters: punctuation (string; default ".,;:!?")
+
+This check looks for instances where emphasized (i.e. bold or italic) text is
+used to separate sections, where a header should be used instead:
+
+    **My document**
+
+    Lorem ipsum dolor sit amet...
+
+    _Another section_
+
+    Consectetur adipiscing elit, sed do eiusmod.
+
+To fix this, use markdown headers instead of emphasized text to denote
+sections:
+
+    # My document
+
+    Lorem ipsum dolor sit amet...
+
+    ## Another section
+
+    Consectetur adipiscing elit, sed do eiusmod.
+
+Note: this rule looks for single line paragraphs that consist entirely of
+emphasized text.  It won't fire on emphasis used within regular text,
+multi-line emphasized paragraphs, and paragraphs ending in punctuation.
+Similarly to rule MD026, you can configure what characters are recognized as
+punctuation.

doc/MD037.md

@@ -0,0 +1,31 @@
+# MD037 - Spaces inside emphasis markers
+
+Tags: whitespace, emphasis
+
+Aliases: no-space-in-emphasis
+
+This rule is triggered when emphasis markers (bold, italic) are used, but they
+have spaces between the markers and the text:
+
+    Here is some ** bold ** text.
+
+    Here is some * italic * text.
+
+    Here is some more __ bold __ text.
+
+    Here is some more _ italic _ text.
+
+To fix this, remove the spaces around the emphasis markers:
+
+    Here is some **bold** text.
+
+    Here is some *italic* text.
+
+    Here is some more __bold__ text.
+
+    Here is some more _italic_ text.
+
+Rationale: Emphasis is only parsed as such when the asterisks/underscores
+aren't completely surrounded by spaces. This rule attempts to detect where
+they were surrounded by spaces, but it appears that emphasized text was
+intended by the author.

doc/MD038.md

@@ -0,0 +1,23 @@
+# MD038 - Spaces inside code span elements
+
+Tags: whitespace, code
+
+Aliases: no-space-in-code
+
+This rule is triggered on code span elements that have spaces right inside the
+backticks:
+
+    ` some text `
+
+    `some text `
+
+    ` some text`
+
+To fix this, remove the spaces inside the codespan markers:
+
+    `some text`
+
+Note: A single leading or trailing space is allowed if used to separate codespan
+markers from an embedded backtick:
+
+    `` ` embedded backtick``

doc/MD039.md

@@ -0,0 +1,13 @@
+# MD039 - Spaces inside link text
+
+Tags: whitespace, links
+
+Aliases: no-space-in-links
+
+This rule is triggered on links that have spaces surrounding the link text:
+
+    [ a link ](http://www.example.com/)
+
+To fix this, remove the spaces surrounding the link text:
+
+    [a link](http://www.example.com/)

doc/MD040.md

@@ -0,0 +1,20 @@
+# MD040 - Fenced code blocks should have a language specified
+
+Tags: code, language
+
+Aliases: fenced-code-language
+
+This rule is triggered when fenced code blocks are used, but a language isn't
+specified:
+
+    ```
+    #!/bin/bash
+    echo Hello world
+    ```
+
+To fix this, add a language specifier to the code block:
+
+    ```bash
+    #!/bin/bash
+    echo Hello world
+    ```

doc/MD041.md

@@ -0,0 +1,21 @@
+# 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.

doc/MD042.md

@@ -0,0 +1,21 @@
+# MD042 - No empty links
+
+Tags: links
+
+Aliases: no-empty-links
+
+This rule is triggered when an empty link is encountered:
+
+    [an empty link]()
+
+To fix the violation, provide a destination for the link:
+
+    [a valid link](https://example.com/)
+
+Empty fragments will trigger this rule:
+
+    [an empty fragment](#)
+
+But non-empty fragments will not:
+
+    [a valid fragment](#fragment)

doc/MD043.md

@@ -0,0 +1,50 @@
+# MD043 - Required header structure
+
+Tags: headers
+
+Aliases: required-headers
+
+Parameters: headers (array of string; default `null` for disabled)
+
+This rule is triggered when the headers in a file do not match the array of
+headers passed to the rule. It can be used to enforce a standard header
+structure for a set of files.
+
+To require exactly the following structure:
+
+    # Head
+    ## Item
+    ### Detail
+
+Set the `headers` parameter to:
+
+    [
+        "# Head",
+        "## Item",
+        "### Detail"
+    ]
+
+To allow optional headers as with the following structure:
+
+    # Head
+    ## Item
+    ### Detail (optional)
+    ## Foot
+    ### Notes (optional)
+
+Use the special value `"*"` meaning "one or more unspecified headers" and set
+the `headers` parameter to:
+
+    [
+        "# Head",
+        "## Item",
+        "*",
+        "## Foot",
+        "*"
+    ]
+
+When an error is detected, this rule outputs the line number of the first
+problematic header (otherwise, it outputs the last line number of the file).
+
+Note that while the `headers` parameter uses the "## Text" ATX header style for
+simplicity, a file may use any supported header style.

doc/MD044.md

@@ -0,0 +1,21 @@
+# MD044 - Proper names should have the correct capitalization
+
+Tags: spelling
+
+Aliases: proper-names
+
+Parameters: names, code_blocks (string array; default `null`, boolean; default `true`)
+
+This rule is triggered when any of the strings in the `names` array do not have
+the specified capitalization. It can be used to enforce a standard letter case
+for the names of projects and products.
+
+For example, the language "JavaScript" is usually written with both the 'J' and
+'S' capitalized - though sometimes the 's' or 'j' appear in lower-case. To enforce
+the proper capitalization, specify the desired letter case in the `names` array:
+
+    [
+        "JavaScript"
+    ]
+
+Set the `code_blocks` parameter to `false` to disable this rule for code blocks.