diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 27 |
1 files changed, 17 insertions, 10 deletions
@@ -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> |