---
title: MD003 - Heading Style
description: Ensures consistent heading style throughout the document
---

# MD003 - Heading Style

**Rule Type**: `warning`

**Default Style**: `atx`

## Description

This rule enforces a consistent heading style in Markdown documents. Markdown supports multiple heading styles, and this rule ensures that only one style is used throughout a document.

## Configuration

This rule has the following configuration options:

- `style`: The heading style to enforce. Can be one of:
  - `"consistent"`: Enforce the first heading style used in the document (default)
  - `"atx"`: Enforce ATX-style headings (`# Heading`)
  - `"atx_closed"`: Enforce closed ATX-style headings (`# Heading #`)
  - `"setext"`: Enforce setext-style headings (`Heading\n=======`)
  - `"setext*with*atx"`: Enforce setext-style for level 1-2 headings and ATX for lower levels

Example configuration:

```json
{
  "MD003": {
    "style": "atx"
  }
}
```

<!-- markdownlint-disable -->
## Examples

### ✓ Correct (ATX Style)

```markdown
# First Level Heading
## Second Level Heading
### Third Level Heading
```

### ✓ Correct (Closed ATX Style)

```markdown
# First Level Heading #
## Second Level Heading ##
### Third Level Heading ###
```

### ✓ Correct (Setext Style for Level 1 and 2)

```markdown
First Level Heading
==================

Second Level Heading
------------------
```

### ❌ Incorrect (Mixed Styles)

```markdown
# First Level Heading

Second Level Heading
------------------

### Third Level Heading
```
<!-- markdownlint-enable -->

## Special Cases

- Setext-style headings only support level 1 (`=`) and level 2 (`-`) headings
- When using `setext*with*atx`, levels 1-2 must use setext style, and levels 3+ must use ATX style
- The rule ignores headings in code blocks
- When style is set to "consistent", the first heading style used in the document is enforced

## Related Rules

- [MD001 - Heading Levels](md001.md): Ensures heading levels increment by one level at a time
- [MD022 - Headings Should Be Surrounded by Blank Lines](md022.md): Ensures headings have blank lines before and after
- [MD023 - Headings Must Start at the Beginning of the Line](md023.md): Ensures headings are not indented
