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/section-headings

    <section> elements have headings or labels

    What it checks

    AI agents use section headings to build a topic map of your page for retrieval-augmented generation (RAG). Unlabeled sections are opaque to AI systems that chunk content by semantic boundaries, reducing the quality of retrieved context for answer generation.

    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 by sequential-headings 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

    Documented consumer behaviour, on the retrieval side rather than the vendor side. LangChain’s HTMLHeaderTextSplitter operates on <h1>, <h2> and <h3> and “adds metadata for each header ‘relevant’ to any given chunk”, with the stated goal of “keeping related text grouped (more or less) semantically”. A named library acting on the element is real evidence; a library in someone’s pipeline is not a vendor statement, and no measurement attaches a magnitude — hence B, not A. The claim the grade covers is the narrow one this audit makes: sections need real heading elements to be segmented on.

    Sources