How to fix heading structure

By Matt Kerr·Published 15 September 2026

Your audit flagged your headings, and you have read contradictory advice about them for years. One H1 per page, or as many as you like. Never skip a level, or nobody cares. The advice contradicts itself because three different things get argued as though they were one: what a crawler can measure, what the HTML standard requires, and what Google says it does with headings. They do not agree, and knowing where they part is more useful than another rule.

Start with what no tool can tell you

Docket reads your HTML. For this check it reads the text inside your heading elements and nothing else — not the paragraphs beneath them, not what the page is for.

So it cannot tell you the thing that matters most: whether a heading describes the section under it. A page can pass every heading finding Docket has and still be organised under headings that say "Overview", "More", "Details" and "Other". That page has a perfect outline and a useless one, and no crawler will flag it, because a crawler has nothing to compare the words against.

It also does not know what the page is for. A checkout step, a category listing and a long guide want different heading structures, and the check applies the same conditions to all three, exempting pages on word count alone. A clean run here means your heading elements are present and in a plausible order, not that your page is well organised.

What the check computes, from the source

The registered check is onpage.headings, "Heading structure", and that one label covers 4 separate findings with unrelated remedies:

• onpage.h1_missing — MEDIUM — "…pages have no H1 heading"
• onpage.h1_multiple — LOW — "…pages have more than one H1"
• onpage.h2_missing — LOW — "…substantial pages have no subheadings"
• onpage.heading_skip — NOTICE — "…pages skip a heading level"

The conditions that produce them are short enough to read in full:

h1s = page.headings.get("h1", [])
if not h1s:
    no_h1.append(page)
elif len(h1s) > 1:
    multi_h1.append(page)

deeper = any(page.headings.get(f"h{level}") for level in (3, 4, 5, 6))
if (page.word_count >= SUBSTANTIAL_WORDS
        and not page.headings.get("h2") and not deeper):
    no_h2.append(page)

if page.headings.get("h3") and not page.headings.get("h2"):
    skipped.append(page)

They are not weighted equally, and the ordering answers the question at the top of this page better than any advice could. A missing H1 carries the heaviest impact weight of the set by a wide margin; a wall of text with no subheading at any level comes next; more than one H1 comes below that; skipping a level is the lightest thing this check emits. That is your triage order, and not the one the advice on the web gives.

The one-H1 question, kept in three parts

This is where the folklore lives, so it is worth separating who says what.

The check. It flags a page with more than one H1 at LOW severity, and its own detail text concedes the point: "Multiple H1s blur what the page is primarily about. HTML5 permits it, but in practice it usually means the template is using H1 for styling." Its fix is to keep one H1 and demote the rest. Note the reasoning — the finding is not "this breaks something", it is "this is usually a symptom", which is a much weaker claim than the rule it resembles.

The HTML standard. It permits multiple H1s outright. The living standard's section on headings and outlines states that a document can contain multiple top-level headings, and prints a conforming example with three. Its only conformance requirement about level one is that if a document has any headings at all, at least a single heading within the outline should have a heading level of 1. WHATWG HTML, Headings and outlines, read 15 September 2026.

Google's documentation. It sets no number. The SEO starter guide says there is no magical, ideal amount of headings a given page should have, and adds that while semantic order is excellent for screen readers, from Google Search's perspective it does not matter if you use them out of order. Google Search Central, SEO starter guide, read 15 September 2026.

So Docket is stricter than both, and is the only one of the three claiming anything. That gap is not a bug — a template emitting three H1s because the designer wanted three big fonts is worth seeing — but read it for what it is. If your page has two H1s because it has two subjects, the standard is on your side and Google is indifferent.

Where the standard is stricter than Docket

The skipped-level finding runs the other way, and this is the part nobody expects.

Docket's condition is a presence test over the whole document: an h3 exists somewhere and no h2 exists anywhere. That catches the common template defect — h1 straight to h3 because h3 was the right size — and it catches nothing else. An h2 followed by an h4 is not flagged. An h1 followed by an h4 with no h3 on the page is not flagged. A page that jumps h1 to h3 halfway down but carries an h2 elsewhere is not flagged either.

The standard's rule is per-sequence: each heading following another must have a level that is less than, equal to, or one greater than the previous heading's level. Its own non-conforming example is an h1 followed by an h3, exactly the case Docket catches — but the rule covers every other jump too, and Docket's does not. A clean onpage.heading_skip does not mean your outline conforms.

