Building books with Markdown using pandoc

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

Originally posted at Medium.

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:

• Markdown Tutorial
• Ghost Markdown Guide
• Markdown Syntax
• Dillinger

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

# 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.
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:

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!

Comments

[Ethan]

Awesome! It would be cool to see a screenshot of what a page would look like in the article...