diff --git a/doc-build/md003.md b/doc-build/md003.md index 6e039588..9a928702 100644 --- a/doc-build/md003.md +++ b/doc-build/md003.md @@ -1,5 +1,5 @@ -This rule is triggered when different heading styles (atx, setext, and 'closed' -atx) are used in the same document: +This rule is triggered when different heading styles are used in the same +document: ```markdown # ATX style H1 @@ -10,7 +10,7 @@ Setext style H1 =============== ``` -Be consistent with the style of heading used in a document: +To fix the issue, use consistent heading styles throughout the document: ```markdown # ATX style H1 @@ -18,8 +18,9 @@ Be consistent with the style of heading used in a document: ## ATX style H2 ``` -The setext_with_atx and setext_with_atx_closed doc styles allow atx-style -headings of level 3 or more in documents with setext style headings: +The `setext_with_atx` and `setext_with_atx_closed` settings allow ATX-style +headings of level 3 or more in documents with setext-style headings (which only +support level 1 and 2 headings): ```markdown Setext style H1 @@ -31,8 +32,16 @@ Setext style H2 ### ATX style H3 ``` -Note: the configured heading 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 is consistent within the document. +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 +just require that usage is consistent within the document via `consistent`. + +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: + +```markdown +A line of text followed by a horizontal rule becomes a heading +--- +``` Rationale: Consistent formatting makes it easier to understand a document. diff --git a/doc/Rules.md b/doc/Rules.md index d48a3385..13d56d7f 100644 --- a/doc/Rules.md +++ b/doc/Rules.md @@ -99,8 +99,8 @@ Parameters: `atx_closed` / `consistent` / `setext` / `setext_with_atx` / `setext_with_atx_closed`) -This rule is triggered when different heading styles (atx, setext, and 'closed' -atx) are used in the same document: +This rule is triggered when different heading styles are used in the same +document: ```markdown # ATX style H1 @@ -111,7 +111,7 @@ Setext style H1 =============== ``` -Be consistent with the style of heading used in a document: +To fix the issue, use consistent heading styles throughout the document: ```markdown # ATX style H1 @@ -119,8 +119,9 @@ Be consistent with the style of heading used in a document: ## ATX style H2 ``` -The setext_with_atx and setext_with_atx_closed doc styles allow atx-style -headings of level 3 or more in documents with setext style headings: +The `setext_with_atx` and `setext_with_atx_closed` settings allow ATX-style +headings of level 3 or more in documents with setext-style headings (which only +support level 1 and 2 headings): ```markdown Setext style H1 @@ -132,9 +133,17 @@ Setext style H2 ### ATX style H3 ``` -Note: the configured heading 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 is consistent within the document. +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 +just require that usage is consistent within the document via `consistent`. + +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: + +```markdown +A line of text followed by a horizontal rule becomes a heading +--- +``` Rationale: Consistent formatting makes it easier to understand a document. diff --git a/doc/md003.md b/doc/md003.md index 19e2409e..f9e9380a 100644 --- a/doc/md003.md +++ b/doc/md003.md @@ -10,8 +10,8 @@ Parameters: `atx_closed` / `consistent` / `setext` / `setext_with_atx` / `setext_with_atx_closed`) -This rule is triggered when different heading styles (atx, setext, and 'closed' -atx) are used in the same document: +This rule is triggered when different heading styles are used in the same +document: ```markdown # ATX style H1 @@ -22,7 +22,7 @@ Setext style H1 =============== ``` -Be consistent with the style of heading used in a document: +To fix the issue, use consistent heading styles throughout the document: ```markdown # ATX style H1 @@ -30,8 +30,9 @@ Be consistent with the style of heading used in a document: ## ATX style H2 ``` -The setext_with_atx and setext_with_atx_closed doc styles allow atx-style -headings of level 3 or more in documents with setext style headings: +The `setext_with_atx` and `setext_with_atx_closed` settings allow ATX-style +headings of level 3 or more in documents with setext-style headings (which only +support level 1 and 2 headings): ```markdown Setext style H1 @@ -43,8 +44,16 @@ Setext style H2 ### ATX style H3 ``` -Note: the configured heading 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 is consistent within the document. +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 +just require that usage is consistent within the document via `consistent`. + +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: + +```markdown +A line of text followed by a horizontal rule becomes a heading +--- +``` Rationale: Consistent formatting makes it easier to understand a document.