2.5.1. 插件

插件是扩展 GitBook 功能（电子书和网站）最好的方式。指定插件版本格式为 donate@^1.0.2,本章介绍的插件在 GitBook 的 3.2.3 版本中都可以正常工作，当然这里只是列举了一部分插件，如有其他需求，请自行搜索。

GitBook 支持的插件可以从 https://github.com/GitbookIO 取找

将其添加至 book.json 中：

"plugins": ["myPlugin", "anotherPlugin"]

添加之后运行 gitbook install 来安装。

默认带7个插件 livereload,highlight,search,lunr,sharing,fontsettings,theme-default

如果要去除自带的插件，可以在插件名称前面加-

"plugins": [
    "-search"
]

插件
- Disqus
- Search Plus
- Prism
- advanced-emoji
- Github
- Github Buttons
- Emphasize
- Splitter
- Mermaid-gb3
- Puml
- theme-comscore
- summary
- Graph
- Chart
- Sharing-plus
- Expandable-chapters-small
- Simple-page-toc
- Anchors
- Anchor-navigation-ex
- Edit Link
- Sitemap-general
- Favicon
- Todo
- Terminal
- mathjax 和 katex
  - MathJax 和 KaTeX 的区别
  - 添加数学公式
- Tbfed-pagefooter
- Alerts
- Sectionx
- Include-csv
- Musicxml
- Klipse
- RSS
- GA
- 3-ba
- Donate
- local-video

2.5.1.1. Disqus

添加 disqus 评论

"plugins": [
    "disqus"
],
"pluginsConfig": {
    "disqus": {
        "shortName": "gitbookuse"
    }
}

2.5.1.2. Search Plus

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

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

2.5.1.3. Prism

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

{
    "plugins": [
        "prism",
        "-highlight"
    ],
    "pluginsConfig": {
        "prism": {
            "css": [
                "prism-themes/themes/prism-base16-ateliersulphurpool.light.css"
            ]
        }
    }
}

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

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

2.5.1.4. advanced-emoji

支持 emoji 表情

emoij表情列表

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

示例

2.5.1.5. Github

添加 Github 图标位置在右上角

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

2.5.1.6. Github Buttons

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

{
    "plugins": [
        "github-buttons"
    ],
    "pluginsConfig": {
        "github-buttons": {
            "repo": "augutdoit/book",
            "types": [
                "star",
                "watch",
                "fork"
            ],
            "size": "small"
        }
    }
}

2.5.1.7. Emphasize

为文字加上底色

"plugins": [
    "emphasize"
]

使用方法

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

效果

This text is highlighted !

This text is highlighted with markdown!

This text is highlighted in green!

This text is highlighted in red!

This text is highlighted with a custom color!

2.5.1.8. Splitter

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

"plugins": [
    "splitter"
]

2.5.1.9. Mermaid-gb3

支持渲染Mermaid图表

"plugins": [
    "mermaid-gb3"
]

使用方法：

{% mermaid %}
....
{% endmermaid %}

或

```mermaid

graph TD;

A-->B;

A-->C;

B-->D;

C-->D;

```

效果

graph TD; A-->B; A-->C; B-->D; C-->D;

或示例:

{% mermaid %}
sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
{% endmermaid %}

效果：

sequenceDiagram Alice->>John: Hello John, how are you? loop Healthcheck John->>John: Fight against hypochondria end Note right of John: Rational thoughts! John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good!

2.5.1.10. Puml

使用 PlantUML 展示 uml 图。

{
    "plugins": ["puml"]
}

使用示例：

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

效果

2.5.1.11. theme-comscore

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

{
"plugins": [
        "theme-comscore"
    ]
}

2.5.1.12. summary

根据文件自动生成目录。

{
"plugins": [
        "summary"
    ]
}

规则：

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

示例：

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

tree .
.
├── ORDER
│   ├── 0-README.md
│   └── 1-orderInfo.md
├── README.md
├── SUMMARY.md
└── USER
    ├── 0-README.md
    └── 1-userInfo.md

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

- ORDER
  * [0 README](ORDER/0-README.md)
  * [1 Order Info](ORDER/1-orderInfo.md)
- USER
  * [0 README](USER/0-README.md)
  * [1 User Info](USER/1-userInfo.md)

2.5.1.13. Graph

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

{
    "plugins": [ "graph" ],
}

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

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

