使用 Zeal 打造属于本身的文档

引言

做为一名程序开发者，翻查文档成为了天天都必须去作的事情。然而，因为使用到的知识和工具不相同，因此几乎每次都须要从新打开官网的文档进行搜索，并且不一样知识和工具的文档还须要切换浏览器标签来浏览，十分不方便。再进一步，咱们工做中，所用到的一些帐号、密码以及平常的一些小知识点，若是概括总结以后，可能也只是放在 word 或者 txt 里面，查阅也是比较不方便的。

那么有没有一个工具，便可以让咱们方便查阅文档，又能够把本身平常用到的资料存起来的工具呢，下面就来介绍一下 Zeal 这一离线文档工具。

Zeal 简介

Zeal 是一款免费的离线文档软件，可以让开发者更加便捷地查阅api文档。目前该软件有 windows、mac 以及 linux 版本，内部有超过 200 个文档，涵盖了几乎全部程序开发用到的库、框架以及语言，是一款十分实用的软件。

Zeal官网

Zeal下载

下载安装完成以后，界面上是看不到任何的文档的，由于须要去下载文档（Zeal 中文档的格式称为 Docsets）。在首页上面按下 Docsets 或者 Tools -> Docsets，选择你想要的文档进行下载，下载完成后就能够看到你所须要的文档了。

除了在 Zeal 的官网上面下载 Docsets 以外，还能经过 Add Feed 来添加。国外有热心的开发者收集了一个 Docsets 集合，咱们只须要点开本身须要的 Docsets，复制 xml 地址到 Add Feed 里面，就能够对应下载 Docsets 了。

下载好本身须要的 Docsets 以后，平常就能够在工做中使用离线文档进行工做了。平常使用过程当中，有几点须要注意：

• Zeal 原理是打开 html 的页面，因此它至关于一个浏览器，尽可能养成定时关闭不用文档的习惯
• Zeal 可以设置打开的快捷键，设置了以后就能快速打开 Zeal 查阅文档
• Zeal 左上角具有搜索功能，在前面输入“文档名称:内容”就能够对指定的文档进行搜索

Zeal 建立本身专属的文档项目

通过上面的步骤后，这个文档系统已经能够很好地为咱们平常开发服务了，可是除了下载经常使用的 api 文档以外，能不能编写咱们本身的文档呢？

Zeal 官方写了一个教咱们如何去编写本身的 Docsets 的文档，可是该文档写得比较简单，而且没有详细地操做指引，操做起来比较复杂。

通过实验以后，Zeal 的 Docsets 实际上是 html 的集合，那么咱们能够先用文档工具，生成一些静态的 html 文档。而后经过 Docsets 官方提供的 Docsets 生成器来把 html 生成 Docsets，这样就能够生成出属于咱们本身的 Docsets 了。

合适的文档生成器

目前各类开发语言都有文档生成器，我比较熟悉的 Node.js 生成器就有数十个像 Gitbook、Docsify、Vuepress 等等。可是并非每个都适合用来制做 Docsets，举个例子：

Docsify 是一个很棒的生成器，可是用于 Docsets 的话就会有问题。缘由是由于 Docsify 是经过 js 读取 Markdown 来实现的，而 Zeal 内部是一个浏览器，并无静态服务器，因此制做出来的 Docsets 会出现跨域的问题。

最终我选择了使用 Gitbook 来制做 Docsets，它能生成静态的 Html 文件，而且可以经过本地双击打开，可以跟 Zeal 完美融合。

编写文档

肯定了使用 Gitbook 以后，先安装 Gitbook： npm install gitbook-cli -g

而后，使用 Gitbook 建立项目： gitbook init

建立完以后，会看到以下目录结构：

├── README.md
├── SUMMARY.md
├── chapter1
│   ├── README.md
│   ├── section1.1.md
│   └── section1.2.md
└── chapter2
    └── README.md
复制代码

建立完成以后，经过命令 gitbook serve 便可看到文档的样式：

接下来就是每一个开发者根据本身的须要，编写本身的 markdown 文件和修改 SUMMARY.md。因为文档是离线的，因此不用担忧会被其余人盗取，能够把平常用到的帐号密码、代码片断、经常使用的资料都分类写进去。

写完以后，经过命令 gitbook build 生成 html 文件。生成后会见到一个 _book 的目录，全部的 html 文件都在里面，这样文档就算编写完成了。

把 html 生成 Docsets

有了文档对应的 html 以后，须要把 html 生成 Docsets。我使用 Node.js 生成，在 npm 上面找了一个叫 docset-generator 的插件。经过如下代码，便可生成对应的 Docsets：

let DocSetGenerator = require("docset-generator").DocSetGenerator;
let docSetGenerator = new DocSetGenerator({
  destination: "./output/",
  name: "Season",
  documentation: "./personal-doc/_book",
  icon: './icon.png',
  entries: [ // entries 能够设置 Docsets 的分类，通常一个分类对应一个 html
    {
      name: "我的资料",
      type: "Guide",
      path: "./index.html"
    },
    ...
  ]
});
docSetGenerator.create();
复制代码

这里我把 Gitbook 和 docset-generator 整合到一个项目中，经过 npm-run-all 插件，先调用 Gitbook 生成 html，而后再生成 Docsets：

...
"scripts": {
  "start": "gitbook build ./personal-doc && node index.js"
},
...
复制代码

生成完以后，将会获得一个 XXX.docsets 的文件夹，接下来就是最后的一步，把这个文件夹放进 Zeal 里面。

在 Zeal 里面有一个叫 docsets 的文件夹，进去以后会看到下载的 docsets 都在里面，把刚刚生成的 docsets 放进去，重启一下 Zeal 就能够看到本身的文档了。

结语

以上是我在工做过程当中，根据本身的开发习惯所作出来的一个小文档，若是你们有其余方便的工具，能够一块儿讨论一下，有任何问题欢迎骚扰~