fumadocs Documentation

Apps Docs Components Agent Instructions (`apps/docs/components/agent-instructions.md`) Copy Section

Set up a Fumadocs site

Instructions for AI coding agents, follow them in order. Fumadocs docs: https://fumadocs.dev/docs, append .mdx to any docs page URL to get it as Markdown, https://fumadocs.dev/llms.txt lists all pages.

1. Keep the docs site separate Copy Chapter

Create the docs as its own app: a new directory or repository, or a new workspace package (e.g. apps/docs) in a monorepo.

Don't add Fumadocs to an existing marketing or product app unless the user explicitly asks for it: Fumadocs UI ships global styles and its own layouts, mixing them into an unrelated app leads to style conflicts, coupled deployments and harder upgrades. If the user does want it inside an existing app, skip step 2 and run npx @fumadocs/cli@latest init --yes in the app (adds the docs in a dedicated route group, supports Next.js, Waku, React Router and Tanstack Start), or follow the manual installation guide of the framework:

• Next.js: https://fumadocs.dev/docs/manual-installation/next.mdx (Recommended)
• Waku: https://fumadocs.dev/docs/manual-installation/waku.mdx (Recommended if user prefer Vite)
• React Router: https://fumadocs.dev/docs/manual-installation/react-router.mdx
• Tanstack Start: https://fumadocs.dev/docs/manual-installation/tanstack-start.mdx
• Astro: https://fumadocs.dev/docs/manual-installation/astro.mdx (Not recommended, some features and syntax are not supported due to framework limitations)

2. Scaffold with create-fumadocs-app Copy Chapter

Use the official scaffolder, it produces the reference project structure with search, llms.txt and OG images configured. Templates:

• +next+fuma-docs-mdx (Next.js): the default, use it unless the user prefers another framework.
• waku, react-router, tanstack-start: when the user already uses that framework.
• +next+fuma-docs-mdx+static, react-router-spa, tanstack-start-spa: when the site must be fully static (hosted on a CDN).

Run it non-interactively (requires Node.js 22+), --yes uses defaults for unspecified options and --pm selects the package manager:

npx create-fumadocs-app@latest my-docs --template +next+fuma-docs-mdx --install --yes

All options: https://fumadocs.dev/docs/cli/create-fumadocs-app.mdx

Don't hand-write the setup from memory or pin older versions, the generated project is the source of truth. Don't edit the .source/ folder, it is generated by Fumadocs MDX.

3. Verify Copy Chapter

Run npm run dev, open http://localhost:3000/docs and make sure pages render. Run npm run build before you finish, fix build errors by reading the docs of the relevant feature rather than removing it.

4. Add content Copy Chapter

• Pages are MDX files in content/docs, the folder structure defines the URLs. Every page needs a title in its frontmatter, and ideally a description.
• meta.json files order pages and folders: https://fumadocs.dev/docs/page-conventions.mdx and https://fumadocs.dev/docs/navigation.mdx
• When migrating existing Markdown docs, move them as-is and keep their content, only adjust frontmatter and links. Supported syntax and components: https://fumadocs.dev/docs/markdown.mdx
• Site name and links live in lib/layout.shared.tsx, GitHub info in lib/shared.ts (Next.js template; other templates put app code under src/, check the generated README).

5. Deploy separately Copy Chapter

Deploy the docs app as its own project on the hosting provider: https://fumadocs.dev/docs/deploying.mdx

To serve it under the main domain, use a subdomain like docs.example.com, or route /docs/* from the main site to the docs deployment (e.g. Next.js Multi-Zones). Keep the docs under the default /docs route so both options work.

Apps Docs Public Robots (`apps/docs/public/robots.txt`) Copy Section

User-agent: *
Allow: /

Host: https://fumadocs.dev

Sitemap: https://fumadocs.dev/sitemap.xml

Apps Docs Content Blog 2024 5 15 (`apps/docs/content/blog/2024-5-15.mdx`) Copy Section

title: How Fumadocs works authors: [fuma] date: 2024-05-15 Copy Chapter

1 year ago, I was having fun with Next.js App Router.
While experimenting with it on my toy No Deploy, I planned to build documentation.
However, Nextra does not support App Router.

To handle this, I implemented a small documentation site with solely Contentlayer and the new features from App Router.
It was working great, looked blazing-fast and minimal.
I cloned the logic from No Deploy and built this documentation framework.
With a few months of development, it soon became powerful and stable.

It was originally named next-docs, I renamed it to Fumadocs as it conflicts with Next.js Docs.

Thanks to the support from Next.js community, I've received a lot of suggestions along the way.
Fumadocs is now a framework used by my libraries and some other amazing projects.

My Opinion Copy Chapter

In Web development, most "robust" frameworks/libraries are incredibly heavy and fabulous, but it has indeed made our developer experience fancy.

On top of Javascript, people built bundlers, transpilers, and even Typescript.
It feels very surprising that Javascript, a high-level scripting language, is more similar to assembly code in modern Web development.
We rarely use them without things like Webpack. This also applies to CSS, at least in my experience, I seldom use CSS without PostCSS.

While they might be necessary for compatibility and DX, the landing of React Server Component and Next.js App Router made the experience even more mindblowing.
It feels like magic. These cunning magical frameworks, and web development miracles.
This kind of design is insane, but it also makes us mindlessly forget the boundaries.

Beginners use Metadata API, while they have no idea how meta tag works.
They put server-side logic in a server component, while they have no idea how expensive the calculation is.
Even when we looked at the code, we can't predict the result without running it in production mode.
I saw too many of these misconceptions.

This happens on many frameworks, they are overly magical.
I wanted to make it less-magic, and straightforward at least for most Next.js developers.

Fumadocs MDX Copy Chapter

As the recommended content source, It is actually a webpack hack.
Since Next.js could only optimize static imports, it first transforms your .map.ts to a file that roughly yields:

export default [import("./my/file.mdx"), ...];

And then transforms MDX files with a custom loader. It makes all magic possible, but it doesn't have the ability of lazy-loading MDX files.
Comparing to Nextra, it might be a suboptimal approach.

Nextra does it even easier, it directly transforms MDX files into pages. Because the Pages Router adapts Javascript files as a single page, it is possible.
In App Router, this is not possible anymore. Therefore, I didn't take this approach.

Fumadocs Core Copy Chapter

The core of Fumadocs is a bunch of utilities and MDX plugins.

• Source API construct page trees from content source, integrated with other content providers.
• Headless components accelerate Fumadocs UI and other custom UI implementations.
• MDX plugins bring a perfect developer experience to all integrations.
• Search utilities make it way easier to implement document search.

In addition, it has also established the definitions of Page Tree and Page Conventions.
Overall, it is not yet a framework without Fumadocs UI.

In my opinion, the most valuable part of the codebase is MDX plugins.
I learned a lot more about ASTs and the eco-system of remark/rehype while working on them.
Absolutely an amazing experience.

Fumadocs UI Copy Chapter

The UI implementation of Fumadocs using Tailwind CSS and Radix UI.
Its design system was inspired by Shadcn UI, using CSS variables for color utilities.

Although the structure of Fumadocs UI is even simpler than core, I've used some subtle hacks to solve the problem of "use client" directive.
The bundler I am using, TSX, can't handle nested structures like client components imported from a server component.
Therefore, I made a little hack to build server components and client components as an individual entry, then inject import statements after the process.

Also it took me some time to come up with the preset approach for integrating Fumadocs UI with Tailwind CSS projects.

Docs Generators Copy Chapter

We have a few built-in integrations, like fumadocs-openapi which takes an OpenAPI schema and output MDX files.

For the OpenAPI one, it simply parses the schema and convert it to MDX file through string templates.

The Typescript integration does a bit more, it obtains type information with Typescript Compiler API. Based on the information, it yields MDX files.
You can use it inside a server component, which is how <AutoTypeTable /> works.

CI/CD Copy Chapter

As a project with very few contributors, I built the CI/CD process as convenient as possible for a better efficiency.
The entire release process is handled by Changesets, and I wrote the scripts to update the template repository automatically.
It worked great so far.

Thanks Copy Chapter

The Github repository of Fumadocs has reached 300 stars in 2024 March, it is a new achievement for me.
Welcome to give it a star to support my work!

Original
https://fuma-nama.vercel.app/blog/fumadocs

Apps Docs Content Blog 2024 5 16 (`apps/docs/content/blog/2024-5-16.mdx`) Copy Section

title: 500 Stars authors: [fuma] date: 2024-05-16 Copy Chapter

It was surprising when I first saw the video from Web Dev Cody, it felt like I had finally built something worth mentioning, instead of another neglected side project that nobody cares about.

So far I've worked on this project for about 1 year, and it is a precious experience to me. The best lecture that you can't find in a university.

Open Source Copy Chapter

I received much feedback, issues and questions. Some are brutal but straightforward, like "please fix it, help me please" "Support XXX please". Some are kind and helpful, willing to provide a PR.
I felt both the good and bad sides of open source.

Sometimes, people are being eager and impulsive because of stress and may spread their frustration on the library maintainers.
Even myself, can be affected by stress or a bad mood.

People may hope for instant answers, and maintainers will face questions like "Why are you running away from my questions?".
I understand a library performing bad can cause your precious time to be wasted, but even if we put all our efforts in maintaining the library, it can't be flawless.

Since then, I feel I'm way more respectful to open-source project maintainers.
At least, I'll check my before before firing an issue on somebody else's Github repository, and try to be as respectful as I can with my poor language skills.

Issues Copy Section

My favourite dev was Anthony Shew, I mentioned him because the issue he opened is the best I've ever seen in my open-source career.
He actually cared about my vision and opinion about the API design, and gave a really concise and constructive feature request.

Obviously, I was not a perfect, neither an experienced library dev.
Fumadocs wasn't capable of many things, such a well-explained feature request and idea is powerful. His passion is inspiring.

Before setting up the YAML issue template, there were very few issues that actually followed the issue template, most of them don't even provide a reproducible repository, or an explanation.

Open a proper issue, follow the instructions, and give maintainers some positive feedback. This is the biggest motivation you can give to maintainers without spending money.

Docs Copy Chapter

It's fun to work on the docs of fumadocs. When first building it, I had very little experience on authoring documentation and tutorial content.
Reading through the feedback from developers, the most common problem is that they can't find the docs of something.

I realized the entire docs is unfriendly for beginners to start with, my friends are senior Next.js devs, and of course they are fine with that.
However, not every dev can understand the docs.

So recently, I started to re-write some of the sections, making it easier and appealing for beginners. Welcome to share your feedback on Github Discussions!

What is Next? Copy Chapter

Web Development is an ever-evolving industry, but I believe the spirit of open source won't disappear.
I don't know what I will be building in the future, and that doesn't matter.
Let's build a better web!

Apps Docs Content Blog A Mistake (`apps/docs/content/blog/a-mistake.mdx`) Copy Section

title: The early mistake of Fumadocs authors: [fuma] date: 2025-08-22 Copy Chapter

A Mistake Copy Chapter

The early mistake of Fumadocs was Fumadocs CLI being too late and not getting enough mentions on docs.

To push the CLI approach further like the recent Shadcn CLI support, there are changes we have to make.
Early adopters will face problems if their customizations went beyond what our abstraction can mitigate.

For example: A small CSS change can still break hacky CSS customizations. We can only ensure backward compatibility for the ones scoped by CSS selectors, or exposed options:

#nd-sidebar {
  /* this will work forever */
  background-color: red;
}

For CLI to work better, we need layout components to be entirely independent for modularization. A ideal state is that:

• Normal users can use exposed options, enjoying UI iterations from upstream.
• Advanced customizations can use Fumadocs CLI, avoiding upstream changes.

Same as the solution described in this post about UI Customization.

A Good Example Copy Section

