markdown - Can I set command line arguments using the YAML metadata

Question

Pandoc supports a YAML metadata block in markdown documents. This can set the title and author, etc. It can also manipulate the appearance of the PDF output by changing the font size, margin width and the frame sizes given to figures that are included. Lots of details are given here.

I'd like to use the metadata block to remember the command line arguments that I'm supposed to be using, such as --toc and --number-sections. I tried this, adding the following to the top of my markdown:

---
title: My Title
toc: yes
number-sections: yes

---

Then I used the command line:

pandoc -o guide.pdf articheck_guide.md

This did produce a table of contents, but didn't number the sections. I wondered why this was, and if there is a way I can specify this kind of thing from the document so that I don't need to add it on the command line.

Answer 1

YAML metadata are not passed to pandoc as arguments, but as variables. When you call pandoc on your MWE, it does not produce this :

pandoc -o guide.pdf articheck_guide.md --toc --number-sections

as we think it would. rather, it calls :

pandoc -o guide.pdf articheck_guide.md -V toc:yes -V number-sections:yes

Why, then, does you MWE produces a toc? Because the default latex template makes use of a toc variable :

~$ pandoc -D latex | grep toc

$if(toc)$
setcounter{tocdepth}{$toc-depth$}

So setting toc to any value should produce a table of contents, at least in latex output. In this template, there is no number-sections variables, so this one doesn't work. However, there is a numbersections variable :

~$ pandoc -D latex | grep number

$if(numbersections)$

Setting numbersections to any value will produce numbering in a latex output with the default template

---
title: My Title
toc: yes
numbersections: yes
---

The trouble with this solution is that it only works with some output format. I thought I had read somewhere on the pandoc mailing-list that we soon would be able to use metadata in YAML blocks as intended (ie. as arguments rather than variables), but I can't find it anymore, so maybe it won't happen very soon.