A YAML metadata block is a valid YAML object, delimited by a line of three hyphens (---
) at the top and a line of three hyphens (---
) or three dots (...
) at the bottom. A YAML metadata block may occur anywhere in the document, but if it is not at the beginning, it must be preceded by a blank line. (Note that, because of the way pandoc concatenates input files when several are provided, you may also keep the metadata in a separate YAML file and pass it to pandoc as an argument, along with your Markdown files:
pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
Just be sure that the YAML file begins with ---
and ends with ---
or ...
.) Alternatively, you can use the --metadata-file
option. Using that approach however, you cannot reference content (like footnotes) from the main markdown input document.
Metadata will be taken from the fields of the YAML object and added to any existing document metadata. Metadata can contain lists and objects (nested arbitrarily), but all string scalars will be interpreted as Markdown. Fields with names ending in an underscore will be ignored by pandoc. (They may be given a role by external processors.) Field names must not be interpretable as YAML numbers or boolean values (so, for example, yes
, True
, and 15
cannot be used as field names).
A document may contain multiple metadata blocks. The metadata fields will be combined through a left-biased union: if two metadata blocks attempt to set the same field, the value from the first block will be taken.
When pandoc is used with -t markdown
to create a Markdown document, a YAML metadata block will be produced only if the -s/--standalone
option is used. All of the metadata will appear in a single block at the beginning of the document.
Note that YAML escaping rules must be followed. Thus, for example, if a title contains a colon, it must be quoted. The pipe character (|
) can be used to begin an indented block that will be interpreted literally, without need for escaping. This form is necessary when the field contains blank lines or block-level formatting:
---
title: 'This is the title: it contains a colon'
author:
- Author One
- Author Two
keywords: [nothing, nothingness]
abstract: |
This is the abstract.
It consists of two paragraphs.
...
Template variables will be set automatically from the metadata. Thus, for example, in writing HTML, the variable abstract
will be set to the HTML equivalent of the Markdown in the abstract
field:
<p>This is the abstract.</p>
<p>It consists of two paragraphs.</p>
Variables can contain arbitrary YAML structures, but the template must match this structure. The author
variable in the default templates expects a simple list or string, but can be changed to support more complicated structures. The following combination, for example, would add an affiliation to the author if one is given:
---
title: The document title
author:
- name: Author One
affiliation: University of Somewhere
- name: Author Two
affiliation: University of Nowhere
...
To use the structured authors in the example above, you would need a custom template:
$for(author)$
$if(author.name)$
$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
$else$
$author$
$endif$
$endfor$
Raw content to include in the document’s header may be specified using header-includes
; however, it is important to mark up this content as raw code for a particular output format, using the raw_attribute
extension), or it will be interpreted as markdown. For example:
header-includes:
- |
```{=latex}
\let\oldsection\section
\renewcommand{\section}[1]{\clearpage\oldsection{#1}}
```