donghao_34's Blog

New way, new future.

0%

使用 gitbook 创建静态页面文档

发表于 更新于 分类于
本文字数： 1.4k 阅读时长 ≈ 1 分钟

参考：

Gitbook 是一个简单的文档生成系统，可以用于进行简单的文档建立和书籍制作，支持生成静态页面或常见的电子书格式 (pdf, epub, mobi)，实现起来较为简单。

Gitbook 环境的安装

Gitbook 需要 Node.js 环境，首先应在此链接下载安装 Node.js 环境。完成后，在命令行中输入以下命令，即可完成安装：

1
$ npm install gitbook -g

Gitbook 电子书的创建

在需要创建电子书的目录下的命令行里输入以下命令，即可完成电子书的初始化：

1
$ gitbook init

完成初始化后会自动在目录下生成 README.md 文件和 SUMMARY.md 文件，分别是书籍的简介（即第一页）和目录结构文件。

SUMMARY.md 文件的格式可以为以下两种形式：

1
2
3
4
5
6
# SUMMARY

* [Chapter1](chapter1/README.md)
  * [Section1.1](chapter1/section1.1.md)
  * [Section1.2](chapter1/section1.2.md)
* [Chapter2](chapter2/README.md)

或

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

### Part I
* [Chapter1](part1/chapter1/README.md)
  * [Section1.1](part1/chapter1/section1.1.md)
  * [Section1.2](part1/chapter1/section1.2.md)
* [Chapter2](part1/chapter2/README.md)

### Part II
 * [Chapter1](part2/chapter1/README.md)
  * [Section1.1](part2/chapter1/section1.1.md)
  * [Section1.2](part2/chapter1/section1.2.md)
* [Chapter2](part2/chapter2/README.md)

修改 SUMMARY.md 文件中的目录结构后，再次运行 gitbook init 命令，会自动生成对应的 markdown 文件。

完成文档的撰写后，可以运行 gitbook build 命令编译电子书，或运行 gitbook serve 创建本地服务实时编译和预览文档。

使用 gitbook 插件

Gitbook 支持大量插件，要使用其插件，首先需要在电子书目录下创建配置程序 book.json，并在其中添加如下设置：

1
2
3
4
5
{
  "plugins": [
      "plugin-name"
   ]
}

常用的插件包括：

  • katex 或 mathjax：实现数学公式的渲染；
  • prism：第三方高亮；
  • splitter：可改变宽度侧栏；
  • code：代码行号和复制按钮；
  • search-pro：高级搜索（支持中文）；
  • hide-element：隐藏元素；
  • chapter-fold: 可折叠章节；
  • back-to-top-button：回到顶部按钮；
  • popup：新标签页打开图片；
  • theme-comscore：彩色标题主题；
  • ……