# GitBook-RealityDemo

**Repository Path**: HDMBS/GitBook-RealityDemo

## Basic Information

- **Project Name**: GitBook-RealityDemo
- **Description**: Maven 管理 GitBook 的开箱即用版Demo and 入门到生产级帮助手册
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2019-01-08
- **Last Updated**: 2021-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitBook 的开箱即用版Demo Or 入门到生产级帮助手册

## 1.GitBook 环境搭建

> **GitBook   是一个基于 [Node.js](https://baike.baidu.com/item/Node.js) 的命令行工具，可使用 [Github](https://baike.baidu.com/item/Github)/[Git](https://baike.baidu.com/item/Git/12647237) 和 [Markdown](https://baike.baidu.com/item/Markdown) 来制作精美的电子书，GitBook 并非关于 Git 的教程。**

![只是举例-Max.png](https://images.gitee.com/uploads/images/2019/0203/002735_89e5c69f_1460924.png)


GitBook支持输出多种文档格式：

- **静态站点(H5)：GitBook默认输出该种格式，经过编译后生成的静态页面可直接放到服务器上；**

- **[PDF](https://baike.baidu.com/item/PDF)：需要安装gitbook-pdf依赖；**

- **[eBook](https://baike.baidu.com/item/eBook)：需要安装ebook-convert；**

- **单[HTML](https://baike.baidu.com/item/HTML)网页：支持将内容输出为单页的HTML，不过一般用在将电子书格式转换为PDF或eBook的中间过程；**

- **[JSON](https://baike.baidu.com/item/JSON)：一般用于电子书的调试或元数据提取。**


  <hr>

### 1.1 安装 Node.js

  > 去 [Node.js官网](https://nodejs.org/en/)  下载 msi 版, (我的版本 v8.12.0)直接安装即可(安装msi 软件需关闭安全软件: 360,腾讯管家等)
  >
  >
  >  安装完进入CMD 命令行用 ```node -v``` 检查当前版本号 ;   

### 1.2 安装 使用npm 安装 GitBook组件

> ```npm```是 ```Node.js``` 的默认包管理工具 , 因为是 ```npm源``` 在国外,用npm下载插件时比较慢,推荐 淘宝维护的镜像``` cnpm ```用法是一样的,实时同步 npm源; 
>
> (cnpm安装命令: npm install -g cnpm --registry=https://registry.npm.taobao.org)

```cnpm install -g gitbook-cli
cnpm install -g gitbook-cli  # gitbook 脚手架安装命令  
gitbook -V            		 # 查看版本命令,校验是否安装成功
CLI version: 2.3.2
GitBook version: 3.2.3
```

## 2.如何创建一个GitBook HTML手册 ?

### 2.1 使用GitBook init 初始化

![init](https://images.gitee.com/uploads/images/2020/1217/095243_fd9c490b_1460924.png "")                                         

### 2.2 生成的两个文件：*README.md*和SUMMARY.md 

![两个文件](https://images.gitee.com/uploads/images/2020/1217/095456_131257ca_1460924.png "屏幕截图.png")

> **编译```gitbook build```后锚点树效果图** 

![Tree.png](https://images.gitee.com/uploads/images/2019/0203/002734_fccce086_1460924.png)

### 2.3 GitBook help 查看要使用什么命令 

![gitbook help.png](https://images.gitee.com/uploads/images/2019/0203/002734_36d48655_1460924.png)


### 2.4 GitBook install 根据 book.json 加载依赖插件  

![book_json.png](https://images.gitee.com/uploads/images/2019/0203/002734_a406ff82_1460924.png)

> **```gitbook install``` 加载book.json上的依赖插件**

![gitbook install.png](https://images.gitee.com/uploads/images/2019/0203/002734_1737d764_1460924.png)

### 2.5 GitBook build 根据 SUMMARY.md  编辑.md生成静态页面

![![Gitbook build.png](https://images.gitee.com/uploads/images/2019/0203/002734_71119cbf_1460924.png)


### 2.6 GitBook serve 运行静态网页 

![gitbook serve.png](https://images.gitee.com/uploads/images/2019/0203/002735_e762f435_1460924.png)

> ```http://localhost:4000``` **查看最终效果**

![run.png](https://images.gitee.com/uploads/images/2019/0203/002735_b138142b_1460924.png)

## 3.如何维护 GitBook-RealityDemo 帮助手册 (请先完成第一章的环境搭建) ?

### 3.1 将 项目中依赖的 node-npm 库解压并删除原7z包 (为了开箱即用考虑 ,跳过了 ```gitbook install``` 加载插件环节)

![nodenpm.png](https://images.gitee.com/uploads/images/2019/0203/002735_2683e666_1460924.png)

### 3.2 使用AntRun 重写 Maven生命周期 

![AntRun.png](https://images.gitee.com/uploads/images/2019/0203/002735_5dc8ad38_1460924.png)

### 3.3. 修改GitBook 中的.md文件 可用被重写后的mvn 命令来进行编译打包

### (编译完成后用tomcat运行即可,切记当前只重写 package和clean 命令)

> **``` mvn package```: 即在将 webapp\doc 目录删除**

![mvn_clean.png](https://images.gitee.com/uploads/images/2019/0203/002735_5367ce07_1460924.png)

**```mvn package```: 即在cmd命令行进入 node目录 ```gitbook build``` 后将 _book 目录拷贝到 webapp\doc 并过滤所有的 *.md (如果改变了一些md文件就```mvn package```重新编译后运行)**

![mvn_package.png](https://images.gitee.com/uploads/images/2019/0203/002735_499c24c8_1460924.png)

### 3.4. 配置Web容器运行 War包 (项目中 target 下已有 War可直接运行)

![war.png](https://images.gitee.com/uploads/images/2019/0203/002735_5c56d078_1460924.png)
### 3.5. 注意事项 (node_modes, _book , .idea 请不要提交SVN)

![ignore.png](https://images.gitee.com/uploads/images/2019/0203/002735_3284928d_1460924.png)

## 4.GitBook 帮助手册使用的插件 (book.json 文件)

```
{
  "title": "某米帮助手册",
  "description": "某米帮助手册",
  "language": "zh-hans",
  "plugins": [
    "-highlight",				# 移除高亮插件
    "-sharing",					# 移除社交分享插件
    "-search",					# 移除原生搜索插件
    "-lunr",					# 移除搜索后端
    "expandable-chapters-small",# 添加标题折叠插件 
    "search-pro",				# 添加pro-中英文站内搜索插件
    "prism",					# 添加代码样式风格插件
    "splitter",					# 添加使侧边栏的宽度可以自由调节插件
    "fontsettings",				# 添加调节默认字体插件
    "navigator"					# 添加锚点插件
  ],
  "styles": {
    "website": "stylehttps://upload-images.jianshu.io/upload_images/9600360-e99c88e7debf2831.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240   "size": 14
    },
    "search-pro": {				# 中英文站内搜索插件配置
      "cutWordLib": "nodejieba",
      "defineWord": [
        "Gitbook Use"
      ]
    },
    "expandable-chapters-small": {} # 标题折叠插件配置(可为空) 
  },
  "pdf": {
  "pageNumbers": false,
  "fontFamily": "Arial",
  "fontSize": 12,
  "paperSize": "a4",
  "margin": {
    "right": 62,
    "left": 62,
    "top": 56,
    "bottom": 56
  }
 }
}
```
### 4.1 GitBook转PDF参考   
> **输出为PDF等其他格式  
  到http://calibre-ebook.com/download下载calibre，安装版和便携版都可以。
  解压或者安装 calibre，在安装/解压目录中找到包含ebook-convert.exe的文件夹，将此文件夹添加到PATH变量中
  运行如下命令生成pdf 或者epub 文件**
  
> **cmd 命令行 切到GitBook根目录执行  ```gitbook pdf```**
 

### 4.2 当前book.json集成后最终效果 


![Max.png](https://images.gitee.com/uploads/images/2019/0203/002735_89e5c69f_1460924.png)