Missing H1, or heading levels skipped

What Is This Issue

This issue checks whether your page headings (H1, H2, H3, etc.) follow a logical structural order that reflects your content organization.

Heading tags create an outline of your page content. For this check to pass:

Your page should have at least one heading (preferably H1 for the main topic)
Headings should follow a logical order (H1, then H2, then H3, etc.)
You should avoid skipping heading levels (e.g., going from H1 directly to H3)
Multiple H1 tags on a single page should be avoided

Example: A well-structured page might have:

H1: “Complete Guide to SEO”
H2: “What is SEO?”
H2: “SEO Best Practices”
H3: “Keyword Research”
H3: “Link Building”

Why Is This Important

Logical heading hierarchy is important for:

Rankings: Search engines use headings to understand the structure and topics of your page
User experience: Clear headings make content scannable and easier to navigate
AI Search / AEO: AI systems use heading structure to understand content organization for answer generation
Accessibility: Screen readers use headings to help visually impaired users navigate content

When heading structure is missing or illogical, search engines may:

Have difficulty understanding your content hierarchy
Miss important topic relationships
View your page as less organized or authoritative
Provide a poor experience for users with assistive technologies

Resolving this issue improves your SEO health score by ensuring search engines and users can easily understand your content structure.

How XeoPix Detects This

XeoPix identifies heading hierarchy issues through these steps:

Fetches the page: XeoPix requests the URL and checks that the response is HTML content.
Extracts headings: The system parses the raw HTML and extracts all heading tags (H1 through H6) in document order.
Analyzes structure: XeoPix evaluates the heading sequence by:
- Counting how many of each heading level exist
- Checking if at least one heading exists
- Verifying there’s exactly one H1 (when H1s are present)
- Looking for skipped heading levels (e.g., H1 to H3 without H2)
Builds sequence: The system creates a heading sequence string (like h1>h2>h3>h2) to visualize the structure.
Flags issues: XeoPix triggers warnings when:
- No heading tags are found
- Multiple H1 tags exist
- Heading levels skip (e.g., H2 directly to H4)
- Heading structure is missing or illogical

The detection uses only raw HTML—no JavaScript-injected headings are considered.

How To Fix

Audit your headings: Crawl your pages to identify heading structure issues like missing H1, multiple H1s, or skipped heading levels.
Use one H1 per page: Each page should have exactly one H1 tag that describes the main topic.
Follow logical order: Structure headings hierarchically:
- H1 for the main title
- H2 for major sections
- H3 for sub-sections under H2
- H4, H5, H6 for deeper nesting as needed
Avoid skipping levels: Don’t jump from H1 to H3 without an H2 in between.
Use headings for structure, not styling: Don’t use heading tags just to make text look bigger—use them to define content hierarchy.
Make headings descriptive: Write clear, descriptive headings that accurately represent the content that follows.
Test your changes: Recrawl your pages to verify heading structure is now logical and well-organized.

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL.

Database Table / Prisma Model

PageSeoBasicsData

Stored Fields

Field	Type	Description
h1Count	Int?	Number of H1 tags found on the page
headingHierarchyValid	Boolean?	Whether heading hierarchy is valid (no skips)
headingTree	Json?	Full heading structure as JSON tree

Detection Dependencies

The following data sources are required to evaluate this issue:
HTML Document — The crawler extracts all heading tags (H1-H6) and analyzes their hierarchy

Examples

Example 1: Correct heading hierarchy

Scenario: A page with proper heading structure.

Passes because:

Exactly one H1 tag exists
Headings follow logical order (H1 → H2 → H3)
No heading levels are skipped


<h1>Complete Guide to SEO</h1>
<h2>What is SEO?</h2>
<h2>SEO Best Practices</h2>
<h3>Keyword Research</h3>
<h3>Link Building</h3>
<h2>Conclusion</h2>

Example 2: Multiple H1 tags

Scenario: A page with multiple H1 tags.

Fails because:

Multiple H1 tags confuse search engines about the main topic
Heading hierarchy is unclear


<h1>Complete Guide to SEO</h1>
<h2>What is SEO?</h2>
<h1>SEO Best Practices</h1>
<!-- Wrong: Should be H2 -->

Corrected version:


<h1>Complete Guide to SEO</h1>
<h2>What is SEO?</h2>
<h2>SEO Best Practices</h2>

Example 3: Skipped heading levels

Scenario: A page that skips from H1 to H3.

Fails because:

Skipping heading levels creates illogical structure
Content hierarchy is unclear


<h1>Complete Guide to SEO</h1>
<h3>Keyword Research</h3>
<!-- Wrong: Should be H2 -->

Corrected version:


<h1>Complete Guide to SEO</h1>
<h2>Keyword Research</h2>

Unit Test

Test File

__tests__/seo-audit-checks/pageSeoBasics/issue-44-canonical-all.test.js

Purpose

Validates that the SEO audit correctly detects pages that are missing a canonical URL tag.

Tested Function

runPageSeoBasics() from toggleGroups/pageSeoBasics.js

Issue Information

Issue Number: 44
Issue Code: CANONICAL_ALL (canonical_all)
Toggle Group: pageSeoBasics

Test Scenarios

Positive Test Cases

Canonical tag present — Page has a <link rel="canonical"> tag with a valid href. No issue should be reported.

Negative Test Cases

No canonical tag — Page has no <link rel="canonical"> tag. The issue should be reported with message 'No canonical URL was found on this page'.
Canonical with empty href — Page has a <link rel="canonical"> tag but the href is empty. The issue should be reported.
No head section — HTML has no <head> section. The issue should be reported.

Boundary Cases

None.

Edge Cases

Multiple canonical tags — When multiple canonical tags exist, the duplicate elements issue is also triggered alongside the canonical check.
Empty href — A canonical tag with an empty href is treated as missing.
No head section — HTML missing the <head> element still triggers the detection.

Expected Outcome

Pass

The issue is not reported when the page has a <link rel="canonical"> tag with a non-empty href.

Fail

The issue is reported when the page has no canonical tag, an empty canonical href, or no <head> section.

Validation

Verifies correct issue detection when canonical tag is missing
Verifies no issue is reported when canonical tag is present
Verifies the issue details.message is 'No canonical URL was found on this page'
Verifies detection for empty canonical href
Verifies detection for missing head section
Verifies multiple canonical tags trigger the duplicate elements issue

toggleGroups/pageSeoBasics.js
issueCodes.js
utils/issues.js

Coverage Summary

Covers page with canonical tag (pass)
Covers page without canonical tag (fail)
Covers page with empty canonical href (fail)
Covers page with multiple canonical tags (fail — duplicate elements)
Covers page with no head section (fail)
Validates issue message in payload

References

Headings — Google Search Central
Heading elements — MDN
Sections and headings — WHATWG