转自“实验楼”

一、实验说明

1.1 GitBook 介绍

Modern book format and toolchain using Git and Markdown

GitBook 是一个使用 GitHub/Git 和 Markdown 来制作电子书的命令行工具 (Node.js 库)。

另外，有一个网站 gitbook.com 可以帮助用户更好的使用 Gitbook。同时 gitbook.com 还提供了一个桌面编辑器，帮助用户编辑电子书。Gitbook 与 gitbook.com 的关系类似 Git 和 GitHub，一个是工具，另一个是基于工具创建的网站。

1.2 知识点

本次课程涉及如下知识点：

• Markdown 书写
• Git 使用
• Gitbook 基本操作
• Github pages

1.3 工作目录

进入实验以后，我们打开桌面上的 Xfce 终端：

$ cd Code
$ mkdir gitbook
$ cd gitbook

文件夹 gitbook 作为我们的工作目录，之后所有的操作都在这个目录下执行。

1.4 效果截图

二、实验操作

2.1 Gitbook 安装

Gitbook 的安装和准备大概需要几分钟。

目前有两种方式可以而让你使用 Gitbook 来编辑、发布和管理电子书：

• 本地编辑，然后发布到类似 GitHub pages 的第三方平台；
• 直接使用已有的 gitbook.com 网站。

2.1.1 本地安装

本地安装 Gitbook 需要 NodeJS 支持，推荐安装 NodeJS v4.0.0 及以上版本。

目前安装 Gitbook 最方便的方式就是通过 npm 安装：

sudo npm install -g gitbook-cli
sudo npm install -g gitbook

安装完之后，你可以检验下是否安装成功。

gitbook -V

2.1.2 编辑书籍

安装好 Gitbook 之后，我们就可以创建图书了。

Gitbook 的基本用法非常简单，基本上就只有两步:

1. 使用 gitbook init 初始化书籍目录
2. 使用 gitbook serve 编译书籍

首先，进入一个目录，例如之前我们创建好的 gitbook，执行初始化命令：

sudo gitbook init

然后我们的 gitbook 空目录会多出两个文件：

gitbook/
├── README.md
└── SUMMARY.md

README.md 和 SUMMARY.md 是两个必须文件，README.md 是对书籍的简单介绍。SUMMARY.md 是书籍的目录结构。

REAMDE.md:

# Introduction

SUMMARY.md:

# Summary

* [Introduction](README.md)

对上面两个文件，我们做一下编辑：

REAMDE.md:

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

SUMMARY.md:

# Summary

* [Introduction](README.md)
* [第一部分](chapter1/README.md)
    * [1.1 数学](chapter1/math/math.md)
        * [1.1 高等数学](chapter1/math/advance.md)
        * [1.2 离散数学](chapter1/math/lisan.md)
    * [1.2 编程语言](chapter1/program/program.md)
        * [1.2.1 C 语言](chapter1/program/c.md)
        * [1.2.2 C++](chapter1/program/c++.md)
        * [1.2.3 Java](chapter1/program/java.md)
    * [1.3 软件工程](chapter1/software/software.md)
    * [1.4 数据结构](chapter1/data_structure/data_structure.md)
    * [1.5 数据库原理](chapter1/database/database.md)
    * [1.6 计算机网络](chapter1/network/compute_network.md)
    * [1.7 计算机系统](chapter1/system/compute_system.md)
        * [1.7.1 操作系统](chapter1/system/operating.md)
        * [1.7.2 微机接口](chapter1/system/interface.md)
        * [1.7.3 计算机组成原理](chapter1/system/comprise.md)
        * [1.7.4 计算机系统结构](chapter1/system/system_structure.md)
* [第二部分](chapter2/README.md)
    * [2.1 算法](chapter2/algorithm/algorithm.md)
    * [2.2 数据挖掘](chapter2/data_mining/data_mining.md)
    * [2.3 机器学习](chapter2/learning/machine_learning.md)
    * [2.4 搜索引擎](chapter2/search/search_engine.md)

编辑这两个文件之后，再次执行：

gitbook init

它会为我们创建 SUMMARY.md 中的目录结构。

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

sudo gitbook serve

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

