40
PandocUser’sGuide
Pandoc’sMarkdown
Extension:yaml_metadata_block
AYAMLmetadatablockisavalidYAMLobject,delimitedbyalineofthreehyphens(---)atthetop
andalineofthreehyphens(---)orthreedots(...)atthebottom.AYAMLmetadatablockmayoccur
anywhereinthedocument,butifitisnotatthebeginning,itmustbeprecededbyablankline.(Note
that,becauseofthewaypandocconcatenatesinputfileswhenseveralareprovided,youmayalsokeep
themetadatainaseparateYAMLfileandpassittopandocasanargument,alongwithyourMarkdown
files:
pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
JustbesurethattheYAMLfilebeginswith---andendswith---or....)
MetadatawillbetakenfromthefieldsoftheYAMLobjectandaddedtoanyexistingdocumentmetadata.
Metadatacancontainlistsandobjects(nestedarbitrarily),butallstringscalarswillbeinterpretedas
Markdown.Fieldswithnamesendinginanunderscorewillbeignoredbypandoc.(Theymaybegiven
arolebyexternalprocessors.)
Adocumentmaycontainmultiplemetadatablocks. Themetadatafieldswillbecombinedthrougha
left-biasedunion: iftwometadatablocksattempttosetthesamefield,thevaluefromthefirstblock
willbetaken.
Whenpandocisusedwith-t markdowntocreateaMarkdowndocument,aYAMLmetadatablockwill
beproducedonlyifthe-s/--standaloneoptionisused. Allofthemetadatawillappearinasingle
blockatthebeginningofthedocument.
NotethatYAMLescapingrulesmustbefollowed.Thus,forexample,ifatitlecontainsacolon,itmustbe
quoted.Thepipecharacter(|)canbeusedtobeginanindentedblockthatwillbeinterpretedliterally,
withoutneedforescaping.Thisformisnecessarywhenthefieldcontainsblanklines:
---
title: 'This is the title: it contains a colon'
author:
- name: Author One
affiliation: University of Somewhere
- name: Author Two
affiliation: University of Nowhere
tags: [nothing, nothingness]
abstract: |
This is the abstract.
It consists of two paragraphs.
...
Templatevariableswillbesetautomaticallyfromthemetadata. Thus,forexample,inwritingHTML,
thevariableabstractwillbesettotheHTMLequivalentoftheMarkdownintheabstractfield:
v1.17.0.3
40