GitBook 插件

记录一些实用的插件, 如果要指定插件的版本可以使用 plugin@0.3.1。下面的插件在 GitBook 的 3.2.3 版本中可以正常工作，因为一些插件可能不会随着 GitBook 版本的升级而升级，即下面的插件可能不适用高版本的 GitBook，所以这里指定了 GitBook 的版本。另外本文记录的插件在 Linux 下都是可以正确工作的，windows 系统没有测试。这里只是列举了一部分插件，如果有其它的需求，可以到 插件官网 区搜索相关插件。

Disqus

添加disqus评论

插件地址

  1. "plugins": [
  2.     "disqus"
  3. ],
  4. "pluginsConfig": {
  5.     "disqus": {
  6.         "shortName": "gitbookuse"
  7.     }
  8. }

Search Plus

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

插件地址

  1. {
  2.     "plugins": ["-lunr", "-search", "search-plus"]
  3. }

Prism

使用 Prism.js 为语法添加高亮显示，需要将 highlight 插件去掉。该插件自带的主题样式较少，可以再安装 prism-themes 插件，里面多提供了几种样式，具体的样式可以参考 这里，在设置样式时要注意设置 css 文件名，而不是样式名。

Prism 插件地址    prism-themes 插件地址

  1. {
  2.     "plugins": [
  3.         "prism",
  4.         "-highlight"
  5.     ],
  6.     "pluginsConfig": {
  7.         "prism": {
  8.             "css": [
  9.                 "prism-themes/themes/prism-base16-ateliersulphurpool.light.css"
  10.             ]
  11.         }
  12.     }
  13. }

如果需要修改背景色、字体大小等，可以在 website.css 定义 pre[class*="language-"] 类来修改，下面是一个示例：

  1. pre[class*="language-"] {
  2.     border: none;
  3.     background-color: #f7f7f7;
  4.     font-size: 1em;
  5.     line-height: 1.2em;
  6. }

Advanced Emoji

支持emoji表情

emoij表情列表
插件地址

  1. "plugins": [
  2.     "advanced-emoji"
  3. ]

使用示例：

:bowtie: :smile: :laughing: :blush: :smiley: :relaxed:

Github

添加github图标

插件地址

  1. "plugins": [
  2.     "github"
  3. ],
  4. "pluginsConfig": {
  5.     "github": {
  6.         "url": "https://github.com/zhangjikai"
  7.     }
  8. }

Github Buttons

添加项目在 github 上的 star，watch，fork情况

插件地址

  1. {
  2.     "plugins": [
  3.         "github-buttons"
  4.     ],
  5.     "pluginsConfig": {
  6.         "github-buttons": {
  7.             "repo": "zhangjikai/gitbook-use",
  8.             "types": [
  9.                 "star",
  10.                 "watch",
  11.                 "fork"
  12.             ],
  13.             "size": "small"
  14.         }
  15.     }
  16. }

Ace Plugin

插件地址

使 GitBook 支持ace 。默认情况下，line-height 为 1，会使代码显得比较挤，而作者好像没提供修改行高的选项，如果需要修改行高，可以到 node_modules -> github-plugin-ace -> assets -> ace.js 中加入下面两行代码 (30 行左右的位置)：

  1. editor.container.style.lineHeight = 1.25;
  2. editor.renderer.updateFontSize();

不过上面的做法有个问题就是，每次使用 gitbook install 安装新的插件之后，代码又会重置为原来的样子。另外可以在 website.css 中加入下面的 css 代码来指定 ace 字体的大小

  1. .aceCode {
  2.   font-size: 14px !important;
  3. }

使用插件：

  1. "plugins": [
  2.     "ace"
  3. ]

使用示例:

{%ace edit=true, lang=’c_cpp’%}
// This is a hello world program for C.

include

int main(){
printf(“Hello World!”);
return 1;
}
{%endace%}

Emphasize

为文字加上底色

插件地址

  1. "plugins": [
  2.     "emphasize"
  3. ]

