Fumadocs v15

概述

v15 的主要目的是支持 Tailwind CSS v4。 Tailwind CSS v4 对其 API 和内部结构进行了完全重新设计，以完全遵循新的 CSS 优先配置风格，这需要进行破坏性更改。

Fumadocs v15 除了将配置迁移到 Tailwind CSS v4 之外，没有其他重大更改。

破坏性更改

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

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

@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 中的新替代方案。

addGlobalColors: true

再次转发颜色：

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

CSS 变量

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

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

Steps

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

排版

包括 prose 和 prose-* 修饰符在内的排版实用工具将继续正常工作。如果它们不再工作或行为发生意外变化，请报告问题。

改进

v15 还包括对 UI 和 OpenAPI 集成的些许改进。

代码块选项卡

过去，当将代码块分离成选项卡时，您需要手动编写 <Tabs />。

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

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

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

</Tabs>

现在您可以这样做：

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

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

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

meta.json 中的反转项目

meta.json 的 pages 属性中的剩余项目 ... 现在支持反转顺序：

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

OpenAPI Playground

v15 改进了 playground UI（受 Scalar 的极简主义启发），并为 Fumadocs OpenAPI 带来了 Scalar API Client 支持。

您可以使用 createOpenAPI() 中的 useScalar 选项启用 Scalar API Client：

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

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

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

npm install @scalar/api-client-react

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

未来计划

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

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

• 移除 transform API - 您可以在运行时使用 .map() 轻松实现相同功能，例如：

import { blog } from "@/.source"

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

• 移除 Manifest API - 它最初设计用于导出搜索索引，但现在推荐使用路由处理器来实现。

• 更多提及我们的MDX Remote 包，它将是处理大型文档站点性能需求的主要解决方案，这些需求是打包器无法实现的，包括 MDX 文件的懒加载编译。