什麼是插件
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
插件有所幫助,瞭解並熟練掌握插件開發的全流程,如果本文對你有所幫助,別忘了給我一個正面反饋以鼓勵我繼續創作喲!
閱讀延伸
如果本文對你有所幫助,不用讚賞,也不必轉發,直接點贊留言告訴鼓勵一下就可以啦!