如何在新版的gitbook上写自己的书

前言

之前为了学习QT当中的qmake，就去看QT的官方文档，但QT的官方文档都是英文的，而自己本身英文较差，就一咬牙决定不如就把qmake的使用文档翻译一下吧。这样即可以加深对文档的理解，也可以留着自己以后查阅，顺便也可以将自己的文档放在网上给想要的人进行查阅。于是就开始查找相关的工具，几经辗转找到了gitbook这个网站。然后了解其使用方法，但不巧的是网站正处于改版时间，网上找到的教程基本全是针对旧版的，而新版的网站许多功能上还没有完善，这个折磨了我好久。

gitbook上提供了多种编辑文档的方式，可以在线编辑也可以离线编辑后再上传。新版的网站和旧版的网站已经有了好多的改变。具体的改变可以参阅gitbook的网站文档。其中的一种编辑文档的方式就是将文档像代码一样推送到GitHub,然后将文档同步到gitbook。虽然之前我没有用过git也没有用过github，我还是挺着迷这种编写文档的方式的，so。。。。因为新网站的功能还不算完善，于是各种折腾开始了。。。。之间我也联系了网站的管理员，他们也以邮件的方式回复了我，表达了它们对网站功能不完善的歉意。这里也表示感谢。。。。于是折腾了几天还是先将对gitbook网站的折腾先暂时搁置了。。。。

继续查阅我还要哪些工具，于是我还要学习Markdown，git以及github的使用。于是学起来。。。。而关于文本编辑器的使用又陷入了纠结。。。再VScode和sublime之间徘徊，最后还是发现vscode更适合我一些（这里并不是说sublime不好）。VScode中可以很方便的预览文档，以及纠正语法错误。

教程

首先我们需要再在github上创建一个仓储，并在电脑的本地安装git并将github上的仓储同步到本地。新建github仓储以及git的受用的方法可以参阅廖雪峰的git教程。更详细的也可以阅读git的官方教程。vscode和Markdown的使用自己百度就好啦。。。

做完上面的这些你就可以在本地使用vscode编写自己的文档，并将文档同步到github。下面介绍如何将文档同步到gitbook上，并生成一本书。下面就开始吧。。。

对了这里还要提一下，gitbook可以添加一个.gitbook.ymal的文件文件的使用方法可以查阅gitbook的网站文档。

这里我们先创建一个gitbook账号，这里推荐直接使用自己的github账号登陆gitbook。我们按照gitbook的网站文档中的步骤创建一个organization，然后再在organization下创建一个space。

然后按照网站文档建立和GitHub上的仓储进行关联。

按照提示关联自己所需要的仓储就好。

写在最后

gitbook官方文档对.gitbook.yaml文档的模板如下所示。该文件需要放在你GitHub仓储的根目录下，然后通过该文档的设置，使用相对路径指定gitbook下的根目录。这里给出我翻译的书qmake-learn其仓储位置是github qmake-learn

# Root directory to locate the content
# Default is the root directory of the repository.
root: ./

# Files to use as SUMMARY/README.
# (Relative to <root> directory)
structure:
  readme: README.md
  summary: SUMMARY.md

# Redirect urls to specific files (relative to the <root> directory)
redirects:
  previous/page: new-folder/page.md

这里给出我翻译的书qmake-learn其仓储位置是github qmake-learn。其实gitbook中也提供了一些其他的服务和设置。比如将你所写的书的网址绑定到自己的域名当中。自定义书的logo，更改书的网址。具体的使用方法可以看一下网站文档，以及自己摸索一下。

这里还要说一下，由于gitbook是国外的网站要像流畅的在上面写书，还是要。。。。。不过浏览文档没什么问题。