Skip to content

MD003 - heading-style

Description

This rule enforces consistent heading styles throughout a document. It triggers when different heading formats are mixed, such as combining ATX-style headings (#) with Setext-style headings (underlined with = or -). The setext_with_atx and setext_with_atx_closed modes allow mixed styles, requiring setext for h1/h2 and ATX (or ATX closed) for h3 and above. Note that a horizontal rule (---) directly below a line of text can be misinterpreted as a setext heading underline.

Rationale

Consistent formatting makes it easier to understand a document. Mixing heading styles can be visually confusing and makes the source harder to maintain.

Configuration

style

Required heading style.

  • Default: consistent
  • Options:
    • consistent: All headings must match the style of the first heading
    • atx: All headings must use ATX-style headings (using # character)
    • atx_closed: All headings must use ATX-style with a closing # character
    • setext: All headings must use underline style (only h1/h2)
    • setext_with_atx: h1/h2 use Setext-style headings, h3+ use atx
    • setext_with_atx_closed: h1/h2 use setext, h3+ use atx_closed

Examples

Invalid

# ATX Heading 1

Setext Heading 2
----------------

### ATX Heading 3

Mixed heading styles in the same document.

Valid

# ATX Heading 1

## ATX Heading 2

### ATX Heading 3

All headings use consistent ATX style.