@@ -733,7 +733,8 @@ will be replaced by the document title.
733733To write a literal `$` in a template, use `$$`.
734734
735735Some variables are set automatically by pandoc. These vary somewhat
736−depending on the output format, but include:
736+depending on the output format, but include metadata fields (such
737+as `title`, `author`, and `date`) as well as the following:
737738
738739`header-includes`
739740: contents specified by `-H/--include-in-header` (may have multiple
@@ -748,13 +749,6 @@ depending on the output format, but include:
748749 multiple values)
749750`body`
750751: body of document
751−`title`
752−: title of document, as specified in title block
753−`author`
754−: author of document, as specified in title block (may have
755− multiple values)
756−`date`
757−: date of document, as specified in title block
758752`lang`
759753: language code for HTML or LaTeX documents
760754`slidy-url`
@@ -801,8 +795,8 @@ depending on the output format, but include:
801795: footer in man pages
802796
803797Variables may be set at the command line using the `-V/--variable`
804−option. This allows users to include custom variables in their
805−templates.
798+option. Variables set in this way override metadata fields with
799+the same name.
806800
807801Templates may contain conditionals. The syntax is as follows:
808802
@@ -829,6 +823,11 @@ consecutive items:
829823
830824 $for(author)$$author$$sep$, $endfor$
831825
826+A dot can be used to select a field of a variable that takes
827+an object as its value. So, for example:
828+
829+ $author.name$ ($author.affiliation$)
830+
832831If you use custom templates, you may need to revise them as pandoc
833832changes. We recommend tracking the changes in the default templates,
834833and modifying your custom templates accordingly. An easy way to do this
@@ -1780,7 +1779,42 @@ YAML metadata block
17801779
17811780**Extension: `yaml_metadata_block`**
17821781
1783−TODO
1782+If the file begins with a YAML object, delimited by a line of three
1783+hyphens (`---`) at the top and a line of three hyphens (`---`) or three
1784+dots (`...`) at the bottom, metadata will be taken from the fields
1785+of the YAML object. Metadata can contain lists and objects (nested
1786+arbitrarily), but all string scalars will be interpreted as markdown.
1787+
1788+Fields with names ending in an underscore will be ignored by
1789+pandoc. (They may be given a role by external processors.)
1790+
1791+Note that YAML escaping rules must be followed. Thus, for example,
1792+if a title contains a colon, it must be quoted. The pipe character
1793+(`|`) can be used to begin an indented block that will be interpreted
1794+literally, without need for escaping. This form is necessary
1795+when the field contains blank lines:
1796+
1797+ ---
1798+ title: 'This is the title: it contains a colon'
1799+ author:
1800+ - name: Author One
1801+ affiliation: University of Somewhere
1802+ - name: Author Two
1803+ affiliation: University of Nowhere
1804+ tags: [nothing, nothingness]
1805+ abstract: |
1806+ This is the abstract.
1807+
1808+ It consists of two paragraphs.
1809+ ...
1810+
1811+Template variables will be set from the metadata. Thus, for example,
1812+in writing HTML, the variable `abstract` will be set to the HTML
1813+equivalent of the markdown in the `abstract` field:
1814+
1815+ <p>This is the abstract.</p>
1816+ <p>It consists of two paragraphs.</p>
1817+
17841818
17851819Backslash escapes
17861820-----------------