基于 Node.js 的 GitBook 使用入门

关注

原创最新推荐文章于 2026-05-20 09:16:39 发布 286 阅读 AI 写同款· GEO 优化 ›

新版GitBook安装及使用——不完全避坑指南最近打算把一些笔记进行电子化整理和归档，于是尝试了 GitBook。 GitBook 是目前最流行的开源书籍写作方案，可以把Markdown 文件汇集成电子书，并提供 PDF、HTML 等多种格式输出。一般还需配合 Markdown 文本编辑器、Git 代码管理工具和 GitHub 托管仓库使用。我本人使用的 Markdown 文本编辑器 Typora 是一个轻量级的 md 编辑器，页面简洁，也容易上手，使用体验非常好。所以创建开源电子书整体的预备配置包括了GitHub + Git + Typora + 阅读详情

简介

GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书。

本文将介绍如何安装、编写、生成、发布一本在线图书。

支持格式

GitBook 支持输出多种文档格式，如：

静态站点：GitBook 默认输出该种格式，生成的静态站点可直接托管搭载 GitHub Pages 服务上。
PDF：需要安装 gitbook-pdf 依赖。
eBook：需要安装 ebook-convert。
单HTML网页：支持将内容输出为单页的 HTML，不过一般用在将电子书格式转换为 PDF 或 eBook 的中间过程。
JSON：一般用于电子书的调试或元数据提取。

GitBook项目地址：

GitBook 项目官网：http://www.gitbook.io
GitBook GitHub 地址：https://github.com/GitbookIO/gitbook

基本安装

本章内容讲述 GitBook 的安装及命令行的功能快速预览说明。

Node.js 安装

Node.js 是一个基于 Chrome JavaScript 运行时建立的一个平台，用来方便搭建快速的、易于扩展的网络应用。

Node.js 借助事件驱动，非阻塞 I/O 模型变得轻量和高效，非常适合 run across distributed devices 的 data-intensive 的实时应用。

安装完成这后，你可以在终端模式下检验一下：

$ node -v
v0.10.28

看到以上提示，就表示你已成功安装上 Node.js 了。

GitBook 安装

GitBook 是从 NMP 安装的，命令行：

$ npm install gitbook -g

安装完之后，你可以检验下是否安装成功：

$ gitbook -V
0.4.2

如果你看到了与上面类似的版本信息，则表示你已成功完装上了 GitBook。

GitBook 命名行速览

GitBook 是一个命令行工具，使用方法：

本地预览

$ gitbook serve ./图书名称

输出一个静态网站

$ gitbook build ./repository --output=./outputFolder

查看帮助

$ gitbook -h
 
Usage: gitbook [options] [command]
 
Commands:
 
build [options] [source_dir] Build a gitbook from a directory
serve [options] [source_dir] Build then serve a gitbook from a directory
pdf [options] [source_dir] Build a gitbook as a PDF
ebook [options] [source_dir] Build a gitbook as a eBook
init [source_dir] Create files and folders based on contents of SUMMARY.md
 
Options:
 
-h, --help     output usage information
-V, --version  output the version number

图书项目结构

README.md 和 SUMMARY.md 是 GitBook 项目必备的两个文件，也就是一本最简单的 GitBook 也必须含有这两个文件，它们在一本 GitBook 中具有不同的用处。

目录初始化

当这个目录文件创建好之后，我们可以使用 GitBook 的命令行工具将这个目录结构生成相应的目录及文件：

$ gitbook init
$ ls
LICENSE    SUMMARY.md book       output
README.md      howtouse   publish
$ tree .
.
├── LICENSE
├── README.md
├── SUMMARY.md
├── book
│ ├── README.md
│ ├── file.md
│ └── prjinit.md
├── howtouse
│ ├── Nodejsinstall.md
│ ├── README.md
│ ├── gitbookcli.md
│ └── gitbookinstall.md
├── output
│ ├── README.md
│ ├── outfile.md
│ └── pdfandebook.md
└── publish
 ├── README.md
 └── gitpages.md

我们可以看到，GitBook 给我们生成了与 SUMMARY.md 所对应的目录及文件。

每个目录中都有一个 README.md 文件，相当于一章的说明。

图书输出

本章内容讲述如何将编写好的图书输出为我们所需要的格式。目前为止，GitBook 支持如下输出：

静态 HTML，可以看作一个静态网站
PDF 格式
eBook 格式
单个 HTML 文件
JSON 格式

