MD003 - Heading Style
Heading style should be consistent throughout the document.
Why This Rule Exists
Markdown supports multiple heading styles. Mixing styles within a document creates visual inconsistency and can confuse readers and tooling.
Heading Styles
ATX Style (Recommended)
# Heading 1
## Heading 2
### Heading 3
ATX Closed Style
#Heading 1#
##Heading 2##
###Heading 3###
Setext Style (H1 and H2 only)
Heading 1
=========
Heading 2
---------
Examples
Incorrect
# ATX Heading
Setext Heading
--------------
### Another ATX
Correct
# Main Title
## Section One
### Subsection
Configuration
[MD003]
style = "atx" # Options: "atx", "atx_closed", "setext", "consistent"
| Value | Description |
|---|---|
atx | Use # style headings |
atx_closed | Use # Heading # style |
setext | Use underline style (H1/H2 only) |
consistent | Match the first heading's style |
When to Disable
- Working with legacy documents using mixed styles
- Importing content from multiple sources
Rule Details
- Rule ID: MD003
- Aliases: heading-style
- Category: Structure
- Severity: Warning
- Auto-fix: Yes