Serve markdown to LLMs via Accept header

Add content negotiation to doc routes to serve markdown when
Accept: text/markdown or Accept: text/plain is requested.

This allows AI coding agents and LLMs to fetch cleaner markdown
content instead of HTML, reducing token usage by ~10x.

- Add prefersMarkdown() helper to check Accept header
- Add ServerRoute handler to both doc routes
- Include Vary: Accept header for proper caching

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: KyleAMathews

src/routes/$libraryId/$version.docs.$.tsx

@@ -5,6 +5,60 @@ import { findLibrary, getBranch, getLibrary } from '~/libraries'
 import { DocContainer } from '~/components/DocContainer'
 import { notFound } from '@tanstack/react-router'
 
+// Helper function to check if the Accept header prefers markdown
+function prefersMarkdown(acceptHeader: string | null): boolean {
+  if (!acceptHeader) return false
+
+  const accepts = acceptHeader.split(',').map(type => {
+    const [mediaType, ...params] = type.trim().split(';')
+    const quality = params.find(p => p.trim().startsWith('q='))
+    const q = quality ? parseFloat(quality.split('=')[1]) : 1.0
+    return { mediaType: mediaType.toLowerCase(), q }
+  })
+
+  const markdownQ = accepts.find(a =>
+    a.mediaType === 'text/markdown' || a.mediaType === 'text/plain'
+  )?.q || 0
+
+  const htmlQ = accepts.find(a =>
+    a.mediaType === 'text/html' || a.mediaType === '*/*'
+  )?.q || 0
+
+  return markdownQ > 0 && markdownQ > htmlQ
+}
+
+export const ServerRoute = createServerFileRoute().methods({
+  GET: async ({ request, params }) => {
+    const acceptHeader = request.headers.get('Accept')
+
+    if (prefersMarkdown(acceptHeader)) {
+      const url = new URL(request.url)
+      const { libraryId, version, _splat: docsPath } = params
+      const library = getLibrary(libraryId)
+      const root = library.docsRoot || 'docs'
+
+      const doc = await loadDocs({
+        repo: library.repo,
+        branch: getBranch(library, version),
+        docsPath: `${root}/${docsPath}`,
+        currentPath: url.pathname,
+        redirectPath: `/${library.id}/${version}/docs/overview`,
+      })
+
+      const markdownContent = `# ${doc.title}\n${doc.content}`
+
+      return new Response(markdownContent, {
+        headers: {
+          'Content-Type': 'text/markdown; charset=utf-8',
+          'Cache-Control': 'public, max-age=0, must-revalidate',
+          'Cdn-Cache-Control': 'max-age=300, stale-while-revalidate=300, durable',
+          'Vary': 'Accept',
+        },
+      })
+    }
+  },
+})
+
 export const Route = createFileRoute({
   staleTime: 1000 * 60 * 5,
   loader: (ctx) => {
@@ -43,6 +97,7 @@ export const Route = createFileRoute({
     return {
       'cache-control': 'public, max-age=0, must-revalidate',
       'cdn-cache-control': 'max-age=300, stale-while-revalidate=300, durable',
+      'vary': 'Accept',
     }
   },
 })

src/routes/$libraryId/$version.docs.framework.$framework.$.tsx

@@ -5,6 +5,60 @@ import { getBranch, getLibrary } from '~/libraries'
 import { capitalize } from '~/utils/utils'
 import { DocContainer } from '~/components/DocContainer'
 
+// Helper function to check if the Accept header prefers markdown
+function prefersMarkdown(acceptHeader: string | null): boolean {
+  if (!acceptHeader) return false
+
+  const accepts = acceptHeader.split(',').map(type => {
+    const [mediaType, ...params] = type.trim().split(';')
+    const quality = params.find(p => p.trim().startsWith('q='))
+    const q = quality ? parseFloat(quality.split('=')[1]) : 1.0
+    return { mediaType: mediaType.toLowerCase(), q }
+  })
+
+  const markdownQ = accepts.find(a =>
+    a.mediaType === 'text/markdown' || a.mediaType === 'text/plain'
+  )?.q || 0
+
+  const htmlQ = accepts.find(a =>
+    a.mediaType === 'text/html' || a.mediaType === '*/*'
+  )?.q || 0
+
+  return markdownQ > 0 && markdownQ > htmlQ
+}
+
+export const ServerRoute = createServerFileRoute().methods({
+  GET: async ({ request, params }) => {
+    const acceptHeader = request.headers.get('Accept')
+
+    if (prefersMarkdown(acceptHeader)) {
+      const url = new URL(request.url)
+      const { libraryId, version, framework, _splat: docsPath } = params
+      const library = getLibrary(libraryId)
+      const root = library.docsRoot || 'docs'
+
+      const doc = await loadDocs({
+        repo: library.repo,
+        branch: getBranch(library, version),
+        docsPath: `${root}/framework/${framework}/${docsPath}`,
+        currentPath: url.pathname,
+        redirectPath: `/${library.id}/${version}/docs/overview`,
+      })
+
+      const markdownContent = `# ${doc.title}\n${doc.content}`
+
+      return new Response(markdownContent, {
+        headers: {
+          'Content-Type': 'text/markdown; charset=utf-8',
+          'Cache-Control': 'public, max-age=0, must-revalidate',
+          'Cdn-Cache-Control': 'max-age=300, stale-while-revalidate=300, durable',
+          'Vary': 'Accept',
+        },
+      })
+    }
+  },
+})
+
 export const Route = createFileRoute({
   staleTime: 1000 * 60 * 5,
   loader: (ctx) => {
@@ -36,6 +90,13 @@ export const Route = createFileRoute({
       }),
     }
   },
+  headers: (ctx) => {
+    return {
+      'cache-control': 'public, max-age=0, must-revalidate',
+      'cdn-cache-control': 'max-age=300, stale-while-revalidate=300, durable',
+      'vary': 'Accept',
+    }
+  },
 })
 
 function Docs() {