Fumadocs v14 | Fumadocs 中文文档

为什么？

从 Shadcn UI 中汲取一些灵感，我决定让 Fumadocs 更容易使用，提供更多简化设计的 API。

这是一个大型更新。

新功能

Fumadocs CLI

将 Fumadocs UI 组件克隆到您的工作区并修改它们。

npm install @fumadocs/cli --save-dev

pnpm fumadocs add

详情请参阅文档。

侧边栏标签页

以前，多页树使用 Fumadocs UI 的 RootToggle 组件实现。您必须将其添加到侧边栏横幅中，这不像其他 API 那样直观。

使用侧边栏标签页，通过创建根文件夹，Fumadocs 将立即在侧边栏添加一个标签页组件。

meta.json

{
  "root": true,
  "title": "标签页名称",
  "description": "关于该标签页的一些文本",
  "icon": "IconName"
}

Orama

我们将内置搜索从 Flexsearch 迁移到 Orama，这是为 Node.js 文档站点提供动力的同一搜索引擎。它是开源的，并且还提供了他们的 Cloud 集成。

无需更改。您可以使用我们的新 createFromSource API 来创建路由处理程序，它提供无需任何配置的 i18n 支持。

import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

export const { GET } = createFromSource(source);

为此，Fumadocs 的新搜索客户端引入了支持不同 API 客户端的功能。这包括 Algolia、Orama（静态和动态，使用路由处理程序）。

import { useDocsSearch } from 'fumadocs-core/search/client';

const client = useDocsSearch({
  type: 'static',
});

请参阅搜索 API。

静态搜索

对于静态导出的站点，您无法使用路由处理程序。我们现在支持使用构建时生成的搜索索引进行客户端搜索。

请参阅静态搜索。

更少的依赖

我一直在努力减少 Fumadocs 所需的依赖，这就是为什么我们将 Fumadocs 分离成不同包的原因之一。

Fumadocs UI 现在将来自 lucide-react 的图标打包，对于不使用 Lucide 的 Next.js 应用，它们可以避免下载整个图标库。

并且 swr 不再用于搜索客户端，我们实现了一个轻量级的 useQuery 钩子，并特别注意 React 性能优化。

新的元数据图像 API

为了改善代码组织，我们在 Fumadocs Core 上制作了一个元数据图像 API。它是 Next.js 元数据 API 的一个小型包装器，与 Source API 无缝组合。

lib/metadata.ts

import { createMetadataImage } from 'fumadocs-core/server';
import { source } from '@/lib/source';

export const metadataImage = createMetadataImage({
  imageRoute: '/docs-og',
  source,
});

route.ts

import { generateOGImage } from 'fumadocs-ui/og';
import { metadataImage } from '@/lib/metadata';

export const GET = metadataImage.createAPI((page) => {
  return generateOGImage({
    title: page.data.title,
    description: page.data.description,
    site: 'My App',
  });
});

export function generateStaticParams() {
  return metadataImage.generateParams();
}

page.tsx

import { source } from '@/lib/source';
import { metadataImage } from '@/lib/metadata';
import { notFound } from 'next/navigation';

export function generateMetadata({ params }: { params: { slug?: string[] } }) {
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return metadataImage.withImage(page.slugs, {
    title: page.data.title,
    description: page.data.description,
  });
}

为此，来自 fumadocs-ui/og 的 getImageMeta 函数已被移除。

简写

您可能已经注意到，我们引入了更多抽象来减少启用某些功能所需的设置步骤。这也是 Fumadocs CLI 的代码生成器正常工作的必要条件。

例如 generateParams 函数，它为 Next.js 的 generateStaticParams 启用零配置的 i18n 支持。

import { source } from '@/lib/source';

export function generateStaticParams() {
  return source.generateParams();
}

更好的卡片组件

Fumadocs UI 卡片现在支持不使用 href 的用法。您可以将 children 作为 React 节点传递，Typography 样式将正确应用。

<Card icon={<Database />} title='内容源'>

您的内容输入/源，它可以是一个 CMS，或者像 [Content Collections](https://www.content-collections.dev) 和 [Fumadocs MDX](/docs/mdx) 这样的本地数据层。

</Card>

更好的类别组件

原始的 DocsCategory 组件是从我们的官方文档中复制的，这是一个非常简单的实现，没有考虑页面树。

现在它通过 from 属性接受源对象。

page.tsx

import { source } from '@/lib/source';
import { DocsCategory } from 'fumadocs-ui/page';

const page = source.getPage(params.slug);

<DocsCategory page={page} from={source} />;

默认情况下，它从 page 中获取 locale 属性来查找相应的页面树进行遍历。您也可以强制指定一个页面树。

page.tsx (i18n enabled)

import { source } from '@/lib/source';
import { DocsCategory } from 'fumadocs-ui/page';

const page = source.getPage(params.slug, params.lang);

<DocsCategory page={page} from={source} tree={source.pageTree['en']} />;

OpenAPI 标签显示名称

使用 x-displayName 更改显示名称。

openapi.yaml

tags:
  - name: test
    description: this is a tag.
    x-displayName: My Test Name

更好的 TypeScript 文档自动化

AutoTypeTable 组件现在支持 type 属性，您可以在字段中使用 TypeScript：

<AutoTypeTable
  path="file.ts"
  name="B"
  type={`
import { ReactNode } from "react"
export type B = ReactNode | { world: string }
`}
/>

并且 typedoc 中的代码高亮也支持 Shiki。

我们强烈推荐在 MDX 文件中导入组件而不是使用 createTypeTable，这允许共享 TypeScript Compiler API 的单个实例。请参阅自动类型表格。

Next.js 15

Fumadocs v14 与 Next.js 15 兼容，支持动态 API 的同步和异步用法。

向后兼容

也支持 Next.js 14，请注意文档中的指南/教程主要针对 Next.js 15。

UI 改进

导航栏链接

Home 布局上的导航菜单已重新设计，具有更好的动画和灵活性。

请参阅新 API。

新导航栏

链接样式

您可以使用 data-card 属性为 a 标签转义 Tailwind CSS Typography 样式。

<a data-card="">
  未应用样式 <code>但它确实应用了</code>
</a>

禁用主题切换

您可以使用布局上的 disableThemeSwitch 禁用默认主题切换器。

破坏性变更

将 `dir` 选项从 `defineDocs` 移动

import { defineDocs } from 'fumadocs-mdx/config';

export const { docs, meta } = defineDocs({
  dir: 'my/content/dir', // 只定义一次
});

重构导入

以前

import { DocsLayout } from 'fumadocs-ui/layout';
import { HomeLayout } from 'fumadocs-ui/home-layout';
import { HomeLayoutProps } from 'fumadocs-ui/home-layout';

新导入路径

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { HomeLayout } from 'fumadocs-ui/layouts/home';
import { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

Twoslash UI

我们将 Twoslash UI 组件移动到 fumadocs-twoslash。这将一些逻辑从 Fumadocs UI 中隔离出来，从而实现更好的代码组织。

以不同的方式导入 CSS 样式和 Popup 组件。

import 'fumadocs-twoslash/twoslash.css';

import { Popup } from 'fumadocs-twoslash/ui';

它需要 Tailwind CSS。

移除已弃用的 API

以前的 createI18nSearchAPIExperimental 现在重命名为 createI18nSearchAPI。它采用 i18n 配置而不是将选项散布在各处。

来自 fumadocs-core/search/shared 的类型已移动到 fumadocs-core/server。