Fumadocs v13

介绍

🌐 Introduction

Fumadocs v13 已经发布。它旨在解决 CSS 污染问题并移除弃用的 API。

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

新功能

🌐 New Features

更好的代码块

🌐 Better Code Blocks

现在支持在 CodeBlock 组件上保留由 Shiki 生成的原始背景。

🌐 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

Callout 现在是默认的 MDX 组件，你可以在 MDX 文件中直接使用它，无需导入，也可以手动将其添加到 MDX 组件中。

🌐 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

目录（TOC）的无头组件现在有了一个单独的滚动容器提供者。

🌐 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

现在支持禁用 Fumadocs UI 添加的 Tailwind CSS 默认容器样式。

🌐 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

在 Docusaurus 中，有一种 警告语法。

🌐 In Docusaurus, there's an Admonition syntax.

对于从 Docusaurus 迁移过来的人，你可以启用新的 remark 插件以支持 Admonition 语法。

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

参见 注释警告。

🌐 See Remark Admonition.

重大更改

🌐 Breaking Changes

颜色、动画和工具的前缀

🌐 Prefix to colors, animations, and utilities

之前，Fumadocs UI 的 Tailwind CSS 插件添加了颜色（包括 primary、secondary），这与 Shadcn UI 和其他设计系统产生了冲突。为了允许在文档中使用独立的设计系统，现已为它们添加了 fd- 前缀。

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

要在你的主要应用中使用 Fumadocs UI 颜色，请启用 addGlobalColors 选项。

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

这会添加没有 fd- 前缀的颜色。

🌐 This adds the colors without the fd- prefix.

或者你也可以直接用 fd- 前缀来引用它们，比如 bg-fd-background。

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

Tailwind CSS 插件仅限 ESM

🌐 Tailwind CSS Plugin ESM-only

由于 Tailwind CSS 支持 TypeScript 配置，因此将整个插件迁移到 ESM 是有意义的。

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

在配置中使用 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()],
};

移除 RollButton 组件

🌐 Remove RollButton component

RollButton 的引入是因为移动端视口上没有“目录”。现在用户可以使用目录弹出窗口在标题之间切换，它不再适合 Fumadocs 的 UI 设计。

你可以复制RollButton的最新实现。

🌐 You may copy the last implementation of RollButton.

更好的国际化

🌐 Better i18n

现在 I18nProvider 组件需要 locale 属性，而不是从路径名中解析它。这修复了一些与 I18n 中间件相关的错误。

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

我们还改变了 translations 的使用方式，以减少客户端加载的额外翻译内容。你必须直接传递活动的翻译。

🌐 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 被作为语言选择组件中的可用选项传递。

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

之前的用法让人困惑，有些属性是直接传递给 pre 的，而有些则没有。

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

在 v13 中，将所有属性传递给 CodeBlock 组件。这也包括类名，如果有必要，你可以更改自定义样式。

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

移除已弃用的 API

🌐 Remove Deprecated APIs

• 移除已弃用的 fumadocs-ui/components/api 组件。
• 将 secondary 链接项替换为 icon 链接项。
• 将 Tabs 组件上的 id 属性重命名为 groupId。

错误修复

🌐 Bug Fixes

用户界面

🌐 UI

• 修复了由 Radix UI 引起的空文件夹动画问题。