基于nvm+nodejs+vscode搭建gitbook开发环境

    由于当前项目建设需要写用户使用手册，在网上搜索了很多工具，有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的主题样式无效。

更多的问题欢迎大家在文章下方讨论。