Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

# 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"
ValueDescription
atxUse # style headings
atx_closedUse # Heading # style
setextUse underline style (H1/H2 only)
consistentMatch 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
  • MD001 - Heading increment
  • MD018 - Space after hash in ATX headings
  • MD019 - Multiple spaces after hash