diff --git a/README.md b/README.md index 6ebeece0..7bfff08e 100644 --- a/README.md +++ b/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 diff --git a/doc/MD001.md b/doc/MD001.md new file mode 100644 index 00000000..4f93f20f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/MD002.md b/doc/MD002.md new file mode 100644 index 00000000..3f335506 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD003.md b/doc/MD003.md new file mode 100644 index 00000000..a50d81a8 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD004.md b/doc/MD004.md new file mode 100644 index 00000000..910a713c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/MD005.md b/doc/MD005.md new file mode 100644 index 00000000..013054c5 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/MD006.md b/doc/MD006.md new file mode 100644 index 00000000..078e243f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/MD007.md b/doc/MD007.md new file mode 100644 index 00000000..4c5dbda6 --- /dev/null +++ b/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 + for more +information. + +In addition, this is a compatibility issue with multi-markdown parsers, which +require a 4 space indents. See + +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). \ No newline at end of file diff --git a/doc/MD009.md b/doc/MD009.md new file mode 100644 index 00000000..42d3d18a --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD010.md b/doc/MD010.md new file mode 100644 index 00000000..6abed727 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/doc/MD011.md b/doc/MD011.md new file mode 100644 index 00000000..3c73f995 --- /dev/null +++ b/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] \ No newline at end of file diff --git a/doc/MD012.md b/doc/MD012.md new file mode 100644 index 00000000..4525da80 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD013.md b/doc/MD013.md new file mode 100644 index 00000000..9c5ce112 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD014.md b/doc/MD014.md new file mode 100644 index 00000000..513fcdc7 --- /dev/null +++ b/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 + +for more information. \ No newline at end of file diff --git a/doc/MD018.md b/doc/MD018.md new file mode 100644 index 00000000..7d69ca89 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/MD019.md b/doc/MD019.md new file mode 100644 index 00000000..33b41ba5 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/MD020.md b/doc/MD020.md new file mode 100644 index 00000000..4616a40d --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD021.md b/doc/MD021.md new file mode 100644 index 00000000..0b062ac4 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD022.md b/doc/MD022.md new file mode 100644 index 00000000..6bd88e9b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD023.md b/doc/MD023.md new file mode 100644 index 00000000..e0da536f --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD024.md b/doc/MD024.md new file mode 100644 index 00000000..8161ff98 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD025.md b/doc/MD025.md new file mode 100644 index 00000000..a3816e74 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD026.md b/doc/MD026.md new file mode 100644 index 00000000..26dd4fa0 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD027.md b/doc/MD027.md new file mode 100644 index 00000000..bdb4eda8 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD028.md b/doc/MD028.md new file mode 100644 index 00000000..cee7170e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD029.md b/doc/MD029.md new file mode 100644 index 00000000..b130752e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD030.md b/doc/MD030.md new file mode 100644 index 00000000..64476cb7 --- /dev/null +++ b/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 + +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. \ No newline at end of file diff --git a/doc/MD031.md b/doc/MD031.md new file mode 100644 index 00000000..c695c2d5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD032.md b/doc/MD032.md new file mode 100644 index 00000000..d115b153 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/MD033.md b/doc/MD033.md new file mode 100644 index 00000000..2ee69d76 --- /dev/null +++ b/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: + +

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. + +Note: To allow specific HTML elements, use the 'allowed_elements' parameter. \ No newline at end of file diff --git a/doc/MD034.md b/doc/MD034.md new file mode 100644 index 00000000..9910e743 --- /dev/null +++ b/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 . + +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` \ No newline at end of file diff --git a/doc/MD035.md b/doc/MD035.md new file mode 100644 index 00000000..ed2acaef --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD036.md b/doc/MD036.md new file mode 100644 index 00000000..4602281d --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD037.md b/doc/MD037.md new file mode 100644 index 00000000..2bcdd24f --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD038.md b/doc/MD038.md new file mode 100644 index 00000000..16c1a55b --- /dev/null +++ b/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`` \ No newline at end of file diff --git a/doc/MD039.md b/doc/MD039.md new file mode 100644 index 00000000..eec1e039 --- /dev/null +++ b/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/) \ No newline at end of file diff --git a/doc/MD040.md b/doc/MD040.md new file mode 100644 index 00000000..0eb53605 --- /dev/null +++ b/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 + ``` \ No newline at end of file diff --git a/doc/MD041.md b/doc/MD041.md new file mode 100644 index 00000000..b4889297 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD042.md b/doc/MD042.md new file mode 100644 index 00000000..d427a8cb --- /dev/null +++ b/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) \ No newline at end of file diff --git a/doc/MD043.md b/doc/MD043.md new file mode 100644 index 00000000..b9a12fd3 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/MD044.md b/doc/MD044.md new file mode 100644 index 00000000..1cc57b74 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/Rules.md b/doc/Rules.md deleted file mode 100644 index 45710027..00000000 --- a/doc/Rules.md +++ /dev/null @@ -1,1144 +0,0 @@ -# Rules - -This document contains a description of all rules, what they are checking for, -as well as an examples of documents that break the rule and corrected -versions of the examples. - -## 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 - -## 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. - -## 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. - -## 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 - -## 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 - -## 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 - -## 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 - for more -information. - -In addition, this is a compatibility issue with multi-markdown parsers, which -require a 4 space indents. See - -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). - -## 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. - -## 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). - -## 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] - -## 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. - -## 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. - -## 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 - -for more information. - -## 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 - -## 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 - -## 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. - -## 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. - -## 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. - -## 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. - -## 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. - -## 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. - -## 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. - -## 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. - -## 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. - -## 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. - -## 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 - -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. - -## 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 - -## 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: - -

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. - -Note: To allow specific HTML elements, use the 'allowed_elements' parameter. - -## 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 . - -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` - -## 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. - -## 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. - -## 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. - -## 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`` - -## 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/) - -## 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 - ``` - -## 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. - -## 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) - -## 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. - -## 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.