GitBook 使用教程_资讯

GitBook 使用教程

创始人

2025-05-28 18:17:59

0次

GitBook，顾名思义它是一个与书有关的工具。通过 GitBook，你可以只用一些 .md 文件就生成一个电子书网页（~~我绝对不会告诉你我就是为了它而去学 GitBook 的~~）或是一本真正的 .epub .mobi 等等格式的电子书。废话不多说，直接开始教程~

1. GitBook 安装

要使用 GitBook 我们得先安装它的命令行工具 gitbook-cli。而安装 gitbook-cli 得先安装 Node.js。没办法，我们先安装吧……

去 Node.js 官网，点这个 msi 下载安装包然后安装它：

安装完之后 win+r 输入 cmd 打开命令提示符输入 npm --version。如果有弹出信息就说明 Node.js 安装成功了。

然后就可以正式安装 GitBook 了。输入 npm i gitbook-cli -g，安装 gitbook-cli：

完事之后输入 gitbook-cli -V 查看 gitbook-cli 版本号并安装 gitbook 本尊：

等亿会儿，不出意料，它报了一个错：

找到错误中那个 polyfills.js 文件的位置，即上图中画横线的部分。然后打开它，找到 65~67 行，直接全部注释掉（即在前面加上 //），如下：

保存，重新 gitbook -V，应该就能安装成功：

2. GitBook 的基本使用

恭喜！安装成功了~

但这仅仅只是一小步，GitBook 是一个复杂的工具，~~要不然花这么长一篇文章说它干嘛~~

找到一只幸运的文件夹，然后如下图所示在此处打开命令提示符：

输入 gitbook init 在该目录初始化一个 gitbook：

不出意外，它又报错了：

网上大部分教程中都是说把 Node.js 换成 12 版，但是 12 版太老了实在是接受不了（T_T）终于，我找到了解决方案（来自博主 @qq_33641175，感谢）。找到你计算机上的这个目录：

然后打开目录下的 init.js，找到第 72 行的 return fs.writeFile(filePath, summary.toText(extension)); 修改为
return summary.toText(extension).then(stx=>{return fs.writeFile(filePath, stx);})，如下：

保存，重新 gitbook init，就可以了~

这时我们会发现出现了两个文件：README.md 与 SUMMARY.md。README.md 是用来写简介的，SUMMARY.md 是用来写目录的。关于 SUMMARY.md 我们会在第 3 节具体说明。现在先把目光放在 README.md 上。

打开 README.md（我使用的是 Typora），在里面随便写些简介：

刚才那个命令行应该没关吧？如果关了就再启动一次。输入 gitbook serve，在跳出的这个界面把两个都勾起来然后点确定：

然后会跳出一个 URL（通常是 localhost:4000），你可以在这里预览你的电子书（按下 Ctrl + C）：

（关于里面的内容怎么切换成中文，第 4 节会详细说。)

你可能会在文件夹中发现一个新的文件夹叫做 _books，里面存放着一些 HTML CSS JS 等静态文件。这些静态文件我们可以放在服务器上或是 GitHub Pages 上，这样别人就可以通过访问你的服务器或 GitHub Pages 来看你的电子书。

（如果你想生成真正的电子书，请参阅最后一章）

如果我们只想生成静态文件，不想开启预览怎么办呢？我们可以使用 gitbook build 命令，它只生成静态页面，不开启预览~~（这不废话）~~。

3. SUMMARY.md

这一小节我们要来聊一聊文章目录 SUMMARY.md。首先我们需要知道 MarkDown 语法里面的毛锚链接。它的结构是 []()，中括号里写链接的文字，小括号里写链接的地址。比如 [目录](SUMMARY.md) 就是一个显示为目录的链接，SUMMARY.md 是链接的地址。你点击这个链接，它就会帮你跳转至 SUMMARY.md。

让我们在 SUMMARY.md 中试一试。书写目录时使用无序列表，快捷键 Ctrl + Shift + ]。如下：

保存，重新 gitbook serve，你会发现 something different：

SUMMARY.md 还可以创建复杂一些的目录结构，比如第一章第一节之类的子目录结构。首先我们创建几个 md，然后把它们放进不同的文件夹内（其中各部分的 README.md 为该章的引言，可以要也可以不要）：

同时指向它们的锚链接格式也要有些变化，需要加上目录名，比如 Chapter 1/README.md。

然后更改 SUMMARY.md。如果你需要书写二级目录（比如 Chapter 1 下的各篇小 md 的目录），你可以按下 Tab 键使这个无序列表变成二级的。如下：

重新 gitbook serve：

SUMMARY.md 中还有一个语法：分割线 —。它可以把我们的目录上下分成不同的部分。实验一下：

重新 gitbook serve：

4. book.json

这一小节要说的文件是 book.json。它是我们电子书的配置文件。gitbook 初始化的时候虽然没有为我们自动生成，但是我们可以自己创建。在与 SUMMARY.md 同级的目录中新建 book.json，然后打开它：

以下是 book.json 的常用的一些功能：

{"title": "Easy Algorithms","author": "copcin","description": "阿巴阿巴","language": "zh-hans","gitbook": "3.2.3","links": {"sidebar": {"GitHub": "xxx"}}
}

对每一个选项做一下说明：

title：书名

author：作者

description：对书的简单描述

language：zh-hans 代表简体中文。有了这个选项你就可以把 GitBook 页面切换成中文。

gitbook：GitBook 版本。通常为 3.2.3。

links.sidebar：侧边栏的一些链接。比如 “GitHub”: “xxx” 就代表一个名字为 GitHub 的指向 xxx 的链接。

保存，重新 gitbook serve：