Gitbook 文档基本使用

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

// 基于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初始化、servebuild等操作快速的构建一个html文档

// 初始化
$ 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)

info: >> generation finished with success in 41.3s ! 

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

4. 文档目录

4.1. 基本目录结构

.
├── 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中指明:

{
    "root": "./docs"
}

4.2. 忽略文件

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

4.3. 静态内容

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

5. SUMMARY.md - 目录参考

# 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链接

左侧栏顶部链接

"links": {
    "sidebar": {
      "https://tkstorm.com": "https://tkstorm.com"
    }
  },

6.2. 自定义样式表

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

  "styles": {
    "website": "styles/website.css"
  },

6.3. gitbook插件

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

gitbook插件具体的方式:

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

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

{
  "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等软件的工作方式。

三者对比起来,简单的概述:

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

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

9. 参考