git.iko.soy/typeable/pandoc
on 2.7.3 help sign in
typeable/pandoc/doc/epub.md
156 lines 5.2 kB history raw
1---
2title: Creating an ebook with pandoc
3author: John MacFarlane
4---
6Starting with version 1.6, pandoc can produce output in the [EPUB]
7electronic book format. EPUB books can be viewed on iPads, Nooks, and
8other electronic book readers, including many smart phones. (They can
9also be converted to Kindle books using [KindleGen].)
11This means that it's now very easy to produce an electronic book!
12Let's try it.
14# A toy example
16Use your text editor to create a file `mybook.txt`, with the following
17contents:
19 % My Book
20 % Sam Smith
22 This is my book!
24 # Chapter One
26 Chapter one is over.
28 # Chapter Two
30 Chapter two has just begun.
32To make this into an ebook takes only one command:
34 pandoc mybook.txt -o mybook.epub
36You can upload `mybook.epub` to your ebook reader and try it out.
38Note that if your markdown file contains links to local images, for
39example
41 ![Juliet](images/sun.jpg)
43pandoc will automatically include the images in the generated
44epub.
46# A real book
48To see what this would look like for a real book, let's convert Scott
49Chacon's book [Pro Git], which he wrote using pandoc's markdown variant
50and released under a [Creative Commons] license. (If you use the book,
51please consider [buying a copy] to help support his excellent work.)
53You can find the markdown source for the book on its
54[github site]. Let's get a copy of the whole repository:[^1]
56 git clone https://github.com/progit/progit.git
58[^1]: If you don't have [git], you can browse to the [github site] and
59click "Download Source" to get the same files in a zip or tar archive.
61This command will create a working directory called `progit` on
62your machine. The actual markdown sources for the English version
63of the book are in the `en` subdirectory, so start by changing
64to that directory:
66 cd progit/en
68As you can see, each chapter is a single text file in its own directory.
69Chacon does some postprocessing on these files, for example, to insert images.
70This is a placeholder for Figure 1-1, for example:
72 Insert 18333fig0101.png
73 Figure 1-1. Local version control diagram.
75The actual image file is called `18333fig0101-tn.png` and lives in
76the `figures` subdirectory of the repository, as you can verify.
78For demonstration purposes, we want pure markdown files, so let's
79change this placeholder into a markdown image link. Pandoc will
80treat a paragraph containing a single image as a figure with
81a caption, which is what we want:
83 ![Figure 1-1. Local version control diagram.](../figures/18333fig0101-tn.png)
85We can make this change in all the files with a perl one-liner:
87 perl -i -0pe \
88 's/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\[\2](..\/figures\/\1-tn.png)/mg' \
89 */*.markdown
91This will modify the files in place. (We won't worry about backing
92them up; if we mess up, we can get the original files back with
93`git reset --hard`.)
95OK! Now we're almost ready to make an ebook. We have the chapters,
96each in its own file, but we still need a title. Create a file,
97`title.txt`, with a pandoc YAML metadata block:
99```
100---
101title: Pro Git
102author: Scott Chacon
103rights: Creative Commons Non-Commercial Share Alike 3.0
104language: en-US
105...
106```
108See the [User's Guide](https://pandoc.org/MANUAL.html#epub-metadata) for more information
109above these fields.
111Now run pandoc to make the ebook, using our title page and modified
112chapter files as sources:
114 pandoc -o progit.epub title.txt \
115 01-introduction/01-chapter1.markdown \
116 02-git-basics/01-chapter2.markdown \
117 03-git-branching/01-chapter3.markdown \
118 04-git-server/01-chapter4.markdown \
119 05-distributed-git/01-chapter5.markdown \
120 06-git-tools/01-chapter6.markdown \
121 07-customizing-git/01-chapter7.markdown \
122 08-git-and-other-scms/01-chapter8.markdown \
123 09-git-internals/01-chapter9.markdown
125That's it! The ebook, `progit.epub`, is ready to be uploaded to your reader.
127## Changing the format
129You can use the `--css` option to specify a CSS file
130for the book. The default CSS is minimal and can be found
131[on GitHub](https://github.com/jgm/pandoc/blob/master/data/epub.css)
132or in the `epub.css` file in your data directory
133(see `--data-dir` in the [User's Guide]).
135You can even embed fonts in the EPUB if you want; see the [User's Guide]
136under `--epub-embed-font` for instructions.
138## Math
140Pandoc has an EPUB3 writer. It renders LaTeX math into MathML, which
141EPUB3 readers are supposed to support (but unfortunately few do).
143Of course, this isn't much help if you want EPUB2 output (`pandoc -t epub2`)
144or target readers that don't support MathML. Then you should try using the
145`--webtex` option, which will use a web service to convert the TeX to an image.
147[KindleGen]: https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211
148[EPUB]: https://en.wikipedia.org/wiki/EPUB
149[Pro Git]: https://git-scm.com/book/en/v2
150[Creative Commons]: https://creativecommons.org/
151[buying a copy]: https://git-scm.com/book/en/v2
152[github site]: https://github.com/progit/progit
153[git]: https://git-scm.com
154[Dublin Core metadata elements]: https://dublincore.org/documents/dces/
155[User's Guide]: https://pandoc.org/MANUAL.html