Convert to code fences in Rules.md and tag all as "markdown".

2025-12-18 06:50:12 +01:00 · 2018-03-09 22:50:01 -08:00 · 2018-03-09 22:50:01 -08:00 · c9571607dc
commit c9571607dc
parent 7310d01fea
1 changed files with 454 additions and 270 deletions
--- a/doc/Rules.md
+++ b/doc/Rules.md
@ -15,15 +15,18 @@ Aliases: header-increment
 This rule is triggered when you skip header levels in a markdown document, for
 example:

+```markdown
 # 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:

+```markdown
 # Header 1

 ## Header 2
@ -35,6 +38,7 @@ level at a time:
 ## Another Header 2

 ### Another Header 3
+```

 <a name="md002"></a>

@ -48,15 +52,19 @@ Parameters: level (number; default 1)

 This rule is triggered when the first header in the document isn't a h1 header:

+```markdown
 ## This isn't a H1 header

 ### Another header
+```

 The first header in the document should be a h1 header:

+```markdown
 # 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.
@ -75,22 +83,27 @@ Parameters: style ("consistent", "atx", "atx_closed", "setext",
 This rule is triggered when different header styles (atx, setext, and 'closed'
 atx) are used in the same document:

+```markdown
 # ATX style H1

 ## Closed ATX style H2 ##

 Setext style H1
 ===============
+```

 Be consistent with the style of header used in a document:

+```markdown
 # ATX style H1

 ## ATX style H2
+```

 The setext_with_atx and setext_with_atx_closed doc styles allow atx-style
 headers of level 3 or more in documents with setext style headers:

+```markdown
 Setext style H1
 ===============

@ -98,6 +111,7 @@ headers of level 3 or more in documents with setext style headers:
 ---------------

 ### 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
@ -117,16 +131,20 @@ Parameters: style ("consistent", "asterisk", "plus", "dash", "sublist"; default
 This rule is triggered when the symbols used in the document for unordered
 list items do not match the configured unordered list style:

+```markdown
 * Item 1
 + Item 2
 - Item 3
+```

 To fix this issue, use the configured style for list items throughout the
 document:

+```markdown
 * 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
@ -135,12 +153,14 @@ 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:

+```markdown
 * Item 1
  + Item 2
    - Item 3
  + Item 4
 * Item 4
  + Item 5
+```

 <a name="md005"></a>

@ -153,18 +173,22 @@ 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:

+```markdown
 * 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:

+```markdown
 * Item 1
  * Nested Item 1
  * Nested Item 2
  * Nested Item 3
+```

 <a name="md006"></a>

@ -177,17 +201,21 @@ Aliases: ul-start-left
 This rule is triggered when top level lists don't start at the beginning of a
 line:

+```markdown
 Some text

  * List item
  * List item
+```

 To fix, ensure that top level list items are not indented:

+```markdown
 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
@ -200,10 +228,12 @@ 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.

+```markdown
 1. List item
  - List item
  - List item
 1. List item
+```

 <a name="md007"></a>

@ -220,13 +250,17 @@ number of spaces (default: 2).

 Example:

+```markdown
 * List item
   * Nested list item indented by 3 spaces
+```

 Corrected Example:

+```markdown
 * 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
@ -272,9 +306,11 @@ Using spaces to indent blank lines inside a list item is usually not necessary,
 but some parsers require it. Set the `list_item_empty_lines` parameter to `true`
 to allow this:

+```markdown
 - list item text
  
  list item text
+```

 <a name="md010"></a>

@ -292,15 +328,19 @@ with spaces instead.

 Example:

+```markdown
 Some text

 	* hard tab character used to indent the list item
+```

 Corrected example:

+```markdown
 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
@ -318,15 +358,21 @@ 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):

+```markdown
 (Incorrect link syntax)[http://www.example.com/]
+```

 To fix this, swap the `[]` and `()` around:

