# 高级用法

>如果想要修改页面的显示或者定制某些页面的部分, 可以参考官方文档上的 [Customization 部分](https://toolchain.gitbook.com/templating/). 以下只介绍一些常用的定制功能.

**[1. 主题](#主题)** <br>
**[2. 定义变量](#定义变量)** <br>
**[3. 页面的通用修改](#页面的通用修改)** <br>
**[4. 插件](#插件)** <br>
**[5. 流程图](#流程图)**





## 主题
gitbook 支持主题, 当你的 gitbook 应用了这些主题之后, 页面显示内容的方式都会发生改变.

[这里](#插件)是使用主题的方法.

同一时间只能使用一个主题, 下面是一些常用的主题.



### 默认主题
本文档现在用的就是默认主题

### faq 主题

https://github.com/GitbookIO/theme-faq

![api](/image/theme-faq.png)

### api 主题

https://github.com/GitbookIO/theme-api

![api](/image/theme-dark.png)


## 定义变量

### 局部变量
我们可以在每个 Markdown 页面中定义变量, 并在接下来的页面内容中使用这些变量, 比如我们在某个页面 xxx.md 中这样写:

```
{% set softwareVersion = "1.0.0" %}

Current version is {{ softwareVersion }}. // 页面将会显示为 Current version is 1.0.0.

```

### 全局变量
除了局部变量外, 你也可以在项目根目录下的 `book.json` 中定义全局变量, 比如

```
...
//variables 与 title 属性平级
"variables": {
        "admin": "张三"
}
```

定义好之后, 就可以在普通的页面中使用这些变量了. 
```
联系管理员 {{ book.admin }} 解决 // 页面将会显示为 联系管理员 张三 解决
```


### 系统变量
在上面全局变量的使用中, 我们可以发现使用的是 `book.admin`, 其实这里的 `book` 就是一个系统变量, 跟他类似的还有很多系统变量, 用户都可以在页面中的任何地方去使用这些系统变量

需要注意的是, 系统变量不能动态的被修改(除非使用插件才有可能做到), 只能提前在相应的文件中定义好. 
```
//像下面这种语法是错误的, 无法动态为一个系统变量赋值
{% set book.admin = "李四" %} 
```

想要了解更多的系统变量, 请参考[这里](https://toolchain.gitbook.com/templating/variables.html)




## 页面的通用修改
上面已经介绍过页面的主题, 当我们没有主动设置一个主题时, gitbook就会自动应用它自带的默认主题. 在使用主题后, 所有 gitbook 页面都按照主题所设置的模板规则来显示, 我们可以对主题的模板规则进行修改, 这样的修改就会应用到所有页面. 

比如对于我们使用的默认模板来说, 如果我们想要修改这个默认模板的行为, 比如修改页面的 title, 可以直接对这个文件 `_layouts/website/page.html` 进行修改(没有的话请自行创建) 

```
{% extends template.self %} // 继承模板所有的内容

{% block title %} // 对模板中的 title block 进行覆写
Gitbook 帮助文档
{% endblock %}
```

对于其它的主题, 比如 api 主题或是 faq, 也是进行类似的操作就可以修改模板的行为, 只是每个模板的具体的参数和修改方式不同 


## 插件
插件是最主要的对 gitbook 进行定制化的工具, 即使主题也是插件的一种. 要使用插件, 我们需要在 `book.json` 中先声明.

以 "api 主题" 这个插件为例, 首先我们需要添加下面的内容到 `book.json` 中,
```
{
    "plugins": ["theme-api"],
    "pluginsConfig": {
        "theme-api": {
            "theme": "dark"
        }
    }
}
```

其中, `plugins` 中声明所有你想要安装的插件的名称, `pluginsConfig` 中可以对每个插件的可选配置进行修改, 比如 `theme-api` 的可选配置就是主题的颜色, 有 dark 和 light 两个选择给用户使用.

常用插件列表可以参考这些:
* https://yangjh.oschina.io/gitbook/faq/Recommand.html
* http://gitbook.wiliam.me/plugins.html

>要注意, 有些网络上的插件由于版本太老旧, 已经不适合现在的版本, 所以有的时候会出现即使安装了插件也没有任何效果的情况



## 流程图

当前的项目中, 已经在 scripts 文件夹下引入了 mermaidjs, 通过这个 js 库可以实现在 markdown 中直接通过代码的形式生成流程图.
以下是示例.

<div>
    ```mermaid
    graph TD;
        A-->B;
        A-->C;
        B-->D;
        C-->D;
    ```
<div>


---

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

mermaid 不仅可以生成流程图, 还可以生成时序图以及甘特图. 详情在这里了解: https://mermaidjs.github.io/

流程图在线实时预览生成器: https://mermaidjs.github.io/mermaid-live-editor/