For lighter customizations like nuqs did, a PR to migrate from old versions #1056 can reduce code on user land and migration is simple.

The Problems Copy Section

When your hacks are heavier, migration is much harder combined with the tech debt of your codebase.

Some problems I observed:

Page Tree API being Neglected

Page tree is actually a crucial idea of Fumadocs, unifying all navigation & linking of docs.

Even in the early days, it's already a robust API supporting features like Root Folder (since v12):

Some projects didn't rely on our file-based routing nor page tree API, which resulted in a lot of hacks around sidebar & loader().

Its idea is simple:

files -> Fumadocs -> page tree

page tree -> navigation components (e.g. page footer & sidebar)

Using it properly can already reduce a massive amount of work, we have a specs for Page Tree for hardcoded page trees.

CSS Variables being Neglected

Fumadocs is using CSS variables for all colors since the beginning, the naming is identical to Shadcn UI which makes customization easy.

But I noticed some are overriding the Tailwind CSS classes rather than colors, like:

#nd-sidebar .color-fd-background\/80 {
  color: red;
}

In fact we always support a simpler way:

#nd-sidebar {
  --color-fd-foreground: red;
}

Now we also have a Shadcn UI preset to reuse your colors from main app.

Early Reflections Copy Section

I think the CLI approach is correct, it'll be the primary way for advanced customization.

My future plans:

• Continue improving Fumadocs CLI: adding install-time optimization to remove unused files according to your options (e.g. use existing sidebar component instead of installing one).
• A better versioning policy: Reduce abstraction for mitigating upstream changes, instead version the components directly (e.g. creating a new fumadocs-ui/layouts/v2/page instead of a major UI change).
• Add Fumadocs-native cloud features: More official integrations like monitoring/analytics feature designed for Fumadocs.

My biggest goal is to build my own dev team or startup, I realized my time is too limited to build the excellent software in my imaginary.
There's rough edges that I never found time to polish, and too many things to do - even if AI has handled the basic work.

That's all I want to say :)

Welcome for questions (via DM/GitHub), I'm happy to improve rough edges whenever I have time.

Apps Docs Content Blog Customise Ui (`apps/docs/content/blog/customise-ui.mdx`) Copy Section

title: Rethink how we customize UI authors: [fuma] date: 2025-04-15 Copy Chapter

The Problem Copy Chapter

Making a docs framework isn't challenging, the hardest problem is how I can make it perfect for everyone, from the perspective of users and developers.
Undoubtedly, this is a dilemma for all frameworks, or even library authors — You cannot write generic code that works out-of-the-box, there's no piece of software that is straight usable while being generic.

For example, headless UI libraries like Radix UI gave us the concept of generic UI components: bare UI primitives that we can customize according to our aesthetics.
However, you'll need time to tune them, these primitives are unusable without further customizations.

Yep it's 2025, Shadcn UI had led a "revolution" on Web Development. It's a great combination of headless UI and styled defaults that takes an extra step away!
But our problem remains unsolved, it might be preposterous that it becomes "unstyled" again when a vast majority of new sites adopted Shadcn UI.

Personally, I felt overwhelmed by nearly identical, ubiquitous flat designs that are obviously one of the default Shadcn UI styles. It has nothing to do with Shadcn UI, but the rest of developers who don't actually care about aesthetics and uniqueness.
Eventually, Shadcn-like design became the default styles, so once again, we will need to do a bit more to make it look stylish.

What should we do? Copy Section

As a docs framework started from "being flexible", Fumadocs must be customisable, tuned to meet developers' preferences.
We will need to take customization seriously if DX is what we aim. And most importantly, it should encourage developers with a sense of beauty to customize.

The Solution Copy Chapter

Typically, there are two types of developers:

those who want docs that just work Copy Section

Fumadocs need to be opinionated by default such that it is immediately usable, and we only have to offer simplest options to change details. (e.g. colors, overriding components).

Most developers have no desire to install dozens of components just to change a tiny detail, which makes the Shadcn approach suboptimal.

those who need the perfect docs tailored to their preferences Copy Section

The kernel of Fumadocs, or the spirit we're pursuing is the latter one. I crafted Fumadocs CLI, a version of Shadcn UI dedicated for Fumadocs, the whole solution is now simplified into a single command:

npx @fumadocs/cli customize

It accounts for two types:

• Customize the default styles when the exposed options are inadequate.
• Roll their own layout from scratch.

The first one is self-evident, people will always have absurd needs that we have not even considered.
We can install the original components, so it's simply identical to the default UI which they've been using.

The latter one is simpler, we can offer the minimal template they can start customising from.

This methodology, inspired by ejection, brings some nice advantages:

Don't break anything when you upgrade Fumadocs

Fumadocs need to be opinionated. Hence, we need to iterate the UI frequently which apparently will break people's hacky customizations.
The charm of Fumadocs CLI is that once you've installed the layout, it stays the same forever regardless of future iterations on Fumadocs UI.

It gives the courage for Fumadocs UI to iterate, and developers to customize unburnt by the fear of upgrading dependencies.

Looks Clean

Just like Shadcn UI and Radix UI, Fumadocs UI has a core package (fumadocs-core), most generic logic will be abstracted by core.

What is Next? Copy Chapter

The innovation of Shadcn UI is amazing, yet, I believe there's more problems Fumadocs can solve.

See Flags SDK and BetterAuth, you can't tell at the first glance if they're powered by Fumadocs.
I hope it can continue to be a "breakable" framework known for how customisable it is.

Apps Docs Content Blog Fumadocs Mdx Road Map (`apps/docs/content/blog/fumadocs-mdx-road-map.mdx`) Copy Section

title: The Future of Fumadocs MDX date: 2025-12-05 authors: [fuma] tags: [Fumadocs MDX] Copy Chapter

Overview of Fumadocs MDX Copy Chapter

Fumadocs MDX serves as a content processing layer, initially developed for processing MDX files and as an alternative to Contentlayer.

Its primary functions include:

• Compiling and processing content.
• Offering interfaces to access compiled content.
• Ensuring type safety and compatibility across environments, such as browsers and Cloudflare Workers.

Comparison with CMS Copy Section

Fumadocs MDX is not a content management system (CMS). A CMS encompasses more than content processing, it integrates features such as:

• Database Integration: For storing content.
• Version Control: To enable rollbacks, commits, and conflict resolution.
• Permission Management: To handle user access and roles.
• Authoring Workflow: Supporting stages like drafting, reviewing, and publishing.

Fumadocs MDX lacks these CMS capabilities independently, but they can be achieved through integration with Git and GitHub. This approach offers distinct benefits over traditional CMS solutions, including:

• Maintaining a unified history within Git, rather than distributing it across Git and a separate CMS.
• Composing content and code changes in a single pull request.

GitHub's collaboration tools, such as access controls, pull request reviews, and automation, support the implementation of authoring workflows.

Fumadocs MDX is not intended to evolve into a CMS; it remains a foundational content processing layer.

Roadmap Copy Chapter

Fumadocs MDX is closely associated with Fumadocs, yet the content processing layer should ideally operate independently, without reliance on any specific documentation framework.

In the near future, certain components will transition to fuma-content, improving extensibility and introducing more APIs. Such as:

• Framework Agnostic: Fuma Content should work anywhere, including Vite, Turbopack/Webpack, and even JS runtimes.
• No Framework Defaults: the MDX preset of Fumadocs will be offered by fumadocs-core, likely as a Fuma Content plugin.
• Content Adapters: Expanding support beyond MDX and JSON files to include custom collection types, as well as an Obsidian plugin for handling editor-specific syntax.
• Zero breaking changes to Fumadocs MDX: we adopt Fuma Content under the hood, but surface APIs will not be changed. Ideally, it will be similar to how Vite leverages Rolldown.

API-wise, Fuma Content plugins will distinguish from bundler plugins, but plugins can leverage the built-in abstraction layer to implement loaders.
Otherwise, we will encourage Unplugin for advanced needs.

Although fuma-content focuses on content processing, it provides a foundation for developing a CMS layer, such as plugins for MDX editing or remote databases. It will be a bigger goal.

The Current Progress Copy Section

Fumadocs MDX already includes primitives for advanced setups, such as the new Workspace API, which enables content processing across multiple repositories.

We are welcome for feedbacks on GitHub Discussions!

Apps Docs Content Blog Make A Blog (`apps/docs/content/blog/make-a-blog.mdx`) Copy Section

title: Making a Blog with Fumadocs authors: [fuma] date: 2024-12-15 Copy Chapter

Fumadocs is a docs framework, but it's also a powerful tool to manage content in Next.js. You can use Fumadocs to build a blog site along with docs, on a single Next.js app.

Overview Copy Chapter

This guide helps you build a blog site with Fumadocs and Fumadocs MDX.

We will use Fumadocs MDX to manage the content, and implement our own UI with Tailwind CSS & Fumadocs UI.

Configure Content Copy Section

Define a blogPosts collection.

import { defineCollections } from 'fumadocs-mdx/config';
import { pageSchema } from 'fumadocs-core/source/schema';
import { z } from 'zod';

export const blogPosts = defineCollections({
  type: 'doc',
  dir: 'content/blog',
  // add required frontmatter properties
  schema: pageSchema.extend({
    author: z.string(),
    date: z.string().date().or(z.date()),
  }),
});

Parse the output collection in source.ts:

import { loader } from 'fumadocs-core/source';
import { toFumadocsSource } from 'fumadocs-mdx/runtime/server';
import { blogPosts } from 'collections/server';

export const blog = loader({
  baseUrl: '/blog',
  source: toFumadocsSource(blogPosts, []),
});

You can now access the content from blog.

Implement UI Copy Section

Create an index page for blog posts.

By default, there should be a (home) route group with <HomeLayout /> inside.
Let's put the blog pages under it, this way we can get the nice navbar on our blog site.

import Link from 'next/link';
import { blog } from '@/lib/source';

export default function Home() {
  const posts = blog.getPages();

  return (
    <main className="flex-1 w-full max-w-[1400px] mx-auto px-4 py-8">
      <h1 className="text-4xl font-bold mb-8">Latest Blog Posts</h1>
      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
        {posts.map((post) => (
          <Link
            key={post.url}
            href={post.url}
            className="block bg-fd-secondary rounded-lg shadow-md overflow-hidden p-6"
          >
            <h2 className="text-xl font-semibold mb-2">{post.data.title}</h2>
            <p className="mb-4">{post.data.description}</p>
          </Link>
        ))}
      </div>
    </main>
  );
}

And create a page for blog posts.

Note that blog posts won't have nested slugs like /slug1/slug2. We don't need a catch-all route for blog posts.

/* Detailed source-code truncated for AI context efficiency. */

And configure metadata:

import { notFound } from 'next/navigation';
import { blog } from '@/lib/source';

export async function generateMetadata(props: { params: Promise<{ slug: string }> }) {
  const params = await props.params;
  const page = blog.getPage([params.slug]);

  if (!page) notFound();

  return {
    title: page.data.title,
    description: page.data.description,
  };
}

Write Posts Copy Section

The UI is now complete, you can write some blog posts under the content/blog directory, like:

---
title: Hello World
author: Fuma Nama
date: 2024-12-15
---

## Hello World

This is an example!

After spinning up the development server with next dev, you should see the blog posts under /blog route.

Apps Docs Content Blog Mdx 12 (`apps/docs/content/blog/mdx-12.mdx`) Copy Section

title: Fumadocs MDX v12 date: 2025-09-20 authors: [fuma] tags: [Release, Fumadocs MDX] Copy Chapter

Overview Copy Chapter

Fumadocs MDX v12 mainly aims to unify Fumadocs MDX on Vite and Next.js.

It contains renames to certain APIs (import paths are unaffected), migrations may be necessary.

Breaking Changes Copy Chapter

Next.js Copy Section

Removed content on page data in favour of getText().