+```markdown
 [Correct link syntax](http://www.example.com/)
+```

 Note: [Markdown Extra](https://en.wikipedia.org/wiki/Markdown_Extra)-style footnotes do not trigger this rule:

+```markdown
 For (example)[^1]
+```

 <a name="md012"></a>

@ -341,16 +387,20 @@ Parameters: maximum (number; default 1)
 This rule is triggered when there are multiple consecutive blank lines in the
 document:

+```markdown
 Some text here


 Some more text here
+```

 To fix this, delete the offending lines:

+```markdown
 Some text here

 Some more text here
+```

 Note: this rule will not be triggered if there are multiple consecutive blank
 lines inside code blocks.
@ -394,26 +444,32 @@ 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 ($):

+```markdown
 $ ls
 $ cat foo
 $ less bar
+```

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

+```markdown
 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:

+```markdown
 $ 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
@ -431,16 +487,20 @@ Aliases: no-missing-space-atx
 This rule is triggered when spaces are missing after the hash characters
 in an atx style header:

+```markdown
 #Header 1

 ##Header 2
+```

 To fix this, separate the header text from the hash character by a single
 space:

+```markdown
 # Header 1

 ## Header 2
+```

 <a name="md019"></a>

@ -453,16 +513,20 @@ 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:

+```markdown
 #  Header 1

 ##  Header 2
+```

 To fix this, separate the header text from the hash character by a single
 space:

+```markdown
 # Header 1

 ## Header 2
+```

 <a name="md020"></a>

@ -475,16 +539,20 @@ Aliases: no-missing-space-closed-atx
 This rule is triggered when spaces are missing inside the hash characters
 in a closed atx style header:

+```markdown
 #Header 1#

 ##Header 2##
+```

 To fix this, separate the header text from the hash character by a single
 space:

+```markdown
 # Header 1 #

 ## Header 2 ##
+```

 Note: this rule will fire if either side of the header is missing spaces.

@ -499,16 +567,20 @@ 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:

+```markdown
 #  Header 1  #

 ##  Header 2  ##
+```

 To fix this, separate the header text from the hash character by a single
 space:

+```markdown
 # Header 1 #

 ## Header 2 ##
+```

 Note: this rule will fire if either side of the header contains multiple
 spaces.
@ -524,15 +596,18 @@ Aliases: blanks-around-headers
 This rule is triggered when headers (any style) are either not preceded or not
 followed by a blank line:

+```markdown
 # 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):

+```markdown
 # Header 1

 Some text
@ -540,6 +615,7 @@ To fix this, ensure that all headers have a blank line both before and after
 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
@ -555,15 +631,19 @@ Aliases: header-start-left

 This rule is triggered when a header is indented by one or more spaces:

+```markdown
 Some text

  # Indented header
+```

 To fix this, ensure that all headers start at the beginning of the line:

+```markdown
 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.
@ -579,15 +659,19 @@ Aliases: no-duplicate-header
 This rule is triggered if there are multiple headers in the document that have
 the same text:

+```markdown
 # Some text

 ## Some text
+```

 To fix this, ensure that the content of each header is different:

+```markdown
 # 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
@ -607,19 +691,23 @@ 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:

+```markdown
 # 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:

+```markdown
 # 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
@ -642,11 +730,15 @@ Parameters: punctuation (string; default ".,;:!?")
 This rule is triggered on any header that has a punctuation character as the
 last character in the line:

+```markdown
 # This is a header.
+```

 To fix this, remove any trailing punctuation:

+```markdown
 # 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
@ -664,13 +756,17 @@ Aliases: no-multiple-space-blockquote
 This rule is triggered when blockquotes have more than one space after the
 blockquote (`>`) symbol:

+```markdown
 >  This is a block quote with bad indentation
 >  there should only be one.
+```

 To fix, remove any extraneous space:

+```markdown
 > This is a blockquote with correct
 > indentation.
+```

 <a name="md028"></a>

@ -683,27 +779,33 @@ Aliases: no-blanks-blockquote
 This rule is triggered when two blockquote blocks are separated by nothing
 except for a blank line:

+```markdown
 > 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:

+```markdown
 > 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:

+```markdown
 > 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
@ -725,22 +827,28 @@ configured style).

 Example valid list if the style is configured as 'one':

+```markdown
 1. Do this.
 1. Do that.
 1. Done.
+```

 Example valid list if the style is configured as 'ordered':

+```markdown
 1. Do this.
 2. Do that.
 3. Done.
+```

 Both examples are valid when the style is configured as 'one_or_ordered'.

 Example invalid list for all styles:

+```markdown
 1. Do this.
 3. Done.
+```

 <a name="md030"></a>

@ -758,6 +866,7 @@ This rule checks for the number of spaces between a list marker (e.g. '`-`',
 The number of spaces checked for depends on the document style in use, but the
 default is 1 space after any list marker:

+```markdown
 * Foo
 * Bar
 * Baz
@ -769,6 +878,7 @@ default is 1 space after any list marker:
 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
@ -782,25 +892,31 @@ 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:

+```markdown
 * Foo
 * Bar
 * Baz
+```

 vs.

+```markdown
 *   Foo

    Second paragraph

 *   Bar
+```

 or

+```markdown
 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.
@ -816,6 +932,7 @@ Aliases: blanks-around-fences
 This rule is triggered when fenced code blocks are either not preceded or not
 followed by a blank line:

+````markdown
 Some text
 ```
 Code block
@ -825,10 +942,12 @@ followed by a blank line:
 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):

+````markdown
 Some text

 ```
@ -840,6 +959,7 @@ and after (except where the block is at the beginning or end of the document):
 ```

 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.
@ -855,6 +975,7 @@ Aliases: blanks-around-lists
 This rule is triggered when lists (of any kind) are either not preceded or not
 followed by a blank line:

+```markdown
 Some text
 * Some
 * List
@ -862,10 +983,12 @@ followed by a blank line:
 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):

+```markdown
 Some text

 * Some
@ -875,6 +998,7 @@ To fix this, ensure that all lists have a blank line both before and after
 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.
@ -882,11 +1006,13 @@ 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:

+```markdown
 * This is
 not okay

 * This is
  okay
+```

 <a name="md033"></a>

@ -900,11 +1026,15 @@ Parameters: allowed_elements (array of string; default empty)

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

+```markdown
 <h1>Inline HTML header</h1>
