「效率工具」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：在左侧导航栏添加链接信息

"links" : {
    "sidebar" : {
        "Home" : "http://austinxt.github.io"
    }
}

plugins：配置使用的插件

"plugins": ["disqus"]

删除自带插件

"plugins": ["-search"]

pluginsConfig：配置插件的属性

"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，就可以显示标题前面的数字索引，默认不显示。

"theme-default": {
	"showLevel": true
}

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

API 文档

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

"plugins": ["theme-api"],
"pluginsConfig": {
    "theme-api": {
        "theme": "dark"
    }
}

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

{*% method %*}

内容区

{*% endmethod %*}

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

FAQ 文档

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

"plugins": [
        "theme-faq",
        "-lunr"
    ]

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

SUMMARY.md

# Summary

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

Git.md

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

book.json

{
  "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": "https://xieting-img.oss-cn-hangzhou.aliyuncs.com/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 初稿