gitbook

目前 gitbook 提供三类文档: Book 文档,API 文档和 FAQ 文档。

gitbook 生成电子书主要有三种方式:

• gitbook-cli 命令行操作，适合技术人员
• gitbook-editor 编辑器操作，可视化编辑
• gitbook.com 官网操作，在线编辑实时发布

基本使用

安装

npm install gitbook-cli -g

常用命令

• gitbook init 初始化 README.md 和 SUMMARY.md 两个文件.

• gitbook build 本地构建但不运行服务,默认输出到 _book/ 目录.

• gitbook serve 本地构建并运行服务,默认访问 http://localhost:4000 实时预览.

目录结构

常见目录结构

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

独立目录结构

如果希望将文档放到其他目录（比如./docs目录下），目录结构如下：

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

同时需要在 book.json 中配置 root ：

{
    "root": "./docs"
}

文件说明

File	Description
book.json	Stores configuration data (optional)
README.md	Preface / Introduction for your book (required)
SUMMARY.md	Table of Contents (See Pages) (optional)
GLOSSARY.md	Lexicon / List of terms to annotate (See Glossary) (optional)

SUMMARY.md

SUMMARY.md 文件用于指定book的目录结构，并且没有在SUMMARY.md文件中列出的文件都会被当作静态文件。

所有的静态文件，只要不是在 .gitignore, .bookignore 和 .ignore 文件中指定忽略的文件，都会被拷贝到输出目录 _book 中。

示例及说明：

# Summary

### Part I

* [Part I](part1/README.md)
    * [Writing is nice](part1/README.md#writing)
    * [GitBook is nice](part1/README.md#gitbook)

### Part II

* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

----

* [Last part without title](part3/title.md)

示例说明：

• ### Part I 、### Part II 代表分组名称
• ---- 用于匿名的分组
• 以 * 开头的必须符合 [标题](链接) 的格式，用于定义book的目录结构
• 缩紧的 * 表示目录结构的层级

md文件

在页面markdown文件中，可以使用Front Matter 定义变量，在Front Matter中定义的变量会被加入到页面变量中，并可以在template中使用。

示例：

---
description: This is a short description of my page
---

# The content of my page
...

配置

详细的配置参考 https://github.com/GitbookIO/gitbook/blob/master/docs/config.md

高阶使用

官方文档

git clone https://github.com/GitbookIO/gitbook.git
cd gitbook/docs
gitbook init
gitbook serve

然后浏览器打开 http://localhost:4000 就可以查看最新的文档。

插件

当发现需要的插件时，在根目录的 book.json 文件中添加插件：

{
        "plugins": ["myPlugin", "anotherPlugin"]
}

然后执行 gitbook install 即可安装。

也可以指定要安装插件的版本 "[email protected]" 。

常用的插件有：

• mermaid-gb3 支持使用 mermaid 编写graph

主题

3.0.0版本之后，系统默认的主题是 theme-default 。你也可以模仿这个项目开发自己的主题。

当发现需要的主题时，也可以像安装插件一样进行安装，比如安装 theme-comscore 主题，只需在 book.json 文件中添加：

{
        "plugins": ["theme-comscore", "mermaid-gb3"]
}

然后执行 gitbook install 即可。

default 默认主题是黑白的,而 comscore 主题是彩色的,即标题和正文颜色有所区分.

开发

最佳实践

将文档放到独立的目录 .docs ，不同分类的文档放到不同的目录下，图片文件放到与md同级目录的 img 目录下。

只所以使用独立的 ./docs 目录，是希望将文档和配置文件分离，文档也可以通过单独的git库来管理，以后如果希望采用除 gitbook 外的其他如 hugo 、hexo、gatsby 等工具，可以直接引用独立的文档库。

启用 mermaid-gb3 插件。

参考

• 官方文档
• gitbook使用文档 重点推荐
• 使用 Gitbook 打造你的电子书
• GitBook插件整理
• gitbook 入门教程之使用 gitbook-cli 开发电子书 推荐
• gitbook 学习笔记 & 自用模板