[GH-ISSUE #1420] MD025 does not trigger when first lines are empty and/or comments #2531

New issue

Closed

opened 2026-03-07 20:08:37 +03:00 by kerem · 1 comment

kerem commented

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

Owner

Originally created by @xefiry on GitHub (Nov 15, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1420

The error MD025 "Multiple top-level headings in the same document" should trigger when there is more than one heading level 1 in the document.

However, if there are empty and/or comment lines before the first heading, the error does not trigger.

Example with an empty line and a comment


<!-- omit in toc -->
# Title

- [Foo](#foo)

# Foo

In this example, the comment is to ignore Title in the generation of the table of content by the extension Markdown All in One, but any comment will do.

The error can be reproduced with any amount of comment lines or empty lines before the first heading.

Originally created by @xefiry on GitHub (Nov 15, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1420 The error MD025 "Multiple top-level headings in the same document" should trigger when there is more than one heading level 1 in the document. However, if there are empty and/or comment lines before the first heading, the error does not trigger. Example with an empty line and a comment ```markdown  # Title - [Foo](#foo) # Foo ``` In this example, the comment is to [ignore Title in the generation of the table of content by the extension Markdown All in One](https://github.com/yzhang-gh/vscode-markdown?tab=readme-ov-file#table-of-contents), but any comment will do. The error can be reproduced with any amount of comment lines or empty lines before the first heading.

kerem

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

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-07 20:08:38 +03:00

Author

Owner

@DavidAnson commented on GitHub (Nov 16, 2024):

This rule is behaving as documented (a top level heading must be on the first line), but I agree that being preceeded by a blank line doesn't seem like it should disable the rule.

https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md

@DavidAnson commented on GitHub (Nov 16, 2024): This rule is behaving as documented (a top level heading must be on the first line), but I agree that being preceeded by a blank line doesn't seem like it should disable the rule. https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md