小技巧：用GitBook组织Markdown文档

喜欢用 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

1npm install gitbook-cli -g


最终，终端里可执行 gitbook
:

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


2 准备文档

2.1 创建文档目录

1mkdir start-gitbook


2.2 创建说明文件 README.md

README.md
是 GitBook 的必要文件

1echo "# My GitBook" > README.md


2.3 创建目录文件 SUMMARY.md

SUMMARY.md
是 GitBook 的必要文件

1cat < SUMMARY.md
2# Summary
3
4This is the summary of my book.
5
6* [section 1](section1/README.md)
7  * [example 1](section1/example1.md)
8  * [example 2](section1/example2.md)
9* [section 2](section2/README.md)
10  * [example 1](section2/example1.md)
11EOF


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

2.4 创建文档结构

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

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


2.5 预览文档

1$ gitbook serve
2Live reload server started on port: 35729
3Press CTRL+C to quit ...
4
5info: 7 plugins are installed
6info: loading plugin "livereload"... OK
7info: loading plugin "highlight"... OK
8info: loading plugin "search"... OK
9info: loading plugin "lunr"... OK
10info: loading plugin "sharing"... OK
11info: loading plugin "fontsettings"... OK
12info: loading plugin "theme-default"... OK
13info: found 6 pages
14info: found 0 asset files
15info: >> generation finished with success in 0.5s !
16
17Starting server ...
18Serving book on http://localhost:4000


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

3 生成文档

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

3.1 安装 ebook-convert 插件

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

Ubuntu 直接安装：

1sudo aptitude install calibre


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

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


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

1$ ebook-convert --version
2ebook-convert (calibre 4.17.0)
3Created by: Kovid Goyal 


3.2 生成 PDF 文档

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


3.3 生成 ePub 文档

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


3.4 生成 MOBI 文档

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


3.5 PDF 预览效果

结语

Go coding!