现在，可以用浏览器打开 http://localhost:4000 查看书籍的效果，如下图：

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

2.2 gitbook.com 使用

gitbook.com 是一个围绕 Gitbook 发行书籍的社区，于 2014 年初创，gitbook.com 提供免费和付费的服务，而且免费账户就可以享受诸多服务，包括：

• 1 本私有书籍;
• 托管不限数量的公开书籍;
• 售卖不限数量的书籍，并分享 80% 的书籍收入;
• 不限数量的协作者;
• 免费的在线书籍编辑器。

要使用 gitbook.com 来托管你的书籍，首先需要注册一个账号。

点此注册

登陆 gitbook.com 后，在用户页面，可以管理现有书籍以及创建新的书籍:

创建完成以后，会进入书籍管理页面：

点击 “Edit your book” 按钮，进入一个在线编辑器：

1. 中间是编辑区域，使用 Markdown 语法；
2. 左上方是章节目录，鼠标右键可以新增章，在上右键可以新增节，托放可以改变顺序；
3. 左下方是文件列表，鼠标右键可以新增目录或文件。这里面最必要的是 README.md 和 SUMMARY.md。前者是书籍的简介，后者是真正决定书籍目录结构的，比如多层次目录结构，需要手动修改 SUMMARY.md(左上方会立刻呈现效果)。
4. 右侧是预览窗口，可以点击 “眼睛图标”关闭/开启预览区域。其实可以关闭左侧区域和右测预览区域，专心写作。

2.3 发布到 GitHub

我们可以在 GitHub 上创建一个仓库，来管理书籍源码。

注意:

源代码保存到 master 分支，编译出来的静态文件 _book 上传到 gh-pages 分支，这样我们就可以通过 GitHub pages 来发布电子书了。

具体操作:

• 登录到Github，创建一个新的仓库，名称我们就命令为 book，这样我就就得到了一个 book 的空仓库;
• 克隆仓库到本地：git clone git@github.com:USER_NAME/book.git;
• 创建一个新分支：git checkout -b gh-pages，注意，分支名必须为 gh-pages;
• 将分支 push 到仓库：git push -u origin gh-pages;
• 切换到主分支: git checkout master。

经过这一步处理，我们已经创建好 gh-pages 分支了，有了这个分支，GitHub 会自动为你分配一个访问网址：http://USERNAME.github.io/book。

操作到这一步，我们所在目录是在 Code/book/ 下，现在我们需要在 Code 目录下保存我们的电子书的静态文件，切换到Code 目录，克隆远程仓库 book 的 gh-pages 分支并保存为 book_build:

git clone -b gh-pages git@github.com:USERNAME/book.git book-build

然后我们从 Code/book/_book 目录下把编译好的电子书静态文件复制到 Code/book_build 下，执行：

sudo git add .
sudo git commit -m "add e-book static file"
sudo git push

将静态文件 push 到远程仓库 book 的 gh-pages 分支。

然后，等十来分钟的样子，你就可以通过访问网址：http://USERNAME.github.io/book来访问到你的在线图书了。之后，每次修改之后，都可以将生成的静态文件 copy 到 book-build 目录，再 push 到远程仓库 book 的 gh-pages 分支。

2.4 Github 集成

我们之前在 gitbook.com 新建了一本电子书，并且把电子书的源码存放在了 GitHub 上。现在，我们可以将 gitbook.com上的这本电子书与 GitHub 的远程仓库关联起来，我们可以通过向书籍的 GitHub 仓库提交内容来更新书籍。

登陆 gitbook.com 网站，可以看到我们之前创建的电子书，然后点击 “Book Settings” 按钮。

在 “Settings” 栏目中，点击 “GitHub”。

点击 “Select a Repository”，选择我们创建的存放电子书源码的仓库。

确定仓库之后，点击 “Sync” 按钮，同步。

成功！之后，每次在 GitHub 上更新电子书时，都会自动同步到 gitbook.com，并且自动编译成电子书。

三、总结

本次试验完成了对 Gitbook 的简单掌握，学会制作简单的电子书籍，并且发布到 gitbook.com 或者 GitHub pages 上面。

参考：

https://github.com/GitbookIO/gitbook