介绍

使用 gitbook 创建 api 文档

安装

要求环境

• NodoJS (推荐 4.0 以上版本)
• Windows，Linux，Unix 或者 Mac OS(X 以上)

通过 NPM 安装

$ (sudo) npm install gitbook-cli -g

如果提示权限不足，加上sudo重新执行上面的命令。

创建文档

$ gitbook init

如果自定义目录创建，可以执行gitbook init ./directory

或者在自己创建好的目录下直接执行初始化命令来创建文档。

然后安装gitbook插件

$ gitbook install

更新

为了方便一键发布，项目集合了express作为静态服务器

在安装gitbook前请先执行express依赖的安装

$ npm install

预览文档

$ gitbook serve

执行上面的命令来预览文档，并且支持实时刷新。

构建发布

$ gitbook build

执行命令后会在根目录下生成_book文件夹，里面是已经编译好的静态 html 文件，可直接发布在服务器上，至于部署方式，可自由选择。

调试

可以使用--log=debug 和--debug选项来显示调试信息。

$ gitbook build ./ --log=debug --debug

目录

.
├── book.json
├── README.md
├── SUMMARY.md
├── api-1/
|   ├── README.md
|   └── something.md
└── api-2/
    ├── README.md
    └── something.md

SUMMARY.md 中列出的所有文档最后都会被转换为 html 文件。

文档结构简单介绍

文件	描述
book.json	文档生成配置 data (可选)
README.md	前言或介绍 (必选)
SUMMARY.md	目录 (参考 Pages) (可选)
GLOSSARY.md	词汇/术语列表（请参阅词汇表)(可选)

如果需要子目录的话，可以这样设置目录

.
├── book.json
└── docs/
    ├── README.md
    └── SUMMARY.md

然后在book.json中添加以下配置:

{
  "root": "./docs"
}

配置文件

使用配置文件 book.json 来自定义文档。

以下是常用设置:

变量	描述
root	除book.json文件之外的文档目录
structure	指定 Readme, Summary, Glossary 的目录
title	标题，默认读取 README 中的
description	描述
author	作者名
isbn	书籍 ISBN
language	本书的语言的ISO code 代码，默认值是en
direction	文本的方向。可以是rtl或ltr，默认值取决于language的值
gitbook	应该使用的 GitBook 版本。使用SemVer规范，例如“> = 3.0.0”

插件

插件及其配置在book.json中指定，详细信息请查看官方文档

3.0.0 版本之后支持自定义主题，该部分同样在官方文档查看

配置好之后需要执行gitbook install 来安装。

生成 eBook 和 PDF 文档

生成的电子书支持 ePub，Mobi，PDF

安装 ebook-convert

# 生成DPF
$ gitbook pdf ./ ./mybook.pdf

# 生成ePub
$ gitbook epub ./ ./mybook.epub

# 生成Mobi
$ gitbook mobi ./ ./mybook.mobi

生成 PDF 的详细配置可以参考

封面

需要插件实现，参考

预览

整体样式

API 页面