fix(website): repair frontmatter handling in docs, then use it for SERP descriptions (#827)

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>

Author: blove

apps/website/content/docs/ag-ui/api/inject-agent.mdx

@@ -1,3 +1,7 @@
+---
+description: injectAgent() returns the AG-UI agent configured by provideAgent() — Angular Signals for chat state, async methods for submit and tool calls.
+---
+
 # injectAgent()
 
 `injectAgent()` retrieves the AG-UI agent from Angular's dependency injection container. Call it in an Angular injection context — typically as a component field initializer. The returned object exposes Angular Signals for reactive UI state and async methods for user actions.

apps/website/content/docs/langgraph/api/inject-agent.mdx

@@ -1,3 +1,7 @@
+---
+description: injectAgent() connects an Angular app to a LangGraph Platform assistant — streaming messages, tool calls, and interrupts as Angular Signals.
+---
+
 # injectAgent()
 
 `injectAgent()` is the LangGraph adapter for Angular. It connects to a LangGraph Platform assistant, consumes the LangGraph SDK event stream, and projects the result into the runtime-neutral `Agent` contract used by `@threadplane/chat`.

apps/website/content/docs/render/concepts/json-render-vs-a2ui.mdx

@@ -1,3 +1,7 @@
+---
+description: json-render renders a fixed spec. A2UI is an agent-to-UI protocol for surfaces that update over time and send user actions back. When to pick each.
+---
+
 # json-render vs A2UI
 
 `@threadplane/render` and `@threadplane/a2ui` both render structured UI, but they solve different problems.

apps/website/src/app/docs/[library]/[section]/[slug]/page.tsx

@@ -109,7 +109,7 @@ export default async function DocsPage({ params }: DocsRouteProps) {
           </div>
           <article className="flex-1 py-8 px-4 sm:px-6 md:px-12 md:max-w-3xl overflow-x-hidden">
             <MdxRenderer
-              source={doc.content}
+              source={doc.body}
               library={library as LibraryId}
               section={section}
               slug={slug}
@@ -141,7 +141,7 @@ export default async function DocsPage({ params }: DocsRouteProps) {
             <DocsPrevNext library={library as LibraryId} section={section} slug={slug} />
           </div>
         </div>
-        <DocsTOC headings={extractHeadings(doc.content)} />
+        <DocsTOC headings={extractHeadings(doc.body)} />
       </div>
     </div>
   );

apps/website/src/app/docs/choosing-an-adapter/page.tsx

@@ -17,6 +17,7 @@ import { CodeGroup } from '../../../components/docs/mdx/CodeGroup';
 import { Pre } from '../../../components/docs/mdx/CodeBlock';
 import { mdxHeadingComponents } from '../../../components/docs/mdx/headings';
 import { createPageMetadata } from '../../../lib/site-metadata';
+import { stripFrontmatter } from '../../../lib/docs';
 
 export const metadata = createPageMetadata({
   title: 'Choosing an adapter — Threadplane',
@@ -59,10 +60,6 @@ function resolveContentFile(): string | null {
   return null;
 }
 
-function stripFrontmatter(source: string): string {
-  return source.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, '');
-}
-
 export default function ChoosingAnAdapterPage() {
   const filePath = resolveContentFile();
   if (!filePath) notFound();

apps/website/src/lib/docs.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { getAllDocSlugs, getDocBySlug, getDocMetadata } from './docs';
+import { getAllDocSlugs, getDocBySlug, getDocMetadata, stripFrontmatter } from './docs';
 import { allDocsPages, docsConfig, findDocsPage, libraryIntroPath, specialDocsPages } from './docs-config';
 import { getCanonicalUrl, getSitemapRoutes } from './site-metadata';
 
@@ -127,6 +127,46 @@ describe('website docs bindings', () => {
     expect(duplicateDescriptions).toHaveLength(0);
   });
 
+  // Both regressions below shipped together and hid each other: the description
+  // regex silently ignored the frontmatter, so the only visible symptom was the
+  // block rendering as Markdown — an <hr> plus a setext <h2> above the real <h1>.
+  it('prefers a frontmatter description when `description` is the last key', () => {
+    // Every real frontmatter block in content/docs/ ends on `description:`.
+    const metadata = getDocMetadata('chat', 'guides', 'custom-catalogs');
+
+    expect(metadata?.description).toBe(
+      'Compose custom component catalogs for generative UI using ViewRegistry composition.',
+    );
+  });
+
+  it('never leaks frontmatter keys into a derived description', () => {
+    for (const { library, section, slug } of getAllDocSlugs()) {
+      const description = getDocMetadata(library, section, slug)?.description ?? '';
+      expect(description, `/docs/${library}/${section}/${slug}`).not.toMatch(/^title:/);
+    }
+  });
+
+  it('exposes a render body with no frontmatter for every doc page', () => {
+    for (const { library, section, slug } of getAllDocSlugs()) {
+      const doc = getDocBySlug(library, section, slug);
+
+      expect(doc?.body.startsWith('---'), `/docs/${library}/${section}/${slug}`).toBe(false);
+    }
+  });
+
+  it('strips a frontmatter block before the body is handed to MDX', () => {
+    const source = '---\ntitle: X\ndescription: D.\n---\n\n# Heading\n\nBody.\n';
+
+    expect(stripFrontmatter(source)).toBe('# Heading\n\nBody.\n');
+  });
+
+  it('leaves a body that merely starts with a thematic break alone', () => {
+    // A leading `---` is only frontmatter when a closing fence follows it.
+    const source = '---\n\n# Heading\n';
+
+    expect(stripFrontmatter(source)).toBe(source);
+  });
+
   it('includes every configured doc page in the sitemap routes', () => {
     const sitemapRoutes = getSitemapRoutes();
 

apps/website/src/lib/docs.ts

@@ -15,13 +15,44 @@ export const DEFAULT_DOCS_DESCRIPTION = 'Threadplane documentation';
 
 export interface ResolvedDoc {
   page: DocsPage;
+  /** Raw file contents, frontmatter included — the description is read from it. */
   content: string;
+  /** `content` with any frontmatter removed. This is what gets rendered. */
+  body: string;
   title: string;
 }
 
 export type ResolvedDocMetadata = Metadata;
 
-const FRONTMATTER_DESCRIPTION_PATTERN = /^---\s*\n[\s\S]*?\ndescription:\s*['"]?(?<description>[^'"\n]+)['"]?\s*\n[\s\S]*?\n---/;
+/**
+ * A leading `---` fence and its closing partner. Matched as a whole block, then
+ * searched for keys — the previous single pattern spliced the two together and
+ * required a key to FOLLOW `description:`, so the last key in a block never
+ * matched. Every real block in content/docs/ ends on `description:`.
+ */
+const FRONTMATTER_BLOCK_PATTERN = /^---\s*\n(?<body>[\s\S]*?)\n---\s*(?:\n|$)/;
+
+const FRONTMATTER_DESCRIPTION_PATTERN = /^description:\s*['"]?(?<description>[^'"\n]+?)['"]?\s*$/m;
+
+/**
+ * Remove a frontmatter block so the rest can be handed to the MDX pipeline.
+ *
+ * `next-mdx-remote` does not strip frontmatter unless asked, and Markdown reads
+ * an unstripped block as an `<hr>` followed by a setext `<h2>` — a junk heading
+ * above the page's real `<h1>`, in its table of contents and heading anchors.
+ *
+ * A body that merely opens with a thematic break is left alone: a leading `---`
+ * is only frontmatter when a closing fence follows it.
+ */
+export function stripFrontmatter(source: string): string {
+  return source.replace(FRONTMATTER_BLOCK_PATTERN, '');
+}
+
+function readFrontmatterDescription(content: string): string | null {
+  const body = content.match(FRONTMATTER_BLOCK_PATTERN)?.groups?.body;
+  if (!body) return null;
+  return body.match(FRONTMATTER_DESCRIPTION_PATTERN)?.groups?.description ?? null;
+}
 
 function normalizeDescription(description: string): string {
   return description
@@ -33,8 +64,7 @@ function normalizeDescription(description: string): string {
 }
 
 function extractFirstParagraph(content: string): string | null {
-  const withoutFrontmatter = content.replace(/^---\s*\n[\s\S]*?\n---\s*/, '');
-  const withoutImports = withoutFrontmatter.replace(/^import\s.+$/gm, '');
+  const withoutImports = stripFrontmatter(content).replace(/^import\s.+$/gm, '');
   const paragraphs = withoutImports.split(/\n{2,}/);
 
   for (const paragraph of paragraphs) {
@@ -56,7 +86,7 @@ function extractFirstParagraph(content: string): string | null {
 }
 
 function getDocDescription(content: string, fallback: string): string {
-  const frontmatterDescription = content.match(FRONTMATTER_DESCRIPTION_PATTERN)?.groups?.description;
+  const frontmatterDescription = readFrontmatterDescription(content);
   if (frontmatterDescription) return normalizeDescription(frontmatterDescription);
   return extractFirstParagraph(content) ?? fallback;
 }
@@ -75,6 +105,7 @@ export function getDocBySlug(library: string, section: string, slug: string): Re
   return {
     page,
     content,
+    body: stripFrontmatter(content),
     title: titleMatch?.[1] ?? page.title,
   };
 }