跳到主要内容

入坑 Docusaurus，看这一篇就够了

· 阅读需 20 分钟

使用官方 V3 Demo，根据本文实战生成的模板代码 template-docusaurus。

在众多的 SSG 框架中，我基于第一印象、支持特性、用户数据、上手难易、界面设计等客观主观方面的比较，最终选择了 Meta 家的基于 React 的 Docusaurus。

选择 Docusaurus 的 n 个理由：

  1. 天然支持 TypeScript
  2. 基于 React（符合我目前的技术栈）
  3. 支持 Markdown、Mermaid、MDX
  4. 支持搜素、国际化等文档站必要因素
  5. 拥有大量的用户，处于积极维护的状态
  6. 上手简单，对新手友好
  7. 大厂出品

但真要找毛病，也不是没有：

  1. 名字是虚构的单词，难写难读（-saurus 为表示爬行动物的后缀，多为恐龙，从图标可以看出）
  2. 本地启动项目，用的是 Webpack，很明显的慢（但我认为这不是什么大不了的事情，晚些他们底层悄咪咪改了也有可能，事实上他们 正在做这个事情）
  3. 部分界面元素偏大，不够精致
  4. TOC 及书签点击后的定位，没有考虑到顶栏的高度，部分内容在跳转后被遮挡

总之，无论从 UX 还是 DX 来讲，Docusaurus 都是一个非常不错的 SSG 框架，虽然有些小瑕疵，但瑕不掩瑜。

为何需要 SSG​

README 是最接近文档的存在，大家应该都会用 Markdown 来写 README。

但作为技术文档，读者可能需要直观的代码运行效果，最好可交互，并且能够一键复制相关代码以便快速验证。这些就不是 README 这样的纯 Markdown 的工作职责了。

即便如此，Markdown 仍然是我们写文档的不二选择，只不过，我们想要的更多——这就需要一个文档框架。

🧐 如何挑选 SSG​

0 - 候选列表​

Jamstack Generators 这里提到了 300 多个 SSG 的框架。但对 Language 和 Templates 的分析并不全面，而且有一部分也没有包含进来。这么多，也没有必要都去研究，以下是我略研究过的（字母序）：

名称自述TSMDXReactVue
astroThe web framework for content-driven websites✅✅✅✅
docsifyA magical documentation site generator✅
docusaurusBuild optimized websites quickly, focus on your content✅✅✅
doczIt's never been easier to document your things!✅✅✅
dumi为组件研发而生的静态站点框架✅✅✅✅
eleventyEleventy is a simpler static site generator✅✅✅
gatsbyGatsby is a React-based open source framework for creating websites.✅✅✅
gitbookBuild docs as a product, not an afterthought✅
gridsomeA Jamstack framework for Vue.js✅
hugoThe world’s fastest framework for building websitesGo
jekyllTransform your plain text into static websites and blogsRuby
nextThe React Framework for the Web✅✅✅
nuxtThe Intuitive Vue Framework✅✅
pelicanStatic site generator powered by PythonPython
rspressLightning Fast Static Site Generator✅✅✅
vitdocA new way to write Component Usage✅✅
vitepressVite & Vue Powered Static Site Generator✅✅✅
vuepressVue-powered Static Site Generator✅✅

SSG 这个赛道也是很卷，相互间会暗自较劲，要么做比较，要么提供迁移方案（这些也是了解有哪些 SSG 的途径），比如：

1 - 第一印象​

找一个趁手的工具，很多时候跟相亲一样，第一印象，眼缘很重要。

眼缘首先看官网。作为 SSG 来说，官网必须是自己的第一个用户，是其展现自身能力的第一演练场。从官网，我们可以看其整体设计感，以及是否有我们需要的相关功能。

