通过Gitbook可以很方便在线阅读文档，内容是Markdown格式的，结合Github可以将自己的书籍进行托管，只需将Gitbook中的Book(笔记)与GitHub中的Repository绑定起来，这样便可以在任意地方通过Git拉取仓库，修改内容，提交内容，GitBook会自动从GitHub中同步Book(笔记)。当然也可以将生成的书籍托管自己网站目录下，通过个人站点查阅电子书。

1.gitbook生成本地书籍

1.1 安装gitbook

gitbook依赖nodejs，安装完成之后安装gitbook.

1
2
3
$ node --version
$ npm -v
$ npm install gitbook-cli -g

1.2 初始化book

1
2
$ gitbook init #会在当前目录生成两个文件， README.md和SUMMARY.md
$ gitbook serve #编译和预览书籍，实际上会首先调用 gitbook build 编译书籍,然后打开web服务器

gitbook init会在当前目录生成两个文件。

  • README.md: 简介文档。
  • SUMMARY.md: 定义了book的目录结构，非常重要。

gitbook serve命令会调用gitbook build在本地生成一个_book目录，这个目录就是一个静态站点，打开里面的index.html就可以访问本地book了。

1.3 在个人站点调用Book

如果有个人站点，需要连接一个gitbook书籍，非常简单，只需要把上面通过gitbook build生成的_book目录放入相应位置即可，以Hexo为例。

我们知道发布Hexo博客有如下几个步骤。

  • hexo clean: 清除cache文件。
  • hexo g: 生成public文件，即Hexo站点静态文件。
  • hexo d: 发布public站点到github或者其他托管站点。

我们只需要在hexo g命令执行完之后拷贝Gitbook的_book内容到Hexo的public目录，然后再执行Hexo d发布站点即可，访问Hexo站点的时候访问书籍的话通过网址：xxx.github.io/_book,浏览器就会自动调用该目录下的index.html文件。也可以尝试将下述命令做成可执行脚本直接运行。

1
$ hexo clean && hexo g && cp -fr ../[path]/_book/ public/ && hexo d

2. 发布Book到GitBook.com

2.1. 在Github中创建一个新的仓库

如果没有Github账号则新创建一个，然后创建一个新的仓库如，ebook

2.2. 在GitBook中注册一个新的账号

新版本Gitbook注册后需要创建一个organization，为便于记忆，填写为个人名字即可。依照提示继续填入project,在project里面可以创建多个space，每个space便是一本书。

2.3. 绑定Gitbook与GitHub仓库

  • 首先需要将Gitbook账号与GitHub账号进行绑定

gitbook

  • 关联账号后可以将书籍与仓库进行绑定关联

    进入Space后点击设置按钮进行关联前面创建的仓库ebook

gitbook

2.4. 通过Git更新书籍

2.4.1 获取到git地址拷贝到本地

1
git clone git@github.com:wowmarcomei/ebook.git

2.4.2 添加readme.md与summary.md内容

1
2
3
4
5
6
gitbook init #生成README.md与SUMMARY.md
vi README.md #编辑README.md
vi SUAMMRY.md #这一步尤其重要，因为需要通过这个文件指定书籍的文档结构
git add *
git commit -m "Initial Commit"
git push origin master

即可将写好的readme内容推送到Github，Gitbook也会同步从Github中获取到数据。

2.4.3 编辑内容并推送到托管仓库

  • 创建新章节：创建一个目录。
  • 章节中的小章节：对应一个Markdown文件。
  • 如果需要对章节进行多层嵌套，则嵌套创建目录即可。
  • 编辑SUMMARY.md文件指定结构。

示例，新增一个章节，在里面指定对应小节：

1
2
3
4
5
6
mkdir 1.爬虫准备
vi 1.常见的三种数据库的安装配置.md
vi 2.Python常用库的安装.md
vi 3.使用Python的正则表达式过滤字符串.md
vi 4.理解Python中使用yield进行迭代.md
###编辑完内容后编辑SUMMARY.md文件指定目录结构

上述是使用vi命令编辑Markdown文件，实际上更推荐使用一些可视化的工作编辑，比如typora等等。

SUMMARY.md格式如下：

1
2
3
4
5
6
7
8
9
10
# Summary

* [Introduction](README.md)
* [1.准备工作](1.准备工作/README.md)
	* [1.常见的三种数据库的安装配置](1.准备工作/1.常见的三种数据库的安装配置.md)
	* [2.Python常用库的安装](1.准备工作/2.Python常用库的安装.md)
	* [3.使用Python的正则表达式过滤字符串](1.准备工作/3.使用Python的正则表达式过滤字符串.md)
	* [4.理解Python中使用yield进行迭代](1.准备工作/4.理解Python中使用yield进行迭代.md)
		* [1.爬虫基本流程](2.理解爬虫/1.爬虫基本流程.md)
		* [2.Python使用Urllib库爬取数据](2.理解爬虫/2.Python使用Urllib库爬取数据.md)

即为[]()构成的列表，如果需要嵌套层级，相比上一个层级多缩进一下即可，上面的例子中就有三个层级。

gitbook

完成后通过git推送到github,gitbook.com就会从仓库里自动同步，此时访问gitbook.com即可访问发布的数据。

1
2
3
$ git add *
$ git commit -m "update..."
$ git push origin master #推送到master分支，gitbook应该也是绑定到仓库的该分支，否则不能同github同步

gitbook

瑕疵: 新版本的Gitbook中对Markdown的有序列表支持不是很好，原本的列表项1, 2, 3, 4, ... 在gitbook中会变成1, 1, 1, 1, ...，目前没看到有解决，所以我们在记录笔记的时候换成无序列表吧，或者换成小标题也行。

文章首发公众号-梅旭红，欢迎关注，不定期更新。

全文完。