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詳解（八）-發布書籍