[PR #1870] [CLOSED] [WIP] Update doc/md041.md for formatting and typographical corrections #3616

New issue

Closed

opened 2026-03-07 20:14:37 +03:00 by kerem · 0 comments

kerem commented

2026-03-07 20:14:37 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/DavidAnson/markdownlint/pull/1870
Author: @Copilot
Created: 11/19/2025
Status: ❌ Closed

Base: main ← Head: copilot/update-md041-formatting-issues

📝 Commits (1)

d6314a8 Initial plan

📄 Description

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.

Original prompt

Update doc/md041.md to fix formatting and correct typographical issues. Changes are small, editorial, and preserve original meaning and examples. Specific edits:

Improve the rule description for clarity (concise sentence replacing two sentences).
Fix punctuation and grammar (add commas, adjust wording like "well supported" -> "well supported by Markdown").
Make the "allow_preamble" example clearer by adding a concluding sentence.
Reword the sentence about the level parameter for clarity.
Preserve all examples and parameter defaults unchanged (except for minor punctuation/grammar).

Please apply the following updated file contents to doc/md041.md.

# `MD041` - First line in a file should be a top-level heading

Tags: `headings`

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 ensures documents have a title. It is triggered when the first line
in a document is not a top-level (HTML `h1`) heading:

```markdown
This is a document without a heading
```

To fix this, add a top-level heading to the beginning of the document:

```markdown
# Document Heading

This is a document with a top-level heading
```

Because projects commonly use an image for the heading of `README.md` — a
pattern that 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 document with a top-level HTML heading
```

In some cases, a document's title heading may be preceded by text such as a
table of contents. This is not ideal for accessibility, but it can be allowed
by setting the `allow_preamble` parameter to `true`:

```markdown
This is a document with preamble text

# Document Heading
```

If 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 what is considered the top-level
heading (for example, 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

No images to include. This is an editorial change only. Create a branch, commit the updated file, and open a pull request with a concise title and description describing the formatting/typo fixes.

This pull request was created as a result of the following prompt from Copilot chat.

Update doc/md041.md to fix formatting and correct typographical issues. Changes are small, editorial, and preserve original meaning and examples. Specific edits:

Improve the rule description for clarity (concise sentence replacing two sentences).
Fix punctuation and grammar (add commas, adjust wording like "well supported" -> "well supported by Markdown").
Make the "allow_preamble" example clearer by adding a concluding sentence.
Reword the sentence about the level parameter for clarity.
Preserve all examples and parameter defaults unchanged (except for minor punctuation/grammar).

Please apply the following updated file contents to doc/md041.md.

# `MD041` - First line in a file should be a top-level heading

Tags: `headings`

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 ensures documents have a title. It is triggered when the first line
in a document is not a top-level (HTML `h1`) heading:

```markdown
This is a document without a heading
```

To fix this, add a top-level heading to the beginning of the document:

```markdown
# Document Heading

This is a document with a top-level heading
```

Because projects commonly use an image for the heading of `README.md` — a
pattern that 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 document with a top-level HTML heading
```

In some cases, a document's title heading may be preceded by text such as a
table of contents. This is not ideal for accessibility, but it can be allowed
by setting the `allow_preamble` parameter to `true`:

```markdown
This is a document with preamble text

# Document Heading
```

If 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 what is considered the top-level
heading (for example, 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

No images to include. This is an editorial change only. Create a branch, commit the updated file, and open a pull request with a concise title and description describing the formatting/typo fixes.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/DavidAnson/markdownlint/pull/1870 **Author:** [@Copilot](https://github.com/apps/copilot-swe-agent) **Created:** 11/19/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `copilot/update-md041-formatting-issues` --- ### 📝 Commits (1) - [`d6314a8`](https://github.com/DavidAnson/markdownlint/commit/d6314a81f1cea70930e4e5208c803c82ce606c10) Initial plan ### 📄 Description Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.  <details> <summary>Original prompt</summary> > Update doc/md041.md to fix formatting and correct typographical issues. Changes are small, editorial, and preserve original meaning and examples. Specific edits: > > - Improve the rule description for clarity (concise sentence replacing two sentences). > - Fix punctuation and grammar (add commas, adjust wording like "well supported" -> "well supported by Markdown"). > - Make the "allow_preamble" example clearer by adding a concluding sentence. > - Reword the sentence about the `level` parameter for clarity. > - Preserve all examples and parameter defaults unchanged (except for minor punctuation/grammar). > > Please apply the following updated file contents to doc/md041.md. > > ````markdown name=doc/md041.md url=https://github.com/DavidAnson/markdownlint/blob/224987d727ebada36752074d2466a061c9e03ff0/doc/md041.md > # `MD041` - First line in a file should be a top-level heading > > Tags: `headings` > > 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 ensures documents have a title. It is triggered when the first line > in a document is not a top-level (HTML `h1`) heading: > > ```markdown > This is a document without a heading > ``` > > To fix this, add a top-level heading to the beginning of the document: > > ```markdown > # Document Heading > > This is a document with a top-level heading > ``` > > Because projects commonly use an image for the heading of `README.md` — a > pattern that 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 document with a top-level HTML heading > ``` > > In some cases, a document's title heading may be preceded by text such as a > table of contents. This is not ideal for accessibility, but it can be allowed > by setting the `allow_preamble` parameter to `true`: > > ```markdown > This is a document with preamble text > > # Document Heading > ``` > > If 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 what is considered the top-level > heading (for example, 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 > ```` > > No images to include. This is an editorial change only. Create a branch, commit the updated file, and open a pull request with a concise title and description describing the formatting/typo fixes. </details> *This pull request was created as a result of the following prompt from Copilot chat.* > Update doc/md041.md to fix formatting and correct typographical issues. Changes are small, editorial, and preserve original meaning and examples. Specific edits: > > - Improve the rule description for clarity (concise sentence replacing two sentences). > - Fix punctuation and grammar (add commas, adjust wording like "well supported" -> "well supported by Markdown"). > - Make the "allow_preamble" example clearer by adding a concluding sentence. > - Reword the sentence about the `level` parameter for clarity. > - Preserve all examples and parameter defaults unchanged (except for minor punctuation/grammar). > > Please apply the following updated file contents to doc/md041.md. > > ````markdown name=doc/md041.md url=https://github.com/DavidAnson/markdownlint/blob/224987d727ebada36752074d2466a061c9e03ff0/doc/md041.md > # `MD041` - First line in a file should be a top-level heading > > Tags: `headings` > > 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 ensures documents have a title. It is triggered when the first line > in a document is not a top-level (HTML `h1`) heading: > > ```markdown > This is a document without a heading > ``` > > To fix this, add a top-level heading to the beginning of the document: > > ```markdown > # Document Heading > > This is a document with a top-level heading > ``` > > Because projects commonly use an image for the heading of `README.md` — a > pattern that 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 document with a top-level HTML heading > ``` > > In some cases, a document's title heading may be preceded by text such as a > table of contents. This is not ideal for accessibility, but it can be allowed > by setting the `allow_preamble` parameter to `true`: > > ```markdown > This is a document with preamble text > > # Document Heading > ``` > > If 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 what is considered the top-level > heading (for example, 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 > ```` > > No images to include. This is an editorial change only. Create a branch, commit the updated file, and open a pull request with a concise title and description describing the formatting/typo fixes.  --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey). --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>