headingRootDuplicates

Reports multiple H1 headings in the same document.

✅ This rule is included in the md logical preset.

An H1 heading is meant to define the main heading of a page, providing important structural information for both users and assistive technologies. Using more than one H1 heading per page can cause confusion for screen readers, dilute SEO signals, and break the logical content hierarchy. It’s best to use a single H1 heading per document.

Examples

❌ Incorrect

# Heading 1

# Another H1 heading

# Heading 1

# Another H1 heading

<h1>First Heading</h1>

<h1>Second Heading</h1>

✅ Correct

# Main Heading

## Subsection

### Deeper Section

<h1>Single HTML Heading</h1>

Content here.

# Single Heading

## Multiple H2s

## Are fine

### And H3s too

When Not To Use It

If you have a specific use case that requires multiple H1 headings in a single Markdown document, you can safely disable this rule. However, this is not recommended for general content as it breaks accessibility and SEO best practices.

Further Reading

• MD025 - Multiple top-level headings
• Heading hierarchy and accessibility

Equivalents in Other Linters

• ESLint: markdown/no-multiple-h1
• Markdownlint: single-h1