6

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.

Community
  • 1
  • 1
Benjohn
  • 13,228
  • 9
  • 65
  • 127
  • I wrote a small script that sets pandoc command-line options from the YAML metadata: https://github.com/mb21/panrun – mb21 Sep 18 '18 at 14:05

2 Answers2

5

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.

scoa
  • 19,359
  • 5
  • 65
  • 80
  • Great, thanks. That all makes sense. While not perfect (and a bit brittle if the templates are mushed about), that'll do for me until an improvement comes along. – Benjohn May 27 '15 at 17:04
3

Have a look at panzer (GitHub repository).

This was recently announced and released by Mark Sprevak -- a piece of software, that adds the notion of 'styles' to Pandoc.

It's basically a wrapper around Pandoc. It exploits the concept of YAML metadata blocks to the maximum.

The 'styles' provide a way to set all options for a Pandoc document conversion process with one line ("I want this document be an article/CV/notes/letter.").

You can regard this as more general abstraction than Pandoc templates. Styles are combinations of...

  • ...Pandoc command line options,
  • ...metadata settings,
  • ...templates,
  • ...instructions to run filters, and
  • ...instructions to run pre/postprocessors.

These settings can be customized on a per output type as well as a per document basis. Styles can be...

  • ...combined and
  • ...can bear inheritance relations to each other.

panzer styles simplify Makefiles: they bundle everything concerning the look of a document in one place -- the YAML metadata (a block in the Markdown file, or a separate file).

You just add one line of metadata (style: ...) to your document, and it will be treated as a letter/article/CV/notebook or whatever.

Kurt Pfeifle
  • 86,724
  • 23
  • 248
  • 345