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 docs didn't mention this option to control table of contents using the YAML header. Furthermore, I see somewhat arbitrary lines in example documents on the same Pandoc readme site.

Main question:

• What Pandoc options are available using the YAML header?

Meta-question:

• What determines the available Pandoc options that are available to set using the YAML header?

Note: my workflow is to use Markdown files (.md) and process them through Pandoc to get PDF files. It has hierarchically organized manuscript writing with math. Such as:

pandoc --standalone --smart \
    --from=markdown+yaml_metadata_block \
    --filter pandoc-citeproc \
    my_markdown_file.md \
    -o my_pdf_file.pdf

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:

<title>$title$</title>

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:

`<script>alert()</script>`{=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).