1. 插件
gitbook 还支持许多插件，用户可以从 NPM 上搜索 gitbook 的插件，gitbook 文档 推荐插件的命名方式为：
- gitbook-plugin-X: 插件
- gitbook-theme-X: 主题
所以，可以通过以上两种方式来搜索 gitbook 的插件或者主题。
- Codeblock-filename
- Emphasize - 为文字加上底色
- Include Codeblock - 用代码块显示包含文件的内容
- KaTex - 用于支持数学公式
- mathjax - 用于编辑数学公式
- mermaid - 编辑显示流程图
- PlanUML - 编辑显示UML
- Splitter - 侧边栏的宽度可以自由调节
- Anchor-navigation-ex - 添加Toc到侧边悬浮导航以及回到顶部按钮
- Ace Plugin - 支持ace
1.1. Codeblock-filename
codeblock-filename为代码块添加文件名称
plugins: [ "codeblock-filename" ]
使用示例:
''':helloworld
helloworld
'''
'''js:test.js
console.log("test");
'''
helloworld
helloworld
test.js
console.log("test");
1.2. Emphasize
Emphasize为文字加上底色
"plugins": ["emphasize"]
gitbook install
使用方式：
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!
1.3. Include Codeblock
Include Codeblock使用代码块的格式显示所包含文件的内容. 该文件必须存在.
"plugins": [
"include-codeblock"
]
使用示例:
'''bash
{import}(path/to/file)
'''
也可以显示文件中的代码段：
{include:30-40}(path/to/file)
使用[] 代替 {}，` 代替 '效果：
{% if file.type=="asciidoc" %}++++{% endif %}
<div class="ace"><div class="aceCode" data-config={"edit":true,"lang":"json","check":false,"theme":"monokai"}>{%raw%}{
"title": "How to use gitbook",
"author": "breezetemple",
"description": "gitbook tutorial",
"language": "zh-hans",
"gitbook": "3.2.3",
"output.name": "site",
"links": {
"sharing": {
"all": null,
"facebook": null,
"google": null,
"twitter": null,
"weibo": null
},
"sidebar": {
"How to use gitbook": "https://legacy.gitbook.com/book/breezetemple/how-to-use-gitbook"
},
"gitbook": true
},
"plugins": [
"anchor-navigation-ex",
"mermaid-gb3",
"-mathjax",
"puml",
"katex",
"emphasize",
"include-codeblock",
"ace",
"splitter",
"codeblock-filename",
"multipart",
"comment"
],
"pluginsConfig": {
"theme-default": {
"showLevel": false
},
"include-codeblock": {
"template": "ace",
"unindent": true,
"edit": true,
"theme": "monokai"
},
"anchor-navigation-ex": {
"showLevel": true,
"isRewritePageTitle": false,
"associatedWithSummary": true,
"tocLevel1Icon": "fa fa-hand-o-right",
"tocLevel2Icon": "fa fa-hand-o-right",
"tocLevel3Icon": "fa fa-hand-o-right"
}
},
"github": "breezetemple/how-to-use-gitbook",
"pdf": {
"fontSize": 16
}
}{%endraw%}<br></div></div>
{% if file.type=="asciidoc" %}++++{% endif %}
"splitter",
"codeblock-filename",
"multipart",
"comment"
],
"pluginsConfig": {
"theme-default": {
"showLevel": false
},
"include-codeblock": {
"template": "ace",
1.4. KaTex
KaTex用于支持数学公式，官网上说Katex速度要快于MathJax。
安装
plugins: ["katex"]
gitbook install
与 MathJax 存在冲突，需要将之屏蔽：
plugins: ["-mathjax"]
使用示例:
When a≠0a \ne 0a≠0, there are two solutions to (ax2+bx+c=0)(ax^2 + bx + c = 0)(ax2+bx+c=0) and they are x=−b±b2−4ac2a.x = {-b \pm \sqrt{b^2-4ac} \over 2a}.x=2a−b±√b2−4ac.
∫−∞∞g(x)dx \int_{-\infty}^\infty g(x) dx ∫−∞∞g(x)dx
13 1 \over 3 31
f(x,y,z)=3y2z(3+7x+51+y2) f(x,y,z) = 3y^2z \left( 3+\frac{7x+5}{1+y^2} \right) f(x,y,z)=3y2z(3+1+y27x+5)
∑i=0n1i2 \sum_{i=0}^n \frac{1}{i^2} ∑i=0ni21
∏i=0n1i2\prod_{i=0}^n \frac{1}{i^2} ∏i=0ni21
效果：
When , there are two solutions to and they are
1.5. mathjax
GitBook plugin-mathjax用于编辑数学公式
npm install gitbook-plugin-mathjax
"plugins": ["mathjax"]
或者：
"plugins": ["mathjax"]
gitbook install
使用方式：使用 $$ 将公式包括起来：
f(x)=a+bf(x)=a+bf(x)=a+b
(ax2+bx+c=0)(ax^2 + bx + c = 0)(ax2+bx+c=0)
x=−b±b2−4ac2a.x = {-b \pm \sqrt{b^2-4ac} \over 2a}.x=2a−b±√b2−4ac.
如下：
When , there are two solutions to and they are
1.6. mermaid
gitbook-plugin-mermaid-gb3用于编辑显示流程图：
npm install gitbook-plugin-mermaid-gb3
"plugins": ["mermaid-gb3"]
或者：
"plugins": ["mermaid-gb3"]
gitbook install
使用方式：
(```mermaid)
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
(```)
生成如下：
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
1.7. UML
安装
npm install gitbook-plugin-puml
"plugins": ["puml"]
或者
"plugins": ["puml"]
gitbook install
{% plantuml %}
Class Stage
Class Timeout {
+constructor:function(cfg)
+timeout:function(ctx)
+overdue:function(ctx)
+stage: Stage
}
Stage <|-- Timeout
{% endplantuml %}
1.8. Splitter
Splitter使侧边栏的宽度可以自由调节
"plugins": [
"splitter"
]
gitbook install
1.9. Anchor-navigation-ex
添加Toc到侧边悬浮导航以及回到顶部按钮。需要注意以下两点：
- 本插件只会提取 h[1-3] 标签作为悬浮导航
- 只有按照以下顺序嵌套才会被提取
# h1 ## h2 ### h3 必须要以 h1 开始，直接写 h2 不会被提取 ## 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"
}
}
}
<extoc></extoc> 会在此处生成TOC目录，效果如下
1.10. Ace Plugin
使 GitBook 支持ace 。默认情况下，line-height 为 1，会使代码显得比较挤，而作者好像没提供修改行高的选项，如果需要修改行高，可以到 node_modules -> github-plugin-ace -> assets -> ace.js 中加入下面两行代码 (30 行左右的位置)：
editor.container.style.lineHeight = 1.25;
editor.renderer.updateFontSize();
不过上面的做法有个问题就是，每次使用 gitbook install 安装新的插件之后，代码又会重置为原来的样子。另外可以在 website.css 中加入下面的 css 代码来指定 ace 字体的大小
.aceCode {
font-size: 14px !important;
}
使用插件：
"plugins": [
"ace"
]
使用示例:
// This is a hello world program for C.
#include <stdio.h>
int main(){
printf("Hello World!");
return 1;
}