「效率工具」GitBook(2):book.json 配置

Configuration · GitBook Toolchain Documentation可以了解到,我们可以灵活定制我们的书,这些选项在book.json文件中指定。

常规配置

变量 描述
root 包含所有图书文件的根文件夹的路径,除了 book.json
structure 指定自述文件,摘要,词汇表等的路径,参考 Structure paragraph
title 书名,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的
description 书籍的描述,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的。
author 作者名,在GitBook.com上,这个字段是预填的。
isbn 国际标准书号 ISBN
language 本书的语言类型 —— ISO code 。默认值是 en,可改为zh-hans
direction 文本阅读顺序,可以是 rtl (从右向左)或 ltr (从左向右),默认值依赖于 language 的值。
gitbook 应该使用的GitBook版本,使用 SemVer 规范,并接受类似于 “>= 3.0.0” 的条件。

拓展配置

links:在左侧导航栏添加链接信息

1
2
3
4
5
"links" : {
"sidebar" : {
"Home" : "http://austinxt.github.io"
}
}

plugins:配置使用的插件

1
"plugins": ["disqus"]

删除自带插件

1
"plugins": ["-search"]

pluginsConfig:配置插件的属性

1
2
3
4
5
"pluginsConfig": {
"disqus": {
"shortName": "MatrixXT"
}
}

pdf:配置 PDF 导出格式

您可以在在线平台生成 PDF,或用gitbook pdf ./ ./mybook.pdf生成 PFD(其他两种格式也是如此)

变量 描述
pdf.pageNumbers 将页码添加到每个页面的底部(默认为 true)
pdf.fontSize 基本字体大小(默认是 12)
pdf.fontFamily 基本字体样式(默认是 Arial
pdf.paperSize 页面尺寸,选项有: 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter' (默认值是 a4
pdf.margin.top 上边界(默认值是 56)
pdf.margin.bottom 下边界(默认值是 56)
pdf.margin.right 右边界(默认值是 62)
pdf.margin.left 左边界(默认值是 62)

更多定制模板,请参考:Templating · GitBook Toolchain Documentation

主题

我们常用的就是 Book 文档模式,如果您需要使用 API 文档模式或者 FAQ 文档模式,只需引入文档对应的主题插件即可。

书籍

theme-default 是默认的 Book 主题,您可以在pluginsConfig里,将 showLevel 设为 true, 就可以显示标题前面的数字索引,默认不显示。

1
2
3
"theme-default": {
"showLevel": true
}

在使用该主题的过程中,发现经常会在控制台报下面的错误,没有找到是哪里的原因,官方也一直没有修复。

API 文档

GitBook 同样可以编写 API 文档,只需要引入theme-api 插件,大部分针对文本的插件对 API 文档模式可用。

1
2
3
4
5
6
"plugins": ["theme-api"],
"pluginsConfig": {
"theme-api": {
"theme": "dark"
}
}

API 文档语法简单,以方法为基本单位,其他遵从 Markdown 语法。(以下加*仅因为 Jeklly 无法编译一些符号组合,去掉即可)

1
2
3
4
5
{*% method %*}

内容区

{*% endmethod %*}

在内容区里面,通过 {*% sample lang="lang" %*}来定义一个针对特定语言的演示,通过 {*% common %*}标识所有语言共同的部分。

FAQ 文档

theme-faq插件主要用来制作知识库或者帮助中心, GitBook Help Center 就使用了该主题。

1
2
3
4
"plugins": [
"theme-faq",
"-lunr"
]

您可以在 Summary 里配置问题以及答案所在的文件,在对应文件中写入问题的答案即可。

SUMMARY.md

1
2
3
4
# Summary

* [什么 is Git](Git.md)
* [什么 is Github](Github.md)

Git.md

1
Git 是一个分布式版本控制软件,最初由林纳斯·托瓦兹(Linus Torvalds)创作,于2005年以GPL发布。最初目的是为更好地管理Linux内核开发而设计。应注意的是,这与GNU Interactive Tools[6](一个类似Norton Commander界面的文件管理器)有所不同。

book.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
"title": "C/C++ Notebook",
"description": "",
"author": "austinxt",
"language": "zh-hans",
"links": {
"sidebar": {
"Home": "blog.austinxt.com"
}
},
"plugins": [
"disqus",
"mathjax",
"donate",
"copy-code-button",
"anchor-navigation-ex",
"-sharing"
],
"pluginsConfig": {
"theme-default": {
"showLevel": true
},
"disqus": {
"shortName": "MatrixXT"
},
"donate": {
"alipay": "http://images.stanine.top/alipay.png",
"title": "等一杯咖啡,写稿到天亮!",
"button": "赏",
"alipayText": "支付宝打赏"
},
"anchor-navigation-ex": {
"multipleH1": false,
"float": {
"showLevelIcon": true,
"level1Icon": "fa fa-hand-o-right",
"level2Icon": "fa fa-hand-o-right",
"level3Icon": "fa fa-hand-o-right"
},
"showLevel": true,
"associatedWithSummary": false
}
}
}

参考

ChangeLog

  • 2018-07-28 初稿
「谢谢您支持」