GitBook 简明使用教程

GitBook 简明使用教程

GitBook 是用来创建一个现代化的文档工具。比如经常被用编写系统文档、API 文档、数据库文档等。要使用 GitBook 必须安装 nodejs,以便能够使用 npm 来安装 gitbook。其次还能导出 pdf、epub、mobi 等格式文件。

1 环境安装

1.1 nodejs 安装

由于我们会用到 npm 命令。所以,我们得先安装 nodejs。

大家可以根据自己的系统类型(Windows、Mac)进行对应的安装。这里仅介绍 Windows 版本的 nodejs 安装。

进入官网地址直接下载 Windows 版本的 nodejs 双击安装即可。地址: https://nodejs.org/zh-cn/

验证是否安装成功。

打开 windows 下的命令提示符工具执行如下命令:

C:\Users\Administrator>node -v
v10.16.3

如果正确安装就会得到 node 的版本号。否则会提示:

C:\Users\Administrator>node -v
'node' 不是内部或外部命令,也不是可运行的程序或批处理文件。

1.2 安装 gitbook 库

在 windows 命令提示符窗口执行如下命令:

C:\Users\Administrator>npm install gitbook-cli -g

安装成功之后,再执行如下命令确认是否安装成功。

C:\Users\Administrator>gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

-V 是大写的字母 V。

有些教程会在安装的时候命令是:npm install gitbook -g。注意少了 gitbook 后面少了 gitbook-cli。这样运行 gitbook -V 命令的时候失提示要安装 gitbook-cli

1.3 安装 ebook-convert 以及 calibre

gitbook 可以将我们写的电子书或文档导出为 PDF、ePub、Mobi 等格式。而导出这三种格式又依赖 npm 的 ebook-convert 库。

而在 windows 下,ebook-convert 库又依赖 calibre 软件提供的库。所以,我们要安装这两个东西。

1.3.1 安装 ebook-convert

在 windows 命令提示符执行如下命令安装:npm install ebook-convert -g

C:\Users\Administrator>npm install ebook-convert -g

验证安装成功与否。

在 windows 命令提示符执行如下命令: ebook-convert --version

C:\Users\Administrator>ebook-convert --version
ebook-convert.exe (calibre 4.2.0)
Created by: Kovid Goyal <kovid@kovidgoyal.net>

1.3.2 安装 Calibre 软件

去官网找对应系统的下载。官网下载地址: https://calibre-ebook.com/download

注意:如果 windows 系统是 64 位,请下载 windows 64 版本的 Calibre。

Windows 下载安装没有特别之后,直接下一步下一步就完成了安装。

安装成功之后还不行。

必须把 Calibre 所在的安装目录添加到系统环境变量 PATH 中。

我的 Calibre 安装目录是: C:\Program Files (x86)\Calibre2 。所以,我把该路径添加到了系统环境变量 PATH 中。至于怎样添加请自行在网上搜索"windows 环境变量添加"。win7 与 win8 操作方式小不同。这里就不做多余说明。

很多人只安装了 ebook-convert 命令,而忘记安装 Calibre 软件,导致导出报错。另外还就有安装之后未添加到系统环境变量。

关于怎样导出 PDF、ePub、Mobi 格式文件。将会后面讲解。

2 创建电子书

在创建电子书文档时,我们先看一个创建好的示例运行效果。

gitbook-001.png

这种结构形式完全是像一本书呈现出来。我们可以用它存放我们的系统设计、API 文档、数据库文档等系列文档。

2.1 先睹为快

为了快速感受 GitBook 带来的魅力,我们来快速搭建体验一下。

在系统任何位置创建一个目录。如:gitbook-test。然后运行 gitbook init 初始化电子目录。然后执行 gitbook serve 启动一个 Web 服务运行该电子书。

E:\gitbook>mkdir gitbook-test

E:\gitbook>cd gitbook-test

E:\gitbook\gitbook-test>gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

E:\gitbook\gitbook-test>gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.3s !

Starting server ...
Serving book on http://localhost:4000

以上就是我快捷创建一本书电子书的全过程。此时,我们已经启动了一个 Web 服务,可以在浏览器直接访问这本电子书了。

浏览器输入:http://localhost:4000

gitbook-002.png

剩下的事情就是我们来编辑这本书里面的内容了:书目录、内容、友情链接等。

2.2 目录结构

通过上一小节我们快捷创建了一个电子书的项目。通过 gitbook init 命令我们产生两个非常关键的文件:

README.md
SUMMARY.md

README.md 它是我们通过浏览器访问电子书时默认显示的首页。是这本电子书的开篇介绍部分。这是相当重要的。请认真妥善对待它。

