Building books with Markdown using pandoc
Tags: markdown, pandoc, books, publishing
Published: 2017-06-29 06:43:39

---
title: Building books with Markdown using pandoc
published: true
description: Create epubs with pandoc using markdown syntax — painlessly.
tags: markdown,pandoc,books,publishing
---

> TL;DR: If you want to do this quickly, install [pandoc](https://github.com/jgm/pandoc/releases/tag/1.19.2.1) and use my [markdown book template](https://github.com/johnpaulada/pandoc-markdown-book-template).

> Originally posted at [Medium](https://medium.com/programmers-developers/building-books-with-markdown-using-pandoc-f0d19df7b2ca).

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](https://en.wikipedia.org/wiki/Markdown) is, you can check these links out:
- [Markdown Tutorial](http://www.markdowntutorial.com/)
- [Ghost Markdown Guide](https://help.ghost.org/hc/en-us/articles/224410728-Markdown-Guide)
- [Markdown Syntax](https://learn.getgrav.org/content/markdown)
- [Dillinger](http://dillinger.io/)

Building a book with markdown is pretty easy with [**pandoc**](http://pandoc.org/). 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](https://github.com/jgm/pandoc/releases/tag/1.19.2.1) page in Github. There are packages for [Debian/Ubuntu](https://github.com/jgm/pandoc/releases/download/1.19.2.1/pandoc-1.19.2.1-1-amd64.deb), [Windows](https://github.com/jgm/pandoc/releases/download/1.19.2.1/pandoc-1.19.2.1-windows.msi), and [Mac](https://github.com/jgm/pandoc/releases/download/1.19.2.1/pandoc-1.19.2.1-osx.pkg).

If you’re on macOS, you can also use Brew by running:
```bash
brew install pandoc
```

If you’re hardcore or if your OS is not supported, you can also build from [source](https://github.com/jgm/pandoc/archive/1.19.2.1.tar.gz).

## 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 `chapter1.markdown` file.
2. Open your Terminal/Command Prompt.
3. Go to the directory where that file is located.
4. Add some markdown to the file. Here’s an example of what it should look like:
```markdown
# Chapter 1
## Subtitle
This is your first markdown chapter!
```

### Building the book
Run this command to create the book:
```bash
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](http://pandoc.org/MANUAL.html#epub-metadata):

```yaml
---
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:

```yaml
---
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:

```css
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:

```bash
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:

```bash
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:

```bash
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](https://github.com/johnpaulada/pandoc-markdown-book-template). To use it follow these steps:

1. Clone or [download](https://github.com/johnpaulada/pandoc-markdown-book-template/archive/master.zip) the template.
2. Open your console (Terminal, Command Prompt, etc.)
3. Replace the contents of `metadata.txt` and `contents.markdown`.
4. Replace `cover.jpg`.
Run this code:

```bash
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!