Gitbook详解（五）-插件的配置和使用详解

目录

• 1. 介绍
  • 1.1 默认插件
  • 1.2 禁用自带的插件
  • 1.3 添加插件列表
  • 1.4 插件属性配置 pluginsConfig
• 2. 实用插件
  • 2.1 insert-logo 插入logo
  • 2.2 favicon 更改网站的图标
  • 2.3 search-pro 高级搜索（支持中文）
  • 2.4 splitter 侧边栏宽度可调节
  • 2.5 github 在右上角添加github图标
  • 2.6 sharing-plus 分享当前页面
  • 2.7 copy-code-button 代码复制按钮
  • 2.8 code 代码添加行号&复制按钮
  • 2.9 advanced-emoji 表情图标
  • 2.10 emphasize 文字底色
  • 2.11 image-captions 在图片下面显示标题
  • 2.12 anchor-navigation-ex 悬浮目录和回到顶部
  • 2.13 expandable-chapters-small 折叠侧边栏
  • 2.14 alerts 漂亮格式的提示块
  • 2.15 flexible-alerts 高级格式显示的提示块
  • 2.16 auto-scroll-table 表格自动过长滚动条
  • 2.17 lightbox 点击图片弹窗显示
  • 2.18 popup 点击图片新页面弹出显示
  • 2.19 tbfed-pagefooter 页脚和版权
  • 2.20 page-footer 高级页脚和版权
  • 2.21 hide-element 隐藏元素
  • 2.22 back-to-top-button 回到顶部按钮
  • 2.23 prism 基于 Prism 的代码高亮
  • 2.24 theme-hqbook 自定义 hqbook 主题
  • 2.25 donate 打赏插件
  • 2.26 更多...
• 3. 总结

1. 介绍

本章主要来详细的介绍一下 Gitbook 中的 插件 相关的配置和使用。在 Gitbook 中可以在书籍的配置文件 book.json 中来进行插件的相关配置。比如有很多好用的插件，可以很好的拓展书籍的外观，可用性或者其他方便的使用，所以接下来就一起来看看 Gitbook 中插件的使用吧。

配置的方法是在配置文件的 plugins 中添加需要的插件名称即可。

如下所示：

"plugins": [
    "search",
    "highlight",
    "sharing",
    "font-settings",
    "livereload",
    ...
]

1.1 默认插件

Gitbook 中默认带有 5 个插件：

名称	说明
highlight	语法高亮插件，代码高亮功能
search	搜索插件，不支持中文搜索
sharing	分享插件，右上角分享功能
font-settings	字体设置（最上方的"A"符号）
livereload	热加载插件，为 GitBook 编辑进行实时重新预览加载

1.2 禁用自带的插件

如果需要去除或者禁用 Gitbook 中的某个插件，可以在插件名称前面加 - 。

如下所示：

"plugins": [
    "-search",
    "-highlight",
    "-sharing",
    "-font-settings",
    "-livereload",
    ...
]

1.3 添加插件列表

如果需要添加一些第三方的自定义插件，可以在 plugins 中添加需要的插件名称列表。

注意：

• 有的第三方的插件可能和默认的插件有重复，或者替代默认插件的，需要禁用对应的默认插件，具体用法一般参考对应插件的使用说明。
• 第三方插件使用的话，可能会破坏书籍的结构，所以使用上需要注意！

例如：

"plugins": [
		"-search",
        "advanced-emoji",
        "search-pro",
        "github",
        "splitter",
        "anchor-navigation-ex",
        "chapter-fold",
        "expandable-chapters-small",
        "code",
        "alerts",
        "insert-logo",
        "flexible-alerts",
        ...
    ]

1.4 插件属性配置 pluginsConfig

配置插件的属性在书籍配置文件中的 pluginsConfig 中进行相关插件的属性配置。

例如：配置insert-logo 插件的相关属性

