Heading Structure Analyzer

Heading Structure Analyzer

An enterprise-grade, high-performance H1–H6 heading hierarchy linter, WCAG 2.2 accessibility auditor, and SEO content architecture analyzer for BrowserMesh.

Inspects, visualizes, and audits heading structures across static HTML and client-hydrated Single Page Applications (SPAs). Simultaneously executes a 35+ rule diagnostic engine covering skipped hierarchy levels, missing or multiple H1s, ARIA heading overrides, HTML5 landmark semantics, DOM nesting bloat, and 2026 AI Overviews / Search Generative Experience (GEO) snippet readiness.

The premier modern alternative to Screaming Frog SEO Spider (£209/yr), Sitebulb ($162–$420/yr), Ahrefs Site Audit, and WebAIM WAVE.

🎯 Target Audience & Industry Solutions

• Technical SEO Specialists & Web Quality Auditors: Instantly detect missing H1 headings, improper multiple H1 usages, skipped heading levels (e.g. <h2> jumping straight to <h4>), and empty heading tags across catalog pages.
• Accessibility & Compliance Officers (ADA / WCAG 2.2 / EAA 2025): Verify adherence to WCAG SC 1.3.1 (Info and Relationships) and SC 2.4.6 (Headings and Labels) to eliminate legal compliance risks under the European Accessibility Act.
• Frontend Engineers & Jamstack Developers: Audit client-rendered applications (Next.js, Nuxt, Remix, React, Vue, SvelteKit) to catch framework span nesting bugs, hidden CSS opacity glitches, and aria-level mismatches.
• Content Strategists & SEO Copywriters: Optimize headings for Google AI Overviews, conversational search, and citation grounding by evaluating question-based headings, power words, stop-word ratios, and Flesch readability scores.
• QA Automation & CI/CD Teams: Integrate automated heading hierarchy checks directly into deployment pipelines to block heading regressions before releasing to production.

🚀 Key Features

1. 5-Layer Deep Heading Audit Engine

Inspects document outlines across 5 specialized diagnostic layers simultaneously:

• Layer 1: Structural Hierarchy: Validates consecutive heading sequences, flags skipped levels (h2 $\to$ h4), detects multiple H1s, identifies inverted outlines, and catches empty headings.
• Layer 2: Content Quality & Clarity: Evaluates character length bounds (20–70 chars for H1), detects generic filler phrases ("Services", "Overview"), catches repetitive identical headings, and flags ALL-CAPS styling.
• Layer 3: WCAG 2.2 & EAA 2025 Accessibility: Analyzes aria-hidden tags, aria-label overrides (Label in Name), aria-level conflicts with native tags, and inaccessible image-only headings without alt text.
• Layer 4: 2026 AI Overviews & Search Generative Experience (GEO): Analyzes conversational question patterns (what, how, why), listicle numbered formats, deep-link anchor ID coverage, and readability metrics.
• Layer 5: HTML5 Semantic & Landmark Architecture: Checks heading placement inside <main>, <header>, <nav>, <aside>, and <footer> landmarks, flags inappropriate interactive parent wrappers (<button>, <label>), and detects deep DOM bloat.

2. Full-Featured 35+ Rule Diagnostic Taxonomy

Detects and provides prescriptive remediation instructions across 35+ specific issue types:

• Critical Issues (-15 pts): no_headings, missing_h1, missing_h1_start, skipped_level, empty_heading, empty_heading_no_aria, image_heading_no_alt, aria_level_mismatch, heading_role_override, heading_inside_heading, all_headings_hidden, inappropriate_parent.
• Warnings (-5 pts): multiple_h1, h1_too_short, h1_too_long, heading_too_short, heading_too_long, duplicate_heading, aria_hidden_heading, hidden_heading, aria_label_override, excessive_depth, h1_wrong_landmark, missing_main_landmark, no_landmark_structure, most_headings_hidden, eaa_compliance_risk, keyword_stuffing.
• Info Notices (Educational): heading_inside_link, similar_headings, heading_opacity_zero, screen_reader_only, multiple_h1_sectioning, missing_anchor_ids, question_format, numbered_heading, all_caps_heading, generic_heading, vague_pronoun, negative_sentiment, excessive_dom_depth, div_instead_of_section, missing_semantic_context, missing_nav_landmark, no_power_words_h1, low_readability.