import { source } from '@/lib/source';

const page = source.getPage(['...']);
console.log(page.data.content);

import { source } from '@/lib/source';

const page = source.getPage(['...']);
console.log(await page.data.getText('raw'));

API Renames on page data:

• _file -> info.
• _file.absolutePath -> info.fullPath.

import { source } from '@/lib/source';

const page = source.getPage(['...']);
console.log(page._file, page._file.absolutePath);

import { source } from '@/lib/source';

const page = source.getPage(['...']);
console.log(page.info, page.info.fullPath);

Improvements Copy Chapter

Vite Copy Section

Added APIs for info to access raw file info.

import { source } from '@/lib/source';

const page = source.getPage(['...']);
console.log(page.info);

`getText()` Copy Section

You can use it to access:

• Raw Markdown content.
• Processed Markdown before being compiled into HAST (HTML).

This is useful for llms.txt generation when used with docs generations tools & remark plugins.

import { source } from '@/lib/source';

const page = source.getPage(['...']);
console.log(await page.data.getText('raw'));
console.log(await page.data.getText('processed'));

To access processed Markdown content, you need to enable includeProcessedMarkdown in collection config.

import { defineDocs } from 'fumadocs-mdx/config';

export default defineDocs({
  docs: {
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
});

Apps Docs Content Blog Mdx V10 Summary (`apps/docs/content/blog/mdx-v10-summary.mdx`) Copy Section

title: Fumadocs MDX v10 Summary date: 2024-11-24 authors: [fuma] tags: [Fumadocs MDX] Copy Chapter

Features Copy Chapter

• More customizations via source.config.ts, a new config file for your content.
• Introduced collections.
• Turbopack support.
• Build-time data validation support.

Migrate from v9 Copy Chapter

Refactor Imports Copy Section

Refactor the import in next.config.

From:

import createMDX from 'fumadocs-mdx/config';

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};

export default withMDX(config);

To:

import { createMDX } from 'fumadocs-mdx/next';

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const config = {
  reactStrictMode: true,
};

export default withMDX(config);

Remove `mdx-components.tsx` Copy Section

mdx-components.tsx is no longer used. It now allows only MDX components passed from MDX body's components prop.

import defaultMdxComponents from 'fumadocs-ui/mdx';

const MDX = page.data.body;

// set your MDX components with `components` prop
<MDX components={{ ...defaultMdxComponents }} />;

This encourages explicit import of MDX components.

Previously, mdx-components.tsx worked by injecting an import to every compiled Markdown/MDX file.
It's somewhat unnecessary because you can always import the components explicitly, or replace default HTML tags like img from MDX body's components prop.

Define Collections Copy Section

Collection is now introduced on source config file (source.config.ts).
It refers to a collection of files/content, such as Markdown files or JSON/YAML files.

Every collection has its own config, you can have customized Zod schema to validate its data, or collection-level MDX options for content collections.

You can create a source config file, and add the following:

import { defineDocs } from 'fumadocs-mdx/config';

export const { docs, meta } = defineDocs({
  dir: 'content/docs',
});

defineDocs declares two collections, one with doc type that scans content files (e.g. md/mdx), one with meta type that scans meta files (e.g. json).

Now you can generate types using fumadocs-mdx command, it's recommended to set it as a postinstall script.

{
  "scripts": {
    "postinstall": "fumadocs-mdx"
  }
}

When starting the development server, a .source folder will be generated, it contains all parsed collections/files.
You can add it to .gitignore, it will replace the old .map file.

To access the collections, import them from the folder with their original name in source.config.ts.

import { docs, meta } from '@/.source';

Now to integrate it with Fumadocs framework, change your source.ts from:

import { map } from '@/.map';
import { createMDXSource } from 'fumadocs-mdx/runtime/next';
import { loader } from 'fumadocs-core/source';

export const { getPage, getPages, pageTree } = loader({
  baseUrl: '/docs',
  rootDir: 'docs',
  source: createMDXSource(map),
});

to:

import { docs, meta } from '@/.source';
import { createMDXSource } from 'fumadocs-mdx/runtime/next';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/docs',
  source: createMDXSource(docs, meta),
});

• we now recommend exporting the output of loader directly as a single variable.
• schema option is no longer defined in source.ts, it's handled by source.config.ts.
• it takes two collections: docs (content) and meta (meta.json).
  You can leave meta as an empty array if it is unused, so you can define only a collection for docs.

`page.data` Copy Section

When using with loader, you no longer need data.frontmatter to access frontmatter data.
It is merged into the page.data object.

page.data.frontmatter.title; // [!code --]
page.data.title; // [!code ++]

MDX Options Copy Section

Instead of passing them to next.config file, define a global config in source.config.ts:

import { defineConfig } from 'fumadocs-mdx/config';

export default defineConfig({
  mdxOptions: {
    // here!
  },
});

Collection Schema Copy Section

The schema option of collection allow you to customize the validation schema, it accepts a Zod type.

For defineDocs, see schema.

Multiple Types Copy Section

Same as before, you can call loader multiple times for different types (e.g. for docs and blog).

import { createMDXSource } from 'fumadocs-mdx/runtime/next';
import { loader } from 'fumadocs-core/source';
import { meta, docs, blog as blogPosts } from '@/.source';

export const source = loader({
  baseUrl: '/docs',
  source: createMDXSource(docs, meta),
});

export const blog = loader({
  baseUrl: '/blog',
  // as mentioned before, you can leave `meta` an empty array
  source: createMDXSource(blogPosts, []),
});

export type DocsPage = (typeof source)['$inferPage'];
export type DocsMeta = (typeof source)['$inferMeta'];

and the corresponding source.config.ts:

import { defineDocs, defineCollections, frontmatterSchema } from 'fumadocs-mdx/config';
import { z } from 'zod';

export const { docs, meta } = defineDocs({
  dir: 'content/docs',
});

export const blog = defineCollections({
  type: 'doc',
  dir: 'content/blog',
  schema: frontmatterSchema.extend({
    author: z.string(),
    date: z.string().date().or(z.date()).optional(),
  }),
});

Further Readings Copy Section

You can read the latest docs of Fumadocs MDX for details.

Apps Docs Content Blog Mdx V10 (`apps/docs/content/blog/mdx-v10.mdx`) Copy Section

title: Fumadocs MDX v10 date: 2024-09-06 authors: [fuma] tags: [Release, Fumadocs MDX] Copy Chapter

The Problem Copy Chapter

Fumadocs MDX worked great for docs. But we also want to prioritize flexibility and code organization.

Previously, it was a simple Webpack loader that turns MDX into JavaScript.
You pass the MDX processor options to the loader, it turns them into JavaScript files.
Then, a .map.ts will be exported:

export const map = {
  'docs/index.mdx': import('./docs/index.mdx'),
  'docs/guide.mdx': import('./docs/guide.mdx'),
};

Your Next.js app will import the map file, and access the available MDX files.

This model works, but we started to see some problems:

• No built-in way to define multiple collections:

  For example, we have a directory for blog posts and a directory for docs pages.

  On Fumadocs MDX, all these resources are transformed into a single object exported by .map.ts:

  ts Copy

  export const map = {
    'blog/post.mdx': import('./blog/post.mdx'),
    'docs/index.mdx': import('./docs/index.mdx'),
  };

  We implemented a solution using Source API rootDir option, but this is not the ideal way.
  This also gave us another problem:

• Different MDX Options for each collection:

  Same as the above example, we have a /blog directory for blog posts.
  If we want to add a remark plugin that only work on blog posts, this is impossible with Fumadocs MDX.

  Once you apply a remark plugin, it's effective on all MDX files, including the MDX files in the docs directory.

• Turbopack Compatibility:

  Turbopack doesn't allow passing unserializable options to loaders.
  However, the entire MDX, remark and rehype ecosystem use functions for plugins.
  Functions are not serializable, we cannot migrate Fumadocs to Turbopack unless we find a seamless solution that supports Turbopack.

• Compile-time validation:

  All schema validation cannot be done during build time because the MDX loader actually, doesn't know the collections you defined in source.ts.

  Furthermore, the Zod schema is passed to the source adapter in source.ts rather than the loader:

  ts Copy

  import { loader } from 'fumadocs-core/source';
  import { createMDXSource } from 'fumadocs-mdx/runtime/next';
  
  export const source = loader({
    source: createMDXSource(map, {
      // schema
    }),
  });

  This loses some performance optimizations that can be possibly done on bundler level.

• Untyped:

  The exported map object from .map.ts file has a type of unknown, it is only typed when using it with Source API loader.

  This avoided the complexity to auto-generate types, but I wanted to make it typed and usable without Source API.

The Solution Copy Section

Taking some references from Content Collections and Velite, I found it would be great to have a config file for Fumadocs MDX.

`source.config.ts`

We can make the syntax similar to Content Collections and other tools, to make the adoption process easier.
To define a collection:

import { z } from 'zod';

export const blog = defineCollections({
  dir: './blog',
  schema: z.object({
    // the schema
  }),
  mdxOptions: {
    // remark plugins?
  },
});

The MDX loader reads the config file, find the corresponding collection of the file, validate, and compile it using the options from collection.

This allows us to pass MDX options normally without breaking Turbopack's rules.

The Implementation Copy Section

As the config file is written in TypeScript, we will need a bundler to read it.
I used esbuild, it is a performant bundler written in Go.

After bundling the config file, a dynamic import will work as expected.

await import('./source.compiled.mjs');

`.map` file

We need a place to import the compiled collections.
Previously, we simply generate a .map.ts file with Webpack plugins.
It declares the types, with no actual data.

export declare const map: unknown;

A loader will be used to transform .map.ts file into the output aforementioned:

export const map = {
  'docs/index.mdx': import('./docs/index.mdx'),
  'docs/guide.mdx': import('./docs/guide.mdx'),
};

The generated .map.ts never changes because it doesn't depend on the config file.
No matter how you configure it, there'll be only a map object exported, with a type of unknown.

Now, we need to generate types for every collection, and the types may change as we change the collections.
The previous approach is no longer applicable.

I renamed the .map.ts file to .source/index, both index.d.ts and index.js are generated by Fumadocs MDX, instead of using a loader.

A map file generator is implemented, it reads the config file and generate output based on exported collections.

Auto-reload

We want to watch for changes:

• When a input file added/removed, add or remove relevant entries from the .source/index.js file.
• When the config file changed, re-compile affected files, and update generate types at .source/index.d.ts.

I chose chokidar to watch file changes, it worked well.
The file watcher lives on next.config.mjs, it's independent to the MDX loader.

To notify bundlers when config files changed, we added a hash.

export const collection1 = [import('./docs/index.mdx?hash=hashOfConfigFile')];

The file will be re-compiled as the config hash changes.

To optimize performance, we also added the collection name.

export const collection1 = [
  import('./docs/index.mdx?hash=hashOfConfigFile&collection=collection1'),
];

The loader obtains the collection of input file from resource query, without taking extra steps to detect its associated collection.

Result Copy Section

A .source/index file will be generated, it is fully typed.
The files will be re-compiled as you modify the config file.

• Turbopack supported, we have a small example in the repo using Turbopack.
• Multiple Collections, with its own MDX options.
• Runtime + Build-time validation & transformation.

Questions Copy Section

I think there is still room for improvement:

• Use a Turbopack-native thing to bundle the config file?
• Lazy bundle/import the main body of MDX file?

Please give me feedback about the redesign of Fumadocs MDX ;)

Apps Docs Content Blog Mdx V13 (`apps/docs/content/blog/mdx-v13.mdx`) Copy Section

title: Fumadocs MDX v13 authors: [fuma] tags: [Release, Fumadocs MDX] date: 2025-10-23 Copy Chapter

Overview Copy Chapter

Fumadocs MDX refined its API surface for better cross-framework compatibility and flexibility.

Plugins API Copy Section

