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

Babur

If you can read Haskell then the answer is available at github.com/jgm/pandoc/search?utf8=%E2%9C%93&q=yaml – Photogene

@Photogene I might be able to learn it. But I was hoping for a natural language explanation or overview. E.g. a description of the architecture or something. Thanks, though, I'll look at it! – Babur

I cannot read Haskell myself (and don't want to learn it) and I don't know about credible description of internal pandoc's behavior other then its source code, so I don't know what is the answer, just tried to be helpful until pandoc's author (stackoverflow.com/users/1261777/john-macfarlane) shows up – Photogene

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

Asperity

Does it say explicitly clearly anywhere, that all variables have support to have their values from a YAML metadata block? Additionally I'd like to mention, that putting the metadata block into the template is only in some cases and for some variables a good idea. Document specific variables like a title should always be defined in the respective document, so that the template may be used for other documents unchanged (since it's a template and that's what templates are for). – Brimstone

I don't understand how this answer to question. The information that seems to me to be missing is this: Which options to Pandoc can be set as "variables"? All of them? (You say that variables can be set in Yaml headers.) Can Yaml headers set only variables? Or is there options that are not variables? Can Yaml headers set those? (Can, for example, an extension be enabled in a Yaml header?) – Bennybenoit

@Bennybenoit The answer explains that variables can be assigned values with the help of YAML blocks. Whether these variables are used in the generated output depends on the template being used (by specifying the output format). The built-in default templates for HTML and latex both use the toc variable to control showing the table of contents. You may invent your own variables and extend templates accordingly. – Hamate

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

```

Skyjack

This focuses on the fact that some variables can also be set via command line switch. This indirectly makes clear that YAML blocks are just an option. – Hamate

Answer 3

You can see the documentation of pandoc for a clue: http://pandoc.org/getting-started.html

But to know exactly where it will be used you can look for templates sources of pandoc: https://github.com/jgm/pandoc-templates

For example, for the html5 output the file is: https://github.com/jgm/pandoc-templates/blob/master/default.html5

Here's an section of the code:

<title>$if(title-prefix)$$title-prefix$ - $endif$$pagetitle$</title>

As you can see it has title-prefix and pagetitle.

You can look the documentation, but the best solution is to look for the source code of the version you are using.

Testudinal

Answer 4

The pandoc main page now contains a list of options and explanations for them:

https://pandoc.org/MANUAL.html#variables

It seems to be the same as the one when looking at man pandoc.

Basilio