What can I control with YAML header options in pandoc?

Question

Only by chance did I see an example document using the toc: true line in their YAML header options in a Markdown file to be processed by Pandoc. And the Pandoc

Answer 1

Almost everything set in the YAML metadata has only an effect through the pandoc template in use.

Pandoc templates may contain variables. For example in your HTML template, you could write:

These template variables can be set with the --variable KEY[=VAL] option.

However, they are also set from the document metadata, which in turn can be set either by using:

• the --metadata KEY[=VAL] option,
• a YAML metadata block, or
• the --metadata-file option.

The --variable options inserts strings verbatim into the template, while --metadata escapes strings. Strings in YAML metadata (also when using --metadata-file) are interpreted as markdown, which you can circumvent by using pandoc markdown's generic raw attributes. For example for HTML output:

``{=html}

See this table for a schematic:

|                        | --variable        | --metadata        | YAML metadata and --metadata-file |
|------------------------|-------------------|-------------------|-----------------------------------|
| values can be…         | strings and bools | strings and bools | also YAML objects and lists       |
| strings are…           | inserted verbatim | escaped           | interpreted as markdown           |
| accessible by filters: | no                | yes               | yes                               |

To answer your question: the template determines what fields in the YAML metadata block have an effect. To view, for example, the default latex template, use:

$ pandoc -D latex

To see some variables that are set automatically by pandoc, see the Manual. Finally, other behaviours of pandoc (such as markdown extensions, etc) can only be set as command-line options (except when using a wrapper script).