book.json

gitbook 在编译书籍的时候会读取书籍源码顶层目录中的 book.js 或者 book.json，这里以 book.json 为例，参考 gitbook 文档 可以知道，book.json 支持如下配置：

  1. {
  2.     // Folders to use for output
  3.     // Caution: it overrides the value from the command line
  4.     // It's not advised this option in the book.json
  5.     "output": null,
  7.     // Generator to use for building
  8.     // Caution: it overrides the value from the command line
  9.     // It's not advised this option in the book.json
  10.     "generator": "site",
  12.     // Book metadats (somes are extracted from the README by default)
  13.     "title": null,
  14.     "description": null,
  15.     "isbn": null,
  17.     // For ebook format, the extension to use for generation (default is detected from output extension)
  18.     // "epub", "pdf", "mobi"
  19.     // Caution: it overrides the value from the command line
  20.     // It's not advised this option in the book.json
  21.     "extension": null,
  23.     // Plugins list, can contain "-name" for removing default plugins
  24.     "plugins": [],
  26.     // Global configuration for plugins
  27.     "pluginsConfig": {
  28.         "fontSettings": {
  29.             "theme": "sepia", "night" or "white",
  30.             "family": "serif" or "sans",
  31.             "size": 1 to 4
  32.         }
  33.     },
  35.     // Variables for templating
  36.     "variables": {},
  38.     // Links in template (null: default, false: remove, string: new value)
  39.     "links": {
  40.         // Custom links at top of sidebar
  41.         "sidebar": {
  42.             "Custom link name": "https://customlink.com"
  43.         },
  45.         // Sharing links
  46.         "sharing": {
  47.             "google": null,
  48.             "facebook": null,
  49.             "twitter": null,
  50.             "weibo": null,
  51.             "all": null
  52.         }
  53.     },
  56.     // Options for PDF generation
  57.     "pdf": {
  58.         // Add page numbers to the bottom of every page
  59.         "pageNumbers": false,
  61.         // Font size for the fiel content
  62.         "fontSize": 12,
  64.         // Paper size for the pdf
  65.         // Choices are [u’a0’, u’a1’, u’a2’, u’a3’, u’a4’, u’a5’, u’a6’, u’b0’, u’b1’, u’b2’, u’b3’, u’b4’, u’b5’, u’b6’, u’legal’, u’letter’]
  66.         "paperSize": "a4",
  68.         // Margin (in pts)
  69.         // Note: 72 pts equals 1 inch
  70.         "margin": {
  71.             "right": 62,
  72.             "left": 62,
  73.             "top": 36,
  74.             "bottom": 36
  75.         },
  77.         //Header HTML template. Available variables: _PAGENUM_, _TITLE_, _AUTHOR_ and _SECTION_.
  78.         "headerTemplate": null,
  80.         //Footer HTML template. Available variables: _PAGENUM_, _TITLE_, _AUTHOR_ and _SECTION_.
  81.         "footerTemplate": null
  82.     }
  83. }

注意：上面的内容直接从 gitbook 文档 中复制，所以可能过期！

首先，将这个文件放到书籍代码顶层目录中，命名为 book.json，然后编译书籍：

  1. $ gitbook build

可以看到，编译完成，使用

  1. $ gitbook serve

然后将浏览器指向 http://127.0.0.1:4000，可以看到，什么都没有改变！

是的，虽然这里 book.json 文件非法，但是 gitbook build 并没有报错！所以，用户需要自己准备工具来保证 book.json 必须是一个合法的 JSON 文件，并且不能含有非法配置项。

首先，删除注释项，以及空行，如果是在 vim 中，可以执行下面的命令：

  1. :%g/\s*\/\//d
  2. :%g/^\s*$/d

然后，使用 python 来检查 book.json 是否合法，同样，在 vim 中执行下面的命令：

  1. :%!python -m json.tool

很显然，下面的配置不能通过，所以删去（注：但是默认主题却是使用的这个配置！）。

  1.     "pluginsConfig": {
  2.         "fontSettings": {
  3.             "theme": "sepia", "night" or "white",
  4.             "family": "serif" or "sans",
  5.             "size": 1 to 4
  6.         }
  7.     },

最后，剩下的内容如下：

  1. {
  2.     "description": null,
  3.     "extension": null,
  4.     "generator": "site",
  5.     "isbn": null,
  6.     "links": {
  7.         "sharing": {
  8.             "all": null,
  9.             "facebook": null,
  10.             "google": null,
  11.             "twitter": null,
  12.             "weibo": null
  13.         },
  14.         "sidebar": {}
  15.     },
  16.     "output": null,
  17.     "pdf": {
  18.         "fontSize": 12,
  19.         "footerTemplate": null,
  20.         "headerTemplate": null,
  21.         "margin": {
  22.             "bottom": 36,
  23.             "left": 62,
  24.             "right": 62,
  25.             "top": 36
  26.         },
  27.         "pageNumbers": false,
  28.         "paperSize": "a4"
  29.     },
  30.     "plugins": [],
  31.     "title": null,
  32.     "variables": {}
  33. }

现在，修改一些配置，修改后为：

  1. {
  2.     "author": "Chengwei Yang <me@chengweiyang.cn>",
  3.     "description": "This is a sample book created by gitbook",
  4.     "extension": null,
  5.     "generator": "site",
  6.     "isbn": null,
  7.     "links": {
  8.         "sharing": {
  9.             "all": null,
  10.             "facebook": null,
  11.             "google": null,
  12.             "twitter": null,
  13.             "weibo": null
  14.         },
  15.         "sidebar": {
  16.             "Chengwei's Blog": "http://www.chengweiyang.cn"
  17.         }
  18.     },
  19.     "output": null,
  20.     "pdf": {
  21.         "fontSize": 12,
  22.         "footerTemplate": null,
  23.         "headerTemplate": null,
  24.         "margin": {
  25.             "bottom": 36,
  26.             "left": 62,
  27.             "right": 62,
  28.             "top": 36
  29.         },
  30.         "pageNumbers": false,
  31.         "paperSize": "a4"
  32.     },
  33.     "plugins": [],
  34.     "title": "Sample GitBook",
  35.     "variables": {}
  36. }

现在，重新编译书籍，预览效果，如下图所示：

configure book.json

可以看到，书籍的标题变成了 “Sample GitBook”，而且在左边的导航栏中添加了一个链接！

需要注意的是：GitBook.com 上的书籍标题经试验不能通过配置 book.json 的方式修改 title，需要在书籍的属性页面中的 ‘Settings’ 中进行修改！