名称第一眼好感个人评价
astro★★★★☆很有设计感，文档排版及色调也不错，该有的功能都有；但顶栏上的下拉用了原生的 select，略拉低档次，且默认不是 SPA
docsify★★★相对简陋，没有顶栏，没有暗色，没有独立的 TOC
docusaurus★★★★☆整体样式偏重，但不难看，文档全面；但部分设计偏大（比如侧边栏的图标），不够精致
dumi★★★☆首页略简陋，文档树略丑
eleventy★★☆内容区域偏窄；有搜索但交互不方便；没有暗色；非 SPA，点击后，左侧文档树会刷新，导致丢失位置；没有 TOC 是最致命的
gatsby★★★广义的应用框架，上手略难
gitbook★★★老牌 SSG，整体样式比较清爽；但要账号，且没有暗色切换
gridsome★★★★☆布局、排版等细节非常棒，非常契合写文档
next★★★☆更广义的应用框架，基于 React，上手略难；虽然也有人用它来做文档站，但更多的是商业站
nuxt★★★☆从名字上看，它和 Next 的定位是一样的，也是广义上的应用框架，基于 Vue
rspress★★★☆让人很有尝试欲的 SSG
vitdoc★文档内容很少，可能烂尾了
vitepress★★★★内容全面，结构清晰，整体样式也不错；Vue 技术栈可以看看
vuepress★★被 vitepress 代替了

总结：论排版的清爽而言，个人认为 Gridsome 最符合文档站的审美需求。从功能的全面性来讲，Astro、Docusaurus、Next、Vitepress 等都不错。

2 - Showcase​

其次看它的用户，一来能够判断其受欢迎程度，二来可以作为借鉴学习的参考。用户量大的，自然会很骄傲地秀出来。

名称Showcase数量
astroastro.build/showcase1200+
docsifydocsify.js.org/#/awesome?i…130+，但相当一部分已经无效
docusaurusdocusaurus.io/showcase270+
gatsbywww.gatsbyjs.com/showcase600+
gitbookwww.gitbook.com/customer-sh…100+
gridsome收集中...
jekylljekyllrb.com/showcase/47+
nextnextjs.org/showcase120+
nuxtnuxt.com/showcase100+

3 - 文档基本需求​

从官网还可以简单看它是否符合文档站的基本需求。每个人的需求可能都不大一样，我的如下：

  1. 支持 TS，必需，无 TS 不 Coding
  2. 支持标准 Markdown：必需，并支持 FrontMatter、右侧独立 TOC、代码高亮、外链默认 target="_blank"
  3. 支持 MDX：必需，以支持更多动态特性，比如可交互 Demo
  4. 支持熟悉的 UI 框架：必需，否则不会需要 MDX
  5. 支持黑白主题：必需
  6. 支持全文搜索：必需，最好是本地搜素
  7. 支持国际化：非必需，有则善
  8. 支持多版本：非必需，有则善
  9. 支持 RTL：非必需
  10. SEO：非必需

以下判断，时间有限，不一定正确。

名称TSMarkdownTOCFrontMatter代码高亮自动外链MDX框架黑/白搜索国际化多版本RTL
astro✅✅✅✅✅❌✅React✅✅✅❓
docsify❌✅左侧✅✅✅VueVue✅✅✅❌
docusaurus✅✅✅✅✅✅✅React✅✅✅✅
docz✅✅左侧✅✅✅✅React❌❌❌❌
dumi✅✅左侧✅✅❌✅React✅✅✅✅✅
eleventy✅✅顶部✅✅❌✅React❌✅✅✅
gatsby✅✅✅✅✅❌✅React❌✅✅✅
gitbook✅✅✅✅✅❌❌❓✅✅ 很慢❌❌
gridsome❌✅✅✅✅✅❓Vue❌✅❌❌
hugoGo✅✅✅✅❌❌❓✅✅✅❌
jekyllRuby✅❌✅✅❌❌❓❌✅❌❌
next✅✅✅✅✅✅✅React✅ 底部✅✅❌
nuxt✅✅✅✅✅❌VueVue✅✅✅❌
pelicanPython✅✅❌✅❌❌❓✅✅✅✅
rspress✅✅✅✅✅✅✅React✅✅✅❌
vitdoc✅✅✅✅✅✅❓React✅✅✅❌
vitepress✅✅✅✅✅✅VueVue✅✅✅✅
vuepress✅✅✅✅✅✅VueVue✅✅✅✅

