Missing H1 and skipped heading levels: fixing a page outline

One H1 per page, and no level entering more than one step deeper than the level before it. Going back up is always fine: H3 followed by H2 simply closes a subsection and opens a new section. Going down two at once is the defect, because there is no parent for the deeper level to belong to.

Notice what is not being measured: wording, length, keyword content, or how many headings the page has. A page with four headings and a clean hierarchy passes. A page with forty and one skip does not.

In a page builder, a heading is a styling choice made by someone choosing how text should look. The control says "Heading 3" and it is sitting in a panel next to font size, so it reads as a size. Nobody picking it is thinking about document structure, because nothing in the interface suggests that is what they are picking.

The result is consistent across tools. Webflow and Elementor sections default to H2 or H3 regardless of nesting, so a page assembled from three section templates often has three H2s and no H1. Shopify sections behave the same way, with the theme's H1 frequently spent on the store name in the header rather than the page title. And a WordPress theme that renders the site title as an H1 leaves every post with two.

The tell is a page whose largest visible text is not a heading at all.

This is the actual export for this check, generated by the audit API from a real crawl, with the site replaced by example.com and nothing else edited. It is what you get when you export the failure rather than a description of what such a file might contain.

Note what it does and does not assume. It tells the agent what string to search for rather than naming a file, because the crawler cannot see your repository layout. It states the skip that was actually observed. And it gives a safe default for the wording of the new heading, since that is the one part requiring judgement.

# Fix: Heading Hierarchy Skip

**Site:** https://example.com

**Check:** `seo-heading-hierarchy-broken` · **Severity:** warning · **Category:** SEO · **Affected pages:** 1

## What's wrong
The heading hierarchy on the page https://example.com/ is broken, with a skip from H1 to H3 without an intervening H2. The crawler observed this skip, which is reported as "H1 → H3 (skipped H2)". This defect is detected by the "seo-heading-hierarchy-broken" check. The page's current heading structure does not follow the standard hierarchical order.

## Why it matters
The broken heading hierarchy hurts accessibility and SEO structure, making it difficult for screen readers and search engines to understand the content structure. This can lead to a poor user experience, especially for users relying on assistive technologies. Proper heading hierarchy is essential for conveying the organization and importance of content.

## How to fix
1. Find the code responsible for generating the headings on the page https://example.com/ by searching for the string "H1" and "H3" in the HTML template or rendering code.
2. Insert an H2 heading between the existing H1 and H3 headings to maintain the correct hierarchical order.
3. Ensure the final HTML output includes the corrected heading structure, such as: `<h1>...</h1><h2>...</h2><h3>...</h3>`.
4. If the wording or content of the new H2 heading requires human judgement, use a safe default such as "Introduction" or "Overview" to maintain the hierarchical structure.

## Acceptance criteria
- [ ] The page https://example.com/ has a corrected heading hierarchy with no skipped levels.
- [ ] The HTML source of the page includes an H2 heading between the H1 and H3 headings.
- [ ] The page's heading structure follows the standard order: H1 → H2 → H3.

## Affected pages

| # | URL | Observed value |
| --- | --- | --- |
| 1 | `https://example.com/` | `H1 → H3 (skipped H2)` |

## Ground rules for the agent

- Start by identifying the stack yourself (package manifest, config files, template extensions) and adapt every step below to it. The steps describe the required output, not the framework.
- Treat the URLs and observed values above as facts from a real crawl. Do not invent additional affected pages.
- Prefer fixing the shared template or layout over patching one page, then confirm the change reaches every affected URL listed.
- Change content and templates, not URLs — renaming a route creates redirects and breaks inbound links.
- If a fix needs copy written (titles, descriptions), draft it from the page's existing content rather than inventing claims about the product.
- Make one issue-type change per commit so a regression can be bisected.
- Do not mark an item complete until its acceptance criterion is actually verifiable.

Because the page still gets indexed, still ranks, and still reads correctly to anyone looking at it. The damage is to two audiences who are not looking at it: assistive technology users, for whom a broken outline is a real navigation failure, and machines parsing structure.

The reason it is not merely Refinement is that heading structure is an input to how passages get extracted, which is a growing use of your content rather than a shrinking one. The severity scale is weighing a present accessibility cost against a future extraction cost, and Important is where that lands.

Do not read the markup for this. Use the accessibility tree in your browser's developer tools, which shows the outline as a machine assembles it, or run a headings extension and look at the resulting list. A list that reads as a sensible table of contents is the pass condition; one with gaps in it is the defect, whatever the source says.

Then re-crawl, because the skip case is the half a single page cannot self-report. Also worth checking after any template change: this is a defect that returns the moment someone adds a section component with its own hardcoded level.