共计 2284 个字符，预计需要花费 6 分钟才能阅读完成。

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 是 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 是插件运行时的入口, 基本示例如下:

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 插件

如果本文对你有所帮助, 不用赞赏, 也不必转发, 直接点赞留言告诉鼓励一下就可以啦!

gitbook-入门教程之小白都能看懂的-Gitbook-插件开发全流程

什么是插件

如何发现插件

如何安装插件

安装插件

配置插件

如何开发插件

目录结构

package.json

index.js

发布插件

专用插件

本地测试插件

单元测试插件

插件总结

阅读延伸

站内搜索