Heading Structure SEO Rule

Verify that every page has the required H1 and H2 heading levels for proper content structure

What This Rule Checks

Validates that every page contains at least one H1 and one H2 heading. Reports which required heading levels are missing with counts of each heading type found.

Why It Matters for SEO & GEO

Pages without proper heading structure lack clear content organization. Search engines use headings to understand content sections, and users rely on them for scanning.

How to Fix

Add at least one H1 heading for the main page topic and at least one H2 heading for primary content sections. Structure your content with a clear heading outline.

Examples

Bad

<p>Content without any headings at all</p>

Good

<h1>Main Topic</h1><h2>First Section</h2><p>Content</p><h2>Second Section</h2>

How VibeLinter Checks Heading Structure

VibeLinter’s headings/structure rule performs these checks on every page:

H1 count — Counts the number of H1 headings on the page
H2 count — Counts the number of H2 headings on the page
Missing levels report — Errors when either H1 or H2 (or both) are missing, listing which levels are absent
Structure confirmation — Reports an info-level message when the required heading structure is present, showing the count of each heading type

Configuration

// vibelinter.config.cjs
module.exports = {
  rules: {
    'headings/structure': {
      enabled: true,
      severity: 'error'
    }
  }
}

SEO Impact

Proper heading structure affects:

Content comprehension — Search engines extract section topics from H2 headings to build a content map
Featured snippets — Pages with clear H1/H2 structure are more likely to be selected for featured snippets
User experience — Headings help users quickly scan and find relevant content sections
GEO (Generative Engine Optimization) — AI models use heading structure to identify distinct content sections; proper H1/H2 structure helps AI accurately break down and cite specific sections of your content