chore: bump fumadocs to 16.11, fumadocs-mdx to 15, shiki to 4

.github/workflows/ci-cd.yml

@@ -93,7 +93,11 @@ jobs:
           pnpm run lint:knip --workspace packages/e2e/remix
           pnpm run lint:knip --workspace packages/e2e/tanstack-router
       - name: Run Knip (docs)
-        run: pnpm run lint:knip --workspace packages/docs
+        # fumadocs-mdx must generate .source/ first (skipped by the
+        # --ignore-scripts install) so knip can resolve collections/*
+        run: |
+          pnpm run --filter docs postinstall
+          pnpm run lint:knip --workspace packages/docs
       - name: Run Knip (examples)
         run: |
           pnpm run --filter "examples-trpc" typegen

knip.json

@@ -53,7 +53,8 @@
       ],
       "project": ["content/**/*.{ts,tsx}", "src/**/*.{ts,tsx}"],
       "paths": {
-        "@/*": ["./*"]
+        "@/*": ["./*"],
+        "collections/*": ["./.source/*"]
       },
       "next": true,
       "ignoreFiles": [
@@ -63,8 +64,8 @@
       "ignoreDependencies": [
         "@headlessui/tailwindcss",
         "@tailwindcss/container-queries",
-        "@types/mdx",
         "hast-util-to-jsx-runtime",
+        "tailwindcss",
         "tailwindcss-animate"
       ]
     },

packages/docs/mdx-components.tsx

@@ -8,16 +8,6 @@ import defaultMdxComponents from 'fumadocs-ui/mdx'
 import type { MDXComponents } from 'mdx/types'
 import { Suspense } from 'react'
 
