check-headings
Analyze and validate HTML heading hierarchy (H1-H6) on web pages. Use when users ask to check headings structure, verify H1 presence, analyze SEO heading hierarchy, find heading issues, or audit page structure. Detects missing H1, multiple H1s, skipped levels, empty headings, and hierarchy violations.
When & Why to Use This Skill
This Claude skill automates the analysis and validation of HTML heading structures (H1-H6) to ensure optimal SEO performance and web accessibility. It identifies critical technical issues such as missing H1 tags, multiple H1s, skipped heading levels, and empty tags, providing actionable insights to improve page hierarchy and search engine visibility.
Use Cases
- SEO Auditing: Automatically scan landing pages to verify if the heading hierarchy aligns with search engine optimization best practices.
- Accessibility Compliance: Ensure websites meet WCAG standards (SC 1.3.1, 2.4.6) by maintaining a logical structure for screen readers and assistive technologies.
- Technical QA: Integrate into the web development workflow to detect 'skipped levels' or 'empty headings' before deploying new pages.
- Content Optimization: Analyze existing blog posts or articles to ensure H1-H6 tags are used correctly to outline content for both users and crawlers.
- Competitive Analysis: Audit the heading structure of competitor pages to understand their content organization and keyword placement strategy.
| name | check-headings |
|---|---|
| description | Analyze and validate HTML heading hierarchy (H1-H6) on web pages. Use when users ask to check headings structure, verify H1 presence, analyze SEO heading hierarchy, find heading issues, or audit page structure. Detects missing H1, multiple H1s, skipped levels, empty headings, and hierarchy violations. |
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
- Command:
plugins/html-checker/commands/check-headings.md - Scripts:
plugins/html-checker/scripts/src/check-headings.ts - Check Links:
plugins/html-checker/skills/check-links/ - Check Meta:
plugins/html-checker/skills/check-meta/