GitBook使用入门篇,让你快速生成文档
2019-03-04 17:39:22
GitBook

前言

相信大家在看很多框架类网站的时候,官网都会提供一套电子书形式的文档供大家学习,那么你会快速生成这种文档吗?

本篇将简单的介绍一下GitBook,它就是专门做这种事的,超级简单,方便,快速哦~

体验网址:http://www.hehaibao.com/uploads/guide/

什么是GitBook?

GitBook 是一个基于 Node.js 的命令行工具,支持 Markdown 和 AsciiDoc 两种语法格式,可以输出 HTML、PDF、eBook 等格式的电子书。所以我更喜欢把 GitBook 定义为文档格式转换工具。

我推荐使用GitBook + Typora一起使用,效率更佳哦~

什么是Typora

一个很棒的支持 macOS、Windows、Linux 的 Markdown 编辑工具

Typora 下载地址:https://typora.io/

Git 下载地址:https://git-scm.com/downloads

Typora 的安装很简单,难点在于需要翻墙才能下载(当然你也可以找我要)。

当然市面上也有很多其他这种工具,我没用过,就不一一说了。

那么怎么安装gitbook呢?

因为 GitBook 是基于 Node.js,所以我们首先需要安装 Node.js(下载地址:https://nodejs.org/en/download/),找到对应平台的版本安装即可。

现在安装 Node.js 都会默认安装 npm(node 包管理工具),所以我们不用单独安装 npm,打开命令行,执行以下命令安装 GitBook:

1
npm install -g gitbook-cli

安装完之后,就会多了一个 gitbook 命令(如果没有,请确认上面的命令是否加了 -g)。

怎么使用呢?

说了这么多,赶紧进入正题,不然你可能要着急咯。

比如 现在你准备构建一个电子书文档,你在硬盘上新建了一个叫 mybook 的文件夹,你首先要做的是在 mybook 文件夹下执行以下命令:

1
gitbook init

执行完后,你会看到多了两个文件 —— README.md 和 SUMMARY.md,它们的作用如下:

README.md —— 书籍的介绍写在这个文件里

SUMMARY.md —— 书籍的目录结构在这里配置

下面我们打开已经安装好的Typora。

将mybook文件夹拖进来。

编辑 SUMMARY.md 文件,内容修改为:

# 目录

  * wordpress主题 H-bao 

  * [前言](README.md)

  * [主题介绍](Chapter1/README.md)

  * [如何购买](Chapter2/README.md)

  * [售后服务](Chapter3/README.md)

  * [常见问题](Chapter4/README.md)

  * [更新记录](Chapter5/README.md) 

    * [# 2018-12-02](Chapter5/20181202.md)
    * [# 2018-12-04](Chapter5/20181204.md)
    * [# 2018-12-05](Chapter5/20181205.md)
    * [# 2018-12-06](Chapter5/20181206.md)
    * [# 2018-12-07](Chapter5/20181207.md)
    * [# 2018-12-10](Chapter5/20181210.md)
    * [# 2018-12-11](Chapter5/2018121.md)
    * [# 2018-12-12](Chapter5/20181212.md)
    * [# 2018-12-13](Chapter5/20181213.md)

  ------

然后创建对应的目录和md文件,因为Typora 是所见即所得(实时渲染)的 Markdown 编辑器,所以你会看到如下图:

GitBook使用入门篇,让你快速生成文档-何海宝的博客

接着我们在终端执行 gitbook serve 来预览这本书籍,执行命令后会对 Markdown 格式的文档进行转换,默认转换为 html 格式,最后提示 “Serving book on http://localhost:4000”。嗯,打开浏览器输入:http://localhost:4000,看一下吧,效果如下图:

GitBook使用入门篇,让你快速生成文档-何海宝的博客

当你写得差不多,你可以执行 gitbook build 命令构建书籍,默认将生成的静态网站输出到 _book 目录。实际上,这一步也包含在 gitbook serve 里面,因为它们是 HTML,所以 GitBook 通过 Node.js 给你提供服务了。
 
当然,build 命令可以指定路径:

1
gitbook build [书籍路径] [输出路径]

serve 命令也可以指定端口:

1
gitbook serve --port 2333

你还可以生成 PDF 格式的电子书:

1
gitbook pdf ./ ./mybook.pdf

生成 epub 格式的电子书:

1
gitbook epub ./ ./mybook.epub

生成 mobi 格式的电子书:

1
gitbook mobi ./ ./mybook.mobi

如果生成不了,你可能还需要安装一些工具,比如 ebook-convert。或者在 Typora 中安装 Pandoc 进行导出。

除此之外,别忘了还可以用 Git 做版本管理呀!在 mybook 目录下执行 git init 初始化仓库,执行 git remote add 添加远程仓库(你得先在远端建好)。接着就可以愉快地 commitpushpull … 啦!

写在最后

好了,本文到此结束!

如果还有什么疑问或者建议,欢迎多多交流,原创文章,文笔有限,文中若有不正之处,万望告知。

如果觉得文章对你有帮助,打个赏,让我有更大的动力去创作,谢谢!