1 安装Nodejs和npm
Nodejs安装方法点本链接
Nodejs选择版本:14.0.0(高版本实测有bug)
正常在安装完Nodejs之后,npm也会被安装上一个版本,参考链接
npm版本选择:6.14.4
2 全局安装Gitbook 3.2.3
2.1安装gitbook-cli
输入命令,全局安装gitbook。
npm install gitbook-cli -g
2.2 初始化目录文件
直接在需要本地部署的文件夹地址栏输入cmd回车,进入命令提示符界面
在当前文件目录下的在窗口中输入如下命令
gitbook init
//初始化目录文件
初始化之后创建SUMMARY.md文件,如果存在该文件,如果有不符合gitbook格式的内容,会将其修正并覆盖。
2.3 加载依赖
在线文档需要匹配对应的依赖文件才能更好的显示在网页上,目前我需要的依赖项在book.json文件中的代码如下:
"language": "zh-hans",
"gitbook": "3.2.3",
"plugins": [
"-sharing",
"search-pro",
"ancre-navigation",
"copy-code-button",
"splitter",
"expandable-chapters",
"mermaid-gb3",
"insert-logo",
"mathjax-pro"
],
其中 mathjax-pro
这个依赖是一个坑,后面讲解如何安装它,无法正常安装,这里我们先把它删掉,将book.json这部分改为:
"language": "zh-hans",
"gitbook": "3.2.3",
"plugins": [
"-sharing",
"search-pro",
"ancre-navigation",
"copy-code-button",
"splitter",
"expandable-chapters",
"mermaid-gb3",
"insert-logo"
],
输入指令:gitbook install
完成各依赖库的安装,我们回过头来安装mathjax
,这里我们直接使用npm安装,指定版本
在生成pdf或者生成网页时,mathjax会报错,一般出现在新安装mathjax或者更新mathjax后,解决办法为,为mathjax降级,安装 2.7.6版本,输入指令:
npm install mathjax@2.7.6
不用在意警告内容,都可以使用的。
但此时运行 gitbook serve
依旧会有报错,后发现原来是之前安装的依赖都不在目标文件夹的node_modules文件夹内造成的。
到这里,我在目标文件夹内cmd打开终端,输入npm install gitbook-cli
,在当前目录中安装gitbook。
然后再执行一次gitbook install
,将依赖库安装到这个目录内。(此处避坑)
3 在线文档服务开启
打开目标文件夹的终端,输入指令:gitbook serve
当提示如下图所示,就可以进行访问了,访问地址:127.0.0.1:4000,在网页上输入该地址就可以访问了。
4 问题处理
4.1 gitbook init报错
错误类型:TypeError [ERR_INVALID_ARG_TYPE]
执行gitbook init
报错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.
将C:\Users\Administrator.gitbook\versions\3.2.3\lib\init.js(我的安装路径是这个)中第72行附近的
return fs.writeFile(filePath, summary.toText(extension));
修改为
return summary.toText(extension).then(stx=>{return fs.writeFile(filePath, stx);})
2.将D:\Program Files\nodejs\node_global\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js文件中62行附近的代码注释掉。
//fs.stat = statFix(fs.stat)
//fs.fstat = statFix(fs.fstat)
//fs.lstat = statFix(fs.lstat)
3.C:\用户\自己的用户名.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js
所有【confirm: true】替换为【confirm: false】