使用 honkit 將 Markdown 文件轉換成 pdf/epub 電子書

起因#

在 Github 上有許多電子書是以 Markdown 文件形式編寫的，它們通常是由若干個文件夾包括若干個 md 文件構成的。這種 Repo 可以使用 GitBook 構建成網頁，可供在線瀏覽。我想將這些文件轉換成 epub 格式並導入到自己的閱讀器中閱讀，以便更方便地管理註釋。

在網頁上查詢後發現 gitbook 有命令行版本，可以生成 html/pdf/epub。下載之後發現初始化的時候會報錯：

Installing GitBook 3.2.3
/opt/homebrew/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
      if (cb) cb.apply(this, arguments)
                 ^

TypeError: cb.apply is not a function
    at /opt/homebrew/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (node:fs:192:5)

Node.js v19.7.0

查了一下報錯，發現是 gitbook 命令行的依賴版本太舊了，而且 gitbook 命令行已經不再開發更新。在 Stack Overflow 上發現有人推薦了 honkit，一個 gitbook 的 fork。

流程#

安裝 honkit#

在使用 honkit 之前，需要先安裝 Node.js。

安裝 honkit：

$ npm init --yes
$ npm install honkit --save-dev

安裝 Calibre#

下載 Calibre 並安裝。

Windows 下需要將 Calibre 安裝路徑添加到環境變量。

Mac 下需要使用如下命令：

$ sudo ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin

轉換：#

在文件夾內初始化：

$ npx honkit init

會生成如下形式的文件結構：

.
├── files
├── README.md
└── SUMMARY.md

其中，README.md 文件包含書籍的前言或介紹信息，SUMMARY.md 文件則包含書籍的內容目錄。

接下來，可以根據書籍的內容編寫目錄。假設該書的內容結構如下：

.
├── ch1
│   ├── ch1.1.md
│   └── ch1.2.md
└── ch2
    └── ch2.1.md

SUMMARY.md的內容應該是

# Summary

### ch1

* [ch1](ch1/ch1.1.md)
* [ch1](ch1/ch1.2.md)

### ch2

* [ch2](ch2/ch2.1.md)

如果書籍內容較多，可以使用 ChatGPT 來加速目錄文件的構建。使用 tree 命令獲取文件結構，將目錄要求和文件結構發送給 ChatGPT，就可以生成目錄文件了。

如果需要自定義書籍元信息，需要在當前文件夾下新建 book.json 文件。

以下是一個示例：

{
    "root": "./",
    "title": "xxx",
    "author": "xxx"
}

更多自定義選項可以參考官方文檔。

在我的經驗中，如果在元數據中使用中文可能會出現一些問題。因此，我建議使用默認設置生成電子書，並將電子書導入到 Calibre 中編輯元數據。編輯完成後，轉換書籍即可應用元數據。這樣更為直觀和簡單。

如果想要添加封面，可以在目錄下添加 cover.jpg 文件。

設置完成後，即可構建電子書。命令如下：

$ npx honkit build
$ npx honkit pdf
$ npx honkit epub

這樣可以生成 html/pdf/epub 文件了。

Docker 使用#

我更推薦直接使用 Docker 版本，更加方便，只需在目錄下執行命令即可。

docker pull honkit/honkit
docker run -v `pwd`:`pwd` -w `pwd` --rm -it honkit/honkit honkit build
docker run -v `pwd`:`pwd` -w `pwd` --rm -it honkit/honkit honkit pdf
docker run -v `pwd`:`pwd` -w `pwd` --rm -it honkit/honkit honkit epub

其他#

這個方法也可以用來把一些網頁專欄製作成 epub 電子書。流程是先用簡悅將網頁轉換成 Markdown 文件並保存，然後再用 Honkit 將其轉換成 epub，這樣就可以導入到 Apple Books/Readwise Reader 等閱讀器中查看並管理標註。