A toy example

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

% My Book% Sam SmithThis is my book!# Chapter OneChapter one is over.# Chapter TwoChapter two has just begun.

To make this into an ebook takes only one command:

pandoc mybook.txt -o mybook.epub

You can uploadmybook.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 bookPro Git, which he wrote using pandoc’s markdown variant and released under aCreative Commons license. (If you use the book, please considerbuying a copy to help support his excellent work.)

You can find the markdown source for the book on itsgithub 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 calledprogit on your machine. The actual markdown sources for the English version of the book are in theen 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.pngFigure 1-1. Local version control diagram.

The actual image file is called18333fig0101-tn.png and lives in thefigures 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 withgit 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 Gitauthor: Scott Chaconrights:  Creative Commons Non-Commercial Share Alike 3.0language: en-US...

See theUser’s Guide for more information about 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.

1. If you don’t havegit, you can browse to thegithub site and click “Download Source” to get the same files in a zip or tar archive.↩︎