Rules / heading rules

heading.order

Default

warn

Plugin

heading

Headings start at <h1> or <h2>, and do not skip levels, such as an <h4> after an <h2>.

Why: Skipped levels break the outline of the page. Screen readers list the outline, so their users can see how sections relate and jump between them. Search engines do not rank pages by heading order, so this rule is for accessibility.

The outline holds every heading of the page, in order, including the headings of a sidebar or footer. The first heading can be an <h2>, such as a menu before the <h1>. A first heading of <h3> or lower skips levels, because the outline starts below its top.

When off: headings in any order pass.

<!-- ✗ Fails -->
<h1>Our sourdough</h1>
<h3>Ingredients</h3>

<!-- ✗ Fails -->
<h4>Menu</h4>
<h1>Our sourdough</h1>

<!-- ✓ Passes -->
<h1>Our sourdough</h1>
<h2>Ingredients</h2>

<!-- ✓ Passes -->
<h2>Menu</h2>
<h1>Our sourdough</h1>

References

• HTML spec: Headings and outlines: A heading must not be more than one level deeper than the heading before it.
• W3C WAI: Headings: Skipped levels confuse users. A page can start with an <h2> before the <h1>.
• MDN: Heading elements: Do not skip heading levels.
• axe: heading-order: The same check in axe-core, as a best practice.
• axe-core: heading-order source: axe-core lets the first heading pass.
• Lighthouse: Accessibility scoring: Lighthouse runs the same check.
• Google: SEO Starter Guide: Google Search does not care about heading order, so the rule warns.
• Search Engine Journal: Google says fixing headings won't change rankings: Google says that fixing headings does not change rankings.