在写文档的过程中，萌生了写书的想发，查阅了一些资料，最终选择了使用Gitbook+Gitlab的方式，做一份笔记记录。

Gitbook

Git是版本控制工具，程序和文章都是迭代下的产物，作为程序员是极其幸运的，因为他可以成为很多角色。
在线的编辑，可以参考Gitbook官网，本文适合为本地编辑。

环境配置

安装Git和Node.js

请参考搭建Gitlib hexo博客中Git和Node.js安装。

安装Gitbook

cmd
1
2
npm install gitbook-cli -g #安装gitbook
gitbook -V #查看安装后的版本

Gitbook命令说明

cmd
1
2
3
4
5
6
7
8
9
10
11
12
13
gitbook init //初始化目录文件
gitbook help //列出gitbook所有的命令
gitbook --help //输出gitbook-cli的帮助信息
gitbook build //生成静态网页
gitbook serve //生成静态网页并运行服务器
gitbook build --gitbook=3.2.3 //生成时指定gitbook的版本, 本地没有会先下载
gitbook ls //列出本地所有的gitbook版本
gitbook ls-remote //列出远程可用的gitbook版本
gitbook fetch 标签/版本号 //安装对应的gitbook版本
gitbook update //更新到gitbook的最新版本
gitbook uninstall 3.2.3 //卸载对应的gitbook版本
gitbook build --log=debug //指定log的级别
gitbook builid --debug //输出错误信息

Gitlab文件

该Gitbook是部署在Gitlab上的，因此不需要上传编译好的静态页面，Gitbook官方给了对应的Gitbook配置文件，将所有文件克隆到本地。

Gitlab创建仓库

参考搭建Gitlib hexo博客中的步骤，选择自动添加README.md，克隆该项目到本地。

Gitbook使用

Gitbook初始化

参照一下命令流程：

cmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
cd gitlab克隆文件夹
gitbook init   //初始化gitbook文件
touch book.json   //创建gitbook配置文件
// 生成两个文件README.md和SUMMARY.md文件
SUMMARY.md中文件的格式（语法跟Markdown的List相同）
# Summary

## 题目
* [第一章](README.md)
    * [第一章 第一节](chapters/1/1.1md)

## 正文
* [第二章](chapters/2/2.md)
README.md中的文件就是简介

配置文件book.json

以下是我的模板：

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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
{
    "title": "sea dauter",
    "description": "boy",
    "author": "sea",
    "output.name": "site",
    "language": "zh-hans",
    "gitbook": "3.x.x",
    "root": ".",
    "links": {
        "sidebar": {
            "作者Blog": "http://www.matace.com"
        }
    },
    "plugins": [
        "-sharing",
        "sharing-plus",
        "-lunr",
        "-highlight",
        "-livereload",
        "-search",
        "-search-plus",
        "search-pro",
        "insert-logo",
        "highlight-code",
        "alerts",
        "terminal",
        "code",
        "expandable-chapters",
        "edit-link",
        "splitter",
        "github",
        "page-footer-ex",
        "hide-element",
        "pageview-count"
    ],
    "pluginsConfig": {
        "theme-default": {
            "showLevel": true
        },
        "insert-logo": {
            "url": "src/img/logo.png",
            "style": "background: none; max-height: 30px; min-height: 30px"
          },
        "terminal": {
            "copyButtons": false,
            "fade": true,
            "style": "flat"
        },
        "hide-element": {
            "elements": [".gitbook-link"]
        },
        "code": {
            "copyButtons": true
        },
        "fontSettings": {
            "theme": "white",
            "family": "msyh",
            "size": 2
        },
        "edit-link": {
            "base": "https://gitlab.com/MATACE/wbook",
            "label": "编辑此页"
        },
        "github": {
            "url": "https://github.com/MATACE"
          },
        "sharing": {
            "douban": false,
            "facebook": false,
            "google": false,
            "hatenaBookmark": false,
            "instapaper": false,
            "line": false,
            "linkedin": false,
            "messenger": false,
            "pocket": false,
            "qq": true,
            "qzone": true,
            "stumbleupon": false,
            "twitter": false,
            "viber": false,
            "vk": false,
            "weibo": true,
            "whatsapp": false,
            "all": [
                "facebook",
                "google",
                "twitter",
                "weibo",
                "qq",
                "linkedin",
                "qzone",
                "douban"
            ]
        }
    },
    "page-footer-ex": {
        "copyright": "By [蓝&羽](http://www.matace.com)，使用[知识共享 署名-相同方式共享 4.0协议](https://creativecommons.org/licenses/by-sa/4.0/)发布",
        "markdown": true,
        "update_label": "此页面修订于：",
        "update_format": "YYYY-MM-DD HH:mm:ss"
    }
}

