高级用法

如果想要修改页面的显示或者定制某些页面的部分, 可以参考官方文档上的 Customization 部分. 以下只介绍一些常用的定制功能.

1. 主题
2. 定义变量
3. 页面的通用修改
4. 插件
5. 流程图

主题

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

这里是使用主题的方法.

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

默认主题

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

faq 主题

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

api 主题

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

定义变量

局部变量

我们可以在每个 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 = "李四" %}

想要了解更多的系统变量, 请参考这里

页面的通用修改

上面已经介绍过页面的主题, 当我们没有主动设置一个主题时, 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 两个选择给用户使用.

常用插件列表可以参考这些:

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

流程图

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

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

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

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

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

customization.md 4.6 KB Historie Surový