We introduced Plugins API, enabling extensible modifications to MDX configurations without bundler-specific code—ideal for file generation (e.g., types, indexes) or config alterations.

There's a json-schema plugin natively provided by Fumadocs MDX.

import jsonSchema from 'fumadocs-mdx/plugins/json-schema';
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
});

export default defineConfig({
  plugins: [jsonSchema()],
});

Migration Copy Chapter

Next.js Copy Section

createMDXSource and resolveFiles are now relocated to fumadocs-mdx/runtime/next.

This should not affect majority of projects, as docs.toFumadocsSource() is now the preferred way.

Vite Copy Section

The source.generated.ts file is now moved to .source/index.ts, you are recommended to import the .source folder (with a path alias).

{
  "compilerOptions": {
    "paths": {
      // [!code ++]
      "@/.source": [".source"]
    }
  }
}

Migrate:

• run dev server/typegen to generate a .source folder.

• import it over the original source.generated.ts.

• note that both docs and create-fumadocs-app are updated to .source folder.

We also supported index file generation targeting other runtimes like Bun/Node.js.

import { defineConfig } from 'vite';
import mdx from 'fumadocs-mdx/vite';
import * as MdxConfig from './source.config';

export default defineConfig({
  plugins: [
    mdx(MdxConfig, {
      generateIndexFile: {
        runtime: 'node',
      },
    }),
    // ...
  ],
});

Bug Fixes Copy Section

• remark-include: fix Markdown stringify logics.
• postprocess.includeMDAST support.
• (Vite) support useContent on client loader for lint avoidance.

Apps Docs Content Blog Mdx V14 (`apps/docs/content/blog/mdx-v14.mdx`) Copy Section

title: Fumadocs MDX 14 authors: [fuma] tags: [Release, Fumadocs MDX] date: 2025-11-16 Copy Chapter

We are pleased to announce Fumadocs MDX 14. This update introduces several major enhancements designed to:

• Improve flexibility, taking the plugin approach further.
• Improve performance & memory consumption.
• Improve browser/dynamic compilation support.

New Model Copy Chapter

The output is now separated into:

• .source/server: the content data available for server (e.g. RSC, SSR), should not be referenced in client code.
• .source/browser: the data available for browser, with built-in serialization, chunking and loader layer.
• .source/dynamic: interface for dynamic content compilation, only generated for collections with dynamic: true.

Breaking Changes Copy Chapter

Entry Files Copy Section

Fumadocs MDX now generates multiple entry files in .source folder.

To migrate, add/update the path aliases in tsconfig.json for new entry files.

{
  "compilerOptions": {
    "paths": {
      // [!code ++]
      "collections/*": ["./.source/*"]
    }
  }
}

Import your collections from the entry files instead of @/.source:

// [!code --]
import { docs } from '@/.source';
// [!code ++]
import { docs } from 'collections/server';

// access collections on server-side, e.g.
import { loader } from 'fumadocs-core/source';

export const source = loader({
  source: docs.toFumadocsSource(),
});

// non-RSC environment (e.g. browser)
// [!code --:20]
import { docs } from '@/.source';

const clientLoader = createClientLoader(docs.doc, {
  id: 'docs',
  component({ toc, frontmatter, default: MDX }) {
    return (
      <DocsPage toc={toc}>
        <DocsTitle>{frontmatter.title}</DocsTitle>
        <DocsDescription>{frontmatter.description}</DocsDescription>
        <DocsBody>
          <MDX
            components={{
              ...defaultMdxComponents,
            }}
          />
        </DocsBody>
      </DocsPage>
    );
  },
});

// [!code ++:20]
import browserCollections from 'collections/browser';

const clientLoader = browserCollections.docs.createClientLoader({
  component({ frontmatter, default: MDX }) {
    return (
      <DocsPage toc={toc}>
        <DocsTitle>{frontmatter.title}</DocsTitle>
        <DocsDescription>{frontmatter.description}</DocsDescription>
        <DocsBody>
          <MDX
            components={{
              ...defaultMdxComponents,
            }}
          />
        </DocsBody>
      </DocsPage>
    );
  },
});

Fumadocs Adapter Copy Section

The adapter for loader() API is also changed.

For docs collection, create.sourceAsync() (Vite) is now consistent with Next.js:

import { docs } from 'collections/server';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/docs',
  // [!code --]
  source: await create.sourceAsync(docs.doc, docs.meta),
  // [!code ++]
  source: docs.toFumadocsSource(),
});

For doc collections, createMDXSource() (Next.js) is renamed to toFumadocsSource().

If you use create.sourceAsync() (Vite) for doc collections, you should also switch to toFumadocsSource().

import { blogPosts } from 'collections/server';
import { toFumadocsSource } from 'fumadocs-mdx/runtime/server';
import { loader } from 'fumadocs-core/source';

export const blog = loader({
  baseUrl: '/blog',
  // [!code --] for Next.js
  source: createMDXSource(blogPosts, []),
  // [!code --] for Vite
  source: await create.sourceAsync(blogPosts, []),
  // [!code ++]
  source: toFumadocsSource(blogPosts, []),
});

Async & Dynamic Mode Copy Section

On Next.js, Async Mode now aligns with the behaviour on Vite to generate async imports. This enables server-side chunking to improve memory usage.

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    // This no longer forces dynamic compilation! [!code ++]
    async: true,
  },
});

Instead, we introduced a dynamic option to enable dynamic compilation. This is available for both Vite and Next.js.

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    // [!code ++]
    dynamic: true,
  },
});

By enabling Async or Dynamic modes, the relevant collections are considered lazy-loaded, offering a load() function to load compiled properties.

Updated Signature for `postInstall()` Copy Section

It now accepts the framework plugin options, you can customize more properties:

import { postInstall } from 'fumadocs-mdx/next';
// or
import { postInstall } from 'fumadocs-mdx/vite';

postInstall('source.config.ts');

import { postInstall } from 'fumadocs-mdx/next';
// or
import { postInstall } from 'fumadocs-mdx/vite';

postInstall({ configPath: 'source.config.ts' });

`getDefaultMDXOptions()` -> `applyMdxPreset()` Copy Section

To support a broader range of presets and accommodate dynamic modes, getDefaultMDXOptions() has been renamed to applyMdxPreset().

import { defineCollections, getDefaultMDXOptions } from 'fumadocs-mdx/config';
import { myPlugin } from './remark-plugin';

export const blog = defineCollections({
  type: 'doc',
  mdxOptions: getDefaultMDXOptions({
    remarkPlugins: [myPlugin],
    // Alternatively, use a function to customize plugin order:
    remarkPlugins: (v) => [myPlugin, ...v],
  }),
});

import { defineCollections, applyMdxPreset } from 'fumadocs-mdx/config';
import { myPlugin } from './remark-plugin';

export const blog = defineCollections({
  type: 'doc',
  mdxOptions: applyMdxPreset({
    remarkPlugins: [myPlugin],
    // Alternatively, use a function to customize plugin order:
    remarkPlugins: (v) => [myPlugin, ...v],
  }),
});

Introduction of `lastModified` Plugin Copy Section

The lastModifiedTime option has been replaced by a dedicated lastModified plugin.

This shift promotes a plugin-based architecture for better extensibility.

import { defineConfig } from 'fumadocs-mdx/config';
import lastModified from 'fumadocs-mdx/plugins/last-modified';

export default defineConfig({
  // [!code ++]
  plugins: [lastModified()],
});

Removal of Multiple `dir` Support Copy Section

Support for specifying multiple directories in a single collection has been discontinued. Instead, utilize the files property to filter and include specific files.

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/guides',
  docs: {
    files: ['./i-love-fumadocs/**/*.{md,mdx}'],
  },
});

Disabling Default Generation of `extractedReferences` Copy Section

The automatic generation of extractedReferences is no longer enabled by default. To retain this functionality, explicitly activate it via the postprocess option.

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    postprocess: {
      // [!code ++]
      extractLinkReferences: true,
    },
  },
});

Vite: `generateIndexFile` -> `index` Copy Section

The generateIndexFile option of our Vite plugin has been renamed to index.

import { defineConfig } from 'vite';
import mdx from 'fumadocs-mdx/vite';
import * as MdxConfig from './source.config';

export default defineConfig({
  plugins: [
    mdx(MdxConfig, {
      index: {
        // options
      },
    }),
  ],
});

Patch Changes Copy Chapter

• Resolved an issue with meta file validation when using Bun.
• Introduced optimizations to reduce unnecessary entry files re-generations.

Thank you for your continued support of Fumadocs. If you encounter any issues during the update, welcome to reach out through our GitHub Discussions.

Apps Docs Content Blog Mdx V15 (`apps/docs/content/blog/mdx-v15.mdx`) Copy Section

title: Fumadocs MDX 15 authors: [fuma] tags: [Release, Fumadocs MDX] date: 2026-05-07 Copy Chapter

Overview Copy Chapter

This is a boring major release mainly to reduce package size. Breaking changes:

• fumadocs-core must be 16.7.0 or above.
• next.config must be ESM.

For Next.js users, if you encounter any error when upgrading, it could be due to ESM compatibility issues, you might be accidentally using CommonJS in next.config.
Consider to rename your config to next.config.mjs or next.config.mts.

If you prefer to use ESM in your entire project, set this in your package.json:

{
  "name": "my-app",
  // [!code ++]
  "type": "module"
}

For other unexpected breakages, please open a bug report on our GitHub repository.

Apps Docs Content Blog New Conventions (`apps/docs/content/blog/new-conventions.mdx`) Copy Section

title: Adding new Conventions date: 2025-04-08 authors: [fuma] Copy Chapter

`mdx-component.tsx` Copy Chapter

Sometimes there are questions raised by beginners confused about where to add MDX components.
Although it's simply located in page.tsx, which shouldn't be difficult to find, I think some kind of conventions may help, so I decided to add back mdx-components.tsx.

I love to have fewer files, but considering create-fumadocs-app should also act as a starting point for beginners who may not be familiar with MDX, it's much more helpful to provide it by default.

Existing Projects Copy Section

The convention is optional (only to make the learning curve smoother).
For existing users, you probably knew how to pass MDX components, and no further change is needed.

But you can still make one:

import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    ...components,
  };
}

And use it in your MDX component.

import { getMDXComponents } from '@/mdx-components';

<MDXContent
  components={getMDXComponents({
    // extend it
  })}
/>;

Deprecating `` Copy Chapter

We now prefer a single <RootProvider /> for everything, replacing the need for `` with a i18n prop.

<RootProvider
  i18n={
    // i18n provider props
  }
>
  {children}
</RootProvider>

This allows Root Provider to handle the hierarchy correctly without revealing too much complexity, for example, the correct order should be:

<FrameworkProvider>
  <ThemesProvider>
    <I18nProvider>
      <SidebarProvider>
        <SearchProvider>{children}</SearchProvider>
      </SidebarProvider>
    </I18nProvider>
  </ThemesProvider>
</FrameworkProvider>

Changing the hierarchy of different providers may result in problems since they actually rely on each other, now it is all integrated into <RootProvider />, including I18n configuration.

The new Internationalization guide requires Fumadocs 15.2.3 or above.

Apps Docs Content Blog Openapi V10 (`apps/docs/content/blog/openapi-v10.mdx`) Copy Section

title: Fumadocs OpenAPI v10 authors: [fuma] tags: [Release, Fumadocs OpenAPI] date: 2025-11-06 Copy Chapter

We are pleased to announce the release of Fumadocs OpenAPI v10.
This major release focuses on enhancing customization capabilities and simplifying API surfaces, it is also an opportunity to drop older/deprecated APIs.

We have introduced multiple breaking changes that require attention during upgrades.

Breaking Changes Copy Chapter

Redesign of `createOpenAPI` Usage Copy Section

