1 Gitbook Start

1. 介绍

Gitbook 是一款优秀的 基于 Node.js 的开源文档管理工具，具有丰富的开源插件。

GitBook 支持 Markdown 和 AsciiDoc 两种语法格式，能够输出 html，pdf，epub，mobi 等多种格式。

2. 条件

nodejs 安装 node一定要安装10.X版本，否则报如下错误：

CLI version: 2.3.2
Installing GitBook 3.2.3
/usr/local/node/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
      if (cb) cb.apply(this, arguments)
                 ^

TypeError: cb.apply is not a function
    at /usr/local/node/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (fs.js:193:5)

系统：ubuntu：18.04

3. 安装 gitbook工具

$ npm install gitbook-cli -g
/usr/local/node/bin/gitbook -> /usr/local/node/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 191.662s

#找到gitbook命令位置
$ ls /usr/local/node-v10.24.0-linux-x64/bin/
gitbook            node               node_modules/      npm                npx                package-lock.json

#添加软连接
$ ln -s /usr/local/node-v17.4.0-linux-x64/bin/gitbook /usr/local/bin/


$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
gitbook@3.2.3 ../../../../tmp/tmp-117466TKiRhUq3ov0O/node_modules/gitbook
├── escape-html@1.0.3
├── escape-string-regexp@1.0.5
├── destroy@1.0.4
├── ignore@3.1.2
├── bash-color@0.0.4
├── gitbook-plugin-livereload@0.0.1
├── cp@0.2.0
├── nunjucks-do@1.0.0
├── graceful-fs@4.1.4
├── github-slugid@1.0.1
├── direction@0.1.5
├── q@1.4.1
├── spawn-cmd@0.0.2
├── gitbook-plugin-fontsettings@2.0.0
├── open@0.0.5
├── is@3.3.0
├── object-path@0.9.2
├── extend@3.0.2
├── json-schema-defaults@0.1.1
├── gitbook-plugin-search@2.2.1
├── jsonschema@1.1.0
├── crc@3.4.0
├── urijs@1.18.0
├── semver@5.1.0
├── immutable@3.8.2
├── front-matter@2.3.0
├── npmi@2.0.1 (semver@4.3.6)
├── resolve@1.1.7
├── gitbook-plugin-theme-default@1.0.7
├── moment@2.13.0
├── npm@3.9.2
├── dom-serializer@0.1.0 (domelementtype@1.1.3, entities@1.1.2)
├── tmp@0.0.28 (os-tmpdir@1.0.2)
├── error@7.0.2 (xtend@4.0.2, string-template@0.2.1)
├── omit-keys@0.1.0 (isobject@0.2.0, array-difference@0.0.1)
├── mkdirp@0.5.1 (minimist@0.0.8)
├── js-yaml@3.14.1 (esprima@4.0.1, argparse@1.0.10)
├── gitbook-plugin-lunr@1.2.0 (html-entities@1.2.0, lunr@0.5.12)
├── gitbook-plugin-highlight@2.0.2 (highlight.js@9.2.0)
├── gitbook-plugin-sharing@1.0.2 (lodash@3.10.1)
├── i18n-t@1.0.1 (lodash@4.17.21)
├── gitbook-markdown@1.3.2 (kramed-text-renderer@0.2.1, gitbook-html@1.3.3, kramed@0.5.6, lodash@4.17.21)
├── gitbook-asciidoc@1.2.2 (gitbook-html@1.3.3, asciidoctor.js@1.5.5-1, lodash@4.17.21)
├── send@0.13.2 (fresh@0.3.0, etag@1.7.0, statuses@1.2.1, range-parser@1.0.3, ms@0.7.1, depd@1.1.2, mime@1.3.4, debug@2.2.0, http-errors@1.3.1, on-finished@2.3.0)
├── fresh-require@1.0.3 (is-require@0.0.1, shallow-copy@0.0.1, astw@1.3.0, acorn@0.9.0, sleuth@0.1.1, escodegen@1.14.3, through2@0.6.5)
├── rmdir@1.2.0 (node.flow@1.2.3)
├── request@2.72.0 (tunnel-agent@0.4.3, aws-sign2@0.6.0, forever-agent@0.6.1, oauth-sign@0.8.2, is-typedarray@1.0.0, caseless@0.11.0, stringstream@0.0.6, aws4@1.11.0, isstream@0.1.2, json-stringify-safe@5.0.1, tough-cookie@2.2.2, node-uuid@1.4.8, qs@6.1.2, hawk@3.1.3, combined-stream@1.0.8, mime-types@2.1.34, http-signature@1.1.1, form-data@1.0.1, bl@1.1.2, har-validator@2.0.6)
├── read-installed@4.0.3 (debuglog@1.0.1, util-extend@1.0.3, slide@1.1.6, readdir-scoped-modules@1.1.0, read-package-json@2.1.2)
├── cpr@1.1.1 (rimraf@2.4.5)
├── tiny-lr@0.2.1 (parseurl@1.3.3, livereload-js@2.4.0, qs@5.1.0, debug@2.2.0, faye-websocket@0.10.0, body-parser@1.14.2)
├── cheerio@0.20.0 (entities@1.1.2, lodash@4.17.21, css-select@1.2.0, htmlparser2@3.8.3, jsdom@7.2.2)
├── juice@2.0.0 (deep-extend@0.4.2, slick@1.12.2, batch@0.5.3, cssom@0.3.1, cross-spawn-async@2.2.5, commander@2.9.0, web-resource-inliner@2.0.0)
├── chokidar@1.5.0 (async-each@1.0.3, path-is-absolute@1.0.1, inherits@2.0.4, glob-parent@2.0.0, is-glob@2.0.1, is-binary-path@1.0.1, anymatch@1.3.2, readdirp@2.2.1)
└── nunjucks@2.5.2 (asap@2.0.6, yargs@3.32.0, chokidar@1.7.0)
GitBook version: 3.2.3

