基於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 <[email protected]>
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 <command> --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
????  /usr/local/Cellar/hugo/0.69.2: 42 files, 74.3MB
==> `brew cleanup` has not been run in 30 days, running now...
Removing: /usr/local/Cellar/gettext/0.20.1... (1,899 files, 18.5MB)
... ...


$hugo version
Hugo Static Site Generator v0.69.2/extended darwin/amd64 BuildDate: unknown

通過hugo new site命令，我們來創建一個新的站點：

$hugo new site go-machine-learning


Congratulations! Your new Hugo site is created in /Users/tonybai/MyEbook/gohugo/go-machine-learning.


Just a few more steps and you're ready to go:


1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".


Visit https://gohugo.io/ for quickstart guide and full documentation.

下面是生成的站點的初始目錄結構：

$tree
.
└── go-machine-learning
    ├── archetypes
    │   └── default.md
    ├── config.toml
    ├── content
    ├── data
    ├── layouts
    ├── static
    └── themes


7 directories, 2 files

接下來我們來安裝gitbook theme：

$cd go-machine-learning


$git submodule add https://github.com/alex-shpak/hugo-book themes/book
Cloning into '/Users/tonybai/MyEbook/gohugo/go-machine-learning/hugo-book'...
remote: Enumerating objects: 3555, done.
Receiving objects:  18% (664/3555), 692.01 KiB | 4.00 KiB/s   
... ...
remote: Total 3555 (delta 0), reused 0 (delta 0), pack-reused 3555
Receiving objects: 100% (3555/3555), 5.74 MiB | 5.00 KiB/s, done.
Resolving deltas: 100% (1809/1809), done.

我們可以修改一下頂層目錄的config.toml，增加theme="book"：

baseURL = "http://example.org/"
languageCode = "zh-cn"
title = "Go機器學習"
theme = "book"

啓動該站點：

$hugo server --minify --theme book




                   | EN 
-------------------+-----
  Pages            |  7 
  Paginator pages  |  0 
  Non-page files   |  0 
  Static files     | 80 
  Processed images |  0 
  Aliases          |  0 
  Sitemaps         |  1 
  Cleaned          |  0 


Built in 26 ms
Watching for changes in /Users/tonybai/MyEbook/gohugo/go-machine-learning/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /Users/tonybai/MyEbook/gohugo/go-machine-learning/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

這時由於content目錄爲空，因此通過瀏覽器訪問: localhost:1313後只能看到只有一個標題的空白頁面。

我們將https://github.com/alex-shpak/hugo-book themes/book下面的樣例站點的content拷貝到我們的站點中：

 $cp -R themes/book/exampleSite/content .
 $ll content
total 8
drwxr-xr-x   6 tonybai  staff   192  6 27 16:36 ./
drwxr-xr-x  12 tonybai  staff   384  6 27 16:35 ../
-rw-r--r--   1 tonybai  staff  1165  6 27 16:36 _index.md
drwxr-xr-x   4 tonybai  staff   128  6 27 16:36 docs/
drwxr-xr-x   3 tonybai  staff    96  6 27 16:36 menu/
drwxr-xr-x   7 tonybai  staff   224  6 27 16:36 posts/

再次啓動hugo server後，我們通過瀏覽器瀏覽，可以看到下面頁面：

圖：gohugo生成的電子書目錄頁

我們看到這個頁面分爲三欄，最左側是站點目錄欄，中間是章節內容，右側顯示的是內容中的標題結構。電子書源文件分佈在content目錄下，該目錄的結構如下：

$tree -L 2 content
content
├── _index.md
├── docs
│   ├── example
│   └── shortcodes
├── menu
│   └── index.md
└── posts
    ├── _index.md
    ├── chapter_1.md
    ├── creating-a-new-theme.md
    ├── goisforlovers.md
    ├── hugoisforlovers.md
    └── migrate-from-jekyll.md


5 directories, 8 files

•_index.md是首頁佈局•menu/index.md是左側欄的佈局

其他均爲文章內容源文件。如果我們要調整首頁佈局或左側欄的書籍結構，我們只需調整上述兩個文件即可。

4. 小結

我們粗略、快速對mdbook、peach和gohugo工具做了比較，三者部署時都是單二進制文件。

我們的目標是利用工具生成電子書，僅從達到這個目的難易度來看：

•mdbook是“門檻”最低的，幾乎無需配置，就能搭建出一個像模像樣的類似gitbook的圖書站點；•peach門檻較高一些，要配置的東西多一些；•gohugo門檻適中，但卻最爲靈活和強大。如果對gohugo的模板語法十分熟悉，可以定義出一套滿足自己風格的電子書瀏覽頁面風格。

---

我的網課“Kubernetes實戰：高可用集羣搭建、配置、運維與應用”在慕課網上線了，感謝小夥伴們學習支持！

我愛發短信：企業級短信平臺定製開發專家 https://51smspush.com/ smspush : 可部署在企業內部的定製化短信平臺，三網覆蓋，不懼大併發接入，可定製擴展；短信內容你來定，不再受約束, 接口豐富，支持長短信，簽名可選。

2020年4月8日，中國三大電信運營商聯合發佈《5G消息白皮書》，51短信平臺也會全新升級到“51商用消息平臺”，全面支持5G RCS消息。

著名雲主機服務廠商DigitalOcean發佈最新的主機計劃，入門級Droplet配置升級爲：1 core CPU、1G內存、25G高速SSD，價格5$/月。有使用DigitalOcean需求的朋友，可以打開這個鏈接地址：https://m.do.co/c/bff6eed92687 開啓你的DO主機之路。

Gopher Daily(Gopher每日新聞)歸檔倉庫 - https://github.com/bigwhite/gopherdaily

我的聯繫方式：

微博：https://weibo.com/bigwhite20xx 微信公衆號：iamtonybai 博客：tonybai.com github: https://github.com/bigwhite

微信讚賞：

商務合作方式：撰稿、出書、培訓、在線課程、合夥創業、諮詢、廣告合作。