This redesign separates API page and server concerns, removes disablePlayground option in favor of playground.enabled, introduces client configuration support, and prefers client configs for adapters.

1. Isolation of API Page and Server:

   Previously, all options are located in createOpenAPI().

   ts title="lib/openapi.ts" Copy

   import { createOpenAPI } from 'fumadocs-openapi/server';
   import path from 'node:path';
   
   export const openapi = createOpenAPI({
     input: [path.resolve('./scalar.yaml')],
     proxyUrl: '/api/proxy',
     mediaAdapters: {/* adapters */},
     shikiOptions: {/* options */},
   });

   Now, you need to separate API page components and the server declaration.

   ts tab="lib/openapi.ts" Copy

   import { createOpenAPI } from 'fumadocs-openapi/server';
   import path from 'node:path';
   
   export const openapi = createOpenAPI({
     input: [path.resolve('./scalar.yaml')],
     proxyUrl: '/api/proxy',
   });

   ts tab="components/api-page.tsx" Copy

   import { openapi } from '@/lib/openapi';
   import { createAPIPage } from 'fumadocs-openapi/ui';
   
   export const APIPage = createAPIPage(openapi, {
     mediaAdapters: {/* adapters */},
     shikiOptions: {/* options */},
   });

2. More Options for Playground:
   Use playground.enabled instead of disablePlayground.

   typescript title="components/api-page.tsx" Copy

   export const APIPage = createAPIPage(openapi, {
     playground: {
       enabled: false,
     },
   });

3. Client Configuration Support:

   The options are now split into server/client configs, some options are moved to the client-side config,

   typescript tab="components/api-page.tsx" Copy

   import client from './api-page.client';
   
   export const APIPage = createAPIPage(openapi, {
     client,
   });

   typescript tab="components/api-page.client.tsx" Copy

   'use client';
   import { defineClientConfig } from 'fumadocs-openapi/ui/client';
   
   export default defineClientConfig({
     playground: {
       transformAuthInputs: (inputs) => [/* modified inputs */],
     },
   });

4. Client-Side Media Adapters:
   Also forward your media adapters via client config.

   typescript title="components/api-page.client.tsx" Copy

   'use client';
   import { defineClientConfig } from 'fumadocs-openapi/ui/client';
   import { adapters } from './my-media-adapters';
   
   export default defineClientConfig({
     mediaAdapters: adapters,
   });

Renaming Options Copy Section

The option content.showExampleInFields has been renamed to schemaUI.showExample.

Removal of Centralized `renderer` and `fields` APIs Copy Section

Fumadocs OpenAPI now prefers per-feature customizations, eliminating the centralized renderer API. Custom render functions are now specified directly in the content option when creating an API page.

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';

export const APIPage = createAPIPage(openapi, {
  content: {
    renderResponseTabs,
    renderAPIExampleLayout,
    renderAPIExampleUsageTabs,
  },
});

For migrating Playground fields options, utilize client-side render APIs:

'use client';
import { defineClientConfig } from 'fumadocs-openapi/ui/client';

export default defineClientConfig({
  playground: {
    renderParameterField: (fieldName, field) => {
      /* custom implementation */
    },
  },
});

Additional layout customizations are available:

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';

export const APIPage = createAPIPage(openapi, {
  content: {
    renderResponseTabs: (tabs) => <div>{/* custom tabs */}</div>,
    renderAPIExampleLayout: ({ selector, usageTabs, responseTabs }) => (
      <div>{/* custom layout */}</div>
    ),
    renderAPIExampleUsageTabs: (generators) => <div>{/* custom tabs */}</div>,
    renderPageLayout: ({ operations, webhooks }) => <div>{/* custom page */}</div>,
    renderOperationLayout: (slots) => <div>{/* custom operation */}</div>,
    renderWebhookLayout: ({ header, authSchemes, parameters, body, responses, callbacks }) => (
      <div>{/* custom webhook */}</div>
    ),
  },
});

`generateFiles()` Requires OpenAPI Server Copy Section

File generation is now handled within the OpenAPI server. The input field for generateFiles must reference the server instance rather than a string array of file paths.

import { openapi } from '@/lib/openapi';
void generateFiles({
  input: ['./products.yaml'],
  output: './content/docs',
});

import { generateFiles } from 'fumadocs-openapi';
import { openapi } from '@/lib/openapi';

void generateFiles({
  input: openapi,
  output: './content/docs',
});

New Features Copy Chapter

Storage Key Prefix Copy Section

v10 introduced the storageKeyPrefix option to prevent state bleed across multiple OpenAPI instances by isolating localStorage keys.

'use client';
import { defineClientConfig } from 'fumadocs-openapi/ui/client';

export default defineClientConfig({
  storageKeyPrefix: 'fumadocs-openapi-custom-',
});

Bug Fixes Copy Chapter

• TypeScript Schema Output Correction: Resolved incorrect TypeScript schema generation. Code formatting is disabled in this process to enhance performance.

We recommend reviewing your implementation against these changes to leverage the improved flexibility and performance.
If you encounter issues, welcome to contribute feedback to our GitHub repository.

Apps Docs Content Blog Openapi V11 (`apps/docs/content/blog/openapi-v11.mdx`) Copy Section

title: Fumadocs OpenAPI v11 authors: [fuma] tags: [Release, Fumadocs OpenAPI] date: 2026-06-11 Copy Chapter

We are pleased to announce the release of Fumadocs OpenAPI v11.
This major release unifies the RSC and client APIs, removes deprecated options accumulated since v10, and simplifies the server surface.

This release requires attention during upgrades. Run a type check after migrating:

npm run types:check

Unify RSC & Client APIs Copy Chapter

createAPIPage() and createClientAPIPage() are replaced by a single createOpenAPIPage() API. The component no longer accepts an OpenAPIServer instance or a separate client config, all options live in one client component.

The fumadocs-openapi/ui/client subpath export is removed. Merge any defineClientConfig() options into createOpenAPIPage() directly.

import { openapi } from '@/lib/openapi';
import { createAPIPage } from 'fumadocs-openapi/ui';
import client from './api-page.client';

export const APIPage = createAPIPage(openapi, {
  client,
  mediaAdapters: {/* ... */},
});

'use client';
import { defineClientConfig } from 'fumadocs-openapi/ui/client';

export default defineClientConfig({
  playground: {
    transformAuthInputs: (inputs) => inputs,
  },
  storageKeyPrefix: 'my-openapi-',
});

'use client';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';

export const OpenAPIPage = createOpenAPIPage({
  mediaAdapters: {/* ... */},
  playground: {
    transformAuthInputs: (inputs) => inputs,
  },
  storageKeyPrefix: 'my-openapi-',
});

api-page.tsx must be a client component. Note that for existing non-RSC usages, old APIs are only deprecated, migrating to the new createOpenAPIPage() is optional, and API surface is identical.

Pass Page Props from Server Copy Section

The server is responsible for passing OpenAPI data to <OpenAPIPage />.

<Tabs items={['Virtual Files', 'MDX Files']}>

import { OpenAPIPage } from '@/components/api-page';

export default function Page({ slug }) {
  const page = source.getPage(slug);

  if (page.type === 'openapi') {
    return (
      <DocsPage full>
        <DocsTitle>{page.data.title}</DocsTitle>
        <DocsBody>
          <OpenAPIPage {...page.data.getOpenAPIPageProps()} />
        </DocsBody>
      </DocsPage>
    );
  }

  // ...
}

import { openapi } from '@/lib/openapi';
import { OpenAPIPage } from '@/components/api-page';

export default async function Page({ slug }) {
  const page = source.getPage(slug);

  return (
    <MdxContent
      components={getMDXComponents({
        OpenAPIPage: async (props) => (
          <OpenAPIPage {...await openapi.preloadOpenAPIPage(page)} {...props} />
        ),
      })}
    />
  );
}

Server & Loader Copy Chapter

`getSchema()` Return Value Copy Section

getSchema() on virtual pages and the OpenAPI server no longer includes a dereferenced document. It now returns the bundled schema only.

const schema = page.data.getSchema();

// dereferenced paths, components, etc.
schema.dereferenced.paths;

const schema = page.data.getSchema();

// bundled (non-dereferenced) document
schema.bundled;

Dereferencing happens at render time inside <OpenAPIPage /> for better performance.

`input` Option Copy Section

The whole-map factory form of input is removed. Use a record instead: each value can be a file path, URL, inline document, or a per-entry async function.

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  input: async () => {
    const res = await fetch('https://example.com/openapi.json');
    return {
      my_api: await res.json(),
    };
  },
});

import { createOpenAPI } from 'fumadocs-openapi/server';

export const openapi = createOpenAPI({
  input: {
    my_api: async () => {
      const res = await fetch('https://example.com/openapi.json');
      return res.json();
    },
  },
});

Customization Callbacks Copy Chapter

Several callbacks now receive richer context about the current operation.

`generateCodeSamples` Copy Section

import { createCodeSample } from 'fumadocs-openapi/server';

export const OpenAPIPage = createOpenAPIPage({
  generateCodeSamples: (method) => [
    createCodeSample({
      label: 'Custom',
      lang: 'js',
      generate(data) {
        return `fetch('${data.url}')`;
      },
    }),
  ],
});

export const OpenAPIPage = createOpenAPIPage({
  generateCodeSamples: ({ operation, method, pathItem }) => [
    {
      label: 'Custom',
      lang: 'js',
      generate(data) {
        return `fetch('${data.url}')`;
      },
    },
  ],
});

`renderOperationLayout` Copy Section

export const OpenAPIPage = createOpenAPIPage({
  content: {
    renderOperationLayout: (slots, ctx, method) => <div>{slots.header}</div>,
  },
});

export const OpenAPIPage = createOpenAPIPage({
  content: {
    renderOperationLayout: (slots, { operation, method, pathItem, ctx }) => (
      <div>{slots.header}</div>
    ),
  },
});

`playground.render` Copy Section

export const OpenAPIPage = createOpenAPIPage({
  playground: {
    render: (method) => <MyPlayground method={method} />,
  },
});

export const OpenAPIPage = createOpenAPIPage({
  playground: {
    render: ({ operation, method, pathItem, path, ctx }) => (
      <MyPlayground operation={operation} method={method} path={path} />
    ),
  },
});

Dropped Deprecated APIs Copy Chapter

The following APIs are removed in v11. Use the replacements listed below.

Loader Plugin Copy Section

import { transformerOpenAPI } from 'fumadocs-openapi/server';

export const source = loader({
  pageTree: {
    transformers: [transformerOpenAPI()],
  },
});

import { openapiPlugin } from 'fumadocs-openapi/server';

export const source = loader({
  plugins: [openapiPlugin()],
});

Proxy Server Copy Section

export const { GET, POST } = openapi.createProxy({
  allowedUrls: ['https://example.com'],
});

export const { GET, POST } = openapi.createProxy({
  allowedOrigins: ['https://example.com'],
});

Playground Request Timeout Copy Section

export const OpenAPIPage = createOpenAPIPage({
  playground: {
    requestTimeout: 30,
  },
});

export const OpenAPIPage = createOpenAPIPage({
  playground: {
    fetchOptions: {
      requestTimeout: 30,
    },
  },
});

TypeScript Definitions Copy Section

export const OpenAPIPage = createOpenAPIPage({
  generateTypeScriptSchema: async (method, statusCode, contentType, ctx) => {
    // ...
  },
});

export const OpenAPIPage = createOpenAPIPage({
  generateTypeScriptDefinitions: async (schema, ctx) => {
    // ...
  },
});

`generateFiles()` Context Copy Section

The documents field is removed from the beforeWrite and index.items callback context. Access schemas from the OpenAPI server instead.

void generateFiles({
  input: openapi,
  output: './content/docs',
  beforeWrite(files) {
    const doc = this.documents['petstore.yaml'];
    // ...
  },
});

