@@ -1438,9 +1438,268 @@ directory (see `--data-dir`, above). *Exceptions:*
14381438Templates contain *variables*, which allow for the inclusion of
14391439arbitrary information at any point in the file. They may be set at the
14401440command line using the `-V/--variable` option. If a variable is not set,
1441−pandoc will look for the key in the document's metadata – which can be set
1441+pandoc will look for the key in the document's metadata, which can be set
14421442using either [YAML metadata blocks][Extension: `yaml_metadata_block`]
1443−or with the `-M/--metadata` option.
1443+or with the `-M/--metadata` option. In addition, some variables
1444+are given default values by pandoc.
1445+
1446+If you use custom templates, you may need to revise them as pandoc
1447+changes. We recommend tracking the changes in the default templates,
1448+and modifying your custom templates accordingly. An easy way to do this
1449+is to fork the [pandoc-templates] repository and merge in
1450+changes after each pandoc release.
1451+
1452+ [pandoc-templates]: https://github.com/jgm/pandoc-templates
1453+
1454+Template syntax
1455+---------------
1456+
1457+To mark variables and control structures in the template, either
1458+`$`...`$` or `${`...`}` may be used as delimiters. The styles
1459+may also be mixed in the same template, but the opening and
1460+closing delimiter must match in each case. The opening
1461+delimiter may be followed by one or more spaces or tabs, which
1462+will be ignored. The closing delimiter may be followed by one or
1463+more spaces or tabs, which will be ignored.
1464+
1465+To include a literal `$` in the document, use `$$`.
1466+
1467+### Comments
1468+
1469+Anything between the sequence `$--` and the end of the
1470+line will be treated as a comment and omitted from the output.
1471+
1472+### Interpolated variables
1473+
1474+A slot for an interpolated variable is a variable name surrounded
1475+by matched delimiters. Variable names must begin with a letter
1476+and can contain letters, numbers, `_`, `-`, and `.`. The
1477+keywords `it`, `if`, `else`, `endif`, `for`, `sep`, and `endfor` may
1478+not be used as variable names. Examples:
1479+
1480+```
1481+$foo$
1482+$foo.bar.baz$
1483+$foo_bar.baz-bim$
1484+$ foo $
1485+${foo}
1486+${foo.bar.baz}
1487+${foo_bar.baz-bim}
1488+${ foo }
1489+```
1490+
1491+Variable names with periods are used to get at structured
1492+variable values. So, for example, `employee.salary` will return the
1493+value of the `salary` field of the object that is the value of
1494+the `employee` field.
1495+
1496+- If the value of the variable is simple value, it will be
1497+ rendered verbatim. (Note that no escaping is done;
1498+ the assumption is that the calling program will escape
1499+ the strings appropriately for the output format.)
1500+- If the value is a list, the values will be concatenated.
1501+- If the value is a map, the string `true` will be rendered.
1502+- Every other value will be rendered as the empty string.
1503+
1504+The value of a variable that occurs by itself on a line
1505+will be indented to the same level as the opening delimiter of
1506+the variable.
1507+
1508+### Conditionals
1509+
1510+A conditional begins with `if(variable)` (enclosed in
1511+matched delimiters) and ends with `endif` (enclosed in matched
1512+delimiters). It may optionally contain an `else` (enclosed in
1513+matched delimiters). The `if` section is used if
1514+`variable` has a non-empty value, otherwise the `else`
1515+section is used (if present). (Note that even the
1516+string `false` counts as a true value.) Examples:
1517+
1518+```
1519+$if(foo)$bar$endif$
1520+
1521+$if(foo)$
1522+ $foo$
1523+$endif$
1524+
1525+$if(foo)$
1526+part one
1527+$else$
1528+part two
1529+$endif$
1530+
1531+${if(foo)}bar${endif}
1532+
1533+${if(foo)}
1534+ ${foo}
1535+${endif}
1536+
1537+${if(foo)}
1538+${ foo.bar }
1539+${else}
1540+no foo!
1541+${endif}
1542+```
1543+
1544+The keyword `elseif` may be used to simplify complex nested
1545+conditionals. Thus
1546+
1547+```
1548+$if(foo)$
1549+XXX
1550+$elseif(bar)$
1551+YYY
1552+$else$
1553+ZZZ
1554+$endif$
1555+```
1556+
1557+is equivalent to
1558+
1559+```
1560+$if(foo)$
1561+XXX
1562+$else$
1563+$if(bar)$
1564+YYY
1565+$else$
1566+ZZZ
1567+$endif$
1568+$endif$
1569+```
1570+
1571+### For loops
1572+
1573+A for loop begins with `for(variable)` (enclosed in
1574+matched delimiters) and ends with `endfor` (enclosed in matched
1575+delimiters. If `variable` is an array, the material inside
1576+the loop will be evaluated repeatedly, with `variable` being set
1577+to each value of the array in turn. If the value of the
1578+associated variable is not an array, a single iteration will be
1579+performed on its value.
1580+
1581+Examples:
1582+
1583+```
1584+$for(foo)$$foo$$sep$, $endfor$
1585+
1586+$for(foo)$
1587+ - $foo.last$, $foo.first$
1588+$endfor$
1589+
1590+${ for(foo.bar) }
1591+ - ${ foo.bar.last }, ${ foo.bar.first }
1592+${ endfor }
1593+```
1594+
1595+You may optionally specify a separator between consecutive
1596+values using `sep` (enclosed in matched delimiters). The
1597+material between `sep` and the `endfor` is the separator.
1598+
1599+```
1600+${ for(foo) }${ foo }${ sep }, ${ endfor }
1601+```
1602+
1603+Instead of the variable name, the special anaphoric keyword `it`
1604+may be used inside the loop.
1605+
1606+```
1607+${ for(foo.bar) }
1608+ - ${ it.last }, ${ it.first }
1609+${ endfor }
1610+```
1611+
1612+### Partials
1613+
1614+Partials (subtemplates stored in different files) may be
1615+included using the syntax
1616+
1617+```
1618+${ boilerplate() }
1619+```
1620+
1621+Partials will be sought in the directory containing
1622+the main template, and will be assumed to have the
1623+same extension as the main template if they lack
1624+an explicit extension. (If the partials are not
1625+found here, they will also be sought in the `templates`
1626+subdirectory of the user data directory.)
1627+
1628+Partials may optionally be applied to variables using
1629+a colon:
1630+
1631+```
1632+${ date:fancy() }
1633+
1634+${ articles:bibentry() }
1635+```
1636+
1637+If `articles` is an array, this will iterate over its
1638+values, applying the partial `bibentry()` to each one.
1639+So the second example above is equivalent to
1640+
1641+```
1642+${ for(articles) }
1643+${ it:bibentry() }
1644+${ endfor }
1645+```
1646+
1647+Note that the anaphoric keyword `it` must be used when
1648+iterating over partials. In the above examples,
1649+the `bibentry` partial should contain `it.title`
1650+(and so on) instead of `articles.title`.
1651+
1652+Final newlines are omitted from included partials.
1653+
1654+Partials may include other partials. If you exceed
1655+a nesting level of 50, though, in resolving partials,
1656+the literal `(loop)` will be returned, to avoid infinite loops.
1657+
1658+A separator between values of an array may be specified
1659+in square brackets, immediately after the variable name
1660+or partial:
1661+
1662+```
1663+${months[, ]}$
1664+
1665+${articles:bibentry()[; ]$
1666+```
1667+
1668+The separator in this case is literal and (unlike with `sep`
1669+in an explicit `for` loop) cannot contain interpolated
1670+variables or other template directives.
1671+
1672+### Breakable spaces
1673+
1674+Normally, spaces in the template itself (as opposed to values of
1675+the interpolated variables) are not breakable, but they can be
1676+made breakable in part of the template by using the `+reflow`
1677+keyword (ended with `-reflow`).
1678+
1679+```
1680+${ +reflow }This long line may break if the document is rendered
1681+with a short line length.${ -reflow }
1682+```
1683+
1684+### Nesting
1685+
1686+As noted above, the value of a variable that occurs by itself on
1687+a line will be indented to the same level as the opening
1688+delimiter of the variable.
1689+
1690+In addition, any part of a template can be marked explicitly for
1691+indented rendering, using the `+nest` keyword (o start nesting at
1692+the column where it appears) and `-nest` to stop nesting.
1693+
1694+Example:
1695+
1696+```
1697+$for(article)$
1698+- $+nest$$article.author$, "$article.title$," in $article.book$
1699+ ($article.year$).$-nest$
1700+$endfor$
1701+```
1702+
14441703
14451704Metadata variables
14461705------------------
@@ -2014,76 +2273,6 @@ on the output format, and include the following:
20142273: title of table of contents (works only with EPUB,
20152274 opendocument, odt, docx, pptx, beamer, LaTeX)
20162275
2017−Using variables in templates
2018−----------------------------
2019−
2020−Variable names are sequences of alphanumerics, `-`, and `_`,
2021−starting with a letter. A variable name surrounded by `$` signs
2022−will be replaced by its value. For example, the string `$title$` in
2023−
2024− <title>$title$</title>
2025−
2026−will be replaced by the document title.
2027−
2028−To write a literal `$` in a template, use `$$`.
2029−
2030−Templates may contain conditionals. The syntax is as follows:
2031−
2032− $if(variable)$
2033− X
2034− $else$
2035− Y
2036− $endif$
2037−
2038−This will include `X` in the template if `variable` has a truthy
2039−value; otherwise it will include `Y`. Here a truthy value is any
2040−of the following:
2041−
2042−- a string that is not entirely white space,
2043−- a non-empty array where the first value is truthy,
2044−- any number (including zero),
2045−- any object,
2046−- the boolean `true` (to specify the boolean `true`
2047− value using YAML metadata or the `--metadata` flag,
2048− use `true`, `True`, or `TRUE`; with the `--variable`
2049− flag, simply omit a value for the variable, e.g.
2050− `--variable draft`).
2051−
2052−`X` and `Y` are placeholders for any valid template text,
2053−and may include interpolated variables or other conditionals.
2054−The `$else$` section may be omitted.
2055−
2056−When variables can have multiple values (for example, `author` in
2057−a multi-author document), you can use the `$for$` keyword:
2058−
2059− $for(author)$
2060− <meta name="author" content="$author$" />
2061− $endfor$
2062−
2063−You can optionally specify a separator to be used between
2064−consecutive items:
2065−
2066− $for(author)$$author$$sep$, $endfor$
2067−
2068−Note that the separator needs to be specified immediately before the `$endfor`
2069−keyword.
2070−
2071−A dot can be used to select a field of a variable that takes
2072−an object as its value. So, for example:
2073−
2074− $author.name$ ($author.affiliation$)
2075−
2076−The value of a variable will be indented to the same level as the variable.
2077−
2078−If you use custom templates, you may need to revise them as pandoc
2079−changes. We recommend tracking the changes in the default templates,
2080−and modifying your custom templates accordingly. An easy way to do this
2081−is to fork the [pandoc-templates] repository and merge in changes after each
2082−pandoc release.
2083−
2084−Templates may contain comments: anything on a line after `$--`
2085−will be treated as a comment and ignored.
2086−
20872276[pandoc-templates]: https://github.com/jgm/pandoc-templates
20882277
20892278Extensions