fix(docs): derive missing titles from Markdown headings

src/utils/docs-title.ts

@@ -0,0 +1,10 @@
+import { parseSiteMarkdown } from './markdown'
+
+export function getDocsTitle(title: string | undefined, content: string) {
+  return (
+    title ??
+    parseSiteMarkdown(content).headings.find((heading) => heading.level === 1)
+      ?.text ??
+    'Documentation'
+  )
+}

src/utils/docs.functions.ts

@@ -1,3 +1,4 @@
+import { getDocsTitle } from './docs-title'
 import { notFound } from '@tanstack/react-router'
 import { createServerFn, createServerOnlyFn } from '@tanstack/react-start'
 import { setResponseHeader } from '@tanstack/react-start/server'
@@ -450,7 +451,7 @@ export const fetchDocs = createServerFn({ method: 'GET' })
     return {
       content: frontMatter.content,
       isFallback: result.isFallback,
-      title: frontMatter.data?.title ?? 'Content temporarily unavailable',
+      title: getDocsTitle(frontMatter.data?.title, frontMatter.content),
       description,
       keywords,
       frameworks: extractFrameworksFromMarkdown(frontMatter.content),

tests/docs-title.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { getDocsTitle } from '../src/utils/docs-title'
+
+test('docs metadata preserves explicit titles and derives missing titles from actual headings', () => {
+  assert.equal(getDocsTitle('Explicit title', '# Body title'), 'Explicit title')
+  assert.equal(
+    getDocsTitle(
+      undefined,
+      '# How to Set Up Testing with Code-Based Routing\n\nGuide body',
+    ),
+    'How to Set Up Testing with Code-Based Routing',
+  )
+  assert.equal(
+    getDocsTitle(
+      undefined,
+      '```md\n# Code example\n```\n\n# **Real** `guide` [title](/guide)',
+    ),
+    'Real guide title',
+  )
+  assert.equal(
+    getDocsTitle(
+      undefined,
+      '# Content temporarily unavailable\n\nPlease try again.',
+    ),
+    'Content temporarily unavailable',
+  )
+  assert.equal(
+    getDocsTitle(undefined, 'A document without a heading.'),
+    'Documentation',
+  )
+})