URL: /rules/a11y/heading-order

---
title: "Heading Order"
description: "Checks that heading levels don't skip"
---

Checks that heading levels don't skip

| | |
|---|---|
| **Rule ID** | `a11y/heading-order` |
| **Category** | [Accessibility](/rules/a11y) |
| **Scope** | Per-page |
| **Severity** | warning |
| **Weight** | 4/10 |

## Solution

Headings should follow a logical hierarchy without skipping levels. Screen reader users navigate by headings, so skipping from H1 to H3 is confusing. Correct order: H1 -> H2 -> H3 (not H1 -> H3). You can have multiple headings at the same level, and you can go back up (H3 -> H2 is fine). Think of headings as an outline - they should make sense when read alone.

## Enable / Disable

### Disable this rule

```toml squirrel.toml
[rules]
disable = ["a11y/heading-order"]
```

### Disable all Accessibility rules

```toml squirrel.toml
[rules]
disable = ["a11y/*"]
```

### Enable only this rule

```toml squirrel.toml
[rules]
enable = ["a11y/heading-order"]
disable = ["*"]
```