如何组织和创建文档

⚙️ 文档配置

源配置

文档系统在 source.config.ts 中配置：

src/source.config.ts

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

export const docs = defineDocs({
  dir: "src/content/docs",
});

源加载器

文档使用 Fumadocs 在 src/lib/source.ts 中加载：

src/lib/source.ts

export const source = loader({
  i18n,
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});

📝 创建文档

添加新的文档页面

在 src/content/docs/ 中创建一个新的 MDX 文件：

---
title: API 参考
description: NEXTDEVKIT 的完整 API 参考
icon: Code
---

# API 参考

NEXTDEVKIT 服务器操作和工具的完整 API 参考。

## 认证 API

### `getSession()`

在服务器端获取当前用户会话。

```typescript title="src/app/components/server-component.tsx"
import { getSession } from '@/lib/auth/server';

export default async function ServerComponent() {
  const session = await getSession();
  
  if (!session?.user) {
    redirect('/auth/login');
  }
  
  return <div>欢迎，{session.user.name}！</div>;
}

frontmatter 中的 icon 属性支持所有 Lucide 图标，并将在侧边栏中生成为图标。

组织结构

Fumadocs 支持文档的分层组织。

您可以在每个文件夹中创建 meta.json 文件来组织文档。

例如，要创建一个名为 configuration 的新章节，您需要在 src/content/docs/ 目录中创建一个名为 configuration 的新文件夹，并在其中添加一个 meta.json 文件。

src/content/docs/configuration/meta.json

{
  "title": "配置",
  "description": "配置文档",
  "pages": [
    "index",
    "website-config",
    "marketing-config"
  ]
}

多语言支持

Fumadocs 支持多语言文档。

您可以使用以下文件命名约定创建多语言内容：

默认语言（例如英语）：filename.mdx
其他语言（例如中文）：filename.zh.mdx

对于国际化，您可以在同一文件夹中创建一个新的 meta.zh.json 文件。

搜索 API

Fumadocs 提供搜索 API 来搜索文档。

您可以使用 createI18nSearchAPI 函数来搜索文档。

src/app/api/search/route.ts

export const { GET } = createI18nSearchAPI("advanced", {
	i18n: {
		defaultLanguage: appConfig.i18n.defaultLocale,
		languages: Object.keys(appConfig.i18n.locales).filter(
			(locale) => locale !== "zh",
		),
	},
	indexes: source.getLanguages().flatMap((entry) =>
		entry.pages.map((page) => ({
			title: page.data.title,
			description: page.data.description,
			structuredData: (page.data as any)?.structuredData,
			id: page.url,
			url: page.url,
			locale: entry.language,
		})),
	),
});

因为默认搜索 API 不支持中文 zh，您需要从 languages 数组中过滤掉中文。

如果您想支持像中文这样的特殊语言搜索，您可以参考以下链接：

例如，对于中文和日文，它们需要额外的配置：

pnpm add @orama/tokenizers

更新搜索 API 以支持特殊语言：