效果如下：

2.5.1.14. Chart

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

{
    "plugins": [ "chart" ],
    "pluginsConfig": {
        "chart": {
            "type": "c3"
        }
    }
}

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

示例：

{% 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 插件多了一些分享方式。

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

可用的包括 douban、facebook、google、hatenaBookmark、instapaper、line、linkedin、messenger、pocket、qq、qzone、stumbleupon、twitter、viber、vk、weibo、whatsapp

个人用的配置:

"pluginsConfig": {
    "sharing": {
       "twitter": false,
       "facebook": true,
       "weibo": true,
       "all": []
   }

2.5.1.16. Expandable-chapters-small

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

plugins: ["expandable-chapters-small"]

2.5.1.17. Simple-page-toc

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

{
"plugins" : [
    "simple-page-toc"
],
    "pluginsConfig": {
        "simple-page-toc": {
        "maxDepth": 3,
        "skipFirstH1": true
        }
    }
}

使用方法: 在需要生成目录的地方加上

2.5.1.18. Anchors

添加 Github 风格的锚点样式。若装了Anchor-navigation-ex 就不用再单装了

"plugins" : [ "anchors" ]

插件地址

在页面中增加<extoc></extoc>标签，会在此处生成TOC目录在页面中增加标签，不会在该页面生成悬浮导航

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

本插件只会提取 h[1-3] 标签作为悬浮导航只有按照以下顺序嵌套才会被提取

# h1
## h2
### h3
必须要以 h1 开始，直接写 h2 不会被提取
## h2

必须要以 h1 开始，直接写 h2 不会被提取

{
    "plugins": [
        "anchor-navigation-ex"
    ],
    "pluginsConfig": {
        "anchor-navigation-ex": {
            "isRewritePageTitle": true,
            "isShowTocTitleIcon": true,
            "tocLevel1Icon": "fa fa-hand-o-right",
            "tocLevel2Icon": "fa fa-hand-o-right",
            "tocLevel3Icon": "fa fa-hand-o-right"
        }
    }
}

2.5.1.20. Edit Link

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

"plugins": ["edit-link"],
"pluginsConfig": {
    "edit-link": {
        "base": "https://github.com/USER/REPO/edit/BRANCH",
        "label": "Edit This Page"
    }
}

2.5.1.21. Sitemap-general

生成sitemap

{
    "plugins": ["sitemap-general"],
    "pluginsConfig": {
        "sitemap-general": {
            "prefix": "你的网址"
        }
    }
}

2.5.1.22. Favicon

更改网站的 favicon.ico

{
    "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"
            }
        }
    }
}

2.5.1.23. Todo

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

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

"plugins": ["todo"]

使用示例：

- [ ] write some articles
- [x] drink a cup of tea

效果：

write some articles
drink a cup of tea

2.5.1.24. Terminal

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

{
    "plugins": [
        "terminal"
    ],
    "pluginsConfig": {
        "terminal": {
            "copyButtons": true,
            "fade": false,
            "style": "flat"
        }
    }
}

现在支持 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

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

**[<tag_name> 内容]

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

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

效果