使用示例:

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 %}

KaTex

为了支持数学公式, 我们可以使用KaTex和MathJax插件, 官网上说Katex速度要快于MathJax

插件地址
MathJax使用LaTeX语法编写数学公式教程

  1. "plugins": [
  2.     "katex"
  3. ]

使用示例:

When {% math %}a \ne 0{% endmath %}, there are two solutions to {% math %}(ax^2 + bx + c = 0){% endmath %} and they are {% math %}x = {-b \pm \sqrt{b^2-4ac} \over 2a}.{% endmath %}


\int_{-\infty}^\infty g(x) dx


1 \over 3

Include Codeblock

使用代码块的格式显示所包含文件的内容. 该文件必须存在。插件提供了一些配置，可以区插件官网查看。如果同时使用 ace 和本插件，本插件要在 ace 插件前面加载。

插件地址 

  1. {
  2.     "plugins": [
  3.         "include-codeblock"
  4.     ],
  5.     "pluginsConfig": {
  6.         "include-codeblock": {
  7.             "template": "ace",
  8.             "unindent": "true",
  9.             "theme": "monokai"
  10.         }
  11.     }
  12. }

使用示例:

import

Splitter

使侧边栏的宽度可以自由调节

插件 - 图1

插件地址

  1. "plugins": [
  2.     "splitter"
  3. ]

Mermaid-gb3

支持渲染Mermaid图表
插件地址

  1. "plugins": [
  2.     "mermaid-gb3"
  3. ]

使用示例:

  1. graph TD;
  2.   A-->B;
  3.   A-->C;
  4.   B-->D;
  5.   C-->D;

Puml

使用 PlantUML 展示 uml 图。

插件地址
PlantUML 地址

  1. {
  2.     "plugins": ["puml"]
  3. }

使用示例：

  1. {% plantuml %}
  2. Class Stage
  3.     Class Timeout {
  4.         +constructor:function(cfg)
  5.         +timeout:function(ctx)
  6.         +overdue:function(ctx)
  7.         +stage: Stage
  8.     }
  9.     Stage <|-- Timeout
  10. {% endplantuml %}

效果如下所示：

{% plantuml %}
Class Stage
Class Timeout {
+constructor:function(cfg)
+timeout:function(ctx)
+overdue:function(ctx)
+stage: Stage
}
Stage <|— Timeout
{% endplantuml %}

Graph

使用 function-plot 绘制数学函数图。

插件地址
function-plot

  1. {
  2.     "plugins": [ "graph" ],
  3. }

下面是一个示例，需要注意的是 {% graph %} 块中的内容必须是合法的 JSON 格式。

  1. {% graph %}
  2. {
  3.     "title": "1/x * cos(1/x)",
  4.     "grid": true,
  5.     "xAxis": {
  6.         "domain": [0.01, 1]
  7.     },
  8.     "yAxis": {
  9.         "domain": [-100, 100]
  10.     },
  11.     "data": [{
  12.         "fn": "1/x * cos(1/x)",
  13.         "closed": true
  14.     }]
  15. }
  16. {% endgraph %}

效果如下所示：
{% graph %}
{
“title”: “1/x cos(1/x)”,
“grid”: true,
“xAxis”: {
“domain”: [0.01, 1]
},
“yAxis”: {
“domain”: [-100, 100]
},
“data”: [{
“fn”: “1/x cos(1/x)”,
“closed”: true
}]
}
{% endgraph %}

Chart

使用 C3.js 或者 Highcharts 绘制图形。

插件地址
C3.js
highcharts

  1. {
  2.     "plugins": [ "chart" ],
  3.     "pluginsConfig": {
  4.         "chart": {
  5.             "type": "c3"
  6.         }
  7.     }
  8. }

type 可以是 c3 或者 highcharts, 默认是 c3.