SUMMARY.md 这个文件它决定了我们左侧的目录结构。所以,这个文件也是相当的重要。

SUMMARY.md 文件的初始内容为如下:

# Summary

* [Introduction](README.md)

我在上面部分演示了自己的创建的电子书。看看我的 SUMMARY.md 是怎样编写的。

# Summary

* [介绍](README.md)
* [第 1 章:Session 分布式存储](chapter-1/README.md)
  * [1.1 Session 基础](chapter-1/basics.md)
* [第 2 章:队列](chapter-2/README.md)
  * [2.1 Redis](chapter-2/redis.md)
  * [2.2 Kafka](chapter-2/kafka.md)
  * [2.3 RabbitMQ](chapter-2/rabbitmq.md)
* [第 3 章:锁](chapter-3/README.md)
  * [3.1 文件锁](chapter-3/file.md)
  * [3.2 MySQL 锁](chapter-3/mysql.md)
  * [3.3 Redis 锁](chapter-3/redis.md)
* [第 4 章:PHP CLI](chapter-4/README.md)
* [第 5 章:守护进程](chapter-5/README.md)
* [第 6 章:Supervisor 管理守护进程](chapter-6/README.md)
* [第 7 章:PHP 多进程](chapter-7/README.md)
* [第 8 章:Composer 基础](chapter-8/README.md)
* [第 9 章:Composer 包开发](chapter-9/README.md)
* [第 10 章:PHP C 扩展安装](chapter-10/README.md)
* [第 11 章:Web Api 设计](chapter-11/README.md)
* [第 12 章:Postman 使用](chapter-12/README.md)
* [第 13 章:PHPunit 单元测试](chapter-13/README.md)
* [第 14 章:PHP 加密技术](chapter-14/README.md)
* [第 15 章:PHP 常量功能案例](chapter-15/README.md)

---

* [第 16 章:PHP-FPM](chapter-16/README.md)
* [第 17 章:Nginx](chapter-17/README.md)
* [第 18 章:Linux](chapter-18/README.md)
* [第 19 章:MySQL](chapter-19/README.md)
* [第 20 章:Web 安全](chapter-20/README.md)
* [第 21 章:HTTP 协议](chapter-21/README.md)
* [第 22 章:Git+GitHub+GitBook](chapter-22/README.md)

通过我给出的示例,其实已经说明了很多事情。

2.2.1 多级目录

书的目录并不只有一级。也会存在二级三级甚至多级的情况。那么怎样让电子书呈现多级呢?

我对 SUMMARY.md 文件进行了更改。如下:

# Summary

* [开篇介绍](README.md)
* [第一级](README.md)
  * [第二级-2.1](README.md)
  * [第二级-2.2](README.md)
    * [第三级-3.1](README.md)

此时我们再去浏览器刷新查看文档目录结果变成了如下图所示:

gitbook-003.png

我们可以得出结论:多级目录实际上是通过缩进方式来进行区分实现的。

2.2.1 文章内容

上面的目录结果还有一个问题我们忽略了。所有的目录都指向同一个 README.md。这是不合适的。所以,在编写文章的时候,请每个目录一个 markdown 文件。这里就不做细说。很容易看明白。

2.3 目录折叠

通过上面演示的示例,大家一定发现了一个问题:目录层级越来越多之后,目录的滚动查看就越来越不方便。那么应该怎样折叠呢?

目录折叠 gitbook 默认没提供这样的功能。但是,可以通过安装配套的 gitbook 插件来实现。也是相当简单的。

在根目录下创建一个 book.json 的文件。该文件主要是对电子书的各种属性进行配置。

book.json 主要功能:

  • 配置电子书名称
  • 配置电子书作者
  • 配置电子书描述
  • 配置电子书语言各类
  • 配置电子书使用的 gitbook 版本
  • 自定义电子书样式
  • 配置电子书左侧导航友情链接
  • 配置插件

本小节目录折叠功能就是靠在 book.json 文件中增加如下配置实现:

{
    "plugins": [ 
        "expandable-chapters"
    ]
}

现在我们在 book.json 当中配置成功之后还不能生效。我们必须执行 gitbook install 命令安装。

E:\gitbook\gitbook-lamphp>gitbook install
info: installing 1 plugins using npm@3.9.2
info:
info: installing plugin "expandable-chapters"
info: install plugin "expandable-chapters" (*) from NPM with version 0.2.0
info: >> plugin "expandable-chapters" installed with success

因为我已经安装了的缘故,所以会提示我该插件已经安装了。

此时我们再通过 gitbook serve 启动 Web 服务再去访问。发现之前展示的导航全部折叠了。

2.4 分隔符

