Combining yaml metadata (header-includes) with Pandoc

Question

If I have these files:

text.md:

---
header-includes:
- \usepackage{pgf-pie}
---

\begin{tikzpicture}
\pie{50/, 50/}
\end{tikzpicture}

settings.yaml:

variables:
    header-includes:
    - \pagecolor{black}

and I compile them with pandoc with the command:

pandoc text.md -d settings -o text.pdf

...the header-includes value in the defaults file settings.yaml will overwrite the metadata block in text.md, thus failing to compile.

Is there a way to get pandoc to combine the two header-includes lists instead?

Answer 1

Combining these header-includes lists is not possible.

There are two reasons to this: One, the values from the defaults file always take precedence. In addition, if a name is used both as as a variable and in the metadata, then the variable will be used.

For additional info and discussions of this topic, see these pandoc GitHub issues:

• Command-line options --css and --include-in-header override corresponding metadata fields instead of accumulating
• Allow defaults to be folded into YAML metadata

---

A possible workaround would be to use a "new style" custom writer, as these provide write access to both metadata and variables:

function Writer (doc, opts)
  local includes_tmpl = pandoc.template.compile('$header-includes$')
  local vars = {['header-includes'] = opts.variables['header-includes'] or ''}

  -- Write header-includes, once with variables, once without (thus
  -- allowing metadata values to be used instead)
  opts.variables['header-includes'] =
    pandoc.write(doc, 'latex', {template=includes_tmpl, variables=vars}) ..
    '\n' ..
    pandoc.write(doc, 'latex', {template=includes_tmpl})

  return pandoc.write(doc, 'latex', opts)
end

Note, however, that this currently requires the development version, so you'd need to use a nightly build. You'll also need to explicitly specify the template and PDF engine, e.g., --template=default.latex --pdf-engine=xelatex.