4. 创建gitbook书籍

$ mkdir gitbook-demo
$ cd gitbook-demo

#使用 gitbook init 初始化书籍目录
$ gitbook init 
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 

$ ls 
README.md  SUMMARY.md
#使用 gitbook build 编译书籍
$ gitbook build
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.4s ! 


$ ls
_book  README.md  SUMMARY.md

$ ls _book/
gitbook  index.html  search_index.json

$ ls _book/gitbook/
fonts  gitbook.js  gitbook-plugin-fontsettings  gitbook-plugin-highlight  gitbook-plugin-lunr  gitbook-plugin-search  gitbook-plugin-sharing  images  style.css  theme.js

#使用 gitbook serve 编译并预览书籍
$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.5s ! 

Starting server ...
Serving book on http://localhost:4000

效果 图中侧栏Introduction的内容正是README.md的内容，SUMMARY.md 是编写界面侧栏的目录结构。

$ cat README.md 
# Introduction

$ cat SUMMARY.md 
# Summary

* [Introduction](README.md)

5. SUMMARY.md

GitBook 使用文件 SUMMARY.md 来定义书本的章节和子章节的结构。文件 SUMMARY.md 被用来生成书本内容的预览表。 SUMMARY.md 的格式是一个简单的链接列表，链接的名字是章节的名字，链接的指向是章节文件的路径。子章节被简单的定义为一个内嵌于父章节的列表。以 # 开头的行为注释被忽略。 GitBook使用一个SUMMARY.md文件来定义文档的菜单。 虽说在官方文档中，它是可选的，但是它相当重要，控制了左边菜单栏的显示内容。它通过 Markdown 中的列表语法来表示文件的父子关系。紧凑型的。

创建一个目录，并编写一个markdown格式的文档

$ mkdir git
$ mv git_training.md git
$ ls
_book  book.json  book.json_bak  git  kubernetes  node_modules  README.md  SUMMARY.md
$ ls git/
1_git_introduce.md  2_git_command.md

