什麼是外掛

Gitbook 外掛是擴充套件 GitBook 功能(電子書和網站)的最佳方式.

只要是 Gitbook 預設沒有提供的功能,基於外掛機制都可以自行擴充套件,是外掛讓 Gitbook 變得更加強大.

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

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

• gitbook 入門教程之外掛介紹
• gitbook 入門教程之實用外掛
• gitbook 入門教程之主題外掛

如何發現外掛

您可以在Gitbook

官網輕鬆搜尋外掛,也可以在npmjs 官網搜尋 gitbook-plugin-<name> 外掛.

目前 Gitbook 官方已不再為維護外掛網站,只能通過 npmjs 發現 Gitbook 外掛.

如何安裝外掛

一旦你找到你想要安裝的外掛,你需要將它新增到你的 book.json 配置檔案,如果沒有該檔案則自行建立.

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

您還可以使用以下命令指定特定版本: [email protected] .
預設不填寫版本的情況下,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外掛

如果本文對你有所幫助,請動動小手點一下推薦,否則還請留言指正,如有需要,請關注個人公眾號「 雪之夢技術驛站 」

相關推薦