3. Stack-Based O(n) Hierarchy Tree Generation

Builds a complete hierarchical parent-child JSON tree representing the document's true reading outline, with automated issue attribution at every individual node level.

4. Calibrated Multi-Engine Execution (auto / http / browser)

• HTTP Mode: Lightning-fast Cheerio parsing (~200–500ms) with Brotli/Gzip decompression and modern Chrome User-Agent.
• Browser Mode: Full stealth Playwright Chromium browser (CloakBrowser) for client-hydrated SPAs and dynamic JavaScript DOMs.
• Auto Mode (Default): Attempts rapid HTTP fetch first; automatically escalates to stealth browser rendering if bot challenges (Cloudflare 403/503) or unhydrated SPA shells (0 static headings) are detected.

5. Fair, Standards-Compliant Scoring Model

• Features weighted deductions with safety caps (critical: max 60 pts, warning: max 25 pts).
• Severity-based ceiling caps ensure that pages with active critical failures cannot receive "Excellent" ($\le 85$), and pages with warnings never receive an undeserved 100 ($\le 95$).
• Educational info notices (such as HTML5 block links and catalog menu similarities) never deduct points.

📊 Comparison with Paid Alternatives

⚙️ How to Configure Your Job

Example Input Configuration

{
  "urls": "https://example.com/blog\nhttps://example.com/pricing\nhttps://example.com/about",
  "scrapeMode": "auto",
  "extractAriaHeadings": true,
  "includeHiddenHeadings": true,
  "enableSeoInsights": true,
  "concurrency": 8,
  "timeout": 30,
  "limit": 100
}

📥 Supported URL & Link Formats

