说在前面:

gitbook官网本身被墙虽然问题不大, 但是其在线编辑器极其恶心, 现在已经不推荐使用GitBook这款工具了.

1. 安装:

1.1 环境要求:

• NodeJS (v4.0.0 and above is recommended):Node.js版本需要为4.0.0以上
• Windows, Linux, Unix, or Mac OS X: 全平台都支持

1.2 安装:

npm install gitbook-cli -g

1.3 创建book:

gitbook init

# `preview` and `serve` your book using: 
gitbook serve

# or `build` the static website using:
gitbook build

1.4 其他:

如果你想用其他版本的gitbook

gitbook fetch beta

# to list remote versions available for install
gitbook ls-remote 

如果想调试网站, 获得更多异常链信息:

#  to get better error messages (with stack trace)
gitbook build ./ --log=debug --debug

2. 项目结构:

2.1 基础:

每个Gitbook项目根目录都应该有一个.gitbook.yaml文件, 文件内容实例如下:

root: ./docs

structure:  
    readme: README.md  
    summary: SUMMARY.md

redirects:  
    previous/page: new-folder/page.md

根目录还有一个可选的book.json用来添加插件, 创建文件添加内容后只需要执行gitbook install即可:

{

    "title": "演示用",
    "description": "演示",
    "author": "twilight",
    "language": "zh-hans",
    "gitbook": "3.2.3",

    "plugins": [
      "back-to-top-button",
      "splitter",
      "lightbox",
      "custom-favicon",
      "chapter-fold",
      "page-toc-button",
      "-sharing",
      "-lunr",
      "-search",
      "search-pro"

    ],

    "pluginsConfig": {

        "page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
        },
        "favicon": "./assets/favicon.ico"
      }
        

}

```json
{
    "plugins": [
      "back-to-top-button",
      "lightbox",
      "chapter-fold",
      "page-toc-button",
      "-sharing",
      "-lunr",
      "-search",
      "search-pro"

    ]
}

## 2.2 `root`:

> `root`字段设置了一个搜索路径, GitBook会以该路径为根目录搜索相关文档
> 
> `事实上, root字段目前似乎不能用, 并不推荐设置该属性!`

**所有其他指定路径的选项都会以根目录为相对路径**. 譬如将`structure.summary`定义为`./product/SUMMARY.md`, 那么GitBook将会搜索文件:`./docs/product/SUMMARY.md`

## 2.3 `structure`:

`structure`字段包含两个属性:

- `readme`: 该文档是文档的第一页, 其默认值为: `./README.md`
- `summary`: 文档的目录, 其默认值为: `./SUMMARY.md`

> 他们的路径都是相对`root`而言的相对路径

## 2.4 `summary`:

```markdown
# Summary

## Use headings to create page groups like this one

* [First page's title](page1/README.md)    
    * [Some child page](page1/page1-1.md)    
    * [Some other child page](part1/page1-2.md)

* [Second page's title](page2/README.md)    
    * [Some child page](page2/page2-1.md)    
    * [Some other child page](part2/page2-2.md)    

## A second-page group

* [Yet another page](another-page.md)

The summary markdown file is a mirror of the Table of Contents of your GitBook space. So even when no summary file is provided during an initial import, GitBook will create one and/or update it whenever you update your content using the GitBook editor.

Due to this, it is not possible to reference the same markdown file twice in your SUMMARY.md file, because this would imply that a single page lives at two different URLs in your GitBook space.

2.5 redirects:

GitBook允许用户自定义URL重定向.

redirects:  
    help: support.md

当用户访问/help时,请求会被重定向到/support上.

redirects:
    help: misc/support.md

/help被重定向到/misc/support上

redirects:  
    help/contact: contact.md

/help/contact被重定向到/contact上

其他:

gitbook出现TypeError: cb.apply is not a function

降低node.js的版本: 10.14.1

1. https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md ↩
2. https://docs.gitbook.com/integrations/git-sync/content-configuration ↩