feat: migrate markdown rendering to RSC with rehype-react

- Use rehype-react to render markdown directly to JSX on server
- Stream RSC content to client via renderServerComponent()
- Remove markdown processor from client bundle
- Fix code block visibility (CSS was hiding dual-theme Shiki blocks)
- Fix hydration errors (nested button in DropdownTrigger)
- Add 'use client' directives to interactive components
- Move MarkdownHeading type to separate types.ts file
- Simplify MarkdownContent to only accept RSC content

Author: tannerlinsley

package.json

@@ -45,23 +45,25 @@
     "@sentry/node": "^10.33.0",
     "@sentry/tanstackstart-react": "^10.32.1",
     "@sentry/vite-plugin": "^4.6.1",
+    "@shikijs/rehype": "^3.22.0",
     "@stackblitz/sdk": "^1.11.0",
     "@tailwindcss/typography": "^0.5.13",
     "@tailwindcss/vite": "^4.1.11",
     "@tanstack/create": "^0.49.1",
     "@tanstack/pacer": "^0.16.4",
     "@tanstack/react-pacer": "^0.17.4",
     "@tanstack/react-query": "^5.90.12",
-    "@tanstack/react-router": "1.157.16",
-    "@tanstack/react-router-devtools": "1.157.16",
-    "@tanstack/react-router-ssr-query": "1.157.16",
-    "@tanstack/react-start": "1.157.16",
+    "@tanstack/react-router": "file:../start-rsc/packages/react-router",
+    "@tanstack/react-router-devtools": "file:../start-rsc/packages/react-router-devtools",
+    "@tanstack/react-router-ssr-query": "file:../start-rsc/packages/react-router-ssr-query",
+    "@tanstack/react-start": "file:../start-rsc/packages/react-start",
     "@tanstack/react-table": "^8.21.3",
     "@types/d3": "^7.4.3",
     "@uploadthing/react": "^7.3.3",
     "@visx/hierarchy": "^2.10.0",
     "@visx/responsive": "^2.10.0",
     "@vitejs/plugin-react": "^4.3.3",
+    "@vitejs/plugin-rsc": "^0.5.15",
     "@webcontainer/api": "^1.6.1",
     "@xstate/react": "^6.0.0",
     "algoliasearch": "^5.23.4",
@@ -74,6 +76,7 @@
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "gray-matter": "^4.0.3",
     "hast-util-is-element": "^3.0.0",
+    "hast-util-to-html": "^9.0.5",
     "hast-util-to-string": "^3.0.1",
     "hono": "^4.11.3",
     "html-react-parser": "^5.1.10",
@@ -93,14 +96,15 @@
     "rehype-callouts": "^2.1.2",
     "rehype-parse": "^9.0.1",
     "rehype-raw": "^7.0.0",
+    "rehype-react": "^8.0.0",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "remove-markdown": "^0.5.0",
     "resend": "^6.6.0",
-    "shiki": "^1.4.0",
+    "shiki": "^3.22.0",
     "tailwind-merge": "^1.14.0",
     "three": "^0.182.0",
     "troika-three-text": "^0.52.4",
@@ -119,7 +123,7 @@
     "@content-collections/vite": "^0.2.4",
     "@eslint/js": "^9.39.1",
     "@playwright/test": "^1.57.0",
-    "@shikijs/transformers": "^1.10.3",
+    "@shikijs/transformers": "^3.22.0",
     "@types/express": "^5.0.3",
     "@types/hast": "^3.0.4",
     "@types/node": "^24.3.0",
@@ -158,7 +162,28 @@
       "jws": ">=3.2.3",
       "qs": ">=6.14.1",
       "js-yaml": "^3.14.2",
