Missing or multiple H1: what squirrel expects on a page

What the H1 is for

The H1 names what the page is about. A screen reader user jumping through headings meets it in document order, usually at the top of the content, and a search engine reads it alongside the title element as the page’s own statement of its subject.

One per page is the working convention. HTML5’s outline algorithm was meant to make multiple H1s meaningful inside sections, but no browser implemented it and assistive technology does not use it, so several H1s just means several competing claims about the page’s subject. The H1 should say the same thing as the title element, usually with more room.

What squirrel checks

The rule runs on every crawled page against the parsed heading data. It emits one check named h1:

• Failing with the message No H1 tag found, the value 0 and the expectation 1.
• Warning with the message Multiple H1 tags found (N), the count as the value and the expectation 1.
• Warning with the message H1 tag is empty and an empty value when there is exactly one H1 with no text.
• Passing with the message Single H1 tag present and the heading text as the value.

The four outcomes are exclusive and the rule stops at the first that applies, so a page with two H1s is reported for the count and never checked for emptiness. Severity is error and weight is 7, behind only the title and description checks in this category.

Pages kept out of the search index are skipped. A page whose <meta name="robots"> tag or X-Robots-Tag header contains noindex (a header scoped to one crawler, such as googlebot: noindex, counts too) gets one skipped check named core/h1 with the message Skipped: page is set to noindex via robots meta tag (or via X-Robots-Tag header) instead, because the page never appears in search results. Skipped checks do not count toward the score. Pages are skipped only on a site that is itself being indexed, judged by its homepage, or by the page the audit started from when the homepage was not fetched. When that page is noindex, as on a staging site or a preview deployment (Vercel, Netlify and Cloudflare Pages previews send X-Robots-Tag: noindex by default), nothing is skipped: the whole host is out of search and the audit is most likely checking it before launch. When neither page was fetched, nothing is skipped either. See pages kept out of search for the full list of rules that do this.

How to fix it

<main>
  <h1>Configuring the build cache</h1>
</main>

One per page, at the top of the main content, saying what the page is about. Where a design has a logo in an H1 in the header, that H1 belongs to the site rather than the page: make it a link with an image and give the page its own H1.

The common false positive is a heading rendered by JavaScript. squirrel reads the HTML the server sent unless browser rendering is on, so a client-rendered H1 is not there to find.

Enable / disable

Disable this rule

[rules]
disable = ["core/h1"]

Disable all Core SEO rules

[rules]
disable = ["core/*"]

Enable only this rule

[rules]
enable = ["core/h1"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• content/heading-hierarchy: whether the headings below the H1 descend in order.
• a11y/empty-heading: headings at any level with no text.
• core/meta-title: the title element the H1 should agree with.
• a11y/heading-order: heading levels that skip, such as an H1 followed by an H3.

Core SEO findings ship in every audit next to the performance, security and agent experience rules. See Fix SEO issues with AI for how an agent works through a report.

References

• The h1 to h6 elements, HTML Standard
• Heading elements, MDN

Check your site

Run squirrel audit https://example.com and open the Core SEO section of the report. Every page without exactly one non-empty H1 is listed. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.