Capyseo Logo Capyseo

Heading Rules

Heading Rules

Rules for validating heading structure and SEO.

heading-hierarchy

Validates proper H1-H6 heading structure.

Checks

  • Page has exactly one H1
  • Headings don't skip levels (H1 → H3)
  • H1 comes first

Examples

Pass:

<h1>Main Title</h1> <h2>Section 1</h2> <h3>Subsection 1.1</h3> <h2>Section 2</h2>

Fail (no H1):

<h2>Section Title</h2> <!-- Error: Page is missing an H1 heading -->

Fail (multiple H1):

<h1>Title One</h1> <h1>Title Two</h1> <!-- Warning: Multiple H1 headings found (2) -->

Fail (skipped level):

<h1>Main Title</h1> <h3>Subsection</h3> <!-- Warning: Skipped heading level (h1 to h3) -->

Configuration

rules: { 'heading-hierarchy': { severity: 'warning', }, }

empty-heading

Detects empty heading elements.

Checks

  • Headings have visible text content
  • Not just whitespace
  • Not just invisible elements

Examples

Fail:

<h2></h2> <!-- Warning: Empty heading element --> <h3> </h3> <!-- Warning: Heading contains only whitespace --> <h2><span class="icon"></span></h2> <!-- Warning: Heading has no visible text -->

Pass:

<h2>About Us</h2> <h3><span class="icon"></span> Features</h3>

Configuration

rules: { 'empty-heading': { severity: 'warning', }, }

heading-keywords

Checks H1 contains relevant keywords from page title.

Checks

  • H1 shares words with page title (30%+ overlap)
  • Primary keywords appear in H1

Examples

Pass:

<title>Getting Started with React - Tutorial</title> <h1>Getting Started with React</h1>

Warning:

<title>React Tutorial for Beginners</title> <h1>Welcome to Our Site</h1> <!-- Info: H1 may not align well with page title keywords -->

Why It Matters

Search engines expect the H1 to reflect the page's main topic, which should align with the title tag.

Configuration

rules: { 'heading-keywords': { severity: 'info', }, }

Best Practices

Heading Structure

<!-- Good structure --> <h1>Complete Guide to React Hooks</h1> <h2>What are Hooks?</h2> <h3>History of Hooks</h3> <h2>useState Hook</h2> <h3>Basic Usage</h3> <h3>Common Patterns</h3> <h2>useEffect Hook</h2>

H1 Guidelines

Do Don't
One H1 per page Multiple H1s
Match page topic Generic "Welcome"
Include keywords Keyword stuffing
Descriptive Too vague

Heading Checklist

  • Single H1 that describes page content
  • H1 contains primary keyword
  • No skipped heading levels
  • No empty headings
  • Headings create clear outline