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