Fix Multiple H1 tags across docs pages (SEO)#73
Open
shivthakker wants to merge 1 commit into
Open
Conversation
Ahrefs flagged 318 pages with multiple <h1> tags — almost all docs pages. Root cause: every docs leaf page rendered the frontmatter title via <DocsTitle> (an <h1>) AND repeated it as a leading `# Heading` in the MDX body (a second <h1>). Section overview pages did the inverse — they skipped <DocsTitle> and relied on the body `# Heading` as their only h1. Fix (deterministic — exactly one <h1> per page): - Strip the duplicate leading `# Heading` from 346 hand-written docs MDX bodies. The auto-generated API docs were already clean (no change). - Render <DocsTitle>/<DocsDescription> unconditionally in all 9 docs section templates (removed the isOverviewPage guard), so overview pages keep an <h1> now that the body heading is gone. Verified on a fresh dev server: /docs landing, section overviews, and leaf pages across platform, fleet-ops, storefront, cli, ledger, and ui all render exactly one <h1> containing the page title. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ahrefs flagged 318 pages with multiple
<h1>tags — the single largest issue in the audit, and almost entirely the docs. Multiple H1s dilute the primary heading signal for search engines. This PR makes every docs page render exactly one<h1>(the page title).Root cause
Docs pages had two competing H1 patterns:
<DocsTitle>(an<h1>) and repeated it as a leading# Headingin the MDX body → 2 H1s.isOverviewPageguard skipped<DocsTitle>, so they relied on the body# Headingas their only h1.Fix (deterministic — one
<h1>per page)# Headingfrom 346 hand-written docs MDX bodies. The auto-generated API docs (content/docs/api/*) were already clean (they use<ResourceHeader>/##), so they're untouched and the generator needs no change.<DocsTitle>/<DocsDescription>unconditionally in all 9 docs section templates (removed theisOverviewPageguard) — so overview pages keep an<h1>now that the body heading is gone, and every page is consistent.Net: 346 MDX + 9
page.tsx, −747 lines (mostly removed duplicate headings).Verification
Confirmed on a fresh dev server that the
/docslanding, section overviews, and leaf pages acrossplatform,fleet-ops,storefront,cli,ledger, anduiall render exactly one<h1>containing the page title (e.g.<h1>Fleet-Ops</h1>,<h1>Orders Overview</h1>).Note for reviewers
DocsTitlecomponent (with the frontmatterdescriptionas a subtitle) instead of an inline#heading — a small, consistent visual change that aligns them with every other docs page.next buildwasn't run locally because the blog needs Ghost API keys; the docs changes were verified via live render. The Vercel preview will exercise the full build.🤖 Generated with Claude Code