4 - 客观数据​

受欢迎程度（下载量、Star 数、Issue 数）和更新频次（版本数、更新时间），属于比较客观的信息，能进一步帮我们确定选择。

以下数据，收集时间为 2025/03/14，纯手工，非 AI。

名称NPM 周下载Github StarOpen Issue版本数第一版上次更新
astro github npm365k49.7k14811702021/032025/03
docsify github npm43.7k29k1431932016/112023/06
docusaurus github npm387.6k58.5k28120272017/062025/01
docz github npm3.5k23.7k1082682018/042022/02 💥 官宣停更
dumi github npm40.2k3.7k1303662019/122025/02
eleventy github npm70k17.7k3961932018/012024/10
gatsby github npm219.5k55.8k21029792015/052024/12
gitbook github npm3.4k27.6k42212015/022017/07
gridsome github npm1.4k8.6k540752018/092020/11
hugo github npm-78.7k4543162013/062025/02
next github npm7559.5k130k2.6k30292011/072025/03
nuxt github npm666.3k56.5k8693492016/?2025/03
rspress github npm6.4k1.6k736752022/102025/03
vitdoc github npm408311402022/082025/03
vitepress github npm114.6k14.1k3362512020/052025/01
vuepress github npm36.4k22.7k5412492018/042023/08 💥 基本停更

选择工具，跟买车一样，最怕停产了，根据上面的数据，可以放弃停产 2 年以上的那些。

5 - 上手​

以上框架，不论是否已停产，在我研究 SSG 框架的最初，应该也有试过（但当时未做记录）。出于篇幅的考虑，以下仅对持续更新中的进行上手演练，以便读者根据自己的喜好进行选择。

🌻 实战总结​

我们以一个新手的视角，从零开始，用 Docusaurus 搭建了一个文档站的基本内容，并配设了文档站十分重要的搜索功能。但这并不是 Docusaurus 的全部，也不是文档站的全部，本文尚未覆盖的相关部分有：

  1. SEO
  2. 国际化
  3. 多版本

🎯 最佳实践​

  1. 使用 Husky + LintStaged + MarkdownLint 规范 Markdown 格式
  2. 文档标题统一用 FrontMatter，并且 TOC 从二级标题 ## 开始
  3. 尽可能每个目录有个 index，或者在 _category_.yaml|json 中设置 link.type 为 generated-index
  4. _category_.yaml|json，JSON 或 YAML 仅取其一，并设置 link.slug
  5. 图片，尽可能就近放在当前目录的 img 子目录下，只有全局通用的放在 static/img 下

📌️ 附录​

有用的资源和网站​

文档，除了文字之外，图标、图片等装饰必不可少，这些网站可以收藏一下：

  • favicon.io 快速简单地生成 FavIcon
  • SVG Stack 可免费下载 SVG 图标，还能编辑后下载
  • SVG Repo 免费的装饰性多色 SVG 图标
  • unDraw 免费的装饰性 SVG 插图
  • Web SVG 很多好看的 SVG 装饰图
  • Flat Icon 图标和装饰图，SVG 要收费，但 PNG 免费
  • SVGOMG SVG 优化

SSG 标识​

自从开始研究文档框架，每打开一个文档站，我都会预判其 SSG 选型（同源的基因很容易看出来），然后在开发工具中找 HTML 上的标识以确定预判是否正确。以下是一些比较明显的标记：

  • body.astro-...
  • div#___gatsby
  • div#__docusaurus
  • div#__next
  • div#__nuxt
  • next-route-announcer
  • div#VPContent Vitepress

前端常用工具的文档站选型​

以下基于 Docusaurus：

