使用GitBook编写项目文档

我之前写了一篇如何在readthedoc上面发布文档的文章,现在又多了一个选择,就是使用GitBook来编写文档。 主要是觉得对于一个托管到GitHub上面的项目来讲,可以顺带的编写使用教程和文档,可以托管到github.io上面, 非常的方便有用。因为很多软件别人觉得好不好用,文档太重要了。

安装

官方文档地址:https://toolchain.gitbook.com/

安装依赖软件

安装Nodejs

首先安装Nodejs环境,参考我的博客《Nodejs的安装和配置》即可。

安装gitbook-cli

1
2
3
4
$ cnpm install gitbook-cli -g
$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

出现上面类似的版本信息就说明安装成功了。

基本使用

gitbook 的基本用法非常简单,基本上就只有几个命令:

  1. 使用 gitbook init 初始化书籍目录
  2. 使用 gitbook build 编译书籍
  3. 使用 gitbook serve 编译并预览书籍

首先,创建如下目录结构:

1
2
3
4
5
6
$ tree book/
book/
├── README.md
└── SUMMARY.md

0 directories, 2 files

EADME.md 和 SUMMARY.md 是两个必须文件,README.md 是对书籍的简单介绍:

1
2
3
4
$ cat book/README.md 
# README

This is a book powered by [GitBook](https://github.com/GitbookIO/gitbook).

SUMMARY.md 是书籍的目录结构。内容如下:

1
2
3
4
5
6
7
$ cat book/SUMMARY.md 
# SUMMARY

* [Chapter1](chapter1/README.md)
* [Section1.1](chapter1/section1.1.md)
* [Section1.2](chapter1/section1.2.md)
* [Chapter2](chapter2/README.md)

创建了这两个文件后,使用 gitbook init,它会为我们创建 SUMMARY.md 中的目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
$ cd book
$ gitbook init
$ tree
.
├── README.md
├── SUMMARY.md
├── chapter1
│ ├── README.md
│ ├── section1.1.md
│ └── section1.2.md
└── chapter2
└── README.md

2 directories, 6 files

书籍目录结构创建完成以后,就可以使用 gitbook serve 来编译和预览书籍了:

1
2
3
4
5
6
7
8
9
10
11
12
[root@VM_170_150_centos book]# gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
...
info: found 5 pages
info: found 0 asset files
info: >> generation finished with success in 1.0s !

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

gitbook serve 命令实际上会首先调用 gitbook build 编译书籍, 完成以后会打开一个 web 服务器,监听在本地的 4000 端口。

现在,gitbook 为我们创建了书籍目录结构后,就可以向其中添加真正的内容了,文件的编写使用 markdown 语法, 在文件修改过程中,每一次保存文件,gitbook serve 都会自动重新编译,所以可以持续通过浏览器来查看最新的书籍效果!

另外,你还可以下载 gitbook 编辑器,做到所见即所得的编辑。

个性化配置

除了修改书籍的主题外,还可以通过配置 book.json 文件来修改 gitbook 在编译书籍时的行为。

gitbook在编译书籍的时候会读取书籍源码顶层目录中的book.json,参考gitbook文档,一个典型的配置:

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
{
"author": "熊能 <yidao620@gmail.com>",
"description": "scrapy简明指南",
"generator": "site",
"language": "zh-hans",
"links": {
"sidebar": {
"我的博客": "https://www.xncoding.com"
}
},
"pdf": {
"fontSize": 12,
"footerTemplate": null,
"headerTemplate": null,
"margin": {
"bottom": 36,
"left": 62,
"right": 62,
"top": 36
},
"pageNumbers": false,
"paperSize": "a4"
},
"plugins": [ "theme-gestalt", "-theme-default", "styles-sass-fix", "multipart", "toggle-chapters" ],
"pluginsConfig": {
"theme-gestalt": {
"logo": "/core-scrapy/assets/logo.png",
"favicon": "/core-scrapy/assets/favicon.png",
"excludeDefaultStyles": true
},
"disqus": {
"shortName": "yidao620cgithubio"
}
},
"styles": {
"website": "./styles/website.scss"
},
"title": "Scrapy Cookbook2",
"variables": {}
}

上面我添加了作者信息,简明介绍,还增加了一个博客链接。另外最重要的是后面的插件配置,关于插件我会在下面讲解。

详细的配置信息参考官方文档:https://toolchain.gitbook.com/config.html

推荐插件

gitbook还支持许多插件,用户可以从 NPM 上搜索 gitbook 的插件,gitbook推荐插件的命名方式为:

  • gitbook-plugin-X: 插件
  • gitbook-plugin-theme-X: 主题

接下来我推荐几个比较好用的插件

1
2
3
4
5
6
7
8
9
cnpm i -g gitbook-plugin-disqus
cnpm i -g gitbook-plugin-multipart
cnpm i -g gitbook-plugin-toggle-chapters
cnpm i -g gitbook-plugin-styles-sass-fix
cnpm i -g gitbook-plugin-multipart
cnpm i -g gitbook-plugin-toggle-chapters
cnpm i -g gitbook-plugin-theme-gestalt
cnpm i -g gitbook-plugin-theme-styles-sass-fix
cnpm i -g gitbook-plugin-styles-sass-fix

theme-gestalt

这是一个主题插件,可替换掉默认主题,我使用的就是这个。还能自己定义css样式

multipart

这个是能将一本书分成街部分,每一部分单独编号,互不影响。 对有非常多章节的书籍非常有用,分成两部分后,各个部分的章节都从 1 开始编号。

toggle-chapters

toggle-chapters 插件的效果是:默认只在目录导航中显示章的标题,而不会显示小节的标题, 点击每一章或者每一节会显示当前章或节的子目录,如果有的话,但是同时会收起其它之前展开的章节。

disqus

Disqus 是一个非常流行的为网站集成评论系统的工具,同样,gitbook 也可以集成 disqus 以便可以和读者交流。

首先,需要在 disqus 上注册一个账号,然后添加一个 website,这会获得一个关键字,然后在集成时配置这个关键字即可。

配置如下:

1
2
3
4
5
6
7
8
{
"plugins": ["disqus"],
"pluginsConfig": {
"disqus": {
"shortName": "yidao620cgithubio"
}
}
}

注意:上面的 shortName 的值就是你在 disqus 上创建的 website 获得的唯一关键字。

暂时我自己用的就这些插件,如果您有更多的建议,欢迎告诉我。

集成GitHub

我对GitBook最感兴趣的地方还是它能非常轻松的跟GitHub集成,对每个项目生成各自的文档或书籍, 并且可以发布至github.io上面,提供版本控制,这个对于写软件的文档来讲实在是太方便了,不得不爱它。

下面我以自己的一个实际项目来说明如果进行集成。

项目地址:https://github.com/yidao620c/core-scrapy

如果读者不了解 GitHub Pages 为何物,简单说就是一个可以托管静态网站的 Git 项目, 支持使用 markdown 语法以及 Jekyll 来构建,或者直接使用已经生成好的静态站点。 详细可以参考 GitHub Pages 主页

由于 gitbook 书籍可以通过 gitbook 本地构建出 site 格式,所以可以直接将构建好的书籍直接放到 GitHub Pages 中托管, 之后,可以通过如下地址访问书籍:

1
http://<username>.github.io/<project>

比如,我演示的这个项目的github page可以通过地址:https://yidao620c.github.io/core-scrapy/ 访问到。

准备工作

你得有个<username>.github.io的github项目才行,没有的话去建一个。

doc目录

在项目根目录下面新建doc目录,然后将所有书籍源码放入到这个目录中。

gh-pages分支

对于你需要进行文档或书籍托管的项目,需要创建名字为gh-pages的分支。也就是说至少有两个分支:

  • master - 保存你原来的代码,另外加一个doc/目录保存书籍的源码
  • gh-pages - 保存书籍编译后的HTML文件

publish脚本

为了每次自动发布gitbook书籍到github.io上去,我自己写了个脚本:

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
#!/bin/bash

cd doc

# gitbook install
# install the plugins and build the static site
gitbook build

cd ..

# checkout to the gh-pages branch
git checkout gh-pages

# pull the latest updates
git pull origin gh-pages


if [[ "$?" != "0" ]]; then
exit 1
fi
# copy the static site files into the current directory.
\cp -Rf doc/_book/* .

# remove 'node_modules' and '_book' directory
# git clean -fx gitbook/node_modules
# git clean -fx gitbook/_book
rm -rf doc/_book/

# remove website css files, except last one
ccount=`ls website-* | wc -w`
if [[ "$ccount" > 1 ]];then
allcss=($(ls website-*))
c=0
for css in "${allcss[@]}"; do
let "c=c+1"
if [[ $c -ge $ccount ]]; then
break;
fi
rm -f $css
done
fi

# add all files
git add --all

# commit
git commit -a -m "Update docs"

# push to the origin
git push origin gh-pages

# checkout to the master branch
git checkout master

初次执行脚本时候注意:

将项目clone下来之后,默认只有maser分支,先手动增加gh-pages分支, 使用npm下载好所有的gitbook插件,并执行gitbook install命令。

这些做好之后再执行publish脚本,以后每次都不用管之前的步骤了。

URL路径问题

一开始发布之后发现logo图片、fontawesome路径都出现404错误,原因是对于每个项目而言多了个项目名称的路径, 这样就会找不到正确的URL。

解决办法:

1. 在我的yidao620c.github.io项目master分支上面添加fontscss文件夹,将相应的字体和css文件下载放入里面。

下载地址:https://cdnjs.com/libraries/font-awesome

fonts目录放入的字体:

  • FontAwesome.otf
  • fontawesome-webfont.eot
  • fontawesome-webfont.svg
  • fontawesome-webfont.ttf
  • fontawesome-webfont.woff
  • fontawesome-webfont.woff2

css目录放入的样式文件:

1
2
3
font-awesome.css
font-awesome.css.map
font-awesome.min.css

2. 同时在配置文件里面,在url路径前面加入项目名前缀,比如上面的配置中:

1
2
3
4
5
6
7
8
9
{
"pluginsConfig": {
"theme-gestalt": {
"logo": "/core-scrapy/assets/logo.png",
"favicon": "/core-scrapy/assets/favicon.png",
"excludeDefaultStyles": true
}
}
}

可直接使用我的这个演示项目来构建您的gitbook文档或书籍。

生成PDF

GitBook也能生成PDF电子书,这个我暂时没有用这个功能,大家有兴趣可以去自己研究下。

生成电子书的文档地址:https://toolchain.gitbook.com/ebook.html

最后放一张截图: