gitbook 入門教程之小白都能看懂的 Gitbook 插件開發全流程

什麼是插件

Gitbook 插件是擴展 GitBook 功能(電子書和網站)的最佳方式.

只要是 Gitbook 默認沒有提供的功能,基於插件機制均可以自行擴展,是插件讓 Gitbook 變得更增強大.

本文將全面介紹插件的相關知識並重點介紹插件開發的全流程,只有熟悉插件開發流程才能作到有的放矢,心中有數,進而開發出本身的插件.

關於插件請參考 Gitbook 入門教程高級進階系列文章,本文重點講解開發 Gitbook 的基本流程.

• gitbook 入門教程之插件介紹
• gitbook 入門教程之實用插件
• gitbook 入門教程之主題插件

如何發現插件

您能夠在Gitbook官網輕鬆搜索插件,也能夠在npmjs 官網搜索 gitbook-plugin-<name> 插件.

目前 Gitbook 官方已 再也不爲維護插件網站,只能經過 npmjs 發現 Gitbook 插件.

如何安裝插件

一旦你找到你想要安裝的插件,你須要將它添加到你的 book.json 配置文件,若是沒有該文件則自行建立.

{
    "plugins": ["myPlugin", "anotherPlugin"]
}

您還可使用如下命令指定特定版本: myPlugin@0.3.1 .
默認不填寫版本的狀況下,GitBook 使用最新版本(兼容版本)的插件.

安裝插件

• 若是是官網在線環境,網站會自動幫你安裝插件.
• 若是是在本地環境,直接運行 gitbook install 來安裝插件.

$ gitbook install

或者使用 npm 提早下載插件再安裝到本地項目:

$ npm install gitbook-plugin-<name>

$ gitbook install

配置插件

插件的配置在 book.json 配置文件中的 pluginsConfig 屬性中(若是沒有該屬性請自行建立),
安裝插件時,最好瀏覽插件的文檔瞭解相關選項的詳細信息.

{
    "plugins": ["github"],
    "pluginsConfig": {
        "github": {
          "url": "https://github.com/snowdreams1006/snowdreams1006.github.io"
        }
    }
}

有些插件並未提供插件配置項,能夠省略該步驟,有的插件會提供配置項,以插件介紹文檔爲準.

如何開發插件

GitBook 插件是在 npm 上發佈的遵循傳統定義的 node 包,除了標準的 node 規範外還有一些 Gitbook 自身定義的相關規範.

目錄結構

Gitbook 插件最基本的項目結構至少包括配置文件 package.json 和入口文件 index.js ,其餘目錄文件根據插件用途自行增減.

.
├── index.js
└── package.json

實際插件項目略有不一樣,可能還會有 _layouts 佈局目錄, asset 資源目錄以及自定義 example 示例目錄和 docs 文檔目錄等等.

package.json

package.json 是nodejs的配置文件,Gitbook 插件一樣遵循該規範,配置文件聲明瞭插件的版本描述性信息,除此以外還有 Gitbook 相關字段,遵循schema準則,基本示例以下:

{
    "name": "gitbook-plugin-mytest",
    "version": "0.0.1",
    "description": "This is my first GitBook plugin",
    "engines": {
        "gitbook": ">1.x.x"
    },
    "gitbook": {
        "properties": {
            "myConfigKey": {
                "type": "string",
                "default": "it's the default value",
                "description": "It defines my awesome config!"
            }
        }
    }
}

值得注意的是, 包名稱必須以 gitbook-plugin-開頭， 包引擎應該包含 gitbook.如需瞭解 package.json 的規範,可參考 官方文檔

index.js

index.js 是插件運行時的入口,基本示例以下:

module.exports = {
    // 鉤子函數
    hooks: {},

    // 代碼塊
    blocks: {},

    // 過濾器
    filters: {}
};

發佈插件

GitBook 插件能夠在npmjs官網上發佈.

如需發佈插件,首先須要在npmjs官網上註冊賬戶,而後經過命令行發佈.

$ npm publish

專用插件

專用插件能夠託管在 GitHub 上,並使用 git urls:

{
    "plugins": [
        "myplugin@git+https://github.com/MyCompany/mygitbookplugin.git#1.0.0"
    ]
}

本地測試插件

使用 npm link 能夠在發佈以前測試你的插件,命令詳情參考官方文檔

在插件的文件夾中,運行：

$ npm link

而後在您的書或者文檔的文件夾中執行:

$ npm link gitbook-plugin-<name>

單元測試插件

gitbook-tester能夠方便地爲你的插件編寫Node.js/Mocha單元測試.

使用Travis.能夠對每一個提交/標籤運行測試.

插件總結

Gitbook 插件是擴展 Gitbook 功能的不二之選,若是熟悉 nodejs 項目的開發流程,只要稍微熟悉下 Gitbook 提供的接口文檔,開發出本身的插件應該不是難事!

但願本文可以對你理解 Gitbook 插件有所幫助,瞭解並熟練掌握插件開發的全流程,若是本文對你有所幫助,別忘了給我一個正面反饋以鼓勵我繼續創做喲!

閱讀延伸

• 什麼是Gitbook插件
• 如何建立Gitbook插件
• 如何測試Gitbook插件

若是本文對你有所幫助,不用讚揚,也沒必要轉發,直接點贊留言告訴鼓勵一下就能夠啦!