MD025 - Single Top-Level Heading
Multiple top-level headings in the same document.
Why This Rule Exists
A document should have a single H1 heading that serves as its title. Multiple H1 headings suggest the content should be split into separate documents or the heading hierarchy needs adjustment.
Examples
Incorrect
# First Title
Content here.
# Second Title
More content.
Correct
# Document Title
## First Section
Content here.
## Second Section
More content.
Configuration
[MD025]
level = 1 # Heading level to check (default: 1)
front_matter_title = "" # Regex for front matter title
When to Disable
- SUMMARY.md files in mdBook (use MDBOOK025 instead)
- Documents intentionally containing multiple articles
- Changelog files with version headings as H1
Rule Details
- Rule ID: MD025
- Aliases: single-title, single-h1
- Category: Structure
- Severity: Warning
- Auto-fix: No
mdBook Integration
For SUMMARY.md files, this rule is automatically relaxed. Use MDBOOK025 which understands mdBook's multi-section SUMMARY format.