Skip to content

MD001 - Heading levels should only increment by one

Aliases: heading-increment

What this rule does

Prevents skipping heading levels (like jumping from # to ### without ##).

Why this matters

  • Document structure: Logical heading hierarchy makes documents easier to navigate
  • Accessibility: Screen readers rely on proper heading order to help users
  • Table of contents: Automated TOC generators need correct heading levels
  • SEO: Search engines use heading structure to understand content

Examples

✅ Correct

# Title
## Chapter 1
### Section 1.1
### Section 1.2
## Chapter 2
### Section 2.1

❌ Incorrect

# Title
### Section 1.1     (skipped level 2)
##### Subsection    (skipped levels 2, 3, and 4)

🔧 Fixed

# Title
## Section 1.1
### Subsection

Configuration

[MD001]
front-matter-title = true  # Count a title in front matter as an implicit level 1 heading (default: true)
front-matter-title-pattern = "^(title|header):"  # Regex matching the front matter line that holds the title

front-matter-title

A document whose front matter carries a title starts at level 1 already, so its first body heading should be a level 2:

---
title: Getting Started
---

## Installation

With front-matter-title = false the front matter is ignored and that document may open at any level.

front-matter-title-pattern

Set this when the title lives under a different key. The pattern is matched against the front matter lines, and replaces the default title: lookup:

[MD001]
front-matter-title-pattern = "^header:"

---
header: Getting Started
---

### Installation

That jumps from the implicit level 1 to a level 3 and is flagged. An empty pattern means "no pattern": the default title: lookup applies.

Automatic fixes

This rule automatically adjusts heading levels to maintain proper hierarchy, changing skipped levels to the next appropriate level.

Learn more

  • MD003 - Heading style should be consistent
  • MD022 - Headings should be surrounded by blank lines