fix(seo): emit a single H1 on generated API reference pages - #94
Open
coderdan wants to merge 1 commit into
Open
Conversation
TypeDoc's reflection template writes `# <symbol>` as the first line of
each generated page's body, and the docs route renders `page.data.title`
through Fumadocs' `<DocsTitle>` as an <h1> above it. Both resolve to the
same string, so all 23 API reference pages shipped two identical H1s —
every multiple-H1 warning in the site audit, and nothing else.
Set `hidePageTitle: true` so TypeDoc omits its copy. Verified against a
minimal TypeDoc project run with the option both ways: the only
difference in the output is the removal of the `# <name>` line and its
trailing blank. Member headings stay at `##`, so page anchors — and the
two `#createencryptionoperators`/`#encryptedindexes` deep links in the
Drizzle guide — are unaffected.
Worth flagging for the next reader: this is `hidePageTitle`, not the
`hidePageHeader` sitting directly above it. The heading in
`reflection.template.js` is gated on the former; `hidePageHeader`
controls the breadcrumb/navigation block, which is a different thing.
The raw-markdown mirrors improve too. `getLLMText` prepends
`# ${page.data.title}` to the processed body, so those files carried the
same duplicate; they now have one H1 as well.
Claude-Session: https://claude.ai/code/session_01Rvx5yeC4Vy2svyohuVvxWj
|
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.
What
One-line change in the TypeDoc options:
hidePageTitle: false→true.Why
TypeDoc's
reflection.template.jswrites# <symbol>as the first line of each generated page's body:The docs route then renders
page.data.titlethrough Fumadocs'<DocsTitle>as an<h1>above it. Both resolve to the same symbol name, so every generated page shipped two identical H1s.That is all 23 API reference pages, and it accounts for every multiple-H1 finding in the Ahrefs site audit — the counts match exactly.
Verification
Can't run the full generator here (its prebuild step shells out to
bun installagainst the published packages), so I ran TypeDoc against a minimal throwaway project with the same option block, once each way. The complete diff between the two outputs:Only the H1 line and its trailing blank.
##member headings are untouched, so page anchors survive — including the two deep links the Drizzle guide makes into its API reference (#createencryptionoperators,#encryptedindexes).Nothing changes visually: the removed heading and the surviving one carry the same text.
Side effect
getLLMTextprepends# ${page.data.title}to the processed body, so the.mdxmirrors andllms.txtcarried the same duplicate. They now have one H1 too.Note for the next reader
This is
hidePageTitle, not thehidePageHeaderimmediately above it in the same options block. The name suggests otherwise, buthidePageHeadergates the breadcrumb/navigation block — the H1 is gated onhidePageTitle.Not in scope
Page size. Four API reference pages are over Googlebot's 2 MB crawl limit (
eql.v3is 14.6 MB and takes ~19s to transfer). That needs breaking the modules into per-symbol pages, which changes URLs and the sidebar — a separate PR.https://claude.ai/code/session_01Rvx5yeC4Vy2svyohuVvxWj