最初认识zeal是在微信公众号里安利了这款工具,进一步了解之后才知道原来这就是我一直要找的api搜索文档工具。平时做项目整理或者归纳的东西都可以在这个工具上查阅和存档。
先下载来试试手!
一、进入官网下载工具 Zeal官网
二、选择64位
三、安装
四、桌面快捷方式打开
五、下载文档(Zeal中文档的格式称为 Docsets)
在首页上面按下 Docsets 或者 Tools-->Docsets,选择你想要的文档进行下载,下载完成后就可以看到你所需要的文档了。
除了在
Zeal
的官网上面下载Docsets
之外,还能通过AddFeed
来添加。国外有热心的开发者收集了一个 Docsets 集合(https://zealusercontributions.now.sh/),我们只需要点开自己需要的Docsets
,复制xml
地址到AddFeed
里面,就可以对应下载Docsets
了。
六、下载完成、close-->打开文档
下载好自己需要的 Docsets 之后,日常就可以在工作中使用离线文档进行工作了。日常使用过程中,有几点需要注意:
-
Zeal 原理是打开 html 的页面,所以它相当于一个浏览器,尽量养成定时关闭不用文档的习惯
-
Zeal 能够设置打开的快捷键,设置了之后就能快速打开 Zeal 查阅文档
-
Zeal 左上角具备搜索功能,在前面输入“
文档名称:内容
”就可以对指定的文档进行搜索
七、创建个人专属的文档项目
Zeal 官方写了一个教我们如何去编写自己的 Docsets 的文档,但是该文档写得比较简单,并且没有详细地操作指引,操作起来比较复杂。这里借鉴CodeSheep作者的做法!
经过实验之后,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 (前提安装NPM)
然后,使用 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"
},
...
十、文件夹放入Zeal中
生成完之后,将会得到一个 XXX.docsets 的文件夹,接下来就是最后的一步,把这个文件夹放进 Zeal 里面。
在 Zeal 里面有一个叫 docsets 的文件夹,进去之后会看到下载的 docsets 都在里面,把刚刚生成的 docsets 放进去,重启一下 Zeal 就可以看到自己的文档了。
上述步骤参考于CodeSheep作者