-declare module 'mdx/types.js' {
-  // Augment the MDX types to make it understand React.
-  namespace JSX {
-    type Element = React.JSX.Element
-    type ElementClass = React.JSX.ElementClass
-    type ElementType = React.JSX.ElementType
-    type IntrinsicElements = React.JSX.IntrinsicElements
-  }
-}
-
 const components = {
   ...defaultMdxComponents,
   Callout,

packages/docs/package.json

@@ -48,9 +48,9 @@
     "date-fns": "^4.4.0",
     "dayjs": "^1.11.21",
     "effect": "^3.22.0",
-    "fumadocs-core": "16.0.4",
-    "fumadocs-mdx": "13.0.2",
-    "fumadocs-ui": "16.0.4",
+    "fumadocs-core": "16.11.5",
+    "fumadocs-mdx": "15.2.0",
+    "fumadocs-ui": "16.11.5",
     "lucide-react": "^0.563.0",
     "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-to-markdown": "^2.1.2",
@@ -69,7 +69,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@shikijs/transformers": "^3.23.0",
+    "@shikijs/transformers": "^4.3.1",
     "@types/mdast": "^4.0.4",
     "@types/mdx": "^2.0.14",
     "@types/node": "^24.13.3",
@@ -80,7 +80,7 @@
     "postcss": "^8.5.19",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "shadcn": "^4.13.0",
-    "shiki": "^3.23.0",
+    "shiki": "^4.3.1",
     "typescript": "catalog:typescript",
     "typescript-7": "catalog:typescript",
     "unified": "^11.0.5",

packages/docs/source.config.ts

@@ -4,13 +4,14 @@ import {
   defineDocs,
   frontmatterSchema
 } from 'fumadocs-mdx/config'
+import lastModified from 'fumadocs-mdx/plugins/last-modified'
 import remarkSmartypants from 'remark-smartypants'
 import { z } from 'zod'
 import { rehypeCodeOptions } from './rehype-code.config'
 import { remarkAudience } from './src/lib/remark-audience'
 
 export default defineConfig({
-  lastModifiedTime: 'git',
+  plugins: [lastModified()],
   mdxOptions: {
     remarkPlugins: [remarkSmartypants, remarkAudience],
     rehypeCodeOptions,
@@ -27,7 +28,7 @@ export default defineConfig({
   }
 })
 
-export const { docs, meta } = defineDocs({
+export const docs = defineDocs({
   dir: 'content/docs',
   docs: {
     schema: frontmatterSchema.extend({

packages/docs/src/app/docs/[[...slug]]/page.tsx

@@ -1,4 +1,6 @@
+import { docsPageClassName } from '@/src/components/shared-layout'
 import { useMDXComponents } from '@/mdx-components'
+import type { TOCItemType } from 'fumadocs-core/toc'
 import { AsideSponsors } from '@/src/app/(pages)/_landing/sponsors'
 import { source } from '@/src/app/source'
 import {
@@ -40,10 +42,12 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
   const gated = gatedHeadingIds(await page.data.getText('raw'), version =>
     isPublished(version, published)
   )
-  const toc = page.data.toc.filter(item => !gated.has(item.url.replace(/^#/, '')))
+  const toc = page.data.toc.filter((item: TOCItemType) => !gated.has(item.url.replace(/^#/, '')))
 
   return (
     <DocsPage
+      className={docsPageClassName}
+      tableOfContentPopover={{ list: { thumbBox: false } }}
       toc={toc}
       tableOfContent={{
         footer: <AsideSponsors />

packages/docs/src/app/docs/changelog/page.tsx

@@ -1,3 +1,4 @@
+import { docsPageClassName } from '@/src/components/shared-layout'
 import { AsideSponsors } from '@/src/app/(pages)/_landing/sponsors'
 import {
   CopyAsMarkdownButton,
@@ -77,6 +78,8 @@ export default async function ChangelogPage() {
 
   return (
     <DocsPage
+      className={docsPageClassName}
+      tableOfContentPopover={{ list: { thumbBox: false } }}
       toc={toc}
       tableOfContent={{
         footer: <AsideSponsors />

packages/docs/src/app/docs/layout.tsx

@@ -15,7 +15,7 @@ export default function RootDocsLayout({ children }: { children: ReactNode }) {
       nav={{ ...shared.nav, mode: 'top' }}
       sidebar={{
         collapsible: false,
-        banner: SideBanner,
+        banner: <SideBanner />,
         footer: (
           <Suspense>
             <SidebarFooter />

packages/docs/src/app/globals.css

@@ -6,6 +6,19 @@
 @plugin '@tailwindcss/container-queries';
 @plugin '@headlessui/tailwindcss';
 
+/*
+  fumadocs-ui's preset.css no longer ships the `container` utility
+  (moved upstream to preset-legacy.css in 16.2, which we don't import).
+  It centered content and capped it at 1400px on 2xl screens; the site
+  layouts rely on it, so keep providing it locally.
+*/
+@utility container {
+  margin-inline: auto;
+  padding-inline: 1rem;
+
+  @apply 2xl:max-w-[1400px];
+}
+
 :root {
   --fd-layout-width: 1600px;
 
@@ -56,7 +69,12 @@
 @layer base {
   html,
   body {
-    height: 100%;
+    /*
+      min-, not plain height: fumadocs-ui 16.11 positions the docs
+      sidebar and TOC with `sticky` inside a grid that must grow with
+      the page content; a viewport-capped body freezes them in place.
+    */
+    min-height: 100%;
   }
   body {
     display: flex;

packages/docs/src/app/playground/(demos)/layout.tsx

@@ -1,5 +1,7 @@
+import { fullBleedPageClassName } from '@/src/components/shared-layout'
 import { QuerySpy } from '@/src/components/query-spy'
 import { QuerystringSkeleton } from '@/src/components/querystring'
+import { DocsPage } from 'fumadocs-ui/page'
 import React, { Suspense } from 'react'
 
 export default function PlaygroundDemoLayout({
@@ -8,11 +10,16 @@ export default function PlaygroundDemoLayout({
   children: React.ReactNode
 }) {
   return (
-    <>
+    <DocsPage
+      className={fullBleedPageClassName}
+      footer={{ enabled: false }}
+      tableOfContent={{ enabled: false }}
+      tableOfContentPopover={{ enabled: false }}
+    >
       <Suspense fallback={<QuerystringSkeleton>&nbsp;</QuerystringSkeleton>}>
         <QuerySpy />
       </Suspense>
       {children}
-    </>
+    </DocsPage>
   )
 }

packages/docs/src/app/playground/(demos)/pagination/pagination-controls.client.tsx

@@ -29,7 +29,7 @@ export function ClientPaginationControls({
         <PaginationItem>
           <PaginationPrevious
             disabled={page === 1}
-            onClick={() => setPage(p => Math.max(1, p - 1))}
+            onClick={() => setPage((p: number) => Math.max(1, p - 1))}
           />
         </PaginationItem>
         {Array.from({ length: numPages }, (_, i) => (
@@ -45,7 +45,7 @@ export function ClientPaginationControls({
         <PaginationItem>
           <PaginationNext
             disabled={page === numPages}
-            onClick={() => setPage(p => Math.min(numPages, p + 1))}
+            onClick={() => setPage((p: number) => Math.min(numPages, p + 1))}
           />
         </PaginationItem>
       </PaginationContent>

packages/docs/src/app/playground/layout.tsx

@@ -27,7 +27,7 @@ export default function PlaygroundLayout({
         nav={{ ...shared.nav, mode: 'top' }}
         sidebar={{
           collapsible: false,
-          banner: SideBanner,
+          banner: <SideBanner />,
           footer: (
             <Suspense fallback={<DebugControlsSkeleton />}>
               <DebugControl />

packages/docs/src/app/playground/page.tsx

@@ -1,3 +1,4 @@
+import { fullBleedPageClassName } from '@/src/components/shared-layout'
 import { Card } from 'fumadocs-ui/components/card'
 import {
   DocsBody,
@@ -14,7 +15,12 @@ export const metadata = {
 
 export default function PlaygroundIndexPage() {
   return (
-    <DocsPage>
+    <DocsPage
+      className={fullBleedPageClassName}
+      footer={{ enabled: false }}
+      tableOfContent={{ enabled: false }}
+      tableOfContentPopover={{ enabled: false }}
+    >
       <DocsTitle>{metadata.title}</DocsTitle>
       <DocsDescription>{metadata.description}</DocsDescription>
       <DocsBody>

packages/docs/src/app/registry/[name]/page.tsx

@@ -1,3 +1,4 @@
+import { docsPageClassName } from '@/src/components/shared-layout'
 import { useMDXComponents } from '@/mdx-components'
 import { rehypeCodeOptions } from '@/rehype-code.config'
 import { CodeBlock } from '@/src/components/code-block'
@@ -8,7 +9,7 @@ import type {
   RegistryBuiltItem
 } from '@/src/registry/schemas'
 import { SiTypescript } from '@icons-pack/react-simple-icons'
-import { Markdown } from 'fumadocs-core/content'
+import { Markdown } from 'fumadocs-core/content/md'
 import { rehypeCode, remarkHeading } from 'fumadocs-core/mdx-plugins'
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
@@ -34,6 +35,8 @@ export default async function Page({ params }: PageProps<'/registry/[name]'>) {
   const usage = await readUsage(name)
   return (
     <DocsPage
+      className={docsPageClassName}
+      tableOfContentPopover={{ list: { thumbBox: false } }}
       toc={[
         {
           url: '#installation',

packages/docs/src/app/registry/layout.tsx

@@ -89,7 +89,7 @@ export default async function RegistryLayout({
         nav={{ ...sharedLayoutProps.nav, mode: 'top' }}
         sidebar={{
           collapsible: false,
-          banner: SideBanner,
+          banner: <SideBanner />,
           footer: (
             <Suspense>
               <SidebarFooter />

packages/docs/src/app/registry/page.tsx

@@ -1,3 +1,4 @@
+import { docsPageClassName } from '@/src/components/shared-layout'
 import { H2 } from '@/src/components/typography'
 import { Card, Cards } from 'fumadocs-ui/components/card'
 import {
@@ -17,7 +18,10 @@ export const metadata = {
 
 export default function Page() {
   return (
-    <DocsPage>
+    <DocsPage
+      className={docsPageClassName}
+      tableOfContentPopover={{ list: { thumbBox: false } }}
+    >
       <nav className="mb-4 flex items-center justify-between">
         <DocsTitle>Shadcn Registry</DocsTitle>
         <RssFeedLink />

packages/docs/src/app/source.ts

@@ -1,9 +1,9 @@
-import { blog as blogPosts, docs, meta } from '@/.source'
+import { blog as blogPosts, docs } from 'collections/server'
 import type { Item } from 'fumadocs-core/page-tree'
 import { type InferPageType, loader } from 'fumadocs-core/source'
-import { createMDXSource } from 'fumadocs-mdx/runtime/next'
+import { toFumadocsSource } from 'fumadocs-mdx/runtime/server'
 
-const mdxSource = createMDXSource(docs, meta)
+const mdxSource = docs.toFumadocsSource()
 
 export const source = loader({
   baseUrl: '/docs',
@@ -37,7 +37,7 @@ export const fullSource = loader({
 
 export const blog = loader({
   baseUrl: '/blog',
-  source: createMDXSource(blogPosts, [])
+  source: toFumadocsSource(blogPosts, [])
 })
 
 export type Page = InferPageType<typeof source>

packages/docs/src/components/changelog/preamble.tsx

@@ -1,6 +1,6 @@
 import { useMDXComponents } from '@/mdx-components'
 import { rehypeCodeOptions } from '@/rehype-code.config'
-import { Markdown } from 'fumadocs-core/content'
+import { Markdown } from 'fumadocs-core/content/md'
 import { rehypeCode, remarkHeading } from 'fumadocs-core/mdx-plugins'
 import remarkSmartypants from 'remark-smartypants'
 

packages/docs/src/components/shared-layout.tsx

@@ -13,6 +13,11 @@ export function getSharedLayoutProps(): BaseLayoutProps {
       ),
       transparentMode: 'top'
     },
+    // fumadocs-ui defaults to a two-state light/dark toggle since 16.7;
+    // restore the 3-way switch with the system option
+    themeSwitch: {
+      mode: 'light-dark-system'
+    },
     links: [
       {
         text: 'Documentation',
@@ -37,3 +42,16 @@ export function getSharedLayoutProps(): BaseLayoutProps {
     ]
   }
 }
+
+/*
+  fumadocs-ui 16.11 caps DocsPage children at 900px but leaves them
+  start-aligned in the main grid track; center them like before.
+*/
+export const docsPageClassName = '*:mx-auto *:w-full'
+
+/*
+  Playground pages were full-bleed before the DocsPage wrapper became
+  structurally required; lift the 900px child cap (important beats the
+  container's *:max-w-[900px] regardless of stylesheet order).
+*/
+export const fullBleedPageClassName = `${docsPageClassName} *:max-w-none!`

packages/docs/tsconfig.json

@@ -16,7 +16,8 @@
     "jsx": "react-jsx",
     "incremental": true,
     "paths": {
-      "@/*": ["./*"]
+      "@/*": ["./*"],
+      "collections/*": ["./.source/*"]
     },
     "plugins": [
       {