From 37d296727f2b5f643d1a6d031674ff8b42898ab2 Mon Sep 17 00:00:00 2001 From: Evan Silberman Date: Sat, 30 Nov 2024 18:00:58 -0800 Subject: [PATCH 1/5] Extract templates doc --- MANUAL.txt | 1205 --------------------------------------------- doc/templates.md | 1207 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1207 insertions(+), 1205 deletions(-) create mode 100644 doc/templates.md diff --git a/MANUAL.txt b/MANUAL.txt index cce71f26f8dc..4cd297eb9eb1 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -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 diff --git a/doc/templates.md b/doc/templates.md new file mode 100644 index 000000000000..3ffaa4915a3d --- /dev/null +++ b/doc/templates.md @@ -0,0 +1,1207 @@ +--- +title: Templates +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 From e31cf8b474351d392d9024f97c65fcb89d94af99 Mon Sep 17 00:00:00 2001 From: Evan Silberman Date: Sat, 30 Nov 2024 19:06:42 -0800 Subject: [PATCH 2/5] Link to standalone templates doc --- MANUAL.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index 4cd297eb9eb1..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 @@ -6266,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/ From 251e9ae78462c75103aba33abe8cb8b0d9c3acf3 Mon Sep 17 00:00:00 2001 From: Evan Silberman Date: Sat, 30 Nov 2024 19:15:50 -0800 Subject: [PATCH 3/5] Add machinery for making more man pages and use it on templates.md manfilter.lua learns how to turn a link to another document in docs/ into a manual page cross-reference. This is paralleled by a pandoc-website filter change for handling such links. a lightly customized template for turning arbitrary docs into manual pages is provided, which exploits the standard `subtitle` metadata for the NAME section of the manual This first stab at this work does the brutal minimum amount of work while still being somewhat extensible. The new Makefile rule that applies the new man template hardcodes section 5. The mapping of document titles to manpage names and sections used by the lua filter is hardcoded at the top. Cleverer ideas could reduce repetition, at the cost of having to read yaml frontmatter out of all the docs to support cross-references, or relying on exotic GNU Make tricks, or similar. --- Makefile | 12 +++++++++++- doc/templates.md | 1 + man/manfilter.lua | 12 +++++++++++- man/template.man | 28 ++++++++++++++++++++++++++++ 4 files changed, 51 insertions(+), 2 deletions(-) create mode 100644 man/template.man diff --git a/Makefile b/Makefile index e8742a0f10a4..2da85bd54a02 100644 --- a/Makefile +++ b/Makefile @@ -137,7 +137,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 +199,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 index 3ffaa4915a3d..01e1937fcfd0 100644 --- a/doc/templates.md +++ b/doc/templates.md @@ -1,5 +1,6 @@ --- title: Templates +subtitle: templates for standalone pandoc output author: John MacFarlane --- 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$ From b9e8b66292d8ddd746a35b575015fffcb73e865a Mon Sep 17 00:00:00 2001 From: Evan Silberman Date: Sat, 30 Nov 2024 19:24:42 -0800 Subject: [PATCH 4/5] Add pandoc-templates.5 Some unrelated changes picked up in pandoc.1 since that's usually a release task. --- Makefile | 1 + pandoc-cli/man/pandoc-templates.5 | 1242 ++++++++++++++++++++++++++++ pandoc-cli/man/pandoc.1 | 1247 +---------------------------- pandoc-cli/pandoc-cli.cabal | 1 + 4 files changed, 1260 insertions(+), 1231 deletions(-) create mode 100644 pandoc-cli/man/pandoc-templates.5 diff --git a/Makefile b/Makefile index 2da85bd54a02..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: 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 From 7a9c650defa8969b246424ab4b1eafcc342634f0 Mon Sep 17 00:00:00 2001 From: Evan Silberman Date: Sat, 30 Nov 2024 19:32:32 -0800 Subject: [PATCH 5/5] Add pandoc-templates.5 to linux/mac release tools UNTESTED --- linux/make_artifacts.sh | 11 +++++++---- macos/make_macos_release.sh | 2 ++ 2 files changed, 9 insertions(+), 4 deletions(-) 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