下面是一个示例：

  1. {% chart %}
  2. {
  3.     "data": {
  4.         "type": "bar",
  5.         "columns": [
  6.             ["data1", 30, 200, 100, 400, 150, 250],
  7.             ["data2", 50, 20, 10, 40, 15, 25]
  8.         ],
  9.         "axes": {
  10.             "data2": "y2"
  11.         }
  12.     },
  13.     "axis": {
  14.         "y2": {
  15.             "show": true
  16.         }
  17.     }
  18. }
  19. {% endchart %}

效果如下所示：
{% chart %}
{
“data”: {
“type”: “bar”,
“columns”: [
[“data1”, 30, 200, 100, 400, 150, 250],
[“data2”, 50, 20, 10, 40, 15, 25]
],
“axes”: {
“data2”: “y2”
}
},
“axis”: {
“y2”: {
“show”: true
}
}
}
{% endchart %}

Sharing-plus

分享当前页面，比默认的 sharing 插件多了一些分享方式。

插件地址

  1.  plugins: ["-sharing", "sharing-plus"]

配置:

  1. "pluginsConfig": {
  2.     "sharing": {
  3.        "douban": false,
  4.        "facebook": false,
  5.        "google": true,
  6.        "hatenaBookmark": false,
  7.        "instapaper": false,
  8.        "line": true,
  9.        "linkedin": true,
  10.        "messenger": false,
  11.        "pocket": false,
  12.        "qq": false,
  13.        "qzone": true,
  14.        "stumbleupon": false,
  15.        "twitter": false,
  16.        "viber": false,
  17.        "vk": false,
  18.        "weibo": true,
  19.        "whatsapp": false,
  20.        "all": [
  21.            "facebook", "google", "twitter",
  22.            "weibo", "instapaper", "linkedin",
  23.            "pocket", "stumbleupon"
  24.        ]
  25.    }
  26. }

为页面添加页脚

插件地址

  1. "plugins": [
  2.    "tbfed-pagefooter"
  3. ],
  4. "pluginsConfig": {
  5.     "tbfed-pagefooter": {
  6.         "copyright":"Copyright &copy zhangjikai.com 2017",
  7.         "modify_label": "该文件修订时间：",
  8.         "modify_format": "YYYY-MM-DD HH:mm:ss"
  9.     }
  10. }

Expandable-chapters-small

使左侧的章节目录可以折叠

插件地址

  1. plugins: ["expandable-chapters-small"]

Toggle-chapters

使左侧的章节目录可以折叠。相比expandable-chapters， 没有折叠箭头符号，并且当前只有一项可以展开。参考：https://blog.csdn.net/lintcgirl/article/details/54314113

插件地址

  1. plugins: ["toggle-chapters"]

Sectionx

将页面分块显示，标签的 tag 最好是使用 b 标签，如果使用 h1-h6 可能会和其他插件冲突。
插件地址 

  1. {
  2.     "plugins": [
  3.        "sectionx"
  4.    ],
  5.     "pluginsConfig": {
  6.         "sectionx": {
  7.           "tag": "b"
  8.         }
  9.       }
  10. }

使用示例

Insert markdown content here (you should start with h3 if you use heading).

GA

Google 统计
插件地址

  1. "plugins": [
  2.     "ga"
  3.  ],
  4. "pluginsConfig": {
  5.     "ga": {
  6.         "token": "UA-XXXX-Y"
  7.     }
  8. }

3-ba

百度统计
插件地址

  1. {
  2.     "plugins": ["3-ba"],
  3.     "pluginsConfig": {
  4.         "3-ba": {
  5.             "token": "xxxxxxxx"
  6.         }
  7.     }
  8. }

Donate

打赏插件
插件地址 

  1. "plugins": [
  2.     "donate"
  3. ],
  4. "pluginsConfig": {
  5.     "donate": {
  6.         "wechat": "https://zhangjikai.com/resource/weixin.png",
  7.         "alipay": "https://zhangjikai.com/resource/alipay.png",
  8.         "title": "",
  9.         "button": "赏",
  10.         "alipayText": "支付宝打赏",
  11.         "wechatText": "微信打赏"
  12.     }
  13. }

