• book.json

    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’ 中进行修改！