给项目补文档，最开始的需求通常很简单：写几页安装说明，再放几个使用示例。
等内容多起来，问题就出现了。README 越写越长，旧版本和新版本的用法混在一起，想找一个配置项还得反复翻页面。好不容易搭了个文档站，发现组件演示、全文搜索、多语言又要一个个补。
那么，能不能一开始就选一个合适的工具？
这次我整理了十套开源方案，从 VitePress、dumi，到面向完整产品文档的框架。重点看三件事：内容怎么写、能力怎么扩展、以后怎么维护。默认主题好不好看也会看，但它不能替我们决定整个项目的方向。
资料与截图核实日期：2026 年 11 月 6 日。这里的 Top 10 是按项目影响力、公开维护记录和用途覆盖整理的选型清单，序号为阅读顺序。MkDocs 与 Material for MkDocs 合并算一套方案。本文基于官方文档、仓库和实际页面观察，并运行了一个 VitePress 颜色交互示例。其他机制图均标为示意，安装、构建速度和长期运行效果不在本次比较范围内。
先想清楚，我们要生成什么
本文讨论的是把 Markdown、MDX、代码注释等资料，组织成可以浏览、搜索和部署的文档网站。
如果只看最终页面，这些工具似乎差不多：左边目录，中间正文，右边当前页面的标题。但背后的工作方式差别挺大。
多数方案会在构建时生成 HTML，然后把产物部署到静态托管服务。docsify 则直接在浏览器里加载和解析 Markdown。Nextra、Fumadocs 又可以借助所在框架，把文档和应用放在一起，是否需要运行服务器取决于具体配置。
选择前，我建议先回答三个问题：
主要写什么？ 是文字教程、组件示例，还是从代码注释生成的 API 手册？
哪些功能现在就需要？ 搜索、多语言、多个产品版本，还是交互式演示？
谁来维护？ 熟悉 Vue 的个人开发者、React 团队，还是已经有 Python 文档流程的项目？
比如我们要写一个小工具的文档，内容包括“安装、快速开始、配置项、常见问题”。先让这四部分能写、能找、能部署，就已经解决了主要需求。只有真的出现旧版本兼容、多个语言维护等问题时，再增加对应的复杂度。
下面这张表先用来缩小范围，具体取舍再往下看。
01 · VitePress
截图：VitePress 官方介绍页。
VitePress 的路径很直接：写 Markdown，套用主题，生成静态 HTML。默认主题已经把导航、侧边栏、正文目录等文档站常见部分安排好了，适合从前面那四页小工具文档开始。
比较有意思的是，每个 Markdown 页面也可以作为 Vue 组件处理。普通段落照常写，需要交互时再引入 Vue 组件。比如讲一个颜色配置项，可以在说明旁边放一个颜色选择器，让读者直接看到变化。
光说“支持 Vue”，还是有点抽象。这里我用 VitePress 1.6.4 做了一个小例子：.md 文件负责标题和说明，再引入 ColorPicker.vue。左边放关键源码，右边就是同一页文档中的运行效果。
本地运行截图：Markdown 中的 <ColorPicker /> 对应右侧交互区。紫色是组件的初始值。
看左下角的两处绑定就好：v-model="color" 把颜色输入连到组件状态，:style 再把这个值连到按钮样式。标题和边框也绑定了同一个值，所以切成绿色后，它们会一起更新。
本地运行截图：当前值变为 #18836b，标题、边框和按钮同步变化。本次也检查了原生颜色输入与预设按钮都能更新状态。
到这里，“文档里加交互”就具体了：读者一边看配置说明，一边验证颜色会影响哪些元素。普通说明继续用 Markdown 写；要演示的那一小块，再用 Vue 处理。截图左侧保留了这个例子的关键源码，颜色输入、组件状态和样式之间的对应关系可以一起对照。
搜索方面，默认主题提供基于 MiniSearch 的本地全文搜索，启用 local provider 即可；也可以接入 Algolia DocSearch。多语言需要配置不同语言的内容与导航，翻译本身仍然要有人维护。
它比较贴合“文字说明为主，偶尔补一点交互”的需求。若要自动生成复杂 API 手册，或把多个产品版本一起维护，还需要补充自己的流程。尤其是组件 demo 的隔离、源码展示等需求，不能只因为 Markdown 能放 Vue 组件，就认为整套组件研发能力已经齐了。
这次官网展示的是 2.0.0-alpha.21，版本菜单也保留了 1.6.4 入口。建站时要确认采用哪条版本线，避免把 alpha 文档里的能力直接套到旧版本上。
02 · dumi
截图：dumi 官网。
如果我们的文档对象是一套组件库，光写参数说明还不够。读者往往想先点一下按钮、切一下状态，再看看这段效果对应什么代码。
dumi 就围绕这件事展开。官方支持把 JSX、TSX 代码块解析成 React demo，也支持引用外部 demo 文件。示例复杂起来时，可以把代码留在独立文件里，文档负责组织说明，读者仍然能查看对应源码。
截图：官方 demo 指南。上面是渲染后的 Hello dumi!，下面是对应 JSX；代码同时承担示例和效果演示。
对组件库文档来说，这样放在一起很实用。读者先确认是不是自己要的效果，再看怎么调用组件，就不用在一张图片和另一个源码文件之间来回找。
它还提供内置全文搜索，标题、正文和 demo 都在覆盖范围内；主题系统、组件资产元数据和与 father 的集成，也都偏向组件研发场景。相比只有几篇文字说明的站点，组件库更容易用上这些能力。
这里有两个需要提前看清的条件。首先，自动 API 表格目前在官方文档中仍标为实验性：基于 JSDoc 和 TypeScript 类型解析 React 组件，需要开启配置；文档还明确写了顶层属性、多语言描述，以及 Windows 环境方面的限制。其次，Vue 3 支持通过 @dumijs/preset-vue 插件集提供，相关页面同样标注了实验性。
截图：自动 API 表格指南。上方 title?: string 与注释，对应下方的属性名、描述、类型和默认值；Markdown 用 <API id="Foo"></API> 引入表格。
这张图可以帮助我们分清两件事：demo 让读者看到组件效果，API 表格把解析出的属性说明列出来。后者要先配置解析器和入口文件，再确认生成结果是否完整。
所以我会优先把 dumi 放进 React 组件库的候选名单；只有文字教程时，它的组件研发能力未必是必需的。如果要依赖自动 API 表格，先拿项目里一个真实组件验证解析结果，会比看展示页更有帮助。
项目入口：官网 · 仓库 · MIT。参考：写组件 demo、自动 API 表格、Vue 支持。
03 · Docusaurus
截图：Docusaurus 官网。
小工具的配置项比较稳定时，维护一份最新文档就够了。但如果产品的 v1、v2 同时有人使用，同一个参数在两个版本里还有不同含义，这时版本管理就成了实际需求。
Docusaurus 提供文档版本机制：把某一阶段的文档与侧边栏保存为独立版本，让最新内容继续演进。它也提供多语言支持和博客能力，适合把使用指南、版本说明、更新文章组织成一个完整站点。
机制示意：根据官方版本管理说明绘制，文件名与版本号为例子。
可以把它理解成给文档留一个当时的状态。左边的当前内容继续改，v1 的正文和目录则保存在对应版本文件里；读者选 v1 时，看到的就是这套说明。版本选择器背后有实际内容副本，后续修正文档时也要考虑哪些版本需要一起改。
正文使用 Markdown、MDX，可以嵌入 React 组件，页面和布局也能用 React 扩展。对已经熟悉 React 的团队来说，这些定制方式比较容易接上现有开发习惯。
搜索要单独看。官方优先支持 Algolia DocSearch，需要配置服务和索引；本地搜索是官方文档列出的社区方案。不能看到官网有搜索框，就默认安装后已经拥有一套不依赖外部服务的搜索。
版本功能也会增加内容副本和构建成本。官方自己就建议只在需要时开启，并控制维护的版本数量。对于前面只有四页的小工具文档，我会先维护单版本；当用户确实需要查旧版用法时，再启用它的版本机制。
项目入口：官网 · 仓库 · 代码采用 MIT。参考：版本管理、搜索方案。
04 · docsify
截图：docsify 官网。
docsify 的特点是省去预先生成 HTML 的步骤。浏览器打开入口页面后，动态读取 Markdown，再把内容显示出来。官方快速开始围绕 index.html、README.md 等文件展开，可以部署到 GitHub Pages 等静态托管环境。
简单理解一下，修改源文件之后，更新的是读者浏览时会读取的 Markdown。对几页项目说明、一个小型知识库来说，这样的流程比较轻。
流程示意：上面在构建时生成 HTML，下面由浏览器运行 docsify 后请求并解析 Markdown。
图里的关键差别是“解析在哪儿发生”。前者把生成好的页面交给托管环境；后者把入口、脚本和 Markdown 放上去，由读者的浏览器完成正文呈现。这也解释了为什么 docsify 的发布流程简单，但阅读时仍需要相应脚本与源文件能够加载。
它有主题和插件机制，全文搜索通过插件提供。但少了构建步骤，并不意味着什么都不用维护：侧边栏、导航、插件版本、脚本的加载地址，依然属于站点的一部分。
浏览器端解析也带来边界。页面正文的呈现依赖 JavaScript 和 Markdown 请求，SEO、无脚本阅读，以及网络失败时的表现，都需要结合自己的用途评估。若内容需要稳定地以预生成 HTML 交付，我会更倾向于清单里的构建型方案。
docsify 适合先把小规模内容变成可浏览的网站。文档规模扩大后，要重新检查搜索索引、插件组合和页面加载流程，不能只凭“没有构建”判断它长期一定更省事。
05 · mdBook
截图：mdBook 官方文档。
有些内容的阅读顺序很重要。比如一份入门教程，先讲安装，再讲基本概念，最后才进入进阶配置。它更接近一本书，目录就是学习路径。
mdBook 是用 Rust 编写的命令行工具，使用 Markdown 创建这种章节式内容。SUMMARY.md 定义目录和章节层级，构建后得到带目录、章节导航和搜索的页面。上面的官方文档本身就是一个例子。
机制示意：左边是示例目录文件，右边是对应导航；“颜色”缩进一层，就成为“配置项”下的章节。
我们不需要另外手写一份页面菜单。先把章节文件写好，再在 SUMMARY.md 里安排阅读次序；调整链接的位置和层级，目录也跟着这条学习路径组织。
它提供代码高亮、主题定制，以及预处理器和其他输出后端的扩展方式。对 Rust 教程还有一个实际优势：mdbook test 可以检查 Rust 代码示例。不过这个能力不能直接理解成所有语言的代码块都会自动验证。
如果我们的四页说明逐渐变成一套从基础到进阶的教程，mdBook 就很合适。若目标是组件展示、复杂产品首页，或多个语言与产品版本同时管理，需要额外组织工具和发布流程。
写内容的人不必因为工具使用 Rust 就先学会 Rust。真正需要接受的是它以“书和章节”为中心的组织方式。内容符合这种结构，维护起来才会顺手。
项目入口：官方文档 · 仓库 · MPL-2.0。参考：目录文件、代码示例检查。
06 · MkDocs + Material
截图：Material for MkDocs 官网，首页明确显示维护期限。
这一套要分两层理解：MkDocs 负责把 Markdown 文档构建成网站，常见配置集中在 mkdocs.yml；Material for MkDocs 提供主题、内容呈现和配套能力。
它适合喜欢用 Markdown 和 YAML 管理内容、希望少写前端页面的人。搜索、代码注释、内容标签页、提示块等能力，让技术说明可以写得比较丰富。插件还能继续补充需求，例如版本发布可与 mike 配合。
截图：内容标签页指南。上方用 === "C++" 声明分组，下方点击 C++ 标签后展示对应代码。
比如同一个操作要给出 C 和 C++ 两种写法，就可以放进这组标签页，让读者只看自己需要的语言。它需要在 mkdocs.yml 中配置对应 Markdown 扩展；图片展示的是官网配置好的效果。
但是，现在推荐它必须补上一条维护信息。截至本次核实，Material 官网明确写着 “End of life on May 5, 2027”，并说明关键维护将持续到 2027 年 5 月 5 日。 团队提供了后继项目 Zensical 的兼容与迁移入口。这个日期针对 Material for MkDocs，不能直接推成 MkDocs 核心的同一停止维护日期。
我的取舍会分开：已有 MkDocs + Material 站点，可以先继续维护内容，整理插件和自定义主题，再评估迁移；从零建设、准备长期维护的新站点，则需要把这条生命周期信息放到选型前面，连同维护成本一起考虑。
它仍然值得出现在清单里，因为不少已有项目正在使用这套方案。只是放在 2026 年讨论，不能只照着旧推荐文章写“成熟、功能多、直接选”。
项目入口：MkDocs · Material · 核心仓库 · 主题仓库。MkDocs 为 BSD-2-Clause，Material 为 MIT。参考：版本发布、官方迁移入口。
07 · Nextra
截图：Nextra 官网。
如果已有网站使用 Next.js，单独再维护一个完全不同的文档工程，往往会多出一套布局、路由和发布流程。Nextra 的价值就在于把 Markdown、MDX 内容与 Next.js 的页面能力结合起来。
它提供文档主题，包含导航、目录、深浅色模式等常见界面；官网也明确介绍了基于 Pagefind 的全文搜索，在构建时建立索引。需要交互内容时，可以在 MDX 里使用 React 组件。
内容组合示意：MDX 写说明并引入 React 组件；右边表示两类内容在同一页中的关系。
还是前面那个颜色配置例子，说明段落留在 MDX，状态和事件放进 React 组件。与 VitePress 的思路相近，接入的组件体系换成了 React。已有 Next.js 工程时，还要按其规则处理客户端交互组件。
这条路径适合让文档区沿用网站已有的组件、样式和布局。官方还提供多语言和静态导出的相关指南，具体采用静态生成还是其他渲染方式，要回到 Next.js 的配置与功能限制上判断。
需要承担的成本也来自这层关系。Next.js 的路由、服务端与客户端组件边界，以及版本兼容，都可能成为文档工程的一部分。只为了放几页文字而新引入整个应用框架，未必划算。
所以我会优先推荐已有 Next.js 项目评估 Nextra。对独立的小型文档站，则先比较自己的定制需求，看看是否真的需要这层应用能力。
08 · Fumadocs
截图：Fumadocs 官网。
Fumadocs 也常出现在 React 文档项目里，但它强调可组合的结构。官方把它解释为 UI、Core 和 Content Source 的组合，各层可以单独承担职责。
职责示意：根据官方架构说明绘制，箭头表示内容与能力的衔接。
先看内容从哪里读进来，再看文档能力怎样组织，最后看读者使用什么界面。这样拆开之后，换内容源、调整导航和定制页面就有了各自的位置；图中的分层表达职责，具体接法仍要回到项目配置。
这个设计比较适合已经有产品工程、愿意写代码定制页面的团队。内容可以来自 MDX 或其他接入的来源，页面与产品组件结合，导航和展示逻辑也可以继续调整。当前官网列出了 Next.js、React Router、TanStack Start、Waku、Astro 等接入入口，不能再把它简单限定为一个 Next.js 主题。
如果文档还要包含接口说明，官方 OpenAPI 集成值得看：可以从规范生成 API 页面，呈现参数、响应示例和交互式请求体验。它需要安装与配置对应集成，并不是新建项目后所有能力就自动开启。
截图：官方 OpenAPI 示例。左边是 planetId 参数和响应结构，右边是 cURL 请求与示例响应；Try in Playground 是交互入口。
这张图就比一句“支持 OpenAPI”直观了。参数类型、响应字段和请求示例被组织到同一个接口页面里，读者不用自己把几份资料拼起来。本次观察了页面展示，没有发送示例接口请求。
部署方面也有一个条件。官方静态构建指南说明，默认采用服务端优先的方式；要输出静态站点，需要配置所在框架，并调整内置搜索的服务端与客户端配置，让索引静态保存、搜索在浏览器计算。
我会把它放在“文档需要像产品的一部分那样被开发”的场景里。自由度高，意味着团队也要维护相应代码。只想改几个导航标题就上线的人，可以先看默认流程更集中的方案。
项目入口：官网 · 仓库 · MIT。参考：架构说明、OpenAPI、静态构建。
09 · Astro Starlight
截图：Starlight 官网。
Starlight 是 Astro 的文档方案，站点导航、搜索、多语言、代码高亮和深浅色模式都在它的基础能力范围里。对一个独立文档站来说，这些已经覆盖了不少常见需求。
内容可以使用 Markdown、MDX 等格式；要接入其他 UI 组件，也能沿用 Astro 的集成能力。这里要分清“可以扩展”和“已经集成”：使用 React、Vue 等组件时，仍需按所选集成的规则配置。
我比较看重它的出发点：先提供完整的文档阅读框架，再让开发者按需求扩展。如果已有 Astro 网站，它也值得优先评估，减少在两套工程之间维护相同页面元素的工作。
需要多语言时，除了界面配置，还得安排翻译内容、导航和更新流程。需要多个产品版本时，也要进一步评估插件或自己的组织方式。基础功能齐全，不代表文档内容的维护流程已经自动解决。
截图：官方多语言指南。右上角已选择简体中文，正文和导航对应切换到中文内容。
观察这张图时，可以同时看三个位置：语言选择器、左侧导航和正文。完整的多语言体验要把它们一起安排好。Starlight 提供相应机制，我们仍然要准备每种语言的文档；选择语言不会自动替项目完成翻译。
对于前面那个“安装、快速开始、配置项、常见问题”的站点，我会把 Starlight 和 VitePress 放在第一轮候选里，再按现有技术栈和交互需求决定。
10 · Sphinx
截图：Sphinx 官方文档。
如果主要文档对象是一个 Python 库，函数签名、类的方法和代码注释都在不断变化，纯手写 API 页面很容易漏改。Sphinx 的方向更贴近这种结构化技术文档。
它支持章节、图表、代码对象之间的交叉引用，也可以借助 Intersphinx 连接其他项目的文档。内置的 autodoc 扩展能从 docstring 中引入 API 说明，但需要显式启用，并保证构建环境可以导入相关模块。
机制示意：Python 模块、conf.py 配置和 .rst 指令共同参与构建，右边表示 API 文档会包含的内容。
看这个小例子，函数叫什么、接收什么参数，来自代码；“设置主题强调色”来自 docstring。文档里的 automodule 指令负责把模块内容引入，再由主题呈现。这样能减少重复录入，但模块能否被构建环境导入、哪些成员应当公开，仍要由项目配置保证。
内容通常使用 reStructuredText；希望使用 Markdown 时，官方给出的方式是安装并配置 MyST-Parser。它还能输出 HTML、LaTeX、ePub 等格式，PDF 流程则需要配套的 LaTeX 工具。
代价是文档工程本身需要一些学习。配置、指令、引用规则、构建依赖，都要逐步弄清楚。若需求只是几页普通工具说明，这套能力可能暂时用不上。
但当目标变成“让 API 文档跟着代码更新，同一份资料还要生成网页和其他格式”时，Sphinx 就很有竞争力。选它的理由应该落在这些内容关系与输出要求上，而不是只比较默认首页。
项目入口：官方文档 · 仓库 · 默认代码许可证为 BSD-2-Clause，个别文件以自身说明为准。参考：Markdown 配置、autodoc、许可证原文。
到这里，怎么缩小到一个选择
十套都看完，没必要再为每个项目记一遍功能清单。回到一开始的内容和维护者，范围就会缩小很多。
独立技术文档，文字为主： 先比较 VitePress、Starlight；Vue 交互需求偏多时优先看 VitePress，已有 Astro 工程时优先看 Starlight。
React 组件库： 优先评估 dumi，重点验证自己的 demo 与类型能否按预期工作。
多个产品版本和语言： 优先评估 Docusaurus，同时决定哪些版本真的值得长期维护。
已有 Next.js 网站： 看 Nextra；如果需要更细的页面组合和 API 集成，再评估 Fumadocs。
小型说明站，想省去 HTML 构建： 看 docsify，同时确认浏览器端解析符合阅读和部署需求。
连续章节教程： 看 mdBook；Python API 和复杂引用： 看 Sphinx。
已有 MkDocs + Material： 先整理现状与迁移计划，结合官方维护期限安排后续工作。
如果还是犹豫，可以把同一份真实内容放进两套候选里：一页安装说明、一页带代码和图片的教程、一页配置项，再加一个稍长的目录。
不要只停留在首页预览。接着看修改一段内容是否方便、搜索能否找到术语、手机上是否好读、构建产物能否部署到准备使用的平台。若确实需要多语言或版本管理，就把它也放进这个小样本里验证。
文档工具决定了我们怎样组织和发布内容。最终读者关心的，还是能不能找到答案，以及按说明操作能不能成功。先选一套自己能持续维护的方案，把这两件事做好，后面的扩展才有意义。
评论