From 0b6deeb37b8e514c087d643a821649ade8b08f5f Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Sat, 31 Oct 2026 23:33:57 -0600
Subject: [PATCH] fix(docs): derive missing titles from Markdown headings

---
 src/utils/docs-title.ts     | 10 ++++++++++
 src/utils/docs.functions.ts |  3 ++-
 tests/docs-title.test.ts    | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 src/utils/docs-title.ts
 create mode 100644 tests/docs-title.test.ts

diff --git a/src/utils/docs-title.ts b/src/utils/docs-title.ts
new file mode 100644
index 000000000..4199ec068
--- /dev/null
+++ b/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'
+  )
+}
diff --git a/src/utils/docs.functions.ts b/src/utils/docs.functions.ts
index 25e88633e..5dfc2213a 100644
--- a/src/utils/docs.functions.ts
+++ b/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),
diff --git a/tests/docs-title.test.ts b/tests/docs-title.test.ts
new file mode 100644
index 000000000..154605ebd
--- /dev/null
+++ b/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',
+  )
+})