当我们折叠的目录太多的时候。我们肯定会希望把一组功能相关的功能导航通过分隔符以示区分。实现这个简单。只需要在 SUMMARY.md 文件当中对导航如下设置即可。

示例:

......
* [第 13 章:PHPunit 单元测试](chapter-13/README.md)
* [第 14 章:PHP 加密技术](chapter-14/README.md)
* [第 15 章:PHP 常量功能案例](chapter-15/README.md)

---

* [第 16 章:PHP-FPM](chapter-16/README.md)
* [第 17 章:Nginx](chapter-17/README.md)
......

对!就这么简单。只需要 --- 三个减号符号即可搞定。

2.5 友情链接

友情链接也是一个非常重要的功能。不管是推广自己的网站还是合作伙伴的网站。这个功能都非常棒。

它也是通过 book.json 文件来实现的。

在 book.json 中增加如下配置:

{
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

2.6 设置书名

书名或文档名称。也是通过 book.json 实现。

示例如下:

{
    "title": "《PHP 向前冲》",
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

2.7 设置作者/描述/语言/版本

也是通过 book.json 来实现。以下示例配置一看就明白。勿须多做说明。

{
    "title": "《PHP 向前冲》",
    "author": "fingerQin",
    "description": "一本集作者十年开发经验的 PHP 电子书",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

2.8 自定义样式

每个人都有自己对美的定义。gitbook 默认的文档样式可能对很多有着更高追求的人来说可能还需要优化。我们的 gitbook 也考虑到这种情况,提供了一种自定义样式的机制让你可以随心所欲制定自己外观。

{
    "title": "《PHP 向前冲》",
    "author": "fingerQin",
    "description": "一本集作者十年开发经验的 PHP 电子书",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "styles": {
        "website": "./styles/website.css"
    },
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "PHP 解说": "https://phpjieshuo.com"
        }
    },
    "plugins": [ 
        "expandable-chapters"
    ]
}

在上面的配置当中,我们增加了如下配置:

......
"styles": {
        "website": "./styles/website.css"
    }
......

3 插件

除了样式可以定制,我们还可以通过插件的形式定制更多的功能。GitBook 默认提供 highlight、search、sharing、fontsettings、livereload 5 个插件。

  • highlight 代码高亮插件。
  • search 搜索插件。就是左侧菜单顶部的搜索功能。
  • sharing 社会化分享工具。
  • fontsettings 文章内容字符设置插件。如文字大小、字体、背景颜色设置。
  • livereload 内容扫更新。如果不使用此插件则内容更新每次都要重启 Web 服务才能看到变化内容。

gitbook-004.png

3.1 插件使用

插件使用非常简单。只需要在 book.json 的 plugins 小节配置即可。如下所示:

{
    ......
    "plugins": [ 
        "expandable-chapters",
        "search"
    ]
    ......
}

注:GitBook 默认的插件即使不在此处配置也是生效的。

3.2 插件配置

所谓插件配置是指当我们要使用一个插件的时候,此插件可能提供了一些高级功能的配置。所以,此时我们需要配置这些参数,则需要通过 plugins-configs 来控制。

我们以配置 sharing 默认插件的分享平台开关为例:

{
    ......
    "plugins": [ 
        "expandable-chapters",
        "search",
        "sharing"
    ],
    "pluginsConfig": {
        "sharing": {
            "facebook" : true,
            "weibo" : false
        }
    }
    ......
}

如果对插件的配置不是特别清楚,可以查看文档: https://www.npmjs.com/package/gitbook-plugin-sharing-plus

在这里可以找到所有插件对应的文档。

3.3 插件禁用

我们安装了各种各校的插件。有时候我们不需要某个插件的时候,可以禁用插件生效。禁用插件也非常简单。

禁用分享插件示例:

{
    ......
    "plugins": [ 
        "expandable-chapters",
        "search",
        "-sharing"
    ]
    ......
}

没错。就是在插件名字前面加一个减号"-"即可对插件禁用。

3.4 常用插件

默认提供的 5 个插件固然很优秀。但是,我们还是希望拥有更多的功能。

3.4.1 捐赠

可以说这个插件是非常常见的功能了。

插件名称:donate

插件地址: https://www.npmjs.com/package/gitbook-plugin-donate

book.json 配置:

{
    ......
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
          "wechat": "微信捐赠二维码图片地址",
          "alipay": "支付宝捐赠二维码图片地址",
          "title": "捐赠",
          "button": "默认值:Donate",
          "alipayText": "默认值:支付宝捐赠",
          "wechatText": "默认值:微信捐赠"
        }
    }
    ......
}

记住,配置好之后,要执行 gitbook install 安装这个插件。否则,这个插件不生效且可能会报错。

