初探GitBook

写在前面

• 硕士期间在折腾某些分析的时候，就发现好些软件的操作文档都是用GitBook写的，并且挂到网上供用户检索与浏览，实在是方便而又简洁好看
• 最近CJ提到了一下GitBook，便抽空鼓捣了一下，感觉还不错，或许以后能用到， 哈哈。

---

折腾GitBook之前，可能要先了解两个东西：Git与GitHub

什么是Git？

具体来说，Git是一种分布式版本控制系统，非常强大！可以用来对项目进行版本管理，还支持多人团队协作开发项目。

• 举个栗子

各位科研中人应该都写过大大小小的论文。在写作过程中，word的审阅模式非常实用，能够查看每一处的修改记录以及某些建议等等。但是仍然不可避免的会存在多个版本的迭代，如果想找回某个版本中的某些内容，若在版本命名中没有注明的话，确实比较麻烦。

又或者，老板或者其他同学帮忙修订文章时，通常我们都会将word文档传过去，对方修改完了再传过来。。。。碰到这种场景，聪明如你当然会想到Git啊~通过Git能够自动记录每一次的版本改动，想知道某个版本做了什么改动，只需要查看记录即可。

此外，项目合作者通过Git可以克隆远程仓库（通常使用GitHub来充当远程仓库的角色）下的部分文档和代码，在完成修改或功能更新后提交回仓库，最后负责人再统一将修改记录合并。这种分支的方法能够使开发者安全的修改某一部分代码而不会影响到整体代码的其他部分。同时，因为有版本更新记录，因此能够在有必要的时候还原到任何一个版本。

什么是GitHub？

GitHub是一个为Git提供远程仓库托管服务的网站，是一堆牛逼的开源项目聚集地，比如vue、bootstrap等，还有一些非常有趣的开源项目，日常摸鱼的时候可以玩玩。GitHub提供了友好的网页界面，使得新手也能方便地使用Git来进行项目管理。只要你创建一个GitHub账号，就可以免费地享受这一切~

什么是GitBook？

GitBook是一款支持Markdown写作的文档平台，似乎初衷是面向程序员写软件手册的。由于其完美支持Markdown，并且能够像使用GitHub进行托管搭建个人blog一样，使文档直接挂到网上，因此用来写写分析记录、分享心情随笔、甚至写电子书等都是非常不错的选择。

一般对于写文档来说，GitBook的免费功能已经够用，但是付费的GitBook更强大，付费之后能够使用团队协作功能，支持多人共同开发一个文档，并且能够查看文档的每个修改记录，并选择是否接受修改。以及一些其他开发功能，例如自定义主题颜色、字体、直接将文档导出为PDF等功能。

收费详情

GitHub与GitBook的关系

其实GitHub与GitBook似乎没有直接关系，是两个独立的网站。但是GitHub与GitBook能够相互关联，实现两边的数据实时同步更新，即在GitBook中每次修改文档都会生成一个commit，自动提交到与GitHub的关联项目中，方便追溯历史版本；而在GitHub中进行修改，也能自动提交到GitBook，实现更新。因此我们完全可以在本地使用喜欢的编辑器编写文档或代码，然后利用Git推送到GitHub，再通过设置关联自动更新到GitBook，舒服！

初探GitBook

GitBook提供本地版和在线版两种使用方式，本地版（Windows或Linux）需要自己配置一下，略麻烦，首先要安装node.js，因为实际上GitBook是基于node.js的一个命令行工具，对没有编程背景的人来说不是太友好。但是GitBook提供的在线版本就非常用户友好，不用敲命令即可在线完成你的文档写作，以及同步到GitHub！

首先我们需要创建一个GitBook账号，GitBook网址为：https://www.GitBook.com

注册完成，登录后的界面长这样：

接着为项目创建一个空间，用来存放该项目的所有内容。比如写一本电子书或一个文档，那么所有的章节都应该在一个Space下。

编辑页面如图，比较好理解，基本随便点一下即可知道该怎么操作。接下来就是看个人审美了，如何将文章合理地排版，使其看起来更清爽舒服。

以之前的一篇推文为例，演示一下在GitBook中的编辑操作

当我们开始对文档进行编辑的时候，会形成一个草稿（draft），编辑完成后点击保存，会将草稿保存下来，这时候建议为草稿添加一些解释说明，特别是在多人协作的时候，方便知道每个草稿都修改了哪些内容。最后点击合并（merge）形成最终的文档。

在Design界面，还可以对电子书的界面做一些样式修改，例如修改颜色、logo、标题、搜索栏的位置等等。如果开启了付费功能，还能支持直接导出PDF。

多人协作。在Teams功能下（付费，免费体验14天），可以邀请多个成员来共同编辑一个文档。这个时候就需要充分利用好draft这个功能（类似Git，版本管理），知晓每个人都做了一些什么工作，然后再最终整合到文档中。

最后，编辑好文档之后，便可以将链接分享出去给别人看啦。
这边分享一下我测试编辑的文档：https://jiawei-li.gitbook.io/test-for-gitbook/

---

设置GitBook与GitHub关联

GitBook允许将Space与GitHub的repository关联，达到两者实时同步的效果。

首先，需要有一个GitHub的账号，GitHub主页为：https://GitHub.com/

点击注册账号

创建好账号之后，便建立一个空仓库（repository），名字可以随意取，但是最好与GitBook中的相同，方便理解。其他参数使用默认参数即可。

创建好repository的界面长这样，先放着不管

接着在需要与GitHub关联的GitBook Space中设置关联

选择刚刚我们建立的repository

同步完成，在GitHub中已经能够看到同步过来的内容。关联设置成功之后，在GitBook中修改或在GitHub中修改，都能实现两边实时同步，因此可以在本地方便地使用Git来更新我们的电子书文档啦，完美！

---

写在最后

至于本地的GitBook以及如何用Git将内容推送到GitHub，下次有机会再写写好了，现在不早啦，该下班啦

开学一段时间了，新的领域，新的开始。希望大家永远相信光，哈哈。