What is the jump worth? Google's answer is above: for Search, not much; for screen readers, a great deal. Docket's finding agrees and says nothing about rankings — "H3s appear with no H2 above them, which breaks the document outline for screen readers and parsers." That is the honest version of a claim usually sold as a ranking factor.

"No subheadings" has to mean no subheadings

The condition used to be "long page, no H2". Run against a publisher's ebook-bundle page — one H1, no H2, five H3s and twenty-eight H4s across roughly thirteen thousand words — it produced two findings from the same loop about the same seven pages: "substantial pages have no subheadings", and "pages skip a heading level". The second was true. The first was not: a reader can count thirty-three subheadings on that page.

The detail text was right and the headline outran it. "Long pages with no H2s are a wall of text" is a claim about H2s and it is fair. Generalised to "no subheadings" it became a different claim and a false one — and a reader who catches a tool being wrong about the page in front of them stops believing the finding that was accurate.

So the condition now requires no heading at any level below H2, with the word floor as its other half: a short page needs no sections and is exempt. The id onpage.h2_missing is a leftover from the version that was wrong.

What Docket counts as a heading

Narrower than you probably assume, and it explains most surprises.

• A heading is its text. The extractor records a heading only if it has text content after whitespace is collapsed. An <h1> holding only a logo image or an inline SVG is not recorded at all, so that page is reported as having no H1 — usually the right answer, and a surprise to anyone who can see a heading on the page.
• Every heading counts, wherever it sits. The extractor walks the whole document, not the main content region, and applies no nav-and-footer filter. An H2 in your footer clears the no-subheadings finding. An H1 wrapping your site logo in the header is that page's H1 on every page of the site — the usual cause of a site-wide "more than one H1".
• Only some pages are asked. The loop runs over the indexable pages whose served HTML carried content. A noindex page is not asked about its H1, nor is a page whose markup is essentially empty because the content arrives by JavaScript — reporting "no H1" there would describe the crawler, not the page.

A title is not a heading

These get conflated constantly and they are separate elements with separate jobs. The <title> lives in the head, never appears on the page, and is what a search result shows. An <h1> lives in the body and is what a visitor reads. The HTML standard notes directly beneath its outline example that the title element is not a heading.

They interact in one documented way. Google's guidance on title links lists heading elements, and H1 elements specifically, among the sources it draws a search result's title from when it does not use your title element, and advises making the main title text the first visible H1 on the page. That is the practical case for one clear H1: not a ranking rule, but control over what the result says. The title element itself is a different job with a different unit of measurement, covered in how to write title tags that fit. Google Search Central, title links, read 15 September 2026.

What to actually do

In the order Docket's own weights put them:

• Give every page an H1 with text in it. Docket's fix text is "Add exactly one H1 per page that names the page's topic in plain language", with the markup <h1>WHAT THIS PAGE IS ABOUT, in plain language</h1>. The "exactly one" is house preference rather than a requirement of the standard; what is not negotiable is that there is one and that it has words in it.
• Break long pages into sections. The fix text asks for descriptive H2s, "ideally phrased as the questions customers ask" — a subheading that states a question is the unit an answer engine can lift.
• Use levels in order. Cheap to do, and the group it genuinely helps is people using a screen reader.
• Then read your headings on their own. Strip the page down to its headings and see whether the list still describes the page. That is the check no tool runs, and the one that changes anything.

The rest of what Docket looks at, check by check, is listed in what Docket checks.

Download Docket

Common questions

Is one H1 per page a real rule?

Not in the HTML standard and not in Google's documentation. The living standard says a document can contain multiple top-level headings and prints a conforming example with three; its only requirement is that at least one heading in the outline is level 1. Docket still flags multiple H1s, at its lightest-but-one weight, because in practice it usually means a template is using H1 for font size.

Does skipping a heading level hurt my rankings?

Google's SEO starter guide says semantic order is excellent for screen readers but that from Google Search's perspective it does not matter if headings are out of order. Docket reports it at NOTICE, its lowest severity, and its finding text talks about screen readers and parsers rather than rankings.

Why does Docket say my page has no H1 when I can see one?

Because it records a heading only if the element has text content. An H1 holding only a logo image or an inline SVG has no text, is not recorded, and the page reads as having none.

Do headings in my footer count?

Yes. The extractor walks the whole document and applies no nav, header or footer filter, so an H2 in your footer clears the no-subheadings finding and a header logo wrapped in an H1 counts as that page's H1 sitewide.

Does Docket check whether my headings are any good?

No, and nor can any tool that reads markup. It can tell you a heading element is present, absent or out of order. It cannot tell you that your subheadings say Overview, More and Other. That judgement is yours and it is worth more than every finding on this page.