"pluginsConfig": {
       "insert-logo": {
           "url": "jim-logo.png",
           "style": "background: none; max-height: 100px; min-height: 30px"
       }
   }

2. 实用插件

Gitbook 中的第三方插件有很多，在此就不进行一一的介绍了。下面就根据博主了解或者使用过的插件，简单整理一些实用的插件进行介绍一下吧。

第三方插件使用方法：

• 在配置文件 book.json 中添加 "plugins" 和 "pluginConfig" 字段，然后执行 gitbook install 来进行插件的安装
• 使用NPM安装 npm install gitbook-plugin-插件名 进行安装
• 从源码 GitHub 地址中下载，放到 node_modules 文件夹里安装

提示：

1. 推荐使用配置文件 book.json 配置的方法进行安装，下面主要通过这种方式来进行介绍安装和配置第三方的插件的简单使用。
2. 更详细的配置或者使用方法，以及效果图，请参考每一个插件后面贴出官方参考链接。

详细效果可以参考：

https://jiangminggithub.github.io/gitbook/

https://jiangming_gitee.gitee.io/gitbook/

2.1 insert-logo 插入logo

将自己的logo图片插入到导航栏上方中，定制显示自己的 logo 标识。

{
    "plugins": [ "insert-logo" ]
    "pluginsConfig": {
      "insert-logo": {
        "url": "./jim-logo.png",
        "style": "background: none; max-height: 100px; min-height: 30px"
      }
    }
}

插件 Github 地址：https://github.com/matusnovak/gitbook-plugin-insert-logo

2.2 favicon 更改网站的图标

自定义的网站图标的插件，可以将自己的 logo 图标设置为网站的图标。

{
    "plugins": [
        "favicon"
    ],
    "pluginsConfig": {
        "favicon": {
            "shortcut": "assets/images/favicon.ico",
            "bookmark": "assets/images/favicon.ico",
            "appleTouch": "assets/images/apple-touch-icon.png",
            "appleTouchMore": {
                "120x120": "assets/images/apple-touch-icon-120x120.png",
                "180x180": "assets/images/apple-touch-icon-180x180.png"
            }
        }
    }
}

插件 Github 地址：https://github.com/menduo/gitbook-plugin-favicon

2.3 search-pro 高级搜索（支持中文）

支持中文搜索的插件, 使用此插件需要将默认的 search 和 lunr 插件去掉。

{
    "plugins": [
      "-lunr", "-search", "search-pro"
    ]
}

插件 Github 地址：https://github.com/gitbook-plugins/gitbook-plugin-search-pro

2.4 splitter 侧边栏宽度可调节

splitter 插件可以使左侧的侧边栏目录宽度可以自定义的调节。

{
    "plugins": ["splitter"]
}

插件 Github 地址：https://github.com/yoshidax/gitbook-plugin-splitter

2.5 github 在右上角添加github图标

github 插件会在右上角添加一个 github 的图标，可以通过插件属性配置链接，点击后可以进入自定义的链接页面。

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

插件 Github 地址：https://github.com/GitbookIO/plugin-github

2.6 sharing-plus 分享当前页面

分享当前页面的插件，比默认的 sharing 插件多了一些分享方式，同样可以通过配置插件属性进行相关的配置，可以通过实际需要进行相关配置。

{
    "plugins": ["-sharing", "sharing-plus"],
    "pluginsConfig": {
        "sharing": {
            "douban": false,
            "facebook": true,
            "google": false,
            "hatenaBookmark": false,
            "instapaper": false,
            "line": false,
            "linkedin": true,
            "messenger": false,
            "pocket": true,
            "qq": false,
            "qzone": false,
            "stumbleupon": false,
            "twitter": true,
            "viber": false,
            "vk": false,
            "weibo": false,
            "whatsapp": false,
            "all": [
                "facebook", "google", "twitter",
                "weibo", "instapaper", "linkedin",
                "pocket", "stumbleupon"
            ]
        }
    }
}

