Pandoc for books: what it is superb at, and where it stops

Pandoc deserves its reputation. It converts between an unreasonable number of document formats, it is free, and pointed at a LaTeX engine it produces books that are genuinely beautifully set — better, out of the box, than most commercial software manages with help.

It is also the tool people abandon three weeks in, having produced something almost right. Both facts are true, and which one applies to you is predictable in advance.

What it does better than anything else

Real typesetting

With a LaTeX engine underneath, you get line-breaking decisions made across the whole paragraph rather than line by line. The practical effect is even spacing between words and few awkward gaps — the thing that makes a page look *set* rather than merely justified. Browsers do not do this. Word processors do not do this.

Citations and cross-references

A BibTeX file plus --citeproc gives you formatted citations and a bibliography in any style you name, updating as you write. Cross-references know what page they are pointing at. If your document needs either of these, the comparison is over — use Pandoc.

Mathematics

LaTeX maths remains unmatched. Nothing else in this space is close, and it is not worth pretending otherwise.

One source, many outputs

One command per target, from the same file:

pandoc book.md -o book.pdf --pdf-engine=xelatex
pandoc book.md -o book.epub
pandoc book.md -o book.docx

For a book that is regenerated by CI every time the manuscript changes, this is exactly right, and a hosted tool with a graphical interface is the wrong shape entirely.

Where the effort curve turns vertical

Every item below is achievable. The point is not that Pandoc cannot do them — it is what each one costs the first time.

Changing the typeface

Straightforward, once you know it goes through fontspec and requires XeLaTeX or LuaLaTeX rather than the default engine:

pandoc book.md -o book.pdf --pdf-engine=xelatex \
  -V mainfont="Lora" -V sansfont="Inter"

Different sizes for headings and body, or a different face for chapter openings, means a custom template. That is the moment the curve turns.

A cover image

For EPUB it is one flag, --epub-cover-image. For PDF there is no flag: you write a title-page template, or you generate the cover separately and merge the PDFs afterwards with another tool.

Seeing what you are doing

There is no preview. You compile, open the PDF, notice the chapter heading sits too close to the text, adjust, compile again. Each cycle is seconds to a minute — fast enough to tolerate and slow enough that most people stop iterating well before the book is right. This, more than any single missing feature, is what makes design work in Pandoc feel like work.

The error messages

When LaTeX fails it fails in LaTeX's own idiom, which assumes you know LaTeX. A missing package produces a wall of output whose actionable line is somewhere in the middle. Solvable, always; pleasant, never.

Deciding in advance

Three questions, and they are quite reliable:

1. Does the document have citations, cross-references or mathematics? If yes, use Pandoc. Nothing below overrides this.
2. Is the book produced by a build rather than by a person? If yes, use Pandoc. A command-line tool is the right shape for a pipeline.
3. Is the hard part how it looks, rather than what is in it? If yes, the effort is going into learning a typesetting system rather than into the book — which is a fine thing to do deliberately and a poor thing to end up doing by accident.

The uncomfortable middle is the third case: a book with no citations and no mathematics, where the whole difficulty is that it should look good, and the author is spending evenings reading LaTeX documentation to move a chapter heading down by six points.

The alternative, stated fairly

That middle case is what bukpress is for. You keep writing Markdown; the design is a handful of controls rather than a template language, and the preview paginates with the same rules the export uses, so the compile-look-adjust loop happens as you type.

It does not do what Pandoc does. There are no citations, no bibliography, no LaTeX maths, no --from docx, and no command-line interface to put in a build. If your document needs any of those, Pandoc is the answer and this article is not trying to talk you out of it.

What it does instead is remove the parts of the middle case that are not writing: pagination, embedding, covers, and seeing the page. If that is your bottleneck, the sample book is the honest test — eight pages, nothing touched after export.