void generateFiles({
  input: openapi,
  output: './content/docs',
  async beforeWrite(files) {
    const schemas = await openapi.getSchemas();
    const doc = schemas['petstore.yaml'];
    // ...
  },
});

Similarly, rename groupStyle to folderStyle when generating meta.json files:

void generateFiles({
  meta: {
    groupStyle: 'separator',
  },
});

void generateFiles({
  meta: {
    folderStyle: 'separator',
  },
});

Deprecated APIs Copy Chapter

The following APIs are deprecated but still available in v11, migration is recommended.

Virtual Files Copy Section

The data methods on page.data are unified into getOpenAPIPageProps().

Apps Docs Content Blog Openapi V12 (`apps/docs/content/blog/openapi-v12.mdx`) Copy Section

title: Fumadocs OpenAPI v12 authors: [fuma] tags: [Release, Fumadocs OpenAPI] date: 2026-09-20 Copy Chapter

We are pleased to announce the release of Fumadocs OpenAPI v12.

An API page used to be one component with a long list of render options. v12 splits it in two:

• a headless layer that owns the state and logic,
• the UI it renders through, which you can install and edit.

Options remain for the small tweaks, the rest is yours to replace.

Headless API Pages Copy Chapter

Everything outside fumadocs-openapi/ui renders nothing on its own.

createOpenAPIRenderer() takes your components and returns an <OpenAPIPage /> that accepts the props of generated pages:

'use client';
import { createOpenAPIRenderer } from 'fumadocs-openapi';
import { Operation } from '@/components/my-operation';
import { SchemaUI } from '@/components/my-schema';

export const OpenAPIPage = createOpenAPIRenderer({
  components: { Operation, SchemaUI },
});

Markdown, CodeBlock and Heading are filled in when you leave them out, so a custom UI starts from two components.

Under the page, hooks read its state:

See Headless for the full surface.

Install the UI Copy Chapter

The entire UI of API pages, built on that layer, installed with Fumadocs CLI:

npx @fumadocs/cli add openapi/page

Your components/api-page.tsx is no longer needed:

import { OpenAPIPage } from '@/components/api-page'; // [!code --]
import { OpenAPIPage } from '@/components/openapi/page'; // [!code ++]

Or take one part of it, and pass the rest through components:

'use client';
import { createOpenAPIPage } from 'fumadocs-openapi/ui';
import { Operation } from '@/components/openapi/operation';
import { Schema } from '@/components/api/schema';

export const OpenAPIPage = createOpenAPIPage({
  components: { Operation, SchemaUI: Schema },
});

What you install is UI, not a fork:

• the request pipeline of the playground stays in the package, an edited playground still drives the real one.
• Select and Input follow the Shadcn UI API, a project that already has them keeps its own.

`@fumadocs/json-schema` Copy Chapter

The JSON Schema utilities of API pages are their own package, with no Fumadocs dependencies:

import { dereference, matches, mergeAllOf, sample, stringify } from '@fumadocs/json-schema';
import { bundle } from '@fumadocs/json-schema/bundle';

• bundle() is a separate entry because it reads files and URLs, everything else runs in the browser.
• @fumadocs/json-schema/react turns a schema into the data an API page draws. generateSchemaUI() flattens it, so your UI walks a map from $root instead of recursing.
• @fumadocs/api-docs is no longer published, its UI is now bundled into the integrations or installed with the CLI.

Smaller Bundles Copy Chapter

createOpenAPIBaseRenderer() is the renderer with nothing built in, it bundles only what you pass:

createOpenAPIBaseRenderer({
  shiki,
  codeUsages: createCodeUsageGeneratorRegistry().register(curl),
  components: { Operation, SchemaUI },
});

createOpenAPIRenderer() and fumadocs-openapi/ui register the full Shiki bundle, every code usage generator and TypeScript definitions for you.

The package entry is client-safe too. generateFiles() reads and writes files, so it ships stubbed under the browser condition, and a client component importing the renderer no longer pulls node:fs into the bundle.

Migration Copy Chapter

Run a type check after upgrading:

npm run types:check

Options Copy Section

Render options that returned a component are components now:

createOpenAPIPage({
-  schemaUI: { render: (props) => <Schema {...props} /> },
-  renderHeading: (props, depth) => <Heading depth={depth} {...props} />,
-  renderCodeBlock: (props) => <CodeBlock {...props} />,
-  renderMarkdown: (md) => <Markdown md={md} />,
+  components: { SchemaUI: Schema, Heading, CodeBlock, Markdown },
 });

• playground.provider is removed, the page provides the auth state of the playground.

• playground.render and generateTypeScriptDefinitions no longer receive ctx. Read the document from useOpenAPI().doc, or the doc passed to generateTypeScriptDefinitions.

• operation.APIExampleSelector is removed, install openapi/operation and edit the selector in usage-tabs.tsx.

• `` reads the operation from useOperation(), its route, method, operation and pathItem props are gone:

  tsx Copy

  playground: {
    render: () => <PlaygroundClient writeOnly readOnly={false} />,
  }

• The ctx of content render options is the render options of the page, what useRenderContext() returns. ctx.schema, ctx.SchemaUI and ctx._default_processMarkdown are removed, read them from useOpenAPI().doc and useComponents().

Hooks Copy Section

The hooks of fumadocs-openapi/ui are replaced by the headless ones:

- const { route, examples, example, setExample, setExampleData } = useOperationContext();
+ const { path } = useOperation();
+ const { items, selected, select, update } = useExampleRequests();
+ // data of the selected example, replaces `addListener()`
+ const data = useExampleRequest();

useStorageKey() is removed, read the prefix from the page:

const { storageKeyPrefix } = useOpenAPI();
localStorage.getItem(`${storageKeyPrefix}my-key`);

Removed & Moved Copy Section

Also in v12 Copy Chapter

• Code samples from x-codeSamples and generateCodeSamples are rendered when their id isn't a built-in generator.
• SchemaData.infoTags entries are data the UI renders: { label, value, block? } or { label, list }. Custom nodes ({ node }) still work, code reading tag.node must handle all shapes.

Thanks for supporting Fumadocs, share your upgrade experience on GitHub :)

Apps Docs Content Blog Openapi V9 (`apps/docs/content/blog/openapi-v9.mdx`) Copy Section

title: Fumadocs OpenAPI v9 date: 2025-05-25 authors: [fuma] tags: [Release, Fumadocs OpenAPI] Copy Chapter

Overview Copy Chapter

This breaking change is mainly made to address problems of generateFiles() function.

Previously, it was a simple function to generate multiple MDX files/pages from your OpenAPI schema, same as every docs generator.
We tested it on public OpenAPI schemas such as Unkey, Vercel and examples from Scalar and Swagger's Museum schema.

Since these schemas were written for different docs solutions, or even their custom ones.
We made generateFiles() too complicated to be capable of producing best results for various schema styles, and it's even harder to customize the generated file paths of API docs.

This update also include:

• Better UI for schema & playground body input
• Improved type-safety for generateFiles()

Breaking Changes Copy Chapter

The algorithm for generating file paths is changed:

• meta.json will no longer be generated, add as your wanted.
• per: operation: The generated path will be identical to your operation id. If not defined, it takes your endpoint path instead.

Group By Copy Section

The behaviour of groupBy API is also changed.

Customize Output Copy Section

The usage of name option is renewed, it can be used to customize the output path of files.

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  name: (output, document) => {
    // page info
    console.log(output);
    // parsed OpenAPI schema
    console.log(document);
    return 'my-dir/filename';
  },
});

Migration Copy Chapter

You can start using the latest algorithm, or keep the current behaviour with:

import { generateFiles } from 'fumadocs-openapi';

void generateFiles({
  name: {
    algorithm: 'v1',
  },
});

Note that it won't create meta.json anymore even with algorithm set to v1, you can keep your current generated meta.json files.

Apps Docs Content Blog V12 After (`apps/docs/content/blog/v12-after.mdx`) Copy Section

title: Fumadocs 12.0.5 date: 2024-06-13 authors: [fuma] tags: [Release] Copy Chapter

Some Improvements Copy Chapter

After releasing Fumadocs 12, some improvements were made to the new UI.

TOC Popover Copy Section

Previously, this was only available on larger devices. Now, it's collapsed to a popover on smaller devices.

Links Menu Copy Section

To make the sidebar look even better, we moved navigation links to the links menu (the three-dots button at the top corner).

The recommended design is:

• Docs related links: Use <RootToggle /> or include it in page trees.
• Other links: Use the Links API of docs layout.

Breadcrumbs Copy Section

Removed the duplicated page name from breadcrumbs, now it only shows the folder names.
Also, you can enable includeSeparators to show separators on your breadcrumbs component.

The new breadcrumbs look cleaner and match the design even better.

Adaption Copy Chapter

Some docs sites such as https://yeecord.com and https://turbo.build have adopted the new UI, I'm very excited about it.
Removing the navbar seemed to be a very risky move to me, almost no documentation framework has done it, and I was expecting some complaints about the new design.

Luckily, most people are satisfied with the new UI.
The new design was originally inspired by Arc, their sidebar looked very impressive to me.
Although I soon discovered the docs site of Linear also doesn't have a navbar, Arc is still the first inspiration of the redesign.

I'm grateful that many people gave me their feedback about the new design, so that I can keep making Fumadocs a better framework to use.
Let's make better docs.

Apps Docs Content Blog V12 (`apps/docs/content/blog/v12.mdx`) Copy Section

title: Fumadocs 12 date: 2024-06-09 authors: [fuma] tags: [Release] Copy Chapter

What's New? Copy Chapter

Fumadocs v12 mainly aims to improve the UI, prioritizing content and reading experience.

New UI Copy Section

After observing large docs sites like https://turbo.build, I found that the navbar took too much space on the screen, while it only contains links to Blog, Showcase, GitHub, etc.
They are not necessarily related to the docs, placing them at the top of our screen doesn't bring a better reading experience.

All these links are now moved to the sidebar, allowing a clean, minimal view of the docs.

I also noticed the docs start to look messy as your content grows. To ameliorate this, the sidebar now includes a border and background by default.
This helps readers to distinguish navigation elements and content easier.

The sidebar will always be placed at the left of the screen, having a bigger space on large viewports.

I believe the new UI still has room for improvement. Welcome to report UI issues, or leave feedback!

Better Multi Page Trees Copy Section

We supported multiple page trees at a very early version of Fumadocs. However, it lacks proper explanations and guides to configure it.
In the past, you needed to implement a navigation element to switch between page trees and mark the folder as a root folder.

Now, you can use the <RootToggle /> component directly, and the docs has a better explanation of it.

Page Tree Post Processors Copy Section

You can now attach properties to page trees easily with the Source API.

import { loader } from 'fumadocs-core/source';

export const utils = loader({
  pageTree: {
    attachFile(node) {
      // modify the node
      return node;
    },
  },
});

Improved i18n Support Copy Section

The language switch is now added to Docs Layout.

import { DocsLayout } from 'fumadocs-ui/layouts/docs';

export default function Layout({ children }: { children: React.ReactNode }) {
  return <DocsLayout i18n>{children}</DocsLayout>;
}

Note that <LanguageSelect /> component is now replaced by <LanguageToggle />, make sure to remove references to the old component.

Breaking Copy Chapter

UI Copy Section

Remove deprecated option enableThemeProvider from Root Provider. Use theme.enabled instead.

Core Copy Section

Remove deprecated option minWidth from Sidebar component. Use blockScrollingWidth instead

Fixes Copy Chapter

UI Copy Section

• Fix problems with twoslash codeblocks
• Apply typography styles to headings
• Support translation for theme label

OpenAPI Copy Section

• Fix nullable types cannot be detected

Core Copy Section

• Remark Headings: Support code syntax in headings

Create Fumadocs App Copy Section

