Andreas/markdownlint
1
0
Fork 0
mirror of https://github.com/DavidAnson/markdownlint.git synced 2025-12-16 14:00:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Update rule documentation to explain how consistent is implemented (fixes #1346).

Browse source
This commit is contained in:
David Anson 2024-10-07 22:08:16 -07:00
parent 61a9c2427e
commit 5faa6f4235
17 changed files with 75 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc-build/md003.md
View file

@ -33,8 +33,8 @@ Setext style H2
``` ```
Note: The configured heading style can be a specific style to require (`atx`, Note: The configured heading style can be a specific style to require (`atx`,
`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may `atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or can
just require that usage is consistent within the document via `consistent`. require that all heading styles match the first heading style via `consistent`.
Note: The placement of a horizontal rule directly below a line of text can Note: The placement of a horizontal rule directly below a line of text can
trigger this rule by turning that text into a level 2 setext-style heading: trigger this rule by turning that text into a level 2 setext-style heading:

7
doc-build/md004.md
View file

@ -16,9 +16,10 @@ document:
* Item 3 * Item 3
``` ```
The configured list style can be a specific symbol to use (asterisk, plus, The configured list style can ensure all list styling is a specific symbol
dash), to ensure that all list styling is consistent, or to ensure that each (`asterisk`, `plus`, `dash`), ensure each sublist has a consistent symbol that
sublist has a consistent symbol that differs from its parent list. differs from its parent list (`sublist`), or ensure all list styles match the
first list style (`consistent`).
For example, the following is valid for the `sublist` style because the 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 outer-most indent uses asterisk, the middle indent uses plus, and the inner-most

11
doc-build/md035.md
View file

@ -13,8 +13,7 @@ in the document:
**** ****
``` ```
To fix this, ensure any horizontal rules used in the document are consistent, To fix this, use the same horizontal rule everywhere:
or match the given style if the rule is so configured:
```markdown ```markdown
--- ---
@ -22,11 +21,7 @@ or match the given style if the rule is so configured:
--- ---
``` ```
Note: by default, this rule is configured to just require that all horizontal The configured style can ensure all horizontal rules use a specific string or it
rules in the document are the same and will trigger if any of the horizontal can ensure all horizontal rules match the first horizontal rule (`consistent`).
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.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

4
doc-build/md046.md
View file

@ -23,7 +23,7 @@ document:
To fix violations of this rule, use a consistent style (either indenting or code To fix violations of this rule, use a consistent style (either indenting or code
fences). fences).
The specified style can be specific (`fenced`, `indented`) or simply require The configured code block style can be specific (`fenced`, `indented`) or can
that usage be consistent within the document (`consistent`). require all code blocks match the first code block (`consistent`).
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

5
doc-build/md048.md
View file

@ -24,7 +24,8 @@ document:
``` ```
```` ````
The configured list style can be a specific symbol to use (backtick, tilde), or The configured code fence style can be a specific symbol to use (`backtick`,
can require that usage be consistent within the document. `tilde`) or it can require all code fences match the first code fence
(`consistent`).
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

7
doc-build/md049.md
View file

@ -13,10 +13,11 @@ To fix this issue, use the configured emphasis style throughout the document:
*Text* *Text*
``` ```
The configured emphasis style can be a specific symbol to use ("asterisk", The configured emphasis style can be a specific symbol to use (`asterisk`,
"underscore"), or can require that usage be consistent within the document. `underscore`) or can require all emphasis matches the first emphasis
(`consistent`).
Note: Emphasis within a word is restricted to "asterisk" in order to avoid Note: Emphasis within a word is restricted to `asterisk` in order to avoid
unwanted emphasis for words containing internal underscores like_this_one. unwanted emphasis for words containing internal underscores like_this_one.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

8
doc-build/md050.md
View file

@ -13,10 +13,10 @@ To fix this issue, use the configured strong style throughout the document:
**Text** **Text**
``` ```
The configured strong style can be a specific symbol to use ("asterisk", The configured strong style can be a specific symbol to use (`asterisk`,
"underscore"), or can require that usage be consistent within the document. `underscore`) or can require all strong matches the first strong (`consistent`).
Note: Emphasis within a word is restricted to "asterisk" in order to avoid Note: Emphasis within a word is restricted to `asterisk` in order to avoid
unwanted emphasis for words containing internal underscores like_this_one. unwanted emphasis for words containing internal underscores like__this__one.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

5
doc-build/md055.md
View file

@ -2,8 +2,9 @@ This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
is inconsistent about its use of leading and trailing pipe characters (`|`). is inconsistent about its use of leading and trailing pipe characters (`|`).
By default (`consistent` style), the header row of the first table in a document By default (`consistent` style), the header row of the first table in a document
is used to determine the style that is enforced for all tables in that document. is used to determine the style that is enforced for every table in the document.
A specific style can be required by setting the `style` parameter accordingly. A specific style can be used instead (`leading_and_trailing`, `leading_only`,
`no_leading_or_trailing`, `trailing_only`).
This table's header row has leading and trailing pipes, but its delimiter row is This table's header row has leading and trailing pipes, but its delimiter row is
missing the trailing pipe and its first row of cells is missing the leading missing the trailing pipe and its first row of cells is missing the leading

51
doc/Rules.md
View file

@ -93,8 +93,8 @@ Setext style H2
``` ```
Note: The configured heading style can be a specific style to require (`atx`, Note: The configured heading style can be a specific style to require (`atx`,
`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may `atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or can
just require that usage is consistent within the document via `consistent`. require that all heading styles match the first heading style via `consistent`.
Note: The placement of a horizontal rule directly below a line of text can Note: The placement of a horizontal rule directly below a line of text can
trigger this rule by turning that text into a level 2 setext-style heading: trigger this rule by turning that text into a level 2 setext-style heading:
@ -139,9 +139,10 @@ document:
* Item 3 * Item 3
``` ```
The configured list style can be a specific symbol to use (asterisk, plus, The configured list style can ensure all list styling is a specific symbol
dash), to ensure that all list styling is consistent, or to ensure that each (`asterisk`, `plus`, `dash`), ensure each sublist has a consistent symbol that
sublist has a consistent symbol that differs from its parent list. differs from its parent list (`sublist`), or ensure all list styles match the
first list style (`consistent`).
For example, the following is valid for the `sublist` style because the 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 outer-most indent uses asterisk, the middle indent uses plus, and the inner-most
@ -1416,8 +1417,7 @@ in the document:
**** ****
``` ```
To fix this, ensure any horizontal rules used in the document are consistent, To fix this, use the same horizontal rule everywhere:
or match the given style if the rule is so configured:
```markdown ```markdown
--- ---
@ -1425,12 +1425,8 @@ or match the given style if the rule is so configured:
--- ---
``` ```
Note: by default, this rule is configured to just require that all horizontal The configured style can ensure all horizontal rules use a specific string or it
rules in the document are the same and will trigger if any of the horizontal can ensure all horizontal rules match the first horizontal rule (`consistent`).
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.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.
@ -1932,8 +1928,8 @@ document:
To fix violations of this rule, use a consistent style (either indenting or code To fix violations of this rule, use a consistent style (either indenting or code
fences). fences).
The specified style can be specific (`fenced`, `indented`) or simply require The configured code block style can be specific (`fenced`, `indented`) or can
that usage be consistent within the document (`consistent`). require all code blocks match the first code block (`consistent`).
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.
@ -2013,8 +2009,9 @@ document:
``` ```
```` ````
The configured list style can be a specific symbol to use (backtick, tilde), or The configured code fence style can be a specific symbol to use (`backtick`,
can require that usage be consistent within the document. `tilde`) or it can require all code fences match the first code fence
(`consistent`).
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.
@ -2048,10 +2045,11 @@ To fix this issue, use the configured emphasis style throughout the document:
*Text* *Text*
``` ```
The configured emphasis style can be a specific symbol to use ("asterisk", The configured emphasis style can be a specific symbol to use (`asterisk`,
"underscore"), or can require that usage be consistent within the document. `underscore`) or can require all emphasis matches the first emphasis
(`consistent`).
Note: Emphasis within a word is restricted to "asterisk" in order to avoid Note: Emphasis within a word is restricted to `asterisk` in order to avoid
unwanted emphasis for words containing internal underscores like_this_one. unwanted emphasis for words containing internal underscores like_this_one.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.
@ -2086,11 +2084,11 @@ To fix this issue, use the configured strong style throughout the document:
**Text** **Text**
``` ```
The configured strong style can be a specific symbol to use ("asterisk", The configured strong style can be a specific symbol to use (`asterisk`,
"underscore"), or can require that usage be consistent within the document. `underscore`) or can require all strong matches the first strong (`consistent`).
Note: Emphasis within a word is restricted to "asterisk" in order to avoid Note: Emphasis within a word is restricted to `asterisk` in order to avoid
unwanted emphasis for words containing internal underscores like_this_one. unwanted emphasis for words containing internal underscores like__this__one.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.
@ -2389,8 +2387,9 @@ This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
is inconsistent about its use of leading and trailing pipe characters (`|`). is inconsistent about its use of leading and trailing pipe characters (`|`).
By default (`consistent` style), the header row of the first table in a document By default (`consistent` style), the header row of the first table in a document
is used to determine the style that is enforced for all tables in that document. is used to determine the style that is enforced for every table in the document.
A specific style can be required by setting the `style` parameter accordingly. A specific style can be used instead (`leading_and_trailing`, `leading_only`,
`no_leading_or_trailing`, `trailing_only`).
This table's header row has leading and trailing pipes, but its delimiter row is This table's header row has leading and trailing pipes, but its delimiter row is
missing the trailing pipe and its first row of cells is missing the leading missing the trailing pipe and its first row of cells is missing the leading

4
doc/md003.md
View file

@ -45,8 +45,8 @@ Setext style H2
``` ```
Note: The configured heading style can be a specific style to require (`atx`, Note: The configured heading style can be a specific style to require (`atx`,
`atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or may `atx_closed`, `setext`, `setext_with_atx`, `setext_with_atx_closed`), or can
just require that usage is consistent within the document via `consistent`. require that all heading styles match the first heading style via `consistent`.
Note: The placement of a horizontal rule directly below a line of text can Note: The placement of a horizontal rule directly below a line of text can
trigger this rule by turning that text into a level 2 setext-style heading: trigger this rule by turning that text into a level 2 setext-style heading:

7
doc/md004.md
View file

@ -29,9 +29,10 @@ document:
* Item 3 * Item 3
``` ```
The configured list style can be a specific symbol to use (asterisk, plus, The configured list style can ensure all list styling is a specific symbol
dash), to ensure that all list styling is consistent, or to ensure that each (`asterisk`, `plus`, `dash`), ensure each sublist has a consistent symbol that
sublist has a consistent symbol that differs from its parent list. differs from its parent list (`sublist`), or ensure all list styles match the
first list style (`consistent`).
For example, the following is valid for the `sublist` style because the 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 outer-most indent uses asterisk, the middle indent uses plus, and the inner-most

11
doc/md035.md
View file

@ -23,8 +23,7 @@ in the document:
**** ****
``` ```
To fix this, ensure any horizontal rules used in the document are consistent, To fix this, use the same horizontal rule everywhere:
or match the given style if the rule is so configured:
```markdown ```markdown
--- ---
@ -32,11 +31,7 @@ or match the given style if the rule is so configured:
--- ---
``` ```
Note: by default, this rule is configured to just require that all horizontal The configured style can ensure all horizontal rules use a specific string or it
rules in the document are the same and will trigger if any of the horizontal can ensure all horizontal rules match the first horizontal rule (`consistent`).
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.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

4
doc/md046.md
View file

@ -34,7 +34,7 @@ document:
To fix violations of this rule, use a consistent style (either indenting or code To fix violations of this rule, use a consistent style (either indenting or code
fences). fences).
The specified style can be specific (`fenced`, `indented`) or simply require The configured code block style can be specific (`fenced`, `indented`) or can
that usage be consistent within the document (`consistent`). require all code blocks match the first code block (`consistent`).
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

5
doc/md048.md
View file

@ -35,7 +35,8 @@ document:
``` ```
```` ````
The configured list style can be a specific symbol to use (backtick, tilde), or The configured code fence style can be a specific symbol to use (`backtick`,
can require that usage be consistent within the document. `tilde`) or it can require all code fences match the first code fence
(`consistent`).
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

7
doc/md049.md
View file

@ -26,10 +26,11 @@ To fix this issue, use the configured emphasis style throughout the document:
*Text* *Text*
``` ```
The configured emphasis style can be a specific symbol to use ("asterisk", The configured emphasis style can be a specific symbol to use (`asterisk`,
"underscore"), or can require that usage be consistent within the document. `underscore`) or can require all emphasis matches the first emphasis
(`consistent`).
Note: Emphasis within a word is restricted to "asterisk" in order to avoid Note: Emphasis within a word is restricted to `asterisk` in order to avoid
unwanted emphasis for words containing internal underscores like_this_one. unwanted emphasis for words containing internal underscores like_this_one.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

8
doc/md050.md
View file

@ -26,10 +26,10 @@ To fix this issue, use the configured strong style throughout the document:
**Text** **Text**
``` ```
The configured strong style can be a specific symbol to use ("asterisk", The configured strong style can be a specific symbol to use (`asterisk`,
"underscore"), or can require that usage be consistent within the document. `underscore`) or can require all strong matches the first strong (`consistent`).
Note: Emphasis within a word is restricted to "asterisk" in order to avoid Note: Emphasis within a word is restricted to `asterisk` in order to avoid
unwanted emphasis for words containing internal underscores like_this_one. unwanted emphasis for words containing internal underscores like__this__one.
Rationale: Consistent formatting makes it easier to understand a document. Rationale: Consistent formatting makes it easier to understand a document.

5
doc/md055.md
View file

@ -14,8 +14,9 @@ This rule is triggered when a [GitHub Flavored Markdown table][gfm-table-055]
is inconsistent about its use of leading and trailing pipe characters (`|`). is inconsistent about its use of leading and trailing pipe characters (`|`).
By default (`consistent` style), the header row of the first table in a document By default (`consistent` style), the header row of the first table in a document
is used to determine the style that is enforced for all tables in that document. is used to determine the style that is enforced for every table in the document.
A specific style can be required by setting the `style` parameter accordingly. A specific style can be used instead (`leading_and_trailing`, `leading_only`,
`no_leading_or_trailing`, `trailing_only`).
This table's header row has leading and trailing pipes, but its delimiter row is This table's header row has leading and trailing pipes, but its delimiter row is
missing the trailing pipe and its first row of cells is missing the leading missing the trailing pipe and its first row of cells is missing the leading