Repository navigation
fix: untangle docs SEO metadata and add a Phone Search guide - #68
Merged
Merged
Conversation
lhagenWP
force-pushed
the
api-docs-seo-fixes
branch
4 times, most recently
from
October 13, 2026 17:17
5fb2b98 to
f6df78e
Compare
trichardswp
requested changes
Oct 13, 2026
Fumadocs reuses one frontmatter title for four jobs: the sidebar label, the H1, the <title> tag, and the anchor text of every card and Related link pointing at that page. Person Search, Property Search, and Reverse Phone Lookup compete with consumer Whitepages surfaces for the same terms, so every internal link aimed at them read as a bare capability name instead of the developer product. The site also shipped with no canonical tag, an incomplete Open Graph block, a hardcoded Twitter card that drifted from Open Graph and still called the product "comprehensive," a keywords tag carrying a do-not-market term, and heading case split between Title Case and sentence case. Person Search, Property Search, and Reverse Phone Lookup are now API-qualified in frontmatter and in every hardcoded card, so the title change propagates to the H1, sidebar, cards, Related links, and llms.txt from one edit per page. Pages with no competing consumer surface keep their bare titles. Every page now emits a self-referencing canonical link and a complete Open Graph block (title, description, url, type, site_name); Twitter tags are no longer hardcoded and inherit from Open Graph instead. The sitewide keywords tag and "comprehensive" are gone. A check-heading-case script, wired into `just validate`, fails CI on a Title Case H2 or H3 in content/docs/, and every existing heading has been converted to sentence case.
No page on the Pro API docs site emits any structured data, so the entity "Whitepages Pro API" resolves to nothing machine-readable. A model reading these docs has to infer what the product is from prose instead of reading a typed assertion. Every page now renders one JSON-LD block with an Organization and a WebAPI node, both defined once as fixed constants so their @id values stay byte-identical across all pages, plus a page-specific TechArticle node carrying that page's own headline and description. Pages that render a breadcrumb trail also get a matching BreadcrumbList, built from the same page tree data the visible breadcrumb uses so the two can never disagree.
This repo is public, so the README and MDX source reach AI training data independently of the rendered site. The README named the wrong product and said nothing about what the API returns, going straight from a six-word line into install instructions. The README now names "Whitepages Pro API" in its heading and opening line, and carries an About section above Development stating what the API returns, that coverage is U.S.-only and varies by record, and that it is not FCRA-regulated. Getting Started and the structured data's WebAPI description use the same wording, so the three surfaces agree.
The Guides section listed person search, webhooks, events, regions, property search, MCP, agentic guidance, and FAQ in no particular order, so the two core data guides sat apart and operational guides preceded the second data guide. The References rail ordered the same entities differently again, so the two sidebars disagreed with each other. Reorders Guides to person search, property search, MCP, agentic guidance, events, webhooks, regions, FAQ: both data APIs first, then the agent-facing guides, then the operational ones. Reorders the matching References entries (person, property, phone, events, webhooks, regions) to the same relative sequence; account has no Guides counterpart and moves to the end of that run.
GET /v2/phone/{phone} and GET /v2/person/ with phone= answer different
questions but shared one guide, so a reader looking for the number's
own facts and a reader looking to rank people against a number landed
on the same page with no clear entry point of its own in the left
rail.
Adds Phone Search as its own top-level guide covering the dedicated
endpoint: line type, carrier, the businesses it returns that person
search cannot, and the spellings that resolve to one resource. Reverse
Phone Lookup keeps the person-search-by-phone content it already had.
Each guide opens with a callout pointing at the other for the opposite
use case, and the capability map, Getting Started, the changelog entry,
and the phone reference page now point at whichever guide fits the
question being answered.
Every reference page renders an Authorization section through fumadocs-openapi's Operation component. When an endpoint declares exactly one security scheme — true for every endpoint here, since they all use the same API key header — it wraps that scheme's label, built as a <div>, inside a <p> tag. A <div> cannot be a descendant of a <p>, so React logs a hydration error on every reference page. The fix landed upstream in 10.10.3, but that release also bumps the fumadocs-core/fumadocs-ui peer requirement past what this repo pins, breaking the build on an unrelated i18n export. Patches the one-line change directly onto the installed 10.1.1 via `bun patch` instead of taking the wider upgrade.
Person Search's Request Parameters table listed 14 of the 18 parameters GET /v2/person/ actually accepts. email was absent entirely, and radius, page, and page_size were each already documented on their own dedicated guide but never made it into the page that bills itself as the parameter reference. The capability map had the same gap: every other way to find a person had a row, but searching by email did not. Adds the four missing parameters to Person Search's table, linking out to Search by Radius and Pagination for the parameters with more behavior to explain, and adds a "find a person by email" row to the capability map's People table.
lhagenWP
force-pushed
the
api-docs-seo-fixes
branch
from
October 13, 2026 19:36
f6df78e to
329b057
Compare
trichardswp
approved these changes
Oct 13, 2026
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
2 participants
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.
Why
Person Search, Property Search, and Reverse Phone Lookup share their
frontmatter title with every internal anchor pointing at them, so pages
that compete with a consumer Whitepages surface for the same term read
as bare capability names everywhere a link points at them. The site
also shipped with no canonical tag, an incomplete Open Graph block, a
hardcoded Twitter card that drifted from Open Graph, no structured
data at all, and a public README that named the wrong product with no
description of what the API returns. Phone Search and Reverse Phone
Lookup also shared one guide with no entry point of its own in the
left rail, even though they answer different questions. Separately,
Person Search's parameter table had drifted out of sync with the
actual endpoint, missing
emailentirely.What Changed
API-qualified in frontmatter and every hardcoded card, propagating
to the H1, sidebar, cards, Related links, and llms.txt. Every page
emits a self-referencing canonical link and a complete Open Graph
block; Twitter tags inherit from Open Graph instead of drifting. The
sitewide
keywordstag and "comprehensive" are gone. Acheck-heading-casescript, wired intojust validate, fails CI ona Title Case H2 or H3.
TechArticle, and a matching BreadcrumbList where one is visible).
Getting Started and the structured data description use the same
wording.
entities (person, property, phone, events, webhooks, regions) the
same way: data APIs first, then agent-facing guides, then
operational ones.
separate from Reverse Phone Lookup's person-search-by-phone content.
Each guide opens with a callout pointing at the other.
fumadocs-openapithat renders a<div>inside a
<p>on every reference page's Authorization section,causing a hydration error. Upstream fixed it in 10.10.3, but that
release needs a newer fumadocs-core/fumadocs-ui than this repo pins;
bun patchapplies just the fix to the installed 10.1.1.email,radius,page, andpage_sizealongside the parametersthey already documented, matching what
GET /v2/person/actuallyaccepts.
Context
Seven independent commits, one per concern, so each can be reviewed
and reverted on its own: metadata/anchors, structured data, README,
rail order, Phone Search, the fumadocs-openapi patch, and the Person
Search parameter audit.