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

MD001 - Heading Increment

Heading levels should only increment by one level at a time.

This rule is triggered when you skip heading levels in a markdown document. For example, a heading level 1 should be followed by level 2, not level 3.

Why This Rule Exists

Proper heading hierarchy improves document structure, accessibility, and navigation. Screen readers and document outlines rely on sequential heading levels to convey the document's organization to users.

Examples

❌ Incorrect (violates rule)

# Title

### Subsection (skips h2)

## Back to h2

##### Deep section (skips h3 and h4)

✅ Correct

# Title

## Section

### Subsection

#### Subsubsection

##### Deep section

Configuration

This rule has no configuration options. It always enforces strict sequential heading levels.

When to Disable

Consider disabling this rule if:

  • You're working with generated content that doesn't follow strict hierarchy
  • You're importing documentation from external sources with different conventions
  • Your project has specific heading level requirements

Rule Details

  • Rule ID: MD001
  • Aliases: heading-increment
  • Category: Structure
  • Severity: Warning
  • Automatic Fix: Not available

Common Violations and Solutions

Skipping from H1 to H3

Problem:

# Main Title
### Subsection

Solution:

# Main Title
## Section
### Subsection

Deep Nesting Without Intermediate Levels

Problem:

## Chapter
##### Deep Detail

Solution:

## Chapter
### Section
#### Subsection
##### Deep Detail

Rationale for Sequential Headings

  1. Accessibility: Screen readers rely on proper heading hierarchy to help users navigate documents
  2. Document Structure: Sequential headings create a logical outline
  3. SEO: Search engines use heading structure to understand content hierarchy
  4. Table of Contents: Automated TOC generators expect proper nesting

Integration with mdBook

mdBook's sidebar generation relies on proper heading structure. Violating this rule can lead to:

  • Broken navigation in the sidebar
  • Incorrect TOC generation
  • Poor mobile navigation experience
  • MD002 - First heading should be a top-level heading
  • MD003 - Heading style consistency
  • MD022 - Headings should be surrounded by blank lines
  • MD025 - Multiple top-level headings in the same document

References