Local Video

使用Video.js 播放本地视频
插件地址 

  1. "plugins": [ "local-video" ]

使用示例：为了使视频可以自适应，我们指定视频的width为100%，并设置宽高比为16:9，如下面所示

  1. {% raw %}
  2. <video id="my-video" class="video-js" controls preload="auto" width="100%"
  3. poster="https://zhangjikai.com/resource/poster.jpg" data-setup='{"aspectRatio":"16:9"}'>
  4.   <source src="https://zhangjikai.com/resource/demo.mp4" type='video/mp4' >
  5.   <p class="vjs-no-js">
  6.     To view this video please enable JavaScript, and consider upgrading to a web browser that
  7.     <a href="http://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a>
  8.   </p>
  9. </video>
  10. {% endraw %}

另外我们还要再配置下css，即在website.css中加入

  1. .video-js {
  2.     width:100%;
  3.     height: 100%;
  4. }



{% raw %}


To view this video please enable JavaScript, and consider upgrading to a web browser that
supports HTML5 video



{% endraw %}

Simple-page-toc

自动生成本页的目录结构。另外 GitBook 在处理重复的标题时有些问题，所以尽量不适用重复的标题。
插件地址 

  1. {
  2.     "plugins" : [
  3.         "simple-page-toc"
  4.     ],
  5.     "pluginsConfig": {
  6.         "simple-page-toc": {
  7.             "maxDepth": 3,
  8.             "skipFirstH1": true
  9.         }
  10.     }
  11. }

使用方法: 在需要生成目录的地方加上 <!— toc —>

Anchors

添加 Github 风格的锚点样式

插件 - 图2

插件地址

  1. "plugins" : [ "anchors" ]

Anchor-navigation-ex

添加Toc到侧边悬浮导航以及回到顶部按钮。需要注意以下两点：

  • 本插件只会提取 h[1-3] 标签作为悬浮导航
  • 只有按照以下顺序嵌套才会被提取
    1. # h1
    2. ## h2
    3. ### h3
    4. 必须要以 h1 开始，直接写 h2 不会被提取
    5. ## h2

插件地址

  1. {
  2.     "plugins": [
  3.         "anchor-navigation-ex"
  4.     ],
  5.     "pluginsConfig": {
  6.         "anchor-navigation-ex": {
  7.             "isRewritePageTitle": true,
  8.             "isShowTocTitleIcon": true,
  9.             "tocLevel1Icon": "fa fa-hand-o-right",
  10.             "tocLevel2Icon": "fa fa-hand-o-right",
  11.             "tocLevel3Icon": "fa fa-hand-o-right"
  12.         }
  13.     }
  14. }

如果将 GitBook 的源文件保存到github或者其他的仓库上，使用该插件可以链接到当前页的源文件上。
插件地址 

  1. "plugins": ["edit-link"],
  2. "pluginsConfig": {
  3.     "edit-link": {
  4.         "base": "https://github.com/USER/REPO/edit/BRANCH",
  5.         "label": "Edit This Page"
  6.     }
  7. }

Sitemap-general

生成sitemap
插件地址 

  1. {
  2.     "plugins": ["sitemap-general"],
  3.     "pluginsConfig": {
  4.         "sitemap-general": {
  5.             "prefix": "http://gitbook.zhangjikai.com"
  6.         }
  7.     }
  8. }

Favicon

更改网站的 favicon.ico
插件地址 

  1. {
  2.     "plugins": [
  3.         "favicon"
  4.     ],
  5.     "pluginsConfig": {
  6.         "favicon": {
  7.             "shortcut": "assets/images/favicon.ico",
  8.             "bookmark": "assets/images/favicon.ico",
  9.             "appleTouch": "assets/images/apple-touch-icon.png",
  10.             "appleTouchMore": {
  11.                 "120x120": "assets/images/apple-touch-icon-120x120.png",
  12.                 "180x180": "assets/images/apple-touch-icon-180x180.png"
  13.             }
  14.         }
  15.     }
  16. }

