新版GitBook安装及使用——不完全避坑指南_Luminous-CSDN博客_gitbook版本

最近打算把一些笔记进行电子化整理和归档，于是尝试了 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安装过程

1、安装 Node.js

GitBook 是基于 Node.js的，所以我们首先需要安装对应版本的 Node.js（下载网址：https://nodejs.org/en/download/）

在这里插入图片描述
目前Node.js的最新稳定版本的v12.18.3。但这个版本对GitBook可能不兼容（在后续安装和启动 GitBook 命令时会出现错误提示），建议直接安装v10.22.0。

当然，如果开始时选择了最新版本也不用慌，可以先尝试后续步骤，如果出现错误提示，参考避坑指南-Node.js版本问题尝试解决。

2、安装GitBook

现在安装 Node.js 都会默认安装 npm（node 包管理工具），所以我们不用单独安装 npm，打开全局命令行Win+R, 输入cmd，执行以下命令：

npm install -g gitbook-cli

耐心等待，安装完成后会显示 GitBook-cli 的版本。

在这里插入图片描述
在这里插入图片描述

3、确认GitBook安装完成

安装完之后，就会多一个 gitbook 的命令。执行

gitbook -V     （注意：V要大写）

如果在上一步骤GitBook安装成功，命令行中会展示版本信息。至此，恭喜你安装成功。

在这里插入图片描述

    • *

二、避坑指南

1、安装速度问题
  • 问题： 执行 gitbook -V 时显示：Installing GitBook 3.2.3 …….，之后出现长时间卡顿
  • 解决办法1： 科学上网
  • 解决办法2： 切换为使用国内速度较快的淘宝镜像。
    在cmd执行命令：
npm config set registry=http://registry.npm.taobao.org -g
2、Node.js版本问题
  • 问题： GitBook安装或查看版本信息时出现报错，报错信息如下：
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版本之间的切换。主要步骤：
  1. 下载nvm：在github地址：https://github.com/coreybutler/nvm-windows，选择nvm-setup.zip，下载后直接安装。
  2. 配置nvm的环境变量：一些教程中提到安装完nvm后需要手动配置环境变量，但最新版本（我下载的是v1.7.7）的nvm-windows在安装完成之后已经自动配置了环境变量。可以再次确认你的环境变量中是否包含了nvm的路径。
    在这里插入图片描述
  3. 使用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版本
  1. 一个小tip：有时使用 nvm install 命令下载新的Node版本会比较慢，这时可以直接从网址：https://nodejs.org/zh-cn/download/releases/上下载所需版本，并安装到nvm的源文件夹下。
    • *

三、GitBook使用简介

1、GitBook创建及预览
  • 创建书籍：

新建一个文件夹，在文件夹下打开命令窗口（在文件夹地址栏输入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
2、GitBook插件

官方获取插件地址： https://plugins.gitbook.com/

安装插件只需要在书籍目录下增加 book.json 文件，例如增加折叠目录的插件，需要在 book.json 内增加下面代码:

{
    "plugins": ["expandable-chapters-small"],
    "pluginsConfig": {
        "expandable-chapters-small":{}
    }
}

然后终端执行 install 来安装插件即可：

gitbook install
3、GitBook连接GitHub

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介绍及使用

原网址: 访问
创建于: 2021-09-13 15:56:02
目录: default
标签: 无

未标明原创文章均为采集，版权归作者所有，转载无需和我联系，请注明原出处，南摩阿彌陀佛，知识，不只知道，要得到

请先后发表评论
  • 最新评论
  • 总共0条评论