使用 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 就能夠看到本身的文檔了。

結語

以上是我在工做過程當中，根據本身的開發習慣所作出來的一個小文檔，若是你們有其餘方便的工具，能夠一塊兒討論一下，有任何問題歡迎騷擾~