Todo

添加 Todo 功能。默认的 checkbox 会向右偏移 2em，如果不希望偏移，可以在 website.css 里加上下面的代码:

  1. input[type=checkbox]{
  2.     margin-left: -2em;
  3. }

插件地址 

  1. "plugins": ["todo"]

使用示例：

  • write some articles
  • drink a cup of tea

Terminal

模拟终端显示，主要用于显示命令以及多行输出，不过写起来有些麻烦。

插件地址

  1. {
  2.     "plugins": [
  3.         "terminal"
  4.     ],
  5.     "pluginsConfig": {
  6.         "terminal": {
  7.             "copyButtons": true,
  8.             "fade": false,
  9.             "style": "flat"
  10.         }
  11.     }
  12. }

现在支持 6 种标签：

  • command: Command “executed” in the terminal.
  • delimiter: Sequence of characters between the prompt and the command.
  • error: Error message.
  • path: Directory path shown in the prompt.
  • prompt: Prompt of the user.
  • warning: Warning message.

标签的使用格式如下所示：

  1. **[<tag_name> 内容]

为了使标签正常工作，需要在代码块的第一行加入 **[termial] 标记，下面是一个完整的示例：

  1. ```
  2. **[terminal]
  3. **[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
  4. Normal output line. Nothing special here...
  5. But...
  6. You can add some colors. What about a warning message?
  7. **[warning [WARNING] The color depends on the theme. Could look normal too]
  8. What about an error message?
  9. **[error [ERROR] This is not the error you are looking for]
  10. ```

