基于Markdown格式的电子书生成工具大比拼：gohugo、mdbook和peach
基于 Markdown格式 文件写博客已经很多年了，一直使用的是Wordpress的markdown插件，由于各种遗留原因，一直没有转换到直接使用静态站点的方式。博客文章之间一般来说多是独立篇章，少有关联，即便是写一个系列文章，数量也不会太多。因此，用博客形式来组织书籍章节是不大合适的。“术业有专攻”，我们还得寻找专门用来制作电子书的工具或平台，并且要支持本地安装，支持基于Markdown格式的源数据文件。
专门用于制作电子书类文档的知名工具包括： gitbook 和 Read the Docs 。不过前者的 开源版本 2018年末就 不更新了 ，而 Read the Docs 则比较老，还需要多个工具配合。我个人倾向于单个二进制文件搞定一切。于是我找到了三个候选： gohugo 、 mdbook 和 peach ，这三个候选部署时都只有一个二进制文件。gohugo和peach是Go语言实现的，而mdbook则是用 Rust语言 实现的。下面我们就来简单对比一下这三个基于Markdown格式的电子书制作工具。
1. mdbook
mdbook是模仿gitbook样式的从markdown文件生成电子书的工具和静态站点服务，它仅聚焦于“电子书制作和站点服务”。如果不是类似gitbook风格的其他类静态内容服务，那么它并不适合。因此，该工具采用了惯例优先原则(convention over configuration)，使得使用时我们无需做太多的配置即可生成一个 像模像样 的电子书站点。
由于是rust实现的，mdbook本地部署时只需一个二进制文件，我们直接从它的github release上下载对应os平台的release文件（这里是macos的0.4.0版本）：
wget -c https://github.com/rust-lang/mdBook/releases/download/v0.4.0/mdbook-v0.4.0-x86_64-apple-darwin.tar.gz
解压后，将mdbook所在路径添加到 PATH 环境变量中：
$tar zxvf mdbook-v0.4.0-x86_64-apple-darwin.tar.gz
x mdbook
$ls
mdbook* mdbook-v0.4.0-x86_64-apple-darwin.tar.gz
$mdbook -help
mdbook v0.4.0
Mathieu David
Creates a book from markdown files
USAGE:
mdbook [SUBCOMMAND]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
build Builds a book from its markdown files
clean Deletes a built book
help Prints this message or the help of the given subcommand(s)
init Creates the boilerplate structure and files for a new book
serve Serves a book at http://localhost:3000, and rebuilds it on changes
test Tests that a book's Rust code samples compile
watch Watches a book's files and rebuilds it on changes
For more information about a specific command, try `mdbook --help`
The source code for mdBook is available at: https://github.com/rust-lang/mdBook
接下来，我们就使用 mdbook init 命令创建一个电子书工程：
$mdbook init go-ml Do you want a .gitignore to be created? (y/n) y What title would you like to give the book? go machine learning 2020-06-27 15:58:03 [INFO] (mdbook::book::init): Creating a new book with stub content All done, no errors...
我们看到 mdbook init 生成了一个目录，目录布局如下：
➜ /Users/tonybai/MyEbook/mdbook git:(master) ✗ $tree
.
└── go-ml
├── book
├── book.toml
└── src
├── SUMMARY.md
└── chapter_1.md
3 directories, 3 files
接下来，我们直接运行 mdbook serve 即启动了一个服务，用于访问该电子书：
➜ /Users/tonybai/MyEbook/mdbook git:(master) ✗ $mdbook serve go-ml 2020-06-27 16:06:56 [INFO] (mdbook::book): Book building has started 2020-06-27 16:06:56 [INFO] (mdbook::book): Running the html backend 2020-06-27 16:06:56 [INFO] (mdbook::cmd::serve): Serving on: http://localhost:3000 2020-06-27 16:06:56 [INFO] (warp::server): listening on http://[::1]:3000 2020-06-27 16:06:56 [INFO] (mdbook::cmd::watch): Listening for changes...
我们通过浏览器访问 http://localhost:3000 ，可以看到如下页面：
图：mdbook生成的电子书首页
我们看到：我们没有做任何配置就生成了一个和gitbook样式差不多的电子书服务站点。该站点还支持选择页面显示模式（截图中使用的是默认的Light模式）、支持查询等。
如果我们要增加新章节、编排章节标题缩进，只需编辑电子书工程下面的 src/SUMMARY.md ：
$cat SUMMARY.md # Summary - [Chapter 1](./chapter_1.md) - [Chapter 1.1](./chapter_1_1.md) - [Chapter 2](./chapter_2.md)
这些对于多数人来说已经是足够了的，后续只需关注书籍内容即可，无需对mdbook生成的工程进行什么调整。mdbook会自动探测src目录下的文件变化并根据变化重新生成静态html文件。我们只需刷新页面即可看到最新变化。
2. peach
peach 是一款由Go语言实现的多语言、实时同步以及全文搜索功能的 Web 文档服务器。它由gogs的作者 无闻 打造，该作者的很多开源项目的文档也都是由peach生成和提供文档服务支撑的。
我们可以直接使用 go get 安装peach：
$export GONOSUMDB="github.com/russross/blackfriday" $go get github.com/peachdocs/peach go: github.com/peachdocs/peach upgrade => v0.9.8 $peach -v Peach version 0.9.8.0810
接下来，我们用peach建立电子书工程：
$peach new -target=go-ml.peach ➜ Creating 'go-ml.peach'... ➜ Creating 'templates'... ➜ Creating 'public'... Do you want to use custom templates?[Y/n] n ✓ Done!
我们这里直接使用peach项目自身文档的自定义模板：
下载配置好的自定义模板：
$ cd go-ml.peach $ git clone https://github.com/peachdocs/peach.peach.git custom Cloning into 'custom'... remote: Enumerating objects: 62, done. remote: Total 62 (delta 0), reused 0 (delta 0), pack-reused 62 Unpacking objects: 100% (62/62), done. Checking connectivity... done.
启动web服务：
$peach web
intro/
|__ installation
|__ getting_started
|__ roadmap
howto/
|__ documentation
|__ webhook
|__ templates
|__ static_resources
|__ navbar
|__ pages
|__ extension
|__ protect_resources
|__ upgrade
advanced/
|__ config_cheat_sheet
faqs/
intro/
|__ installation
|__ getting_started
|__ roadmap
howto/
|__ documentation
|__ webhook
|__ templates
|__ static_resources
|__ navbar
|__ pages
|__ extension
|__ protect_resources
|__ upgrade
advanced/
|__ config_cheat_sheet
faqs/
[Peach] 20-06-27 10:17:31 [ INFO] Peach 0.9.8.0810
[Peach] 20-06-27 10:17:31 [ INFO] Peach Server Listen on 127.0.0.1:5556
我们通过浏览器访问 http://localhost:5556 ，可以看到如下页面：
图：peach生成的电子书目录页
不过，和mdbook不同，上面peach加载并渲染的文档并不在本地，我们在custom/app.ini中看到如下配置：
[docs] TYPE = remote TARGET = https://github.com/peachdocs/docs.git SECRET = peach
我们看到当前例子采用了 remote 模式，即使用Github上的仓库peachdocs/docs中的数据(markdown文件）作为源文件进行渲染，而这个仓库的结构如下：
$tree -L 2 docs
docs
├── TOC.ini
├── en-US
│ ├── advanced
│ ├── faqs
│ ├── howto
│ └── intro
├── images
│ └── github_webhook.png
└── zh-CN
├── advanced
├── faqs
├── howto
└── intro
11 directories, 2 files
TOC.ini文件描述了文档结构布局：
$cat TOC.ini -: intro -: howto -: advanced -: faqs [intro] -: README -: installation -: getting_started -: roadmap [howto] -: README -: documentation -: webhook -: templates -: static_resources -: navbar -: pages -: extension -: protect_resources -: upgrade [advanced] -: README -: config_cheat_sheet [faqs] -: README
我们看到，和mdbook相比，peach的门槛稍高一些，需要学习TOC.ini中的特殊配置语法，同时如果要改变peach的默认风格，还要学习peach使用的模板语法(Peach 使用 Go 语言 Pongo2 v3 版本 作为模板引擎，它使用的是 Django HTML 格式)。
3. gohugo+git book theme
gohugo是这几年最火的静态站点生成工具。和上面两个工具不同的是：它致力于成为一个通用的静态站点工具，与hexo等目标一致。结合gohugo与git book风格的theme也能实现电子书制作与站点服务。
经过多年发展，gohugo的安装十分方便：在macos上，我们既可以使用go get安装（gohugo支持module），也可以使用brew安装：
“`
$brew install hugo
==> Downloading https://mirrors.ustc.edu.cn/homebrew-bottles/bottles/hugo-0.69.2.mojave.bottle.tar.gz
==> Summary
© 2020,bigwhite. 版权所有.
About The Author
