从零开始创建gitbook

本文是博主在自己使用gitbook创建电子书,并通过github托管时躺过的坑的总结,如有表述不清楚的地方,请在评论区留言交流。本文的结构分为两大模块,分别为从零开始创建gitbook协作开发gitbook,并假设所有的读者已有一个github账号。文章可能比较基础,大佬请绕路 ^_^

由于某墙的原因,访问gitbook和github可能比较慢,请耐心等待,或者google搜索修改host翻墙,或者使用fq梯子,这里博主实力推荐 Lantern 2.2.5 版本(至于为什么是2.2.5版本……因为它free)
ps: 前方多图,请在wifi环境下阅读,土豪。。。随意。。

从零开始创建gitbook(单人)

这里解释一波gitbook和github的关系,首先Gitbook和Git/Github都没有什么关系。它只是一个build book的工具而已,我们写好的markdown格式的文件,放在github上,然后通过gitbook获取到这些内容,在gitbook网站上编译生成html,生成gitbook.io形式的在线预览图书,通过webhook绑定github和gitbook,就能做到提交内容到github仓库,gitbook上的书籍实时更新。

1. 申请gitbook账号

已有gitbook账号看官请跳过这一步。
google搜索gitbook,进入gitbook官网 ,也可以直接注册itbook账号,这里我们使用github登陆激活gitbook,毕竟它们是一家的产品,截图如下:
signup
signin

2. 设置gitbook连接github权限

gitbook需要设置权限,才能连接到github上共有仓库的内容。
点击图像处的下拉按钮,选择Account Settings,进入gitbook账号设置
access
Personal settings > Profile > GitHub 中,点击Reconnet GitHub Account按钮,选择With acceess to public repositories,上方会显示绿色的ADDED信息,表示连接成功,如图
public

3. 在github上创建仓库

我们切换到github网站,关于如何在github上创建仓库,这里不再赘述,直接上图
比如我们的仓库名为testbook,记得在最后生成仓库的时候,勾选下面的Initialize this repository with a README
githubrepo

4. 在gitbook上创建书籍

我们切换到gitbook网站,新建一本书籍,为了保持一致性,我们的书籍名也叫 testbook,当然可凭个人喜好选择书名,记得选择public书籍,如图
createbook

5. 连接gitbook与github仓库

这一步是配置gitbook与github连接,让testbook这本书的内容连接到github仓库
点击SETTING,选择Settings > Github ,点击Select a Repository,选择刚刚第三部在github上创建的仓库,如图:
configbook1
chooserepo
点击 Sync按钮,进行同步,之后会显示如下界面,表示仓库连接成功:
succacc

6. 配置webhook

在gitbook设置里,配置webhook,使github仓库内容和gitbook同步更新
点击 Settings > Hooks > New Webhook
addhook
Payload URL里填上刚刚github上新建的testbook仓库的地址,Secret可填可不填,博主选择不填
github仓库地址获取如下
gitaddress
gitbook上填写完毕截图如下:
hookdetail
hookcomplete
此时,在github的testbook仓库设置里,webhooks选项应该会多出一个,表示刚刚配置的gitbook上的webhook连接github成功
githubhook
如果没有的话,手动添加截图如下:
切换到gitbook网站,在gitbook上的testbook书籍设置里获取webhook url
gitbookhookurl
复制这个url地址,切换到github的testbook仓库设置里
githubaddhook1
githubaddhook2
如果在之前配置gitbook的webhook时有设置secret,那么在github上的secret选项也要填上

此时,关于gitbook和github的配置已结束
测试是否正常工作,在github的testbook仓库,点击修改readme.md内容,发起Commit changes,然后在gitbook上刷新testbook,点击update,即可预览testbook内容,此时,如果有配置邮件,你会收到一封邮件,通知你的gitbook创建成功了。

注:不要急着去点击下图的 read shortly,因为gitbook编译可能需要一段时间,过早点击可能造成无法发布生成图书,然后当网络比较慢的时候也可能造成图书生成不成功,这个时候不要方,再来一次,或者等待gitbook服务器修复好(因为gitbook不是特别稳定,容易出bug,博主好几次生不出图书,然后等到第二天,啥都没干,一刷新就好了,所以如果前面的步骤严格遵循,你要相信,这不是你的锅,其实你的书已经发布成功了,可以参考后面的如何本地预览图书)
testbook1
testbook2
testbook3
testbook4


