Mastering Master Documents with Pandoc – Part 2

Markdown on Steroids

In the previous article, I talked about the need for a master document system, why Markdown is a surprisingly good language for it, and how Pandoc can use Markdown to create documents in almost every format you might want. Here, I’m going to look at how Pandoc can take plain, boring Markdown and turn it into beautiful documents formatted just the way you want.

There are two ways to spice up your Markdown add style to your master documents: external stylesheets and inline tags.

I’m using the term "stylesheet" loosely here to mean not just CSS but templates and "reference documents". Starting with CSS, let’s unpack this command:

pandoc -s --toc -c pandoc.css -H header.html -A footer.html my_document.md -o my_document.html

First you have the -s option to tell pandoc to create a standalone HTML document rather than a fragment. Next, you have --toc, which generates a table of contents. The -c option points to our CSS file, and -H and -A point to files with code to be inserted immediately before and after the HTML body respectively. Producing HTML pages like this is a nice case of separating formatting and content; if you have a lot of different people writing occasional posts for your website, for example, you can just tell them a couple of basic Markdown commands you want them to use, like hashtags for headings and asterisks for emphasis, then have Pandoc do all the formatting magic. In the long term this is a lot easier than dealing with a bunch quirkily formatted Word documents. You can even use this kind of CSS formatting to produce PDFs if you have the appropriate HTML engine installed, which is great if you’re into CSS Paged Media.

If you prefer to use LaTeX to generate your PDF output, you can customise the default.latex template and point to it with the --template option. Alternatively, you can specify LaTeX options in your command, such as this monstrous example adapted from the Pandoc Demos page:

pandoc -N --variable "geometry=margin=1.2in" --variable mainfont="Palatino" --variable sansfont="Helvetica" --variable monofont="Menlo" --variable fontsize=12pt --variable version=2.0 my_document.md --include-in-header fancyheaders.tex --pdf-engine=xelatex --toc -o my_document.pdf

I’ll leave it to the TeXperts among you to work all that out!

There is a customisable template for ODT files, but of course it is rare that we have to use LibreOffice for output rather than input; what we need more often, unfortunately, is an easy way to produce Word and PowerPoint documents, formatted according to the needs of our school or company, and this is where Pandoc really shines. There are no Word or PowerPoint templates as such; rather there is a "reference document", which is a Pandoc-generated file that you can make a copy of with the command pandoc -o custom-reference.docx --print-default-data-file reference.docx. (Actually, I just used a Word document I wrote in LibreOffice, but using the Pandoc one is more reliable.) Customise that document any way you like and either put it where your markdown files are, or point to it with the --reference-doc option. Again, this is very useful when you are coordinating input from a lot of different writers because even if you give people a Word template, most of them will still format manually rather than using the styles provided (as anyone who has edited conference proceedings will tell you).

Most versions of Markdown allow you to insert HTML tags if you need something fancier than the standard Markdown commands; all things being equal, anything inside angle brackets will be interpreted as HTML, as will anything inside <div> tags. There are also some extensions that allow you to add HTML/CSS formatting without actually having to write HTML. Here’s an example of an image where the dimensions and title are specified:

![](image2.jpg "Editing a content page"){.img-responsive width="1028" height="483"}

And here’s an example of a level 2 heading with an identifier and a class:

## More Pandoc Magic{#MPM .subhead}

You can even use the curly-brackets syntax to specify custom styles in your Word reference document; for example, Do [not]{custom-style="superemphasised"} ask the learning technologist to phone you. will render the "not" in your custom style "superemphasised" (e.g., bold red italics).

Finally, for the TeXperts, Pandoc will interpret LaTeX commands such as \cite inside Markdown, and anything between \begin{} and \end{} commands will be interpreted as raw (La)TeX.

Although my emphasis here has been on Markdown, you can also use Pandoc as a document converter without writing any Markdown at all or, for that matter, to convert documents to rather than from Markdown. If you only need to convert a few documents, it may be easier to use an online converter like Zamzar, but Pandoc’s command line format means it can be included in scripts to batch convert files (which is how I dealt with that pesky Moodle Book that I mentioned in Part 1).

There is much, much more that can be done with Pandoc, so if your appetite is whetted, I recommend browsing the Pandoc Manual. Or if it all sounds like too much work, come back to it when your boss mails you fifty Word documents and asks you to make them into a website and a PDF.