那些开箱即用的在线文档方案

2,784 阅读3分钟

对于程序员来说,不可避免的需要写一些文档,这里介绍几种常见的在线文档技术方案。

VuePress

VuePress是一个Vue驱动的静态网站生成器,它有灵活的主题配置和插件系统,支持国际化和文档搜索,同时还支持Vite和Webpack构建,大概长下面这个样子

image.png

VuePress本质上是用Vue和Vue Router驱动的单页面应用,通过文件目录结构来生成页面路由的。

路由会根据你的 Markdown 文件的相对路径来自动生成。每个 Markdown 文件都通过 markdown-it 编译为 HTML ,然后将其作为 Vue 组件的模板。

如果不知道怎么使用的话,可以参考VuePress网站源码

VitePress

VitePress也是一个Vue驱动的静态网站生成器,与VuePress不同的是首先是页面布局不太一样,VitePress把左侧菜单靠近中间(我觉得还是VuePress那种好看🤣),并且右侧多了个标题锚点

另外一个不同的是,使用npx vitepress init的时候,会初始生成一个左侧菜单和顶部导航,更加容易配置。初始化后,就是下面这种样子

image.png

nextra

nextra是一个基于Next.js和MDX的网站生成工具,也是通过文件路径生成路由的。支持.md.mdx文件

为了快速开始,可以直接克隆一个模板项目

git clone https://github.com/shuding/nextra-docs-template.git

然后执行npm inpm run dev即可出现如下图所示页面

image.png

dumi

dumi是一个为组件研发而生的静态站点框架,当前只适用于React。一些常见的阿里系开源组件框架网站就是用dumi搭建的,比如ahooksUmiJSProComponents等。

以前V1版本是长这样的

image.png

现在是这个样子的 image.png

Docusaurus

Docusaurus也是一个基于React的一个静态站点生成工具,使用起来也是非常简单的。

// 使用脚手架搭建my-website的项目
npx create-docusaurus@latest my-website classic

// 运行
cd my-website  
npm run start

运行后,如下图所示

image.png

image.png

React NativeJest的官网就是用Docusaurus搭建的

总结

如果团队的技术栈主要是使用Vue的话,可以使用VuePress或者VitePress; 如果是使用React作为技术栈的话,可以使用Docusaurus或者是nestra, 如果是组件文档的话,我觉得dumi是最好的选择。

其它

上面只是一些开箱即用的在线文档技术方案,对于一些应用或者公司官网来说,还需要考虑网站的SEO、页面性能和网络请求等方面。这时可以采用下面的几种技术框架。

1.Gatsby

Gatsby 是一个基于 React 的免费、开源框架,用于帮助 开发者构建运行速度极快的 网站 和 应用程序airbnb就是用Gastby搭建的

2. Next.js

Next.js也是一个基于React的开源框架,它支持SSG和SSR两种模式。现在最新的React官网就是用Next.js搭建的

3.Nuxt

Nuxt是一个基于Vue的开源框架,它也支持SSR,对于使用Vue技术栈的人来说,是一个不错的选择

其它的像WordPress、Hugo等就不一一列举了😐,下面说出你们最喜欢哪种在线技术文档😁