使用 Zeal 打造属于自己的文档

墨蓝 2021-07-31 14:50 506阅读 0赞

![640?wx\_fmt=jpeg][640_wx_fmt_jpeg]

## **前言**    ##

技术博文征文比赛进行中，人人都可以参与，具体参与方式点击此链接：

## **正****文** ##

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

那么有没有一个工具，即可以让我们方便查阅文档，又可以把自己日常用到的资料存起来的工具呢，下面就来介绍一下 Zeal 这一离线文档工具。

![640?wx\_fmt=other][640_wx_fmt_other]

## **Zeal 简介** ##

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

Zeal官网：zealdocs.org/

Zeal下载：zealdocs.org/download.html

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

![640?wx\_fmt=other][640_wx_fmt_other 1]

> 除了在 Zeal 的官网上面下载 Docsets 之外，还能通过 Add Feed 来添加。国外有热心的开发者收集了一个Docsets 集合（zealusercontributions.now.sh），我们只需要点开自己需要的 Docsets，复制 xml 地址到 Add Feed 里面，就可以对应下载 Docsets 了。

下载好自己需要的 Docsets 之后，日常就可以在工作中使用离线文档进行工作了。日常使用过程中，有几点需要注意：

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

![640?wx\_fmt=png][640_wx_fmt_png]

## **Zeal 创建自己专属的文档项目** ##

经过上面的步骤后，这个文档系统已经可以很好地为我们日常开发服务了，但是除了下载常用的 api 文档之外，能不能编写我们自己的文档呢？

Zeal 官方写了一个教我们如何去编写自己的 Docsets 的文档（https://kapeli.com/docsets），但是该文档写得比较简单，并且没有详细地操作指引，操作起来比较复杂。

经过实验之后，Zeal 的 Docsets 其实是 html 的集合，那么我们可以先用文档工具，生成一些静态的 html 文档。然后通过 Docsets 官方提供的 Docsets 生成器来把 html 生成 Docsets，这样就可以生成出属于我们自己的 Docsets 了。

### **合适的文档生成器** ###

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

> D oc sify 是一个很棒的生成器，但是用于 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` 即可看到文档的样式：

![640?wx\_fmt=other][640_wx_fmt_other 2]

接下来就是每个开发者根据自己的需要，编写自己的 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 就可以看到自己的文档了。

![640?wx\_fmt=other][640_wx_fmt_other 3]

## **结语** ##

以上是我在工作过程中，根据自己的开发习惯所做出来的一个小文档，如果大家有其他方便的工具，可以一起讨论一下，有任何问题欢迎留言。

**推****荐****阅****读**

***1.***

***2.***

***3.***

***4.***

![640?][640]

[640_wx_fmt_jpeg]: /images/20210731/681dfeca849b41a5a85a57aa6c444b1b.png?wx_fmt=jpeg
[640_wx_fmt_other]: /images/20210731/ddb9da9dd29748b684a94f35183830fd.png?wx_fmt=other
[640_wx_fmt_other 1]: /images/20210731/b6e084a54aef40b580a1af86aef50aeb.png?wx_fmt=other
[640_wx_fmt_png]: /images/20210731/9862359f3d7f44acb01b806ee54708b7.png?wx_fmt=png
[640_wx_fmt_other 2]: /images/20210731/265897cb0ef34d9982833b98601ef19e.png?wx_fmt=other
[640_wx_fmt_other 3]: /images/20210731/b12c28b5c01a44a592f48960bf3bacf9.png?wx_fmt=other
[640]: /images/20210731/01725e3f32d0452f93d46db11cd37508.png?