• Add layout.config.tsx file for sharing layout options

Apps Docs Content Blog V13 (`apps/docs/content/blog/v13.mdx`) Copy Section

title: Fumadocs v13 authors: [fuma] tags: [Release] date: 2024-07-28 Copy Chapter

Introduction Copy Chapter

Fumadocs v13 has been released. It aims to fix the CSS pollution problem and remove deprecated APIs.

New Features Copy Chapter

Better Code Blocks Copy Section

Now supports keeping the original background generated by Shiki on CodeBlock component.

import { Pre, CodeBlock } from 'fumadocs-ui/components/codeblock';

<MDX
  components={{
    pre: ({ ref: _ref, ...props }) => (
      <CodeBlock keepBackground {...props}>
        <Pre>{props.children}</Pre>
      </CodeBlock>
    ),
  }}
/>;

Callout Copy Section

Callout is now a default MDX component, you can use it in MDX files without an import, or manually adding it to MDX components.

<Callout type="warn">Hello World</Callout>

New Headless TOC Copy Section

The headless component of Table of Contents (TOC) now has a separate scroll container provider.

import * as Base from 'fumadocs-core/toc';

return (
  <Base.AnchorProvider>
    <Base.ScrollProvider>
      <Base.TOCItem />
      <Base.TOCItem />
    </Base.ScrollProvider>
  </Base.AnchorProvider>
);

The anchor provider can be placed anywhere.

Opt-out of Container Copy Section

Now supports disabling the default container styles of Tailwind CSS added by Fumadocs UI.

import { createPreset } from 'fumadocs-ui/tailwind-plugin';

/** @type {import('tailwindcss').Config} */
export default {
  presets: [
    createPreset({
      modifyContainer: false,
    }),
  ],
};

Admonition Syntax Copy Section

In Docusaurus, there's an Admonition syntax.

For people migrating from Docusaurus, you can enable the new remark plugin to support the Admonition syntax.

See Remark Admonition.

Breaking Changes Copy Chapter

Prefix to colors, animations, and utilities Copy Section

Previously, the Tailwind CSS plugin of Fumadocs UI added colors (including primary, secondary) which conflicted with Shadcn UI and other design systems.
A fd- prefix is added to them to allow the flexibility to have a separated design system on docs.

To use the Fumadocs UI colors on your primary app, enable the addGlobalColors option.

import { createPreset } from 'fumadocs-ui/tailwind-plugin';

/** @type {import('tailwindcss').Config} */
export default {
  presets: [
    createPreset({
      addGlobalColors: true,
    }),
  ],
};

This adds the colors without the fd- prefix.

Or you can just reference them with the fd- prefix, like bg-fd-background.

Tailwind CSS Plugin ESM-only Copy Section

Since Tailwind CSS supports TypeScript configuration, it makes sense to migrate the entire plugin to ESM.

Use ESM syntax in your configuration.

import { createPreset } from 'fumadocs-ui/tailwind-plugin';

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './app/**/*.{ts,tsx}',
    // others
  ],
  presets: [createPreset()],
};

Remove `RollButton` component Copy Section

RollButton was introduced because there were no "Table Of Contents" on mobile viewports.
Now users can use the TOC Popover to switch between headings, it is no longer a suitable design for Fumadocs UI.

You may copy the last implementation of RollButton.

Better i18n Copy Section

Now the I18nProvider component requires the locale prop instead of parsing it from pathname.
This fixed some bugs with the I18n middleware.

We also changed the usage of translations to reduce extra translations loaded on the client side.
You have to pass the active translations directly.

locales is passed as the available options on the Language Select component.

import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';
import { I18nProvider } from 'fumadocs-ui/i18n';

export default function Layout({
  params: { lang },
  children,
}: {
  params: { lang: string };
  children: ReactNode;
}) {
  return (
    <html lang={lang}>
      <body>
        <I18nProvider
          locale={lang}
          // options
          locales={[
            {
              name: 'English',
              locale: 'en',
            },
            {
              name: 'Chinese',
              locale: 'cn',
            },
          ]}
          // translations
          translations={
            {
              cn: {
                toc: '目錄',
              },
            }[lang]
          }
        >
          <RootProvider>{children}</RootProvider>
        </I18nProvider>
      </body>
    </html>
  );
}

Code Block Usage Copy Section

The previous usage was confusing, some props are passed directly to pre while some are not.

With v13, pass all props to the CodeBlock component.
This also includes class names, you may change your custom styles if necessary.

import { Pre, CodeBlock } from 'fumadocs-ui/components/codeblock';

<MDX
  components={{
    // HTML `ref` attribute conflicts with `forwardRef`
    pre: ({ ref: _ref, ...props }) => (
      <CodeBlock {...props}>
        <Pre>{props.children}</Pre>
      </CodeBlock>
    ),
  }}
/>;

Remove Deprecated APIs Copy Section

• Remove deprecated fumadocs-ui/components/api components.
• Replace secondary link items with icon link items.
• Rename id prop on Tabs component to groupId.

Bug Fixes Copy Chapter

UI Copy Section

• Fixed empty folder animation problems caused by Radix UI.

Apps Docs Content Blog V14 (`apps/docs/content/blog/v14.mdx`) Copy Section

title: Fumadocs v14 authors: [fuma] tags: [Release] date: 2024-09-19 Copy Chapter

Why? Copy Chapter

Taking some inspirations from Shadcn UI, I decided to make Fumadocs easier to use, with more APIs that simplify the design.

This is a large update.

New Features Copy Chapter

Fumadocs CLI Copy Section

Clone Fumadocs UI components to your workspace and modify them.

npm install @fumadocs/cli --save-dev

pnpm fumadocs add

See docs for details.

Sidebar Tabs Copy Section

Previously, multiple page tree is implemented with Fumadocs UI RootToggle component.
You have to add it to the sidebar banner which isn't as intuitive as other APIs.

With Sidebar Tabs, by creating a root folder, Fumadocs will immediately add a tabs component to the sidebar.

{
  "root": true,
  "title": "Tab Name",
  "description": "Some text about the tab",
  "icon": "IconName"
}

Orama Copy Section

We migrated the built-in search from Flexsearch to Orama, the same search engine that powers the Node.js docs site.
It is open source, and also have their Cloud integration.

No changes required.
You can use our new createFromSource API to create the route handler, which offers i18n support without any configurations.

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

export const { GET } = createFromSource(source);

In favour of this, the new search client of Fumadocs is introduced with support for different API clients.
This includes Algolia, Orama (static and dynamic with route handlers).

import { useDocsSearch } from 'fumadocs-core/search/client';
import { oramaStaticClient } from 'fumadocs-core/search/client/orama-static';

const client = useDocsSearch({
  client: oramaStaticClient(),
});

See Search API.

Static Search Copy Section

For sites with static export, you cannot use route handlers.
We now support client-side search using search indexes generated during build time.

See Static Search.

Less Dependencies Copy Section

I'm always working to reduce the dependencies required for Fumadocs, that is one reason why we separated Fumadocs into different packages.

Fumadocs UI now bundles icons from lucide-react, for Next.js apps that is not using Lucide, they can avoid downloading the entire icon library.

And swr is no longer used for search client, we implemented a light useQuery hook with extra care on React performance optimization.

New Metadata Image API Copy Section

To improve code organization, we made a Metadata Image API on Fumadocs Core.
It is a tiny wrapper over Next.js Metadata API, composes seamlessly with Source API.

import { createMetadataImage } from 'fumadocs-core/server';
import { source } from '@/lib/source';

export const metadataImage = createMetadataImage({
  imageRoute: '/docs-og',
  source,
});

import { generateOGImage } from 'fumadocs-ui/og';
import { metadataImage } from '@/lib/metadata';

export const GET = metadataImage.createAPI((page) => {
  return generateOGImage({
    title: page.data.title,
    description: page.data.description,
    site: 'My App',
  });
});

export function generateStaticParams() {
  return metadataImage.generateParams();
}

import { source } from '@/lib/source';
import { metadataImage } from '@/lib/metadata';
import { notFound } from 'next/navigation';

export function generateMetadata({ params }: { params: { slug?: string[] } }) {
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return metadataImage.withImage(page.slugs, {
    title: page.data.title,
    description: page.data.description,
  });
}

In favour of this, the getImageMeta function from fumadocs-ui/og has been removed.

Shorthands Copy Section

As you may notice, we introduced more abstractions to reduce the setup steps required for enabling some features.
It is also required for the code generator from Fumadocs CLI to work.

Like the generateParams function, it enables zero-configuration i18n support for Next.js generateStaticParams.

import { source } from '@/lib/source';

export function generateStaticParams() {
  return source.generateParams();
}

Better Card Component Copy Section

Fumadocs UI Card can now support usage without href.
You can pass children as React node, Typography styles will be applied correctly.

<Card icon={<Database />} title='Content Source'>