3.4.2 导航目录折叠

在本文档 2.3 小节我们已经介绍过了。这里不多做介绍。

插件名称:expandable-chapters

插件地址: https://www.npmjs.com/package/gitbook-plugin-expandable-chapters

3.4.3 回到顶部

当一个页面内容太多的时候。回到顶部这样一个小且实用的功能是非常棒的。

插件名称:back-to-top-button

插件地址: https://www.npmjs.com/package/gitbook-plugin-back-to-top-button

{
    "plugins" : [ "back-to-top-button" ]
}

使用比较简单,直接在 plugins 中增加 back-to-top-button 并通过 gitbook install 安装这个插件即可生效。

3.4.4 内页生成导航

当我们一个内页内容非常多的时候。此时如果能在内页起始就能查阅当前的内页目录提供检索,那是相当的棒。

插件名称:page-treeview

插件地址: https://www.npmjs.com/package/gitbook-plugin-page-treeview

{
    "plugins" : [ "page-treeview" ]
}

使用比较简单,直接在 plugins 中增加 page-treeview 并通过 gitbook install 安装这个插件即可生效。

由于常用且实用的插件很多。这里仅作抛砖引玉。更多更优秀的插件等着大家去发掘。

4 导出

导出功能可谓非常强大。gitbook 支持导出 pdf、epub、mobi、html静态网站等。

在环境安装一小节,我们已经安装了 ebook-convert 插件以及 calibre 软件。所以,这里不再对这两个东西的安装进行过多说明。

4.1 导出 PDF

导出 PDF 非常容易。打开 windows 命令行提示符,在电子书根目录执行命令:gitbook pdf

E:\gitbook>gitbook pdf

直接回车慢慢等待即可。执行成功会在当前目录下生成一个 pdf 文件。

不过我在 windows 下运行的时候会出现工具内部代码报错的异常。这可能与平台工具有很大关系。

4.2 导出 ePub

与 PDF 一样依然很简单。打开 windows 命令提示符,在电子书根目录执行命令:gitbook epub

E:\gitbook>gitbook epub
info: 9 plugins are installed
info: 13 explicitly listed
info: loading plugin "expandable-chapters"... OK
info: loading plugin "highlight"... OK
info: loading plugin "splitter"... OK
info: loading plugin "livereload"... OK
info: loading plugin "sharing"... OK
info: loading plugin "search"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "lunr"... OK
info: loading plugin "theme-default"... OK
info: found 30 pages
info: found 42 asset files
info: >> generation finished with success in 2.6s !
info: >> 1 file(s) generatedE:\gitbook>gitbook epub

命令运行成功会在根目录生成一个 book.epub 格式的文件。

4.3 导出 mobi

与 PDF 一样依然很简单。打开 windows 命令提示符,在电子书根目录执行命令:gitbook mobi

E:\gitbook>gitbook mobi
info: 9 plugins are installed
info: 13 explicitly listed
info: loading plugin "expandable-chapters"... OK
info: loading plugin "highlight"... OK
info: loading plugin "splitter"... OK
info: loading plugin "livereload"... OK
info: loading plugin "sharing"... OK
info: loading plugin "search"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "lunr"... OK
info: loading plugin "theme-default"... OK
info: found 30 pages
info: found 43 asset files
info: >> generation finished with success in 3.0s !
info: >> 1 file(s) generated

命令运行成功会在根目录生成一个 book.mobi 格式的文件。

mobi 格式是亚马逊 kindle 的电子书格式。可以直接发送到 kindle 设备阅读。

4.4 导出 HTML

非常简单。如下所示:

E:\gitbook>gitbook build
info: 9 plugins are installed
info: 13 explicitly listed
info: loading plugin "expandable-chapters"... OK
info: loading plugin "highlight"... OK
info: loading plugin "splitter"... OK
info: loading plugin "livereload"... OK
info: loading plugin "sharing"... OK
info: loading plugin "search"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "lunr"... OK
info: loading plugin "theme-default"... OK
info: found 30 pages
info: found 44 asset files
info: >> generation finished with success in 1.6s !

会在当前目录下的 _book 文件夹下生成一堆的 HTML。就可以打包成各种各样的格式分享出去。比如,打包成 CHM 格式的文件。

博主 2011 年创建了一个《PHP 初学者官方群》,目前群成员 500 人左右。群号:168159147。为了防止广告,设置为付费入群。欢迎大家加入讨论技术!

标签: 无

精彩评论
  1. 现在写技术文档 vuepress 了解下

  2. flyingfox

    博主大佬自己写的技术文档网址可以分享一下吗..付费也行

    1. 我做的这套教程本身也是为了收费准备的。

发表评论: