A toy example

Use your text editor to create a file mybook.txt, with the following contents:

% My Book
% Sam Smith

This is my book!

# Chapter One

Chapter one is over.

# Chapter Two

Chapter two has just begun.

To make this into an ebook takes only one command:

pandoc mybook.txt -o mybook.epub

You can upload mybook.epub to your ebook reader and try it out.

Note that if your markdown file contains links to local images, for example

![Juliet](images/sun.jpg)

pandoc will automatically include the images in the generated epub.

A real book

To see what this would look like for a real book, let’s convert Scott Chacon’s book Pro Git, which he wrote using pandoc’s markdown variant and released under a Creative Commons license. (If you use the book, please consider buying a copy to help support his excellent work.)

You can find the markdown source for the book on its github site. Let’s get a copy of the whole repository:¹

git clone https://github.com/progit/progit.git

This command will create a working directory called progit on your machine. The actual markdown sources for the English version of the book are in the en subdirectory, so start by changing to that directory:

cd progit/en

As you can see, each chapter is a single text file in its own directory. Chacon does some postprocessing on these files, for example, to insert images. This is a placeholder for Figure 1-1, for example:

Insert 18333fig0101.png
Figure 1-1. Local version control diagram.

The actual image file is called 18333fig0101-tn.png and lives in the figures subdirectory of the repository, as you can verify.

For demonstration purposes, we want pure markdown files, so let’s change this placeholder into a markdown image link. Pandoc will treat a paragraph containing a single image as a figure with a caption, which is what we want:

![Figure 1-1. Local version control diagram.](../figures/18333fig0101-tn.png)

We can make this change in all the files with a perl one-liner:

perl -i -0pe \
's/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\[\2](..\/figures\/\1-tn.png)/mg' \
*/*.markdown

This will modify the files in place. (We won’t worry about backing them up; if we mess up, we can get the original files back with git reset --hard.)

OK! Now we’re almost ready to make an ebook. We have the chapters, each in its own file, but we still need a title. Create a file, title.txt, with a pandoc YAML metadata block:

---
title: Pro Git
author: Scott Chacon
rights:  Creative Commons Non-Commercial Share Alike 3.0
language: en-US
...

See the User’s Guide for more information above these fields.

Now run pandoc to make the ebook, using our title page and modified chapter files as sources:

pandoc -o progit.epub title.txt \
  01-introduction/01-chapter1.markdown \
  02-git-basics/01-chapter2.markdown \
  03-git-branching/01-chapter3.markdown \
  04-git-server/01-chapter4.markdown \
  05-distributed-git/01-chapter5.markdown \
  06-git-tools/01-chapter6.markdown \
  07-customizing-git/01-chapter7.markdown \
  08-git-and-other-scms/01-chapter8.markdown \
  09-git-internals/01-chapter9.markdown

That’s it! The ebook, progit.epub, is ready to be uploaded to your reader.