1. 对比
1. 基于 jsdoc/tsdoc 自动生成文档
优点
无需单独维护文档
缺点
需要额外学习 tsdoc/jsdoc 规范（因为是直接使用注释+注解生成的，所以注释的质量决定了文档质量）
文档效果相对一般：TypeDoc - v0.25.3
文档更像是把各种符号（函数、变量、类型的名称）给以及彼此之间的关系列了出来。而不是一个完善的项目的文档。
页面格式比较固定，有不少意义不大的字段，而且不太好修改
搜索只能搜符号，不能搜正文
2. markdown 转文档平台（SSG）
参考：
- Static site generator market share, websites and contacts - Wappalyzer
- Static Site Generators - Top Open Source SSGs | Jamstack
下面这些他们自己的文档就是用的自己的工具渲染出来的。行为上都是 markdown -> 静态页面
都支持在文档里面使用一些 UI 框架去增强页面的交互能力。（目前应该用不到，但是小程序以外的 util 能力，基本都能直接在浏览器里面跑 ，想整个 playground 也可以直接用）
支持 vue 的
vuepress：v2.vuepress.vuejs.org/ （Vue2）
vitepress：VitePress | Vite & Vue Powered Static Site Generator
vitepress：vitepress.dev/ （VitePress is the spiritual successor of VuePress，Vue3）
docsify：docsify.js.org/ （支持 Vue2 Vue3）
支持 react 的
docusaurus：docusaurus.io/docs
其他
astro：docs.astro.build/zh-cn/getti… （偶然看到的 ，看起来好像不错。而且不依赖特定 UI 框架）
暂不考虑
gitbook：docs.gitbook.com/，看起来不是 SSG 的模式。而是导入外部仓库
gatsby：www.gatsbyjs.com/docs/ 没听说过，先不考虑了
nextjs, nuxtjs：二这倒是都支持 markdown 渲染，但毕竟主要是 SSR 框架，而不是专门生成文档的工具。
gatsby：www.gatsbyjs.com/docs/ 没听说过，先不考虑了
hexo, jekyll 等：虽然是预渲染生成静态文件的模式，但是这种主流更适合做博客，文档/wiki 的形式相对麻烦一些。（另外 jekyll(ruby), hugo(golang) 等不是纯前端技术栈的）
对比 vitepress, docsify, docusaurus
| 指标 | vitepress | docsify | docusaurus | |
|---|---|---|---|---|
| 创建 | CLI 工具直接创建。可以单独项目 ，或者和项目并存（只占用一个目录） | CLI 工具直接创建，不涉及写 package.json。随便一个位置都能放 | 单独仓库作为项目。他自己文件很多。 补充一句，编译需要大约 6s | |
| 文件索引（菜单/侧边栏） | 手动配置，不支持自动生成。有插件可以做到 auto sidebar mode · Issue #1297 · vuejs/vitepress · GitHub | 手写 _sidebar.md 或者docsify generate . -s _sidebar.md | 默认字典序自动生成。支持手动配置（[Autogenerated | Docusaurus](docusaurus.io/docs/sideba… |
| 文件内目录（TOC） | 默认、右侧 | 自动生成，指定最大层数 原生会和菜单显示在一起（侧边栏的子层级），需要插件来放到其他地方 | 默认自带，右侧显示 | |
| 多组文档 | 支持。在 config.mjs 里面分别配置 nav 顶部菜单，和不同路由的 sidebar | 不支持 | ||
| 配置项和配置方式 | .vitepress/config.mts | index.html 直接修改 window.\$docsify | 修改 ./docusaurus.config.js | |
| 全文检索 | 内置 localSearch，加一个参数就可以。无需其他变动 | 多引入一个 js 就行，其他可以默认配置。预先缓存全部页面到 localStorage（即首次访问会请求所有 md 文件） | 官方推荐 algolia（外部服务），其他是社区支持localSearch。目前工具已经 3.0.0 了，但是插件还是 2.x [Search | Docusaurus](docusaurus.io/docs/search) 没有进一步测试 |
| 纯文字文档是否需要写代码 | 不需要（除了搜索） | 不用（除了改配置） | 应该不用。用也是删东西（可能除了搜索） | |
| mdx | 不支持，但是可以在普通 md 文件插入 vue 组件 | 不支持。但是可以在普通 md 文件插入 vue 组件 | 默认支持 | |
| HMR | 支持 | 不支持。但是修改会自动刷新页面 | 支持 | |
| node 运行 | vitepress dev docs因为基于 vite，启动很快 | docsify serve docs（目测也就多了一个修改自动刷新，否则几乎没有区别） | npx docusaurus start走的 webpack dev server 启动有点慢（冷启大约 6s） | |
| SSR 部署(SEO) | SSG 可以满足 | 不需要 SEO 没啥意义。人阅读 CSR 就够了。 不过文档上有 SSR 支持，没测试 | SSG 可以满足 | |
| SSG 部署 | npx vitepress build docs | 无（另外，因为它的搜索是加载的 markdown 文件，所以可能也不适合标准意义上的 SSG） | npx docusaurus build。测试大约 13s | |
| 构建和部署 | SSG 产物直接部署 | 默认行为是 CSR（index.html 里面有加载 markdown 文件的逻辑，然后动态加载 markdown。部署是直接把 docs 目录作为静态资源就行） 走哈希路由 http://localhost:8081/#/proj/a?id=this-is-a-title | SSG 产物直接部署 | |
| 插件集合 | GitHub - docsifyjs/awesome-docsify: 💖 A curated list of awesome things related to docsify | |||
| 评价 | 侧边栏目录、多项目在单独仓库不太行 | 有点庞大，或者默认主题原因看起来比较重量级 侵入性强，不适合文档代码同仓库 |
3. 富文本平台
知识库
优点
只需要写文档，不用考虑任何其他内容。
缺点
受限于知识库的形式，没办法保证文档版本与代码版本的一致性。
例如说，代码从 1.0 -> 1.1，可以直接对照代码 diff 更新文档的仓库，然后打上同样的 tag。同样，文档也可以有一步 CR，检查是否有问题。采用知识库的话，文档没办法确定是否修改、改了多少，以及翻阅历史版本文档。