book.json中参数说明

  • title 书本的标题
book.json
1
2
3
{
"title": "sea dauter"
}
  • description 书本简单描述
book.json
1
2
3
{
"description": "boy"
}
  • author 作者信息
book.json
1
2
3
{
"author": "sea"
}
  • language 文章显示的语言
book.json
1
2
3
{
"language": "zh-hans"
}
  • gitbook 使用的gitbook版本
book.json
1
2
3
{
"gitbook": "3.x.x"
}
  • root的路径
book.json
1
2
3
{
"root": "."
}
  • links的网站
book.json
1
2
3
4
5
6
7
{
"links": {
        "sidebar": {
            "Home": "http://www.matace.com"
        }
    }
}
  • plugins安装插件和pluginsConfig插件的设置
book.json
1
2
3
4
5
6
7
8
9
10
{
 "plugins": [
    "github"
 ],
 "pluginsConfig": {
        "github": {
            "url": "https://github.com/MATACE"
          }
 }
}
  • 输出PDF常见配置
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
{
  "gitbook": "3.2.3",
  "title": "测试",
  "description": "测试",
  "language": "zh-hans",
  "structure": {
    "readme": "preface.md"
  },
  "pluginsConfig": {
    "fontSettings": {
      "theme": "white",
      "family": "msyh",
      "size": 2
    },
    "plugins": [
      "yahei",
      "katex",
      "-search"
    ]
  },
  "fontState": {
    "size": "2",
    "family": "sans",
    "theme": "night"
  },
  "pdf": {
    "pageNumbers": true, 
    "fontFamily": "Arial",
    "fontSize": 12,
    "paperSize": "a4",
    "margin": {
      "right": 62,
      "left": 62,
      "top": 56,
      "bottom": 56
    }
  }
}
参数 参数说明
pdf.pageNumbers 添加页码
pdf.fontSize 字体大小
pdf.fontFamily 字体
pdf.paperSize 默认A4
top 顶部白色宽度
bottom 底部白色宽度
right 右侧白色宽度
left 左侧白色宽度
  • PDF生成和三方库软件安装
    第三方软件库网址，安装完成后需要将安装路径假如电脑的全局变量。
    生成PDF步骤：
cmd
1
2
3
npm install gitbook-pdf -g // 输出为PDF文件，需要先安装gitbook pdf
cd 工程文件顶目录
gitbook pdf .
  • hide-element 隐藏元素
book.json
1
2
3
4
5
6
7
8
9
10
{
    "plugins": [
        "hide-element"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        }
    }
}
  • back-to-top-button 回到顶部
book.json
1
2
3
4
5
{
    "plugins": [
         "back-to-top-button"
    ]
}
  • 使用其他文件替代README.md
book.json
1
2
3
4
5
{
   "structure" : {
        "readme" : "myIntro.md"
    }
}
  • 封面使用
book.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "plugins": ["autocover"],
    "pluginsConfig": {
        "autocover": {
            "font": {
                "size": null,
                "family": "Impact",
                "color": "#FFF"
            },
            "size": {
                "w": 1800,
                "h": 2360
            },
            "background": {
                "color": "#09F"
            }
        }
    }
}

封面由 cover.jpg 文件指定，cover_small.jpg 同样可以作为小版本封面存在。封面应该是 JPEG 格式的文件。

描述 大 小
文件 cover.jpg cover_small.jpg
大小（像素） 1800x2360 200x262
  • 多语言设置
    每个语言应该作为一个子目录，命名为 LANGS.md。
cmd
1
2
3
* [英语](en/)
* [法语](fr/)
* [西班牙语](es/)

可以参考Gitbook示例，更多内容参考Gitbook文档。

  • 自定义术语
cmd
1
2
3
4
5
6
根目录下创建GLOSSORY.md文件
# 术语
这个术语的定义

# 另外一个术语
它的定义可以包含粗体和其他所有类型的内嵌式标记...
  • insert-logo 插入logo
cmd
1
2
3
4
5
6
7
8
9
{
    "plugins": [ "insert-logo" ]
    "pluginsConfig": {
      "insert-logo": {
        "url": "images/logo.png",
        "style": "background: none; max-height: 30px; min-height: 30px"
      }
    }
}

推送到Gitlab上和绑定域名

推送前删除_book文件夹和使用gitbook install安装插件。
参考搭建Gitlib hexo博客中的步骤。