GitBook 使用教程

背景

生成接口文档

GitBook 简介

• GitBook 官网
• GitBook 文档

GitBook 准备工作

安装 Node.js

GitBook 是一个基于 Node.js 的命令行工具，下载安装 Node.js，安使用下面的命令来检验是否安装成功。

$ node -v
v11.6.0

mac 安装yum install node.js

安装 GitBook

输入下面的命令来安装 GitBook。

$ npm install gitbook-cli -g

安装完成之后，你可以使用下面的命令来检验是否安装成功。

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

更多详情请参照 GitBook 安装文档 来安装 GitBook。

安装 GitBook 编辑器

去 GitBook 官网 下载 GitBook 编辑器；

使用

进入一个要写文档的目录

$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

可以看到会创建 README.md 和 SUMMARY.md 这两个文件，README.md 是说明文档， SUMMARY.md 是书的章节目录，其默认内容如下所示：

# Summary

* [Introduction](README.md)

输入 $ gitbook serve 命令，然后在浏览器地址栏中输入 http://localhost:4000 便可预览。

效果如图：

image.png

运行该命令后会在生成一个 _book 文件夹, 里面的内容即为生成的 html 文件，可以使用下面命令来生成网页而不开启服务器。

gitbook build

目录结构

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter1/
|   ├── README.md

book.json

该文件主要用来存放配置信息，我先放出我的配置文件。

{
  "title": "API对接文档",
  "description": "API对接文档",
  "plugins": [
    "image-captions",
    "splitter",
    "expandable-chapters-small",
    "-mathjax",
    "-lunr",
    "-search",
    "search-pro",
    "localized-footer"
  ],
  "pluginsConfig": {
    "theme-default": {
      "showLevel": true
    },
    "image-captions": {
      "caption": "Image - _CAPTION_",
      "align": "center"
    },
    "expandable-chapters-small": {},
    "fontSettings": {
      "theme": "white",
      "family": "serif",
      "size": 2
    },
    "search-pro": {
      "cutWordLib": "nodejieba"
    },
    "localized-footer": {
      "hline": true,
      "filename": "./FOOTER.md"
    }
  }
}

编写完成后在book.json文件目录执行如下命令安装插件
gitbook install

SUMMARY.md

GitBook 的章节目录，通过 Markdown 中的列表语法来表示文件的父子关系，下面是一个简单的示例：

# Summary

* [文档历史](history/README.md)

* [测试工具](tools/README.md)

* [鉴权](auth/README.md)
    * [获取token](auth/token.md)
    * [参数签名](auth/sign.md)
    * [签名&令牌传递](auth/tokenTrans.md)

* [业务接口](apis/README.md)
    * [获取配置](apis/config.md)
    * [获取订单ID](apis/get_id.md)
    * [下单](apis/request_ride.md)
    * [订单查询](apis/ride_detail.md)
    * [取消订单](apis/ride_cancel.md)

README.md

主页，可以在book.json中修改

.gitignore

配置.gitignore

$ cat .gitignore 
.gradle
/build/
!gradle/wrapper/gradle-wrapper.jar
gradle/
gradlew*
.DS_Store

### STS ###
.apt_generated
.classpath
.factorypath
.project
.settings
.springBeans

### IntelliJ IDEA ###
.idea
*.iws
*.iml
*.ipr

### NetBeans ###
nbproject/private/
build/
nbbuild/
dist/
nbdist/
.nb-gradle/