fix(website): repair docs frontmatter handling, then use it for SERP descriptions - #827
Merged
Merged
Conversation
…RP descriptions Two regressions that hid each other. `FRONTMATTER_DESCRIPTION_PATTERN` spliced the opening and closing fences into one match and required a key to *follow* `description:`, so the last key in a block never matched — and `description:` is the last key in every frontmatter block in content/docs/. Every such page silently fell back to its first paragraph. Because the description was ignored, the only visible symptom was the second bug: the docs route handed raw file contents to `next-mdx-remote`, which does not strip frontmatter unless asked. Markdown then read the block as an `<hr>` followed by a setext `<h2>`, putting a junk "title: … description: …" heading above the real `<h1>` on /docs/chat/guides/custom-catalogs and /docs/render/api/views — in the page, its table of contents, and its heading anchor labels. Live in production since the frontmatter was added. Match the block first and search it for keys; strip it via a shared `stripFrontmatter` (the one route that was already correct, /docs/choosing-an-adapter, had its own private copy — now deleted). `ResolvedDoc` gains an explicit `body`: the description is read from `content`, so stripping in place would have traded one bug for the other. With frontmatter working, set descriptions on the three pages the Search Console data singles out. Derived descriptions truncate at 180 chars and Google cuts at ~155, so /docs/langgraph/api/inject-agent — 101 impressions at position 5.6, the site's top striking-distance page — was serving a snippet that ended mid-word. All three replacements are under 155 and answer the query rather than restating the title. `resolveDocDescription` is shared with the JSON-LD, so the meta tag and the structured data stay in sync. Not touched: `ag ui angular` and `json-render vs a2ui` reads at n=8..25, where hyphen/space twins of one query swing 0%->25% at the same position. That is binomial noise, not a CTR signal. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
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.
Follow-up to #826. Started as "apply three meta descriptions"; checking whether the mechanism worked first turned up two live bugs that would have silently swallowed the change.
Two regressions that hid each other
The frontmatter description was never read.
FRONTMATTER_DESCRIPTION_PATTERNspliced both fences into a single match and required a key to followdescription:.description:is the last key in every frontmatter block incontent/docs/, so it never matched and every such page fell back to its first paragraph.The frontmatter rendered as Markdown. Because the description was ignored, the only visible symptom was this: the docs route passed raw file contents to
next-mdx-remote, which doesn't strip frontmatter unless asked. Markdown read the block as an<hr>plus a setext<h2>:A junk heading above the real
<h1>, in the page, its TOC, and its heading-anchoraria-label. Live in production on/docs/chat/guides/custom-catalogsand/docs/render/api/views./docs/choosing-an-adapterwas the one unaffected page — it carried its own privatestripFrontmatter. That copy is now deleted in favour of the shared one.The fix
Match the block, then search it for keys. Strip it through a shared
stripFrontmatter.ResolvedDocgains an explicitbody— the description is read fromcontent, so stripping in place would have traded one bug for the other.Then the actual CTR work
Derived descriptions truncate at 180 chars; Google cuts at ~155.
/docs/langgraph/api/inject-agent— 101 impressions at position 5.6, the top striking-distance page in the first GSC pull — was serving a snippet ending mid-word:Three descriptions set, all under 155, each answering the query instead of restating the title.
resolveDocDescriptionis shared with the JSON-LD, so the meta tag and structured data stay in sync automatically.Deliberately not touched:
ag ui angularandjson-render vs a2ui. At n=8..25, hyphen/space twins of the same query swing 0% → 25% at identical position — binomial noise, not a CTR signal.Verification
npx vitest run --config vite.config.mtsfromapps/website: 312 passed, 5 failedthanks/page.spec.tsx,PostCard.spec.tsx,Differentiator.spec.tsx— none touched by this diff. 307 passed before; the 5 added tests account for the delta.nx lint website: 0 errors, 29 warnings (unchanged)nx build website --configuration=production: succeedsdist/confirms all four affected pages carry the intended<meta name="description">and zero<h2 id="title-…">🤖 Generated with Claude Code