**[terminal]
**[prompt foo@joe]**[path ~]**[delimiter  $ ]**[command ./myscript]
Normal output line. Nothing special here...
But...
You can add some colors. What about a warning message?
**[warning [WARNING] The color depends on the theme. Could look normal too]
What about an error message?
**[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.

2.5.1.25. Copy-code-button

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

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

2.5.1.26. mathjax 和 katex

GitBook 可以使用插件支持数学公式和 Tex。当前有两个官方的插件用来显示数学公式：mathjax 和 katex。

{
    "plugins": ["mathjax"]
}

2.5.1.26.1. MathJax 和 KaTeX 的区别

mathjax 和 katex 插件是 Tex 公式绘制的不同实现，它们基于各自的开源库：KaTeX 和 MathJax 。

MathJax 支持整个 Tex 语法，但是在制作电子书版本时不是很完美。 KaTex 在所有格式（网页和电子书）的绘制上都很完美，但是还不支持所有的语法。

2.5.1.26.2. 添加数学公式

用 {% math %} 添加 Tex 公式

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

效果：

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

报错解决

PluginError: Error with plugin "mathjax": Cannot find module 'mathjax/unpacked/MathJax'

一般出现在新安装或更新mathjax后，解决办法为,为mathjax降级，安装 2.7.6版本

sudo npm install [email protected]
gitbook install

2.5.1.27. Tbfed-pagefooter

为页面添加页脚

{
    "plugins": [
       "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
             "copyright":"Copyright &copy augustdoit 2020",
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

2.5.1.28. Alerts

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

{
    "plugins": ["alerts"]
}

下面是使用示例：

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.

效果如下所示：

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.

2.5.1.29. Sectionx

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

{
    "plugins": [
       "sectionx"
   ],
    "pluginsConfig": {
        "sectionx": {
          "tag": "b"
        }
      }
}

使用示例

<!--sec data-title="Sectionx Demo" data-id="section0" data-show=true ces-->
插入内容...
<!--endsec-->

Sectionx Demo

插入内容...

2.5.1.30. Include-csv

展示 csv 文件。

{
    "plugins": ["include-csv"]
}

使用示例：

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

效果

csv/test.csv

产业	数值	比重
第一产业	111	10.00%
第二产业	222	20.00%
第三产业	333	30.00%
第四产业	444	40.00%

2.5.1.31. Musicxml

支持 musicxml 格式的乐谱渲染

{
    "plugins": ["musicxml"]
}

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

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

效果

2.5.1.32. Klipse

集成 Klipse (online code evaluator)

{
    "plugins": ["klipse"]
}

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.

示例：

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

效果

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

2.5.1.33. RSS

添加 rss 订阅功能。

{
    "plugins": [ "rss" ],
    "pluginsConfig": {
        "rss": {
            "title": "网站名",
            "description": "描述",
            "author": "作者",
            "feed_url": "http://xxx.com/rss",
            "site_url": "http://xxx.com/",
            "managingEditor": "[email protected]",
            "webMaster": "[email protected]",
            "categories": [
                "gitbook"
            ]
        }
    }
}

2.5.1.34. GA

Google 统计

"plugins": [
    "ga"
 ],
"pluginsConfig": {
    "ga": {
        "token": "UA-XXXX-Y"
    }
}

2.5.1.35. 3-ba

百度统计

{
    "plugins": ["3-ba"],
    "pluginsConfig": {
        "3-ba": {
            "token": "xxxxxxxx"
        }
    }
}

2.5.1.36. Donate

打赏插件

"plugins": [
    "donate"
],
"pluginsConfig": {
    "donate": {
        "wechat": "https://xxx.com/resource/weixin.png",
        "alipay": "https://xxx.com/resource/alipay.png",
        "title": "",
        "button": "赏",
        "alipayText": "支付宝打赏",
        "wechatText": "微信打赏"
    }
}

2.5.1.37. local-video

使用 Video.js 播放视频

"plugins": [ "local-video" ]

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

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

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

.video-js {
    width:100%;
    height: 100%;
}

2.5.1. 插件

2.5.1.1. Disqus

2.5.1.2. Search Plus

2.5.1.3. Prism

2.5.1.4. advanced-emoji

2.5.1.5. Github

2.5.1.6. Github Buttons

2.5.1.7. Emphasize

2.5.1.8. Splitter

2.5.1.9. Mermaid-gb3

2.5.1.10. Puml

2.5.1.11. theme-comscore

2.5.1.12. summary

2.5.1.13. Graph

2.5.1.14. Chart

2.5.1.15. Sharing-plus

2.5.1.16. Expandable-chapters-small

2.5.1.17. Simple-page-toc

2.5.1.18. Anchors

2.5.1.19. Anchor-navigation-ex

2.5.1.20. Edit Link

2.5.1.21. Sitemap-general

2.5.1.22. Favicon

2.5.1.23. Todo

2.5.1.24. Terminal

2.5.1.25. Copy-code-button

2.5.1.26. mathjax 和 katex

2.5.1.26.1. MathJax 和 KaTeX 的区别

2.5.1.26.2. 添加数学公式

2.5.1.27. Tbfed-pagefooter

2.5.1.28. Alerts

2.5.1.29. Sectionx

2.5.1.30. Include-csv

2.5.1.31. Musicxml

2.5.1.32. Klipse

2.5.1.33. RSS

2.5.1.34. GA

2.5.1.35. 3-ba

2.5.1.36. Donate

2.5.1.37. local-video

results matching ""

No results matching ""