编写SUMMARY.md

# Summary
  
## 前言

* [Introduction](README.md)

## git

* [git 介绍](git/1_git_introduce.md)
  * [git 命令](git/2_git_training.md)

启动

$ gitbook serve

效果： 当 md 文件数量非常多时，我们可以利用 插件 summary 自动生成菜单 summary 文件的介绍。

6. README.md

书本的首页内容默认是从文件 README.md 中提取的。

README.md是 gitbook 最基础的文件之一，它一般用来描述这本书最基本的信息。 它呈现给读者这本书最初的样子，如果内容不够简洁明了，很可能就没有看下去的欲望了。

可以通过 gitbook init 自动创建该文件。

如果这个文件名没有出现在 SUMMARY.md (目录索引文件) 中，那么它会被添加为章节的第一个条目。

如何替代README.md

一些项目更愿意将 README.md 文件作为项目的介绍而不是书的介绍。

大部分代码托管平台将 README.md 自动显示到项目首页，如果你不喜欢这样。 从GitBook >2.0.0 起，就可以在 book.json 中定义某个文件作为README。

删除掉SUMMARY.md文档关于README.md的引用 编写information.md

$ cat information.md 
---
这是一本关于介绍git、github、gitlab、gitbook的书籍。

比起官方的理解，它更接近体验训练。

book.json添加structure参数

book.json
{
    "structure" : {
        "readme" : "information.md"
    }
}

启动

$ gitbook serve

效果：默认的首页

7. book.json

7.1 侧栏添加链接

$ ls
_book  book.json  kubernetes  README.md  SUMMARY.md

$ vim book.json
{
    "author": "zongxun <[e-mail]>",
    "description": "This is a sample book created by gitbook",
    "extension": null,
    "generator": "site",
    "links": {
        "sharing": {
            "all": null,
            "facebook": null,
            "google": null,
            "twitter": null,
            "weibo": null
        },
        "sidebar": {
            "Blog": "https://blog.csdn.net/xixihahalelehehe?spm=1000.2115.3001.5343"
        }
    },
    "output": null,
    "pdf": {
        "fontSize": 12,
        "footerTemplate": null,
        "headerTemplate": null,
        "margin": {
            "bottom": 36,
            "left": 62,
            "right": 62,
            "top": 36
        },
        "pageNumbers": false,
        "paperSize": "a4"
    },
    "plugins": [],
    "title": "GitBook Handbook",
    "variables": {}
}

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.5s ! 

Starting server ...
Serving book on http://localhost:4000

效果，只看到了一个Blog链接。

7.2 添加一个插件

编写book.json添加新theme-comscore主题插件

$ cat book.json
{
    "author": "zongxun <[e-mail]>",
    "description": "This is a sample book created by gitbook",
    "extension": null,
    "generator": "site",
    "links": {
        "sharing": {
            "all": null,
            "facebook": null,
            "google": null,
            "twitter": null,
            "weibo": null
        },
        "sidebar": {
            "Blog": "https://blog.csdn.net/xixihahalelehehe?spm=1000.2115.3001.5343"
        }
    },
    "output": null,
    "pdf": {
        "fontSize": 12,
        "footerTemplate": null,
        "headerTemplate": null,
        "margin": {
            "bottom": 36,
            "left": 62,
            "right": 62,
            "top": 36
        },
        "pageNumbers": false,
        "paperSize": "a4"
    },
    "plugins": [
     "theme-comscore" 
    ],
    "title": "GitBook Handbook",
    "variables": {}
}

安装插件

gitbook install
info: installing 1 plugins using npm@3.9.2 
info:  
info: installing plugin "theme-comscore" 
info: install plugin "theme-comscore" (*) from NPM with version 0.0.3 
/root/github/gitbook-demo
└── gitbook-plugin-theme-comscore@0.0.3 

info: >> plugin "theme-comscore" installed with success 
 

执行

$  gitbook serve

添加主题插件前： 添加主题插件后：