小技巧：用 GitBook 组织 Markdown 文档

GoCoding

发布于 2021-05-06 14:28:09

4480

发布于 2021-05-06 14:28:09

文章被收录于专栏：GoCoding

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

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

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

1 准备工具

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

npm install gitbook-cli -g

最终，终端里可执行 gitbook :

$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

2 准备文档

2.1 创建文档目录

mkdir start-gitbook

2.2 创建说明文件 README.md

README.md 是 GitBook 的必要文件

echo "# My GitBook" > README.md

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

编辑组织已经存在的 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

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

浏览器打开 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

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

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

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

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

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

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

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