插件参考地址：https://www.npmjs.com/package/gitbook-plugin-sharing-plus

2.7 copy-code-button 代码复制按钮

为代码块添加一个可以复制的按钮。

{
    "plugins": ["copy-code-button"]
}

插件 Github 地址：https://github.com/WebEngage/gitbook-plugin-copy-code-button

2.8 code 代码添加行号&复制按钮

这个插件可以为代码块添加行号和复制按钮，单行代码情况无行号。

如果需要去除代码复制按钮，可在配置文件进行配置 copyButtons 属性为 false。

{
    "plugins" : [ 
            "code" 
     ],
    "pluginsConfig": {
      "code": {
        "copyButtons": false
      }
    }
}

插件 Github 地址：https://github.com/TGhoul/gitbook-plugin-code

2.9 advanced-emoji 表情图标

这个插件可以在书籍中使用表情列表中的表情图标。

{
    "plugins": [
        "advanced-emoji"
    ]
}

插件 Github 地址：https://github.com/codeclou/gitbook-plugin-advanced-emoji

2.10 emphasize 文字底色

这个插件可以给书籍中的文本内容加上特定的文字底色效果。

{
    "plugins": ["emphasize"]
}

简单的使用示例（markdown书籍中内容中）：

This text is {% em %}highlighted !{% endem %}

This text is {% em %}highlighted with **markdown**!{% endem %}

This text is {% em type="green" %}highlighted in green!{% endem %}

This text is {% em type="red" %}highlighted in red!{% endem %}

This text is {% em color="#ff0000" %}highlighted with a custom color!{% endem %}

插件 Github 地址：https://github.com/GitbookIO/plugin-emphasize

2.11 image-captions 在图片下面显示标题

抓取内容中图片的 alt 或 title 属性，在图片下面显示标题。更多详细的配置属性和使用方法参考官方说明。

基本使用：

{
    "plugins": [
        "image-captions"
    ],
    "pluginsConfig": {
      "image-captions": {
          "caption": "Image _PAGE_LEVEL_._PAGE_IMAGE_NUMBER_ - _CAPTION_",
          "align": "left",
          ...
      }
  }
}

插件 Github 地址：https://github.com/todvora/gitbook-plugin-image-captions

2.12 anchor-navigation-ex 悬浮目录和回到顶部

插件功能：

• 给页面H1-H6标题增加锚点效果
• 浮动导航模式
• 页面内顶部导航模式
• 导航标题前的层级图标是否显示，自定义H1-H3的层级图标
• plugins["theme-default"],页面标题层级与官方默认主题的showLevel层级关联
• plugins["theme-default"],插件样式支持官网默认主题的三种样式：White、Sepia、Night
• 在页面中增加标签，会在此处生成TOC目录
• 在页面中增加标签，不会在该页面生成悬浮导航
• config.printLog=true,打印当前的处理进度，排错很有用
• config.multipleH1=false,去掉丑陋的多余的1. 序号（如过您的书籍遵循一个MD文件只有一个H1标签的话）
• config.showGoTop=true,显示返回顶部按钮 V1.0.11+
• config.float.floatIcon 可以配置浮动导航的悬浮图标样式 V1.0.12+
• 在页面中增加不会在该页面生成层级序号 V1.0.12+

使用：

{
  "plugins": [
       "anchor-navigation-ex"
  ]
}

插件 Github 地址：https://github.com/zq99299/gitbook-plugin-anchor-navigation-ex

2.13 expandable-chapters-small 折叠侧边栏

在左侧目录前面显示一个折叠的标志，可以进行折叠侧边栏。

{
    plugins: ["expandable-chapters-small"]
}

插件 Github 地址：https://github.com/chrisjake/gitbook-plugin-expandable-chapters-small

2.14 alerts 漂亮格式的提示块

这个插件可以将将块引用转换为漂亮的提示格式的信息。

