测试开发技术网站

[TOC]

# 一、安装 Nodejs
若要在 Windows 10 系统即本地使用 Gitbook，需要安装 gitlab-cli 工具，而 gitbook-cli 工具是基于 Nodejs的，因此首先需要安装 Nodejs

如果是初学者，可以参考 [Nodejs----基于 Windows 10 系统安装 Nodejs](http://devops-dev.com/article/387) 安装 Nodejs，这里需要注意，本文验证过安装 16.20.1 版本的 Nodejs是可以的，因此这里建议也安装 16.20.1 版本，不要安装更高的版本，如果手头上涉及多个前端项目，那么本文这里还是直接推荐参考 [nvm----在 Windows10 系统同时安装管理多个Nodejs版本并能进行灵活便捷的切换工具](http://devops-dev.com/article/527) 通过安装nvm，从而可以在 Windows 系统上安装多个 Nodejs 版本，这样在后续项目开发中可以做到灵活切换 Nodejs 的版本。本文就以 nvm 工具的方式演示

# 二、安装 Gitbook
（1）首先通过 nvm 查看本地已经安装了的 Nodejs 的版本，如下，这里已经安装了三个版本
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/8232542e-9c23-11ee-8383-0242ac110004.png)

（2）因此这里可以通过 nvm use 16.20.1 命令切换 Nodejs 的版本，切换完成后，再次查看，如下确认 Nodejs 版本已经切换到 16.20.1 版本了。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/069baf90-9c28-11ee-8383-0242ac110004.png)

（3）然后即可开始安装 gitbook-cli 包了，执行如下命令
```bash
npm install gitbook-cli -g
```

（4） 然后执行如下命令查看 gitbook-cli 的版本号并安装 gitbook
```bash
gitbook -V
```

（5） 此时有可能会出现如下错误，如果没有出现则直接跳过本步骤，如果出现了如下错误，则需要去解决一下。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/20e40b5e-9c28-11ee-8383-0242ac110004.png)

根据这里的报错提示，去打开 D:\ProgrameFile\nvm\v16.20.1\global\node_modules\gitbook-cli\node_modules\npm\node_modules\graceful-fs\polyfills.js 文件，找到287行代码，可以看出如果有调用 statFix 函数则会触发这个问题。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/18a9f456-9c25-11ee-8383-0242ac110004.png)

在这个文件中搜索 staFix 函数调用的位置，如下所示，只有如下三行在调用
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/68d3a1d4-9c25-11ee-8383-0242ac110004.png)

这里也在网上查询了一些资料，发现好多人遇到过此问题，而且反馈只需要将此三行注释掉即可，因此这里我们同样也将此三行代码注释掉，如下图所示。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/a0f09df6-9c25-11ee-8383-0242ac110004.png)

然后保存，再此执行 gitbook -V 命令，如下图所示，可以看到已经安装成功了。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/484b73d0-9c28-11ee-8383-0242ac110004.png)

# 三、gitbook 的使用方法
（1）这里就以 https://github.com/redrose2100/docs 代码仓为例展示了，将此 docs 项目下载到本地后，比如想写一本关于 Linux 的电子书，这里在 docs 项目中新建一个文件夹 linux，用于存放即将编写的电子书。目录结构如下所示：
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/71d1a61a-9c29-11ee-8383-0242ac110004.png)

（2）在cmd窗口中进入到 linux 的文件夹，然后执行 gitbook init 命令，这里又遇到了如下所示的错误。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/d3921c40-9c29-11ee-8383-0242ac110004.png)

此时需要找到文件 C:\Users\Administrator\.gitbook\versions\3.2.3\lib\init.js，然后将 72 行注释掉，然后修改为 73行的代码
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/b12c606a-9c2a-11ee-8383-0242ac110004.png)
即将
```bash
return fs.writeFile(filePath, summary.toText(extension));
```
修改为：
```bash
return summary.toText(extension).then(stx=>{return fs.writeFile(filePath, stx);});
```
保存后，重新执行 gitbook init 命令，此时可以看到可以执行成功了。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/f301e686-9c2a-11ee-8383-0242ac110004.png)

（3）此时会新生成两个文件 README.md 和 SUMMARY.md，目录结构如下图所示：
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/2e29bbee-9c2b-11ee-8383-0242ac110004.png)

