Skip to content

fix(api-reference): distinguish API pages from docs pages in title/description, add hreflang - #1337

Merged
twosugar merged 1 commit into
longbridge:mainfrom
nic75408:fix/seo-api-title-desc
Nov 19, 2026
Merged

twosugar merged 1 commit into
longbridge:mainfrom
nic75408:fix/seo-api-title-desc

Conversation

@nic75408

Copy link
Copy Markdown
Contributor

Summary

Each API Reference page (/docs/api/<id>) has the same H1, the same meta description and a title that only differs in the suffix from the docs page for the same endpoint (e.g. /docs/market/top-movers). Google Search Console shows that for 5 English pairs only one page of each pair is indexed and the other is "Crawled - currently not indexed". API pages also output no hreflang at all.

Both pages should stay (the docs page covers CLI / SDK usage, the API page the HTTP request and Try it), so this PR only changes the <head> of API pages:

Change File Effect
Title and description carry the HTTP method and path; WebSocket commands use WebSocket cmd N packages/api-reference/src/openapi-markdown.ts (apiPageMeta()) Top Movers · API Reference → Top Movers (POST /v1/quote/market/stock-events) · API Reference; description becomes POST /v1/quote/market/stock-events — Get stocks whose…. Same 160-char truncation as before, the prefix is always kept.
API page URLs added to the published URL set src/lib/published-urls.ts, new src/lib/api-page-urls.ts BaseLayout already emits hreflang via buildSeoLinks(), but only for URLs in getPublishedUrls(), which listed the docs collection only. API pages (161 × 3 locales) now get en / zh-Hans / zh-Hant / x-default, the same output as docs pages. No layout change.
Tests packages/api-reference/src/api-page-meta.test.ts, src/lib/api-page-urls.test.ts label in every title/description, ≤160 chars, no duplicates among API pages per locale; three-locale hreflang for an API page.

Not in this PR (optional, your call): the H1 (ep-title in ApiReference.tsx) is still the bare summary, e.g. Top Movers, same as the docs page H1. Adding the method/path there would change what users see on the page, so I left it out.

Verification (before merge)

  • Duplicate check with apiPageMeta (same method as fix(api-reference): de-duplicate API page titles and descriptions #1335), 483 API pages vs 866 docs pages, same locale:

    before after
    duplicate titles among API pages 0 0
    duplicate descriptions among API pages 0 0
    API page title (without suffix) = docs page title 347 0
    API page description = docs page description 317 0
  • astro dev, <head> of the 6 pairs below: all 200, title and description differ within each pair, canonical self-referencing, each API page has 4 hreflang links pointing to its own en / zh-CN / zh-HK URLs + x-default (also checked /zh-CN/docs/api/top_movers).

  • vitest run: 72/72 passed (8 files). bun test in packages/api-reference: 20/20.

  • oxlint on the changed files: clean. tsc --noEmit: no errors in the changed files (the remaining errors are the existing astro:content implicit-any ones, same as main). prettier -c reports only the existing long lines in openapi-markdown.ts.

  • No build was run, per CLAUDE.md.

First-screen impact

Only <head> text changes: longer title/description and 4 more <link rel="alternate"> tags on API pages (about 0.35 KB of HTML). No new requests, no script or data changes; docs pages are unchanged.

Post-deploy check

Request each pair and compare <title>, meta description, hreflang:

Docs page API page
/docs/account/dca/update-dca /docs/api/dca_update
/docs/account/dca/calc-date /docs/api/dca_calc_date
/docs/market/top-movers /docs/api/top_movers
/docs/content/topics/topic-detail /docs/api/topic_detail
/docs/quote/pull/intraday /docs/api/ws-intraday
/zh-HK/docs/market/top-movers /zh-HK/docs/api/top_movers

Expected: title and description differ within each pair; API page title contains (METHOD /path) or (WebSocket cmd N); API page has hreflang en, zh-Hans, zh-Hant, x-default pointing to /docs/api/<id>, /zh-CN/docs/api/<id>, /zh-HK/docs/api/<id>.

Sample: curl -s https://open.longbridge.com/docs/api/top_movers | grep -o '<title>[^<]*' → <title>Top Movers (POST /v1/quote/market/stock-events) · API Reference.

🤖 Generated with Claude Code

…scription, add hreflang

API Reference pages (/docs/api/<id>) shared the title and meta description
with the docs page for the same endpoint (e.g. /docs/market/top-movers),
so search engines kept only one of each pair. Also, API pages had no
hreflang because getPublishedUrls() only listed the docs collection.

- apiPageMeta(): title and description carry the HTTP method and path
  (WebSocket commands: "WebSocket cmd N"); description truncation stays
  at 160 chars with the prefix kept.
- getPublishedUrls(): include the API page URLs of all three locales, so
  BaseLayout emits en / zh-Hans / zh-Hant / x-default for them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@twosugar
twosugar merged commit 9db4939 into longbridge:main Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants