gitbook构建文档系统

简介

GitBook是一个基于node.js的命令行工具，可使用Github/Git和Markdown来制作精美的电子书

使用

假如您已经安装了node，您可以使用npm做以下的操作。

项目中安装gitbook-cli(非全局) 注意：下面使用的npx指令，会自动去./node_modules/.bin目录下面搜索执行指令。如果不使用npx指令，可以使用node_modules\.bin\gitbook build（window系统）这种方式执行gitbook指令

1. 新建文件夹（初始化项目）

npm init

2. 下载gitbook-cli（下面都是在本地安装演示）

npm install gitbook-cli --save--dev
// 或者您也可以全局下载npm install gitbook-cli -g

3. 生成SUMMARY.md

npx gitbook init

4. 可以打开连接直接使用

npx gitbook serve

5. 或者简单的构建，可以放在站点使用

npx gitbook build

以上的步骤，可以搭建起一个最简单版本的系统。如果您需要搭建一个功能更加完善的系统，请跟着下面操作

输出格式

gitbook能将文档生成以下几个格式

1. 静态页面

npx gitbook build

2. eBook: 首先下载ebook-convert创建（有待测试）
   • 生成PDF:
   • 生成ePub:
   • 生成MOBI:
3. JSON

npx gitbook build ./myrepo --format=json

文档格式

一个文档系统中至少包含2个文件：README.md 和 SUMMARY.md。

README.md

用来介绍您的文档的。在初始化的时候，会被自动加到摘要（SUMMARY.md）中

SUMMARY.md

SUMMARY.md是用来定义文档结构的，需要包含章的列表，并且链接到各自的页面。

Example:

# Summary
 
This is the summary of my book.
 
* [section 1](section1/README.md)
    * [example 1](section1/example1.md)
    * [example 2](section1/example2.md)
* [section 2](section2/README.md)
    * [example 1](section2/example1.md)

国际化

GitBook支持构建多语言文档。在项目的根目录中，创建一个LANGS.md文件。注意：每种语言有一个单独的子目录，并且这个目录包含至少README.md和 SUMMARY.md这两个文件。
Example:

* [English](en/)
* [French](fr/)
* [Español](es/)

名词解释

可以在GLOSSARY.md这个文件中定义需要解释的名词，当鼠标移动到这个名词上面，会出现名词解释的信息。 非ascii码会被自动忽略，不会出现名词解释

Example:

# term
Definition for this term
 
# Another term
With it's definition, this can contain bold text and all other kinds of inline markup ...

变量模版

可以把一系列变量定义到book.json中：

{
    "variables": {
        "host": "mybook.com"
    }
}

内容引用

在同一个项目中引用或者引用git仓库中的

{% include "./test.md" %}

{% include "git+https://github.com/GitbookIO/documentation.git/README.md#1.0.1" %}

忽略文件或文件夹

GitBook会读取.gitignore,.bookignore和.ignore中的内容并且忽略他们。最好忽略node_modules和GitBook中构建的文件或者文件夹

node_modules
_book
*.epub
*.mobi
*.pdf