feat: add no-multiple-h1 rule

[Pixel998]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request?

This PR adds a new rule no-multiple-h1 to enforce at most one h1 heading in Markdown.

What changes did you make? (Give an overview)

Added the no-multiple-h1 rule, along with documentation and tests.

I decided to name it no-multiple-h1 instead to be more explicit about what the rule does.

Related Issues

Closes #373

Is there anything you'd like reviewers to focus on?

[lumirlumir]

Currently, Markdownlint’s MD025 supports the title field in YAML front matter. It also provides an option to customize which field should be recognized as the valid H1 heading.

In contrast, @eslint/markdown supports both YAML and TOML front matter (while Markdownlint only supports YAML).

Given that, I think we should support the title field in both YAML and TOML front matter as valid H1 headings.

That’s my personal opinion — I’d love to hear what other team members think about supporting H1 detection from both YAML and TOML front matter, similar to how Markdownlint handles it.

@eslint/eslint-team

---

Also, we should support detecting <h1> HTML tags. The following code should trigger a warning:

<h1> Heading </h1>

# Heading

[nzakas]

Currently, Markdownlint’s MD025 supports the title field in YAML front matter. It also provides an option to customize which field should be recognized as the valid H1 heading.

That seems reasonable to me. So if there's a frontmatter title then that counts as an H1. 👍

[lumirlumir]

---
hello: world # title: My Title
---
# Heading 1

Still a false positive when handling comments.

Should we introduce a YAML or TOML parser like yaml?

Using only regular expressions seems too fragile.

[Pixel998]

@lumirlumir Do you have specific examples or edge cases in mind where regex parsing might fail?

[nzakas]

Let's not introduce a parser. Rules shouldn't be doing parsing. If we can't accurately detect frontmatter H1s then let's leave it off this initial version.

[nzakas]

@ntdiary please open a separate issue to request enhancements. We like to keep PRs focused on the original request.

[snitin315]

LGTM, thanks!

Leaving it open for 2nd review.