最近打算把一些笔记进行电子化整理和归档,于是尝试了 GitBook。
GitBook 是目前最流行的开源书籍写作方案,可以把Markdown 文件汇集成电子书,并提供 PDF、HTML 等多种格式输出。一般还需配合 Markdown 文本编辑器、Git 代码管理工具和 GitHub 托管仓库使用。我本人使用的Typora 是一个轻量级的 Markdown 文本编辑器,页面简洁,也容易上手,使用体验比较好。
所以创建开源电子书整体的预备配置包括了GitHub + Git + Typora + GitBook
。前三者的准备比较简单:注册 GitHub 账号,下载 GitHub DeskTop, Git 和 Typora(或其他Markdown 文本编辑器,如 GitBook Editor),这里就不再赘述。
GitBook的安装折腾了我将近一整天… 由于 GitBook 近期进行了改版和更新,网络上的一些教程可能不再完全适用。这里结合个人的摸索,介绍一下改版后 GitBook 的安装和使用步骤,以及我在安装过程中踩过的一些坑和解决办法。
GitBook 是基于 Node.js的,所以我们首先需要安装对应版本的 Node.js(下载网址:https://nodejs.org/en/download/)
目前Node.js的最新稳定版本的v12.18.3
。但这个版本对GitBook可能不兼容(在后续安装和启动 GitBook 命令时会出现错误提示),建议直接安装v10.22.0
。
当然,如果开始时选择了最新版本也不用慌,可以先尝试后续步骤,如果出现错误提示,参考避坑指南-Node.js版本问题尝试解决。
现在安装 Node.js 都会默认安装 npm(node 包管理工具),所以我们不用单独安装 npm,打开全局命令行Win+R, 输入cmd
,执行以下命令:
npm install -g gitbook-cli
耐心等待,安装完成后会显示 GitBook-cli 的版本。
安装完之后,就会多一个 gitbook 的命令。执行
gitbook -V (注意:V要大写)
如果在上一步骤GitBook安装成功,命令行中会展示版本信息。至此,恭喜你安装成功。
gitbook -V
时显示:Installing GitBook 3.2.3 …….
,之后出现长时间卡顿npm config set registry=http://registry.npm.taobao.org -g
if (cb) cb.apply(this, arguments)
^
TypeError: cb.apply is not a function
或
# Fatal error in , line 0
# Check failed: U_SUCCESS(status).
#
#
#
#FailureMessage Object: 00000013F6B1D570
说明Node.js的版本环境有问题,需要降低Node版本。最新稳定版本是v12.18.3,试下来在Win10上v10.22.0是可以正常使用的,下面以该版本的安装为例,展示上述报错的解决方案。(注:该方法可能只使用于Win10操作系统)
解决办法1: 卸载已下载版本,重新下载10.22.0
版本的Node.js(下载网址:https://nodejs.org/zh-cn/download/releases/)
缺点:对未来Node.js版本的更新或多个版本之间的切换使用不太方便
解决办法2: 使用Windows系统下的Node.js的版本管理器nvm-windows
(Node.js Version Manager for Windows)。nvm-windows可以帮助实现在同一台设备上进行多个node版本之间的切换。主要步骤:
下载nvm:在github地址:https://github.com/coreybutler/nvm-windows,选择nvm-setup.zip,下载后直接安装。
配置nvm的环境变量:一些教程中提到安装完nvm后需要手动配置环境变量,但最新版本(我下载的是v1.7.7
)的nvm-windows在安装完成之后已经自动配置了环境变量。可以再次确认你的环境变量中是否包含了nvm的路径。
使用nvm命令实现多版本node的下载和切换:
nvm -v 查看nvm版本信息:
nvm install 10.22.0 安装多版本 node/npm(以v10.22.0为例):
nvm use 10.22.0 使用特定Node版本(以v10.22.0为例):
nvm ls available 查看远程服务器上的可用Node版本:
nvm ls 查看本机的可用Node版本
nvm install
命令下载新的Node版本会比较慢,这时可以直接从网址:https://nodejs.org/zh-cn/download/releases/上下载所需版本,并安装到nvm的源文件夹下。新建一个文件夹,在文件夹下打开命令窗口(在文件夹地址栏输入cmd后回车
或在cmd中用cd命令
),初始化文件夹:
gitbook init
执行上述命令后,会自动生成两个必要的文件 README.md
和 SUMMARY.md
。
README.md: 书的介绍文字,如前言、简介,在章节中也可做为章节的简介。
SUMMARY.md: 定制书籍的章节结构和顺序。
gitbook serve
执行命令,GitBook 会启动一个 4000 端口(http://localhost:4000)用于预览。
但由于GitBook版本不稳定,有时运行serve命令会出现报错:
Error: ENOENT: no such file or directory, stat '~~~.js'
解决办法: 在用户目录下找到以下文件.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js
,把所有的 confirm: true
替换为 confirm: false
。
gitbook build
上述命令默认将生成的静态网站输出到 _book
目录。
实际上,这一步也包含在 gitbook serve
里面,但 gitbook build
可以指定路径:
gitbook build [书籍路径] [输出路径]
gitbook pdf ./ ./mybook.pdf
gitbook epub ./ ./mybook.epub
gitbook mobi ./ ./mybook.mobi
官方获取插件地址: https://plugins.gitbook.com/
安装插件只需要在书籍目录下增加 book.json
文件,例如增加折叠目录的插件,需要在 book.json
内增加下面代码:
{
"plugins": ["expandable-chapters-small"],
"pluginsConfig": {
"expandable-chapters-small":{}
}
}
然后终端执行 install
来安装插件即可:
gitbook install
https://www.bilibili.com/video/BV14s411n7fD/?spm_id_from=333.788.videocard.3
https://www.cnblogs.com/yufanstudio/p/12300324.html
以上是我在安装和使用GitBook过程中的一些体会,刚刚入门,欢迎交流~
参考文章:
教你在Github写开源电子书
编写Gitbook电子书教程
GitBook 从懵逼到入门
GitBook 安装以及使用
nvm介绍及使用