• Standard HTTP/HTTPS URLs: https://example.com, http://blog.example.com/post-1
• Bare Domain Names: example.com (automatically normalized to https://example.com)
• Deep Content Paths: https://example.com/docs/api/v1/endpoints#overview
• Batch Multiline Input: Raw newline-separated lists, comma-separated lists, or mixed URL inputs.
• SSRF & Security Filtering: Automatically blocks internal network requests, loopbacks (127.0.0.1, localhost), and cloud metadata IP addresses (169.254.169.254).

📋 Output Fields Reference (15 Fields)

💡 Example Output

[
  {
    "url": "https://infisical.com/",
    "pageUrl": "https://infisical.com/",
    "domain": "infisical.com",
    "statusCode": 200,
    "status": "healthy",
    "title": "Infisical | Open Source Secret Management Platform",
    "h1": "Open Source Secret Management",
    "headings": [
      {
        "hasAnchor": true,
        "tag": "h1",
        "level": 1,
        "text": "Open Source Secret Management",
        "html": "<h1 class=\"text-4xl font-bold tracking-tight\">Open Source Secret Management</h1>",
        "position": 0,
        "depth": 5,
        "ariaHidden": false,
        "isHidden": false,
        "parentElement": "div",
        "parentSemanticTag": "main",
        "isInLandmark": true,
        "landmarkType": "main"
      },
      {
        "hasAnchor": true,
        "tag": "h2",
        "level": 2,
        "text": "Centralize secrets across your infrastructure",
        "html": "<h2 id=\"centralize\" class=\"text-2xl font-semibold\">Centralize secrets across your infrastructure</h2>",
        "position": 1,
        "depth": 6,
        "ariaHidden": false,
        "isHidden": false,
        "parentElement": "section",
        "parentSemanticTag": "section",
        "isInLandmark": true,
        "landmarkType": "main"
      }
    ],
    "hierarchy": {
      "text": "Document Root",
      "level": 0,
      "tag": "root",
      "id": "root",
      "html": "",
      "position": -1,
      "items": [
        {
          "text": "Open Source Secret Management",
          "level": 1,
          "tag": "h1",
          "id": "open-source-secret-management",
          "html": "<h1 class=\"text-4xl font-bold tracking-tight\">Open Source Secret Management</h1>",
          "position": 0,
          "items": [
            {
              "text": "Centralize secrets across your infrastructure",
              "level": 2,
              "tag": "h2",
              "id": "centralize",
              "html": "<h2 id=\"centralize\" class=\"text-2xl font-semibold\">Centralize secrets across your infrastructure</h2>",
              "position": 1,
              "items": [],
              "issues": []
            }
          ],
          "issues": []
        }
      ],
      "issues": []
    },
    "metrics": {
      "total": 11,
      "h1Count": 1,
      "h2Count": 6,
      "h3Count": 4,
      "h4Count": 0,
      "h5Count": 0,
      "h6Count": 0,
      "maxDepth": 3,
      "headingsWithIdCount": 10,
      "anchorCoveragePct": 91,
      "avgHeadingLength": 38
    },
    "audit": {
      "score": 100,
      "grade": "Excellent",
      "totalIssues": 2,
      "criticalCount": 0,
      "warningCount": 0,
      "infoCount": 2,
      "issues": [
        {
          "type": "no_power_words_h1",
          "severity": "info",
          "message": "H1 does not contain high-engagement power words",
          "recommendation": "Consider adding persuasive power words (e.g. \"Complete\", \"Guide\", \"Proven\") to boost CTR."
        },
        {
          "type": "missing_nav_landmark",
          "severity": "info",
          "message": "No heading found within a <nav> landmark element",
          "recommendation": "Consider providing accessible headings for navigation sections."
        }
      ]
    },
    "accessibility": {
      "wcagLevel": "Pass",
      "eaaCompliant": true,
      "hiddenCount": 0,
      "ariaIssues": []
    },
    "seoInsights": {
      "hasQuestionHeadings": false,
      "hasNumberedHeadings": false,
      "hasAnchorIds": true,
      "aiOverviewReadiness": "High",
      "questionHeadingCount": 0,
      "anchorIdPercentage": 91,
      "avgHeadingLength": 38,
      "powerWordCount": 0,
      "readabilityScores": [
        { "heading": "Open Source Secret Management", "score": 85 },
        { "heading": "Centralize secrets across your infrastructure", "score": 78 }
      ]
    },
    "scrapeMode": "http",
    "error": null
  }
]

💡 Best Practices & Frequently Asked Questions

Can a webpage have multiple H1 headings?

While HTML5 formally introduced the outline algorithm allowing an <h1> per <section> or <article>, search engines (Google, Bing) and screen readers overwhelmingly favor maintaining a single primary H1 per document. Multiple H1s dilute topic authority and confuse assistive technology users navigating page outlines.

Why does the analyzer flag skipped heading levels as Critical?

Skipping heading levels (e.g., jumping from <h2> directly to <h4>) violates WCAG 2.2 Success Criterion 1.3.1 (Info and Relationships). Screen reader users rely on headings to build mental models of content hierarchies; skipping levels implies missing sections or broken content structure.

How does the plugin handle client-rendered React/Next.js/Vue apps?

In 'auto' mode, if static HTTP extraction yields 0 headings or detects client-side hydration shells (<div id="__next">, <div id="root">), the plugin automatically escalates to stealth Chromium (CloakBrowser). It renders the live DOM, executes entrance animations, and audits hydrated headings accurately.

Are headings inside links (<a><h2>...</h2></a>) allowed?

Yes. The W3C HTML5 specification (§4.5.1) explicitly permits block-level anchor links wrapping headings. The analyzer recognizes valid HTML5 block links and issues an educational info notice (heading_inside_link) rather than penalizing the audit score.