What is the minimal "API" a pandoc template must provide

Question

I was trying to define my own pandoc template for job reports and I stumbled across many "undefined control sequence" problems. I have taken a look at the default template but it's too generic to really be understood.

I have written this and I don't want my template to be much more complex (i.e. no conditionals), the reason being I'd rather use \LaTeX to specify high-level typesseting options (that's what it was made for) and leave the YAML at a minimum.

\documentclass[11pt]{article}

\usepackage{fontspec,xltxtra,xunicode}

\setmainfont[
    BoldFont={Fira Sans SemiBold}, 
    BoldItalicFont={Fira Sans SemiBold Italic}
]{Fira Sans Book}
\setmonofont[
    Contextuals={Alternate}
]{Fira Code Retina}

\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

\begin{document}
$body$
\end{document}

Considering I already had to provide the \tightlistcommand, I would like to know what API does pandoc expect from my template, i.e. which functions / commands I would need to define in order to pandoc to just work. I would write it in pure LaTeX but I also need to upload these documents to a GitLab repository, so markdown is the simplest solution.

I also haven't found any good, "for dummies" guide on writting pandoc templates, so if it exists, pointing me to that will be greatly appreciated.

Edit: the template I provided is throwing errors when using Pandoc (although may be a problem with my command flags: pandoc -N --template=mytemplate.tex --pdf-engine=xelatex my_doc.md -o my_doc.pdf). I say this because the answer suggests that this template should work, but it's not :(

Answer 1

There is, as far as I know, currently no document which gives a full specification. Part of the reason is that a lot depends on the input document: one can get away with less complexity if one is willing to make certain assumptions about the input. E.g., \tightlist is only required if the document contains such lists, \usepackage{graphix} is not needed unless you have images or a logo specified somewhere, etc. The default template also concerns itself with verbatim in unexpected places (footnotes), "i18n" support for other languages, different LaTeX engines (pdflatex vs. xelatex vs. lualatex), and so on. The template tries to carefully handle all possible inputs in a sensible way. In that sense, the default template is already minimal.

Dealing with simple inputs, it should be perfectly fine to use a template like yours. Extend and modify that template as you hit an issue. This will work well if your inputs are simple enough.

If the expectation is that the template should work even for arbitrarily complex markdown documents, then one should go the other way: get the default template (via pandoc -D latex > my-template.tex) and get rid of or replace things as one sees fit. One would likely remove everything that deals with beamer presentations, and, as you seem to dislike YAML, most pandoc-template checks like $if(…)$ … $endif$, commit to a specific LaTeX engine by dropping all xetex/luatex checks, and hard-code all packages that one intents to use. I speak from experience when I say that this is a lot of work; I do not recommend it.

The third option would of course be to deal with the way pandoc is usually used, and customize the output via a YAML file and a file to include in the header (via -H). This has the advantage that one will profit from updates to pandoc's default template without having to port them to a custom template. More often than not, this is the simplest method, and hence the one I'd recommend.

Answer 2

As @tarleb notes, you need to include the appropriate packages/code for the features your text uses.

To replicate your example, you don't need to create a custom template at all; you can achieve the same thing by using the variables within the default template, adding this to the YAML front matter in your document:

---
fontsize: 11pt
mainfont: Fira Sans Book
mainfontoptions:
- BoldFont={Fira Sans SemiBold}
- BoldItalicFont={Fira Sans SemiBold Italic}
monofont: Fira Code Retina
monofontoptions:
- Contextuals={Alternate}
---