diff --git a/MANUAL.txt b/MANUAL.txt index cce71f26f8dc..a1dbf8432b75 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -55,7 +55,7 @@ use the `-s` or `--standalone` flag: pandoc -s -o output.html input.txt For more information on how standalone documents are produced, see -[Templates] below. +[Templates](templates.md). If multiple input files are given, pandoc will concatenate them all (with blank lines between them) before parsing. (Use `--file-scope` to parse files @@ -759,7 +759,7 @@ header when requesting a document from a URL: `--template=`*FILE*|*URL* : Use the specified file as a custom template for the generated document. - Implies `--standalone`. See [Templates], below, for a description + Implies `--standalone`. See [Templates](templates.md) for a description of template syntax. If no extension is specified, an extension corresponding to the writer will be added, so that `--template=special` looks for `special.html` for HTML output. If the template is not @@ -2229,1211 +2229,6 @@ be added to `html-math-method:`. | ``` | ``` | +----------------------------------+-----------------------------------+ -# Templates - -When the `-s/--standalone` option is used, pandoc uses a template to -add header and footer material that is needed for a self-standing -document. To see the default template that is used, just type - - pandoc -D *FORMAT* - -where *FORMAT* is the name of the output format. A custom template -can be specified using the `--template` option. You can also override -the system default templates for a given output format *FORMAT* -by putting a file `templates/default.*FORMAT*` in the user data -directory (see `--data-dir`, above). *Exceptions:* - -- For `odt` output, customize the `default.opendocument` template. -- For `docx` output, customize the `default.openxml` template. -- For `pdf` output, customize the `default.latex` template - (or the `default.context` template, if you use `-t context`, - or the `default.ms` template, if you use `-t ms`, or the - `default.html` template, if you use `-t html`). -- `pptx` has no template. - -Note that `docx`, `odt`, and `pptx` output can also be customized -using `--reference-doc`. Use a reference doc to adjust the styles -in your document; use a template to handle variable interpolation and -customize the presentation of metadata, the position of the table -of contents, boilerplate text, etc. - -Templates contain *variables*, which allow for the inclusion of -arbitrary information at any point in the file. They may be set at the -command line using the `-V/--variable` option. If a variable is not set, -pandoc will look for the key in the document's metadata, which can be set -using either [YAML metadata blocks][Extension: `yaml_metadata_block`] -or with the `-M/--metadata` option. In addition, some variables -are given default values by pandoc. See [Variables] below for -a list of variables used in pandoc's default templates. - -If you use custom templates, you may need to revise them as pandoc -changes. We recommend tracking the changes in the default templates, -and modifying your custom templates accordingly. An easy way to do this -is to fork the [pandoc-templates] repository and merge in -changes after each pandoc release. - - [pandoc-templates]: https://github.com/jgm/pandoc-templates - -## Template syntax - -### Comments - -Anything between the sequence `$--` and the end of the -line will be treated as a comment and omitted from the output. - -### Delimiters - -To mark variables and control structures in the template, -either `$`...`$` or `${`...`}` may be used as delimiters. -The styles may also be mixed in the same template, but the -opening and closing delimiter must match in each case. The -opening delimiter may be followed by one or more spaces -or tabs, which will be ignored. The closing delimiter may -be preceded by one or more spaces or tabs, which will be -ignored. - -To include a literal `$` in the document, use `$$`. - -### Interpolated variables - -A slot for an interpolated variable is a variable name surrounded -by matched delimiters. Variable names must begin with a letter -and can contain letters, numbers, `_`, `-`, and `.`. The -keywords `it`, `if`, `else`, `endif`, `for`, `sep`, and `endfor` may -not be used as variable names. Examples: - -``` -$foo$ -$foo.bar.baz$ -$foo_bar.baz-bim$ -$ foo $ -${foo} -${foo.bar.baz} -${foo_bar.baz-bim} -${ foo } -``` - -Variable names with periods are used to get at structured -variable values. So, for example, `employee.salary` will return the -value of the `salary` field of the object that is the value of -the `employee` field. - -- If the value of the variable is a simple value, it will be - rendered verbatim. (Note that no escaping is done; - the assumption is that the calling program will escape - the strings appropriately for the output format.) -- If the value is a list, the values will be concatenated. -- If the value is a map, the string `true` will be rendered. -- Every other value will be rendered as the empty string. - -### Conditionals - -A conditional begins with `if(variable)` (enclosed in -matched delimiters) and ends with `endif` (enclosed in matched -delimiters). It may optionally contain an `else` (enclosed in -matched delimiters). The `if` section is used if -`variable` has a true value, otherwise the `else` -section is used (if present). The following values count -as true: - -- any map -- any array containing at least one true value -- any nonempty string -- boolean True - -Note that in YAML metadata (and metadata specified on the -command line using `-M/--metadata`), unquoted `true` and `false` will be -interpreted as Boolean values. But a variable specified on the -command line using `-V/--variable` will always be given a string -value. Hence a conditional `if(foo)` will be triggered if you -use `-V foo=false`, but not if you use `-M foo=false`. - -Examples: - -``` -$if(foo)$bar$endif$ - -$if(foo)$ - $foo$ -$endif$ - -$if(foo)$ -part one -$else$ -part two -$endif$ - -${if(foo)}bar${endif} - -${if(foo)} - ${foo} -${endif} - -${if(foo)} -${ foo.bar } -${else} -no foo! -${endif} -``` - -The keyword `elseif` may be used to simplify complex nested -conditionals: - -``` -$if(foo)$ -XXX -$elseif(bar)$ -YYY -$else$ -ZZZ -$endif$ -``` - -### For loops - -A for loop begins with `for(variable)` (enclosed in -matched delimiters) and ends with `endfor` (enclosed in matched -delimiters). - -- If `variable` is an array, the material inside the loop will - be evaluated repeatedly, with `variable` being set to each - value of the array in turn, and concatenated. -- If `variable` is a map, the material inside will be set to - the map. -- If the value of the associated variable is not an array or - a map, a single iteration will be performed on its value. - -Examples: - -``` -$for(foo)$$foo$$sep$, $endfor$ - -$for(foo)$ - - $foo.last$, $foo.first$ -$endfor$ - -${ for(foo.bar) } - - ${ foo.bar.last }, ${ foo.bar.first } -${ endfor } - -$for(mymap)$ -$it.name$: $it.office$ -$endfor$ -``` - -You may optionally specify a separator between consecutive -values using `sep` (enclosed in matched delimiters). The -material between `sep` and the `endfor` is the separator. - -``` -${ for(foo) }${ foo }${ sep }, ${ endfor } -``` - -Instead of using `variable` inside the loop, the special -anaphoric keyword `it` may be used. - -``` -${ for(foo.bar) } - - ${ it.last }, ${ it.first } -${ endfor } -``` - -### Partials - -Partials (subtemplates stored in different files) may be -included by using the name of the partial, followed -by `()`, for example: - -``` -${ styles() } -``` - -Partials will be sought in the directory containing -the main template. The file name will be assumed to -have the same extension as the main template if it -lacks an extension. When calling the partial, the -full name including file extension can also be used: - -``` -${ styles.html() } -``` - -(If a partial is not found in the directory of the -template and the template path is given as a relative -path, it will also be sought in the `templates` -subdirectory of the user data directory.) - -Partials may optionally be applied to variables using -a colon: - -``` -${ date:fancy() } - -${ articles:bibentry() } -``` - -If `articles` is an array, this will iterate over its -values, applying the partial `bibentry()` to each one. So the -second example above is equivalent to - -``` -${ for(articles) } -${ it:bibentry() } -${ endfor } -``` - -Note that the anaphoric keyword `it` must be used when -iterating over partials. In the above examples, -the `bibentry` partial should contain `it.title` -(and so on) instead of `articles.title`. - -Final newlines are omitted from included partials. - -Partials may include other partials. - -A separator between values of an array may be specified -in square brackets, immediately after the variable name -or partial: - -``` -${months[, ]} - -${articles:bibentry()[; ]} -``` - -The separator in this case is literal and (unlike with `sep` -in an explicit `for` loop) cannot contain interpolated -variables or other template directives. - -### Nesting - -To ensure that content is "nested," that is, subsequent lines -indented, use the `^` directive: - -``` -$item.number$ $^$$item.description$ ($item.price$) -``` - -In this example, if `item.description` has multiple lines, -they will all be indented to line up with the first line: - -``` -00123 A fine bottle of 18-year old - Oban whiskey. ($148) -``` - -To nest multiple lines to the same level, align them -with the `^` directive in the template. For example: - -``` -$item.number$ $^$$item.description$ ($item.price$) - (Available til $item.sellby$.) -``` - -will produce - -``` -00123 A fine bottle of 18-year old - Oban whiskey. ($148) - (Available til March 30, 2020.) -``` - -If a variable occurs by itself on a line, preceded by whitespace -and not followed by further text or directives on the same line, -and the variable's value contains multiple lines, it will be -nested automatically. - -### Breakable spaces - -Normally, spaces in the template itself (as opposed to values of -the interpolated variables) are not breakable, but they can be -made breakable in part of the template by using the `~` keyword -(ended with another `~`). - -``` -$~$This long line may break if the document is rendered -with a short line length.$~$ -``` - -### Pipes - -A pipe transforms the value of a variable or partial. Pipes are -specified using a slash (`/`) between the variable name (or partial) -and the pipe name. Example: - -``` -$for(name)$ -$name/uppercase$ -$endfor$ - -$for(metadata/pairs)$ -- $it.key$: $it.value$ -$endfor$ - -$employee:name()/uppercase$ -``` - -Pipes may be chained: - -``` -$for(employees/pairs)$ -$it.key/alpha/uppercase$. $it.name$ -$endfor$ -``` - -Some pipes take parameters: - -``` -|----------------------|------------| -$for(employee)$ -$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$ -$endfor$ -|----------------------|------------| -``` - -Currently the following pipes are predefined: - -- `pairs`: Converts a map or array to an array of maps, - each with `key` and `value` fields. If the original - value was an array, the `key` will be the array index, - starting with 1. - -- `uppercase`: Converts text to uppercase. - -- `lowercase`: Converts text to lowercase. - -- `length`: Returns the length of the value: number - of characters for a textual value, number of elements - for a map or array. - -- `reverse`: Reverses a textual value or array, - and has no effect on other values. - -- `first`: Returns the first value of an array, if - applied to a non-empty array; otherwise returns - the original value. - -- `last`: Returns the last value of an array, if - applied to a non-empty array; otherwise returns - the original value. - -- `rest`: Returns all but the first value of an array, if - applied to a non-empty array; otherwise returns - the original value. - -- `allbutlast`: Returns all but the last value of an array, if - applied to a non-empty array; otherwise returns - the original value. - -- `chomp`: Removes trailing newlines (and breakable space). - -- `nowrap`: Disables line wrapping on breakable spaces. - -- `alpha`: Converts textual values that can be - read as an integer into lowercase alphabetic - characters `a..z` (mod 26). This can be used to get lettered - enumeration from array indices. To get uppercase - letters, chain with `uppercase`. - -- `roman`: Converts textual values that can be - read as an integer into lowercase roman numerals. - This can be used to get lettered enumeration from array indices. - To get uppercase roman, chain with `uppercase`. - -- `left n "leftborder" "rightborder"`: Renders a textual value - in a block of width `n`, aligned to the left, with an optional - left and right border. Has no effect on other values. This - can be used to align material in tables. Widths are positive - integers indicating the number of characters. Borders - are strings inside double quotes; literal `"` and `\` characters - must be backslash-escaped. - -- `right n "leftborder" "rightborder"`: Renders a textual value - in a block of width `n`, aligned to the right, and has no - effect on other values. - -- `center n "leftborder" "rightborder"`: Renders a textual - value in a block of width `n`, aligned to the center, and has - no effect on other values. - - -## Variables - -### Metadata variables - -`title`, `author`, `date` -: allow identification of basic aspects of the document. Included - in PDF metadata through LaTeX and ConTeXt. These can be set - through a [pandoc title block][Extension: `pandoc_title_block`], - which allows for multiple authors, or through a - [YAML metadata block][Extension: `yaml_metadata_block`]: - - --- - author: - - Aristotle - - Peter Abelard - ... - - Note that if you just want to set PDF or HTML metadata, without - including a title block in the document itself, you can - set the `title-meta`, `author-meta`, and `date-meta` - variables. (By default these are set automatically, based - on `title`, `author`, and `date`.) The page title in HTML - is set by `pagetitle`, which is equal to `title` by default. - -`subtitle` -: document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx - documents - -`abstract` -: document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc, and docx - documents - -`abstract-title` -: title of abstract, currently used only in HTML, EPUB, and docx. - This will be set automatically to a localized value, - depending on `lang`, but can be manually overridden. - -`keywords` -: list of keywords to be included in HTML, PDF, ODT, pptx, docx - and AsciiDoc metadata; repeat as for `author`, above - -`subject` -: document subject, included in ODT, PDF, docx, EPUB, and pptx metadata - -`description` -: document description, included in ODT, docx and pptx metadata. Some - applications show this as `Comments` metadata. - -`category` -: document category, included in docx and pptx metadata - -Additionally, -any root-level string metadata, not included in ODT, docx -or pptx metadata is added as a *custom property*. -The following [YAML] metadata block for instance: - - --- - title: 'This is the title' - subtitle: "This is the subtitle" - author: - - Author One - - Author Two - description: | - This is a long - description. - - It consists of two paragraphs - ... - -will include `title`, `author` and `description` as standard document -properties and `subtitle` as a custom property when converting to docx, -ODT or pptx. - -### Language variables - -`lang` -: identifies the main language of the document using IETF language - tags (following the [BCP 47] standard), such as `en` or `en-GB`. - The [Language subtag lookup] tool can look up or verify these tags. - This affects most formats, and controls hyphenation in PDF output - when using LaTeX (through [`babel`] and [`polyglossia`]) or ConTeXt. - - Use native pandoc [Divs and Spans] with the `lang` attribute to - switch the language: - - --- - lang: en-GB - ... - - Text in the main document language (British English). - - ::: {lang=fr-CA} - > Cette citation est écrite en français canadien. - ::: - - More text in English. ['Zitat auf Deutsch.']{lang=de} - -`dir` -: the base script direction, either `rtl` (right-to-left) - or `ltr` (left-to-right). - - For bidirectional documents, native pandoc `span`s and - `div`s with the `dir` attribute (value `rtl` or `ltr`) can - be used to override the base direction in some output - formats. This may not always be necessary if the final - renderer (e.g. the browser, when generating HTML) supports - the [Unicode Bidirectional Algorithm]. - - When using LaTeX for bidirectional documents, only the - `xelatex` engine is fully supported (use - `--pdf-engine=xelatex`). - -[BCP 47]: https://tools.ietf.org/html/bcp47 -[Unicode Bidirectional Algorithm]: https://www.w3.org/International/articles/inline-bidi-markup/uba-basics -[Language subtag lookup]: https://r12a.github.io/app-subtags/ - -### Variables for HTML - -`document-css` -: Enables inclusion of most of the [CSS] in the `styles.html` - [partial](#partials) (have a look with - `pandoc --print-default-data-file=templates/styles.html`). - Unless you use `--css`, this variable - is set to `true` by default. You can disable it with - e.g. `pandoc -M document-css=false`. - -`mainfont` -: sets the CSS `font-family` property on the `html` element. - -`fontsize` -: sets the base CSS `font-size`, which you'd usually set - to e.g. `20px`, but it also accepts `pt` - (12pt = 16px in most browsers). - -`fontcolor` -: sets the CSS `color` property on the `html` element. - -`linkcolor` -: sets the CSS `color` property on all links. - -`monofont` -: sets the CSS `font-family` property on `code` elements. - -`monobackgroundcolor` -: sets the CSS `background-color` property on `code` elements - and adds extra padding. - -`linestretch` -: sets the CSS `line-height` property on the `html` element, - which is preferred to be unitless. - -`maxwidth` -: sets the CSS `max-width` property (default is 32em). - -`backgroundcolor` -: sets the CSS `background-color` property on the `html` element. - -`margin-left`, `margin-right`, `margin-top`, `margin-bottom` -: sets the corresponding CSS `padding` properties on the `body` element. - -To override or extend some [CSS] for just one document, include for example: - - --- - header-includes: | - - --- - -[CSS]: https://developer.mozilla.org/en-US/docs/Learn/CSS - -### Variables for HTML math - -`classoption` -: when using `--katex`, you can render display math equations - flush left using [YAML metadata](#layout) or with `-M - classoption=fleqn`. - -### Variables for HTML slides - -These affect HTML output when [producing slide shows with -pandoc](#slide-shows). - -`institute` -: author affiliations: can be a list when there are multiple authors - -`revealjs-url` -: base URL for reveal.js documents (defaults to - `https://unpkg.com/reveal.js@^4/`) - -`s5-url` -: base URL for S5 documents (defaults to `s5/default`) - -`slidy-url` -: base URL for Slidy documents (defaults to - `https://www.w3.org/Talks/Tools/Slidy2`) - -`slideous-url` -: base URL for Slideous documents (defaults to `slideous`) - -`title-slide-attributes` -: additional attributes for the title slide of reveal.js slide shows. - See [background in reveal.js, beamer, and pptx] for an example. - -All [reveal.js configuration options] are available as variables. -To turn off boolean flags that default to true in reveal.js, use `0`. - -[reveal.js configuration options]: https://revealjs.com/config/ - -### Variables for Beamer slides - -These variables change the appearance of PDF slides using [`beamer`]. - -`aspectratio` -: slide aspect ratio (`43` for 4:3 [default], `169` for 16:9, - `1610` for 16:10, `149` for 14:9, `141` for 1.41:1, `54` for 5:4, - `32` for 3:2) - -`beameroption` -: add extra beamer option with `\setbeameroption{}` - -`institute` -: author affiliations: can be a list when there are multiple authors - -`logo` -: logo image for slides - -`navigation` -: controls navigation symbols (default is `empty` for no navigation - symbols; other valid values are `frame`, `vertical`, and `horizontal`) - -`section-titles` -: enables "title pages" for new sections (default is true) - -`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` -: beamer themes - -`themeoptions`, `colorthemeoptions`, `fontthemeoptions`, `innerthemeoptions`, `outerthemeoptions` -: options for LaTeX beamer themes (lists) - -`titlegraphic` -: image for title slide: can be a list - -`titlegraphicoptions` -: options for title slide image - -`shorttitle`, `shortsubtitle`, `shortauthor`, `shortinstitute`, `shortdate` -: some beamer themes use short versions of the title, subtitle, author, - institute, date - -### Variables for PowerPoint - -These variables control the visual aspects of a slide show that -are not easily controlled via templates. - -`monofont` -: font to use for code. - -### Variables for LaTeX - -Pandoc uses these variables when [creating a PDF] with a LaTeX engine. - -#### Layout - -`block-headings` -: make `\paragraph` and `\subparagraph` (fourth- and - fifth-level headings, or fifth- and sixth-level with book - classes) free-standing rather than run-in; requires further - formatting to distinguish from `\subsubsection` (third- or - fourth-level headings). Instead of using this option, - [KOMA-Script] can adjust headings more extensively: - - --- - documentclass: scrartcl - header-includes: | - \RedeclareSectionCommand[ - beforeskip=-10pt plus -2pt minus -1pt, - afterskip=1sp plus -1sp minus 1sp, - font=\normalfont\itshape]{paragraph} - \RedeclareSectionCommand[ - beforeskip=-10pt plus -2pt minus -1pt, - afterskip=1sp plus -1sp minus 1sp, - font=\normalfont\scshape, - indent=0pt]{subparagraph} - ... - -`classoption` -: option for document class, e.g. `oneside`; repeat for multiple options: - - --- - classoption: - - twocolumn - - landscape - ... - -`documentclass` -: document class: usually one of the standard classes, - [`article`], [`book`], and [`report`]; the [KOMA-Script] - equivalents, `scrartcl`, `scrbook`, and `scrreprt`, which - default to smaller margins; or [`memoir`] - -`geometry` -: option for [`geometry`] package, e.g. `margin=1in`; - repeat for multiple options: - - --- - geometry: - - top=30mm - - left=20mm - - heightrounded - ... - -`hyperrefoptions` -: option for [`hyperref`] package, e.g. `linktoc=all`; - repeat for multiple options: - - --- - hyperrefoptions: - - linktoc=all - - pdfwindowui - - pdfpagemode=FullScreen - ... - -`indent` -: if true, pandoc will use document class settings for - indentation (the default LaTeX template otherwise removes - indentation and adds space between paragraphs) - -`linestretch` -: adjusts line spacing using the [`setspace`] - package, e.g. `1.25`, `1.5` - -`margin-left`, `margin-right`, `margin-top`, `margin-bottom` -: sets margins if `geometry` is not used (otherwise `geometry` - overrides these) - -`pagestyle` -: control `\pagestyle{}`: the default article class - supports `plain` (default), `empty` (no running heads or page numbers), - and `headings` (section titles in running heads) - -`papersize` -: paper size, e.g. `letter`, `a4` - -`secnumdepth` -: numbering depth for sections (with `--number-sections` option - or `numbersections` variable) - -`beamerarticle` -: produce an article from Beamer slides. Note: if you set - this variable, you must specify the beamer writer but use the - default *LaTeX* template: for example, - `pandoc -Vbeamerarticle -t beamer --template default.latex`. - -`handout` -: produce a handout version of Beamer slides (with overlays condensed - into single slides) - -#### Fonts - -`fontenc` -: allows font encoding to be specified through `fontenc` package (with - `pdflatex`); default is `T1` (see [LaTeX font encodings guide]) - -`fontfamily` -: font package for use with `pdflatex`: - [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. - The default is [Latin Modern][`lm`]. - -`fontfamilyoptions` -: options for package used as `fontfamily`; repeat for multiple options. - For example, to use the Libertine font with proportional lowercase - (old-style) figures through the [`libertinus`] package: - - --- - fontfamily: libertinus - fontfamilyoptions: - - osf - - p - ... - -`fontsize` -: font size for body text. The standard classes allow 10pt, 11pt, and - 12pt. To use another size, set `documentclass` to one of - the [KOMA-Script] classes, such as `scrartcl` or `scrbook`. - -`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`, `CJKsansfont`, `CJKmonofont` -: font families for use with `xelatex` or - `lualatex`: take the name of any system font, using the - [`fontspec`] package. `CJKmainfont` uses the [`xecjk`] package if `xelatex` is used, - or the [`luatexja`] package if `lualatex` is used. - -`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`, `luatexjapresetoptions` -: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, - `CJKmainfont` in `xelatex` and `lualatex`. Allow for any - choices available through [`fontspec`]; repeat for multiple - options. For example, to use the [TeX Gyre] version of - Palatino with lowercase figures: - - --- - mainfont: TeX Gyre Pagella - mainfontoptions: - - Numbers=Lowercase - - Numbers=Proportional - ... - -`mainfontfallback`, `sansfontfallback`, `monofontfallback` -: fonts to try if a glyph isn't found in `mainfont`, `sansfont`, or `monofont` - respectively. These are lists. The font name must be followed by a colon - and optionally a set of options, for example: - - --- - mainfontfallback: - - "FreeSans:" - - "NotoColorEmoji:mode=harf" - ... - - Font fallbacks currently only work with `lualatex`. - -`babelfonts` -: a map of Babel language names (e.g. `chinese`) to the font - to be used with the language: - - --- - babelfonts: - chinese-hant: "Noto Serif CJK TC" - russian: "Noto Serif" - ... - -`microtypeoptions` -: options to pass to the microtype package - -#### Links - -`colorlinks` -: add color to link text; automatically enabled if any of - `linkcolor`, `filecolor`, `citecolor`, `urlcolor`, or `toccolor` are set - -`boxlinks` -: add visible box around links (has no effect if `colorlinks` is set) - -`linkcolor`, `filecolor`, `citecolor`, `urlcolor`, `toccolor` -: color for internal links, external links, citation links, linked - URLs, and links in table of contents, respectively: uses options - allowed by [`xcolor`], including the `dvipsnames`, `svgnames`, and - `x11names` lists - -`links-as-notes` -: causes links to be printed as footnotes - -`urlstyle` -: style for URLs (e.g., `tt`, `rm`, `sf`, and, the default, `same`) - -#### Front matter - -`lof`, `lot` -: include list of figures, list of tables (can also be set using - `--lof/--list-of-figures`, `--lot/--list-of-tables`) - -`thanks` -: contents of acknowledgments footnote after document title - -`toc` -: include table of contents (can also be set using - `--toc/--table-of-contents`) - -`toc-depth` -: level of section to include in table of contents - -#### BibLaTeX Bibliographies - -These variables function when using BibLaTeX for [citation rendering]. - -`biblatexoptions` -: list of options for biblatex - -`biblio-style` -: bibliography style, when used with `--natbib` and `--biblatex` - -`biblio-title` -: bibliography title, when used with `--natbib` and `--biblatex` - -`bibliography` -: bibliography to use for resolving references - -`natbiboptions` -: list of options for natbib - -[KOMA-Script]: https://ctan.org/pkg/koma-script -[LaTeX Font Catalogue]: https://tug.org/FontCatalogue/ -[LaTeX font encodings guide]: https://ctan.org/pkg/encguide -[TeX Gyre]: http://www.gust.org.pl/projects/e-foundry/tex-gyre -[`article`]: https://ctan.org/pkg/article -[`book`]: https://ctan.org/pkg/book -[`libertinus`]: https://ctan.org/pkg/libertinus -[`memoir`]: https://ctan.org/pkg/memoir -[`report`]: https://ctan.org/pkg/report - -### Variables for ConTeXt - -Pandoc uses these variables when [creating a PDF] with ConTeXt. - -`fontsize` -: font size for body text (e.g. `10pt`, `12pt`) - -`headertext`, `footertext` -: text to be placed in running header or footer (see [ConTeXt Headers and - Footers]); repeat up to four times for different placement - -`indenting` -: controls indentation of paragraphs, e.g. `yes,small,next` (see - [ConTeXt Indentation]); repeat for multiple options - -`interlinespace` -: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); - repeat for multiple options - -`layout` -: options for page margins and text arrangement (see [ConTeXt Layout]); - repeat for multiple options - -`linkcolor`, `contrastcolor` -: color for links outside and inside a page, e.g. `red`, `blue` (see - [ConTeXt Color]) - -`linkstyle` -: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`, - `type`, `cap`, `small` - -`lof`, `lot` -: include list of figures, list of tables - -`mainfont`, `sansfont`, `monofont`, `mathfont` -: font families: take the name of any system font (see - [ConTeXt Font Switching]) - -`mainfontfallback`, `sansfontfallback`, `monofontfallback` -: list of fonts to try, in order, if a glyph is not found in the - main font. Use `\definefallbackfamily`-compatible font name syntax. - Emoji fonts are unsupported. - -`margin-left`, `margin-right`, `margin-top`, `margin-bottom` -: sets margins, if `layout` is not used (otherwise `layout` - overrides these) - -`pagenumbering` -: page number style and location (using [`setuppagenumbering`]); - repeat for multiple options - -`papersize` -: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]); - repeat for multiple options - -`pdfa` -: adds to the preamble the setup necessary to generate PDF/A - of the type specified, e.g. `1a:2005`, `2a`. If no type is - specified (i.e. the value is set to True, by e.g. - `--metadata=pdfa` or `pdfa: true` in a YAML metadata block), - `1b:2005` will be used as default, for reasons of backwards - compatibility. Using `--variable=pdfa` without specified value - is not supported. To successfully generate PDF/A the required - ICC color profiles have to be available and the content and all - included files (such as images) have to be standard-conforming. - The ICC profiles and output intent may be specified using the - variables `pdfaiccprofile` and `pdfaintent`. See also [ConTeXt - PDFA] for more details. - -`pdfaiccprofile` -: when used in conjunction with `pdfa`, specifies the ICC profile to use - in the PDF, e.g. `default.cmyk`. If left unspecified, `sRGB.icc` is - used as default. May be repeated to include multiple profiles. Note that - the profiles have to be available on the system. They can be obtained - from [ConTeXt ICC Profiles]. - -`pdfaintent` -: when used in conjunction with `pdfa`, specifies the output intent for - the colors, e.g. `ISO coated v2 300\letterpercent\space (ECI)` - If left unspecified, `sRGB IEC61966-2.1` is used as default. - -`toc` -: include table of contents (can also be set using - `--toc/--table-of-contents`) - -`urlstyle` -: typeface style for links without link text, e.g. `normal`, `bold`, `slanted`, `boldslanted`, - `type`, `cap`, `small` - -`whitespace` -: spacing between paragraphs, e.g. `none`, `small` (using - [`setupwhitespace`]) - -`includesource` -: include all source documents as file attachments in the PDF file - -[ConTeXt Paper Setup]: https://wiki.contextgarden.net/PaperSetup -[ConTeXt Layout]: https://wiki.contextgarden.net/Layout -[ConTeXt Font Switching]: https://wiki.contextgarden.net/Font_Switching -[ConTeXt Color]: https://wiki.contextgarden.net/Color -[ConTeXt Headers and Footers]: https://wiki.contextgarden.net/Headers_and_Footers -[ConTeXt Indentation]: https://wiki.contextgarden.net/Indentation -[ConTeXt ICC Profiles]: https://wiki.contextgarden.net/PDFX#ICC_profiles -[ConTeXt PDFA]: https://wiki.contextgarden.net/PDF/A -[`setupwhitespace`]: https://wiki.contextgarden.net/Command/setupwhitespace -[`setupinterlinespace`]: https://wiki.contextgarden.net/Command/setupinterlinespace -[`setuppagenumbering`]: https://wiki.contextgarden.net/Command/setuppagenumbering - -### Variables for `wkhtmltopdf` - -Pandoc uses these variables when [creating a PDF] with [`wkhtmltopdf`]. -The `--css` option also affects the output. - -`footer-html`, `header-html` -: add information to the header and footer - -`margin-left`, `margin-right`, `margin-top`, `margin-bottom` -: set the page margins - -`papersize` -: sets the PDF paper size - -### Variables for man pages - -`adjusting` -: adjusts text to left (`l`), right (`r`), center (`c`), - or both (`b`) margins - -`footer` -: footer in man pages - -`header` -: header in man pages - -`section` -: section number in man pages - -### Variables for Texinfo - -`version` -: version of software (used in title and title page) - -`filename` -: name of info file to be generated (defaults to a name based on the - texi filename) - -### Variables for Typst - -`margin` -: A dictionary with the fields defined in the Typst documentation: - `x`, `y`, `top`, `bottom`, `left`, `right`. - -`papersize` -: Paper size: `a4`, `us-letter`, etc. - -`mainfont` -: Name of system font to use for the main font. - -`fontsize` -: Font size (e.g., `12pt`). - -`section-numbering` -: Schema to use for numbering sections, e.g. `1.A.1`. - -`page-numbering` -: Schema to use for numbering pages, e.g. `1` or `i`, or - an empty string to omit page numbering. - -`columns` -: Number of columns for body text. - -### Variables for ms - -`fontfamily` -: `A` (Avant Garde), `B` (Bookman), `C` (Helvetica), `HN` - (Helvetica Narrow), `P` (Palatino), or `T` (Times New Roman). - This setting does not affect source code, which is always - displayed using monospace Courier. These built-in fonts are - limited in their coverage of characters. Additional fonts may - be installed using the script [`install-font.sh`] provided - by Peter Schaffter and documented in detail on [his web - site][ms-font-steps]. - -`indent` -: paragraph indent (e.g. `2m`) - -`lineheight` -: line height (e.g. `12p`) - -`pointsize` -: point size (e.g. `10p`) - -[`install-font.sh`]: https://www.schaffter.ca/mom/bin/install-font.sh -[ms-font-steps]: https://www.schaffter.ca/mom/momdoc/appendices.html#steps - -### Variables set automatically - -Pandoc sets these variables automatically in response to [options] or -document contents; users can also modify them. These vary depending -on the output format, and include the following: - -`body` -: body of document - -`date-meta` -: the `date` variable converted to ISO 8601 YYYY-MM-DD, - included in all HTML based formats (dzslides, epub, - html, html4, html5, revealjs, s5, slideous, slidy). - The recognized formats for `date` are: `mm/dd/yyyy`, - `mm/dd/yy`, `yyyy-mm-dd` (ISO 8601), `dd MM yyyy` - (e.g. either `02 Apr 2018` or `02 April 2018`), - `MM dd, yyyy` (e.g. `Apr. 02, 2018` or `April 02, 2018), - `yyyy[mm[dd]]` (e.g. `20180402, `201804` or `2018`). - -`header-includes` -: contents specified by `-H/--include-in-header` (may have multiple - values) - -`include-before` -: contents specified by `-B/--include-before-body` (may have - multiple values) - -`include-after` -: contents specified by `-A/--include-after-body` (may have - multiple values) - -`meta-json` -: JSON representation of all of the document's metadata. Field - values are transformed to the selected output format. - -`numbersections` -: non-null value if `-N/--number-sections` was specified - -`sourcefile`, `outputfile` -: source and destination filenames, as given on the command line. - `sourcefile` can also be a list if input comes from multiple files, - or empty if input is from stdin. You can use the following snippet in - your template to distinguish them: - - $if(sourcefile)$ - $for(sourcefile)$ - $sourcefile$ - $endfor$ - $else$ - (stdin) - $endif$ - - Similarly, `outputfile` can be `-` if output goes to the terminal. - - If you need absolute paths, use e.g. `$curdir$/$sourcefile$`. - -`curdir` -: working directory from which pandoc is run. - -`pandoc-version` -: pandoc version. - -`toc` -: non-null value if `--toc/--table-of-contents` was specified - -`toc-title` -: title of table of contents (works only with EPUB, - HTML, revealjs, opendocument, odt, docx, pptx, beamer, LaTeX). - Note that in docx and pptx a custom `toc-title` will be - picked up from metadata, but cannot be set as a variable. - -[pandoc-templates]: https://github.com/jgm/pandoc-templates - # Extensions The behavior of some of the readers and writers can be adjusted by @@ -7471,7 +6266,7 @@ to use `--standalone` with a custom writer, you will need to specify a template manually using `--template` or add a new default template with the name `default.NAME_OF_CUSTOM_WRITER.lua` to the `templates` -subdirectory of your user data directory (see [Templates]). +subdirectory of your user data directory (see [Templates](templates.md)). [Lua]: https://www.lua.org [lpeg]: http://www.inf.puc-rio.br/~roberto/lpeg/ diff --git a/Makefile b/Makefile index e8742a0f10a4..0fdb5fe48cdb 100644 --- a/Makefile +++ b/Makefile @@ -109,6 +109,7 @@ check-manversion: grep '"pandoc $(version)"' "pandoc-cli/man/pandoc.1" grep '"pandoc $(version)"' "pandoc-cli/man/pandoc-server.1" grep '"pandoc $(version)"' "pandoc-cli/man/pandoc-lua.1" + grep '"pandoc $(version)"' "pandoc-cli/man/pandoc-templates.5" .PHONY: check-manversion checkdocs: @@ -137,7 +138,7 @@ changes_github: ## copy this release's changes in gfm $(pandoc) --lua-filter tools/extract-changes.lua changelog.md -t gfm --wrap=none --template tools/changes_template.html | sed -e 's/\\#/#/g' | pbcopy .PHONY: changes_github -man: pandoc-cli/man/pandoc.1 pandoc-cli/man/pandoc-server.1 pandoc-cli/man/pandoc-lua.1 ## build man pages +man: pandoc-cli/man/pandoc.1 pandoc-cli/man/pandoc-server.1 pandoc-cli/man/pandoc-lua.1 pandoc-cli/man/pandoc-templates.5 ## build man pages .PHONY: man latex-package-dependencies: ## print packages used by default latex template @@ -199,6 +200,16 @@ pandoc-cli/man/%.1: doc/%.md pandoc.cabal --include-after-body man/pandoc.1.after \ -o $@ +pandoc-cli/man/pandoc-%.5: doc/%.md pandoc.cabal man/template.man + $(pandoc) $< -f markdown -t man -s \ + --template man/template.man \ + --lua-filter man/manfilter.lua \ + --metadata author="" \ + --variable section="5" \ + --variable title="$(basename $(notdir $@))" \ + --variable header='Pandoc User\[cq]s Guide' \ + --variable footer="pandoc $(version)" \ + -o $@ README.md: README.template MANUAL.txt tools/update-readme.lua $(pandoc) --lua-filter tools/update-readme.lua \ diff --git a/doc/templates.md b/doc/templates.md new file mode 100644 index 000000000000..01e1937fcfd0 --- /dev/null +++ b/doc/templates.md @@ -0,0 +1,1208 @@ +--- +title: Templates +subtitle: templates for standalone pandoc output +author: John MacFarlane +--- + +When the `-s/--standalone` option is used, pandoc uses a template to +add header and footer material that is needed for a self-standing +document. To see the default template that is used, just type + + pandoc -D *FORMAT* + +where *FORMAT* is the name of the output format. A custom template +can be specified using the `--template` option. You can also override +the system default templates for a given output format *FORMAT* +by putting a file `templates/default.*FORMAT*` in the user data +directory (see `--data-dir`, above). *Exceptions:* + +- For `odt` output, customize the `default.opendocument` template. +- For `docx` output, customize the `default.openxml` template. +- For `pdf` output, customize the `default.latex` template + (or the `default.context` template, if you use `-t context`, + or the `default.ms` template, if you use `-t ms`, or the + `default.html` template, if you use `-t html`). +- `pptx` has no template. + +Note that `docx`, `odt`, and `pptx` output can also be customized +using `--reference-doc`. Use a reference doc to adjust the styles +in your document; use a template to handle variable interpolation and +customize the presentation of metadata, the position of the table +of contents, boilerplate text, etc. + +Templates contain *variables*, which allow for the inclusion of +arbitrary information at any point in the file. They may be set at the +command line using the `-V/--variable` option. If a variable is not set, +pandoc will look for the key in the document's metadata, which can be set +using either [YAML metadata blocks][Extension: `yaml_metadata_block`] +or with the `-M/--metadata` option. In addition, some variables +are given default values by pandoc. See [Variables] below for +a list of variables used in pandoc's default templates. + +If you use custom templates, you may need to revise them as pandoc +changes. We recommend tracking the changes in the default templates, +and modifying your custom templates accordingly. An easy way to do this +is to fork the [pandoc-templates] repository and merge in +changes after each pandoc release. + + [pandoc-templates]: https://github.com/jgm/pandoc-templates + +# Template syntax + +## Comments + +Anything between the sequence `$--` and the end of the +line will be treated as a comment and omitted from the output. + +## Delimiters + +To mark variables and control structures in the template, +either `$`...`$` or `${`...`}` may be used as delimiters. +The styles may also be mixed in the same template, but the +opening and closing delimiter must match in each case. The +opening delimiter may be followed by one or more spaces +or tabs, which will be ignored. The closing delimiter may +be preceded by one or more spaces or tabs, which will be +ignored. + +To include a literal `$` in the document, use `$$`. + +## Interpolated variables + +A slot for an interpolated variable is a variable name surrounded +by matched delimiters. Variable names must begin with a letter +and can contain letters, numbers, `_`, `-`, and `.`. The +keywords `it`, `if`, `else`, `endif`, `for`, `sep`, and `endfor` may +not be used as variable names. Examples: + +``` +$foo$ +$foo.bar.baz$ +$foo_bar.baz-bim$ +$ foo $ +${foo} +${foo.bar.baz} +${foo_bar.baz-bim} +${ foo } +``` + +Variable names with periods are used to get at structured +variable values. So, for example, `employee.salary` will return the +value of the `salary` field of the object that is the value of +the `employee` field. + +- If the value of the variable is a simple value, it will be + rendered verbatim. (Note that no escaping is done; + the assumption is that the calling program will escape + the strings appropriately for the output format.) +- If the value is a list, the values will be concatenated. +- If the value is a map, the string `true` will be rendered. +- Every other value will be rendered as the empty string. + +## Conditionals + +A conditional begins with `if(variable)` (enclosed in +matched delimiters) and ends with `endif` (enclosed in matched +delimiters). It may optionally contain an `else` (enclosed in +matched delimiters). The `if` section is used if +`variable` has a true value, otherwise the `else` +section is used (if present). The following values count +as true: + +- any map +- any array containing at least one true value +- any nonempty string +- boolean True + +Note that in YAML metadata (and metadata specified on the +command line using `-M/--metadata`), unquoted `true` and `false` will be +interpreted as Boolean values. But a variable specified on the +command line using `-V/--variable` will always be given a string +value. Hence a conditional `if(foo)` will be triggered if you +use `-V foo=false`, but not if you use `-M foo=false`. + +Examples: + +``` +$if(foo)$bar$endif$ + +$if(foo)$ + $foo$ +$endif$ + +$if(foo)$ +part one +$else$ +part two +$endif$ + +${if(foo)}bar${endif} + +${if(foo)} + ${foo} +${endif} + +${if(foo)} +${ foo.bar } +${else} +no foo! +${endif} +``` + +The keyword `elseif` may be used to simplify complex nested +conditionals: + +``` +$if(foo)$ +XXX +$elseif(bar)$ +YYY +$else$ +ZZZ +$endif$ +``` + +## For loops + +A for loop begins with `for(variable)` (enclosed in +matched delimiters) and ends with `endfor` (enclosed in matched +delimiters). + +- If `variable` is an array, the material inside the loop will + be evaluated repeatedly, with `variable` being set to each + value of the array in turn, and concatenated. +- If `variable` is a map, the material inside will be set to + the map. +- If the value of the associated variable is not an array or + a map, a single iteration will be performed on its value. + +Examples: + +``` +$for(foo)$$foo$$sep$, $endfor$ + +$for(foo)$ + - $foo.last$, $foo.first$ +$endfor$ + +${ for(foo.bar) } + - ${ foo.bar.last }, ${ foo.bar.first } +${ endfor } + +$for(mymap)$ +$it.name$: $it.office$ +$endfor$ +``` + +You may optionally specify a separator between consecutive +values using `sep` (enclosed in matched delimiters). The +material between `sep` and the `endfor` is the separator. + +``` +${ for(foo) }${ foo }${ sep }, ${ endfor } +``` + +Instead of using `variable` inside the loop, the special +anaphoric keyword `it` may be used. + +``` +${ for(foo.bar) } + - ${ it.last }, ${ it.first } +${ endfor } +``` + +## Partials + +Partials (subtemplates stored in different files) may be +included by using the name of the partial, followed +by `()`, for example: + +``` +${ styles() } +``` + +Partials will be sought in the directory containing +the main template. The file name will be assumed to +have the same extension as the main template if it +lacks an extension. When calling the partial, the +full name including file extension can also be used: + +``` +${ styles.html() } +``` + +(If a partial is not found in the directory of the +template and the template path is given as a relative +path, it will also be sought in the `templates` +subdirectory of the user data directory.) + +Partials may optionally be applied to variables using +a colon: + +``` +${ date:fancy() } + +${ articles:bibentry() } +``` + +If `articles` is an array, this will iterate over its +values, applying the partial `bibentry()` to each one. So the +second example above is equivalent to + +``` +${ for(articles) } +${ it:bibentry() } +${ endfor } +``` + +Note that the anaphoric keyword `it` must be used when +iterating over partials. In the above examples, +the `bibentry` partial should contain `it.title` +(and so on) instead of `articles.title`. + +Final newlines are omitted from included partials. + +Partials may include other partials. + +A separator between values of an array may be specified +in square brackets, immediately after the variable name +or partial: + +``` +${months[, ]} + +${articles:bibentry()[; ]} +``` + +The separator in this case is literal and (unlike with `sep` +in an explicit `for` loop) cannot contain interpolated +variables or other template directives. + +## Nesting + +To ensure that content is "nested," that is, subsequent lines +indented, use the `^` directive: + +``` +$item.number$ $^$$item.description$ ($item.price$) +``` + +In this example, if `item.description` has multiple lines, +they will all be indented to line up with the first line: + +``` +00123 A fine bottle of 18-year old + Oban whiskey. ($148) +``` + +To nest multiple lines to the same level, align them +with the `^` directive in the template. For example: + +``` +$item.number$ $^$$item.description$ ($item.price$) + (Available til $item.sellby$.) +``` + +will produce + +``` +00123 A fine bottle of 18-year old + Oban whiskey. ($148) + (Available til March 30, 2020.) +``` + +If a variable occurs by itself on a line, preceded by whitespace +and not followed by further text or directives on the same line, +and the variable's value contains multiple lines, it will be +nested automatically. + +## Breakable spaces + +Normally, spaces in the template itself (as opposed to values of +the interpolated variables) are not breakable, but they can be +made breakable in part of the template by using the `~` keyword +(ended with another `~`). + +``` +$~$This long line may break if the document is rendered +with a short line length.$~$ +``` + +## Pipes + +A pipe transforms the value of a variable or partial. Pipes are +specified using a slash (`/`) between the variable name (or partial) +and the pipe name. Example: + +``` +$for(name)$ +$name/uppercase$ +$endfor$ + +$for(metadata/pairs)$ +- $it.key$: $it.value$ +$endfor$ + +$employee:name()/uppercase$ +``` + +Pipes may be chained: + +``` +$for(employees/pairs)$ +$it.key/alpha/uppercase$. $it.name$ +$endfor$ +``` + +Some pipes take parameters: + +``` +|----------------------|------------| +$for(employee)$ +$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$ +$endfor$ +|----------------------|------------| +``` + +Currently the following pipes are predefined: + +- `pairs`: Converts a map or array to an array of maps, + each with `key` and `value` fields. If the original + value was an array, the `key` will be the array index, + starting with 1. + +- `uppercase`: Converts text to uppercase. + +- `lowercase`: Converts text to lowercase. + +- `length`: Returns the length of the value: number + of characters for a textual value, number of elements + for a map or array. + +- `reverse`: Reverses a textual value or array, + and has no effect on other values. + +- `first`: Returns the first value of an array, if + applied to a non-empty array; otherwise returns + the original value. + +- `last`: Returns the last value of an array, if + applied to a non-empty array; otherwise returns + the original value. + +- `rest`: Returns all but the first value of an array, if + applied to a non-empty array; otherwise returns + the original value. + +- `allbutlast`: Returns all but the last value of an array, if + applied to a non-empty array; otherwise returns + the original value. + +- `chomp`: Removes trailing newlines (and breakable space). + +- `nowrap`: Disables line wrapping on breakable spaces. + +- `alpha`: Converts textual values that can be + read as an integer into lowercase alphabetic + characters `a..z` (mod 26). This can be used to get lettered + enumeration from array indices. To get uppercase + letters, chain with `uppercase`. + +- `roman`: Converts textual values that can be + read as an integer into lowercase roman numerals. + This can be used to get lettered enumeration from array indices. + To get uppercase roman, chain with `uppercase`. + +- `left n "leftborder" "rightborder"`: Renders a textual value + in a block of width `n`, aligned to the left, with an optional + left and right border. Has no effect on other values. This + can be used to align material in tables. Widths are positive + integers indicating the number of characters. Borders + are strings inside double quotes; literal `"` and `\` characters + must be backslash-escaped. + +- `right n "leftborder" "rightborder"`: Renders a textual value + in a block of width `n`, aligned to the right, and has no + effect on other values. + +- `center n "leftborder" "rightborder"`: Renders a textual + value in a block of width `n`, aligned to the center, and has + no effect on other values. + + +# Variables + +## Metadata variables + +`title`, `author`, `date` +: allow identification of basic aspects of the document. Included + in PDF metadata through LaTeX and ConTeXt. These can be set + through a [pandoc title block][Extension: `pandoc_title_block`], + which allows for multiple authors, or through a + [YAML metadata block][Extension: `yaml_metadata_block`]: + + --- + author: + - Aristotle + - Peter Abelard + ... + + Note that if you just want to set PDF or HTML metadata, without + including a title block in the document itself, you can + set the `title-meta`, `author-meta`, and `date-meta` + variables. (By default these are set automatically, based + on `title`, `author`, and `date`.) The page title in HTML + is set by `pagetitle`, which is equal to `title` by default. + +`subtitle` +: document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx + documents + +`abstract` +: document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc, and docx + documents + +`abstract-title` +: title of abstract, currently used only in HTML, EPUB, and docx. + This will be set automatically to a localized value, + depending on `lang`, but can be manually overridden. + +`keywords` +: list of keywords to be included in HTML, PDF, ODT, pptx, docx + and AsciiDoc metadata; repeat as for `author`, above + +`subject` +: document subject, included in ODT, PDF, docx, EPUB, and pptx metadata + +`description` +: document description, included in ODT, docx and pptx metadata. Some + applications show this as `Comments` metadata. + +`category` +: document category, included in docx and pptx metadata + +Additionally, +any root-level string metadata, not included in ODT, docx +or pptx metadata is added as a *custom property*. +The following [YAML] metadata block for instance: + + --- + title: 'This is the title' + subtitle: "This is the subtitle" + author: + - Author One + - Author Two + description: | + This is a long + description. + + It consists of two paragraphs + ... + +will include `title`, `author` and `description` as standard document +properties and `subtitle` as a custom property when converting to docx, +ODT or pptx. + +## Language variables + +`lang` +: identifies the main language of the document using IETF language + tags (following the [BCP 47] standard), such as `en` or `en-GB`. + The [Language subtag lookup] tool can look up or verify these tags. + This affects most formats, and controls hyphenation in PDF output + when using LaTeX (through [`babel`] and [`polyglossia`]) or ConTeXt. + + Use native pandoc [Divs and Spans] with the `lang` attribute to + switch the language: + + --- + lang: en-GB + ... + + Text in the main document language (British English). + + ::: {lang=fr-CA} + > Cette citation est écrite en français canadien. + ::: + + More text in English. ['Zitat auf Deutsch.']{lang=de} + +`dir` +: the base script direction, either `rtl` (right-to-left) + or `ltr` (left-to-right). + + For bidirectional documents, native pandoc `span`s and + `div`s with the `dir` attribute (value `rtl` or `ltr`) can + be used to override the base direction in some output + formats. This may not always be necessary if the final + renderer (e.g. the browser, when generating HTML) supports + the [Unicode Bidirectional Algorithm]. + + When using LaTeX for bidirectional documents, only the + `xelatex` engine is fully supported (use + `--pdf-engine=xelatex`). + +[BCP 47]: https://tools.ietf.org/html/bcp47 +[Unicode Bidirectional Algorithm]: https://www.w3.org/International/articles/inline-bidi-markup/uba-basics +[Language subtag lookup]: https://r12a.github.io/app-subtags/ + +## Variables for HTML + +`document-css` +: Enables inclusion of most of the [CSS] in the `styles.html` + [partial](#partials) (have a look with + `pandoc --print-default-data-file=templates/styles.html`). + Unless you use `--css`, this variable + is set to `true` by default. You can disable it with + e.g. `pandoc -M document-css=false`. + +`mainfont` +: sets the CSS `font-family` property on the `html` element. + +`fontsize` +: sets the base CSS `font-size`, which you'd usually set + to e.g. `20px`, but it also accepts `pt` + (12pt = 16px in most browsers). + +`fontcolor` +: sets the CSS `color` property on the `html` element. + +`linkcolor` +: sets the CSS `color` property on all links. + +`monofont` +: sets the CSS `font-family` property on `code` elements. + +`monobackgroundcolor` +: sets the CSS `background-color` property on `code` elements + and adds extra padding. + +`linestretch` +: sets the CSS `line-height` property on the `html` element, + which is preferred to be unitless. + +`maxwidth` +: sets the CSS `max-width` property (default is 32em). + +`backgroundcolor` +: sets the CSS `background-color` property on the `html` element. + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets the corresponding CSS `padding` properties on the `body` element. + +To override or extend some [CSS] for just one document, include for example: + + --- + header-includes: | + + --- + +[CSS]: https://developer.mozilla.org/en-US/docs/Learn/CSS + +## Variables for HTML math + +`classoption` +: when using `--katex`, you can render display math equations + flush left using [YAML metadata](#layout) or with `-M + classoption=fleqn`. + +## Variables for HTML slides + +These affect HTML output when [producing slide shows with +pandoc](#slide-shows). + +`institute` +: author affiliations: can be a list when there are multiple authors + +`revealjs-url` +: base URL for reveal.js documents (defaults to + `https://unpkg.com/reveal.js@^4/`) + +`s5-url` +: base URL for S5 documents (defaults to `s5/default`) + +`slidy-url` +: base URL for Slidy documents (defaults to + `https://www.w3.org/Talks/Tools/Slidy2`) + +`slideous-url` +: base URL for Slideous documents (defaults to `slideous`) + +`title-slide-attributes` +: additional attributes for the title slide of reveal.js slide shows. + See [background in reveal.js, beamer, and pptx] for an example. + +All [reveal.js configuration options] are available as variables. +To turn off boolean flags that default to true in reveal.js, use `0`. + +[reveal.js configuration options]: https://revealjs.com/config/ + +## Variables for Beamer slides + +These variables change the appearance of PDF slides using [`beamer`]. + +`aspectratio` +: slide aspect ratio (`43` for 4:3 [default], `169` for 16:9, + `1610` for 16:10, `149` for 14:9, `141` for 1.41:1, `54` for 5:4, + `32` for 3:2) + +`beameroption` +: add extra beamer option with `\setbeameroption{}` + +`institute` +: author affiliations: can be a list when there are multiple authors + +`logo` +: logo image for slides + +`navigation` +: controls navigation symbols (default is `empty` for no navigation + symbols; other valid values are `frame`, `vertical`, and `horizontal`) + +`section-titles` +: enables "title pages" for new sections (default is true) + +`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme` +: beamer themes + +`themeoptions`, `colorthemeoptions`, `fontthemeoptions`, `innerthemeoptions`, `outerthemeoptions` +: options for LaTeX beamer themes (lists) + +`titlegraphic` +: image for title slide: can be a list + +`titlegraphicoptions` +: options for title slide image + +`shorttitle`, `shortsubtitle`, `shortauthor`, `shortinstitute`, `shortdate` +: some beamer themes use short versions of the title, subtitle, author, + institute, date + +## Variables for PowerPoint + +These variables control the visual aspects of a slide show that +are not easily controlled via templates. + +`monofont` +: font to use for code. + +## Variables for LaTeX + +Pandoc uses these variables when [creating a PDF] with a LaTeX engine. + +### Layout + +`block-headings` +: make `\paragraph` and `\subparagraph` (fourth- and + fifth-level headings, or fifth- and sixth-level with book + classes) free-standing rather than run-in; requires further + formatting to distinguish from `\subsubsection` (third- or + fourth-level headings). Instead of using this option, + [KOMA-Script] can adjust headings more extensively: + + --- + documentclass: scrartcl + header-includes: | + \RedeclareSectionCommand[ + beforeskip=-10pt plus -2pt minus -1pt, + afterskip=1sp plus -1sp minus 1sp, + font=\normalfont\itshape]{paragraph} + \RedeclareSectionCommand[ + beforeskip=-10pt plus -2pt minus -1pt, + afterskip=1sp plus -1sp minus 1sp, + font=\normalfont\scshape, + indent=0pt]{subparagraph} + ... + +`classoption` +: option for document class, e.g. `oneside`; repeat for multiple options: + + --- + classoption: + - twocolumn + - landscape + ... + +`documentclass` +: document class: usually one of the standard classes, + [`article`], [`book`], and [`report`]; the [KOMA-Script] + equivalents, `scrartcl`, `scrbook`, and `scrreprt`, which + default to smaller margins; or [`memoir`] + +`geometry` +: option for [`geometry`] package, e.g. `margin=1in`; + repeat for multiple options: + + --- + geometry: + - top=30mm + - left=20mm + - heightrounded + ... + +`hyperrefoptions` +: option for [`hyperref`] package, e.g. `linktoc=all`; + repeat for multiple options: + + --- + hyperrefoptions: + - linktoc=all + - pdfwindowui + - pdfpagemode=FullScreen + ... + +`indent` +: if true, pandoc will use document class settings for + indentation (the default LaTeX template otherwise removes + indentation and adds space between paragraphs) + +`linestretch` +: adjusts line spacing using the [`setspace`] + package, e.g. `1.25`, `1.5` + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins if `geometry` is not used (otherwise `geometry` + overrides these) + +`pagestyle` +: control `\pagestyle{}`: the default article class + supports `plain` (default), `empty` (no running heads or page numbers), + and `headings` (section titles in running heads) + +`papersize` +: paper size, e.g. `letter`, `a4` + +`secnumdepth` +: numbering depth for sections (with `--number-sections` option + or `numbersections` variable) + +`beamerarticle` +: produce an article from Beamer slides. Note: if you set + this variable, you must specify the beamer writer but use the + default *LaTeX* template: for example, + `pandoc -Vbeamerarticle -t beamer --template default.latex`. + +`handout` +: produce a handout version of Beamer slides (with overlays condensed + into single slides) + +### Fonts + +`fontenc` +: allows font encoding to be specified through `fontenc` package (with + `pdflatex`); default is `T1` (see [LaTeX font encodings guide]) + +`fontfamily` +: font package for use with `pdflatex`: + [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. + The default is [Latin Modern][`lm`]. + +`fontfamilyoptions` +: options for package used as `fontfamily`; repeat for multiple options. + For example, to use the Libertine font with proportional lowercase + (old-style) figures through the [`libertinus`] package: + + --- + fontfamily: libertinus + fontfamilyoptions: + - osf + - p + ... + +`fontsize` +: font size for body text. The standard classes allow 10pt, 11pt, and + 12pt. To use another size, set `documentclass` to one of + the [KOMA-Script] classes, such as `scrartcl` or `scrbook`. + +`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`, `CJKsansfont`, `CJKmonofont` +: font families for use with `xelatex` or + `lualatex`: take the name of any system font, using the + [`fontspec`] package. `CJKmainfont` uses the [`xecjk`] package if `xelatex` is used, + or the [`luatexja`] package if `lualatex` is used. + +`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`, `luatexjapresetoptions` +: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`, + `CJKmainfont` in `xelatex` and `lualatex`. Allow for any + choices available through [`fontspec`]; repeat for multiple + options. For example, to use the [TeX Gyre] version of + Palatino with lowercase figures: + + --- + mainfont: TeX Gyre Pagella + mainfontoptions: + - Numbers=Lowercase + - Numbers=Proportional + ... + +`mainfontfallback`, `sansfontfallback`, `monofontfallback` +: fonts to try if a glyph isn't found in `mainfont`, `sansfont`, or `monofont` + respectively. These are lists. The font name must be followed by a colon + and optionally a set of options, for example: + + --- + mainfontfallback: + - "FreeSans:" + - "NotoColorEmoji:mode=harf" + ... + + Font fallbacks currently only work with `lualatex`. + +`babelfonts` +: a map of Babel language names (e.g. `chinese`) to the font + to be used with the language: + + --- + babelfonts: + chinese-hant: "Noto Serif CJK TC" + russian: "Noto Serif" + ... + +`microtypeoptions` +: options to pass to the microtype package + +### Links + +`colorlinks` +: add color to link text; automatically enabled if any of + `linkcolor`, `filecolor`, `citecolor`, `urlcolor`, or `toccolor` are set + +`boxlinks` +: add visible box around links (has no effect if `colorlinks` is set) + +`linkcolor`, `filecolor`, `citecolor`, `urlcolor`, `toccolor` +: color for internal links, external links, citation links, linked + URLs, and links in table of contents, respectively: uses options + allowed by [`xcolor`], including the `dvipsnames`, `svgnames`, and + `x11names` lists + +`links-as-notes` +: causes links to be printed as footnotes + +`urlstyle` +: style for URLs (e.g., `tt`, `rm`, `sf`, and, the default, `same`) + +### Front matter + +`lof`, `lot` +: include list of figures, list of tables (can also be set using + `--lof/--list-of-figures`, `--lot/--list-of-tables`) + +`thanks` +: contents of acknowledgments footnote after document title + +`toc` +: include table of contents (can also be set using + `--toc/--table-of-contents`) + +`toc-depth` +: level of section to include in table of contents + +### BibLaTeX Bibliographies + +These variables function when using BibLaTeX for [citation rendering]. + +`biblatexoptions` +: list of options for biblatex + +`biblio-style` +: bibliography style, when used with `--natbib` and `--biblatex` + +`biblio-title` +: bibliography title, when used with `--natbib` and `--biblatex` + +`bibliography` +: bibliography to use for resolving references + +`natbiboptions` +: list of options for natbib + +[KOMA-Script]: https://ctan.org/pkg/koma-script +[LaTeX Font Catalogue]: https://tug.org/FontCatalogue/ +[LaTeX font encodings guide]: https://ctan.org/pkg/encguide +[TeX Gyre]: http://www.gust.org.pl/projects/e-foundry/tex-gyre +[`article`]: https://ctan.org/pkg/article +[`book`]: https://ctan.org/pkg/book +[`libertinus`]: https://ctan.org/pkg/libertinus +[`memoir`]: https://ctan.org/pkg/memoir +[`report`]: https://ctan.org/pkg/report + +## Variables for ConTeXt + +Pandoc uses these variables when [creating a PDF] with ConTeXt. + +`fontsize` +: font size for body text (e.g. `10pt`, `12pt`) + +`headertext`, `footertext` +: text to be placed in running header or footer (see [ConTeXt Headers and + Footers]); repeat up to four times for different placement + +`indenting` +: controls indentation of paragraphs, e.g. `yes,small,next` (see + [ConTeXt Indentation]); repeat for multiple options + +`interlinespace` +: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]); + repeat for multiple options + +`layout` +: options for page margins and text arrangement (see [ConTeXt Layout]); + repeat for multiple options + +`linkcolor`, `contrastcolor` +: color for links outside and inside a page, e.g. `red`, `blue` (see + [ConTeXt Color]) + +`linkstyle` +: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`, + `type`, `cap`, `small` + +`lof`, `lot` +: include list of figures, list of tables + +`mainfont`, `sansfont`, `monofont`, `mathfont` +: font families: take the name of any system font (see + [ConTeXt Font Switching]) + +`mainfontfallback`, `sansfontfallback`, `monofontfallback` +: list of fonts to try, in order, if a glyph is not found in the + main font. Use `\definefallbackfamily`-compatible font name syntax. + Emoji fonts are unsupported. + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: sets margins, if `layout` is not used (otherwise `layout` + overrides these) + +`pagenumbering` +: page number style and location (using [`setuppagenumbering`]); + repeat for multiple options + +`papersize` +: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]); + repeat for multiple options + +`pdfa` +: adds to the preamble the setup necessary to generate PDF/A + of the type specified, e.g. `1a:2005`, `2a`. If no type is + specified (i.e. the value is set to True, by e.g. + `--metadata=pdfa` or `pdfa: true` in a YAML metadata block), + `1b:2005` will be used as default, for reasons of backwards + compatibility. Using `--variable=pdfa` without specified value + is not supported. To successfully generate PDF/A the required + ICC color profiles have to be available and the content and all + included files (such as images) have to be standard-conforming. + The ICC profiles and output intent may be specified using the + variables `pdfaiccprofile` and `pdfaintent`. See also [ConTeXt + PDFA] for more details. + +`pdfaiccprofile` +: when used in conjunction with `pdfa`, specifies the ICC profile to use + in the PDF, e.g. `default.cmyk`. If left unspecified, `sRGB.icc` is + used as default. May be repeated to include multiple profiles. Note that + the profiles have to be available on the system. They can be obtained + from [ConTeXt ICC Profiles]. + +`pdfaintent` +: when used in conjunction with `pdfa`, specifies the output intent for + the colors, e.g. `ISO coated v2 300\letterpercent\space (ECI)` + If left unspecified, `sRGB IEC61966-2.1` is used as default. + +`toc` +: include table of contents (can also be set using + `--toc/--table-of-contents`) + +`urlstyle` +: typeface style for links without link text, e.g. `normal`, `bold`, `slanted`, `boldslanted`, + `type`, `cap`, `small` + +`whitespace` +: spacing between paragraphs, e.g. `none`, `small` (using + [`setupwhitespace`]) + +`includesource` +: include all source documents as file attachments in the PDF file + +[ConTeXt Paper Setup]: https://wiki.contextgarden.net/PaperSetup +[ConTeXt Layout]: https://wiki.contextgarden.net/Layout +[ConTeXt Font Switching]: https://wiki.contextgarden.net/Font_Switching +[ConTeXt Color]: https://wiki.contextgarden.net/Color +[ConTeXt Headers and Footers]: https://wiki.contextgarden.net/Headers_and_Footers +[ConTeXt Indentation]: https://wiki.contextgarden.net/Indentation +[ConTeXt ICC Profiles]: https://wiki.contextgarden.net/PDFX#ICC_profiles +[ConTeXt PDFA]: https://wiki.contextgarden.net/PDF/A +[`setupwhitespace`]: https://wiki.contextgarden.net/Command/setupwhitespace +[`setupinterlinespace`]: https://wiki.contextgarden.net/Command/setupinterlinespace +[`setuppagenumbering`]: https://wiki.contextgarden.net/Command/setuppagenumbering + +## Variables for `wkhtmltopdf` + +Pandoc uses these variables when [creating a PDF] with [`wkhtmltopdf`]. +The `--css` option also affects the output. + +`footer-html`, `header-html` +: add information to the header and footer + +`margin-left`, `margin-right`, `margin-top`, `margin-bottom` +: set the page margins + +`papersize` +: sets the PDF paper size + +## Variables for man pages + +`adjusting` +: adjusts text to left (`l`), right (`r`), center (`c`), + or both (`b`) margins + +`footer` +: footer in man pages + +`header` +: header in man pages + +`section` +: section number in man pages + +## Variables for Texinfo + +`version` +: version of software (used in title and title page) + +`filename` +: name of info file to be generated (defaults to a name based on the + texi filename) + +## Variables for Typst + +`margin` +: A dictionary with the fields defined in the Typst documentation: + `x`, `y`, `top`, `bottom`, `left`, `right`. + +`papersize` +: Paper size: `a4`, `us-letter`, etc. + +`mainfont` +: Name of system font to use for the main font. + +`fontsize` +: Font size (e.g., `12pt`). + +`section-numbering` +: Schema to use for numbering sections, e.g. `1.A.1`. + +`page-numbering` +: Schema to use for numbering pages, e.g. `1` or `i`, or + an empty string to omit page numbering. + +`columns` +: Number of columns for body text. + +## Variables for ms + +`fontfamily` +: `A` (Avant Garde), `B` (Bookman), `C` (Helvetica), `HN` + (Helvetica Narrow), `P` (Palatino), or `T` (Times New Roman). + This setting does not affect source code, which is always + displayed using monospace Courier. These built-in fonts are + limited in their coverage of characters. Additional fonts may + be installed using the script [`install-font.sh`] provided + by Peter Schaffter and documented in detail on [his web + site][ms-font-steps]. + +`indent` +: paragraph indent (e.g. `2m`) + +`lineheight` +: line height (e.g. `12p`) + +`pointsize` +: point size (e.g. `10p`) + +[`install-font.sh`]: https://www.schaffter.ca/mom/bin/install-font.sh +[ms-font-steps]: https://www.schaffter.ca/mom/momdoc/appendices.html#steps + +## Variables set automatically + +Pandoc sets these variables automatically in response to [options] or +document contents; users can also modify them. These vary depending +on the output format, and include the following: + +`body` +: body of document + +`date-meta` +: the `date` variable converted to ISO 8601 YYYY-MM-DD, + included in all HTML based formats (dzslides, epub, + html, html4, html5, revealjs, s5, slideous, slidy). + The recognized formats for `date` are: `mm/dd/yyyy`, + `mm/dd/yy`, `yyyy-mm-dd` (ISO 8601), `dd MM yyyy` + (e.g. either `02 Apr 2018` or `02 April 2018`), + `MM dd, yyyy` (e.g. `Apr. 02, 2018` or `April 02, 2018), + `yyyy[mm[dd]]` (e.g. `20180402, `201804` or `2018`). + +`header-includes` +: contents specified by `-H/--include-in-header` (may have multiple + values) + +`include-before` +: contents specified by `-B/--include-before-body` (may have + multiple values) + +`include-after` +: contents specified by `-A/--include-after-body` (may have + multiple values) + +`meta-json` +: JSON representation of all of the document's metadata. Field + values are transformed to the selected output format. + +`numbersections` +: non-null value if `-N/--number-sections` was specified + +`sourcefile`, `outputfile` +: source and destination filenames, as given on the command line. + `sourcefile` can also be a list if input comes from multiple files, + or empty if input is from stdin. You can use the following snippet in + your template to distinguish them: + + $if(sourcefile)$ + $for(sourcefile)$ + $sourcefile$ + $endfor$ + $else$ + (stdin) + $endif$ + + Similarly, `outputfile` can be `-` if output goes to the terminal. + + If you need absolute paths, use e.g. `$curdir$/$sourcefile$`. + +`curdir` +: working directory from which pandoc is run. + +`pandoc-version` +: pandoc version. + +`toc` +: non-null value if `--toc/--table-of-contents` was specified + +`toc-title` +: title of table of contents (works only with EPUB, + HTML, revealjs, opendocument, odt, docx, pptx, beamer, LaTeX). + Note that in docx and pptx a custom `toc-title` will be + picked up from metadata, but cannot be set as a variable. + +[pandoc-templates]: https://github.com/jgm/pandoc-templates diff --git a/linux/make_artifacts.sh b/linux/make_artifacts.sh index dff3cc24eac6..eb7eb42ef84b 100644 --- a/linux/make_artifacts.sh +++ b/linux/make_artifacts.sh @@ -48,6 +48,7 @@ make_deb() { mkdir -p "$DEST/bin" mkdir -p "$DEST/share/man/man1" + mkdir -p "$DEST/share/man/man5" mkdir -p "$DEST/share/doc/pandoc" find "$DIST" -type d -exec chmod 755 {} \; @@ -56,10 +57,10 @@ make_deb() { ln -s pandoc pandoc-server ln -s pandoc pandoc-lua popd - for manpage in pandoc.1 pandoc-lua.1 pandoc-server.1 + for manpage in pandoc.1 pandoc-lua.1 pandoc-server.1 pandoc-templates.5 do - cp "$WORK/pandoc-cli/man/$manpage" "$DEST/share/man/man1/$manpage" - gzip -9 "$DEST/share/man/man1/$manpage" + cp "$WORK/pandoc-cli/man/$manpage" "$DEST/share/man/man${manpage##*.}/$manpage" + gzip -9 "$DEST/share/man/man${manpage##*.}/$manpage" done cp $WORK/COPYRIGHT "$COPYRIGHT" echo "" >> "$COPYRIGHT" @@ -84,9 +85,11 @@ make_tarball() { pushd "$ARTIFACTS" rm -rf "$TARGET" mkdir "$TARGET" - mkdir "$TARGET/bin" "$TARGET/share" "$TARGET/share/man" "$TARGET/share/man/man1" + mkdir "$TARGET/bin" "$TARGET/share" "$TARGET/share/man" "$TARGET/share/man/man1" "$TARGET/share/man/man5" cp $WORK/pandoc-cli/man/pandoc.1 $WORK/pandoc-cli/man/pandoc-server.1 $WORK/pandoc-cli/man/pandoc-lua.1 "$TARGET/share/man/man1" + cp $WORK/pandoc-cli/man/pandoc-templates.5 "$TARGET/share/man/man5" gzip -9 "$TARGET"/share/man/man1/*.1 + gzip -9 "$TARGET"/share/man/man5/*.5 mv pandoc "$TARGET/bin" pushd "$TARGET/bin" ln -s pandoc pandoc-server diff --git a/macos/make_macos_release.sh b/macos/make_macos_release.sh index 6e988c0092ab..9c1516abaa9e 100644 --- a/macos/make_macos_release.sh +++ b/macos/make_macos_release.sh @@ -22,6 +22,7 @@ mkdir -p $ARTIFACTS mkdir -p $RESOURCES mkdir -p $DEST/bin mkdir -p $DEST/share/man/man1 +mkdir -p $DEST/share/man/man5 # Copy binary and strip it echo "Copying executable..." @@ -33,6 +34,7 @@ echo "Copying manuals and license..." cp pandoc-cli/man/pandoc.1 "$DEST/share/man/man1/pandoc.1" cp pandoc-cli/man/pandoc-server.1 "$DEST/share/man/man1/pandoc-server.1" cp pandoc-cli/man/pandoc-lua.1 "$DEST/share/man/man1/pandoc-lua.1" +cp pandoc-cli/man/pandoc-templates.5 "$DEST/share/man/man5/pandoc-templates.5" "$BINPATH" -s COPYING.md -Vpagetitle=License -o "$RESOURCES/license.html" # Prepare distribution directory; after downloading, run 'make' to notarize diff --git a/man/manfilter.lua b/man/manfilter.lua index 6abd950fc7e1..f6474afb1947 100644 --- a/man/manfilter.lua +++ b/man/manfilter.lua @@ -1,6 +1,11 @@ -- we use preloaded text to get a UTF-8 aware 'upper' function local text = require('text') +local manuals = { + ["MANUAL.txt"] = { title = "pandoc", section = "1" }, + ["templates.md"] = { title = "pandoc-templates", section = "5" } +} + -- capitalize level 1 headers function Header(el) if el.level == 1 then @@ -35,7 +40,12 @@ end -- replace links with link text function Link(el) - return el.content + local manual = manuals[el.target] + if manual then + return pandoc.RawInline("man", "\\fI" .. manual.title .. "\\fR(" .. manual.section .. ")") + else + return el.content + end end -- remove notes diff --git a/man/template.man b/man/template.man new file mode 100644 index 000000000000..b4db05b512e4 --- /dev/null +++ b/man/template.man @@ -0,0 +1,28 @@ +$if(has-tables)$ +'\" t +$endif$ +$if(pandoc-version)$ +.\" Automatically generated by Pandoc $pandoc-version$ +.\" +$endif$ +$if(adjusting)$ +.ad $adjusting$ +$endif$ +.TH "$title/nowrap$" "$section/nowrap$" "$date/nowrap$" "$footer/nowrap$"$if(header)$ "$header/nowrap$"$endif$ +$for(header-includes)$ +$header-includes$ +$endfor$ +$for(include-before)$ +$include-before$ +$endfor$ +.SH NAME +$title$ - $subtitle$ +.SH DESCRIPTION +$body$ +$for(include-after)$ +$include-after$ +$endfor$ +$if(author)$ +.SH AUTHORS +$for(author)$$author$$sep$; $endfor$. +$endif$ diff --git a/pandoc-cli/man/pandoc-templates.5 b/pandoc-cli/man/pandoc-templates.5 new file mode 100644 index 000000000000..e413a549e12b --- /dev/null +++ b/pandoc-cli/man/pandoc-templates.5 @@ -0,0 +1,1242 @@ +.\" Automatically generated by Pandoc 3.5 +.\" +.TH "pandoc-templates" "5" "" "pandoc 3.5" "Pandoc User\[cq]s Guide" +.SH NAME +pandoc-templates - templates for standalone pandoc output +.SH DESCRIPTION +.PP +When the \f[CR]\-s/\-\-standalone\f[R] option is used, pandoc uses a +template to add header and footer material that is needed for a +self\-standing document. +To see the default template that is used, just type +.IP +.EX +pandoc \-D *FORMAT* +.EE +.PP +where \f[I]FORMAT\f[R] is the name of the output format. +A custom template can be specified using the \f[CR]\-\-template\f[R] +option. +You can also override the system default templates for a given output +format \f[I]FORMAT\f[R] by putting a file +\f[CR]templates/default.*FORMAT*\f[R] in the user data directory (see +\f[CR]\-\-data\-dir\f[R], above). +\f[I]Exceptions:\f[R] +.IP \[bu] 2 +For \f[CR]odt\f[R] output, customize the \f[CR]default.opendocument\f[R] +template. +.IP \[bu] 2 +For \f[CR]docx\f[R] output, customize the \f[CR]default.openxml\f[R] +template. +.IP \[bu] 2 +For \f[CR]pdf\f[R] output, customize the \f[CR]default.latex\f[R] +template (or the \f[CR]default.context\f[R] template, if you use +\f[CR]\-t context\f[R], or the \f[CR]default.ms\f[R] template, if you +use \f[CR]\-t ms\f[R], or the \f[CR]default.html\f[R] template, if you +use \f[CR]\-t html\f[R]). +.IP \[bu] 2 +\f[CR]pptx\f[R] has no template. +.PP +Note that \f[CR]docx\f[R], \f[CR]odt\f[R], and \f[CR]pptx\f[R] output +can also be customized using \f[CR]\-\-reference\-doc\f[R]. +Use a reference doc to adjust the styles in your document; use a +template to handle variable interpolation and customize the presentation +of metadata, the position of the table of contents, boilerplate text, +etc. +.PP +Templates contain \f[I]variables\f[R], which allow for the inclusion of +arbitrary information at any point in the file. +They may be set at the command line using the +\f[CR]\-V/\-\-variable\f[R] option. +If a variable is not set, pandoc will look for the key in the +document\[cq]s metadata, which can be set using either [YAML metadata +blocks][Extension: \f[CR]yaml_metadata_block\f[R]] or with the +\f[CR]\-M/\-\-metadata\f[R] option. +In addition, some variables are given default values by pandoc. +See Variables below for a list of variables used in pandoc\[cq]s default +templates. +.PP +If you use custom templates, you may need to revise them as pandoc +changes. +We recommend tracking the changes in the default templates, and +modifying your custom templates accordingly. +An easy way to do this is to fork the pandoc\-templates repository and +merge in changes after each pandoc release. +.SH TEMPLATE SYNTAX +.SS Comments +Anything between the sequence \f[CR]$\-\-\f[R] and the end of the line +will be treated as a comment and omitted from the output. +.SS Delimiters +To mark variables and control structures in the template, either +\f[CR]$\f[R]\&...\f[CR]$\f[R] or \f[CR]${\f[R]\&...\f[CR]}\f[R] may be +used as delimiters. +The styles may also be mixed in the same template, but the opening and +closing delimiter must match in each case. +The opening delimiter may be followed by one or more spaces or tabs, +which will be ignored. +The closing delimiter may be preceded by one or more spaces or tabs, +which will be ignored. +.PP +To include a literal \f[CR]$\f[R] in the document, use \f[CR]$$\f[R]. +.SS Interpolated variables +A slot for an interpolated variable is a variable name surrounded by +matched delimiters. +Variable names must begin with a letter and can contain letters, +numbers, \f[CR]_\f[R], \f[CR]\-\f[R], and \f[CR].\f[R]. +The keywords \f[CR]it\f[R], \f[CR]if\f[R], \f[CR]else\f[R], +\f[CR]endif\f[R], \f[CR]for\f[R], \f[CR]sep\f[R], and \f[CR]endfor\f[R] +may not be used as variable names. +Examples: +.IP +.EX +$foo$ +$foo.bar.baz$ +$foo_bar.baz\-bim$ +$ foo $ +${foo} +${foo.bar.baz} +${foo_bar.baz\-bim} +${ foo } +.EE +.PP +Variable names with periods are used to get at structured variable +values. +So, for example, \f[CR]employee.salary\f[R] will return the value of the +\f[CR]salary\f[R] field of the object that is the value of the +\f[CR]employee\f[R] field. +.IP \[bu] 2 +If the value of the variable is a simple value, it will be rendered +verbatim. +(Note that no escaping is done; the assumption is that the calling +program will escape the strings appropriately for the output format.) +.IP \[bu] 2 +If the value is a list, the values will be concatenated. +.IP \[bu] 2 +If the value is a map, the string \f[CR]true\f[R] will be rendered. +.IP \[bu] 2 +Every other value will be rendered as the empty string. +.SS Conditionals +A conditional begins with \f[CR]if(variable)\f[R] (enclosed in matched +delimiters) and ends with \f[CR]endif\f[R] (enclosed in matched +delimiters). +It may optionally contain an \f[CR]else\f[R] (enclosed in matched +delimiters). +The \f[CR]if\f[R] section is used if \f[CR]variable\f[R] has a true +value, otherwise the \f[CR]else\f[R] section is used (if present). +The following values count as true: +.IP \[bu] 2 +any map +.IP \[bu] 2 +any array containing at least one true value +.IP \[bu] 2 +any nonempty string +.IP \[bu] 2 +boolean True +.PP +Note that in YAML metadata (and metadata specified on the command line +using \f[CR]\-M/\-\-metadata\f[R]), unquoted \f[CR]true\f[R] and +\f[CR]false\f[R] will be interpreted as Boolean values. +But a variable specified on the command line using +\f[CR]\-V/\-\-variable\f[R] will always be given a string value. +Hence a conditional \f[CR]if(foo)\f[R] will be triggered if you use +\f[CR]\-V foo=false\f[R], but not if you use \f[CR]\-M foo=false\f[R]. +.PP +Examples: +.IP +.EX +$if(foo)$bar$endif$ + +$if(foo)$ + $foo$ +$endif$ + +$if(foo)$ +part one +$else$ +part two +$endif$ + +${if(foo)}bar${endif} + +${if(foo)} + ${foo} +${endif} + +${if(foo)} +${ foo.bar } +${else} +no foo! +${endif} +.EE +.PP +The keyword \f[CR]elseif\f[R] may be used to simplify complex nested +conditionals: +.IP +.EX +$if(foo)$ +XXX +$elseif(bar)$ +YYY +$else$ +ZZZ +$endif$ +.EE +.SS For loops +A for loop begins with \f[CR]for(variable)\f[R] (enclosed in matched +delimiters) and ends with \f[CR]endfor\f[R] (enclosed in matched +delimiters). +.IP \[bu] 2 +If \f[CR]variable\f[R] is an array, the material inside the loop will be +evaluated repeatedly, with \f[CR]variable\f[R] being set to each value +of the array in turn, and concatenated. +.IP \[bu] 2 +If \f[CR]variable\f[R] is a map, the material inside will be set to the +map. +.IP \[bu] 2 +If the value of the associated variable is not an array or a map, a +single iteration will be performed on its value. +.PP +Examples: +.IP +.EX +$for(foo)$$foo$$sep$, $endfor$ + +$for(foo)$ + \- $foo.last$, $foo.first$ +$endfor$ + +${ for(foo.bar) } + \- ${ foo.bar.last }, ${ foo.bar.first } +${ endfor } + +$for(mymap)$ +$it.name$: $it.office$ +$endfor$ +.EE +.PP +You may optionally specify a separator between consecutive values using +\f[CR]sep\f[R] (enclosed in matched delimiters). +The material between \f[CR]sep\f[R] and the \f[CR]endfor\f[R] is the +separator. +.IP +.EX +${ for(foo) }${ foo }${ sep }, ${ endfor } +.EE +.PP +Instead of using \f[CR]variable\f[R] inside the loop, the special +anaphoric keyword \f[CR]it\f[R] may be used. +.IP +.EX +${ for(foo.bar) } + \- ${ it.last }, ${ it.first } +${ endfor } +.EE +.SS Partials +Partials (subtemplates stored in different files) may be included by +using the name of the partial, followed by \f[CR]()\f[R], for example: +.IP +.EX +${ styles() } +.EE +.PP +Partials will be sought in the directory containing the main template. +The file name will be assumed to have the same extension as the main +template if it lacks an extension. +When calling the partial, the full name including file extension can +also be used: +.IP +.EX +${ styles.html() } +.EE +.PP +(If a partial is not found in the directory of the template and the +template path is given as a relative path, it will also be sought in the +\f[CR]templates\f[R] subdirectory of the user data directory.) +.PP +Partials may optionally be applied to variables using a colon: +.IP +.EX +${ date:fancy() } + +${ articles:bibentry() } +.EE +.PP +If \f[CR]articles\f[R] is an array, this will iterate over its values, +applying the partial \f[CR]bibentry()\f[R] to each one. +So the second example above is equivalent to +.IP +.EX +${ for(articles) } +${ it:bibentry() } +${ endfor } +.EE +.PP +Note that the anaphoric keyword \f[CR]it\f[R] must be used when +iterating over partials. +In the above examples, the \f[CR]bibentry\f[R] partial should contain +\f[CR]it.title\f[R] (and so on) instead of \f[CR]articles.title\f[R]. +.PP +Final newlines are omitted from included partials. +.PP +Partials may include other partials. +.PP +A separator between values of an array may be specified in square +brackets, immediately after the variable name or partial: +.IP +.EX +${months[, ]} + +${articles:bibentry()[; ]} +.EE +.PP +The separator in this case is literal and (unlike with \f[CR]sep\f[R] in +an explicit \f[CR]for\f[R] loop) cannot contain interpolated variables +or other template directives. +.SS Nesting +To ensure that content is \[lq]nested,\[rq] that is, subsequent lines +indented, use the \f[CR]\[ha]\f[R] directive: +.IP +.EX +$item.number$ $\[ha]$$item.description$ ($item.price$) +.EE +.PP +In this example, if \f[CR]item.description\f[R] has multiple lines, they +will all be indented to line up with the first line: +.IP +.EX +00123 A fine bottle of 18\-year old + Oban whiskey. ($148) +.EE +.PP +To nest multiple lines to the same level, align them with the +\f[CR]\[ha]\f[R] directive in the template. +For example: +.IP +.EX +$item.number$ $\[ha]$$item.description$ ($item.price$) + (Available til $item.sellby$.) +.EE +.PP +will produce +.IP +.EX +00123 A fine bottle of 18\-year old + Oban whiskey. ($148) + (Available til March 30, 2020.) +.EE +.PP +If a variable occurs by itself on a line, preceded by whitespace and not +followed by further text or directives on the same line, and the +variable\[cq]s value contains multiple lines, it will be nested +automatically. +.SS Breakable spaces +Normally, spaces in the template itself (as opposed to values of the +interpolated variables) are not breakable, but they can be made +breakable in part of the template by using the \f[CR]\[ti]\f[R] keyword +(ended with another \f[CR]\[ti]\f[R]). +.IP +.EX +$\[ti]$This long line may break if the document is rendered +with a short line length.$\[ti]$ +.EE +.SS Pipes +A pipe transforms the value of a variable or partial. +Pipes are specified using a slash (\f[CR]/\f[R]) between the variable +name (or partial) and the pipe name. +Example: +.IP +.EX +$for(name)$ +$name/uppercase$ +$endfor$ + +$for(metadata/pairs)$ +\- $it.key$: $it.value$ +$endfor$ + +$employee:name()/uppercase$ +.EE +.PP +Pipes may be chained: +.IP +.EX +$for(employees/pairs)$ +$it.key/alpha/uppercase$. $it.name$ +$endfor$ +.EE +.PP +Some pipes take parameters: +.IP +.EX +|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| +$for(employee)$ +$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$ +$endfor$ +|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| +.EE +.PP +Currently the following pipes are predefined: +.IP \[bu] 2 +\f[CR]pairs\f[R]: Converts a map or array to an array of maps, each with +\f[CR]key\f[R] and \f[CR]value\f[R] fields. +If the original value was an array, the \f[CR]key\f[R] will be the array +index, starting with 1. +.IP \[bu] 2 +\f[CR]uppercase\f[R]: Converts text to uppercase. +.IP \[bu] 2 +\f[CR]lowercase\f[R]: Converts text to lowercase. +.IP \[bu] 2 +\f[CR]length\f[R]: Returns the length of the value: number of characters +for a textual value, number of elements for a map or array. +.IP \[bu] 2 +\f[CR]reverse\f[R]: Reverses a textual value or array, and has no effect +on other values. +.IP \[bu] 2 +\f[CR]first\f[R]: Returns the first value of an array, if applied to a +non\-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]last\f[R]: Returns the last value of an array, if applied to a +non\-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]rest\f[R]: Returns all but the first value of an array, if applied +to a non\-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]allbutlast\f[R]: Returns all but the last value of an array, if +applied to a non\-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]chomp\f[R]: Removes trailing newlines (and breakable space). +.IP \[bu] 2 +\f[CR]nowrap\f[R]: Disables line wrapping on breakable spaces. +.IP \[bu] 2 +\f[CR]alpha\f[R]: Converts textual values that can be read as an integer +into lowercase alphabetic characters \f[CR]a..z\f[R] (mod 26). +This can be used to get lettered enumeration from array indices. +To get uppercase letters, chain with \f[CR]uppercase\f[R]. +.IP \[bu] 2 +\f[CR]roman\f[R]: Converts textual values that can be read as an integer +into lowercase roman numerals. +This can be used to get lettered enumeration from array indices. +To get uppercase roman, chain with \f[CR]uppercase\f[R]. +.IP \[bu] 2 +\f[CR]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +textual value in a block of width \f[CR]n\f[R], aligned to the left, +with an optional left and right border. +Has no effect on other values. +This can be used to align material in tables. +Widths are positive integers indicating the number of characters. +Borders are strings inside double quotes; literal \f[CR]\[dq]\f[R] and +\f[CR]\[rs]\f[R] characters must be backslash\-escaped. +.IP \[bu] 2 +\f[CR]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +textual value in a block of width \f[CR]n\f[R], aligned to the right, +and has no effect on other values. +.IP \[bu] 2 +\f[CR]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders +a textual value in a block of width \f[CR]n\f[R], aligned to the center, +and has no effect on other values. +.SH VARIABLES +.SS Metadata variables +.TP +\f[CR]title\f[R], \f[CR]author\f[R], \f[CR]date\f[R] +allow identification of basic aspects of the document. +Included in PDF metadata through LaTeX and ConTeXt. +These can be set through a [pandoc title block][Extension: +\f[CR]pandoc_title_block\f[R]], which allows for multiple authors, or +through a [YAML metadata block][Extension: +\f[CR]yaml_metadata_block\f[R]]: +.RS +.IP +.EX +\-\-\- +author: +\- Aristotle +\- Peter Abelard +\&... +.EE +.PP +Note that if you just want to set PDF or HTML metadata, without +including a title block in the document itself, you can set the +\f[CR]title\-meta\f[R], \f[CR]author\-meta\f[R], and +\f[CR]date\-meta\f[R] variables. +(By default these are set automatically, based on \f[CR]title\f[R], +\f[CR]author\f[R], and \f[CR]date\f[R].) +The page title in HTML is set by \f[CR]pagetitle\f[R], which is equal to +\f[CR]title\f[R] by default. +.RE +.TP +\f[CR]subtitle\f[R] +document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx +documents +.TP +\f[CR]abstract\f[R] +document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc, and docx +documents +.TP +\f[CR]abstract\-title\f[R] +title of abstract, currently used only in HTML, EPUB, and docx. +This will be set automatically to a localized value, depending on +\f[CR]lang\f[R], but can be manually overridden. +.TP +\f[CR]keywords\f[R] +list of keywords to be included in HTML, PDF, ODT, pptx, docx and +AsciiDoc metadata; repeat as for \f[CR]author\f[R], above +.TP +\f[CR]subject\f[R] +document subject, included in ODT, PDF, docx, EPUB, and pptx metadata +.TP +\f[CR]description\f[R] +document description, included in ODT, docx and pptx metadata. +Some applications show this as \f[CR]Comments\f[R] metadata. +.TP +\f[CR]category\f[R] +document category, included in docx and pptx metadata +.PP +Additionally, any root\-level string metadata, not included in ODT, docx +or pptx metadata is added as a \f[I]custom property\f[R]. +The following [YAML] metadata block for instance: +.IP +.EX +\-\-\- +title: \[aq]This is the title\[aq] +subtitle: \[dq]This is the subtitle\[dq] +author: +\- Author One +\- Author Two +description: | + This is a long + description. + + It consists of two paragraphs +\&... +.EE +.PP +will include \f[CR]title\f[R], \f[CR]author\f[R] and +\f[CR]description\f[R] as standard document properties and +\f[CR]subtitle\f[R] as a custom property when converting to docx, ODT or +pptx. +.SS Language variables +.TP +\f[CR]lang\f[R] +identifies the main language of the document using IETF language tags +(following the BCP 47 standard), such as \f[CR]en\f[R] or +\f[CR]en\-GB\f[R]. +The Language subtag lookup tool can look up or verify these tags. +This affects most formats, and controls hyphenation in PDF output when +using LaTeX (through [\f[CR]babel\f[R]] and [\f[CR]polyglossia\f[R]]) or +ConTeXt. +.RS +.PP +Use native pandoc [Divs and Spans] with the \f[CR]lang\f[R] attribute to +switch the language: +.IP +.EX +\-\-\- +lang: en\-GB +\&... + +Text in the main document language (British English). + +::: {lang=fr\-CA} +> Cette citation est écrite en français canadien. +::: + +More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de} +.EE +.RE +.TP +\f[CR]dir\f[R] +the base script direction, either \f[CR]rtl\f[R] (right\-to\-left) or +\f[CR]ltr\f[R] (left\-to\-right). +.RS +.PP +For bidirectional documents, native pandoc \f[CR]span\f[R]s and +\f[CR]div\f[R]s with the \f[CR]dir\f[R] attribute (value \f[CR]rtl\f[R] +or \f[CR]ltr\f[R]) can be used to override the base direction in some +output formats. +This may not always be necessary if the final renderer (e.g.\ the +browser, when generating HTML) supports the Unicode Bidirectional +Algorithm. +.PP +When using LaTeX for bidirectional documents, only the +\f[CR]xelatex\f[R] engine is fully supported (use +\f[CR]\-\-pdf\-engine=xelatex\f[R]). +.RE +.SS Variables for HTML +.TP +\f[CR]document\-css\f[R] +Enables inclusion of most of the CSS in the \f[CR]styles.html\f[R] +partial (have a look with +\f[CR]pandoc \-\-print\-default\-data\-file=templates/styles.html\f[R]). +Unless you use \f[CR]\-\-css\f[R], this variable is set to +\f[CR]true\f[R] by default. +You can disable it with e.g.\ \f[CR]pandoc \-M document\-css=false\f[R]. +.TP +\f[CR]mainfont\f[R] +sets the CSS \f[CR]font\-family\f[R] property on the \f[CR]html\f[R] +element. +.TP +\f[CR]fontsize\f[R] +sets the base CSS \f[CR]font\-size\f[R], which you\[cq]d usually set to +e.g.\ \f[CR]20px\f[R], but it also accepts \f[CR]pt\f[R] (12pt = 16px in +most browsers). +.TP +\f[CR]fontcolor\f[R] +sets the CSS \f[CR]color\f[R] property on the \f[CR]html\f[R] element. +.TP +\f[CR]linkcolor\f[R] +sets the CSS \f[CR]color\f[R] property on all links. +.TP +\f[CR]monofont\f[R] +sets the CSS \f[CR]font\-family\f[R] property on \f[CR]code\f[R] +elements. +.TP +\f[CR]monobackgroundcolor\f[R] +sets the CSS \f[CR]background\-color\f[R] property on \f[CR]code\f[R] +elements and adds extra padding. +.TP +\f[CR]linestretch\f[R] +sets the CSS \f[CR]line\-height\f[R] property on the \f[CR]html\f[R] +element, which is preferred to be unitless. +.TP +\f[CR]maxwidth\f[R] +sets the CSS \f[CR]max\-width\f[R] property (default is 32em). +.TP +\f[CR]backgroundcolor\f[R] +sets the CSS \f[CR]background\-color\f[R] property on the +\f[CR]html\f[R] element. +.TP +\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] +sets the corresponding CSS \f[CR]padding\f[R] properties on the +\f[CR]body\f[R] element. +.PP +To override or extend some CSS for just one document, include for +example: +.IP +.EX +\-\-\- +header\-includes: | + +\-\-\- +.EE +.SS Variables for HTML math +.TP +\f[CR]classoption\f[R] +when using \f[CR]\-\-katex\f[R], you can render display math equations +flush left using YAML metadata or with \f[CR]\-M classoption=fleqn\f[R]. +.SS Variables for HTML slides +These affect HTML output when producing slide shows with pandoc. +.TP +\f[CR]institute\f[R] +author affiliations: can be a list when there are multiple authors +.TP +\f[CR]revealjs\-url\f[R] +base URL for reveal.js documents (defaults to +\f[CR]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R]) +.TP +\f[CR]s5\-url\f[R] +base URL for S5 documents (defaults to \f[CR]s5/default\f[R]) +.TP +\f[CR]slidy\-url\f[R] +base URL for Slidy documents (defaults to +\f[CR]https://www.w3.org/Talks/Tools/Slidy2\f[R]) +.TP +\f[CR]slideous\-url\f[R] +base URL for Slideous documents (defaults to \f[CR]slideous\f[R]) +.TP +\f[CR]title\-slide\-attributes\f[R] +additional attributes for the title slide of reveal.js slide shows. +See [background in reveal.js, beamer, and pptx] for an example. +.PP +All reveal.js configuration options are available as variables. +To turn off boolean flags that default to true in reveal.js, use +\f[CR]0\f[R]. +.SS Variables for Beamer slides +These variables change the appearance of PDF slides using +[\f[CR]beamer\f[R]]. +.TP +\f[CR]aspectratio\f[R] +slide aspect ratio (\f[CR]43\f[R] for 4:3 [default], \f[CR]169\f[R] for +16:9, \f[CR]1610\f[R] for 16:10, \f[CR]149\f[R] for 14:9, \f[CR]141\f[R] +for 1.41:1, \f[CR]54\f[R] for 5:4, \f[CR]32\f[R] for 3:2) +.TP +\f[CR]beameroption\f[R] +add extra beamer option with \f[CR]\[rs]setbeameroption{}\f[R] +.TP +\f[CR]institute\f[R] +author affiliations: can be a list when there are multiple authors +.TP +\f[CR]logo\f[R] +logo image for slides +.TP +\f[CR]navigation\f[R] +controls navigation symbols (default is \f[CR]empty\f[R] for no +navigation symbols; other valid values are \f[CR]frame\f[R], +\f[CR]vertical\f[R], and \f[CR]horizontal\f[R]) +.TP +\f[CR]section\-titles\f[R] +enables \[lq]title pages\[rq] for new sections (default is true) +.TP +\f[CR]theme\f[R], \f[CR]colortheme\f[R], \f[CR]fonttheme\f[R], \f[CR]innertheme\f[R], \f[CR]outertheme\f[R] +beamer themes +.TP +\f[CR]themeoptions\f[R], \f[CR]colorthemeoptions\f[R], \f[CR]fontthemeoptions\f[R], \f[CR]innerthemeoptions\f[R], \f[CR]outerthemeoptions\f[R] +options for LaTeX beamer themes (lists) +.TP +\f[CR]titlegraphic\f[R] +image for title slide: can be a list +.TP +\f[CR]titlegraphicoptions\f[R] +options for title slide image +.TP +\f[CR]shorttitle\f[R], \f[CR]shortsubtitle\f[R], \f[CR]shortauthor\f[R], \f[CR]shortinstitute\f[R], \f[CR]shortdate\f[R] +some beamer themes use short versions of the title, subtitle, author, +institute, date +.SS Variables for PowerPoint +These variables control the visual aspects of a slide show that are not +easily controlled via templates. +.TP +\f[CR]monofont\f[R] +font to use for code. +.SS Variables for LaTeX +Pandoc uses these variables when [creating a PDF] with a LaTeX engine. +.SS Layout +.TP +\f[CR]block\-headings\f[R] +make \f[CR]\[rs]paragraph\f[R] and \f[CR]\[rs]subparagraph\f[R] +(fourth\- and fifth\-level headings, or fifth\- and sixth\-level with +book classes) free\-standing rather than run\-in; requires further +formatting to distinguish from \f[CR]\[rs]subsubsection\f[R] (third\- or +fourth\-level headings). +Instead of using this option, KOMA\-Script can adjust headings more +extensively: +.RS +.IP +.EX +\-\-\- +documentclass: scrartcl +header\-includes: | + \[rs]RedeclareSectionCommand[ + beforeskip=\-10pt plus \-2pt minus \-1pt, + afterskip=1sp plus \-1sp minus 1sp, + font=\[rs]normalfont\[rs]itshape]{paragraph} + \[rs]RedeclareSectionCommand[ + beforeskip=\-10pt plus \-2pt minus \-1pt, + afterskip=1sp plus \-1sp minus 1sp, + font=\[rs]normalfont\[rs]scshape, + indent=0pt]{subparagraph} +\&... +.EE +.RE +.TP +\f[CR]classoption\f[R] +option for document class, e.g.\ \f[CR]oneside\f[R]; repeat for multiple +options: +.RS +.IP +.EX +\-\-\- +classoption: +\- twocolumn +\- landscape +\&... +.EE +.RE +.TP +\f[CR]documentclass\f[R] +document class: usually one of the standard classes, \f[CR]article\f[R], +\f[CR]book\f[R], and \f[CR]report\f[R]; the KOMA\-Script equivalents, +\f[CR]scrartcl\f[R], \f[CR]scrbook\f[R], and \f[CR]scrreprt\f[R], which +default to smaller margins; or \f[CR]memoir\f[R] +.TP +\f[CR]geometry\f[R] +option for [\f[CR]geometry\f[R]] package, e.g.\ \f[CR]margin=1in\f[R]; +repeat for multiple options: +.RS +.IP +.EX +\-\-\- +geometry: +\- top=30mm +\- left=20mm +\- heightrounded +\&... +.EE +.RE +.TP +\f[CR]hyperrefoptions\f[R] +option for [\f[CR]hyperref\f[R]] package, e.g.\ \f[CR]linktoc=all\f[R]; +repeat for multiple options: +.RS +.IP +.EX +\-\-\- +hyperrefoptions: +\- linktoc=all +\- pdfwindowui +\- pdfpagemode=FullScreen +\&... +.EE +.RE +.TP +\f[CR]indent\f[R] +if true, pandoc will use document class settings for indentation (the +default LaTeX template otherwise removes indentation and adds space +between paragraphs) +.TP +\f[CR]linestretch\f[R] +adjusts line spacing using the [\f[CR]setspace\f[R]] package, +e.g.\ \f[CR]1.25\f[R], \f[CR]1.5\f[R] +.TP +\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] +sets margins if \f[CR]geometry\f[R] is not used (otherwise +\f[CR]geometry\f[R] overrides these) +.TP +\f[CR]pagestyle\f[R] +control \f[CR]\[rs]pagestyle{}\f[R]: the default article class supports +\f[CR]plain\f[R] (default), \f[CR]empty\f[R] (no running heads or page +numbers), and \f[CR]headings\f[R] (section titles in running heads) +.TP +\f[CR]papersize\f[R] +paper size, e.g.\ \f[CR]letter\f[R], \f[CR]a4\f[R] +.TP +\f[CR]secnumdepth\f[R] +numbering depth for sections (with \f[CR]\-\-number\-sections\f[R] +option or \f[CR]numbersections\f[R] variable) +.TP +\f[CR]beamerarticle\f[R] +produce an article from Beamer slides. +Note: if you set this variable, you must specify the beamer writer but +use the default \f[I]LaTeX\f[R] template: for example, +\f[CR]pandoc \-Vbeamerarticle \-t beamer \-\-template default.latex\f[R]. +.TP +\f[CR]handout\f[R] +produce a handout version of Beamer slides (with overlays condensed into +single slides) +.SS Fonts +.TP +\f[CR]fontenc\f[R] +allows font encoding to be specified through \f[CR]fontenc\f[R] package +(with \f[CR]pdflatex\f[R]); default is \f[CR]T1\f[R] (see LaTeX font +encodings guide) +.TP +\f[CR]fontfamily\f[R] +font package for use with \f[CR]pdflatex\f[R]: [TeX Live] includes many +options, documented in the LaTeX Font Catalogue. +The default is [Latin Modern][\f[CR]lm\f[R]]. +.TP +\f[CR]fontfamilyoptions\f[R] +options for package used as \f[CR]fontfamily\f[R]; repeat for multiple +options. +For example, to use the Libertine font with proportional lowercase +(old\-style) figures through the \f[CR]libertinus\f[R] package: +.RS +.IP +.EX +\-\-\- +fontfamily: libertinus +fontfamilyoptions: +\- osf +\- p +\&... +.EE +.RE +.TP +\f[CR]fontsize\f[R] +font size for body text. +The standard classes allow 10pt, 11pt, and 12pt. +To use another size, set \f[CR]documentclass\f[R] to one of the +KOMA\-Script classes, such as \f[CR]scrartcl\f[R] or \f[CR]scrbook\f[R]. +.TP +\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R], \f[CR]CJKsansfont\f[R], \f[CR]CJKmonofont\f[R] +font families for use with \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R]: +take the name of any system font, using the [\f[CR]fontspec\f[R]] +package. +\f[CR]CJKmainfont\f[R] uses the [\f[CR]xecjk\f[R]] package if +\f[CR]xelatex\f[R] is used, or the [\f[CR]luatexja\f[R]] package if +\f[CR]lualatex\f[R] is used. +.TP +\f[CR]mainfontoptions\f[R], \f[CR]sansfontoptions\f[R], \f[CR]monofontoptions\f[R], \f[CR]mathfontoptions\f[R], \f[CR]CJKoptions\f[R], \f[CR]luatexjapresetoptions\f[R] +options to use with \f[CR]mainfont\f[R], \f[CR]sansfont\f[R], +\f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R] in +\f[CR]xelatex\f[R] and \f[CR]lualatex\f[R]. +Allow for any choices available through [\f[CR]fontspec\f[R]]; repeat +for multiple options. +For example, to use the TeX Gyre version of Palatino with lowercase +figures: +.RS +.IP +.EX +\-\-\- +mainfont: TeX Gyre Pagella +mainfontoptions: +\- Numbers=Lowercase +\- Numbers=Proportional +\&... +.EE +.RE +.TP +\f[CR]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] +fonts to try if a glyph isn\[cq]t found in \f[CR]mainfont\f[R], +\f[CR]sansfont\f[R], or \f[CR]monofont\f[R] respectively. +These are lists. +The font name must be followed by a colon and optionally a set of +options, for example: +.RS +.IP +.EX +\-\-\- +mainfontfallback: + \- \[dq]FreeSans:\[dq] + \- \[dq]NotoColorEmoji:mode=harf\[dq] +\&... +.EE +.PP +Font fallbacks currently only work with \f[CR]lualatex\f[R]. +.RE +.TP +\f[CR]babelfonts\f[R] +a map of Babel language names (e.g.\ \f[CR]chinese\f[R]) to the font to +be used with the language: +.RS +.IP +.EX +\-\-\- +babelfonts: + chinese\-hant: \[dq]Noto Serif CJK TC\[dq] + russian: \[dq]Noto Serif\[dq] +\&... +.EE +.RE +.TP +\f[CR]microtypeoptions\f[R] +options to pass to the microtype package +.SS Links +.TP +\f[CR]colorlinks\f[R] +add color to link text; automatically enabled if any of +\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], +\f[CR]urlcolor\f[R], or \f[CR]toccolor\f[R] are set +.TP +\f[CR]boxlinks\f[R] +add visible box around links (has no effect if \f[CR]colorlinks\f[R] is +set) +.TP +\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], \f[CR]urlcolor\f[R], \f[CR]toccolor\f[R] +color for internal links, external links, citation links, linked URLs, +and links in table of contents, respectively: uses options allowed by +[\f[CR]xcolor\f[R]], including the \f[CR]dvipsnames\f[R], +\f[CR]svgnames\f[R], and \f[CR]x11names\f[R] lists +.TP +\f[CR]links\-as\-notes\f[R] +causes links to be printed as footnotes +.TP +\f[CR]urlstyle\f[R] +style for URLs (e.g., \f[CR]tt\f[R], \f[CR]rm\f[R], \f[CR]sf\f[R], and, +the default, \f[CR]same\f[R]) +.SS Front matter +.TP +\f[CR]lof\f[R], \f[CR]lot\f[R] +include list of figures, list of tables (can also be set using +\f[CR]\-\-lof/\-\-list\-of\-figures\f[R], +\f[CR]\-\-lot/\-\-list\-of\-tables\f[R]) +.TP +\f[CR]thanks\f[R] +contents of acknowledgments footnote after document title +.TP +\f[CR]toc\f[R] +include table of contents (can also be set using +\f[CR]\-\-toc/\-\-table\-of\-contents\f[R]) +.TP +\f[CR]toc\-depth\f[R] +level of section to include in table of contents +.SS BibLaTeX Bibliographies +These variables function when using BibLaTeX for [citation rendering]. +.TP +\f[CR]biblatexoptions\f[R] +list of options for biblatex +.TP +\f[CR]biblio\-style\f[R] +bibliography style, when used with \f[CR]\-\-natbib\f[R] and +\f[CR]\-\-biblatex\f[R] +.TP +\f[CR]biblio\-title\f[R] +bibliography title, when used with \f[CR]\-\-natbib\f[R] and +\f[CR]\-\-biblatex\f[R] +.TP +\f[CR]bibliography\f[R] +bibliography to use for resolving references +.TP +\f[CR]natbiboptions\f[R] +list of options for natbib +.SS Variables for ConTeXt +Pandoc uses these variables when [creating a PDF] with ConTeXt. +.TP +\f[CR]fontsize\f[R] +font size for body text (e.g.\ \f[CR]10pt\f[R], \f[CR]12pt\f[R]) +.TP +\f[CR]headertext\f[R], \f[CR]footertext\f[R] +text to be placed in running header or footer (see ConTeXt Headers and +Footers); repeat up to four times for different placement +.TP +\f[CR]indenting\f[R] +controls indentation of paragraphs, e.g.\ \f[CR]yes,small,next\f[R] (see +ConTeXt Indentation); repeat for multiple options +.TP +\f[CR]interlinespace\f[R] +adjusts line spacing, e.g.\ \f[CR]4ex\f[R] (using +\f[CR]setupinterlinespace\f[R]); repeat for multiple options +.TP +\f[CR]layout\f[R] +options for page margins and text arrangement (see ConTeXt Layout); +repeat for multiple options +.TP +\f[CR]linkcolor\f[R], \f[CR]contrastcolor\f[R] +color for links outside and inside a page, e.g.\ \f[CR]red\f[R], +\f[CR]blue\f[R] (see ConTeXt Color) +.TP +\f[CR]linkstyle\f[R] +typeface style for links, e.g.\ \f[CR]normal\f[R], \f[CR]bold\f[R], +\f[CR]slanted\f[R], \f[CR]boldslanted\f[R], \f[CR]type\f[R], +\f[CR]cap\f[R], \f[CR]small\f[R] +.TP +\f[CR]lof\f[R], \f[CR]lot\f[R] +include list of figures, list of tables +.TP +\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R] +font families: take the name of any system font (see ConTeXt Font +Switching) +.TP +\f[CR]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] +list of fonts to try, in order, if a glyph is not found in the main +font. +Use \f[CR]\[rs]definefallbackfamily\f[R]\-compatible font name syntax. +Emoji fonts are unsupported. +.TP +\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] +sets margins, if \f[CR]layout\f[R] is not used (otherwise +\f[CR]layout\f[R] overrides these) +.TP +\f[CR]pagenumbering\f[R] +page number style and location (using \f[CR]setuppagenumbering\f[R]); +repeat for multiple options +.TP +\f[CR]papersize\f[R] +paper size, e.g.\ \f[CR]letter\f[R], \f[CR]A4\f[R], \f[CR]landscape\f[R] +(see ConTeXt Paper Setup); repeat for multiple options +.TP +\f[CR]pdfa\f[R] +adds to the preamble the setup necessary to generate PDF/A of the type +specified, e.g.\ \f[CR]1a:2005\f[R], \f[CR]2a\f[R]. +If no type is specified (i.e.\ the value is set to True, by e.g. +\f[CR]\-\-metadata=pdfa\f[R] or \f[CR]pdfa: true\f[R] in a YAML metadata +block), \f[CR]1b:2005\f[R] will be used as default, for reasons of +backwards compatibility. +Using \f[CR]\-\-variable=pdfa\f[R] without specified value is not +supported. +To successfully generate PDF/A the required ICC color profiles have to +be available and the content and all included files (such as images) +have to be standard\-conforming. +The ICC profiles and output intent may be specified using the variables +\f[CR]pdfaiccprofile\f[R] and \f[CR]pdfaintent\f[R]. +See also ConTeXt PDFA for more details. +.TP +\f[CR]pdfaiccprofile\f[R] +when used in conjunction with \f[CR]pdfa\f[R], specifies the ICC profile +to use in the PDF, e.g.\ \f[CR]default.cmyk\f[R]. +If left unspecified, \f[CR]sRGB.icc\f[R] is used as default. +May be repeated to include multiple profiles. +Note that the profiles have to be available on the system. +They can be obtained from ConTeXt ICC Profiles. +.TP +\f[CR]pdfaintent\f[R] +when used in conjunction with \f[CR]pdfa\f[R], specifies the output +intent for the colors, +e.g.\ \f[CR]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If +left unspecified, \f[CR]sRGB IEC61966\-2.1\f[R] is used as default. +.TP +\f[CR]toc\f[R] +include table of contents (can also be set using +\f[CR]\-\-toc/\-\-table\-of\-contents\f[R]) +.TP +\f[CR]urlstyle\f[R] +typeface style for links without link text, e.g.\ \f[CR]normal\f[R], +\f[CR]bold\f[R], \f[CR]slanted\f[R], \f[CR]boldslanted\f[R], +\f[CR]type\f[R], \f[CR]cap\f[R], \f[CR]small\f[R] +.TP +\f[CR]whitespace\f[R] +spacing between paragraphs, e.g.\ \f[CR]none\f[R], \f[CR]small\f[R] +(using \f[CR]setupwhitespace\f[R]) +.TP +\f[CR]includesource\f[R] +include all source documents as file attachments in the PDF file +.SS Variables for \f[CR]wkhtmltopdf\f[R] +Pandoc uses these variables when [creating a PDF] with +[\f[CR]wkhtmltopdf\f[R]]. +The \f[CR]\-\-css\f[R] option also affects the output. +.TP +\f[CR]footer\-html\f[R], \f[CR]header\-html\f[R] +add information to the header and footer +.TP +\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] +set the page margins +.TP +\f[CR]papersize\f[R] +sets the PDF paper size +.SS Variables for man pages +.TP +\f[CR]adjusting\f[R] +adjusts text to left (\f[CR]l\f[R]), right (\f[CR]r\f[R]), center +(\f[CR]c\f[R]), or both (\f[CR]b\f[R]) margins +.TP +\f[CR]footer\f[R] +footer in man pages +.TP +\f[CR]header\f[R] +header in man pages +.TP +\f[CR]section\f[R] +section number in man pages +.SS Variables for Texinfo +.TP +\f[CR]version\f[R] +version of software (used in title and title page) +.TP +\f[CR]filename\f[R] +name of info file to be generated (defaults to a name based on the texi +filename) +.SS Variables for Typst +.TP +\f[CR]margin\f[R] +A dictionary with the fields defined in the Typst documentation: +\f[CR]x\f[R], \f[CR]y\f[R], \f[CR]top\f[R], \f[CR]bottom\f[R], +\f[CR]left\f[R], \f[CR]right\f[R]. +.TP +\f[CR]papersize\f[R] +Paper size: \f[CR]a4\f[R], \f[CR]us\-letter\f[R], etc. +.TP +\f[CR]mainfont\f[R] +Name of system font to use for the main font. +.TP +\f[CR]fontsize\f[R] +Font size (e.g., \f[CR]12pt\f[R]). +.TP +\f[CR]section\-numbering\f[R] +Schema to use for numbering sections, e.g.\ \f[CR]1.A.1\f[R]. +.TP +\f[CR]page\-numbering\f[R] +Schema to use for numbering pages, e.g.\ \f[CR]1\f[R] or \f[CR]i\f[R], +or an empty string to omit page numbering. +.TP +\f[CR]columns\f[R] +Number of columns for body text. +.SS Variables for ms +.TP +\f[CR]fontfamily\f[R] +\f[CR]A\f[R] (Avant Garde), \f[CR]B\f[R] (Bookman), \f[CR]C\f[R] +(Helvetica), \f[CR]HN\f[R] (Helvetica Narrow), \f[CR]P\f[R] (Palatino), +or \f[CR]T\f[R] (Times New Roman). +This setting does not affect source code, which is always displayed +using monospace Courier. +These built\-in fonts are limited in their coverage of characters. +Additional fonts may be installed using the script +\f[CR]install\-font.sh\f[R] provided by Peter Schaffter and documented +in detail on his web site. +.TP +\f[CR]indent\f[R] +paragraph indent (e.g.\ \f[CR]2m\f[R]) +.TP +\f[CR]lineheight\f[R] +line height (e.g.\ \f[CR]12p\f[R]) +.TP +\f[CR]pointsize\f[R] +point size (e.g.\ \f[CR]10p\f[R]) +.SS Variables set automatically +Pandoc sets these variables automatically in response to [options] or +document contents; users can also modify them. +These vary depending on the output format, and include the following: +.TP +\f[CR]body\f[R] +body of document +.TP +\f[CR]date\-meta\f[R] +the \f[CR]date\f[R] variable converted to ISO 8601 YYYY\-MM\-DD, +included in all HTML based formats (dzslides, epub, html, html4, html5, +revealjs, s5, slideous, slidy). +The recognized formats for \f[CR]date\f[R] are: \f[CR]mm/dd/yyyy\f[R], +\f[CR]mm/dd/yy\f[R], \f[CR]yyyy\-mm\-dd\f[R] (ISO 8601), +\f[CR]dd MM yyyy\f[R] (e.g.\ either \f[CR]02 Apr 2018\f[R] or +\f[CR]02 April 2018\f[R]), \f[CR]MM dd, yyyy\f[R] +(e.g.\ \f[CR]Apr. 02, 2018\f[R] or +\f[CR]April 02, 2018),\f[R]yyyy[mm[dd]]\f[CR](e.g.\f[R]20180402, +\f[CR]201804\f[R] or \f[CR]2018\f[R]). +.TP +\f[CR]header\-includes\f[R] +contents specified by \f[CR]\-H/\-\-include\-in\-header\f[R] (may have +multiple values) +.TP +\f[CR]include\-before\f[R] +contents specified by \f[CR]\-B/\-\-include\-before\-body\f[R] (may have +multiple values) +.TP +\f[CR]include\-after\f[R] +contents specified by \f[CR]\-A/\-\-include\-after\-body\f[R] (may have +multiple values) +.TP +\f[CR]meta\-json\f[R] +JSON representation of all of the document\[cq]s metadata. +Field values are transformed to the selected output format. +.TP +\f[CR]numbersections\f[R] +non\-null value if \f[CR]\-N/\-\-number\-sections\f[R] was specified +.TP +\f[CR]sourcefile\f[R], \f[CR]outputfile\f[R] +source and destination filenames, as given on the command line. +\f[CR]sourcefile\f[R] can also be a list if input comes from multiple +files, or empty if input is from stdin. +You can use the following snippet in your template to distinguish them: +.RS +.IP +.EX +$if(sourcefile)$ +$for(sourcefile)$ +$sourcefile$ +$endfor$ +$else$ +(stdin) +$endif$ +.EE +.PP +Similarly, \f[CR]outputfile\f[R] can be \f[CR]\-\f[R] if output goes to +the terminal. +.PP +If you need absolute paths, use e.g.\ \f[CR]$curdir$/$sourcefile$\f[R]. +.RE +.TP +\f[CR]curdir\f[R] +working directory from which pandoc is run. +.TP +\f[CR]pandoc\-version\f[R] +pandoc version. +.TP +\f[CR]toc\f[R] +non\-null value if \f[CR]\-\-toc/\-\-table\-of\-contents\f[R] was +specified +.TP +\f[CR]toc\-title\f[R] +title of table of contents (works only with EPUB, HTML, revealjs, +opendocument, odt, docx, pptx, beamer, LaTeX). +Note that in docx and pptx a custom \f[CR]toc\-title\f[R] will be picked +up from metadata, but cannot be set as a variable. diff --git a/pandoc-cli/man/pandoc.1 b/pandoc-cli/man/pandoc.1 index 3fa285023b16..a93128df84f2 100644 --- a/pandoc-cli/man/pandoc.1 +++ b/pandoc-cli/man/pandoc.1 @@ -59,7 +59,7 @@ pandoc \-s \-o output.html input.txt .EE .PP For more information on how standalone documents are produced, see -Templates below. +\fIpandoc-templates\fR(5). .PP If multiple input files are given, pandoc will concatenate them all (with blank lines between them) before parsing. @@ -136,8 +136,8 @@ The tool used to generate the PDF from the intermediate format may be specified using \f[CR]\-\-pdf\-engine\f[R]. .PP You can control the PDF style using variables, depending on the -intermediate format used: see variables for LaTeX, variables for -ConTeXt, variables for \f[CR]wkhtmltopdf\f[R], variables for ms. +intermediate format used: see [variables for LaTeX], [variables for +ConTeXt], [variables for \f[CR]wkhtmltopdf\f[R]], [variables for ms]. When HTML is used as an intermediate format, the output can be styled using \f[CR]\-\-css\f[R]. .PP @@ -773,7 +773,7 @@ included; otherwise, metadata is suppressed. \f[CR]\-\-template=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] Use the specified file as a custom template for the generated document. Implies \f[CR]\-\-standalone\f[R]. -See Templates, below, for a description of template syntax. +See \fIpandoc-templates\fR(5) for a description of template syntax. If no extension is specified, an extension corresponding to the writer will be added, so that \f[CR]\-\-template=special\f[R] looks for \f[CR]special.html\f[R] for HTML output. @@ -785,10 +785,13 @@ output format will be used (see \f[CR]\-D/\-\-print\-default\-template\f[R]). .TP \f[CR]\-V\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]\-\-variable=\f[R]\f[I]KEY\f[R][\f[CR]:\f[R]\f[I]VAL\f[R]] -Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when -rendering the document in standalone mode. +Set the template variable \f[I]KEY\f[R] to the string value +\f[I]VAL\f[R] when rendering the document in standalone mode. If no \f[I]VAL\f[R] is specified, the key will be given the value \f[CR]true\f[R]. +Structured values (lists, maps) cannot be assigned using this option, +but they can be assigned in the \f[CR]variables\f[R] section of a +defaults file. .TP \f[CR]\-\-sandbox[=true|false]\f[R] Run pandoc in a sandbox, limiting IO operations in readers and writers @@ -2155,1225 +2158,6 @@ field can be added to \f[CR]html\-math\-method:\f[R]. .EE .RE -.SH TEMPLATES -When the \f[CR]\-s/\-\-standalone\f[R] option is used, pandoc uses a -template to add header and footer material that is needed for a -self\-standing document. -To see the default template that is used, just type -.IP -.EX -pandoc \-D *FORMAT* -.EE -.PP -where \f[I]FORMAT\f[R] is the name of the output format. -A custom template can be specified using the \f[CR]\-\-template\f[R] -option. -You can also override the system default templates for a given output -format \f[I]FORMAT\f[R] by putting a file -\f[CR]templates/default.*FORMAT*\f[R] in the user data directory (see -\f[CR]\-\-data\-dir\f[R], above). -\f[I]Exceptions:\f[R] -.IP \[bu] 2 -For \f[CR]odt\f[R] output, customize the \f[CR]default.opendocument\f[R] -template. -.IP \[bu] 2 -For \f[CR]pdf\f[R] output, customize the \f[CR]default.latex\f[R] -template (or the \f[CR]default.context\f[R] template, if you use -\f[CR]\-t context\f[R], or the \f[CR]default.ms\f[R] template, if you -use \f[CR]\-t ms\f[R], or the \f[CR]default.html\f[R] template, if you -use \f[CR]\-t html\f[R]). -.IP \[bu] 2 -\f[CR]docx\f[R] and \f[CR]pptx\f[R] have no template (however, you can -use \f[CR]\-\-reference\-doc\f[R] to customize the output). -.PP -Templates contain \f[I]variables\f[R], which allow for the inclusion of -arbitrary information at any point in the file. -They may be set at the command line using the -\f[CR]\-V/\-\-variable\f[R] option. -If a variable is not set, pandoc will look for the key in the -document\[cq]s metadata, which can be set using either YAML metadata -blocks or with the \f[CR]\-M/\-\-metadata\f[R] option. -In addition, some variables are given default values by pandoc. -See Variables below for a list of variables used in pandoc\[cq]s default -templates. -.PP -If you use custom templates, you may need to revise them as pandoc -changes. -We recommend tracking the changes in the default templates, and -modifying your custom templates accordingly. -An easy way to do this is to fork the pandoc\-templates repository and -merge in changes after each pandoc release. -.SS Template syntax -.SS Comments -Anything between the sequence \f[CR]$\-\-\f[R] and the end of the line -will be treated as a comment and omitted from the output. -.SS Delimiters -To mark variables and control structures in the template, either -\f[CR]$\f[R]\&...\f[CR]$\f[R] or \f[CR]${\f[R]\&...\f[CR]}\f[R] may be -used as delimiters. -The styles may also be mixed in the same template, but the opening and -closing delimiter must match in each case. -The opening delimiter may be followed by one or more spaces or tabs, -which will be ignored. -The closing delimiter may be preceded by one or more spaces or tabs, -which will be ignored. -.PP -To include a literal \f[CR]$\f[R] in the document, use \f[CR]$$\f[R]. -.SS Interpolated variables -A slot for an interpolated variable is a variable name surrounded by -matched delimiters. -Variable names must begin with a letter and can contain letters, -numbers, \f[CR]_\f[R], \f[CR]\-\f[R], and \f[CR].\f[R]. -The keywords \f[CR]it\f[R], \f[CR]if\f[R], \f[CR]else\f[R], -\f[CR]endif\f[R], \f[CR]for\f[R], \f[CR]sep\f[R], and \f[CR]endfor\f[R] -may not be used as variable names. -Examples: -.IP -.EX -$foo$ -$foo.bar.baz$ -$foo_bar.baz\-bim$ -$ foo $ -${foo} -${foo.bar.baz} -${foo_bar.baz\-bim} -${ foo } -.EE -.PP -Variable names with periods are used to get at structured variable -values. -So, for example, \f[CR]employee.salary\f[R] will return the value of the -\f[CR]salary\f[R] field of the object that is the value of the -\f[CR]employee\f[R] field. -.IP \[bu] 2 -If the value of the variable is a simple value, it will be rendered -verbatim. -(Note that no escaping is done; the assumption is that the calling -program will escape the strings appropriately for the output format.) -.IP \[bu] 2 -If the value is a list, the values will be concatenated. -.IP \[bu] 2 -If the value is a map, the string \f[CR]true\f[R] will be rendered. -.IP \[bu] 2 -Every other value will be rendered as the empty string. -.SS Conditionals -A conditional begins with \f[CR]if(variable)\f[R] (enclosed in matched -delimiters) and ends with \f[CR]endif\f[R] (enclosed in matched -delimiters). -It may optionally contain an \f[CR]else\f[R] (enclosed in matched -delimiters). -The \f[CR]if\f[R] section is used if \f[CR]variable\f[R] has a true -value, otherwise the \f[CR]else\f[R] section is used (if present). -The following values count as true: -.IP \[bu] 2 -any map -.IP \[bu] 2 -any array containing at least one true value -.IP \[bu] 2 -any nonempty string -.IP \[bu] 2 -boolean True -.PP -Note that in YAML metadata (and metadata specified on the command line -using \f[CR]\-M/\-\-metadata\f[R]), unquoted \f[CR]true\f[R] and -\f[CR]false\f[R] will be interpreted as Boolean values. -But a variable specified on the command line using -\f[CR]\-V/\-\-variable\f[R] will always be given a string value. -Hence a conditional \f[CR]if(foo)\f[R] will be triggered if you use -\f[CR]\-V foo=false\f[R], but not if you use \f[CR]\-M foo=false\f[R]. -.PP -Examples: -.IP -.EX -$if(foo)$bar$endif$ - -$if(foo)$ - $foo$ -$endif$ - -$if(foo)$ -part one -$else$ -part two -$endif$ - -${if(foo)}bar${endif} - -${if(foo)} - ${foo} -${endif} - -${if(foo)} -${ foo.bar } -${else} -no foo! -${endif} -.EE -.PP -The keyword \f[CR]elseif\f[R] may be used to simplify complex nested -conditionals: -.IP -.EX -$if(foo)$ -XXX -$elseif(bar)$ -YYY -$else$ -ZZZ -$endif$ -.EE -.SS For loops -A for loop begins with \f[CR]for(variable)\f[R] (enclosed in matched -delimiters) and ends with \f[CR]endfor\f[R] (enclosed in matched -delimiters). -.IP \[bu] 2 -If \f[CR]variable\f[R] is an array, the material inside the loop will be -evaluated repeatedly, with \f[CR]variable\f[R] being set to each value -of the array in turn, and concatenated. -.IP \[bu] 2 -If \f[CR]variable\f[R] is a map, the material inside will be set to the -map. -.IP \[bu] 2 -If the value of the associated variable is not an array or a map, a -single iteration will be performed on its value. -.PP -Examples: -.IP -.EX -$for(foo)$$foo$$sep$, $endfor$ - -$for(foo)$ - \- $foo.last$, $foo.first$ -$endfor$ - -${ for(foo.bar) } - \- ${ foo.bar.last }, ${ foo.bar.first } -${ endfor } - -$for(mymap)$ -$it.name$: $it.office$ -$endfor$ -.EE -.PP -You may optionally specify a separator between consecutive values using -\f[CR]sep\f[R] (enclosed in matched delimiters). -The material between \f[CR]sep\f[R] and the \f[CR]endfor\f[R] is the -separator. -.IP -.EX -${ for(foo) }${ foo }${ sep }, ${ endfor } -.EE -.PP -Instead of using \f[CR]variable\f[R] inside the loop, the special -anaphoric keyword \f[CR]it\f[R] may be used. -.IP -.EX -${ for(foo.bar) } - \- ${ it.last }, ${ it.first } -${ endfor } -.EE -.SS Partials -Partials (subtemplates stored in different files) may be included by -using the name of the partial, followed by \f[CR]()\f[R], for example: -.IP -.EX -${ styles() } -.EE -.PP -Partials will be sought in the directory containing the main template. -The file name will be assumed to have the same extension as the main -template if it lacks an extension. -When calling the partial, the full name including file extension can -also be used: -.IP -.EX -${ styles.html() } -.EE -.PP -(If a partial is not found in the directory of the template and the -template path is given as a relative path, it will also be sought in the -\f[CR]templates\f[R] subdirectory of the user data directory.) -.PP -Partials may optionally be applied to variables using a colon: -.IP -.EX -${ date:fancy() } - -${ articles:bibentry() } -.EE -.PP -If \f[CR]articles\f[R] is an array, this will iterate over its values, -applying the partial \f[CR]bibentry()\f[R] to each one. -So the second example above is equivalent to -.IP -.EX -${ for(articles) } -${ it:bibentry() } -${ endfor } -.EE -.PP -Note that the anaphoric keyword \f[CR]it\f[R] must be used when -iterating over partials. -In the above examples, the \f[CR]bibentry\f[R] partial should contain -\f[CR]it.title\f[R] (and so on) instead of \f[CR]articles.title\f[R]. -.PP -Final newlines are omitted from included partials. -.PP -Partials may include other partials. -.PP -A separator between values of an array may be specified in square -brackets, immediately after the variable name or partial: -.IP -.EX -${months[, ]}$ - -${articles:bibentry()[; ]$ -.EE -.PP -The separator in this case is literal and (unlike with \f[CR]sep\f[R] in -an explicit \f[CR]for\f[R] loop) cannot contain interpolated variables -or other template directives. -.SS Nesting -To ensure that content is \[lq]nested,\[rq] that is, subsequent lines -indented, use the \f[CR]\[ha]\f[R] directive: -.IP -.EX -$item.number$ $\[ha]$$item.description$ ($item.price$) -.EE -.PP -In this example, if \f[CR]item.description\f[R] has multiple lines, they -will all be indented to line up with the first line: -.IP -.EX -00123 A fine bottle of 18\-year old - Oban whiskey. ($148) -.EE -.PP -To nest multiple lines to the same level, align them with the -\f[CR]\[ha]\f[R] directive in the template. -For example: -.IP -.EX -$item.number$ $\[ha]$$item.description$ ($item.price$) - (Available til $item.sellby$.) -.EE -.PP -will produce -.IP -.EX -00123 A fine bottle of 18\-year old - Oban whiskey. ($148) - (Available til March 30, 2020.) -.EE -.PP -If a variable occurs by itself on a line, preceded by whitespace and not -followed by further text or directives on the same line, and the -variable\[cq]s value contains multiple lines, it will be nested -automatically. -.SS Breakable spaces -Normally, spaces in the template itself (as opposed to values of the -interpolated variables) are not breakable, but they can be made -breakable in part of the template by using the \f[CR]\[ti]\f[R] keyword -(ended with another \f[CR]\[ti]\f[R]). -.IP -.EX -$\[ti]$This long line may break if the document is rendered -with a short line length.$\[ti]$ -.EE -.SS Pipes -A pipe transforms the value of a variable or partial. -Pipes are specified using a slash (\f[CR]/\f[R]) between the variable -name (or partial) and the pipe name. -Example: -.IP -.EX -$for(name)$ -$name/uppercase$ -$endfor$ - -$for(metadata/pairs)$ -\- $it.key$: $it.value$ -$endfor$ - -$employee:name()/uppercase$ -.EE -.PP -Pipes may be chained: -.IP -.EX -$for(employees/pairs)$ -$it.key/alpha/uppercase$. $it.name$ -$endfor$ -.EE -.PP -Some pipes take parameters: -.IP -.EX -|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| -$for(employee)$ -$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$ -$endfor$ -|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| -.EE -.PP -Currently the following pipes are predefined: -.IP \[bu] 2 -\f[CR]pairs\f[R]: Converts a map or array to an array of maps, each with -\f[CR]key\f[R] and \f[CR]value\f[R] fields. -If the original value was an array, the \f[CR]key\f[R] will be the array -index, starting with 1. -.IP \[bu] 2 -\f[CR]uppercase\f[R]: Converts text to uppercase. -.IP \[bu] 2 -\f[CR]lowercase\f[R]: Converts text to lowercase. -.IP \[bu] 2 -\f[CR]length\f[R]: Returns the length of the value: number of characters -for a textual value, number of elements for a map or array. -.IP \[bu] 2 -\f[CR]reverse\f[R]: Reverses a textual value or array, and has no effect -on other values. -.IP \[bu] 2 -\f[CR]first\f[R]: Returns the first value of an array, if applied to a -non\-empty array; otherwise returns the original value. -.IP \[bu] 2 -\f[CR]last\f[R]: Returns the last value of an array, if applied to a -non\-empty array; otherwise returns the original value. -.IP \[bu] 2 -\f[CR]rest\f[R]: Returns all but the first value of an array, if applied -to a non\-empty array; otherwise returns the original value. -.IP \[bu] 2 -\f[CR]allbutlast\f[R]: Returns all but the last value of an array, if -applied to a non\-empty array; otherwise returns the original value. -.IP \[bu] 2 -\f[CR]chomp\f[R]: Removes trailing newlines (and breakable space). -.IP \[bu] 2 -\f[CR]nowrap\f[R]: Disables line wrapping on breakable spaces. -.IP \[bu] 2 -\f[CR]alpha\f[R]: Converts textual values that can be read as an integer -into lowercase alphabetic characters \f[CR]a..z\f[R] (mod 26). -This can be used to get lettered enumeration from array indices. -To get uppercase letters, chain with \f[CR]uppercase\f[R]. -.IP \[bu] 2 -\f[CR]roman\f[R]: Converts textual values that can be read as an integer -into lowercase roman numerals. -This can be used to get lettered enumeration from array indices. -To get uppercase roman, chain with \f[CR]uppercase\f[R]. -.IP \[bu] 2 -\f[CR]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a -textual value in a block of width \f[CR]n\f[R], aligned to the left, -with an optional left and right border. -Has no effect on other values. -This can be used to align material in tables. -Widths are positive integers indicating the number of characters. -Borders are strings inside double quotes; literal \f[CR]\[dq]\f[R] and -\f[CR]\[rs]\f[R] characters must be backslash\-escaped. -.IP \[bu] 2 -\f[CR]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a -textual value in a block of width \f[CR]n\f[R], aligned to the right, -and has no effect on other values. -.IP \[bu] 2 -\f[CR]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders -a textual value in a block of width \f[CR]n\f[R], aligned to the center, -and has no effect on other values. -.SS Variables -.SS Metadata variables -.TP -\f[CR]title\f[R], \f[CR]author\f[R], \f[CR]date\f[R] -allow identification of basic aspects of the document. -Included in PDF metadata through LaTeX and ConTeXt. -These can be set through a pandoc title block, which allows for multiple -authors, or through a YAML metadata block: -.RS -.IP -.EX -\-\-\- -author: -\- Aristotle -\- Peter Abelard -\&... -.EE -.PP -Note that if you just want to set PDF or HTML metadata, without -including a title block in the document itself, you can set the -\f[CR]title\-meta\f[R], \f[CR]author\-meta\f[R], and -\f[CR]date\-meta\f[R] variables. -(By default these are set automatically, based on \f[CR]title\f[R], -\f[CR]author\f[R], and \f[CR]date\f[R].) -The page title in HTML is set by \f[CR]pagetitle\f[R], which is equal to -\f[CR]title\f[R] by default. -.RE -.TP -\f[CR]subtitle\f[R] -document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx -documents -.TP -\f[CR]abstract\f[R] -document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc, and docx -documents -.TP -\f[CR]abstract\-title\f[R] -title of abstract, currently used only in HTML, EPUB, and docx. -This will be set automatically to a localized value, depending on -\f[CR]lang\f[R], but can be manually overridden. -.TP -\f[CR]keywords\f[R] -list of keywords to be included in HTML, PDF, ODT, pptx, docx and -AsciiDoc metadata; repeat as for \f[CR]author\f[R], above -.TP -\f[CR]subject\f[R] -document subject, included in ODT, PDF, docx, EPUB, and pptx metadata -.TP -\f[CR]description\f[R] -document description, included in ODT, docx and pptx metadata. -Some applications show this as \f[CR]Comments\f[R] metadata. -.TP -\f[CR]category\f[R] -document category, included in docx and pptx metadata -.PP -Additionally, any root\-level string metadata, not included in ODT, docx -or pptx metadata is added as a \f[I]custom property\f[R]. -The following YAML metadata block for instance: -.IP -.EX -\-\-\- -title: \[aq]This is the title\[aq] -subtitle: \[dq]This is the subtitle\[dq] -author: -\- Author One -\- Author Two -description: | - This is a long - description. - - It consists of two paragraphs -\&... -.EE -.PP -will include \f[CR]title\f[R], \f[CR]author\f[R] and -\f[CR]description\f[R] as standard document properties and -\f[CR]subtitle\f[R] as a custom property when converting to docx, ODT or -pptx. -.SS Language variables -.TP -\f[CR]lang\f[R] -identifies the main language of the document using IETF language tags -(following the BCP 47 standard), such as \f[CR]en\f[R] or -\f[CR]en\-GB\f[R]. -The Language subtag lookup tool can look up or verify these tags. -This affects most formats, and controls hyphenation in PDF output when -using LaTeX (through \f[CR]babel\f[R] and \f[CR]polyglossia\f[R]) or -ConTeXt. -.RS -.PP -Use native pandoc Divs and Spans with the \f[CR]lang\f[R] attribute to -switch the language: -.IP -.EX -\-\-\- -lang: en\-GB -\&... - -Text in the main document language (British English). - -::: {lang=fr\-CA} -> Cette citation est écrite en français canadien. -::: - -More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de} -.EE -.RE -.TP -\f[CR]dir\f[R] -the base script direction, either \f[CR]rtl\f[R] (right\-to\-left) or -\f[CR]ltr\f[R] (left\-to\-right). -.RS -.PP -For bidirectional documents, native pandoc \f[CR]span\f[R]s and -\f[CR]div\f[R]s with the \f[CR]dir\f[R] attribute (value \f[CR]rtl\f[R] -or \f[CR]ltr\f[R]) can be used to override the base direction in some -output formats. -This may not always be necessary if the final renderer (e.g.\ the -browser, when generating HTML) supports the Unicode Bidirectional -Algorithm. -.PP -When using LaTeX for bidirectional documents, only the -\f[CR]xelatex\f[R] engine is fully supported (use -\f[CR]\-\-pdf\-engine=xelatex\f[R]). -.RE -.SS Variables for HTML -.TP -\f[CR]document\-css\f[R] -Enables inclusion of most of the CSS in the \f[CR]styles.html\f[R] -partial (have a look with -\f[CR]pandoc \-\-print\-default\-data\-file=templates/styles.html\f[R]). -Unless you use \f[CR]\-\-css\f[R], this variable is set to -\f[CR]true\f[R] by default. -You can disable it with e.g.\ \f[CR]pandoc \-M document\-css=false\f[R]. -.TP -\f[CR]mainfont\f[R] -sets the CSS \f[CR]font\-family\f[R] property on the \f[CR]html\f[R] -element. -.TP -\f[CR]fontsize\f[R] -sets the base CSS \f[CR]font\-size\f[R], which you\[cq]d usually set to -e.g.\ \f[CR]20px\f[R], but it also accepts \f[CR]pt\f[R] (12pt = 16px in -most browsers). -.TP -\f[CR]fontcolor\f[R] -sets the CSS \f[CR]color\f[R] property on the \f[CR]html\f[R] element. -.TP -\f[CR]linkcolor\f[R] -sets the CSS \f[CR]color\f[R] property on all links. -.TP -\f[CR]monofont\f[R] -sets the CSS \f[CR]font\-family\f[R] property on \f[CR]code\f[R] -elements. -.TP -\f[CR]monobackgroundcolor\f[R] -sets the CSS \f[CR]background\-color\f[R] property on \f[CR]code\f[R] -elements and adds extra padding. -.TP -\f[CR]linestretch\f[R] -sets the CSS \f[CR]line\-height\f[R] property on the \f[CR]html\f[R] -element, which is preferred to be unitless. -.TP -\f[CR]maxwidth\f[R] -sets the CSS \f[CR]max\-width\f[R] property (default is 32em). -.TP -\f[CR]backgroundcolor\f[R] -sets the CSS \f[CR]background\-color\f[R] property on the -\f[CR]html\f[R] element. -.TP -\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] -sets the corresponding CSS \f[CR]padding\f[R] properties on the -\f[CR]body\f[R] element. -.PP -To override or extend some CSS for just one document, include for -example: -.IP -.EX -\-\-\- -header\-includes: | - -\-\-\- -.EE -.SS Variables for HTML math -.TP -\f[CR]classoption\f[R] -when using \f[CR]\-\-katex\f[R], you can render display math equations -flush left using YAML metadata or with \f[CR]\-M classoption=fleqn\f[R]. -.SS Variables for HTML slides -These affect HTML output when producing slide shows with pandoc. -.TP -\f[CR]institute\f[R] -author affiliations: can be a list when there are multiple authors -.TP -\f[CR]revealjs\-url\f[R] -base URL for reveal.js documents (defaults to -\f[CR]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R]) -.TP -\f[CR]s5\-url\f[R] -base URL for S5 documents (defaults to \f[CR]s5/default\f[R]) -.TP -\f[CR]slidy\-url\f[R] -base URL for Slidy documents (defaults to -\f[CR]https://www.w3.org/Talks/Tools/Slidy2\f[R]) -.TP -\f[CR]slideous\-url\f[R] -base URL for Slideous documents (defaults to \f[CR]slideous\f[R]) -.TP -\f[CR]title\-slide\-attributes\f[R] -additional attributes for the title slide of reveal.js slide shows. -See background in reveal.js, beamer, and pptx for an example. -.PP -All reveal.js configuration options are available as variables. -To turn off boolean flags that default to true in reveal.js, use -\f[CR]0\f[R]. -.SS Variables for Beamer slides -These variables change the appearance of PDF slides using -\f[CR]beamer\f[R]. -.TP -\f[CR]aspectratio\f[R] -slide aspect ratio (\f[CR]43\f[R] for 4:3 [default], \f[CR]169\f[R] for -16:9, \f[CR]1610\f[R] for 16:10, \f[CR]149\f[R] for 14:9, \f[CR]141\f[R] -for 1.41:1, \f[CR]54\f[R] for 5:4, \f[CR]32\f[R] for 3:2) -.TP -\f[CR]beameroption\f[R] -add extra beamer option with \f[CR]\[rs]setbeameroption{}\f[R] -.TP -\f[CR]institute\f[R] -author affiliations: can be a list when there are multiple authors -.TP -\f[CR]logo\f[R] -logo image for slides -.TP -\f[CR]navigation\f[R] -controls navigation symbols (default is \f[CR]empty\f[R] for no -navigation symbols; other valid values are \f[CR]frame\f[R], -\f[CR]vertical\f[R], and \f[CR]horizontal\f[R]) -.TP -\f[CR]section\-titles\f[R] -enables \[lq]title pages\[rq] for new sections (default is true) -.TP -\f[CR]theme\f[R], \f[CR]colortheme\f[R], \f[CR]fonttheme\f[R], \f[CR]innertheme\f[R], \f[CR]outertheme\f[R] -beamer themes -.TP -\f[CR]themeoptions\f[R], \f[CR]colorthemeoptions\f[R], \f[CR]fontthemeoptions\f[R], \f[CR]innerthemeoptions\f[R], \f[CR]outerthemeoptions\f[R] -options for LaTeX beamer themes (lists) -.TP -\f[CR]titlegraphic\f[R] -image for title slide: can be a list -.TP -\f[CR]titlegraphicoptions\f[R] -options for title slide image -.TP -\f[CR]shorttitle\f[R], \f[CR]shortsubtitle\f[R], \f[CR]shortauthor\f[R], \f[CR]shortinstitute\f[R], \f[CR]shortdate\f[R] -some beamer themes use short versions of the title, subtitle, author, -institute, date -.SS Variables for PowerPoint -These variables control the visual aspects of a slide show that are not -easily controlled via templates. -.TP -\f[CR]monofont\f[R] -font to use for code. -.SS Variables for LaTeX -Pandoc uses these variables when creating a PDF with a LaTeX engine. -.SS Layout -.TP -\f[CR]block\-headings\f[R] -make \f[CR]\[rs]paragraph\f[R] and \f[CR]\[rs]subparagraph\f[R] -(fourth\- and fifth\-level headings, or fifth\- and sixth\-level with -book classes) free\-standing rather than run\-in; requires further -formatting to distinguish from \f[CR]\[rs]subsubsection\f[R] (third\- or -fourth\-level headings). -Instead of using this option, KOMA\-Script can adjust headings more -extensively: -.RS -.IP -.EX -\-\-\- -documentclass: scrartcl -header\-includes: | - \[rs]RedeclareSectionCommand[ - beforeskip=\-10pt plus \-2pt minus \-1pt, - afterskip=1sp plus \-1sp minus 1sp, - font=\[rs]normalfont\[rs]itshape]{paragraph} - \[rs]RedeclareSectionCommand[ - beforeskip=\-10pt plus \-2pt minus \-1pt, - afterskip=1sp plus \-1sp minus 1sp, - font=\[rs]normalfont\[rs]scshape, - indent=0pt]{subparagraph} -\&... -.EE -.RE -.TP -\f[CR]classoption\f[R] -option for document class, e.g.\ \f[CR]oneside\f[R]; repeat for multiple -options: -.RS -.IP -.EX -\-\-\- -classoption: -\- twocolumn -\- landscape -\&... -.EE -.RE -.TP -\f[CR]documentclass\f[R] -document class: usually one of the standard classes, \f[CR]article\f[R], -\f[CR]book\f[R], and \f[CR]report\f[R]; the KOMA\-Script equivalents, -\f[CR]scrartcl\f[R], \f[CR]scrbook\f[R], and \f[CR]scrreprt\f[R], which -default to smaller margins; or \f[CR]memoir\f[R] -.TP -\f[CR]geometry\f[R] -option for \f[CR]geometry\f[R] package, e.g.\ \f[CR]margin=1in\f[R]; -repeat for multiple options: -.RS -.IP -.EX -\-\-\- -geometry: -\- top=30mm -\- left=20mm -\- heightrounded -\&... -.EE -.RE -.TP -\f[CR]hyperrefoptions\f[R] -option for \f[CR]hyperref\f[R] package, e.g.\ \f[CR]linktoc=all\f[R]; -repeat for multiple options: -.RS -.IP -.EX -\-\-\- -hyperrefoptions: -\- linktoc=all -\- pdfwindowui -\- pdfpagemode=FullScreen -\&... -.EE -.RE -.TP -\f[CR]indent\f[R] -if true, pandoc will use document class settings for indentation (the -default LaTeX template otherwise removes indentation and adds space -between paragraphs) -.TP -\f[CR]linestretch\f[R] -adjusts line spacing using the \f[CR]setspace\f[R] package, -e.g.\ \f[CR]1.25\f[R], \f[CR]1.5\f[R] -.TP -\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] -sets margins if \f[CR]geometry\f[R] is not used (otherwise -\f[CR]geometry\f[R] overrides these) -.TP -\f[CR]pagestyle\f[R] -control \f[CR]\[rs]pagestyle{}\f[R]: the default article class supports -\f[CR]plain\f[R] (default), \f[CR]empty\f[R] (no running heads or page -numbers), and \f[CR]headings\f[R] (section titles in running heads) -.TP -\f[CR]papersize\f[R] -paper size, e.g.\ \f[CR]letter\f[R], \f[CR]a4\f[R] -.TP -\f[CR]secnumdepth\f[R] -numbering depth for sections (with \f[CR]\-\-number\-sections\f[R] -option or \f[CR]numbersections\f[R] variable) -.TP -\f[CR]beamerarticle\f[R] -produce an article from Beamer slides. -Note: if you set this variable, you must specify the beamer writer but -use the default \f[I]LaTeX\f[R] template: for example, -\f[CR]pandoc \-Vbeamerarticle \-t beamer \-\-template default.latex\f[R]. -.TP -\f[CR]handout\f[R] -produce a handout version of Beamer slides (with overlays condensed into -single slides) -.SS Fonts -.TP -\f[CR]fontenc\f[R] -allows font encoding to be specified through \f[CR]fontenc\f[R] package -(with \f[CR]pdflatex\f[R]); default is \f[CR]T1\f[R] (see LaTeX font -encodings guide) -.TP -\f[CR]fontfamily\f[R] -font package for use with \f[CR]pdflatex\f[R]: TeX Live includes many -options, documented in the LaTeX Font Catalogue. -The default is Latin Modern. -.TP -\f[CR]fontfamilyoptions\f[R] -options for package used as \f[CR]fontfamily\f[R]; repeat for multiple -options. -For example, to use the Libertine font with proportional lowercase -(old\-style) figures through the \f[CR]libertinus\f[R] package: -.RS -.IP -.EX -\-\-\- -fontfamily: libertinus -fontfamilyoptions: -\- osf -\- p -\&... -.EE -.RE -.TP -\f[CR]fontsize\f[R] -font size for body text. -The standard classes allow 10pt, 11pt, and 12pt. -To use another size, set \f[CR]documentclass\f[R] to one of the -KOMA\-Script classes, such as \f[CR]scrartcl\f[R] or \f[CR]scrbook\f[R]. -.TP -\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R], \f[CR]CJKsansfont\f[R], \f[CR]CJKmonofont\f[R] -font families for use with \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R]: -take the name of any system font, using the \f[CR]fontspec\f[R] package. -\f[CR]CJKmainfont\f[R] uses the \f[CR]xecjk\f[R] package if -\f[CR]xelatex\f[R] is used, or the \f[CR]luatexja\f[R] package if -\f[CR]lualatex\f[R] is used. -.TP -\f[CR]mainfontoptions\f[R], \f[CR]sansfontoptions\f[R], \f[CR]monofontoptions\f[R], \f[CR]mathfontoptions\f[R], \f[CR]CJKoptions\f[R], \f[CR]luatexjapresetoptions\f[R] -options to use with \f[CR]mainfont\f[R], \f[CR]sansfont\f[R], -\f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R] in -\f[CR]xelatex\f[R] and \f[CR]lualatex\f[R]. -Allow for any choices available through \f[CR]fontspec\f[R]; repeat for -multiple options. -For example, to use the TeX Gyre version of Palatino with lowercase -figures: -.RS -.IP -.EX -\-\-\- -mainfont: TeX Gyre Pagella -mainfontoptions: -\- Numbers=Lowercase -\- Numbers=Proportional -\&... -.EE -.RE -.TP -\f[CR]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] -fonts to try if a glyph isn\[cq]t found in \f[CR]mainfont\f[R], -\f[CR]sansfont\f[R], or \f[CR]monofont\f[R] respectively. -These are lists. -The font name must be followed by a colon and optionally a set of -options, for example: -.RS -.IP -.EX -\-\-\- -mainfontfallback: - \- \[dq]FreeSans:\[dq] - \- \[dq]NotoColorEmoji:mode=harf\[dq] -\&... -.EE -.PP -Font fallbacks currently only work with \f[CR]lualatex\f[R]. -.RE -.TP -\f[CR]babelfonts\f[R] -a map of Babel language names (e.g.\ \f[CR]chinese\f[R]) to the font to -be used with the language: -.RS -.IP -.EX -\-\-\- -babelfonts: - chinese\-hant: \[dq]Noto Serif CJK TC\[dq] - russian: \[dq]Noto Serif\[dq] -\&... -.EE -.RE -.TP -\f[CR]microtypeoptions\f[R] -options to pass to the microtype package -.SS Links -.TP -\f[CR]colorlinks\f[R] -add color to link text; automatically enabled if any of -\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], -\f[CR]urlcolor\f[R], or \f[CR]toccolor\f[R] are set -.TP -\f[CR]boxlinks\f[R] -add visible box around links (has no effect if \f[CR]colorlinks\f[R] is -set) -.TP -\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], \f[CR]urlcolor\f[R], \f[CR]toccolor\f[R] -color for internal links, external links, citation links, linked URLs, -and links in table of contents, respectively: uses options allowed by -\f[CR]xcolor\f[R], including the \f[CR]dvipsnames\f[R], -\f[CR]svgnames\f[R], and \f[CR]x11names\f[R] lists -.TP -\f[CR]links\-as\-notes\f[R] -causes links to be printed as footnotes -.TP -\f[CR]urlstyle\f[R] -style for URLs (e.g., \f[CR]tt\f[R], \f[CR]rm\f[R], \f[CR]sf\f[R], and, -the default, \f[CR]same\f[R]) -.SS Front matter -.TP -\f[CR]lof\f[R], \f[CR]lot\f[R] -include list of figures, list of tables (can also be set using -\f[CR]\-\-lof/\-\-list\-of\-figures\f[R], -\f[CR]\-\-lot/\-\-list\-of\-tables\f[R]) -.TP -\f[CR]thanks\f[R] -contents of acknowledgments footnote after document title -.TP -\f[CR]toc\f[R] -include table of contents (can also be set using -\f[CR]\-\-toc/\-\-table\-of\-contents\f[R]) -.TP -\f[CR]toc\-depth\f[R] -level of section to include in table of contents -.SS BibLaTeX Bibliographies -These variables function when using BibLaTeX for citation rendering. -.TP -\f[CR]biblatexoptions\f[R] -list of options for biblatex -.TP -\f[CR]biblio\-style\f[R] -bibliography style, when used with \f[CR]\-\-natbib\f[R] and -\f[CR]\-\-biblatex\f[R] -.TP -\f[CR]biblio\-title\f[R] -bibliography title, when used with \f[CR]\-\-natbib\f[R] and -\f[CR]\-\-biblatex\f[R] -.TP -\f[CR]bibliography\f[R] -bibliography to use for resolving references -.TP -\f[CR]natbiboptions\f[R] -list of options for natbib -.SS Variables for ConTeXt -Pandoc uses these variables when creating a PDF with ConTeXt. -.TP -\f[CR]fontsize\f[R] -font size for body text (e.g.\ \f[CR]10pt\f[R], \f[CR]12pt\f[R]) -.TP -\f[CR]headertext\f[R], \f[CR]footertext\f[R] -text to be placed in running header or footer (see ConTeXt Headers and -Footers); repeat up to four times for different placement -.TP -\f[CR]indenting\f[R] -controls indentation of paragraphs, e.g.\ \f[CR]yes,small,next\f[R] (see -ConTeXt Indentation); repeat for multiple options -.TP -\f[CR]interlinespace\f[R] -adjusts line spacing, e.g.\ \f[CR]4ex\f[R] (using -\f[CR]setupinterlinespace\f[R]); repeat for multiple options -.TP -\f[CR]layout\f[R] -options for page margins and text arrangement (see ConTeXt Layout); -repeat for multiple options -.TP -\f[CR]linkcolor\f[R], \f[CR]contrastcolor\f[R] -color for links outside and inside a page, e.g.\ \f[CR]red\f[R], -\f[CR]blue\f[R] (see ConTeXt Color) -.TP -\f[CR]linkstyle\f[R] -typeface style for links, e.g.\ \f[CR]normal\f[R], \f[CR]bold\f[R], -\f[CR]slanted\f[R], \f[CR]boldslanted\f[R], \f[CR]type\f[R], -\f[CR]cap\f[R], \f[CR]small\f[R] -.TP -\f[CR]lof\f[R], \f[CR]lot\f[R] -include list of figures, list of tables -.TP -\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R] -font families: take the name of any system font (see ConTeXt Font -Switching) -.TP -\f[CR]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] -list of fonts to try, in order, if a glyph is not found in the main -font. -Use \f[CR]\[rs]definefallbackfamily\f[R]\-compatible font name syntax. -Emoji fonts are unsupported. -.TP -\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] -sets margins, if \f[CR]layout\f[R] is not used (otherwise -\f[CR]layout\f[R] overrides these) -.TP -\f[CR]pagenumbering\f[R] -page number style and location (using \f[CR]setuppagenumbering\f[R]); -repeat for multiple options -.TP -\f[CR]papersize\f[R] -paper size, e.g.\ \f[CR]letter\f[R], \f[CR]A4\f[R], \f[CR]landscape\f[R] -(see ConTeXt Paper Setup); repeat for multiple options -.TP -\f[CR]pdfa\f[R] -adds to the preamble the setup necessary to generate PDF/A of the type -specified, e.g.\ \f[CR]1a:2005\f[R], \f[CR]2a\f[R]. -If no type is specified (i.e.\ the value is set to True, by e.g. -\f[CR]\-\-metadata=pdfa\f[R] or \f[CR]pdfa: true\f[R] in a YAML metadata -block), \f[CR]1b:2005\f[R] will be used as default, for reasons of -backwards compatibility. -Using \f[CR]\-\-variable=pdfa\f[R] without specified value is not -supported. -To successfully generate PDF/A the required ICC color profiles have to -be available and the content and all included files (such as images) -have to be standard\-conforming. -The ICC profiles and output intent may be specified using the variables -\f[CR]pdfaiccprofile\f[R] and \f[CR]pdfaintent\f[R]. -See also ConTeXt PDFA for more details. -.TP -\f[CR]pdfaiccprofile\f[R] -when used in conjunction with \f[CR]pdfa\f[R], specifies the ICC profile -to use in the PDF, e.g.\ \f[CR]default.cmyk\f[R]. -If left unspecified, \f[CR]sRGB.icc\f[R] is used as default. -May be repeated to include multiple profiles. -Note that the profiles have to be available on the system. -They can be obtained from ConTeXt ICC Profiles. -.TP -\f[CR]pdfaintent\f[R] -when used in conjunction with \f[CR]pdfa\f[R], specifies the output -intent for the colors, -e.g.\ \f[CR]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If -left unspecified, \f[CR]sRGB IEC61966\-2.1\f[R] is used as default. -.TP -\f[CR]toc\f[R] -include table of contents (can also be set using -\f[CR]\-\-toc/\-\-table\-of\-contents\f[R]) -.TP -\f[CR]urlstyle\f[R] -typeface style for links without link text, e.g.\ \f[CR]normal\f[R], -\f[CR]bold\f[R], \f[CR]slanted\f[R], \f[CR]boldslanted\f[R], -\f[CR]type\f[R], \f[CR]cap\f[R], \f[CR]small\f[R] -.TP -\f[CR]whitespace\f[R] -spacing between paragraphs, e.g.\ \f[CR]none\f[R], \f[CR]small\f[R] -(using \f[CR]setupwhitespace\f[R]) -.TP -\f[CR]includesource\f[R] -include all source documents as file attachments in the PDF file -.SS Variables for \f[CR]wkhtmltopdf\f[R] -Pandoc uses these variables when creating a PDF with -\f[CR]wkhtmltopdf\f[R]. -The \f[CR]\-\-css\f[R] option also affects the output. -.TP -\f[CR]footer\-html\f[R], \f[CR]header\-html\f[R] -add information to the header and footer -.TP -\f[CR]margin\-left\f[R], \f[CR]margin\-right\f[R], \f[CR]margin\-top\f[R], \f[CR]margin\-bottom\f[R] -set the page margins -.TP -\f[CR]papersize\f[R] -sets the PDF paper size -.SS Variables for man pages -.TP -\f[CR]adjusting\f[R] -adjusts text to left (\f[CR]l\f[R]), right (\f[CR]r\f[R]), center -(\f[CR]c\f[R]), or both (\f[CR]b\f[R]) margins -.TP -\f[CR]footer\f[R] -footer in man pages -.TP -\f[CR]header\f[R] -header in man pages -.TP -\f[CR]section\f[R] -section number in man pages -.SS Variables for Texinfo -.TP -\f[CR]version\f[R] -version of software (used in title and title page) -.TP -\f[CR]filename\f[R] -name of info file to be generated (defaults to a name based on the texi -filename) -.SS Variables for Typst -.TP -\f[CR]margin\f[R] -A dictionary with the fields defined in the Typst documentation: -\f[CR]x\f[R], \f[CR]y\f[R], \f[CR]top\f[R], \f[CR]bottom\f[R], -\f[CR]left\f[R], \f[CR]right\f[R]. -.TP -\f[CR]papersize\f[R] -Paper size: \f[CR]a4\f[R], \f[CR]us\-letter\f[R], etc. -.TP -\f[CR]mainfont\f[R] -Name of system font to use for the main font. -.TP -\f[CR]fontsize\f[R] -Font size (e.g., \f[CR]12pt\f[R]). -.TP -\f[CR]section\-numbering\f[R] -Schema to use for numbering sections, e.g.\ \f[CR]1.A.1\f[R]. -.TP -\f[CR]columns\f[R] -Number of columns for body text. -.SS Variables for ms -.TP -\f[CR]fontfamily\f[R] -\f[CR]A\f[R] (Avant Garde), \f[CR]B\f[R] (Bookman), \f[CR]C\f[R] -(Helvetica), \f[CR]HN\f[R] (Helvetica Narrow), \f[CR]P\f[R] (Palatino), -or \f[CR]T\f[R] (Times New Roman). -This setting does not affect source code, which is always displayed -using monospace Courier. -These built\-in fonts are limited in their coverage of characters. -Additional fonts may be installed using the script -\f[CR]install\-font.sh\f[R] provided by Peter Schaffter and documented -in detail on his web site. -.TP -\f[CR]indent\f[R] -paragraph indent (e.g.\ \f[CR]2m\f[R]) -.TP -\f[CR]lineheight\f[R] -line height (e.g.\ \f[CR]12p\f[R]) -.TP -\f[CR]pointsize\f[R] -point size (e.g.\ \f[CR]10p\f[R]) -.SS Variables set automatically -Pandoc sets these variables automatically in response to options or -document contents; users can also modify them. -These vary depending on the output format, and include the following: -.TP -\f[CR]body\f[R] -body of document -.TP -\f[CR]date\-meta\f[R] -the \f[CR]date\f[R] variable converted to ISO 8601 YYYY\-MM\-DD, -included in all HTML based formats (dzslides, epub, html, html4, html5, -revealjs, s5, slideous, slidy). -The recognized formats for \f[CR]date\f[R] are: \f[CR]mm/dd/yyyy\f[R], -\f[CR]mm/dd/yy\f[R], \f[CR]yyyy\-mm\-dd\f[R] (ISO 8601), -\f[CR]dd MM yyyy\f[R] (e.g.\ either \f[CR]02 Apr 2018\f[R] or -\f[CR]02 April 2018\f[R]), \f[CR]MM dd, yyyy\f[R] -(e.g.\ \f[CR]Apr. 02, 2018\f[R] or -\f[CR]April 02, 2018),\f[R]yyyy[mm[dd]]\f[CR](e.g.\f[R]20180402, -\f[CR]201804\f[R] or \f[CR]2018\f[R]). -.TP -\f[CR]header\-includes\f[R] -contents specified by \f[CR]\-H/\-\-include\-in\-header\f[R] (may have -multiple values) -.TP -\f[CR]include\-before\f[R] -contents specified by \f[CR]\-B/\-\-include\-before\-body\f[R] (may have -multiple values) -.TP -\f[CR]include\-after\f[R] -contents specified by \f[CR]\-A/\-\-include\-after\-body\f[R] (may have -multiple values) -.TP -\f[CR]meta\-json\f[R] -JSON representation of all of the document\[cq]s metadata. -Field values are transformed to the selected output format. -.TP -\f[CR]numbersections\f[R] -non\-null value if \f[CR]\-N/\-\-number\-sections\f[R] was specified -.TP -\f[CR]sourcefile\f[R], \f[CR]outputfile\f[R] -source and destination filenames, as given on the command line. -\f[CR]sourcefile\f[R] can also be a list if input comes from multiple -files, or empty if input is from stdin. -You can use the following snippet in your template to distinguish them: -.RS -.IP -.EX -$if(sourcefile)$ -$for(sourcefile)$ -$sourcefile$ -$endfor$ -$else$ -(stdin) -$endif$ -.EE -.PP -Similarly, \f[CR]outputfile\f[R] can be \f[CR]\-\f[R] if output goes to -the terminal. -.PP -If you need absolute paths, use e.g.\ \f[CR]$curdir$/$sourcefile$\f[R]. -.RE -.TP -\f[CR]curdir\f[R] -working directory from which pandoc is run. -.TP -\f[CR]pandoc\-version\f[R] -pandoc version. -.TP -\f[CR]toc\f[R] -non\-null value if \f[CR]\-\-toc/\-\-table\-of\-contents\f[R] was -specified -.TP -\f[CR]toc\-title\f[R] -title of table of contents (works only with EPUB, HTML, revealjs, -opendocument, odt, docx, pptx, beamer, LaTeX). -Note that in docx and pptx a custom \f[CR]toc\-title\f[R] will be picked -up from metadata, but cannot be set as a variable. .SH EXTENSIONS The behavior of some of the readers and writers can be adjusted by enabling or disabling various extensions. @@ -6727,7 +5511,7 @@ CSS files, which are assumed to be available at the relative path \f[CR]w3.org\f[R] (for Slidy). (These paths can be changed by setting the \f[CR]slidy\-url\f[R], \f[CR]slideous\-url\f[R], \f[CR]revealjs\-url\f[R], or -\f[CR]s5\-url\f[R] variables; see Variables for HTML slides, above.) +\f[CR]s5\-url\f[R] variables; see [Variables for HTML slides], above.) For DZSlides, the (relatively short) JavaScript and CSS are included in the file by default. .PP @@ -6922,7 +5706,7 @@ directory. For dzslides, the CSS is included in the HTML file itself, and may be modified there. .PP -All reveal.js configuration options can be set through variables. +All [reveal.js configuration options] can be set through variables. For example, themes can be used by setting the \f[CR]theme\f[R] variable: .IP @@ -7136,7 +5920,7 @@ Slide 2 has a special image for its background, even though the heading has no c EPUB metadata may be specified using the \f[CR]\-\-epub\-metadata\f[R] option, but if the source document is Markdown, it is better to use a YAML metadata block. -Here is an example: +Here is an example of a YAML metadata block with EPUB metadata: .IP .EX \-\-\- @@ -7195,7 +5979,7 @@ A string value in \f[CR]YYYY\-MM\-DD\f[R] format. Pandoc will attempt to convert other common date formats. .TP \f[CR]lang\f[R] (or legacy: \f[CR]language\f[R]) -A string value in BCP 47 format. +A string value in [BCP 47] format. Pandoc will default to the local language if nothing is specified. .TP \f[CR]subject\f[R] @@ -7385,7 +6169,7 @@ correct formatting of pandoc\[cq]s HTML output. .PP The \f[CR]document\-css\f[R] variable may be set if the more opinionated styling of pandoc\[cq]s default HTML templates is desired (and in that -case the variables defined in Variables for HTML may be used to +case the variables defined in [Variables for HTML] may be used to fine\-tune the style). .SH CHUNKED HTML \f[CR]pandoc \-t chunkedhtml\f[R] will produce a zip archive of linked @@ -7719,7 +6503,8 @@ If you want to use \f[CR]\-\-standalone\f[R] with a custom writer, you will need to specify a template manually using \f[CR]\-\-template\f[R] or add a new default template with the name \f[CR]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[CR]templates\f[R] -subdirectory of your user data directory (see Templates). +subdirectory of your user data directory (see +\fIpandoc-templates\fR(5)). .SH REPRODUCIBLE BUILDS Some of the document formats pandoc targets (such as EPUB, docx, and ODT) include build timestamps in the generated document. diff --git a/pandoc-cli/pandoc-cli.cabal b/pandoc-cli/pandoc-cli.cabal index f8b6ae48fd9a..1a3d43f110e3 100644 --- a/pandoc-cli/pandoc-cli.cabal +++ b/pandoc-cli/pandoc-cli.cabal @@ -19,6 +19,7 @@ extra-source-files: man/pandoc.1 man/pandoc-lua.1 man/pandoc-server.1 + man/pandoc-templates.5 source-repository head type: git location: git://github.com/jgm/pandoc.git