Pandocomatic and Scrivomatic

· geekery · software ·

Regular readers among you will know that if there’s an easy way to do it, or a difficult but deliciously geeky way to do it which involves substantial amounts of tinkering, I invariably prefer the latter. So you’ll appreciate that when a search for some tidbit of information about Pandoc turned up an article by Andrew Goldstone titled Easy Lecture Slides Made Difficult with Pandoc and Beamer (and its follow up, Programmatic Lecture Slides Made Even More Difficult with R Markdown), I smiled with recognition. It seems that Andrew and I are both connoisseurs of a geekily baroque workflow.

I’m a long-time user of Pandoc to produce most kinds of document, but this week I have been trying out a couple of linked systems — Pandocomatic and Scrivomatic — which aim to tidy up your Pandoc workflow, and make it quicker to produce the kinds of output you need.

I only found Scrivomatic because the author (Ian) linked to my Bookends and Pandoc article, and so the link turned up in my referrer logs1. Scrivomatic uses Pandocomatic, so I ended up trying them both. Pandocomatic is essentially a wrapper script around Pandoc, but a very cleverly written one that allows you to write template configurations which specify various options for the pandoc command. For example, you might have article-pdf and article-docx templates, each of which would set the appropriate variables, commands, and pandoc templates to produce a PDF version and a Word *.docx version of an article, just the way you like it. The clever bit is that once you have done the hard work of configuring these templates in your pandocomatic.yaml file, you can add a couple of lines to the metadata of your document, then use pandocomatic to build things the way you want.

For example, the YAML metadata to use the article-pdf template might look as follows for the Markdown file ‘my_lovely_horse.md’:

---
title: "My lovely horse"
author: "Father Ted Crilly"
pandocomatic_:
    use-template: article-pdf
...

Then you could generate the PDF output using the command pandocomatic -i my_lovely_horse.md.

It’s a very flexible and modular system, so you can, for example, create templates which just set the options and configuration variables to process references, and then use that template to extend other templates, thus avoiding the need to repeat yourself. You can also override variables in the YAML front matter of your document itself, which means that you can set a default option in the template, like the citation style that you use most frequently, but specify a different style in a particular document. You can also specify filters, pre-processor and post-processor scripts, so it’s possible to set up quite sophisticated workflows.

Inevitably, I’m still tweaking, but I’ve now got templates for nice-looking PDF and DOCX articles, fancy reports with a coverpage, Tufte-style HTML pages, and books with chapters. I’m finding it a bit more tricky to get a template working for my Beamer lecture slides, because it writes to a Latex file, not straight to PDF, but I’ll get there. My plan is to create templates for the presentation slides and handouts (both PDF), so that I can create both easily from one source Markdown file.

One of the Sublime Text packages for Pandoc I had been using employed a similar system. However, I found that this had stopped working with the update to Pandoc 2, and in any case, Pandocomatic is easier to use in different contexts. In Sublime Text, I have set up a build system document to use Pandocomatic, so I can build the current file by using Cmd-B. However, since Pandocomatic isn’t tied to any particular application, I can use it to build documents in Sublime Text, at the command line, using Alfred, or in Scrivener, all using the same set of templates. That brings me on to Scrivomatic.

Scrivomatic is — if you can believe this — a wrapper around Pandocomatic2. Scrivomatic (as the name suggests) simplifies using Pandocomatic templates in Scrivener’s compile system, so that you can compile using Pandoc straight to your favourite format, including generating both a PDF and a DOCX file at the same time. The instructions are clear on the Github page, and it works like a dream. Scrivener is my preferred writing environment for longer writing projects, and with Scrivener’s new styles system, you can get the best of both worlds: writing in a rich text editor, with easy annotations, comments, footnotes and display of images, but the flexibility to export to any kind of format. Ian also provides links on his Github page to an Alfred workflow so that you can run Scrivomatic/Pandocomatic on a file selected in Alfred, and there’s a very useful set of tools for using Bookends with Alfred.


  1. One of the few reasons that I still bother with web analytics is because I frequently find out about interesting stuff through my referrer logs. ↩︎

  2. So a wrapper around a wrapper around a command — it’s like a game of ‘pass the parcel’! ↩︎