Headings follow proper hierarchy

heading_hierarchy

Verifies headings follow proper hierarchy (H1 > H2 > H3).

What does this rule check?

Heading tags should follow a logical hierarchy: H1 for the main topic, H2 for major sections, H3 for subsections, and so on. Skipping levels (e.g., going from H1 directly to H3) breaks the document outline.

Why is this important?

Proper heading hierarchy helps search engines understand content structure and section importance. It also improves accessibility for screen reader users who navigate by headings.

How to fix

Restructure headings to follow a sequential hierarchy. Don't skip heading levels. Use H2 after H1, H3 after H2, etc.

Examples

<h1>Main Title</h1>
<h3>Section One</h3>  <!-- Skipped H2! -->
<h5>Detail</h5>       <!-- Skipped H4! -->

<h1>Main Title</h1>
<h2>Section One</h2>
<h3>Detail</h3>

Agent fix snippet

Copy this snippet and paste it into your AI coding agent to fix this issue automatically.

Review all heading tags and fix the hierarchy:
- H1: main page topic (one only)
- H2: major sections
- H3: subsections within H2
- H4: subsections within H3
Never skip levels.