mirror of
https://github.com/DavidAnson/markdownlint.git
synced 2025-09-21 21:30:47 +02:00
Update MD041/first-line-heading to add an allow_preamble parameter (fixes #1416).
This commit is contained in:
David Anson
parent
c061888937
commit
62dc79864d
17 changed files with 538 additions and 163 deletions
47
doc/Rules.md
47
doc/Rules.md
|
|
@ -1670,48 +1670,63 @@ Aliases: `first-line-h1`, `first-line-heading`
|
|||
|
||||
Parameters:
|
||||
|
||||
- `allow_preamble`: Allow content before first heading (`boolean`, default
|
||||
`false`)
|
||||
- `front_matter_title`: RegExp for matching title in front matter (`string`,
|
||||
default `^\s*title\s*[:=]`)
|
||||
- `level`: Heading level (`integer`, default `1`)
|
||||
|
||||
This rule is intended to ensure documents have a title and is triggered when
|
||||
the first line in the file isn't a top-level (h1) heading:
|
||||
the first line in a document is not a top-level ([HTML][HTML] `h1`) heading:
|
||||
|
||||
```markdown
|
||||
This is a file without a heading
|
||||
This is a document without a heading
|
||||
```
|
||||
|
||||
To fix this, add a top-level heading to the beginning of the file:
|
||||
To fix this, add a top-level heading to the beginning of the document:
|
||||
|
||||
```markdown
|
||||
# File with heading
|
||||
# Document Heading
|
||||
|
||||
This is a file with a top-level heading
|
||||
This is a document with a top-level heading
|
||||
```
|
||||
|
||||
Because it is common for projects on GitHub to use an image for the heading of
|
||||
`README.md` and that is not well-supported by Markdown, HTML headings are also
|
||||
permitted by this rule. For example:
|
||||
`README.md` and that pattern is not well-supported by Markdown, HTML headings
|
||||
are also permitted by this rule. For example:
|
||||
|
||||
```markdown
|
||||
<h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
|
||||
|
||||
This is a file with a top-level HTML heading
|
||||
This is a document with a top-level HTML heading
|
||||
```
|
||||
|
||||
Note: The `level` parameter can be used to change the top-level (ex: to h2) in
|
||||
cases where an h1 is added externally.
|
||||
In some cases, a document's title heading may be preceded by text like a table
|
||||
of contents. This is not ideal for accessibility, but can be allowed by setting
|
||||
the `allow_preamble` parameter to `true`.
|
||||
|
||||
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
|
||||
contains a `title` property (commonly used with blog posts), this rule will not
|
||||
report a violation. To use a different property name in the front matter,
|
||||
specify the text of a regular expression via the `front_matter_title` parameter.
|
||||
To disable the use of front matter by this rule, specify `""` for
|
||||
`front_matter_title`.
|
||||
```markdown
|
||||
This is a document with preamble text
|
||||
|
||||
# Document Heading
|
||||
```
|
||||
|
||||
If [YAML][YAML] front matter is present and contains a `title` property
|
||||
(commonly used with blog posts), this rule will not report a violation. To use a
|
||||
different property name in the front matter, specify the text of a [regular
|
||||
expression][RegExp] via the `front_matter_title` parameter. To disable the use
|
||||
of front matter by this rule, specify `""` for `front_matter_title`.
|
||||
|
||||
The `level` parameter can be used to change the top-level heading (ex: to `h2`)
|
||||
in cases where an `h1` is added externally.
|
||||
|
||||
Rationale: The top-level heading often acts as the title of a document. More
|
||||
information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
|
||||
|
||||
[HTML]: https://en.wikipedia.org/wiki/HTML
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
|
||||
[YAML]: https://en.wikipedia.org/wiki/YAML
|
||||
|
||||
<a name="md042"></a>
|
||||
|
||||
## `MD042` - No empty links
|
||||
|
|
|
|||
47
doc/md041.md
47
doc/md041.md
|
|
@ -6,44 +6,59 @@ Aliases: `first-line-h1`, `first-line-heading`
|
|||
|
||||
Parameters:
|
||||
|
||||
- `allow_preamble`: Allow content before first heading (`boolean`, default
|
||||
`false`)
|
||||
- `front_matter_title`: RegExp for matching title in front matter (`string`,
|
||||
default `^\s*title\s*[:=]`)
|
||||
- `level`: Heading level (`integer`, default `1`)
|
||||
|
||||
This rule is intended to ensure documents have a title and is triggered when
|
||||
the first line in the file isn't a top-level (h1) heading:
|
||||
the first line in a document is not a top-level ([HTML][HTML] `h1`) heading:
|
||||
|
||||
```markdown
|
||||
This is a file without a heading
|
||||
This is a document without a heading
|
||||
```
|
||||
|
||||
To fix this, add a top-level heading to the beginning of the file:
|
||||
To fix this, add a top-level heading to the beginning of the document:
|
||||
|
||||
```markdown
|
||||
# File with heading
|
||||
# Document Heading
|
||||
|
||||
This is a file with a top-level heading
|
||||
This is a document with a top-level heading
|
||||
```
|
||||
|
||||
Because it is common for projects on GitHub to use an image for the heading of
|
||||
`README.md` and that is not well-supported by Markdown, HTML headings are also
|
||||
permitted by this rule. For example:
|
||||
`README.md` and that pattern is not well-supported by Markdown, HTML headings
|
||||
are also permitted by this rule. For example:
|
||||
|
||||
```markdown
|
||||
<h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
|
||||
|
||||
This is a file with a top-level HTML heading
|
||||
This is a document with a top-level HTML heading
|
||||
```
|
||||
|
||||
Note: The `level` parameter can be used to change the top-level (ex: to h2) in
|
||||
cases where an h1 is added externally.
|
||||
In some cases, a document's title heading may be preceded by text like a table
|
||||
of contents. This is not ideal for accessibility, but can be allowed by setting
|
||||
the `allow_preamble` parameter to `true`.
|
||||
|
||||
If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
|
||||
contains a `title` property (commonly used with blog posts), this rule will not
|
||||
report a violation. To use a different property name in the front matter,
|
||||
specify the text of a regular expression via the `front_matter_title` parameter.
|
||||
To disable the use of front matter by this rule, specify `""` for
|
||||
`front_matter_title`.
|
||||
```markdown
|
||||
This is a document with preamble text
|
||||
|
||||
# Document Heading
|
||||
```
|
||||
|
||||
If [YAML][YAML] front matter is present and contains a `title` property
|
||||
(commonly used with blog posts), this rule will not report a violation. To use a
|
||||
different property name in the front matter, specify the text of a [regular
|
||||
expression][RegExp] via the `front_matter_title` parameter. To disable the use
|
||||
of front matter by this rule, specify `""` for `front_matter_title`.
|
||||
|
||||
The `level` parameter can be used to change the top-level heading (ex: to `h2`)
|
||||
in cases where an `h1` is added externally.
|
||||
|
||||
Rationale: The top-level heading often acts as the title of a document. More
|
||||
information: <https://cirosantilli.com/markdown-style-guide#top-level-header>.
|
||||
|
||||
[HTML]: https://en.wikipedia.org/wiki/HTML
|
||||
[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions
|
||||
[YAML]: https://en.wikipedia.org/wiki/YAML
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue