pandoc/doc/customizing-pandoc.md

This document provides a quick overview over the various ways to customize pandoc's output. Follow the links to learn how to use each approach.

Templates

Pandoc comes with a template for (almost) every output format. A template is a plain text file, that contains for example the line $body$. That variable is replaced by the document's body text on output.

There are many other variables, like title, header-includes, etc. that are either set automatically, or that you can set using YAML metadata blocks, --metadata (which properly escape things), or --variable (which does no escaping). You can also generate your own template (e.g. pandoc -D html > myletter.html) and customize that file, for example by introducing new variables.

reference.docx/pptx/odt

To output a docx, pptx or odt document, which is a ZIP of several files, things are a bit more complicated. Instead of a single template file, you need to provide a customized reference.docx/pptx/odt.

Lua filters and filters

Templates are very powerful, but they are only a sort of scaffold to place your document's body text in. You cannot directly change the body text using the template (beyond e.g. adding CSS for HTML output, or \renewcommand for LaTeX output).

If you need to affect the output of the actual body text, you probably need a pandoc filter. A filter is a small program, that transforms the document, between the parsing and the writing phase, while it is still in pandoc's native format -- an abstract syntax tree (AST), not unlike the HTML DOM. As can be seen in the AST definition Pandoc Meta [Block], a pandoc document is a chunk of metadata and a list of Blocks.

• There's a list of third party filters on the wiki.
• Unless you have a good reason not to, it's best to write your own filter in the Lua scripting language. Since pandoc ships with a Lua interpreter, Lua filters are very portable and efficient. See Lua filters.
• For a gentle introduction into filters and writing them in any programming language, see filters.

Furthecustomizations

• Custom Styles in Docx
• If you're converting from Markdown, see
  • Generic raw attributes: to include raw snippets
  • Divs and Spans: generic blocks that can be transformed with filters
• Custom syntax highlighting, provided by the skylighting library
• Custom writers
• Pandoc Extras wiki page