使用 Docusaurus 构建文档站点

你需要为你的库、框架或 SaaS 产品搭建一个文档站点。你希望它是静态的、快速的、易于维护的,而不需要从零开始构建所有内容。Docusaurus v3 能够很好地满足这些需求——它是一个成熟的基于 React 的静态站点生成器,开箱即支持版本管理、搜索集成和 MDX。

本指南涵盖了 Docusaurus 文档站点的架构和实际搭建方法,重点关注在各个次要版本中保持稳定的核心概念。

Docusaurus 文档站点的核心架构

Docusaurus 将内容组织为三种不同的内容类型:

文档(Docs) 位于 /docs 目录中。这些是你的主要文档页面,会自动渲染侧边栏导航并支持版本管理。每个 Markdown 或 MDX 文件都会成为一个页面。

博客(Blog) 文章放在 /blog 目录中。这些适合用于更新日志、版本发布公告或具有时效性的教程。

页面(Pages) 位于 /src/pages 目录中,是独立的 React 组件或 MDX 文件,用于自定义落地页、关于页面或任何不属于文档/博客结构的内容。

侧边栏和版本管理模型值得关注。Docusaurus 会根据你的文件夹结构自动生成侧边栏,或者你可以在 sidebars.js 中显式定义它们。当你创建一个版本时,它会将当前文档快照到 versioned_docs/ 目录中,让用户能够访问旧版本的文档。

Docusaurus v3 设置:入门指南

现代脚手架支持 npm、Yarn、pnpm 和 Bun。选择你团队使用的任何一个:

npx create-docusaurus@latest my-docs classic

classic 预设捆绑了文档插件、博客插件和默认主题——对于大多数开发者文档站点来说已经足够。Docusaurus v3 在本地开发和 CI 环境中需要 Node.js 20 或更高版本。

脚手架搭建完成后,你的项目结构如下所示:

my-docs/
├── docs/
├── blog/
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
├── docusaurus.config.js
└── sidebars.js

docusaurus.config.js 文件控制站点元数据、主题配置、导航栏、页脚和插件选项。这个单一文件可以处理大部分自定义需求,而无需触碰 React 代码。

MDX 文档:编写内容

Docusaurus v3 使用 MDX v3,它比早期版本更严格。如果你正在从 v2 迁移,这一点很重要——MDX v3 强制执行正确的 JSX 语法,不会静默忽略格式错误的组件。

每个文档文件都支持用于元数据的 frontmatter:

---
id: getting-started
title: Getting Started
sidebar_position: 1
---

# Getting Started

Your content here. You can import React components directly.

你可以嵌入 React 组件,使用 Mermaid 图表,并包含交互式代码块。@site 别名指向你的项目根目录,用于导入。

要启用图表功能,在配置中启用 Mermaid 插件:

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
}

主题和自定义

插件系统允许你在不 fork 主题的情况下扩展功能。常见插件可以处理分析、站点地图、PWA 支持和重定向。

对于视觉自定义,可以在 src/css/custom.css 中覆盖 CSS 变量。主题底层使用 Infima,因此你调整的是设计令牌而不是编写组件样式:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

更深层次的自定义使用 “swizzling”——弹出主题组件以进行修改。运行 npx docusaurus swizzle 查看可用组件。只 swizzle 你需要的部分,因为弹出的组件在升级 Docusaurus 时需要手动更新。

搜索集成

大多数生产环境的 Docusaurus 站点使用 Algolia DocSearch。如果你的文档是公开的,可以申请免费计划;对于私有文档,可以自托管爬虫。

配置位于 themeConfig 中:

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
}

DocSearch v4 还支持 Algolia AskAI,它在标准搜索体验之上添加了可选的对话式搜索功能,并作为同一 Algolia 集成的一部分进行配置。

部署

Docusaurus 将站点构建为 /build 目录中的静态 HTML、CSS 和 JavaScript 文件。任何静态托管服务都可以使用:Vercel、Netlify、GitHub Pages、Cloudflare Pages 或你自己的 CDN。

npm run build

输出是一个标准的静态站点,不需要服务器运行时。配置你的托管服务提供商,通过为未知路径提供 index.html 来处理客户端路由。

生产环境注意事项

维护开发者文档站点的几个实用建议:

• 版本管理会增加复杂性。 只有在用户确实需要访问旧文档时才使用版本管理。许多项目只使用单个”当前”版本就能运行良好。
• MDX 的严格性能捕获真实的 bug。 如果从 v2 迁移时页面出现问题,错误通常指向值得修复的实际 JSX 问题。
• 构建时间随内容增长而增加。 大型站点可以从 CI 中的增量构建和缓存 node_modules 中受益。

总结

Docusaurus 处理基础设施,让你可以专注于编写优质文档。React 基础意味着前端团队可以在需要时进行深度自定义,而默认配置已经足够好,许多站点无需触碰 React 代码就能发布。从 classic 预设开始,随着需求出现添加插件,并在文档内容完善之前抵制过度自定义的冲动。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.