{
    "plugins": ["alerts"]
}

目前支持 4 种提示的类型：info，warning，danger，success

Info styling

> **[info] For info**
>
> Use this for infomation messages.

Warning styling

> **[warning] For warning**
>
> Use this for warning messages.

Danger styling

> **[danger] For danger**
>
> Use this for danger messages.

Success styling

> **[success] For info**
>
> Use this for success messages.

插件参考地址：https://www.npmjs.com/package/gitbook-plugin-alerts

2.15 flexible-alerts 高级格式显示的提示块

这个插件将块引用转换为漂亮的警报。可以在全局和警报特定级别配置外观，因此输出确实符合您的需求。此外，您还可以提供自己的警报类型（比如最后的comment）。

{
    "plugins": [
      "flexible-alerts"
    ],
    "pluginsConfig": {
      "flexible-alerts": {
        "style": "callout",
        "comment": {
          "label": "Comment",
          "icon": "fa fa-comments",
          "className": "info"
        }
      }
    }
}

用法：

> [!type|style:xx|label:xx|icon:xx|className:xx|labelVisibility:xx|iconVisibility:xx]
> 内容部分

字段介绍，如果不设置的表示选择默认，除了!type都不是必需的。

键	允许的值	说明
!type	NOTE，TIP，WARNING和DANGER	警告级别设置
style	以下值之一: callout（默认）, flat	警告样式，见图19的左右不同
label	任何文字	警告块的标题位置，即Note这个字段位置（不支持中文）
icon	e.g. 'fa fa-info-circle'	一个有效的Font Awesome图标，那块小符号
className	CSS类的名称	指定css文件，用于指定外观
labelVisibility	以下值之一：visible（默认），hidden	标签是否可见
iconVisibility	以下值之一：visible（默认），hidden	图标是否可见

1. 这是简单的用法
> [!NOTE]
> 这是一个简单的Note类型的使用，所有的属性都是默认值。

---
2. 这是自定义属性的用法
> [!NOTE|style:flat|lable:Mylable|iconVisibility:hidden]
> "!type":`NOTE`、"style":`flat`、"lable":`自定义标签`、图标不可见

json 配置个性化，自定义一个COMMENT类型使用。

"pluginsConfig": {
      "flexible-alerts": {
        "style": "callout",
        "comment": {
          "label": "Comment",
          "icon": "fa fa-comments",
          "className": "info"
        }
      }
    }

使用：

> [!COMMENT]
> An alert of type 'comment' using style 'callout' with default settings.

插件 Github 地址：https://github.com/fzankl/gitbook-plugin-flexible-alerts

2.16 auto-scroll-table 表格自动过长滚动条

为避免表格过宽，在过宽的表格页面中增加滚动条。

{
  "plugins": ["auto-scroll-table"]
}

2.17 lightbox 点击图片弹窗显示

这个插件可以单击图片，以图片本身大小的方式弹窗显示图片和一些图片相关的 Alt 的信息。

{
    "plugins": [
        "lightbox"
    ],
    "lightbox": {
        "includeJQuery": false,
        "sameUuid": true,
        "options": {
            "resizeDuration": 500,
            "wrapAround": false
        }
    }
}

配置参数介绍：

• includeJQuery: 如果你的项目中已经引入了 JQuery 可以在此设置是否包含插件本身的 JQuery。
• sameUuid：在图片预览中添加上一个、下一个按钮来浏览本页面的图片配置。
• options： 这个选项配置显示的动画时长，是否包裹等相关配置。

插件 Github 地址：https://github.com/vongola12324/gitbook-plugin-lightbox

2.18 popup 点击图片新页面弹出显示

可以单击图片，在新页面查看大图。

{
  "plugins": [ "popup" ]
}

插件 Github 地址：https://github.com/somax/gitbook-plugin-popup

2.19 tbfed-pagefooter 页脚和版权

