2.3.1. 创建及使用
Gitbook 的基本用法非常简单，基本上就只有两步：
- 使用 gitbook init 初始化书籍目录
- 使用 gitbook serve 编译預覽书籍
2.3.1.1. 创建书籍
mkdir book
cd book
gitbook init
#輸出
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
使用tree命令查看目录树
tree
#輸出
.
├── README.md
└── SUMMARY.md
README.md 及 SUMMARY.md 是两个必要文件
2.3.1.2. 格式
GitBook 约定了下面这些文件的作用：
- README：书本的介绍
- SUMMARY：章节结构
- LANGS：多语言书籍
- GLOSSARY：术语描述的清单
至少需要一个 README 和 SUMMARY 文件来构建一本书。
2.3.1.3. 自述和介绍
书本的第一页内容是从文件 README.md 中提取的。如果这个文件名没有出现在 SUMMARY 中，那么它会被添加为章节的第一个条目。
使用其他文件替代README.md
一些托管在 GitBook 上的书更加喜欢将 README.md 文件作为项目的介绍而不是书的介绍。
可以在 book.json 中定义某个文件作为 README 。
2.3.1.4. 章节设置
通过 SUMMARY.md 定义目录结构，通过 gitbook init 自动生成目录结构对应的文件夹和 Markdown 文件。也可以先创建好章节目录及文件，再回来编辑目录。
目录示例
#Summary
* [第一章](chapter1.md)
* [第二章](chapter2.md)
* [第三章](chapter3.md)
多层结构目录示例
#Summary
* [第一章](section1/README.md)
* [第一节](section1/example1.md)
* [第二节](section1/example2.md)
* [第二章](section2/README.md)
* [第一节](section2/example1.md)
使用标题或水平分割线将目录分成几个部分
# Summary
### Part I
* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)
### Part II
* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)
----
* [Last part without title](part3/title.md)
2.3.1.5. 多语言
GitBook 支持多种语言编写图书。每种语言必须是一个子目录，子目录结构与 GitBook 结构相同（拥有各自的 README.md 、 SUMMARY.md 以及实际内容文件）， LANGS.md 在外层父目录（书籍项目根目录），其内容格式如下：
LANGS.md
* [English](en/)
* [zh-hans](zh-hans/)
* [zh-tw](zh-tw/)
示例：Learn Git
2.3.1.6. 忽略目录和文件
GitBook 会读取 .gitignore,.bookignore 以及 .ignore 这三个档案，根据里面的内容，忽略特定的文件或子目录。（格式为一行一个文件或目录。）
.gitignore
# 忽略 test.md 文件
test.md
# 忽略 "bin" 目录下所有文件
bin/*
2.3.1.7. 术语表
在术语表中指定要显示的术语和其各自的定义。基于这些条件 gitbook 会自动建立索引，并在内容页面中高亮显示这些术语。注意不支持中文术语
GLOSSARY.md
# git
是一个分布式版本控制软件，最初由林纳斯·托瓦兹创作，于2005年以GPL发布。最初目的是为更好地管理Linux内核开发而设计。应注意的是，这与GNU Interactive Tools 一个类似Norton Commander界面的文件管理器）不同。
# GitHub
GitHub是通过Git进行版本控制的软件源代码托管服务平台，由GitHub公司（曾称Logical Awesome）的开发者Chris Wanstrath、PJ Hyett和Tom Preston-Werner使用Ruby on Rails编写而成。
2.3.1.8. 封面
cover.jpg 和 cover_small.jpg缩略图
最佳尺寸
| 大 | 缩略图 | |
|---|---|---|
| 文件 | cover.jpg |
cover_small.jpg |
| 大小 | 1800x2360 | 200x262 |
插件 autocover 同样可以实现，参照 https://github.com/GitbookIO/plugin-autocover
2.3.1.9. 模板 待添加
注意与配置中 variables 有关
2.3.1.10. 内容引用
内容参考 (conref) 是便于用来重复使用其他文件和书本内容。
导入本地文件
使用 include 标签导入其他文件的内容真的很简单：
{% include "./test.md" %}
从其他书本导入文件
GitBook 同样能处理使用了git协议的include路径：
{% include "git+https://github.com/GitbookIO/documentation.git/README.md#0.0.1" %}
git的url格式是：
git+https://[email protected]/project/blah.git/file#commit-ish
真实的git url应该以 .git 结尾，导入的文件名从 .git 之后的 url 片段提取。
commit-ish 可以是任何可以作为 git checkout 参数的标签，sha，或分支。默认是 master。
继承
模板继承是一种重复使用模板的简单方式。当写完一个模板，你可以定义 "block" 让字模板来替换。继承链可以任意长。
block 在模板中定义了一个区域并用一个名字标识了它。基类模板可以指定一些块，而子类可以用新的内容替换它们。
{% extends "./mypage.md" %}
{% block pageContent %}
# This is my page content
{% endblock %}
在文件 mypage.md 中，你应该指定用来替换内容的块。
{% block pageContent %}
This is the default content
{% endblock %}
# License
{% import "./LICENSE" %}
2.3.1.11. gitbook指令集
gitbook help 指令查看所有指令集，如下
build [book] [output] build a book
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
--format Format to build to (Default is website; Values are website, json, ebook)
--[no-]timing Print timing debug information (Default is false)
serve [book] [output] serve the book as a website for testing
--port Port for server to listen on (Default is 4000)
--lrport Port for livereload server to listen on (Default is 35729)
--[no-]watch Enable file watcher and live reloading (Default is true)
--[no-]live Enable live reloading (Default is true)
--[no-]open Enable opening book in browser (Default is false)
--browser Specify browser for opening book (Default is )
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
--format Format to build to (Default is website; Values are website, json, ebook)
install [book] install all plugins dependencies
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
parse [book] parse and print debug information about a book
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
init [book] setup and create files for chapters
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
pdf [book] [output] build a book into an ebook file
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
epub [book] [output] build a book into an ebook file
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
mobi [book] [output] build a book into an ebook file
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)