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).

Answer 2

It is a rather long list that you can browse by running man pandoc in the command line and navigating to "Variables set by pandoc" section under "TEMPLATES."

The top of the list includes the following among many other options:

Variables set by pandoc    Some variables are set automatically by pandoc.  These vary somewhat depending  on  the    output format, but include metadata fields as well as the following:     title, author, date           allow identification of basic aspects of the document.  Included in PDF metadata           through LaTeX and ConTeXt.  These can be set through a pandoc title block, which           allows for multiple authors, or through a YAML metadata block:                   ---                  author:                  - Aristotle                  - Peter Abelard                  ...     subtitle           document subtitle; also used as subject in PDF metadata     abstract           document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx     keywords           list  of  keywords  to  be  included in HTML, PDF, and AsciiDoc metadata; may be           repeated as for author, above     header-includes           contents specified by -H/--include-in-header (may have multiple values)     toc    non-null value if --toc/--table-of-contents was specified     toc-title           title of table of contents (works only with EPUB and docx)     include-before           contents specified by -B/--include-before-body (may have multiple values)     include-after           contents specified by -A/--include-after-body (may have multiple values)     body   body of document 

```