-      "brace-expansion": ">=1.1.12"
+      "brace-expansion": ">=1.1.12",
+      "@tanstack/history": "file:../start-rsc/packages/history",
+      "@tanstack/router-core": "file:../start-rsc/packages/router-core",
+      "@tanstack/react-router": "file:../start-rsc/packages/react-router",
+      "@tanstack/react-router-devtools": "file:../start-rsc/packages/react-router-devtools",
+      "@tanstack/router-devtools-core": "file:../start-rsc/packages/router-devtools-core",
+      "@tanstack/router-ssr-query-core": "file:../start-rsc/packages/router-ssr-query-core",
+      "@tanstack/react-router-ssr-query": "file:../start-rsc/packages/react-router-ssr-query",
+      "@tanstack/react-start": "file:../start-rsc/packages/react-start",
+      "@tanstack/react-start-client": "file:../start-rsc/packages/react-start-client",
+      "@tanstack/react-start-server": "file:../start-rsc/packages/react-start-server",
+      "@tanstack/react-start-rsc": "file:../start-rsc/packages/react-start-rsc",
+      "@tanstack/start-plugin-core": "file:../start-rsc/packages/start-plugin-core",
+      "@tanstack/start-client-core": "file:../start-rsc/packages/start-client-core",
+      "@tanstack/start-server-core": "file:../start-rsc/packages/start-server-core",
+      "@tanstack/start-storage-context": "file:../start-rsc/packages/start-storage-context",
+      "@tanstack/start-fn-stubs": "file:../start-rsc/packages/start-fn-stubs",
+      "@tanstack/router-utils": "file:../start-rsc/packages/router-utils",
+      "@tanstack/router-generator": "file:../start-rsc/packages/router-generator",
+      "@tanstack/router-plugin": "file:../start-rsc/packages/router-plugin",
+      "@tanstack/virtual-file-routes": "file:../start-rsc/packages/virtual-file-routes",
+      "@tanstack/valibot-adapter": "file:../start-rsc/packages/valibot-adapter"
     }
   }
 }

pnpm-lock.yaml

@@ -1,7 +1,7 @@
 import { Link } from '@tanstack/react-router'
 import { ChevronDown } from 'lucide-react'
 import { twMerge } from 'tailwind-merge'