+```

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

+```markdown
 # 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
@ -923,11 +1053,15 @@ Aliases: no-bare-urls
 This rule is triggered whenever a URL is given that isn't surrounded by angle
 brackets:

+```markdown
 For more information, see http://www.example.com/.
+```

 To fix this, add angle brackets around the URL:

+```markdown
 For more information, see <http://www.example.com/>.
+```

 Rationale: Without angle brackets, the URL isn't converted into a link in many
 markdown parsers.
@ -936,7 +1070,9 @@ 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:

+```markdown
 `http://www.example.com`
+```

 <a name="md035"></a>

@ -952,6 +1088,7 @@ horizontal rule; default "consistent")
 This rule is triggered when inconsistent styles of horizontal rules are used
 in the document:

+```markdown
 ---

 - - -
@ -961,13 +1098,16 @@ 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:

+```markdown
 ---

 ---
+```

 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
@ -989,6 +1129,7 @@ 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:

+```markdown
 **My document**

 Lorem ipsum dolor sit amet...
@ -996,10 +1137,12 @@ used to separate sections, where a header should be used instead:
 _Another section_

 Consectetur adipiscing elit, sed do eiusmod.
+```

 To fix this, use markdown headers instead of emphasized text to denote
 sections:

+```markdown
 # My document

 Lorem ipsum dolor sit amet...
@ -1007,6 +1150,7 @@ sections:
 ## 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,
@ -1025,6 +1169,7 @@ 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:

+```markdown
 Here is some ** bold ** text.

 Here is some * italic * text.
@ -1032,9 +1177,11 @@ have spaces between the markers and the text:
 Here is some more __ bold __ text.

 Here is some more _ italic _ text.
+```

 To fix this, remove the spaces around the emphasis markers:

+```markdown
 Here is some **bold** text.

 Here is some *italic* text.
@ -1042,6 +1189,7 @@ To fix this, remove the spaces around the emphasis markers:
 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
@ -1059,20 +1207,26 @@ Aliases: no-space-in-code
 This rule is triggered on code span elements that have spaces right inside the
 backticks:

+```markdown
 ` some text `

 `some text `

 ` some text`
+```

 To fix this, remove the spaces inside the codespan markers:

+```markdown
 `some text`
+```

 Note: A single leading or trailing space is allowed if used to separate codespan
 markers from an embedded backtick:

+```markdown
 `` ` embedded backtick``
+```

 <a name="md039"></a>

@ -1084,11 +1238,15 @@ Aliases: no-space-in-links

 This rule is triggered on links that have spaces surrounding the link text:

+```markdown
 [ a link ](http://www.example.com/)
+```

 To fix this, remove the spaces surrounding the link text:

+```markdown
 [a link](http://www.example.com/)
+```

 <a name="md040"></a>

@ -1101,17 +1259,21 @@ Aliases: fenced-code-language
 This rule is triggered when fenced code blocks are used, but a language isn't
 specified:

+````markdown
 ```
 #!/bin/bash
 echo Hello world
 ```
+````

 To fix this, add a language specifier to the code block:

+````markdown
 ```bash
 #!/bin/bash
 echo Hello world
 ```
+````

 <a name="md041"></a>

@ -1126,13 +1288,17 @@ Parameters: level, front_matter_title (number; default 1, string; default "^\s*t
 This rule is triggered when the first line in the file isn't a top level (h1)
 header:

+```markdown
 This is a file without a header
+```

 To fix this, add a header to the top of your file:

+```markdown
 # File with header

 This is a file with a top level header
+```

 The `level` parameter can be used to change the top level (ex: to h2) in cases
 where an h1 is added externally.
@ -1153,19 +1319,27 @@ Aliases: no-empty-links

 This rule is triggered when an empty link is encountered:

+```markdown
 [an empty link]()
+```

 To fix the violation, provide a destination for the link:

+```markdown
 [a valid link](https://example.com/)
+```

 Empty fragments will trigger this rule:

+```markdown
 [an empty fragment](#)
+```

 But non-empty fragments will not:

+```markdown
 [a valid fragment](#fragment)
+```

 <a name="md043"></a>

@ -1183,29 +1357,36 @@ structure for a set of files.

 To require exactly the following structure:

+```markdown
 # Head
 ## Item
 ### Detail
+```

 Set the `headers` parameter to:

+```json
 [
    "# Head",
    "## Item",
    "### Detail"
 ]
+```

 To allow optional headers as with the following structure:

+```markdown
 # Head
 ## Item
 ### Detail (optional)
 ## Foot
 ### Notes (optional)
+```

 Use the special value `"*"` meaning "one or more unspecified headers" and set
 the `headers` parameter to:

+```json
 [
    "# Head",
    "## Item",
@ -1213,6 +1394,7 @@ the `headers` parameter to:
    "## 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).
@ -1238,9 +1420,11 @@ 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:

+```json
 [
    "JavaScript"
 ]
+```

 Set the `code_blocks` parameter to `false` to disable this rule for code blocks.