效果如下所示：

  1. **[terminal]
  2. **[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
  3. Normal output line. Nothing special here...
  4. But...
  5. You can add some colors. What about a warning message?
  6. **[warning [WARNING] The color depends on the theme. Could look normal too]
  7. What about an error message?
  8. **[error [ERROR] This is not the error you are looking for]

terminal 支持下面 5 种样式，如果需要更换样式，在 pluginsConfig 里配置即可。

  • black: Just that good old black terminal everybody loves.
  • classic: Looking for green color font over a black background? This is for you.
  • flat: Oh, flat colors. I love flat colors. Everything looks modern with them.
  • ubuntu: Admit it or not, but Ubuntu have a good looking terminal.
  • white: Make your terminal to blend in with your GitBook.

Copy-code-button

为代码块添加复制的按钮。

插件地址

  1. {
  2.     "plugins": ["copy-code-button"]
  3. }

效果如下图所示：

插件 - 图3

Alerts

添加不同 alerts 样式的 blockquotes，目前包含 info, warning, danger 和 success 四种样式。

插件地址

  1. {
  2.     "plugins": ["alerts"]
  3. }

下面是使用示例：

  1. Info styling
  2. > **[info] For info**
  3. >
  4. > Use this for infomation messages.
  6. Warning styling
  7. > **[warning] For warning**
  8. >
  9. > Use this for warning messages.
  11. Danger styling
  12. > **[danger] For danger**
  13. >
  14. > Use this for danger messages.
  16. Success styling
  17. > **[success] For info**
  18. >
  19. > Use this for success messages.

效果如下所示：

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.

Include-csv

展示 csv 文件。

插件地址

  1. {
  2.     "plugins": ["include-csv"]
  3. }

使用示例：

  1. {% includeCsv  src="./assets/csv/test.csv", useHeader="true" %} {% endincludeCsv %}

效果如下所示：

{% includeCsv src=”./assets/csv/test.csv”, useHeader=”true” %} {% endincludeCsv %}

Musicxml

支持 musicxml 格式的乐谱渲染。

插件地址
musicXML

  1. {
  2.     "plugins": ["musicxml"]
  3. }

下面是一个示例，需要注意的是 block 中的内容必须是一个合法的 musicxml 文件路径，并且不能有换行和空格。

  1. {% musicxml %}assets/musicxml/mandoline - debussy.xml{% endmusicxml %}

效果如下所示
{% musicxml %}assets/musicxml/mandoline - debussy.xml{% endmusicxml %}

Klipse

集成 Klipse (online code evaluator)

插件地址
Klipse

  1. {
  2.     "plugins": ["klipse"]
  3. }

klipse 目前支持下面的语言：

  • javascript: evaluation is done with the javascript function eval and pretty printing of the result is done with pretty-format
  • clojure[script]: evaluation is done with Self-Hosted Clojurescript
  • ruby: evaluation is done with Opal
  • C++: evaluation is done with JSCPP
  • python: evaluation is done with Skulpt
  • scheme: evaluation is done with BiwasScheme
  • PHP: evaluation is done with Uniter
  • BrainFuck
  • JSX
  • EcmaScript2017
  • Google Charts: See Interactive Business Report with Google Charts.

下面是一个使用示例：

  1. ```eval-python
  2. print [x + 1 for x in range(10)]
  3. ```

效果如下所示：

  1. print [x + 1 for x in range(10)]

Versions-select

添加版本选择的下拉菜单，针对文档有多个版本的情况。

插件地址

  1. {
  2.     "plugins": [ "versions-select" ],
  3.     "pluginsConfig": {
  4.         "versions": {
  5.             "options": [
  6.                 {
  7.                     "value": "http://gitbook.zhangjikai.com",
  8.                     "text": "v3.2.2"
  9.                 },
  10.                 {
  11.                     "value": "http://gitbook.zhangjikai.com/v2/",
  12.                     "text": "v2.6.4"
  13.                 }
  14.             ]
  15.         }
  16.     }
  17. }

我们可以自定义 css 来修改 select 的显示样式：

  1. .versions-select select {
  2.     height: 2em;
  3.     line-height: 2em;
  4.     border-radius: 4px;
  5.     background: #efefef;
  6. }

效果见左上角。

RSS

添加 rss 订阅功能。

插件地址

  1. {
  2.     "plugins": [ "rss" ],
  3.     "pluginsConfig": {
  4.         "rss": {
  5.             "title": "GitBook 使用教程",
  6.             "description": "记录 GitBook 的配置和一些插件的使用",
  7.             "author": "Jikai Zhang",
  8.             "feed_url": "http://gitbook.zhangjikai.com/rss",
  9.             "site_url": "http://gitbook.zhangjikai.com/",
  10.             "managingEditor": "me@zhangjikai.com",
  11.             "webMaster": "me@zhangjikai.com",
  12.             "categories": [
  13.                 "gitbook"
  14.             ]
  15.         }
  16.     }
  17. }

效果见右上角。

theme-comscore

主题插件, 修改标题和表格颜色。默认标题都是黑色的。

插件地址

  1. {
  2. "plugins": [
  3.         "theme-comscore"
  4.     ]
  5. }

summary

根据文件自动生成目录。

插件地址

  1. {
  2. "plugins": [
  3.         "summary"
  4.     ]
  5. }

规则：

  • 每个新增的目录中加入README.md，否则菜单为不可折叠
  • 同个目录下的文件采用自然排序来决定菜单生成的前后顺序， 故在文件或目录前加入 “数字-“ 如 “0-“ 或 “1-“ 来排序菜单的前后顺序。
  • 菜单由目录自动生成，菜单名称依赖md文件中的标题， 故每个md文件中必须添加标题, 否则无法生成目录。

示例：

我们假设您的源代码树是这样完成的：

  1. $ tree .
  2. .
  3. ├── 1-Getting Started
  4. │   ├── 0-README.md
  5. │   └── 1-TEST.md
  6. ├── 2-Reference
  7. │   └── 0-README.md
  8. ├── README.md
  9. └── SUMMARY.md

生成的SUMMARY.md文件将如下所示：

  1. - [Getting Started](1-Getting Started/0-README.md)
  2.     - [Test](1-Getting Started/1-TEST.md)
  3. - [Reference](2-Reference/0-README.md)