（4）此时暂时先不做任何修改，然后直接执行 gitbook serve 命令启动服务，如下图所示：
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/f52ccc2c-9c2b-11ee-8383-0242ac110004.png)

（5）根据提示然后在浏览器中打开 http://localhost:4000/ ，即可打开电子书的页面了，如下图所示：
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/3fe8a2f4-9c2c-11ee-8383-0242ac110004.png)

# 四、设计电子书的目录结构
首先需要规划一下电子书的目录结构，比如我们想写一本关于Linux的电子书，然后大概设计如下目录：
```bash
第一章 Linux 概述
   1.1 Linux 简介
   1.2 Linux 特点
   1.3 Linux 的发展历史
第二章 Linux 常用命令
   2.1 用户与权限管理命令
   2.2 文件管理命令
   2.3 磁盘管理命令
第三章 shell 编程
   3.1 条件语句
   3.2 循环语句
   3.3 shell 编程实例
```
（1）首先在 linux 文件下创建三个文件夹，比如 ch01、ch02、ch03，用于存放三章内容，然后在每一个创建的子文件夹中继续创建md文件，比如 ch01/1_1.md, ch01/1_2.md, ch01/1_3.md, ch02/2_1.md, ch02/2_2.md, ch02/2_3.md, ch03/3_1.md, ch03/3_2.md, ch03/3_3.md, 此时的文件目录结构如下图所示：
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/ef29e820-9c2e-11ee-8383-0242ac110004.png)

（2）linux/README.md 文档可以理解为电子书的前言，而 SUMMARY.md 则是目录文件，这里比如先将 README.md 文档内容修改为如下内容：
```bash
# 前言

这是一本关于 Linux 的技术实战类型的书籍
```

（3）然后重点就是写 SUMMARY.md 文档，即编写目录了，这里根据电子书籍规划目录，可以编写 SUMMARY.md 文件的内容如下：
```bash
# 目录

* [前言](README.md)

* [第一章 Linux 概述]()
   * [1.1 Linux 简介](ch01/1_1.md)
   * [1.2 Linux 特点](ch01/1_2.md)
   * [1.3 Linux 的发展历史](ch01/1_3.md)
* [第二章 Linux 常用命令]()
   * [2.1 用户与权限管理命令](ch02/2_1.md)
   * [2.2 文件管理命令](ch02/2_2.md)
   * [2.3 磁盘管理命令](ch02/2_3.md)
* [第三章 Linux shell 编程]()
   * [3.1 条件语句](ch03/3_1.md)
   * [3.2 循环语句](ch03/3_2.md)
   * [3.3 shell 编程实例](ch03/3_3.md)
```

（4）将 gitbook serve 命令停止，然后重新执行 gitbook serve 命令，然后再根据提示打开 http://localhost:4000/ ，结果如下图所示，可以看出，此时已经和我们心中想象的电子书的格式差不多了。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/9fb02226-9c30-11ee-8383-0242ac110004.png)

# 五、设置 gitbook 常用配置
（1）在linux 文件夹即与 SUMMARY.md 同一目录下创建 book.json 文件，文件内容如下所示：
```json
{
    "title": "Linux 从入门到精通",
    "author": "redrose2100",
    "description": "Linux 从入门到精通",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "links": {
        "sidebar": {
            "GitHub": "https://github.com/redrose2100/docs"
        }
    }
}
```
其中：
* title：书名
* author：作者
* description： 简要描述
* language： 语言，这里使用 zh-hans 可以将页面切换为中文
* gitbook： gitbook 的版本号，在安装的时候可以看到
* links.sidebar： 可以设置连接，比如设置github链接调转到 docs 代码仓库地址

（2）再一次重新执行 gitbook serve 命令，然后重新打开 http://localhost:4000/ ，如下图所示，此时页面上原本英文的全部切换为中文了，而且在左侧还增加了一个 Github 链接，点击后是可以跳转到 github 上 docs 代码仓的。
![](https://redrose2100.oss-cn-hangzhou.aliyuncs.com/img/56bb18f8-9c32-11ee-8383-0242ac110004.png)

至此，在Windows上就将gitbook成功的运行起来了，当然为了能够编写出更加丰富多彩的电子书，后续还有许多功能比如常用的插件、比如屏蔽不必要的信息等，都需要继续进一步去优化，后续优化将在其他文章中继续详细展开，这里就暂时不在展开了。

测试开发技术网站

博客