majiayu000 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/