Making an Epub Out of Markdown Files Using Pandoc

2021-01-04 tips-and-tricks Epub

Sometimes, you write stuff, and want to make an ebook out of it, and why not? If you’ve written your stuff in Markdown, here’s a quick way to convert your file(s) to an epub!

Let’s install pandoc

sudo apt install pandoc

A first example

Let’s start with something easy, shall we?

In a file called write the following content:

% A bit more about Python, for my dear students
% Maria Climent-Pommeret

This ebook it for you, dear students, so that you'll get a bit more familiar with Python.

![Python logo](images/python-logo.png)

# Chapter One: why you should always use Python 3

XXX TODO XXX: write this section

# Chapter Two: why I really like conda

XXX TODO XXX: write this section 

And then run:

pandoc -o simple.epub

With your favorite ebook reader, display the result. You’ve made your first ebook \o/

Let’s put a cover!

What’s a book without a nice cover? Well that’s easy to do :)

You just have to run:

pandoc --epub-cover-image=images/python-logo.png -o simple.epub

A table of content?

Well yes sure!

pandoc --epub-cover-image=images/python-logo.png --toc -o simple.epub

An example with multiple files and metadata

Well if you’re writing something else than my dummy book, your chapters are probably splitted into many files and you probably want some metadata. Here you go

Defining metadata.xml

In a file called metadata.xml write:

title: "A bit more about Python, for my dear students"
 - "Maria Climent-Pommeret"
keywords: ["python", "conda", "error-handling"]
abstract: |
    This is an abstract.

    This is still an abstract.

    I have no idea what I'm doing.

Create the full ebook

Please run

pandoc --epub-cover-image=images/python-logo.png --toc --smart --epub-metadata=metadata.xml -o myebook.epub

And there, you’ve done it! Enjoy :)

Note: pandoc is awesome, you can do many many things with it. Check it out!