summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README27
1 files changed, 17 insertions, 10 deletions
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:
<p>This is the abstract.</p>