如何在新版的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是国外的网站要像流畅的在上面写书,还是要。。。。。不过浏览文档没什么问题。

阅读 9k
6 声望
1 粉丝
0 条评论
6 声望
1 粉丝
宣传栏