Use honkit to convert Markdown files into pdf/epub ebooks.

Background#

There are many e-books on Github that are written in Markdown format. They are usually composed of several folders and several md files. This kind of repository can be built into a webpage using GitBook for online browsing. I want to convert these files into epub format and import them into my own e-reader for easier management of annotations.

After searching on the web, I found that GitBook has a command-line version that can generate html/pdf/epub. After downloading it, I found that it would throw an error during initialization:

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

After checking the error, I found that the dependency version of the GitBook command-line tool is too old, and the GitBook command-line tool is no longer being developed and updated. I found a fork of GitBook called honkit recommended by someone on Stack Overflow.

Process#

Install honkit#

Before using honkit, you need to install Node.js.

Install honkit:

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

Install Calibre#

Download Calibre and install it.

For Windows, you need to add the installation path of Calibre to the environment variable.

For Mac, you need to use the following command:

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

Conversion:#

Initialize in the folder:

$ npx honkit init

It will generate the following file structure:

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

Among them, the README.md file contains the preface or introduction of the book, and the SUMMARY.md file contains the content directory of the book.

Next, you can write the directory based on the content of the book. Assuming the content structure of the book is as follows:

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

The content of SUMMARY.md should be:

# Summary

### ch1

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

### ch2

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

If there is a lot of content in the book, you can use ChatGPT to speed up the construction of the directory file. Use the tree command to get the file structure, send the directory requirements and file structure to ChatGPT, and you can generate the directory file.

If you need to customize the book metadata, you need to create a book.json file in the current folder.

Here is an example:

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

More custom options can be found in the official documentation.

In my experience, using Chinese in metadata may cause some problems. Therefore, I recommend using the default settings to generate e-books and import them into Calibre to edit metadata. After editing is complete, you can apply the metadata by converting the book. This is more intuitive and simple.

If you want to add a cover, you can add a cover.jpg file in the directory.

After the settings are complete, you can build the e-book. The commands are as follows:

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

This will generate html/pdf/epub files.

Docker Usage#

I recommend using the Docker version directly, which is more convenient. Just execute the command in the directory.

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

Others#

This method can also be used to convert some web columns into epub e-books. The process is to first use Simplify to convert the webpage into Markdown files and save them, and then use Honkit to convert them into epub, so that they can be imported into e-readers such as Apple Books/Readwise Reader for viewing and managing annotations.