Allow multiple YAML metadata blocks in document.

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>