可以添加页脚，版权信息。

{
    "plugins": [
       "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"Copyright ©JiangMing 2021",
            "modify_label": "更新时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

如果想自定义一个链接说明，自己可以去index.js里，把 powered by gitbook，改成
powered by <a href="你的说明内容链接" target="_blank">你的说明内容

插件 Github 地址：https://github.com/zhj3618/gitbook-plugin-tbfed-pagefooter

2.20 page-footer 高级页脚和版权

更高级的页脚版权信息的插件，支持normal，symmetrical，Issues三种不同样式的形式。

{
    "plugins": [
        "page-footer"
    ],
    "pluginsConfig": {
        "page-footer": {
            "description": "modified at",
            "signature": "Aleen",
            "wisdom": "More than a coder, more than a designer",
            "format": "yyyy-MM-dd hh:mm:ss",
            "copyright": "Copyright © aleen42",
            "timeColor": "#666",
            "copyrightColor": "#666",
            "utcOffset": "8",
            "isShowQRCode": true,
            "baseUri": "https://aleen42.gitbooks.io/personalwiki/content/",
            "isShowIssues": true,
            "repo": "aleen42/PersonalWiki",
            "issueNum": "8",
            "token": "",
            "style": "normal"
        }
    }
}

插件 Github 地址：https://github.com/aleen42/gitbook-footer

2.21 hide-element 隐藏元素

可以隐藏不想看到的元素，比如导航栏中 Published by GitBook 。

{
    "plugins": [
        "hide-element"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        }
    }
}

插件 Github 地址：https://github.com/gonjay/gitbook-plugin-hide-element

2.22 back-to-top-button 回到顶部按钮

可以在浏览文章到一定长度的时候，显示一个回到顶部的快捷按钮，点击可以快速回到文章顶部。

{
    "plugins": [
         "back-to-top-button"
    ]
}

插件 Github 地址：https://github.com/stuebersystems/gitbook-plugin-back-to-top-button

2.23 prism 基于 Prism 的代码高亮

prism 基于 Prism 的代码高亮插件，可以为代码块配置不同的主题风格。

{
    "plugins": [
        "prism",
        "-highlight"
    ],
    "pluginsConfig": {
        "prism": {
            "css": [
                "prismjs/themes/prism-solarizedlight.css"
            ],
            "lang": {
                "flow": "typescript"
            },
            "ignore": [
                "mermaid",
                "eval-js"
            ]
        }
    }
}

配置参数介绍：

• css：指定自定义主题的样式文件。
• lang： 配置自定义语言前缀名，来混淆配置。
• ignore：由于其他插件使用自定 lang 代码块的概念来表示其他功能，你可以忽略某些 langs。

插件 Github 地址：https://github.com/gaearon/gitbook-plugin-prism

2.24 theme-hqbook 自定义 hqbook 主题

Gitbook 也支持通过插件的方式来自定义主题，在 Github中可能有很多主题资源，但是不是非常建议大家去使用第三方的主题，因为第三的主题可能会导致一些不兼容的情况或者各种问题。

hqbook 主题其实也是不是非常完善的，比如不能很好的适配移动端，在移动端访问，界面就可能出现各种不协调的地方，截止到目前为止，博主还没有发现一个比较完善的主题，本节仅供大家参考，具体的使用还是需要自己去研究或者有能力的情况自行开发一套哈。

{
    "plugins": [
        "theme-hqbook"
    ],
    "variables": {
        "themeHqbook":{
            "nav":[
                {
                    "url": "https://blog.csdn.net/ming_97y",
                    "target": "_blank",
                    "name": "Blog"
                },
                // { ... }
            ]
        },
    },
    "pluginsConfig": {
        "theme-hqbook":{
            "favicon": "./favicon.ico",
            "logo":"./logo.png",
            "search-placeholder":"输入关键字搜索",
			"copyButtons": true,
			"copyLines": true,
			"dragSplitter": true,
            "hide-elements": [
                ".summary .gitbook-link"
            ],
            "flexible-linkcard": {
                "title": "flexible-linkcard",
                "hrefUrl": "https://github.com/HaoqiangChen/gitbook-plugin-flexible-linkcard",
                "target": "_blank",
                "imgSrc": "./book/logo.png",
                "imgClass": "rect"
            }
        }
    }
}

参数简单介绍：

• favicon：自定义favicon地址，修改标题栏图标

• logo：自定义logo地址，修改logo

• search-placeholder：搜索框提示信息

• copyButtons：代码块添加复制按钮

• copyLines：当显示多行代码时，将添加行号

• dragSplitter：在左侧目录和右侧内容之间添加一个可以拖拽的栏，用来调整两边的宽度

• hide-elements：隐藏元素，比如导航栏中Published by GitBook

• nav：顶部导航栏，nav为数组，将需要的导航添加到变量themeHqbook中

• flexible-linkcard：

1. title : 定义flexible-linkcard的默认标题
2. hrefUrl : 定义flexible-linkcard的默认网址
3. target : 定义flexible-linkcard的网址默认打开方式，即HTML<a>的target属性，属性值有_seft, _blank, _parent, _top几种，最好还是设置_blank新窗口打开
4. imgSrc : 定义flexible-linkcard的默认显示图片
5. imgClass : 定义flexible-linkcard的默认图片样式

插件 Github 地址：https://github.com/HaoqiangChen/gitbook-plugin-theme-hqbook

2.25 donate 打赏插件

显示在文章最下面的按钮，点击可弹出收款相关的图片和信息。

{
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
          "wechat": "/images/wechat-qr.png",
          "alipay": "/images/alipay-qr.png",
          "title": "默认空",
          "button": "默认值：Donate",
          "alipayText": "默认值：支付宝捐赠",
          "wechatText": "默认值：微信捐赠"
        }
    }
}

