目前 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 即可安装。
也可以指定要安装插件的版本 "myPlugin@0.3.1" 。
常用的插件有：
-
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 插件。
网友评论