由于当前项目建设需要写用户使用手册,在网上搜索了很多工具,有gitbook,有docsify,还有阿里的,个人觉得还是使用gitbook作为教程制作工具比较合适,不喜勿喷。
网上有很多类似的教程,但都多少会遇到些问题。现把我搭建gitbook开发环境的教程奉上,自己认为相对比较全面,可避免搭建过程中遇到的一些坑。
gitbook开发环境基于nvm+nodejs+vscode搭建,系统为win10家庭版。
1:安装nvm
nvm是nodejs的版本管理器,由于搭建环境中出现的各种问题,需要使用不同版本的nodejs,因此选择使用nvm作为版本管理器,需要时可以随时切换nodejs版本。
nvm下载地址:https://github.com/coreybutler/nvm-windows/releases,下载最新版即可。
注意事项:安装路径中不能有中文或者空格,即不能安装在Program Files这个文件夹下,否则使用过程中会报如下错误:
我个人安装文件夹为D:\ProgramFiles\nvm
安装过程中需要指定nodejs的下载路径,个人指定为:D:\ProgramFiles\nodejs,一路确定完成安装。
安装完成后系统环境变量path后面会增加两个值,与nvm相关,如下图所示:
此时以管理员身份打开cmd窗口,输入nvm -v,出现如下界面说明安装正常。
2:安装nodejs
安装nodejs之前需切换淘宝镜像,nvm默认链接的是官方镜像,很有可能下载失败。
在之前的cmd窗口依次输入如下命令,回车即可
nvm node_mirror https://npm.taobao.org/mirrors/node/
nvm npm_mirror https://npm.taobao.org/mirrors/npm/
之后便可以安装nodejs,选择安装版本10.14.1。注意不能安装最新版,否则后续gitbook在初始化时会报js文件的错误。
在之前的cmd窗口输入:
nvm install 10.14.1
自动下载安装nodejs以及npm。
安装完成后在cmd窗口输入
nvm list
可查看当前安装的nodejs版本。
继续输入:
nvm use 10.14.1
可使用10.14.1版本。输入node -v 以及npm -v检查相应的环境变量是否正常工作。
ps1:某些情况下输入nvm use之后会出现node不是内部或者外部命令的问题,此时如果环境变量正常的话,可按照安装nvm之后node不可用,“node”不是内部或外部命令,也不是可运行的程序或批处理文件(ng) - cencenyue - 博客园这里的方式解决问题。
ps2:使用成功的版本号之前会有一个 * 号。
3: 安装gitbook
安装gitbook之前首先得配置下npm的有关路径。npm是window下的包管理器。
首先新建两个目录:D:\ProgramFiles\nodejs\node_global
D:\ProgramFiles\nodejs\node_cache
依次在cmd窗口输入以下命令:
npm config set prefix "D:\ProgramFiles\nodejs\node_global" //设置全局包目录
npm config set cache "D:\ProgramFiles\nodejs\node_cache" //设置缓存目录
路径配置完毕之后,需把这两个路径添加到系统path路径里面。
在系统变量里面新建变量:NODEJS_PATH,值填入D:\ProgramsFiles\nodejs
点击确定保存,然后选择path变量,点击编辑,增加两项内容,然后保存
在cmd窗口输入:
npm install -g gitbook-cli
即可安装gitbook开发工具。
至此,gitbook基础开发工具安装完毕。
4、利用vscode编辑gitbook书籍
gitbook是基于MarkDown语法的开发工具。
打开vscode,新建文件夹UserManual,路径和名字随个人喜好指定。
在vscode中打开新终端,输入gitbook init,如图所示:、
则会在当前目录下生成,会初始化开发环境,自动生成README.md和SUMMARY.md。
然后输入gitbook install,自动安装开发所需默认功能插件
关于gitbook的相关教程可参考:GitBook 使用教程 - 简书
书籍的编写可使用Markdown的语法去编辑。
想要使书籍比较美观和功能多样化,通过book.json文件配置gitbook插件。
book.json文件不会自动生成,自己在根目录下新建一个就行。
保存配置文件,并在终端窗口输入gitbook install来安装指定插件。
gitbook插件使用教程可参考:GitBook插件整理 - 简书
个人book.json文件配置:
{
"title": "用户手册",
"author": "XHK",
"description": "简介及相关教程",
"language": "zh-hans",
"gitbook": "3.2.3",
"links": {
"sidebar": {
"官网": "https://****"
}
},
"plugins": [
"-lunr",
"-search",
"-highlight",
"-livereload",
"-sharing",
"search-pro",
"code",
"github",
"prism",
"prism-themes",
"advanced-emoji",
"splitter",
"tbfed-pagefooter",
"expandable-chapters",
"favicon",
"anchor-navigation-ex",
"back-to-top-button",
"chapter-fold",
"toggle-chapters",
"insert-logo",
"flexible-alerts"
],
"styles": {
"website": "styles/website.css"
},
"pluginsConfig": {
"theme-default": {
"showLevel": false
},
"github": {
"url": "https://gitee.com/hpcproject/hpczn-usermanual.git"
},
"chapter-fold":{},
"toggle-chapters":{},
"search-pro": {
"cutWordLib": "nodejieba",
"defineWord": ["Gitbook Use"]
},
"prism": {
"css": [
"prism-themes/themes/prism-atom-dark.css"
]
},
"insert-logo": {
"url": "hpc.jpg",
"style": "background: none; max-height: 60px; min-height: 60px;max-width: 250px",
"title": "高性能计算平台"
},
"tbfed-pagefooter": {
"copyright": "Copyright &Central South University 2021",
"modify_label": "文件修订时间:",
"modify_format": "YYYY-MM-DD HH:mm:ss"
},
"favicon": {
"shortcut": "favicon.ico",
"bookmark": "favicon.ico"
},
"anchor-navigation-ex": {
"associatedWithSummary": false,
"showLevel": false,
"multipleH1": true,
"mode": "float",
"pageTop": {
"showLevelIcon": false,
"level1Icon": "fa fa-hand-o-right",
"level2Icon": "fa fa-hand-o-right",
"level3Icon": "fa fa-hand-o-right"
}
}
}
}
值得注意的是,plugin字段里面的内容有先后顺序的,比如code插件必须放在prism之前,否则会导致prism-theme的主题样式无效。
更多的问题欢迎大家在文章下方讨论。