Gitbook 文档基本使用

2019/04/01 共 1436 字 5 分钟阅读
EFFICIENT • SOFTWARE-ENGINEERING tools gitbook git document show

Table of Content

AI 摘要: GitBook是一个命令行工具，通过使用GitHub/Git和Markdown（或AsciiDoc）构建生成指定格式（HTML，PDF，ePub或Mobi）的文档。它支持许多插件，包括文本搜索、字体设置、代码高亮、主题定制等。GitBook是一种方便的文档构建工具，可以配合其他工具如hugo、sphinx-doc使用。它与这些工具的区别在于语言、插件方面、markdown文档支持、样式自定义和上手难度。根据不同的应用场景可以选择使用哪个文档构建工具。

GitBook既是一个用于编写和托管文档的在线平台( https://legacy.gitbook.com/ )，也是一个开源书籍格式和工具链( https://github.com/GitbookIO/gitbook - 本文主要介绍的)。
PS. GitBook团队的工作重点是GitBook.com平台，因此CLI不再处于积极开发阶段。

1. Gitbook 概述

GitBook是一个命令行工具（和Node.js库），利用GitHub/Git和Markdown（或AsciiDoc）构建生成指定文档格式（HTML，PDF，ePub或Mobi）

Gitbook 使用十分简单，同时支持许多插件，比如文本搜索、字体设置、代码高亮、主题定制等。

2. 快速安装Gitbook

2.1. 安装nodejs & 淘宝镜像

因为gitbook是基于nodejs运行的，故需要提前安装好node以及npm，细节可以直接从官网下载安装：https://nodejs.org/en/download/

安装node后，npm也同步安装了，国内环境优先配置好npm淘宝镜像：https://npm.taobao.org/

2.2. 安装gitbook cli工具

参考：https://toolchain.gitbook.com/setup.html

1
2
3
4
5
6
7
// 基于cnpm安装
$ cnpm install gitbook-cli -g

// 安装完后，执行gitbook -V时候会输出cli以及GitBook的相关版本信息
$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

3. Gitbook基本使用

gitbook可以通过init初始化、serve、build等操作快速的构建一个html文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// 初始化
$ cd gitbook-dir
$ gitbook init

// 服务，将启动一个http://127.0.0.1:4000的http服务
$ gitbook serve

// 构建静态文件
$ gitbook build

// debug模式
$ gitbook build ./ --log=debug --debug

gitbook serve启动后，会自动检查文档的变动，然后自动构建（注意，当文档较大时候，整体构建比较慢，比如构建一本go-zh书籍花费了41s）

1
2
3
4
info: >> generation finished with success in 41.3s ! 

Starting server ...
Serving book on http://localhost:4000

4. 文档目录

4.1. 基本目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
.
├── book.json   //存储gitbook配置信息，包括基本设置、插件等信息
├── README.md   //书的前言/介绍（必填）
├── SUMMARY.md  //目录（参见页数）（可选）
├── GLOSSARY.md //词典/注释术语列表（见术语表）（可选）
├── chapter-1/  
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

SUMMARY.md文件用于生成图书的目录;

另外，可以使用子目录（如docs/）来存储项目文档的书籍，但需要在book.json中指明：

1
2
3
{
    "root": "./docs"
}

4.2. 忽略文件

可以添加忽略文件至.gitignore, .bookignore， .ignore中，将需要忽略的文件忽略

4.3. 静态内容

静态文件是SUMMARY.md中未列出的文件，除非被忽略，否则所有静态文件都将复制到输出中。

5. SUMMARY.md - 目录参考

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Summary

* [前言](preface.md)
  * [Go语言起源](ch0/ch0-01.md)
  * [Go语言项目](ch0/ch0-02.md)
  * [致谢](ch0/ch0-05.md)
* [入门](ch1/ch1.md)
  * [Hello, World](ch1/ch1-01.md)
  * [命令行参数](ch1/ch1-02.md)
  * [查找重复的行](ch1/ch1-03.md)
  * [本章要点](ch1/ch1-08.md)
...

6. book.json - 配置文件

配置文件主要涉及文档基本配置，如标题、描述、作者、links链接、isbn准书编码、语言、gitbook版本、插件等

6.1. links链接

左侧栏顶部链接

1
2
3
4
5
"links": {
    "sidebar": {
      "https://tkstorm.com": "https://tkstorm.com"
    }
  },

6.2. 自定义样式表

样式文可以放到sytels/目录下，可以基于自定义样式覆盖掉默认的样式，比如我自定义了一些样式：样式修改demo ，效果参见: https://tkstorm.com/gopl-book/

1
2
3
  "styles": {
    "website": "styles/website.css"
  },

6.3. gitbook插件

插件可以说算是gitbook的一大亮点，丰富的插件，可以实现诸如主题定制、全文搜索、字体设置、分栏设置等、prismjs代码高亮等功能。

gitbook插件具体的方式：

在npmjs中搜索gitbook plugin关键字；
查阅对应的gitbook插件文档，通过npm安装特定包，比如安装搜索包：npm i gitbook-plugin-search-plus；
基于对应的插件，在book.json中引入插件，并设定对应的插件配置：

7. book.json - 一份完整的配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "gitbook": "3.x",
  "title": "Go语言圣经",
  "description": "<The Go Programming Language>中文版",
  "language": "zh-hans",
  "structure": {
    "readme": "preface.md"
  },
  "links": {
    "sidebar": {
      "https://tkstorm.com": "https://tkstorm.com"
    }
  },
  "styles": {
    "website": "styles/website.css"
  },
  "plugins": [
    "theme-comscore",
    "splitter",
    "prism",
    "-highlight",
    "-sharing",
    "-search",
    "katex",
    "-lunr",
    "search-plus",
    "emphasize",
    "multipart"
  ],
  "pluginsConfig": {
    "prism": {
      "lang": {
        "flow": "typescript"
      },
      "css": [
        "prismjs/themes/prism-solarizedlight.css"
      ],
      "ignore": [
        "mermaid",
        "eval-js"
      ]
    }
  }
}

8. 小结

Gitbook是很便捷的构建文档的方式，类似于hugo、sphinx-doc等软件的工作方式。

三者对比起来，简单的概述：

语言不同：gitbook是基于nodejs、sphinx-doc是基于python，hugo是基于go（本博客就是基于hugo构建的，明显全量构建速度要优于前两者）
插件方面：gitbook插件依托npm有丰富的插件，主题方面，hugo比较丰富，sphinx比较中规中矩；
markdown文档支持：sphinx-doc默认是支持reST文档，转markdwon文件需要利用第三方插件支持
样式自定义：三者都支持样式自定义设定
上手方面：gitbook（文档简单，上手最快），其次为sphinx(专业性更强一些)，再次为hugo(一系列文档内容和概念过于繁杂，除普通文档外，支持更的功能，诸如url自定义、目录结构、文档tag、文章分类等概念，更适合做Blog)

在不同的场合三者都有对应的应用场景，可以视应用场景来决定使用哪个文档构建工具；