-import type { MarkdownHeading } from '~/utils/markdown/processor'
+import type { MarkdownHeading } from '~/utils/markdown/types'
 import {
   Dropdown,
   DropdownTrigger,
@@ -43,7 +43,7 @@ export function Breadcrumbs({
         )}
         {showTocToggle && (
           <Dropdown>
-            <DropdownTrigger asChild={false}>
+            <DropdownTrigger>
               <button
                 className={twMerge(
                   hiddenClass,

src/components/Breadcrumbs.tsx

@@ -1,13 +1,14 @@
 import { useState } from 'react'
 import { Card } from '~/components/Card'
-import { CodeBlock } from '~/components/markdown'
+import { HighlightedCodeBlock } from '~/components/markdown'
 import { FrameworkIconTabs } from '~/components/FrameworkIconTabs'
 import type { Framework } from '~/libraries'
 
 interface CodeExampleCardProps {
   title?: string
   frameworks: Framework[]
-  codeByFramework: Partial<Record<Framework, { lang: string; code: string }>>
+  /** Pre-highlighted HTML by framework (from server-side Shiki) */
+  codeByFramework: Partial<Record<Framework, { lang: string; html: string }>>
 }
 
 export function CodeExampleCard({
@@ -32,9 +33,12 @@ export function CodeExampleCard({
             value={framework}
             onChange={setFramework}
           />
-          <CodeBlock className="mt-0 border-0" showTypeCopyButton={false}>
-            <code className={`language-${selected.lang}`}>{selected.code}</code>
-          </CodeBlock>
+          <HighlightedCodeBlock
+            html={selected.html}
+            lang={selected.lang}
+            showCopyButton={false}
+            className="mt-0 border-0"
+          />
         </div>
       </Card>
     </div>

src/components/CodeExampleCard.tsx

@@ -1,44 +1,47 @@
 import React from 'react'
-import { CodeBlock } from '~/components/markdown'
+import { HighlightedCodeBlock } from '~/components/markdown'
 import { FileExplorer } from './FileExplorer'
 import { InteractiveSandbox } from './InteractiveSandbox'
 import { CodeExplorerTopBar } from './CodeExplorerTopBar'
 import type { GitHubFileNode } from '~/utils/documents.server'
 import type { Library } from '~/libraries'
 import { twMerge } from 'tailwind-merge'
 
-function overrideExtension(ext: string | undefined) {
-  if (!ext) return 'txt'
+function getLanguageFromPath(path: string): string {
+  const ext = path.split('.').pop() || ''
 
-  // Override some extensions
-  if (['cts', 'mts'].includes(ext)) return 'ts'
-  if (['cjs', 'mjs'].includes(ext)) return 'js'
-  if (['prettierrc', 'babelrc', 'webmanifest'].includes(ext)) return 'json'
-  if (['env', 'example'].includes(ext)) return 'sh'
-  if (
-    [
-      'gitignore',
-      'prettierignore',
-      'log',
-      'gitattributes',
-      'editorconfig',
-      'lock',
-      'opts',
-      'Dockerfile',
-      'dockerignore',
-      'npmrc',
-      'nvmrc',
-    ].includes(ext)
-  )
-    return 'txt'
+  const langMap: Record<string, string> = {
+    ts: 'typescript',
+    tsx: 'tsx',
+    js: 'javascript',
+    jsx: 'jsx',
+    mts: 'typescript',
+    cts: 'typescript',
+    mjs: 'javascript',
+    cjs: 'javascript',
+    json: 'json',
+    md: 'markdown',
+    html: 'html',
+    css: 'css',
+    scss: 'scss',
+    yaml: 'yaml',
+    yml: 'yaml',
+    toml: 'toml',
+    sh: 'bash',
+    bash: 'bash',
+    sql: 'sql',
+    vue: 'vue',
+    svelte: 'svelte',
+  }
 
-  return ext
+  return langMap[ext] || 'text'
 }
 
 interface CodeExplorerProps {
   activeTab: 'code' | 'sandbox'
   codeSandboxUrl: string
-  currentCode: string
+  /** Pre-highlighted HTML from server-side Shiki */
+  currentCodeHtml: string
   currentPath: string
   examplePath: string
   githubContents: GitHubFileNode[] | undefined
@@ -52,7 +55,7 @@ interface CodeExplorerProps {
 export function CodeExplorer({
   activeTab,
   codeSandboxUrl,
-  currentCode,
+  currentCodeHtml,
   currentPath,
   examplePath,
   githubContents,
@@ -85,6 +88,8 @@ export function CodeExplorer({
     return () => window.removeEventListener('closeSidebar', handleCloseSidebar)
   }, [])
 
+  const lang = getLanguageFromPath(currentPath)
+
   return (
     <div
       className={`flex flex-col min-h-[60dvh] sm:min-h-[80dvh] border border-gray-200 dark:border-gray-700 rounded-lg overflow-hidden ${
@@ -117,21 +122,15 @@ export function CodeExplorer({
             setCurrentPath={setCurrentPath}
           />
           <div className="flex-1 overflow-auto relative">
-            <CodeBlock
+            <HighlightedCodeBlock
+              html={currentCodeHtml}
+              lang={lang}
               isEmbedded
               className={twMerge(
                 'h-full border-0',
                 isFullScreen ? 'max-h-[90dvh]' : 'max-h-[80dvh]',
               )}
-            >
-              <code
-                className={`language-${overrideExtension(
-                  currentPath.split('.').pop(),
-                )}`}
-              >
-                {currentCode}
-              </code>
-            </CodeBlock>
+            />
           </div>
         </div>
         <InteractiveSandbox

src/components/CodeExplorer.tsx

@@ -5,16 +5,17 @@ import { useWidthToggle, DocNavigation } from '~/components/DocsLayout'
 import { AdGate } from '~/contexts/AdsContext'
 import { GamHeader } from './Gam'
 import { Toc } from './Toc'
-import { renderMarkdown } from '~/utils/markdown'
 import { DocBreadcrumb } from './DocBreadcrumb'
 import { MarkdownContent } from '~/components/markdown'
 import type { ConfigSchema } from '~/utils/config'
 import { useLocalCurrentFramework } from './FrameworkSelect'
 import { useParams } from '@tanstack/react-router'
+import type { MarkdownHeading } from '~/utils/markdown/types'
 
 type DocProps = {
   title: string
-  content: string
+  contentRsc: React.ReactNode
+  headings: MarkdownHeading[]
   repo: string
   branch: string
   filePath: string
@@ -36,7 +37,8 @@ type DocProps = {
 
 export function Doc({
   title,
-  content,
+  contentRsc,
+  headings,
   repo,
   branch,
   filePath,
@@ -51,12 +53,6 @@ export function Doc({
   footer,
   framework: frameworkProp,
 }: DocProps) {
-  // Extract headings synchronously during render to avoid hydration mismatch
-  const { headings, markup } = React.useMemo(
-    () => renderMarkdown(content),
-    [content],
-  )
-
   // Get current framework from prop, URL params, or local storage
   const { framework: paramsFramework } = useParams({ strict: false })
   const localCurrentFramework = useLocalCurrentFramework()
@@ -159,7 +155,7 @@ export function Doc({
             repo={repo}
             branch={branch}
             filePath={filePath}
-            htmlMarkup={markup}
+            contentRsc={contentRsc}
             containerRef={markdownContainerRef}
             libraryId={libraryId}
             libraryVersion={libraryVersion}

src/components/Doc.tsx

@@ -1,7 +1,7 @@
 import { useParams } from '@tanstack/react-router'
 import { Breadcrumbs } from './Breadcrumbs'
 import type { ConfigSchema } from '~/utils/config'
-import type { MarkdownHeading } from '~/utils/markdown/processor'
+import type { MarkdownHeading } from '~/utils/markdown/types'
 
 function findSectionForDoc(
   config: ConfigSchema,

src/components/DocBreadcrumb.tsx

@@ -1,5 +1,6 @@
 import { format, formatDistanceToNow } from '~/utils/dates'
-import { Markdown } from '~/components/markdown'
+// TODO: Fix feed to use server-rendered markdown
+// import { Markdown } from '~/components/markdown'
 import { libraries } from '~/libraries'
 import { partners } from '~/utils/partners'
 import { twMerge } from 'tailwind-merge'
@@ -415,7 +416,8 @@ export function FeedEntry({
 
               {/* Content */}
               <div className="text-xs text-gray-900 dark:text-gray-100 leading-snug mb-3">
-                <Markdown rawContent={entry.content} />
+                {/* TODO: Fix feed to use server-rendered markdown */}
+                <div>{entry.content}</div>
               </div>
 
               {/* External Link */}

src/components/FeedEntry.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react'
 import { format, formatDistanceToNow } from '~/utils/dates'
-import { Markdown } from '~/components/markdown'
+// TODO: Fix feed to use server-rendered markdown
+// import { Markdown } from '~/components/markdown'
 import { Card } from '~/components/Card'
 import { libraries } from '~/libraries'
 import { partners } from '~/utils/partners'
@@ -333,7 +334,8 @@ export function FeedEntryTimeline({
             !expanded && 'line-clamp-6',
           )}
         >
-          <Markdown rawContent={entry.content} />
+          {/* TODO: Fix feed to use server-rendered markdown */}
+          <div>{entry.content}</div>
         </div>
 
         {/* Show more/less button */}

src/components/FeedEntryTimeline.tsx

@@ -566,7 +566,7 @@ function LibraryRefinement() {
 
   return (
     <Dropdown>
-      <DropdownTrigger asChild={false}>
+      <DropdownTrigger>
         <button className="flex items-center gap-1 text-sm focus:outline-none cursor-pointer font-bold">
           {currentLibrary ? (
             <span className="uppercase font-black [letter-spacing:-.05em]">
@@ -638,7 +638,7 @@ function FrameworkRefinement() {
 
   return (
     <Dropdown>
-      <DropdownTrigger asChild={false}>
+      <DropdownTrigger>
         <button className="flex items-center gap-1 text-sm font-bold focus:outline-none cursor-pointer">
           {currentFramework && (
             <img