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/

jiangys@jiangyoengdeMBP ~ % node -v
v18.12.1

 安装GitBook

$ npm install gitbook-cli -g

 

如果报错，如下：

 

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

sudo npm install -g npm@9.1.2

 npm升级成功

jiangys@jiangyoengdeMBP ~ % npm --version           
9.1.2

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

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

 这一步也可能出错，如：

/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 准备工作做好之后，我们进入一个你要写书的目录，输入如下命令。

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

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

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

 

查看报错日记

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便可预览书籍。

gitbook serve

如下图

输入 http://localhost:4000/

停止服务

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

 

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

目录折叠

plugins: ["chapter-fold"]

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

"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个：

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