pandoc-novel

This is a template project for generating a novel or story collection from markdown files and building an ePub file, a printable PDF book suitable for Amazon KDP, and a SFFMS format manuscript PDF using Pandoc, LaTeX, and GNU Make. This project is a distillation of the code I used to build my story collection, and was partly inspired by Dan Grec's post on how he created his book for publication using LaTeX.

Well formatted ePub and PDF files should be enough for publishing ebooks and print-on-demand books with Amazon KDP, Barnes and Noble Press, Smashwords.com, and other self-publishing outlets. (Well, that and a decent-looking cover, but cover design, especially for print books, is beyond the scope of this template.)

You can see example output for book PDF, ePub, and manuscript PDF.

Set Up

Install prequisites

Pandoc
LaTeX --- Installing LaTeX is beyond the scope of this document, but I use MacTex on macOS.
the createspace package, for formatting your ready-print book pdf. On the Mac, you can git clone that repo into $HOME/Library/texmf/tex/latex/createspace/.
the sffms package for formatting a manuscript-format PDF.

Clone this repo

git clone git@github.com:jp-fosterson/pandoc-novel.git

...or fork the repo (it's a template), and clone your own copy.

Try it out

cd pandoc-novel
make

This will build three targets out/example.epub, out/example.pdf, and example-ms.pdf. Open them in your favorite viewers.

If you're on macOS make view-epub will attempt to build the epub target and open the file in Calibre's ebook viewer component (without actually adding the book to your library). Likewise make view-pdf will build the pdf target and open it with the default PDF viewer (probably Preview). If you're not on macOS, you can edit these targets in the Makefile to open the documents in your favorite viewers.

Writing

`text/`

The most important part of the novel, the text, goes in markdown-format chapter files in the text/ directory. Aside from the .md extension, there are no particular requirements about the file names, chapter ordering will be defined in the Makefile (see below). Chapter titles should be indicated with a H1-level header. If you wish your chapters to be unnumbered, tag them with {.unnumbered} after the title. Backmatter such as acknowledgements and an author bio should just be included as {.unnumbered} chapters; they will be indicated in the Makefile.

`Makefile`

Set the SLUG variable in the Makefile to change the prefix used on the output files

#
# Slug: filename prefix that will be used for the generated
# files. e.g. example.epub and example.pdf, plus intermediate
# files like example.tex
#
SLUG=example

To define the chapter ordering add the chapter files, in order, in the CONTENTS and BACKMATTER variables in Makefile:

#
# The main text of the book. This sequence determines the
# chapter order.
#
CONTENTS = \
	text/beginning.md\
	text/middle.md\
	text/end.md\
	\
#
# The stuff in the back, not part of the story.
#
BACKMATTER = \
	text/ack.md \
	text/about.md\
	\

`metadata.yaml`

The title, author, copyright notice, ePub cover image, and other important metadata are defined in metadata.yaml.

`make` targets

make or make all --- makes the main ePub and PDF targets in out/.
make pdf -- builds the print-ready book PDF.
make epub --- builds the epub book.
make ms --- builds the manuscript-format PDF.
make unzip --- Builds the ePub document, which really just a zip archive full of files, and then unzips it into out/$(SLUG).unzip so that you can examine the contents. This is fun for the curious, or if you need to understand the style classes used in the document when modifying the stylesheet (see below).
make clean --- cleans up everything, including the output and all the LaTeX shrapnel left in the directory after building.
make tkcheck --- searches for "TK" in the text and fails if it finds any. [Editors use "TK" to indicate more to come, i.e. unfinished writing. You can do make tkcheck all to build the documents only when all TKs are removed.]

Customization

You can customize the style of the generated ePub via CSS stylesheets, and the PDF via the LaTeX document template.

ePub Stylesheets

The STYLESHEET variable in the Makefile selects the stylesheet to use when building the ePub document. Two stylesheets are provided in the /css directory, one with an indented paragraph style and one with a block-paragraph style. Either can be used as a starting point for a new style. If you're not sure what style classes you need to modify, do make unzip then examine the chXXX.xhtml files in out/$(SLUG).unzip/EPUB/text.

LaTeX Template

The LaTeX files that generate the book and manuscript PDF are built from templates in templates/book.tex and templates/sffms.tex. They use Pandoc template syntax.

For the book PDF, the title page design for the book template was taken from Peter Wilson's great collection of LaTeX title pages, feel free to replace it with a design you like better. The page header and numbering are controlled by the fancyhdr package.

For the manuscript PDF, I had to define or override a handful of LaTeX commands to get some things to work (e.g. sections). Inputs that deviate consierably from the example text may require some LaTeX tinkering to get right. By default, the manuscript omits the backmatter like "Acknowledgements" and "About the Author" sections. To include them, add $(BACKMATTER) to the $(SLUG)-ms.tex target in the Makefile.

Publishing

Ebooks

Amazon KDP will take an ePub doc and covert it to a Kindle book, and it does a fairly good job. If you're curious what it looks like, you can get Kindle Previewer, and other ebook sites take ePubs directly.

Print

I have only tried KDP, but the KDP site does a pretty good job of showing how your PDF will fit in different page trim sizes. I found that despite using the "pocket" size parameter in the createspace package, it fits well in 6x9" with good size margins (IMO).

Cover Design

For the artistically challenged like me, Canva provides nice starting templates for eBook covers. Amazon provides a cover designer for print books that takes care of computing the spine width properly. Its editor leaves a lot to be desired, but I thought it was worth it to not have to do the sizing manually.

A Gratuitous Note on Gratuitous Typography

This example, especially for the print version, reflects a set of simple typographic choices designed to achieve a basic standard of readability: Pagella/Palatino font throughout, 1.5 line spacing for the text, centered chapter titles, simple centered page header and footer, etc.

I arrived at these choices, to be honest, by pulling a bunch of novels off my shelf, looking at the pages, and trying to emulate what I saw there, but the choice to stay simple was one I made before I started. As practical matter, of course, it makes sense for this example to shoot for a least-common-denominator from which users can branch off in different directions according to their tastes. But, frankly, I think most such typographical branchings are a waste of effort. I understand how a writer might want to do titles and headers in a futuristic sans-serif font for a sci-fi novel, or an old-fashioned font in historical fiction, but is it worth it? For fiction---storytelling in written prose---the cost of not making such embellishements is nil. If your prose is doing its job then the reader won't notice the typography, as long as you've met a basic threshold of readability and it doesn't look weird.

Consider the great, classic novels. For me these would be things like Pride and Predjudice, Moby Dick, The Adventures of Huckleberry Finn, The Awakening, Gatsby, The Left Hand of Darkness, Stranger in a Strange Land, and others. For you, maybe other works, but surely there are some. These books, especially the older ones, have been reprinted and retypeset many times, even released as ebooks, where the typography is fluid, and yet their greatness remains. The greatness is in the words, not the glyphs. Some fiction is so great that its greatness survives not just being typeset differently, but even being translated into different languages that use different alphabets! (Murakami and the great Russians come to mind)

For an indie author, the effort required to go beyond basic, good-looking, inoffensive readability is almost always better spent on writing. This is my whole reason for writing in Markdown instead of using a WYSIWYG word processor: the formatting is irrelevant to the story. Pedants will find counterexamples, of course, where some typographical aspect of some book or other is crucial to the story, but those are exceptions. Moreover, futzing with word processor settings (and the like) is one of the great sinks of procrastination for writers. Just stop it and get back to writing.

Meanwhile, if you do get fancy, you risk making bad typographic choices that distract the reader from your story. Right now I'm reading a contemporary novel from a small press. It uses a traditional serif font for the main text, a typewriter font for some parts of the text that are composed as snippets of screenplay, a modern-looking sans-serif for the page header and footer and some of the chapter titles, a caligraphic font for the remaining chapter and subchapter titles, and a different caligraphic font for the title pages of the major parts of the book. The result feels to me as if the typesetter was trying to justify his salary. There might be a meaning to the different chapter title fonts, but I'm damned if I can figure out what it is. Trying to deduce is just distracts me from staying immersed in the story.

Every rule has exceptions, of course. Whoever typsets Tolkien will have to figure out how to deal with the Tengwar. If you make up a new alphabet for your story, then you'll have to to typeset it. But if you're not doing something exceptional, you're better off thinking about your characters and what they'll be doing than your fonts, margins, spacing, and the like.

thoughtpunch/pandoc-novel