Heading hierarchy: what the check tests and how to fix it

Passes when 80% of crawled pages have exactly one h1 and never jump down a level (h2 to h4). Pages with no headings count as failing. Low weight.

Structured Data · Weight 0.5 in the w2agent Score

How common is it?

35% of 1223 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

For each crawled page (the homepage plus a sample of same-site pages) the audit lists every h1 to h6 element in the served HTML, in document order, wherever they sit in the page, including in the navigation, header and footer. A page is good when all three hold:

  • It has at least one heading. A page with no headings is never good.
  • It has exactly one h1. Zero or two or more fails the page. An empty h1 still counts as an element.
  • Reading the headings in order, no heading is more than one level deeper than the one before it. h1 then h3 fails. Going up by any amount is fine, so h4 then h2 passes. The first heading's level is not checked, so a page that opens with an h3 is not penalised for that alone.

The score is good pages divided by all crawled pages, rounded. Pages without headings stay in the divisor.

  • Pass: 80 or more.
  • Partial: above 0 but under 80.
  • Fail: 0.

Because it counts markup and not meaning, a page can pass with useless headings, and a page can fail on a layout choice. A common case is a theme that puts the site name in an h1 in the header and the page title in a second h1. Another is a footer that uses h4 headings straight after an h2. Headings that only exist to make text bigger count the same as real ones. The check also reads the HTML as served, so headings created in the browser by script are not seen.

Why it matters to agents

MDN states that heading information can be used by user agents to build a table of contents automatically. Any tool that reads the HTML can use the same outline to split a long page into sections and find the one it needs. A clean h1 gives the page one clear subject.

No official source cited here says that AI assistants or crawlers rank pages by heading order, so do not read this check as a ranking factor. It is a content-structure check with weight 0.5, the lowest tier in the category. The practical reason to pass is that a tool that reads the HTML can follow the structure.

MDN's guidance matches this check on two points: do not skip heading levels, and avoid several h1 elements on one page. It notes the HTML standard allows more than one h1, but calls that not a best practice. The check applies the stricter reading.

How to fix it

  1. Give each page one h1 that says what the page is about, ideally close to the <title>.
  2. Use h2 for the main sections, h3 for parts of those, and so on, without gaps. Choose the level for the structure and use CSS font-size for the look.
  3. In a theme or component library, check that the logo or site name in the header is not an h1 on inner pages. A p or div with a link works.
  4. Check that footer, sidebar and card titles do not jump. If the heading before a card title is an h2, the card title can be an h2 or h3, not an h4. If the design needs small text there, style a p or div instead of using a deeper heading.
  5. Add at least one heading to pages that have none, such as landing pages built from images and styled text.
  6. View the source (not the inspector) to confirm the headings are in the HTML the server returns.

For related structure, see Semantic HTML elements, which checks for main, nav, article, section and aside, and Content accessible without JS.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →