Fumadocs v13

Introduction

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

New Features

Better Code Blocks

Supported to keep 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

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

The headless component of Table of Contents (TOC) now separated the 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

Supported to disable 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

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.

Previously, the Tailwind CSS plugin of Fumadocs UI adds colors (including primary, secondary) which conflicts 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

Since Tailwind CSS supported 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

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

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 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

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>
    ),
  }}
/>;