# 快速入门 本指南将从空文件夹开始，使用 Onedocs 搭建文档网站。如果你已有 Next.js 项目，请跳过已有文件，并参照其余步骤。 ## 先决条件 - Node.js 20.9 或更高版本（Next.js 16 的要求） - Next.js 16（使用 App Router），React 19.2 或更高版本 - Tailwind CSS v4（Onedocs CSS 预设会导入 `tailwindcss`） Fumadocs UI 16 仅支持 Next.js 16 和 React 19.2，因此较旧的 Next.js 或 React 版本无法使用，尽管 `onedocs` 包元数据仍列出了这些版本（[问题 #5](https://github.com/inline0/onedocs/issues/5)）。 ## 安装 Onedocs 不会捆绑 Next.js 或 Fumadocs。它们是对等依赖项，因此需要与它一同安装： ```bash npm install onedocs fumadocs-core fumadocs-mdx fumadocs-ui lucide-react@0.562 next react react-dom npm install -D tailwindcss @tailwindcss/postcss typescript @types/react @types/react-dom @types/node ``` 保留 `lucide-react@0.562` 固定版本。`onedocs` 0.1.27 将 `lucide-react` `^0.562.0` 声明为对等依赖项；如果不固定版本，npm 会安装 lucide-react 1.x，并因 `ERESOLVE` 错误而停止（[问题 #1](https://github.com/inline0/onedocs/issues/1)）。 同一组包也适用于 pnpm、yarn 或 bun。 将 Next.js 脚本添加到 `package.json`： ```json title="package.json" { "scripts": { "dev": "next dev", "build": "next build", "start": "next start" } } ``` ## 项目结构 最终的项目结构如下： ``` your-project/ ├── content/ │ └── docs/ │ ├── index.mdx │ └── meta.json ├── public/ │ └── fonts/ │ └── InterVariable.woff2 ├── src/ │ ├── app/ │ │ ├── layout.tsx │ │ ├── page.tsx │ │ ├── globals.css │ │ └── docs/ │ │ ├── layout.tsx │ │ └── [[...slug]]/ │ │ └── page.tsx │ └── lib/ │ └── source.ts ├── onedocs.config.ts ├── source.config.ts ├── next.config.mjs ├── postcss.config.mjs ├── tsconfig.json └── package.json ``` 现在来创建每个文件。 ## 配置文件 ### onedocs.config.ts 你的主要配置文件。只有 `title` 是必需的；其他配置请参阅 [配置](https://onedocs.inline0.dev/zh/docs/configuration)。 ```ts title="onedocs.config.ts" import { defineConfig } from "onedocs/config"; export default defineConfig({ title: "My Docs", description: "Documentation for my project", nav: { github: "username/repo", }, }); ``` ### source.config.ts 告诉 Fumadocs MDX 内容所在的位置。这是唯一设置内容文件夹的位置： ```ts title="source.config.ts" import { defineDocs } from "fumadocs-mdx/config"; export const docs = defineDocs({ dir: "content/docs", }); ``` ### next.config.mjs 启用 MDX 处理： ```js title="next.config.mjs" import { createMDX } from "fumadocs-mdx/next"; const withMDX = createMDX(); /** @type {import('next').NextConfig} */ const config = {}; export default withMDX(config); ``` Fumadocs MDX 会在 Next.js 启动时，根据 `source.config.ts` 生成 `.source/` 文件夹。将 `.source` 添加到 `.gitignore` 中。 ### postcss.config.mjs 运行 Tailwind CSS v4，这是 Onedocs CSS 预设的基础： ```js title="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, }, }; ``` ### tsconfig.json 以下示例从 `@/` 导入，因此请将其映射到 `src/`： ```json title="tsconfig.json" { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } } ``` 首次运行 `next dev` 或 `next build` 时，Next.js 会向此文件添加所需的其余编译器选项。 ## 源设置 ### src/lib/source.ts 加载文档内容： ```ts title="src/lib/source.ts" import { loader } from "fumadocs-core/source"; import { docs } from "../../.source/server"; export const source = loader({ baseUrl: "/docs", source: docs.toFumadocsSource(), }); ``` ## 应用文件 ### src/app/layout.tsx 你的根布局： ```tsx title="src/app/layout.tsx" import type { Metadata } from "next"; import { RootProvider } from "fumadocs-ui/provider/next"; import { FontHead } from "onedocs"; import "./globals.css"; export const metadata: Metadata = { title: "My Docs", description: "Documentation for my project", }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` 来自 Fumadocs UI 的 `RootProvider` 提供搜索对话框和浅色、深色主题。`FontHead` 会从 `/fonts/InterVariable.woff2` 预加载 Inter Variable 字体，并将其设为页面字体。Onedocs 不会附带字体文件：请从 [Inter 发布版本](https://github.com/rsms/inter/releases) 下载 `InterVariable.woff2`，并将其放入 `public/fonts/`。若未提供，文本会回退到系统无衬线字体。 如需改为根据配置生成此元数据，请参阅 `createMetadata`，位置在 [API 参考](https://onedocs.inline0.dev/zh/docs/api-reference#createmetadata)中。 ### src/app/globals.css 导入 CSS 预设： ```css title="src/app/globals.css" @import "onedocs/css/preset.css"; @source "./**/*.tsx"; @source "../../content/**/*.mdx"; ``` 此预设会加载 Tailwind CSS、Fumadocs UI 样式和 Onedocs 布局样式。`@source` 路径相对于 `globals.css`，因此这两行分别指向 `src/app/` 和项目根目录中的 `content/` 文件夹。 ### src/app/page.tsx 主页。`HomePage` 会根据你的配置渲染主视觉、功能介绍和页脚： ```tsx title="src/app/page.tsx" import { HomePage } from "onedocs"; import config from "../../onedocs.config"; export default function Home() { return ; } ``` `packageName` 会在主视觉中添加适用于 npm、yarn、pnpm 和 bun 的安装命令。如果你的项目不是一个包，请省略它。 ### src/app/docs/layout.tsx 带侧边栏的文档布局： ```tsx title="src/app/docs/layout.tsx" import { DocsLayout } from "onedocs"; import type { ReactNode } from "react"; import { source } from "@/lib/source"; import config from "../../../onedocs.config"; export default function Layout({ children }: { children: ReactNode }) { return ( {children} ); } ``` ### src/app/docs/[[...slug]]/page.tsx 单独的文档页面： ```tsx title="src/app/docs/[[...slug]]/page.tsx" import { source } from "@/lib/source"; import { DocsPage, mdxComponents } from "onedocs"; import { notFound } from "next/navigation"; export default async function Page(props: { params: Promise<{ slug?: string[] }>; }) { const params = await props.params; const page = source.getPage(params.slug); if (!page) notFound(); const MDX = page.data.body; return ( ); } export async function generateStaticParams() { return source.generateParams(); } export async function generateMetadata(props: { params: Promise<{ slug?: string[] }>; }) { const params = await props.params; const page = source.getPage(params.slug); if (!page) notFound(); return { title: page.data.title, description: page.data.description, }; } ``` ## 内容 ### content/docs/index.mdx 每个页面都需要在 frontmatter 中设置 `title`。`description` 为可选项： ```mdx title="content/docs/index.mdx" --- title: Introduction description: What this project does. --- Welcome to the docs. Components such as `` work without imports; see [Components](/docs/components). ``` ### content/docs/meta.json 设置侧边栏中的页面顺序： ```json title="content/docs/meta.json" { "pages": ["index"] } ``` 创建另一个 `.mdx` 文件并在 `pages` 中列出其名称，即可添加页面。 ## 运行 启动开发服务器： ```bash npm run dev ``` 主页位于 `http://localhost:3000`，文档位于 `http://localhost:3000/docs`。 构建生产版本： ```bash npm run build ``` 接下来，在 [SEO 与搜索](https://onedocs.inline0.dev/zh/docs/seo-search)中添加搜索、站点地图和 llms.txt。