The input/source of your content, it can be a CMS, or local data layers like [Content Collections](https://www.content-collections.dev) and [Fumadocs MDX](/docs/mdx).

</Card>

Better Category Component Copy Section

The original DocsCategory component was copied from our official docs, which is a very simple implementation that doesn't take page tree into account.

Now it accepts the source object via from prop.

import { source } from '@/lib/source';
import { DocsCategory } from 'fumadocs-ui/page';

const page = source.getPage(params.slug);

<DocsCategory page={page} from={source} />;

By default, it takes the locale property from page to find the corresponding page tree to traverse.
You can also force a page tree.

import { source } from '@/lib/source';
import { DocsCategory } from 'fumadocs-ui/page';

const page = source.getPage(params.slug, params.lang);

<DocsCategory page={page} from={source} tree={source.pageTree['en']} />;

OpenAPI Tag Display Name Copy Section

Change the display name with x-displayName.

tags:
  - name: test
    description: this is a tag.
    x-displayName: My Test Name

Better TypeScript Docs Automation Copy Section

The AutoTypeTable component now supports a type prop, you can use TypeScript inside the field:

<AutoTypeTable
  path="file.ts"
  name="B"
  type={`
import { ReactNode } from "react"
export type B = ReactNode | { world: string }
`}
/>

And code highlighting in typedoc is also supported with Shiki.

We highly recommend to use createTypeTable instead of importing the component in MDX files, this allows a single instance of TypeScript Compiler API to be shared.
See Auto Type Table.

Next.js 15 Copy Section

Fumadocs v14 is compatible with Next.js 15, supporting sync and async usages of dynamic APIs.

UI Improvements Copy Chapter

Navbar Links Copy Section

The navigation menu on Home layout is redesigned, with better animation and flexibility.

See the new API.

Link Styles Copy Section

You can escape Tailwind CSS Typography styles for the a tag with data-card attribute.

<a data-card="">
  No styles applied <code>But it does</code>
</a>

Disable Theme Switch Copy Section

You can disable the default theme switcher with disableThemeSwitch on layouts.

Breaking Changes Copy Chapter

Move `dir` option from `defineDocs` Copy Section

import { defineDocs } from 'fumadocs-mdx/config';

export const { docs, meta } = defineDocs({
  dir: 'my/content/dir', // define once
});

Refactor Imports Copy Section

Previous

import { DocsLayout } from 'fumadocs-ui/layout';
import { HomeLayout } from 'fumadocs-ui/home-layout';
import { HomeLayoutProps } from 'fumadocs-ui/home-layout';

New Import Path

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { HomeLayout } from 'fumadocs-ui/layouts/home';
import { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

Twoslash UI Copy Section

We moved Twoslash UI components to fumadocs-twoslash.
This isolates some logic from Fumadocs UI, allowing a better code organization.

Import the CSS styles and Popup component differently.

import 'fumadocs-twoslash/twoslash.css';

import { Popup } from 'fumadocs-twoslash/ui';

It requires Tailwind CSS.

Remove Deprecated APIs Copy Section

The previous createI18nSearchAPIExperimental is now renamed to createI18nSearchAPI.
It takes the i18n config instead of scattering the options everywhere.

The types from fumadocs-core/search/shared is moved to fumadocs-core/server.

Apps Docs Content Blog V15 2 (`apps/docs/content/blog/v15-2.mdx`) Copy Section

title: Fumadocs v15.2 date: 2025-03-28 authors: [fuma] tags: [Release] Copy Chapter

Overview Copy Chapter

Fumadocs 15.2 introduces a layer over fumadocs-core to extend support to other React frameworks, including React Router and Tanstack Start. Other frameworks can also be supported using the FrameworkProvider from fumadocs-core/framework/base.

Why? Copy Section

The main focus of Fumadocs is flexibility, I aim to support more frameworks as long as it doesn't change the fundamentals of Fumadocs, like the separation of core and UI package.

The React.js ecosystem is a joy to work with, porting Fumadocs to other frameworks isn't as difficult as I thought.
It's also my goal to make it work not only for Next.js devs, but also everyone in the ecosystem who is using a SSR-compatible React framework.

Breaking Changes Copy Section

This is a minor release, it shouldn't break any previous usages unless you're relying on the lower level APIs from fumadocs-core without fumadocs-ui.

Fumadocs Core now requires a FrameworkProvider. It's as simple as wrapping it with appropriate provider:

import { NextProvider } from 'fumadocs-core/framework/next';

export function Provider({ children }) {
  return <NextProvider>{children}</NextProvider>;
}

If you're using Fumadocs UI, there's no need to change. RootProvider included it by default, and allows you to provide your own framework with:

import { RootProvider } from 'fumadocs-ui/provider/base';

export function Provider({ children }) {
  // now it doesn't add the Next.js provider
  return <RootProvider>{children}</RootProvider>;
}

Please report issues if you find any public APIs are broken unexpectedly.

Compilation Time Copy Section

15.2 also included some small performance improvements to Fumadocs, the time taken for Turbopack to start dev server and compile its first docs page is about 2-3 seconds.

This change also potentially allows Fumadocs to run on Vite, production build of minimal React Router setup only takes around 4s on a Macbook.

Try it out Copy Chapter

Upgrade from your existing Next.js docs:

pnpm update -i -r

If you want to try the React Router example:

pnpm create fumadocs-app

Future Plans Copy Section

15.2 doesn't support Astro, and probably won't unless better React.js support is provided by Astro.

• transition:persist is needed for Fumadocs UI layouts, however this will also affect its children (e.g. MDX content), causing page content to be persisted even after navigation.
• React contexts cannot work across islands, this changes the usage of Fumadocs significantly and hence require a redesign of APIs.

Fumadocs will continue to be Next.js first, the docs won't be changed to generalize usages of other frameworks. Instead, a new docs site will be developed for other frameworks (planned).

Apps Docs Content Blog V15 (`apps/docs/content/blog/v15.mdx`) Copy Section

title: Fumadocs v15 authors: [fuma] tags: [Release] date: 2025-01-24 Copy Chapter

Overview Copy Chapter

The purpose of v15 is mainly to support Tailwind CSS v4.
Tailwind CSS v4 is a complete redesign of its API and internals, to fully adhere to the new CSS-first config style, a breaking change is required.

Fumadocs v15 has no other significant changes other than migrating the config to Tailwind CSS v4.

Breaking Changes Copy Chapter

Before making the switch, upgrade your site to Tailwind CSS v4 following their upgrade guide.
You can remove the unused tailwind.config.js file and fully rely on the new CSS-first config.

Add @import to the presets exported by Fumadocs UI, and include the fumadocs-ui package in the source.

@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';

/* relative to the CSS file, make sure it's correct for your app */
@source '../node_modules/fumadocs-ui/dist/**/*.js';

Since v15, you will no longer pass options in JavaScript to customize plugins.
Instead, you can use the new alternatives in Tailwind CSS v4.

`addGlobalColors: true` Copy Section

Forward the colors again:

@theme {
  --color-primary: var(--color-fd-primary);
  /* same for other colors */
}

CSS Variables Copy Section

Fumadocs no longer use --fd-<color> like --fd-primary: 0 0% 0% for colors, it directly defines and uses colors in @theme.
Instead of the previous format, it uses hsl():

@theme {
  --color-fd-primary: hsl(0, 0%, 100%);
}

Steps Copy Section

Previous Tailwind CSS utilities like steps & step are renamed to fd-steps and fd-step to avoid conflicts.

Typography Copy Section

Typography utilities including prose, prose-* modifiers will continue to work. Please report problems if they are no longer working or have unexpected change in behaviours.

Improvements Copy Chapter

v15 also includes some minor improvements to the UI and OpenAPI integration.

Code Block Tabs Copy Section

In the past, you needed to write the <Tabs /> manually when separating code blocks into tabs.

<Tabs items={["Tab 1", "Tab 2"]}>

```ts tab="Tab 1"
console.log('Hello World');
```

```ts tab="Tab 2"
console.log('Hello World');
```

</Tabs>

Now you can do:

```ts tab="Tab 1"
console.log('Hello World');
```

```ts tab="Tab 2"
console.log('Hello World');
```

Note that the previous usage still works for those who want to customize or pass props to the <Tabs /> component.

Reversed Items in `meta.json` Copy Section

The rest item ... in the pages property of meta.json now supports reversed order:

{
  "pages": ["z...a"]
}

OpenAPI Playground Copy Section

v15 improves the playground UI (inspired by the minimalism of Scalar), and brought Scalar API Client support to Fumadocs OpenAPI.

You can enable the Scalar API Client using useScalar option in createOpenAPI():

import { createOpenAPI } from 'fumadocs-openapi/server';
import { APIPlayground } from 'fumadocs-openapi/scalar';

export const openapi = createOpenAPI({
  renderer: {
    APIPlayground,
  },
});

And install & configure their @scalar/api-client-react:

@scalar/api-client-react

@import '@scalar/api-client-react/style.css' layer(base);

Future Plans Copy Chapter

This update should be a simple migration for most developers updating to Tailwind CSS v4.

In the future, we also want to make further improvements to Fumadocs MDX:

• remove transform API - you can easily do the same with .map() on runtime like:

import { blog } from "@/.source"

export const updatedBlog = blog.map(...)

• remove Manifest API - it was designed to export search indexes, but now it's recommended to implement using route handlers.

• Mention more about our MDX Remote package, it will be the primary solution to handle large docs sites with performance needs that bundlers couldn't do, including lazy compilation of MDX files.

Apps Docs Content Blog V16 17 (`apps/docs/content/blog/v16-17.mdx`) Copy Section

title: Fumadocs 16.17 authors: [fuma] tags: [Release] date: 2026-10-09 ogImage: /blog/v16-17.png Copy Chapter

import { MarkdownLayer } from './v16-17/layer';
import { Pipeline } from './v16-17/pipeline';
import { RenderToMarkdown } from './v16-17/render';
import { TableRecords } from './v16-17/search';
import { PerfChart } from './v16-17/perf';

We are pleased to announce the release of Fumadocs 16.17.

This release rethinks how Fumadocs turns your pages into Markdown, and builds on top of it:

• A new stringification pipeline: Markdown that gives humans and agents the right context.
• Better search: records that keep the structure of your content.
• Better performance: Markdown and search records are generated over 10x faster.

The Markdown Form of a Page Copy Chapter

A page is read in more places than a browser. Agents fetch its Markdown from .md routes, llms.txt and MCP servers, readers copy it into ChatGPT, and your search indexes it.

## Installation

```npm
npm i fumadocs-core
```



<auto-type-table path="./props.ts" name="Options" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>

  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm i fumadocs-core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add fumadocs-core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add fumadocs-core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add fumadocs-core
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<img alt="Preview" src="__img0" />

<TypeTable
  id="type-table-props.ts-Options"
  type="{
  &#x22;id&#x22;: &#x22;props.ts-Options&#x22;,
  &#x22;name&#x22;: &#x22;Options&#x22;,
  &#x22;description&#x22;: &#x22;&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;dir&#x22;,
      &#x22;description&#x22;: &#x22;The directory of pages.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;baseUrl&#x22;,
      &#x22;description&#x22;: &#x22;The base URL of pages.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;defaultValue&#x22;,
          &#x22;text&#x22;: &#x22;'/'&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

import { asMarkdown, md } from 'fumadocs-core/server';

export function Callout({ title, children }) {
  if (asMarkdown()) return md.linePrefix('> ')`**${title}**\n${children}`;

  return <div className="callout">...</div>;
}

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  docs: {
    postprocess: {
      includeProcessedMarkdown: { output: 'function' },
    },
  },
});

import { getMDXComponents } from '@/components/mdx';

const markdown = await page.data.getText('processed', {
  components: getMDXComponents(),
});

## Installation [#installation]

```npm
npm i fumadocs-core
```



### Options

| Prop       | Type     | Description                           |
| ---------- | -------- | ------------------------------------- |
| `dir`      | `string` | The directory of pages.               |
| `baseUrl?` | `string` | The base URL of pages. Default: `'/'` |

import type { Root } from 'mdast';
import type { VFile } from 'vfile';
import { visit } from 'unist-util-visit';
import { replaceSource } from 'fumadocs-core/mdx-plugins/stringifier';

export function remarkNote() {
  return (tree: Root, file: VFile) => {
    visit(tree, 'mdxJsxFlowElement', (node) => {
      if (node.name !== 'Note') return;

      replaceSource(file, node, (s) => `**Note:**\n\n${s.inner(node)}`);
      // transform the node for rendering...
    });
  };
}

::highlight(fd-search) {
  color: var(--color-fd-primary);
  text-decoration: underline;
}

import { useFetchSearch } from 'fumadocs-core/search/client';

const search = useFetchSearch();

<SearchDialog {...search} {...props} />;

#nd-docs-layout {
  grid-template:
    'sidebar header toc'
    'sidebar toc-popover toc'
    'sidebar main toc' 1fr / minmax(var(--fd-sidebar-col), 1fr) minmax(0, var(--fd-page-col))
    minmax(min-content, 1fr);

  --fd-docs-row-1: var(--fd-banner-height, 0px);
  --fd-docs-row-2: calc(var(--fd-docs-row-1) + var(--fd-header-height));
  --fd-docs-row-3: calc(var(--fd-docs-row-2) + var(--fd-toc-popover-height));
}

.layout-component {
  position: sticky;
  top: var(--fd-docs-row-1);
  height: calc(var(--fd-docs-height) - var(--fd-docs-row-1));
}

#nd-docs-layout:has(.layout-component) {
  --fd-header-height: 56px;
}

.custom-component {
  /* depends on the layout, usually we have toc, toc-popover, sidebar, header, main */
  grid-area: main;
}

/* [!code --] */
@import 'fumadocs-ui/css/preset.css';
/* [!code ++] */
@import 'fumadocs-ui/css/preset-legacy.css';

// [!code --:2]
import {} from 'fumadocs-ui/contexts/sidebar';
import {} from 'fumadocs-ui/contexts/layout';

// [!code ++:2]
import {} from 'fumadocs-ui/legacy/sidebar';
import {} from 'fumadocs-ui/legacy/layout';

import type { ReactNode } from 'react';
import { SidebarProvider } from 'fumadocs-ui/legacy/sidebar';

export function RootLayout({ children }: { children: ReactNode }) {
  return <SidebarProvider>{children}</SidebarProvider>;
}

// [!code --]
import { useSidebar } from 'fumadocs-ui/contexts/sidebar';
// [!code ++]
import { useSidebar } from 'fumadocs-ui/components/sidebar/base';

// For docs layout
import { DocsPage } from 'fumadocs-ui/layouts/docs/page';
// For notebook layout
import { DocsPage } from 'fumadocs-ui/layouts/notebook/page';