Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    content-extraction/sequential-headings

    Sequential heading hierarchy

    What it checks

    AI systems build content outlines from headings to understand document structure. Skipped levels (e.g., h1 to h3 without h2) break the hierarchy, causing agents to misinterpret section nesting and produce inaccurate content summaries. Fix heading levels to follow a sequential order.

    Why it matters

    Real h1–h6 elements are the boundary markers that heading-aware chunkers and accessibility-tree serializers use to segment a page; visually-styled div, span or p pseudo-headings are not. LangChain’s HTMLHeaderTextSplitter and HTMLSectionSplitter split on header tags, and attach the enclosing header chain as chunk metadata. Readability scores h2–h6, and uses a lone h1 to recover the article title. a11y snapshots emit heading nodes with an explicit level. If a page has no true heading elements, these consumers produce either one undifferentiated blob (no heading metadata to attach) or fall back to guessing (HTMLSectionSplitter infers sections from font size).

    Evidence

    Heading hierarchy

    Consumer behaviour on the RAG side is documented. LangChain’s splitter docs state that it operates on <h1>, <h2> and <h3>, and ‘adds metadata for each header “relevant” to any given chunk’. The stated goal is ‘keeping related text grouped (more or less) semantically and preserving context-rich information encoded in document structures’ [langchain-html-splitters]. On the agent side, HTML-AAM maps h1–h6 to the heading role with aria-level [w3c-html-aam], and Playwright MCP snapshots explicitly include ‘headings with levels’ [playwright-mcp-snapshots]; Anthropic’s read_page returns the same tree [anthropic-browser-use-tool].

    On the extraction side, Readability scores section, h2 to h6, p, td and pre when it looks for the article body, and prefers the single h1 as the title when <title> is ambiguous [mozilla-readability-source]. Cloudflare’s markdown conversion maps headings to ‘##’, costing ~3 tokens vs 12-15 for the HTML form [cloudflare-markdown-for-agents]. Baseline: 59% of mobile sites pass the ordered-headings audit [web-almanac-2025-accessibility].

    Limits

    The falsifiable claim that survives is ‘headings must exist and be real elements’. The stricter claim audited here is that levels must never skip, as in h2 to h4. That claim has no documented consumer. Every splitter and snapshot cited tolerates skipped levels, and simply records whatever level it finds. No vendor doc or study shows a measured penalty for skipped levels in LLM parsing. Google states outright that ‘there are no additional requirements to appear in AI Overviews or AI Mode, nor other special optimizations necessary’ [google-ai-features-docs], so no AI-search vendor endorses heading structure as an extraction or ranking requirement.

    LangChain is a library used by site owners’ own pipelines, not a public crawler of third-party sites — treat it as mechanism evidence, not proof that ChatGPT chunks your page this way.

    How it scores

    The B applies to the well-evidenced half of this signal — that real h1–h6 elements are what heading-aware chunkers such as LangChain’s HTMLHeaderTextSplitter segment on. It does not extend to the stricter claim this audit checks. No documented consumer cares whether levels skip: every splitter and accessibility-tree snapshot examined tolerates an h2 followed by an h4 and simply records the level it finds, and no vendor document or study shows a measurable cost. That gap is why the finding reads as a structure warning rather than a claim about how agents read the page.

    Sources