小技巧：用 GitBook 组织 Markdown 文档_gitbook summary.md

喜欢用 Markdown 写文档，那怎么把一个个 Markdown 文档组成在一起呢？

这篇文章，分享了一个用 GitBook 来组织 Markdown 文档的办法。一起了解下吧。

Markdown 是一种轻量级标记语言。只需人们纯文本编写文档，加上点标记符号，就能转成有格式的文档（如 HTML 富文本）。已广泛应用在笔记、文档、博客、出书等。2016 年 RFC 7763 开始也引入了 MIME 类型 text/markdown 。

1 准备工具

1. 安装 Node.js: https://nodejs.org/
2. 安装 GitBook: https://www.npmjs.com/package/gitbook

npm install gitbook-cli -g
1

最终，终端里可执行 gitbook :

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3
1
2
3

2 准备文档

2.1 创建文档目录

mkdir start-gitbook
1

2.2 创建说明文件 README.md

README.md 是 GitBook 的必要文件

echo "# My GitBook" > README.md
1

2.3 创建目录文件 SUMMARY.md

SUMMARY.md 是 GitBook 的必要文件

cat <<EOF > SUMMARY.md
# 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)
EOF
1
2
3
4
5
6
7
8
9
10
11

编辑组织已经存在的 Markdown 文档路径。新建的项目，则写预想的文档结构。

2.4 创建文档结构

依照 SUMMARY.md ，创建新项目的文档结构。

$ gitbook init
info: create section1/README.md
info: create section1/example1.md
info: create section1/example2.md
info: create section2/README.md
info: create section2/example1.md
info: create SUMMARY.md
1
2
3
4
5
6
7

2.5 预览文档

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 0 asset files
info: >> generation finished with success in 0.5s !

Starting server ...
Serving book on http://localhost:4000
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

浏览器打开 http://localhost:4000 ，即可预览。效果如下：

3 生成文档

默认生成 HTML 文档，在 _book 目录。如果要生成其他格式，需要安装 ebook-convert 插件。

3.1 安装 ebook-convert 插件

安装 Calibre: https://calibre-ebook.com/download ，并配置好终端 ebook-convert 命令。

Ubuntu 直接安装：

sudo aptitude install calibre
1

macOS 下载安装，并配置软链接：

ln -s /Users/John/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin
1

最终，终端里可执行 ebook-convert :

$ ebook-convert --version
ebook-convert (calibre 4.17.0)
Created by: Kovid Goyal <kovid@kovidgoyal.net>
1
2
3

3.2 生成 PDF 文档

$ gitbook pdf ./ ./mybook.pdf
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 5.7s !
info: >> 1 file(s) generated
1
2
3
4
5
6
7
8
9
10
11
12
13

3.3 生成 ePub 文档

$ gitbook epub ./ ./mybook.epub
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 1.9s !
info: >> 1 file(s) generated
1
2
3
4
5
6
7
8
9
10
11
12
13

3.4 生成 MOBI 文档

$ gitbook mobi ./ ./mybook.mobi
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 1.6s !
info: >> 1 file(s) generated
1
2
3
4
5
6
7
8
9
10
11
12
13

3.5 PDF 预览效果

结语

Go coding!

---

分享 Coding 中实用的小技巧、小知识！欢迎关注，共同成长！