Overview
Source: ./src/documentation/development/seo/headline-structure.mdx
SEO guideline: headline structure on websites
Last updated: August 5, 2026
Why this matters
Search engines (Google, Bing) use heading tags (<h1> to <h6>) to understand page structure, content hierarchy, and topical relevance.
Incorrect heading usage can hurt rankings, accessibility, and crawlability, even if the page looks fine visually.
1. The golden rule: one <h1> per page
- Exactly one
<h1>per page. This is the main topic and title of the content. - Include the primary keyword for the page in the
<h1>, phrased naturally. - Never use
<h1>for logos, navigation, or decorative text. - Never skip
<h1>in favor of a styled<div>or<span>element. Search engines and screen readers rely on the actual tag.
<!-- ✅ Correct -->
<h1>Running Shoes for Marathon Training</h1>
<!-- ❌ Wrong -->
<h1>Welcome</h1>
<div class="page-title">Running Shoes for Marathon Training</div>
2. Hierarchical order: no skipping levels
Headings must follow a logical, nested structure, like an outline in a document. Think of it as a table of contents.
Example:
<h1>SEO Guide for Developers</h1>
<h2>Headline Structure</h2>
<h3>Why h1 matters</h3>
<h3>Common mistakes</h3>
<h2>Meta Tags</h2>
Rules:
- Don’t skip levels (e.g., h1 → h3 without an h2).
- It’s fine to have multiple h2, h3, and so on elements. Keep the nesting logical.
3. Content, not just styling
- Headings must describe the content that follows. Do not use headings only because the text looks larger.
- Don’t choose heading level based on font size. Don’t use heading tags for text styling.
<!-- ❌ Wrong: h3 misused for styling only -->
<h3>Free Shipping!</h3>
<!-- ✅ Correct -->
<p class="badge">Free Shipping!</p>
4. Accessibility = SEO bonus
Correct heading structure also improves accessibility, since screen readers navigate by headings. This indirectly supports SEO through better UX signals. See the accessibility documentation for general guidelines on making your content accessible.
5. Developer checklist
- Exactly one
<h1>per page, which includes primary keyword naturally - Headings follow strict hierarchy (no skipped levels)
- Headings describe search-relevant content that matches the site’s main content
- No heading tags used purely for a font size or bold formatting effect
- Headings are present in server-rendered HTML (not JS-injected)
Tip Use a browser extension like "Web Developer" to visualize your page’s heading outline before merging a feature.
See also: SEO optimization techniques for guidance on internal linking and link masking and switching.