Fumadocs v13 | Fumadocs 中文文档

介绍

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

新功能

更好的代码块

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

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 type="warn">Hello World</Callout>

新的 Headless TOC

目录 (TOC) 的 headless 组件现在有一个独立的滚动容器提供者。

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

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

锚点提供者可以放置在任何位置。

选择退出容器

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

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

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

Admonition 语法

在 Docusaurus 中，有 Admonition 语法。

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

见 Remark Admonition。

破坏性变更

颜色、动画和实用程序的前缀

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

要将 Fumadocs UI 的颜色用于您的主应用程序，请启用 addGlobalColors 选项。

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

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

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

或者您可以直接使用 fd- 前缀引用它们，例如 bg-fd-background。

Tailwind CSS 插件仅 ESM

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

在您的配置中使用 ESM 语法。

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

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

移除 `RollButton` 组件

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

您可以复制 RollButton 的最后实现。

更好的 i18n

现在 I18nProvider 组件需要 locale prop，而不是从路径名解析它。这修复了 I18n 中间件的一些 bug。

我们还改变了 translations 的用法，以减少客户端加载的额外翻译。您必须直接传递活动的翻译。

locales 被传递为 Language Select 组件上的可用选项。

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: '英语',
              locale: 'en',
            },
            {
              name: '中文',
              locale: 'cn',
            },
          ]}
          // translations
          translations={
            {
              cn: {
                toc: '目錄',
              },
            }[lang]
          }
        >
          <RootProvider>{children}</RootProvider>
        </I18nProvider>
      </body>
    </html>
  );
}

代码块用法

先前的用法令人困惑，有些 prop 直接传递给 pre，而有些没有。

使用 v13，将所有 prop 传递给 CodeBlock 组件。这也包括类名，如果必要，您可以更改您的自定义样式。

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