Check Headings

Analyze and validate HTML heading hierarchy (H1-H6) on web pages for SEO and accessibility compliance.

Quick Start

Run the heading checker from the scripts directory:

cd /path/to/html-checker/scripts
bun src/check-headings.ts <URL>

CLI Options

| Option | Short | Default | Description | |--------|-------|---------|-------------| | --verbose | -v | false | Show detailed heading content | | --json | -j | false | Output results as JSON |

Checks Performed

| Check | Severity | Description | |-------|----------|-------------| | Missing H1 | Error | Page has no H1 heading | | Multiple H1 | Warning | Page has more than one H1 | | Skipped Level | Warning | Heading level skipped (e.g., H2 to H4) | | Empty Heading | Error | Heading tag with no text content | | Wrong Order | Warning | Heading appears before its parent level |

Usage Examples

Basic check

bun src/check-headings.ts https://example.com

Verbose output with heading content

bun src/check-headings.ts https://example.com --verbose

JSON output for automation

bun src/check-headings.ts https://example.com --json

Output

The checker provides:

Summary - Total headings found per level
Issues - List of problems with severity
Hierarchy - Visual tree of heading structure
Recommendations - Actionable fixes

Example Output

Heading Analysis for https://example.com

Summary:
  H1: 1  H2: 5  H3: 12  H4: 3  H5: 0  H6: 0

Issues Found: 2
  [WARNING] Skipped level: H2 -> H4 at line 45
  [ERROR] Empty heading: H3 at line 78

Hierarchy:
  H1: Welcome to Example
    H2: About Us
      H3: Our Mission
      H3: Our Team
    H2: Services
      H4: Web Development  <-- Skipped H3

SEO Best Practices

One H1 per page: The H1 should match the page's main topic
Sequential hierarchy: Don't skip levels (H2 -> H4)
Descriptive headings: Avoid generic text like "Read More"
Keyword inclusion: Include target keywords naturally
Logical structure: Headings should outline page content

Accessibility (WCAG)

SC 1.3.1: Headings must convey structure
SC 2.4.6: Headings must be descriptive
SC 2.4.10: Section headings organize content

Related Files

Scripts: /plugins/html-checker/scripts/
Check Links: /plugins/html-checker/skills/check-links/