feat(docs): honor description and keywords frontmatter in docs <head>

AlemTuzlak · AlemTuzlak · commit fc2ec405f72d · 2026-04-17T11:44:30.000+02:00
The docs renderer previously auto-generated a &lt;meta name="description"&gt;
from the first paragraph of every doc and ignored any description in
frontmatter. It also did not emit a &lt;meta name="keywords"&gt; tag at all.

- extractFrontMatter now preserves the user-supplied description when
  present (exposed as userDescription) and falls back to the existing
  auto-generated excerpt otherwise.
- fetchDocs / fetchDocsPage prefer the user description and expose a
  normalized keywords field (arrays of strings are joined with ", ";
  empty values are dropped).
- The two docs catch-all routes (\$libraryId/\$version/docs/\$ and the
  framework variant) pass keywords through to seo().

Individual library docs repos can now author SEO copy in frontmatter:

  ---
  title: ...
  description: "..."
  keywords:
    - ...
  ---

Pages that omit these fields keep today's behavior unchanged.
diff --git a/src/routes/$libraryId/$version.docs.$.tsx b/src/routes/$libraryId/$version.docs.$.tsx
@@ -72,6 +72,7 @@ export const Route = createFileRoute('/$libraryId/$version/docs/$')({
       meta: seo({
         title: `${loaderData?.title} | ${library.name} Docs`,
         description: loaderData?.description,
+        keywords: loaderData?.keywords,
         noindex: library.visible === false,
       }),
     }
diff --git a/src/routes/$libraryId/$version.docs.framework.$framework.$.tsx b/src/routes/$libraryId/$version.docs.framework.$framework.$.tsx
@@ -75,6 +75,7 @@ export const Route = createFileRoute(
           ? `${ctx.loaderData.title} | ${tail}`
           : tail,
         description: ctx.loaderData?.description,
+        keywords: ctx.loaderData?.keywords,
         noindex: library.visible === false,
       }),
     }
diff --git a/src/utils/docs.functions.ts b/src/utils/docs.functions.ts
@@ -227,7 +227,9 @@ export const fetchDocs = createServerFn({ method: 'GET' })
     }
 
     const frontMatter = extractFrontMatter(file)
-    const description = removeMarkdown(frontMatter.excerpt ?? '')
+    const description =
+      frontMatter.userDescription ?? removeMarkdown(frontMatter.excerpt ?? '')
+    const keywords = extractFrontMatterKeywords(frontMatter.data.keywords)
     const { contentRsc, headings } = await renderMarkdownToRsc(
       frontMatter.content,
     )
@@ -239,6 +241,7 @@ export const fetchDocs = createServerFn({ method: 'GET' })
       contentRsc,
       title: frontMatter.data?.title ?? 'Content temporarily unavailable',
       description,
+      keywords,
       filePath,
       headings,
       frontmatter: frontMatter.data,
@@ -253,13 +256,32 @@ export const fetchDocsPage = createServerFn({ method: 'GET' })
     return {
       contentRsc: doc.contentRsc,
       description: doc.description,
+      keywords: doc.keywords,
       filePath: doc.filePath,
       frontmatter: doc.frontmatter,
       headings: doc.headings,
       title: doc.title,
     }
   })
 
+function extractFrontMatterKeywords(value: unknown): string | undefined {
+  if (Array.isArray(value)) {
+    const normalized = value
+      .filter((item): item is string => typeof item === 'string')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0)
+
+    return normalized.length > 0 ? normalized.join(', ') : undefined
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    return trimmed.length > 0 ? trimmed : undefined
+  }
+
+  return undefined
+}
+
 export const fetchFile = createServerFn({ method: 'GET' })
   .inputValidator(repoFileInput)
   .handler(async ({ data }: { data: RepoFileRequest }) => {
diff --git a/src/utils/documents.server.ts b/src/utils/documents.server.ts
@@ -421,19 +421,25 @@ export function extractFrontMatter(content: string) {
     excerpt: (file: any) => (file.excerpt = createRichExcerpt(file.content)),
   })
   const redirectFrom = normalizeRedirectFrom(result.data.redirect_from)
+  const userDescription =
+    typeof result.data.description === 'string' &&
+    result.data.description.trim().length > 0
+      ? result.data.description
+      : undefined
 
   return {
     ...result,
     data: {
       ...result.data,
-      description: createExcerpt(result.content),
+      description: userDescription ?? createExcerpt(result.content),
       redirect_from: redirectFrom,
       redirectFrom,
     } as { [key: string]: any } & {
       description: string
       redirect_from?: Array<string>
       redirectFrom?: Array<string>
     },
+    userDescription,
   }
 }
 

Original file line number	Diff line number	Diff line change
`@@ -72,6 +72,7 @@ export const Route = createFileRoute('/$libraryId/$version/docs/$')({`
`72`	`72`	`meta: seo({`
`73`	`73`	title: `${loaderData?.title} \| ${library.name} Docs`,
`74`	`74`	`description: loaderData?.description,`
	`75`	`+ keywords: loaderData?.keywords,`
`75`	`76`	`noindex: library.visible === false,`
`76`	`77`	`}),`
`77`	`78`	`}`
Original file line number	Diff line number	Diff line change
`@@ -75,6 +75,7 @@ export const Route = createFileRoute(`
`75`	`75`	? `${ctx.loaderData.title} \| ${tail}`
`76`	`76`	`: tail,`
`77`	`77`	`description: ctx.loaderData?.description,`
	`78`	`+ keywords: ctx.loaderData?.keywords,`
`78`	`79`	`noindex: library.visible === false,`
`79`	`80`	`}),`
`80`	`81`	`}`