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/

?

1 2	jiangys@jiangyoengdeMBP ~ % node -v v18.12.1

 安装GitBook

?

1	$ npm install gitbook-cli -g

 

如果报错，如下：

 

证明npm的版本过低，升级到9.1.2

?

1	sudo npm install -g npm@9.1.2

 npm升级成功

?

1 2	jiangys@jiangyoengdeMBP ~ % npm --version           9.1.2

安装完成之后，你可以使用下面的命令来检验是否安装成功

?

1 2 3

$ gitbook -V CLI version: 2.3.2 GitBook version: 3.2.3

 这一步也可能出错，如：

?

1 2 3 4 5 6 7

/usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287       if (cb) cb.apply(this, arguments)                  ^   TypeError: cb.apply is not a function     at /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18     at FSReqCallback.oncomplete (node:fs:208:5)

 打开polyfills.js文件，注释掉62-64行的代码，这是一个BUG

 

编辑器

可以用 VsCode、Typora 等自己喜欢的来编辑。

先睹为快

GitBook 准备工作做好之后，我们进入一个你要写书的目录，输入如下命令。

?

1 2 3 4

$ gitbook init warn: no summary file in this book info: create README.md info: create SUMMARY.md

 这一步，还会报错，如下：

?

1	TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView. Received an instance of Promise

 

查看报错日记

?

1	gitbook init --debug

解决方案

将\3.2.3\lib\init.js中第71行附近的
return fs.writeFile(filePath, summary.toText(extension));
修改为
return summary.toText(extension).then(stx=>{return fs.writeFile(filePath, stx);});

参考：https://blog.csdn.net/qq_33641175/article/details/122508473

接下来，我们输入 $ gitbook serve 命令，然后在浏览器地址栏中输入 http://localhost:4000便可预览书籍。

?

1	gitbook serve

如下图

输入 http://localhost:4000/

停止服务

如果要停止服务器,只需同时按住CTRL+C即可

 

在主目录下增加book.json文件做定制化配置

目录折叠

?

1	plugins: ["chapter-fold"]

 去掉插件，前面加一个『-』

?

1 2 3

"plugins": [     "-search" ]

页内导航

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

回到顶部

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

GitBook 有如下命令，常用到的有前面6个：

?

1 2 3 4 5 6 7 8 9 10 11 12 13

gitbook init //初始化目录文件 gitbook help //列出gitbook所有的命令 gitbook –help //输出gitbook-cli的帮助信息 gitbook build //生成静态网页 gitbook serve //生成静态网页并运行服务器 gitbook build –gitbook=2.0.1 //生成时指定gitbook的版本, 本地没有会先下载 gitbook ls //列出本地所有的gitbook版本 gitbook ls-remote //列出远程可用的gitbook版本 gitbook fetch 标签/版本号 //安装对应的gitbook版本 gitbook update //更新到gitbook的最新版本 gitbook uninstall 2.0.1 //卸载对应的gitbook版本 gitbook build –log=debug //指定log的级别 gitbook builid –debug //输出错误信息

 

GitHub Pages 快速入门 https://docs.github.com/cn/pages/quickstart