No skipped heading levels

ZMD002

Ensure headings (`<h1>`–`<h6>`) follow a logical, sequential order to maintain a clear document outline.

✅ Good

<h2>Main section</h2>
<h3>Subpoint</h3>
<p>Details…</p>

❌ Bad

<h2>Main section</h2>
<h4>Subpoint</h4>
<p>Details…</p>

When: A heading level is more than one step deeper than the previous heading

Warning: Heading level skipped: <hX> after <hY>

Solution: Follow sequential heading order

Why it matters

Accessibility: Skipping levels disrupts screen-reader users’ mental model of document structure and impairs navigation.

SEO: Misordered headings can confuse search engine crawlers about content hierarchy.

In brief

  • Goal: Maintain a nested document structure via proper heading nesting.
  • What to do: Do not jump more than one level (e.g. `<h2>` → `<h4>`).
  • Why: Screen readers and sighted users rely on heading order to understand hierarchy and navigate content.

Intent

Prevent confusion in document structure by enforcing sequential heading levels without skips.

Benefits

  • Consistent outline improves comprehension for users with cognitive disabilities.
  • Screen-reader users can predict content flow and navigate headings linearly.
  • Search engines better understand content hierarchy, aiding SEO.

Techniques

  • H42: Using h2–h6 to create subheadings in sequence.
  • H65: Validating heading order programmatically.

HTML Semantics

Each heading tag defines a section in the outline; skipping levels breaks the implicit tree structure.

Tips & edge cases

  • Use linter rules or automated tests to catch skips early.
  • In long documents, consider an outline to plan heading levels before writing.