插件 Github 地址：https://github.com/willin/gitbook-plugin-donate

2.26 更多...

其他插件参考：

• ad 在每个页面顶部和底部添加广告或任何自定义内容：https://github.com/zhaoda/gitbook-plugin-ad
• sectionx 分离各个段落，并提供一个展开收起的按钮：https://github.com/ymcatar/gitbook-plugin-sectionx
• Puml 使用 PlantUML 展示 uml 图: https://github.com/GitbookIO/plugin-puml
• Graph 使用 function-plot 绘制数学函数图：https://github.com/cjam/gitbook-plugin-graph
• todo 添加 todo（选中框） 功能：https://github.com/ly-tools/gitbook-plugin-todo
• include-csv 展示 csv 文件内容：https://github.com/TakuroFukamizu/gitbook-plugin-include-csv
• musicxml 支持 musicxml 格式的乐谱渲染：https://github.com/ymcatar/gitbook-plugin-musicxml
• url-embed 嵌入动态内容：https://github.com/basilvetas/gitbook-plugin-url-embed
• ...

关于第三方插件的介绍就到这里了，大家有兴趣的可以去查看一下：https://github.com/GitbookIO

更多的插件，请到 NPM Package 或者 GitHub 中查询使用。

3. 总结

到此将插件的配置和使用详细的介绍完了，也列举了一些常用的一些第三方的插件的使用方法，相信现在大家可以很好的利用这些比较好用的第三方的插件，去更好的去构建自己的书籍了。

>>> 系列文章快捷导航：

1. Gitbook详解（一）-介绍和安装详解
2. Gitbook详解（二）-命令行的使用
3. Gitbook详解（三）-目录结构详解
4. Gitbook详解（四）-配置和说明详解
5. Gitbook详解（五）-插件的配置和使用详解
6. Gitbook详解（六）-导出电子书详解
7. Gitbook详解（七）-Markdown编辑器推荐
8. Gitbook详解（八）-发布书籍