pandoc_templates

Pandoc templates

Pandoc uses templates to help translate documents. Templates help add information that is needed to compile a document but is not included in the main file that you are editing. For example, think about all of the text that comes before \begin{document} in a native .tex file. This information is missing in markdown files. Pandoc adds all of this header information for you.

To see what is added by default, add -D to a call to pandoc navigate to see a default template. You can also save this output to a file (e.g., pandoclatextamplate.tex) or call a different template other than the one for latex by changing the statement after -D to html or opendocument.

pandoc -D latex
pandoc -D latex >> pandoclatextemplate.tex

Users can write their own custom templates that set and manipulate the resulting output, but be aware that pandoc is constantly changing, and thus, your custom template might also need to change. Therefore, the most sustainable development path going forward is to fork and clone the repository that stores the code for pandoc and implement your changes to the forked version of the default template. Then add changes, commit them, and rebase from the upstream master branch. This workflow ensures that your template is always compatible with the most recent version of pandoc. Additional templates are located in the rstudio repository as well.

Variables

Pandoc templates use variables to set information. These variables can be set in style files, YAML headers, or using pandoc -V/--variable. The default method when dealing with markdown files is to set variables in the YAML header.

Variables in a YAML header

For example, the following sets the author in the metadata (i.e., title-meta) and on the title page to Kelli Faye Johnson and includes the longtable LaTeX package in the header information of the resulting .tex file.

---
author: Kelli Faye Johnson
table: yes
---

Typically, users don't need to access metadata and are instead more concerned about text that is actually rendered in the document. Regardless, pandoc sets metadata behind the scenes. If you have markdown tables in your .md file, the latter will be turned on by default; but if you only include tables using latex code inside .md files, then you must turn on tables. Additionally, you can add YAML fields and then call them in your template file. This is also how author and the language (lang: en-GB) is set.

There is a long list of variables that are specific to beamer slides, for example aspectratio sets the slide aspect ratio to 43 by default, which results in 4:3. Lots of the other options pertain to the theme, but see the pandoc documentation for further information.

There is a long list of variables that are specific to creating a pdf. These variables are specific to the engine used, but are similar across engines. For example, natbiboptions lists the options for natbib.

Body variable

The body of a LaTeX document, defined in a template via $body$ will be the code generated from the Markdown document, e.g., everything after the YAML header. The body will typically go between the \begin{document} and \end{document} clauses.

Delimiters around variables in a template

$foo$
$foo.bar.baz$
$foo$

where the variable name, here foo, must start with a letter but it can contain letters, numbers, underscores, hyphens, or full stops. Full stops are used to create structure, e.g., foo.foolish will return foolish, which is a field of foo.

Conditional statements in a template

Conditionals begin with if(variable) and end with endif with optional else statements inside the conditional. If statements are used when the variable has a non-empty value, otherwise the else statement will be evaluated. elseif can be used to simplify nested conditionals, though I don't quite understand them yet.

$if(foo)$
part one
$else$
part two
$endif$

% Set the language of the document
$if(lang)$
  pdflang={$lang$},
$endif$

% Pass more options to packages, which is safe if they are already loaded
\PassOptionsToPackage{hyphens}{url}

For statements in a template

Loops begin with for(variable) and end with endifor. If the variable is an array, then the material inside the loop will be evaluated repeatedly and variable will be set to each value of the array in turn and concatenated. If variable is a map, then the material inside will be set to the map. The variable it can be used instead of the variable name inside the for loop.

Comments in a template

$-- to the end of the line will be a comment

Though, I think you can use % too, which is more standard.