7. 本地编写书籍

我们这里还是以一本空的书籍为开始,从初始化到最终发布,在gitbook上预览
编写分为两种,一种是使用gitbook官方提供的客户端,gitbook editor , 一种是使用文本编辑器+gitbook命令行+git 来编写,客户端比较简单,看官请自行摸索,我们这里介绍第二种比较极客的编写模式

1. 通过npm安装gitbook-cli

npm是nodejs包管理工具,直接下载安装nodejs,会自带npm包管理工具

1
npm install -g gitbook-cli

全局安装gitbook命令行,安装完毕后,使用

1
gitbook -V

测试是否成功安装gitbook

2. 下载github仓库内容,并手动建立 SUMMARY.md

首先下载github上testbook仓库内容,选择一个自己喜欢的目录,比如博主的本地地址 D:\github

1
2
$ cd d:\github
$ git clone https://github.com/Superlee2013/testbook.git

然后进入刚刚下载好的仓库里,新建 SUMMARY.md

1
2
$ cd /d/github/testbook
$ touch SUMMARY.md

这个SUMMARY.md就是最后的书的目录,同时gitbook会根据该文件生成相应的目录结构
local1

3. 编辑SUMMARY.md,生成目录结构

1
2
3
4
5
6
7
8
9
10
11
12
* [简介](README.md)
* [第一章](chapter1/README.md)
- [第一节](chapter1/section1.md)
- [第二节](chapter1/section2.md)
- [第三节](chapter1/section3.md)
- [第四节](chapter1/section4.md)
* [第二章](chapter2/README.md)
- [第一节](chapter2/section1.md)
- [第二节](chapter2/section2.md)
- [第三节](chapter2/section3.md)
* [第三章](chapter3/README.md)
- [第一节](chapter3/section1.md)

然后进入命令行,进入testbook这本书的本地目录下,执行如下命令

1
$ gitbook init

local2
最终本地的目录结构如下:
local3
然后,可以拿你喜欢的的文本编辑器进行gitbook的书写,博主推荐 sublime text 3 , 当然,如果要实时预览markdown,博主推荐 typora

4. gitbook本地预览

在推送到远程github之前,可以本地预览最终的gitbook效果,执行如下命令

1
$ gitbook serve

gitbookserve
然后,浏览器打开localhost:4000 即可在预览

5. 向远程仓库推送

编写好这些markdown文件后,使用git命令行向远程仓库推送

1
2
3
$ git add .
$ git commit -m"update"
$ git push origin master

此时,可以查看github仓库有没有推送成功,然后在gitbook上,打开testbook,点击Read,即可看到最终的书籍样式
bookc1

到此,从零开始创建gitbook,并通过github托管的所有过程结束,现在可以愉快的编写专属你的电子书了

协同创建gitbook(多人)

协作创建的意思是,已经有一个gitbook的书籍了,然后我们fork到github本地,通过发起pull request请求进行协同创作书籍

1. fork仓库到自己的github账号

找到需要参加协作编写的仓库地址,fork到自己的github账户仓库
c1

2. 下载到本地

复制刚刚fork到自己的仓库的url地址,clone到本地
cf1
c2

3. gitbook本地预览

在推送到远程github之前,可以本地预览最终的gitbook效果,执行如下命令

1
$ gitbook serve

gitbookserve
然后,浏览器打开localhost:4000 即可在预览

4.编写后提交到自己的仓库

c3

5. 在github网站上发起pull request请求

c4
c5
c6

如果有冲突的时候,github网站会给出提示,标识本次pull request可能造成conflict

然后,等待原仓库管理员进行merge操作就可以了

如果你需要从已有的github仓库创建一本属于自己的gitbook,比如上文中你从别人的仓库fork过来的,这个时候,只需要在gitbook上新建图书,然后连接github仓库就好,详细请参考第一部分从零开始创建gitbook(单人),也就是你不需要在github上新建仓库,

以上即是关于gitbook操作的全部内容,转载请注明出处
关于文章中的描述,如有疑问,请在下面的评论区留言,博主会第一时间进行解答更新


博客: http://blog.superlee.me
作者: Superlee

坚持干货知识技术分享,您的支持将鼓励我继续创作!