当我们会写文章了之后,我们有想把他们整合在一起,并且可以快速索引到我们想要的地方,先来看一个效果吧,左边是文章结构的链接,右边显示具体的内容,看看你是不是也想制作这样的“书本”呢?
![97c144674576cb2a81879be8c54a2bcd.png](https://i-blog.csdnimg.cn/blog_migrate/3fc82f74259b6bb9d7205ad19629a532.jpeg)
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来处理的话,有以下的好处:
- 语法简单,你只需要花一点点时间学习就可以掌握所有的知识;
- 兼容性强,可以在多平台操作,生成出多种格式的内容;
- 导出方便,生存的过程非常简单;
- 专注内容,不用过多考虑排版,使用Markdown可以轻松编写;
- 团队协作,组织好结构后,可以由不同的人编写不同的板块,通过git就可以随时同步;
- 当然,gitbook也不是万能的,如果你需要非常精巧的排版,或者你需要印刷你的文章或书籍,还是推荐使用Office相关的软件来处理,gitbook更适合像网页那样展示的效果。
Gitbook在哪使用
目前Gitbook官方网站上,已经有了50万+的用户,15万+的用户空间,以及每个月超过2千万的访问量,这还仅仅是官方的使用情况,不少企业都在内部或对外发布了使用gitbook编写的类似“用户指南”之类的文档。
- 通过gitbook搭建官方说明文档,或内部学习文档,比如cocos官方说明文档
![fbec97220744375f65d7e3f609217d92.png](https://i-blog.csdnimg.cn/blog_migrate/48679ab1c7c6da45be801f9d332e10a3.jpeg)
Cocos官方说明文档
- 通过整理这些书籍,整合成一个书籍分享的网站,比如国内比较流行的看云
![f150abea7ee457cd2afb8b7e474b709e.png](https://i-blog.csdnimg.cn/blog_migrate/d569df2f4dc7b958284ecdebc28986fd.jpeg)
看云官方网站
Gitbook的安装环境
- gitbook的安装是基于nodejs的,如果你本地没有nodejs环境,需要先安装配置一下,具体的操作流程,可以参考《常用环境配置大合集之NodeJs篇》一文,这里仅将具体的步骤图贴出来,以供快速参考。
![eeeeb5aad84f1a029f3b9b2858e94061.png](https://i-blog.csdnimg.cn/blog_migrate/cc81cda6b2a850a8f6cc9f4e8133e2ab.jpeg)
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 即可查看效果了。
![b9b519c4587df7985e2cdeba2e3b9288.png](https://i-blog.csdnimg.cn/blog_migrate/d8cdb2687308acdc7265a835847f0e25.jpeg)
默认的gitbook网站视图
编写文章
就像上个章节所说的那样,将md文件转为html的话,就需要我们去书写 Markdown 文件,关于如何使用与书写 Markdown,其实也是非常简单的,可以参考《如何快速写出高质量文档(Markdown篇)》,这里依然为大家贴上简单的示意图。
![3f246f11b79e299787bd98897b316c1e.png](https://i-blog.csdnimg.cn/blog_migrate/129c7883a1a6164d6f8ccac14a9466b2.jpeg)
使用标记的方式书写文章
组织文章结构
接下来我们先来了解一下组织的结构,上面提到两个重要的文件:
- 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账户非常方便。
![19d34926fcd055739ff7d409b061f706.png](https://i-blog.csdnimg.cn/blog_migrate/e6ee7027bd0c662a137b7ffcc4fcc66c.jpeg)
Gitbook Eidtor编辑器界面
- 如果你想要部署到自己的服务器,那么就让你的 gitbook serve 一直后台运行吧。
欢迎大家关注我,以后每周为大家分享各种程序员视角小知识。同时已准备了一系列的专题进行整理,如有发现问题,也希望大家能及时纠正~