使用 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 就可以看到自己的文檔了。

結語

以上是我在工作過程中，根據自己的開發習慣所做出來的一個小文檔，如果大家有其他方便的工具，可以一起討論一下，有任何問題歡迎騷擾~