Heading Tag Analyzer

Parses HTML and reports the heading hierarchy: count and text of h1 through h6 elements, hierarchical nesting structure, and detected violations. Common issues flagged include multiple h1 tags, skipped levels (h2 followed by h4), and empty heading elements.

Proper heading structure improves accessibility (screen reader navigation) and SEO (content structure understanding). Search engines and assistive technologies treat heading hierarchy as a primary signal of content organization.

The analyzer parses the input HTML, walks the DOM, and emits a flattened heading list with line numbers and computed indent based on level. Violation detection runs as a separate pass: count h1 elements, identify level skips by comparing each heading's level to the previous one, flag empty or whitespace-only headings, and check for headings inside elements with role="presentation" or aria-hidden="true". The output presents the structure both as an indented outline and as a flagged-issues list.

Heading hierarchy serves two distinct audiences with overlapping needs. Screen readers (NVDA, JAWS, VoiceOver) provide a "heading navigation" mode that lets users jump between headings — a shortcut equivalent to scanning section titles in a printed document. Properly structured headings turn a long page into a navigable document; poorly structured headings (or no headings) force users to read sequentially. Search engines use headings as topical signals, weighting heading text in relevance scoring and using H1 as a strong title hint when the page title element is missing or generic.

A worked example for a blog post: H1 "How CSP Headers Work" at the top of the page. H2 "What CSP Solves," H2 "Building a Policy," H2 "Common Mistakes," each containing H3 subsections like "Nonce-based scripts" and "Hash-based scripts." This structure produces a clean outline. A common mistake: nesting an H4 directly under an H2 because the visual design called for smaller text. The analyzer flags this; the fix is to use an H3 with adjusted CSS for visual size, preserving the semantic hierarchy independent of visual style.

The "multiple H1" debate has shifted over time. Early HTML5 specifications described a "document outline" algorithm where multiple H1 elements within sectioning content (article, section) would produce sensible nested outlines. In practice, screen readers never reliably implemented the document-outline algorithm; they report H1 elements as document title equivalents regardless of nesting context. Current best practice treats the page as having a single semantic H1 even within HTML5 sectioning constructs.

Limitations: the analyzer reads only the static HTML. Pages that build content dynamically with JavaScript may not have the final heading structure visible to a non-rendering parser. Single-page applications routinely fail static heading analysis; running the analyzer against a rendered DOM (via headless browser or after JavaScript execution) gives accurate results. The analyzer also does not assess heading text quality; descriptive headings are an SEO and UX best practice but require human judgment, not pattern matching.