Skip to content

MD001 - heading-increment

Description

This rule checks that heading levels increment sequentially without skipping levels. For example, an h1 should be followed by an h2, not directly by an h3 or h4. Both ATX-style headings (using # characters) and setext-style headings (using underlines with = or -) are checked.

Rationale

Headings represent the structure of a document and can be confusing when skipped, especially for accessibility scenarios. Screen readers and other assistive technologies rely on proper heading hierarchy to accurately convey the document's structure. If front matter contains a title (matched by the front_matter_title regex), it is treated as an implicit h1, so the first heading in the document should be h2. Set front_matter_title to an empty string to disable this behavior.

Configuration

front_matter_title

Regex pattern to match title in front matter. If front matter contains a matching line, it is treated as an implicit h1. Set to empty string to disable.

  • Default: ^\s*title\s*[:=]

Examples

Invalid

# Heading 1

### Heading 3

###### Heading 6

Valid

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

## Another Heading 2

### Another Heading 3