我们这里着重说下如何输出静态的 HTML 和 PDF 文件。

输出为静态网站

你有两种方式输出一个静态网站：

1.本地预览时自动生成

当你在自己的电脑上编辑好图书之后，你可以使用 GitBook 的命令行进行本地预览：

$ gitbook serve ./图书目录
这里会启动一个端口为 4000 用于预览的服务器：
$ gitbook serve .
Press CTRL+C to quit ...
 
Starting build ...
Successfuly built !
 
Starting server ...
Serving book on http://localhost:4000

你可以你的浏览器中打开这个网址：http://localhost:4000：

这里你会发现，在你的图书项目的目录中多了一个名为 _book 的文件目录，而这个目录中的文件，即是生成的静态网站内容。

使用 build 参数生成到指定目录，与直接预览生成的静态网站文件不一样的是，使用这个命令，你可以将内容输入到你所想要的目录中去：

$ mkdir /tmp/gitbook
$ gitbook build --output=/tmp/gitbook
Starting build ...
Successfuly built !
$ ls /tmp/gitbook/
LICENSE           howtouse          manifest.appcache search_index.json
book              imgs              output
gitbook           index.html        publish

2.输出 PDF

输入为 PDF 文件，需要先使用 NPM 安装上 GitBook PDF ：

$ npm install gitbook-pdf -g

笔者在安装这个模块，下载一个名为 phantomjs 的包时，出现请求未能响应的情况，你可以到这个应用的网站上去下载：http://phantomjs.org/。

这个包的安装方法，请看网站上的说明。然后，使用下面的命令，可生成 PDF 文件了：

$ gitbook pdf ./图书目录

如果你在图书目录内容，也可以这样做：

$ gitbook pdf .

然后，你会发现你的目录里多了一个名为 book.pdf 的文件！

发布

本章内容讲述如何使用 GitHub Pages 服务将我们的发布到网络上去。我们假设你已经会使用 Git 命令和 GitHub 的仓库管理。

发布到 GitHub Pages

将编写好的格式为 .md 的文件通过 GitBook 处理，然后再发布到 GitHub Gages 上去。

我个人比较喜欢将源码，即 .md 文件与 GitHub Pages 静态文件存放在一个仓库中。

.md 文件为 master 分支，而 HTML 文件为 gh-pages 分支。具体流程是这样的：

1.创建仓库与分支

登录到 GitHub，创建一个新的仓库，名称我们就命令为 book ，这样我就就得到了一个 book 的空仓库。
克隆仓库到本地： git clone git@github.com:USER_NAME/book.git 。
创建一个新分支： git checkout -b gh-pages ，注意，分支名必须为 gh-pages 。
将分支 push 到仓库： git push -u origin gh-pages 。
切换到主分支: git checkout master 。

经过这一步处理，我们已经创建好 gh-pages 分支了，有了这个分支，GitHub 会自动为你分配一个访问网址：

http://USERNAME.github.io/book

你可以在项目页面右下 settings 中看到。当然，由于我们内容还没有上传所以你点开链接，也只是一个 404 页面。

2.同步静态网站代码到分支

下面我们就可以将 build 好的静态网站代码同步到 gh-pages 分支中去了：

切换出 master 分支目录。我们需要将 gh-pages 分支内容存放到另一个目录中去。
克隆 gh-pages 分支： git clone -b gh-pages git@github.com:USERNAME/book.git book-end 。这步我们只克隆了 gh-pages 分支，并存放在一个新的目录 book-end 里面。
Copy 静态多站代码到 book-end 目录中。
Push 到仓库。

然后，等十来分钟，你就可以访问到你的在线图书了。而后，每次修改之后，都可以将生成的代码 Copy 到 book-end 目录，再 Push 一下就好了。

当然，对于 gh-pages 存放问题，你也可以直接在 master 分支目录中直接 git clone gh-pages 分支，假如名称为 book-end ，然后修改一下 .gitignore 文件，将 book-end/ 添加进去，这样主分支就不会理会 book-end 内容的修改了。

笔者曾试过直接使用 gitbook build –output=/PATH/book-end 这个方式输出到 gh-pages 分支目录中，但发现 GitBook 在 build 的时候，相当于删除存在的这个目录，然后再新建目录，再写入内容，原来的 Git 信息会完全删除掉，显示这不是我们想要看到的，所以只能 Copy 才行。