How to create ebooks with Markdown

By

Tagged: Tutorials

My process for creating ebooks from Markdown using honkit: book.json, chapters and images, PDF and EPUB via Calibre, and a local preview with honkit serve.

I currently have 16 free books which I share, free of charge, to anyone that subscribes to my email newsletter.

Some of those books are at their 2nd edition (the ones on JavaScript and React) as tech moves fast and we must keep up.

The first one is from 2018.

In the near future I want to reorganize my free ebooks collection by revisiting a few of them, and maybe even adding new ones.

If you’re planning a book yourself, I built a free word count goals planner that helps you estimate the length and set a writing schedule.

I had to set up again my book creation workflow on my Mac since I last updated to the wonderful 2021 MacBook Pro 14”, so I took the opportunity to write about it.

I use a tool called honkit.

It’s a fork of another tool that was called gitbook, which I’ve been using before but has been deprecated and abandonware for a long time now, and does not work any more.

honkit works great. It is a free utility for creating a book using Markdown, and generate a PDF/ePub/Mobi version of it.

I can update a book and with a single command I can upload it to my website and let CloudFlare distribute it.

As far as I know, this is the simplest tool ever available capable of generating all those book versions.

Some other tools exist but don’t have all those capabilities.

Here’s how to get started.

Create a folder, and inside it add a book.json file

{
  "author": "Your name",
  "title": "The book title"
}

author and title are enough to start. book.json can hold more than that.

Useful ones beyond author and title:

A fuller file looks like this:

{
  "author": "Flavio Copes",
  "title": "The JavaScript Handbook",
  "description": "A practical JavaScript handbook",
  "language": "en",
  "pdf": {
    "fontSize": 12,
    "paperSize": "a4",
    "pageNumbers": true
  }
}

Those pdf.* keys only change the PDF. EPUB and MOBI ignore them.

Create a cover.jpg vertical image that’s used for the cover. Add a cover_small.jpg if you want to make an ePub / Mobi version too. HonKit wants JPEG. The docs suggest 1800x2360 for cover.jpg and 200x262 for cover_small.jpg.

Create a SUMMARY.md file with the ToC:

# Summary

- [Preface](README.md)
- [First chapter](content/1-first.md)
- [Second chapter](content/2-second.md)

SUMMARY.md is the table of contents. Each link is one chapter. The link text is the chapter title. The path is the Markdown file. A nested list becomes a subchapter.

Now add a README.md file, that’s the markdown file for the preface.

Add a content/1-first.md, that’s the markdown file for the first chapter.

And so on.

Put images next to the chapter, or in an images/ folder. HonKit copies any file that is not listed in SUMMARY.md, unless you ignore it in .gitignore or .bookignore.

In the chapter, use a normal Markdown image, with a path relative to that file:

![A diagram of the event loop](../images/event-loop.png)

Links to other chapters should keep the .md extension. HonKit rewrites them in the output.

While you write, preview the website output with:

npx honkit serve

It builds the book and opens a local server. Refresh after you save a chapter. This is faster than generating a PDF on every edit.

You can also change how the book looks. The default theme reads extra stylesheets from book.json. Paths are relative to the book root (root if you set one).

{
  "styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css"
  }
}

website is the honkit serve / honkit build HTML. ebook applies to EPUB, MOBI, and PDF, unless you set those formats on their own. pdf then wins for PDF only.

A styles/pdf.css file can change fonts, heading size, or page breaks. Same idea for styles/ebook.css and styles/website.css. You pick the filenames. book.json is what HonKit reads.

PDF, EPUB and MOBI generation needs Calibre’s ebook-convert on your PATH. Download Calibre and install it, or use Homebrew on macOS: brew install --cask calibre.

On macOS the app often stays inside calibre.app, so the command is missing from your PATH. HonKit’s docs add a symlink:

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

If ebook-convert is missing, npx honkit pdf (and epub / mobi) fails with:

"ebook-convert" is not installed.
Install it from Calibre: https://calibre-ebook.com

Then run:

npx honkit pdf  ./ ./book.pdf
npx honkit epub ./ ./book.epub
npx honkit mobi ./ ./book.mobi

that’s it, the book in PDF, ePub and Mobi will show up in the folder.

For Kindle you now send the EPUB. Amazon’s Send to Kindle stopped accepting MOBI. The npx honkit mobi command still works if you need a MOBI for an old device. It’s optional.

While writing the chapters, my free markdown preview is handy to quickly check how the markdown renders.

Want me to talk about your product? You can sponsor this site.

Related posts about tutorial: