H1-H6 heading hierarchy logical

Issue No: 44

Category: page seo basics

Issue type: Warning

Priority: IMPORTANT

Description

Verify that heading tags in raw HTML follow a logical structural order and include a clear top-level heading signal for content organization.

How do we capture it

1. Fetch page and ensure response is HTML.
2. Parse raw HTML body and extract heading tags <h1> through <h6> in document order.
3. For each heading, store level, text content, and source position index.
4. Validate hierarchy rules:
   • At least one heading exists for content pages.
   • Prefer exactly one primary h1 where applicable.
   • Disallow large upward jumps (for example h2 directly to h4) unless intentionally nested by structure policy.
5. Build a heading sequence string (for example h1>h2>h3>h2).
6. Flag anomalies such as missing h1, multiple h1 tags, or disordered nesting transitions.
7. Constraint: only headings present in raw server HTML are checked. JavaScript-injected headings are out of scope.

What to store

Field	Type	Comment
page_url TEXT	TEXT	Crawled page URL.
heading_count INTEGER	INTEGER	Total number of heading tags h1-h6 found.
h1_count INTEGER	INTEGER	Number of h1 tags found.
heading_sequence TEXT	TEXT	Ordered sequence of heading levels in document order.
heading_nodes JSONB	JSONB	Structured heading list with level, text, and position.
has_heading_structure BOOLEAN	BOOLEAN	Whether any heading structure exists.
heading_hierarchy_is_logical BOOLEAN	BOOLEAN	Whether heading order passes hierarchy validation rules.
heading_hierarchy_violations JSONB	JSONB	Detailed list of hierarchy violations detected.
heading_capture_error TEXT	TEXT	Parsing errors or malformed HTML notes.

Condition for trigger

This audit triggers when heading structure is missing or semantically inconsistent.

• Trigger Rule 1: Missing Heading Structure

  • Target Field: has_heading_structure
  • Evaluation Logic: has_heading_structure = FALSE
  • Severity: WARNING
  • Diagnostic Message: "No heading tags were found to define page structure."

• Trigger Rule 2: Multiple Primary H1 Tags

  • Target Field: h1_count
  • Evaluation Logic: h1_count > 1
  • Severity: WARNING
  • Diagnostic Message: "Multiple H1 tags were detected; primary page topic may be ambiguous."

• Trigger Rule 3: Illogical Heading Order

  • Target Field: heading_hierarchy_is_logical
  • Evaluation Logic: heading_hierarchy_is_logical = FALSE
  • Severity: WARNING
  • Diagnostic Message: "Heading hierarchy contains non-sequential level transitions."

Sources

• Google Search Central on Headings: https://developers.google.com/search/docs/appearance/snippet#headings
• MDN Heading elements: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
• WHATWG HTML Sections and Headings: https://html.spec.whatwg.org/multipage/sections.html

Long description

Heading tags provide structural semantics that help search engines and assistive technologies interpret page organization. A logical hierarchy improves topic segmentation and content scannability. Missing or disordered headings can reduce semantic clarity, especially on long-form or content-rich pages.

Common failure scenarios checked by the crawler:

• No heading tags present.
• Multiple h1 elements competing as primary topic heading.
• Heading jumps that skip levels without clear section context.
• Empty headings with no meaningful text content.

How to Fix

Use heading tags to reflect a clear content outline with one dominant top-level heading where appropriate and orderly subsection levels. Keep heading progression consistent across templates and avoid using heading levels purely for visual styling.