对文档的编辑过多_如何写出高质量文档（Gitbook篇）

当我们会写文章了之后，我们有想把他们整合在一起，并且可以快速索引到我们想要的地方，先来看一个效果吧，左边是文章结构的链接，右边显示具体的内容，看看你是不是也想制作这样的“书本”呢？

gitbook的显示效果

Gitbook的简单介绍

如果你看到Gitbook，你突然想到了git，这很自然，但他跟 git 其实并没有什么关联，甚至它跟程序员或者编程也没有什么必然的联系，不过如果你把它和 git 一起使用，可以更加方便部署你的文章，它只是一个用于生产文章或者图书(book)的工具罢了。

(如果你对 git或更多相关知识感兴趣，可以关注我，每周我会对编程领域里的技术进行分享)

下面正经给出gitbook的定义，这是一段来自百度百科的简介

GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书，GitBook 并非关于 Git 的教程。

Gitbook都能干啥

• 首先看到了book就知道，他是可以制作精美电子书的，可以输出多种格式，包括：PDF，这个格式大家很常用；ePub，这是一个基于开放的电子书标准，大部分的读书设备都支持；Mobi，这是一个基于XHTML的电子书标准，Kindle支持该格式；
• 当然，你可能并不是很像做一本书，而是把知识点整理起来，现在这个网络时代，把整理的知识放到网站上，随时随地可以通过网页进行阅读，才是最好的方式，那么gitbook会非常适合。你可以通过它生成一系列的HTML文档，部署到你的网站上；如果你没有自己的网站，你还可以在gitbook网站上注册一个账号，并把你的内容发布到该网站；

Gitbook有啥优势

• 那么，为什么非要选择gitbook呢？当然你可以选择别的方式来组织你的文章，只不过使用gitbook来处理的话，有以下的好处：

1. 语法简单，你只需要花一点点时间学习就可以掌握所有的知识；
2. 兼容性强，可以在多平台操作，生成出多种格式的内容；
3. 导出方便，生存的过程非常简单；
4. 专注内容，不用过多考虑排版，使用Markdown可以轻松编写；
5. 团队协作，组织好结构后，可以由不同的人编写不同的板块，通过git就可以随时同步；

• 当然，gitbook也不是万能的，如果你需要非常精巧的排版，或者你需要印刷你的文章或书籍，还是推荐使用Office相关的软件来处理，gitbook更适合像网页那样展示的效果。

Gitbook在哪使用

目前Gitbook官方网站上，已经有了50万+的用户，15万+的用户空间，以及每个月超过2千万的访问量，这还仅仅是官方的使用情况，不少企业都在内部或对外发布了使用gitbook编写的类似“用户指南”之类的文档。

• 通过gitbook搭建官方说明文档，或内部学习文档，比如cocos官方说明文档

Cocos官方说明文档

• 通过整理这些书籍，整合成一个书籍分享的网站，比如国内比较流行的看云

看云官方网站

Gitbook的安装环境

• gitbook的安装是基于nodejs的，如果你本地没有nodejs环境，需要先安装配置一下，具体的操作流程，可以参考《常用环境配置大合集之NodeJs篇》一文，这里仅将具体的步骤图贴出来，以供快速参考。

nodejs环境配置

• 接下来，就是要正经安装gitbook了，使用刚刚安装的 node 环境，输入以下 npm 指令(注：npm是伴随node一起安装的，用于处理node所需要的模块)

$ npm install gitbook-cli -g

• 注意，这里一定要使用 -g 参数，表示全局使用，安装完之后可以验证一下是否安装成功。

$ gitbook -VCLI version: 2.3.2GitBook version: 3.2.3

• 看到这样的版本信息，就表示已经安装完成了。

Gitbook的使用指南

接下来，如果你还要继续使用命令来操作的话，我们来简化一下，记住以下几个操作就可以了：

• 初始化一本书

$ gitbook init

创建一个文件夹，并在该路径下使用以上命令，初始化之后，会自动生成 README.md 和 SUMMARY.md 文件，这两个文件是非常重要的、且必须的文件，后面我们讲如何使用他们。

• 构建目标文件

$ gitbook build

当你使用md文件书写好你的内容，此时还不能看到最终的效果，需要将这些文件转换成html，使用以上命令会在路径下生成一个 _book 文件夹，里面存放了自动生成的目标html文件。

• 启动服务预览

$ gitbook serve

此时输入以上命令即可启动本地服务器，打开浏览器，并输入：http://localhost:4000 即可查看效果了。

默认的gitbook网站视图

编写文章

就像上个章节所说的那样，将md文件转为html的话，就需要我们去书写 Markdown 文件，关于如何使用与书写 Markdown，其实也是非常简单的，可以参考《如何快速写出高质量文档(Markdown篇)》，这里依然为大家贴上简单的示意图。

使用标记的方式书写文章

组织文章结构

接下来我们先来了解一下组织的结构，上面提到两个重要的文件:

• README.md是用来做自述和介绍的，就是图中我们看到的Introduction，当然你可以在该文档里书写你自己想要的内容，同时2.0起，可以通过在根路径下的 book.json 文件中修改为别的文件：

{      "structure" : {                "readme" : "myIntro.md"      }}

• SUMMARY.md是用来定义书本的章节和子章节的结构的，当你的文章分为了多个篇幅的时候，就像是doc文件里的 4，4.1，4.1.1 等类似的层级结构，可以在该文件中组织起来。

# 概要* [卷 I](part1/README.md)    * [写作很棒](part1/writing.md)    * [GitBook很酷](part1/gitbook.md)* [卷 II](part2/README.md)    * [期待反馈](part2/feedback_please.md)    * [更好的写作工具](part2/better_tools.md)

书本的配置信息

上面我们提到了 book.json 文件，我们除了可以修改介绍文件的位置，还可以做一些其他的操作，我们来简单了解一下：

• title：书本的标题
• author：书本的作者
• description：书本的简介
• language：书本的语言，中文为“zh-hans”
• gitbook：指定使用的gitbook的版本
• style：自定义页面样式
• structure：指定Readme，Summary，Glossary，Languages对应文件名
• links：在左侧导航栏添加链接信息
• plugins：配置使用的插件
• pluginsConfig：配置插件的属性

导出文档还是发布书籍

首先来个总结，我们已经配置了环境，创建了书本，然后构建了目录，并完成了内容的创作，通过调整配置完善了书本的信息，这期间可以通过 gitbook build 来不断构建生成目标 html 文件，然后在你的浏览器里看到效果。

在确认效果没有问题了以后，你可能有2个选择，要么导出指定格式的文档，要么上传到网站上分享给别人，那么怎么操作呢？

• 首先是生成文档：

$ gitbook pdf ./ ./bookname.pdf$ gitbook epub ./ ./bookname.pdf$ gitbook mobi ./ ./bookname.pdf

通过以上3种命令，可以分别生成pdf、epub、mobi不同格式的文档。是不是很简单呢？

• 或者，你希望上传发布他们：这时候就需要使用 gitbook 网站的托管功能了。当然，官方还提供了专门的编辑工具 Gitbook Editor(下载地址：https://www.gitbook.com/editor)，对于如何将文件放到gitbook.com上，可以通过github账户非常方便。

Gitbook Eidtor编辑器界面

• 如果你想要部署到自己的服务器，那么就让你的 gitbook serve 一直后台运行吧。

欢迎大家关注我，以后每周为大家分享各种程序员视角小知识。同时已准备了一系列的专题进行整理，如有发现问题，也希望大家能及时纠正~