Building books with Markdown using pandoc

Create epubs with pandoc using markdown syntax — painlessly.

John Paul Ada
Jun 29, 2017 · 4 min read

TL;DR: If you want to do this quickly, install pandoc and use my markdown book template.

If you’re a developer or a blogger, you probably know what Markdown is, and if you know what Markdown is, you know that it’s a great way to describe your content. Maybe you’ve thought about writing a book in Markdown. If so, this is for you.

If you don’t know what Markdown is, you can check these links out:

Building a book with markdown is pretty easy with pandoc. Pandoc calls itself a universal document converter. Makes sense. In this tutorial, we’re going to convert markdown to epub. You can convert markdown to other formats in pandoc but I’m going to use epub because they’re pretty flexible.

Installing Pandoc

To install pandoc, install the packages found on their releases page in Github. There are packages for Debian/Ubuntu, Windows, and Mac.

If you’re on macOS, you can also use Brew by running:

brew install pandoc

If you’re hardcore or if your OS is not supported, you can also build from source.

Creating a simple Markdown book

To create a simple book, create a markdown file and feed it into pandoc. For example, you can try these steps:

  1. Create a content.markdown file.
# Chapter 1
## Subtitle
This is your first markdown chapter!

Building the book

Run this command to create the book:

pandoc -S -o book.epub content.markdown

You will get a book.epub as the output.

Create metadata file

Of course we want to add information about our book like title, author, etc. To add that, we’ll create a metadata file. Here is a sample metadata file from their documentation:

---
title:
- type: main
text: My Book
- type: subtitle
text: An investigation of metadata
creator:
- role: author
text: John Smith
- role: editor
text: Sarah Jones
identifier:
- scheme: DOI
text: doi:10.234234.234/33
publisher: My Press
rights: © 2007 John Smith, CC BY-NC
...

In addition, we can add a path to a stylesheet and a cover image like this:

---
title:
- type: main
text: My Book
- type: subtitle
text: An investigation of metadata
creator:
- role: author
text: John Smith
- role: editor
text: Sarah Jones
identifier:
- scheme: DOI
text: doi:10.234234.234/33
publisher: My Press
rights: © 2007 John Smith, CC BY-NC
stylesheet: epub.css
cover-image: cover.jpg
...

Creating a stylesheet

Pandoc epubs have the following styles:

body { margin: 5%; text-align: justify; font-size: medium; }
code { font-family: monospace; }
h1 { text-align: left; }
h2 { text-align: left; }
h3 { text-align: left; }
h4 { text-align: left; }
h5 { text-align: left; }
h6 { text-align: left; }
h1.title { }
h2.author { }
h3.date { }
ol.toc { padding: 0; margin-left: 1em; }
ol.toc li { list-style-type: none; margin: 0; padding: 0; }

You can just edit this to customize your book’s style and save this to the path specified on the metadata.

Adding a cover image

To add an image as the cover of your book, you just have to make sure that the path specified in the metadata points to that image.

Applying metadata to book

To apply the created metadata, along with the styles and cover image, you just have to include it as an input, like this:

pandoc -S -o book.epub metadata.txt contents.markdown

Embed custom fonts

To embed custom fonts, you use the — epub-embed-font parameter with the path to the fonts as the argument, like this:

pandoc -S --epub-embed-font='fonts/*.ttf' -o book.epub metadata.txt contents.markdown

Add a Table of Contents

To add a table of contents, you can use the — toc switch, like this:

pandoc -S --toc --epub-embed-font='fonts/*.ttf' -o book.epub metadata.txt contents.markdown

Epub Template

To make this process easier, you can try my Markdown Book Pandoc Template. To use it follow these steps:

  1. Clone or download the template.
pandoc -S --toc --epub-embed-font='fonts/*.ttf' -o book.epub metadata.txt contents.markdown

This will generate book.epub.

Voila! Your book is finished!

If you liked this post, like it, share it, and subscribe!

Also, star my Github project! It means so much!

Programmers — Developers

The official publication of the Programmers,Developers…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store