Fumadocs v15

概览

🌐 Overview

v15 的主要目的是支持 Tailwind CSS v4。Tailwind CSS v4 对其 API 和内部结构进行了全面的重新设计，为了完全遵循新的以 CSS 为中心的配置方式，必须进行破坏性更改。

🌐 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 没有其他重大变化，唯一的改动是将配置迁移到 Tailwind CSS v4。

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

重大更改

🌐 Breaking Changes

在进行切换之前，请按照他们的升级指南将你的网站升级到 Tailwind CSS v4。你可以删除未使用的 tailwind.config.js 文件，完全依赖新的 CSS 优先配置。

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

将 @import 添加到 Fumadocs UI 导出的预设中，并在源文件中包含 fumadocs-ui 包。

🌐 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';

自 v15 起，你将无法在 JavaScript 中传递选项来定制插件。取而代之的是，你可以使用 Tailwind CSS v4 中的新替代方案。

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

addGlobalColors: true

再次显示颜色：

🌐 Forward the colors again:

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

CSS 变量

🌐 CSS Variables

Fumadocs 不再像 --fd-primary: 0 0% 0% 那样使用 --fd-<color> 来表示颜色，而是直接在 @theme 中定义和使用颜色。它不再使用以前的格式，而是使用 hsl()：

🌐 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

以前的 Tailwind CSS 工具类如 steps 和 step 已重命名为 fd-steps 和 fd-step 以避免冲突。

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

排版

🌐 Typography

包括 prose、prose-* 修饰符在内的排版工具将继续有效。如果它们不再工作或行为出现意外变化，请报告问题。

🌐 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

v15 还包括对用户界面和 OpenAPI 集成的一些小改进。

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

代码块标签

🌐 Code Block Tabs

过去，当将代码块分到不同标签时，你需要手动编写 <Tabs />。

🌐 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');
```

请注意，对于那些想要自定义或向 <Tabs /> 组件传递属性的人，之前的使用方式仍然有效。

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

meta.json 中的反转项目

🌐 Reversed Items in meta.json

meta.json 的 pages 属性中的剩余项 ... 现在支持倒序排列：

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

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

OpenAPI 试玩

🌐 OpenAPI Playground

v15 改进了 Playground 用户界面（受 Scalar 极简主义的启发），并为 Fumadocs OpenAPI 带来了 Scalar API 客户端支持。

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

你可以在 createOpenAPI() 中使用 useScalar 选项启用 Scalar API 客户端：

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

并安装并配置他们的 @scalar/api-client-react：

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

npm install @scalar/api-client-react

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

未来计划

🌐 Future Plans

对于大多数更新到 Tailwind CSS v4 的开发者来说，这次更新应该是一次简单的迁移。

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

未来，我们还希望对 Fumadocs MDX 进行进一步改进：

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

• 移除 transform API - 你可以像下面这样在运行时轻松使用 .map():

import { blog } from "@/.source"

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

• 移除 Manifest API——它曾用于导出搜索索引，但现在建议使用路由处理程序来实现。
• 更多提到我们的 MDX Remote 包，它将成为处理性能需求较高的大型文档网站的主要解决方案，这是打包工具无法做到的，包括 MDX 文件的延迟编译。