# 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
```markdown
# Title
## Chapter 1
### Section 1.1
### Section 1.2
## Chapter 2
### Section 2.1
```
### ❌ Incorrect
```markdown
# Title
### Section 1.1 (skipped level 2)
##### Subsection (skipped levels 2, 3, and 4)
```
### 🔧 Fixed
```markdown
# Title
## Section 1.1
### Subsection
```
## Configuration
```toml
[MD001]
front-matter-title = true # Count a title in front matter as an implicit level 1 heading (default: true)
### `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:
```markdown
---
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:
```toml
[MD001]
front-matter-title-pattern = "^header:"
```
```markdown
---
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
- [Web Content Accessibility Guidelines - Headings](https://www.w3.org/WAI/tutorials/page-structure/headings/) - Why heading structure matters
- [CommonMark headings](https://spec.commonmark.org/0.31.2/#atx-headings) - Technical specification
## Related rules
- [MD003](md003.md) - Heading style should be consistent
- [MD022](md022.md) - Headings should be surrounded by blank lines