什么是插件
Gitbook 插件是扩展 GitBook 功能(电子书和网站)的最佳方式.
只要是 Gitbook 默认没有提供的功能,基于插件机制都可以自行扩展,是插件让 Gitbook 变得更加强大.
![8dd02c09732ab07c8810f046089ffb53.png](https://img-blog.csdnimg.cn/img_convert/8dd02c09732ab07c8810f046089ffb53.png)
本文将全面介绍插件的相关知识并重点介绍插件开发的全流程,只有熟悉插件开发流程才能做到有的放矢,心中有数,进而开发出自己的插件.
关于插件请参考 Gitbook 入门教程高级进阶系列文章,本文重点讲解开发 Gitbook 的基本流程.
- gitbook 入门教程之插件介绍
- gitbook 入门教程之实用插件(新增3个插件)
- gitbook 入门教程之主题插件
如何发现插件
您可以在~~Gitbook官网[1]~~轻松搜索插件,也可以在 npmjs 官网[2]搜索 gitbook-plugin- 插件.
![27a9ac1c43d9d4b733072141805c805b.png](https://img-blog.csdnimg.cn/img_convert/27a9ac1c43d9d4b733072141805c805b.png)
目前 Gitbook 官方已不再为维护插件网站,只能通过 npmjs 发现 Gitbook 插件.
如何安装插件
一旦你找到你想要安装的插件,你需要将它添加到你的 book.json 配置文件,如果没有该文件则自行创建.
![198aff5968d32ad0e877f17ce49613c0.png](https://img-blog.csdnimg.cn/img_convert/198aff5968d32ad0e877f17ce49613c0.png)
您还可以使用以下命令指定特定版本: myPlugin@0.3.1 . 默认不填写版本的情况下,GitBook 使用**最新版本(兼容版本)**的插件.
![8c312c480a9f9d61e9ed9d6d3b7047e7.png](https://img-blog.csdnimg.cn/img_convert/8c312c480a9f9d61e9ed9d6d3b7047e7.png)
安装插件
- 如果是官网[3]在线环境,网站会自动帮你安装插件.
- 如果是在本地环境,直接运行 gitbook install 来安装插件.
![d7bbe248a14eb2e0a3d4b831e3871424.png](https://img-blog.csdnimg.cn/img_convert/d7bbe248a14eb2e0a3d4b831e3871424.png)
或者使用 npm 提前下载插件再安装到本地项目:
![6fe546fd3682faa8c71b9adf31c7288d.png](https://img-blog.csdnimg.cn/img_convert/6fe546fd3682faa8c71b9adf31c7288d.png)
配置插件
插件的配置在 book.json 配置文件中的 pluginsConfig 属性中(如果没有该属性请自行创建), 安装插件时,最好浏览插件的文档了解相关选项的详细信息.
![96af2885d1c031a2fade0cc7f029fdd6.png](https://img-blog.csdnimg.cn/img_convert/96af2885d1c031a2fade0cc7f029fdd6.png)
有些插件并未提供插件配置项,可以省略该步骤,有的插件会提供配置项,以插件介绍文档为准.
如何开发插件
GitBook 插件是在 npm 上发布的遵循传统定义的 node 包,除了标准的 node 规范外还有一些 Gitbook 自身定义的相关规范.
![93b61971ec33a1dff89d574b6e6a96dc.png](https://img-blog.csdnimg.cn/img_convert/93b61971ec33a1dff89d574b6e6a96dc.png)
目录结构
Gitbook 插件最基本的项目结构至少包括配置文件 package.json 和入口文件 index.js ,其他目录文件根据插件用途自行增减.
.├── index.js└── package.json
实际插件项目略有不同,可能还会有 _layouts 布局目录, asset 资源目录以及自定义 example 示例目录和 docs 文档目录等等.
package.json
package.json 是nodejs的配置文件,Gitbook 插件同样遵循该规范,配置文件声明了插件的版本描述性信息,除此之外还有 Gitbook 相关字段,遵循schema[4]准则,基本示例如下:
![cf26b247e63e7dfd41196a83bdc7635a.png](https://img-blog.csdnimg.cn/img_convert/cf26b247e63e7dfd41196a83bdc7635a.png)
值得注意的是,包名称必须以 gitbook-plugin-开头,包引擎应该包含gitbook.如需了解 package.json 的规范,可参考官方文档[5]
index.js
index.js 是插件运行时的入口,基本示例如下:
![15ed1eae1911f03dd1e66190e7c9c69c.png](https://img-blog.csdnimg.cn/img_convert/15ed1eae1911f03dd1e66190e7c9c69c.png)
发布插件
GitBook 插件可以在npmjs官网[6]上发布.
如需发布插件,首先需要在npmjs官网[7]上注册帐户,然后通过命令行发布.
![4a8e5739bebf9832db24aeae4c9a129e.png](https://img-blog.csdnimg.cn/img_convert/4a8e5739bebf9832db24aeae4c9a129e.png)
专用插件
专用插件可以托管在 GitHub 上,并使用 git urls:
本地测试插件
使用 npm link 可以在发布之前测试你的插件,命令详情参考官方文档[8]
在插件的文件夹中,运行:
![b8a05da90dbfc705687388784992f84f.png](https://img-blog.csdnimg.cn/img_convert/b8a05da90dbfc705687388784992f84f.png)
然后在您的书或者文档的文件夹中执行:
![b94e7625bd45f97ebab4d437f1dbc3b8.png](https://img-blog.csdnimg.cn/img_convert/b94e7625bd45f97ebab4d437f1dbc3b8.png)
单元测试插件
gitbook-tester[9]可以方便地为你的插件编写Node.js/Mocha单元测试.
使用Travis[10].可以对每个提交/标签运行测试.
插件总结
Gitbook 插件是扩展 Gitbook 功能的不二之选,如果熟悉 nodejs 项目的开发流程,只要稍微熟悉下 Gitbook 提供的接口文档,开发出自己的插件应该不是难事!
![6bec02d8d0edb02406527b55c983d426.png](https://img-blog.csdnimg.cn/img_convert/6bec02d8d0edb02406527b55c983d426.png)
希望本文能够对你理解 Gitbook 插件有所帮助,了解并熟练掌握插件开发的全流程,如果本文对你有所帮助,别忘了给我一个正面反馈以鼓励我继续创作哟!
阅读延伸
- 什么是 Gitbook 插件[11]
- 如何创建 Gitbook 插件[12]
- 如何测试 Gitbook 插件[13]
参考资料
[1] Gitbook官网: https://plugins.gitbook.com[2] npmjs 官网: https://www.npmjs.com[3] 官网: https://www.gitbook.com[4] schema: http://json-schema.org[5] 官方文档: https://docs.npmjs.com/files/package.json[6] npmjs官网: https://www.npmjs.com[7] npmjs官网: https://www.npmjs.com[8] 官方文档: https://docs.npmjs.com/cli/link[9] gitbook-tester: https://github.com/todvora/gitbook-tester[10] Travis: https://travis.org[11] 什么是Gitbook插件: https://snowdreams1006.github.io/gitbook-official/en/plugins/[12] 如何创建Gitbook插件: https://snowdreams1006.github.io/gitbook-official/en/plugins/create.html[13] 如何测试Gitbook插件: https://snowdreams1006.github.io/gitbook-official/en/plugins/testing.html