站点分类可参考
babel编译
electron前端 App 化顶栏下拉菜单
format.js国际化
gulp构建
hooks-tsReact Hook
immerimmutable 辅助
jest单元测试多版本
lernamonorepo 工作流
npmpackagejsonlint代码质量
playwrighte2e 测试
pnpm包管理
prettier代码格式
react-liveReact Playground
redux-saga状态管理自定义主题切换按钮
redux-toolkit状态管理不一样的搜索
remirror在线编辑
stylelint代码质量
tauri@v1前端 App 化顶栏下拉菜单
testing-library单元测试
verdaccioNPM 仓库多版本、多语言

以下基于其他框架

站点分类使用框架
atlassian design设计系统Gatsby
biome代码质量Astro
commitlintGit 工作流Vitepress
cypresse2e 测试Next
eslint代码质量？
highlight.js代码高亮Next
huskyGit 工作流Vitepress
mermaid文字转图表Vitepress
npm docsNPMGatsby
parcel构建？
radashi工具集Astro
reactLibNext
rollup构建Vitepress
shiki代码高亮Vitepress
styled-componentsCss-in-JSNext
tauri前端 App 化Astro
typescript编译Gatsby
use-hooksReact HookAstro
vite构建Vitepress
vitest单元测试Vitepress
vueLibVitepress
webpack构建？
zustand状态管理Next

关于技术文档的一些文章​

🙋 FAQ​

❓ 为什么不选 Storybook？​

首先要说明的是，个人非常喜欢 storybook，在我的项目中少不了它。

Storybook 非常受欢迎，它不仅仅是一个 UI 测试框架，甚至可以用它写文档，甚至写文档非常方便（支持 MDX，并且只需要一行配置就可以自动生成相关的文档）。

而且已经有不少团队已经在用 Storybook 辅助生成文档，一些例子：

我不选择它作为文档基座，有以下原因：

  1. Storybook 自己没用它来写文档
  2. Storybook 自动生成的文档比较生硬，不像自己写那样自然
  3. 没有全局搜索
  4. 左侧树状导航很紧凑，没有层次感，影响阅读
  5. 生成的文档默认没有 TOC，但应该可以加上，比如 circuit.sumup.com 有个比较丑的 TOC

❓ 如何显示代码行号？​

Docusaurus 并没有提供全局开启代码行号的配置，但你可以针对特定的一块代码显示行号，给代码块加上 showLineNumbers 即可。

我认为这样的按需策略是正确的，毕竟多数情况下，两三行的代码，并不需要行号。

md

 体验AI代码助手
 代码解读
复制代码\`\`\`type showLineNumbers
...code...
\`\`\`

❓ 如何增加代码高亮的语言种类？​

Docusaurus 使用 Prism 对代码块进行高亮处理，并且内置了一些常用语言，但可能漏了你需要的，比如我们经常会在文档中写一些命令行，就没有高亮。

在配置项中，增加 prism.additionalLanguages：

ts

 体验AI代码助手
 代码解读
复制代码export default {
  // ...
  themeConfig: {
    // ...
    prism: {
      // ...
      additionalLanguages: ['bash']
    }
  }
};

注意，填 Prism 不支持的语言会导致运行时报错，从而白屏。更多内容可以看 Code Blocks - Supported Languages。

❓ 如何 include Markdown/MDX 代码片段？​

比你想象的简单，但仅支持在 MDX 中引别处的 Markdown 或 MDX，只需要 import，然后把它当成 React 组件进行渲染即可：

mdx

 体验AI代码助手
 代码解读
复制代码---
sidebar_position: 100
title: 变更历史
---

import Changelog from '../../../CHANGELOG.md';

<Changelog />

被 import 的文件，甚至不必须在文档项目目录下，比如以上的 CHANGELOG.md，其实位于 Monorepo 根目录下。

作者：驳是 链接：https://juejin.cn/post/7518188007541489704 来源：稀土掘金 著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。