[GH-ISSUE #359] MD041 should trigger if there is at least one heading present #2150

New issue

Closed

opened 2026-03-07 20:05:02 +03:00 by kerem · 1 comment

kerem commented

2026-03-07 20:05:02 +03:00

Owner

Originally created by @Yash-Singh1 on GitHub (Dec 28, 2020).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/359

Currently MD041 states that the first line in a file should be a # or h1 heading. Some markdown files such as _sidebar.md in docsify (https://docsify.js.org/#/more-pages?id=sidebar) don't need any heading at all. Here is an example _sidebar.md:

- [Home](/)
- [Setting Up](setup.md)
- [Using Site](ui.md)

The rule should contain an extra rule stating that the top-level heading is required if there is at least one heading. E.g., the linting error should appear on the following file:

Hello World!

## Foo

Talking about foo here

But not give an error in:

Hello World!

Talking about foo here

This is because the first one has at least one heading present while the second one doesn't have any headings present.

Originally created by @Yash-Singh1 on GitHub (Dec 28, 2020). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/359 Currently `MD041` states that the first line in a file should be a `#` or `h1` heading. Some markdown files such as `_sidebar.md` in `docsify` (<https://docsify.js.org/#/more-pages?id=sidebar>) don't need any heading at all. Here is an example `_sidebar.md`: ```markdown - [Home](/) - [Setting Up](setup.md) - [Using Site](ui.md) ``` The rule should contain an extra rule stating that the top-level heading is required if there is at least one heading. E.g., the linting error should appear on the following file: ```markdown Hello World! ## Foo Talking about foo here ``` But not give an error in: ```markdown Hello World! Talking about foo here ``` This is because the first one has at least one heading present while the second one doesn't have any headings present.

kerem

2026-03-07 20:05:02 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:05:03 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 28, 2020):

The rule documentation explains the reasoning: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041

Specifically:

Rationale: The top level heading often acts as the title of a document. More information: https://cirosantilli.com/markdown-style-guide#top-level-header.

This is independent of whether or not there are other headers, so I think the current behavior of the rule is appropriate.

@DavidAnson commented on GitHub (Dec 28, 2020): The rule documentation explains the reasoning: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041 Specifically: > Rationale: The top level heading often acts as the title of a document. More information: https://cirosantilli.com/markdown-style-guide#top-level-header. This is independent of whether or not there are other headers, so I think the current behavior of the rule is appropriate.