Heading Rules
Heading rules ensure proper document structure, hierarchy, and formatting for markdown headings.
Rules in This Category
| Rule | Description | Fix |
|---|---|---|
| MD001 | Heading levels should only increment by one level at a time | ❌ |
| MD002 | First heading should be a top-level heading | ❌ |
| MD003 | Heading style (ATX vs Setext) | ❌ |
| MD018 | No space after hash on ATX style heading | ✅ |
| MD019 | Multiple spaces after hash on ATX style heading | ✅ |
| MD020 | No space inside hashes on closed ATX style heading | ✅ |
| MD021 | Multiple spaces inside hashes on closed ATX style heading | ✅ |
| MD022 | Headings should be surrounded by blank lines | ❌ |
| MD023 | Headings must start at the beginning of the line | ✅ |
| MD024 | Multiple headings with the same content | ❌ |
| MD025 | Multiple top-level headings in the same document | ❌ |
| MD026 | Trailing punctuation in heading | ❌ |
| MD041 | First line in file should be a top-level heading | ❌ |
Best Practices
Document Structure
A well-structured document follows these heading principles:
- Start with H1: Documents should begin with a single H1 heading
- Sequential Levels: Never skip heading levels (H1 → H3 is wrong)
- Logical Hierarchy: Use headings to create a document outline
- Consistent Style: Use either ATX (
#) or Setext style consistently
ATX vs Setext Headings
ATX Style (Recommended):
# Heading 1
## Heading 2
### Heading 3
Setext Style (Limited to H1 and H2):
Heading 1
=========
Heading 2
---------
Closed ATX Headings
Some prefer closed ATX headings for symmetry:
# Heading 1 #
## Heading 2 ##
### Heading 3 ###
Rules MD020 and MD021 ensure proper formatting of closed headings.
Common Issues and Solutions
Issue: Inconsistent Heading Hierarchy
Problem: Jumping between heading levels disrupts document flow.
# Main Title
### Subsection (skips H2)
## Back to H2
##### Deep section (skips H3 and H4)
Solution: Maintain sequential heading levels.
# Main Title
## Section
### Subsection
## Another Section
### Subsection
#### Deeper Content
##### Deepest Content
Issue: Multiple H1 Headings
Problem: Multiple top-level headings confuse document structure.
# First Title
Content...
# Second Title
More content...
Solution: Use a single H1 with H2s for major sections.
# Document Title
## First Section
Content...
## Second Section
More content...
Issue: Indented Headings
Problem: Headings with leading spaces may not render correctly.
# This might not be a heading
## This is problematic
Solution: Start headings at the beginning of the line.
# Proper Heading
## Another Proper Heading
Accessibility Considerations
Proper heading structure is crucial for accessibility:
- Screen Readers: Use headings to navigate and understand document structure
- Keyboard Navigation: Many tools allow jumping between headings
- Document Outline: Assistive technologies generate outlines from headings
- WCAG Compliance: Proper heading hierarchy is part of WCAG 2.1 guidelines
Integration with mdBook
mdBook relies heavily on proper heading structure:
- Table of Contents: Generated from heading hierarchy
- Search Index: Headings are weighted in search results
- Navigation: Sidebar navigation reflects heading structure
- Anchors: Automatic anchor generation for deep linking
Configuration Examples
Enforce ATX Style Only
[MD003]
style = "atx"
Allow Trailing Punctuation
[MD026]
enabled = false
Require Document to Start with H1
[MD041]
level = 1
front_matter_title = false