From 0e2605ffdf69b7a6a7c942a986dec4283a886e82 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sun, 18 Aug 2013 18:39:04 -0700 Subject: Allow multiple YAML metadata blocks in document. --- README | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) (limited to 'README') diff --git a/README b/README index c1429aec3..7a2b01f49 100644 --- a/README +++ b/README @@ -1815,14 +1815,21 @@ YAML metadata block **Extension: `yaml_metadata_block`** -If the file begins with a YAML object, delimited by a line of three -hyphens (`---`) at the top and a line of three hyphens (`---`) or three -dots (`...`) at the bottom, metadata will be taken from the fields -of the YAML object. 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.) +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. + +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.) + +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. Note that YAML escaping rules must be followed. Thus, for example, if a title contains a colon, it must be quoted. The pipe character @@ -1844,8 +1851,8 @@ when the field contains blank lines: It consists of two paragraphs. ... -Template variables will be set from the metadata. Thus, for example, -in writing HTML, the variable `abstract` will be set to the HTML +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:

This is the abstract.

-- cgit v1.2.3