静态文档或网站生成器Hexo、Gitbook、Vuepress、Docsify、Docute、Nuxt

GitBook在不久前改版了,新版本向着商业化、平台化运作了,而作为开源工具的CLI也不在提供了(Gitbook V2 Important differences),查找静态网站生成器代替方案记录如下。

1、Hexo

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown(或其他渲染引擎)解析文章,在几秒内,即可利用靓丽的主题生成静态网页。
Hexo 配合他的主题模块,比如Next主题,可以作为非常简洁方便的静态博客系统。
 

2、Nuxt

Nuxt.js 是一个基于 Vue.js 的通用应用框架。通过对客户端/服务端基础架构的抽象组织,Nuxt.js 主要关注的是应用的 UI渲染。Nuxt.js 的目标是创建一个灵活的应用框架,你可以基于它初始化新项目的基础结构代码,或者在已有 Node.js 项目中使用 Nuxt.js。
Nuxt 更像是为构建应用程序而生的,而不是独立的内容静态网站。
 

3、Docsify

docsify是一个很好的选择,前提是你是拿来建文档(简单的blog也行)。但hexo-theme-sakura文档不是用它建的,并是不它不好,只是那时候看只是部分文档,还以为它没有导航栏。而且发现中文文档都是404页面,官方的文档也没有使用导航栏(单一个语言选框没看出来是导航栏)。后来有心想把这几个文档成生器折腾个demo出来给大家快速使用,才重新去折腾docsify才发现其英文文档的详细。
Docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行。
Docsify是基于 Vue,完全的运行时驱动,不需要渲染html,所以对 SEO 不够友好。如果不关注 SEO,安装简单化不想有大量依赖,他是比较好的选择,比如公司或这团队内部的文档系统。
不要觉得它的使用文档多,多说明两点:

  1. 写的详细,解释详细了那就更容易上手。
  2. 功能多,更强大。

你只要按照文档一步一步边看边学习下来,到最后,你就会发现你的文档网页开发好了,同时也会用docsify了。

总结:

适合所有人。文档详细(仅限英文文档),体积小,star多,功能多;运行时驱动,只要负责改md就行;自带站内搜索。
 

4、Docute

Docute 本质上就是一个 JavaScript 文件,它可以获取 Markdown 文件并将它们呈现为单页面应用。
它完全由运行时驱动,因此并不涉及服务端组件,这就意味着没有构建过程。你只需创建一个 HTML 文件和一堆 Markdown 文档,你的网站就差不多完成了!
Docute 与Docsify 基本一样,只是在文件大小和UI 及不同的使用方式,Docute网站有其差异介绍。
强烈推荐docute@3,不要问为什么。就是3版本。如上图你所见的就是它的首页。
文档简单,hexo-theme-sakura文档就是用它建的,当然最简单的就是copy官方的。老实说一开始有给这三个文档生成器整快速上手demo的念头,就是copy docute官方文档的时候涌现的。没错,docute的文档是很简单了,但哪有用demo并直接在上改改配置就能用方便。但是有个遗憾的地方就是docute没有本地搜索功能,用的是DocSearch,是一个algolia.com提供的免费搜索服务,所以你要用搜索还要注册啥的折腾下。

总结:

简单,文档简单,体积小,运行时驱动,只要负责改md就行;DocSearch第三方搜索。
 

5、GitBook

GitBook 是一个现代的文档平台,团队或个人可以在其上编写产品、API接口文档以及团队内部知识库。
GitBook 改版之后,感觉的团队更专注于商业产品而不是开源工具,同时CLI工具不再提供了,所以无法实现个性化部署,所以不做介绍,有兴趣的可以看其官网。
 

6、VuePress

VuePress 是基于Vue开发的平台,功能上实现了GitBook功能。这是一开始的选择,老实说官方使用文档写的不是很走心。(太多内容放在开发上面了,没有让人单纯的负责写作就好)
VuePress 展示页面与Docsify类似,但是与Docsify不同的是,预先渲染html。
然后你要做成官方文档那种有导航栏、侧边栏的就要自行参考这个目录结构
与其说是推荐还不如直白的说目录如下(或者直接帮忙建好),目录建好后还要看这篇文档:默认主题配置,才能加上导航栏、侧边栏等。(当然加起来也不是那么简单的)
搭的差不多了才发现vuepress是直接生成静态页面的模式,如果拿来搭建文档的话不能够直接在仓库里更新文档。当然你可以用第三方持续集成自动编译,但是好麻烦~。

总结:

不适合小白入门,当然你有大把时间折腾的ok。特点:生成静态页面,seo友好,速度快。改md后还要花时间生成,比较复杂,适合diy,可以折腾成blog,自带站内搜索。
 
 

最后也是最棒的

不多说,Vuepress、docsify、docute的快速上手demo同步上传在github仓库和百度云上,使用教程待续……

发表评论