Kindle-Ready eBooks from Markdown

I've found that turning Markdown notes into eBooks is a nice way to learn away from the computer. Here is the workflow I use to make EPUBs and send them to a Kindle.

The Setup

Install pandoc via Homebrew:

brew install pandoc

Add a script to package.json. I'm using a Node.js project with pnpm, but the command itself works outside Node too:

{
  "scripts": {
    "book:epub": "pandoc book/*.md --epub-cover-image=book/cover.png -t epub3 --metadata uuid='a3f1c820-4b2e-4d91-8c77-1e9f3d5b6a04' --metadata author='AUTHOR' --metadata title='TITLE' -o 'TITLE - AUTHOR.epub'"
  }
}

Run it with pnpm book:epub.

What Each Flag Does

book/*.md selects chapter files in filename order. Names such as 01-intro.md and 02-chapter.md keep them in the intended sequence.

--epub-cover-image points to the cover. I've found a 3:4 image, such as 1200 × 1600 pixels, works well. JPEG or PNG is fine; you could use Gemini or ChatGPT to make one.

-t epub3 creates an EPUB 3 file to send through Send to Kindle.

--metadata uuid gives the book a unique identifier. Use a new one for each title; uuidgenerator.net can generate it. In my tests, this was important for Send to Kindle to accept the file.

--metadata title and --metadata author set the book's details. Pandoc also uses the title in the table of contents. I've found that setting both makes Send to Kindle more reliable.

Naming the Output File

Use a descriptive filename. In my tests, the Send to Kindle desktop app didn't pick up the title and author from the metadata:

'TITLE - AUTHOR.epub'

For example, TITLE could be PyTorch Notes. With the web version, I use just PyTorch Notes.epub, as it uses the filename for the displayed title.

AI-Generated Content

Some suggestions:

  • Ask for each chapter as a separate Markdown file, then put them in book/ and run the script.
  • Use names such as 001-intro.md and 002-chapter.md to keep chapters in order.
  • For notes on a codebase, try a chapter per source file. Ask for code examples, background explanations and questions to check your understanding.

Sending to Kindle

Once you have the .epub, the easiest route is Send to Kindle. You can either download the desktop app or use the web version.