|
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
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 ).
docx and pptx have no template (however, you can use --reference-doc to customize the output).
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 or with the -M/--metadata option.
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, which allows for multiple authors, or through a 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 .)
subtitle
document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx documents
abstract
document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx documents
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 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 ).
Variables for HTML slides
These affect HTML output when [producing slide shows with pandoc]. All reveal.js configuration options are available as variables.
revealjs-url
base URL for reveal.js documents (defaults to reveal.js )
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 )
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)
beamerarticle
produce an article from Beamer slides
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
options for LaTeX beamer themes (a list).
titlegraphic
image for title slide
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
...
indent
uses 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)
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.
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
font families for use with xelatex or lualatex : take the name of any system font, using the fontspec package. CJKmainfont uses the xecjk package.
mainfontoptions , sansfontoptions , monofontoptions , mathfontoptions , CJKoptions
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
...
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
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
Front matter
lof , lot
include list of figures, 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
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)
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-1b:2005. 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 can be obtained from ConTeXt ICC Profiles. See also ConTeXt PDFA for more details.
toc
include table of contents (can also be set using --toc/--table-of-contents )
whitespace
spacing between paragraphs, e.g. none , small (using setupwhitespace )
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
hyphenate
if true (the default), hyphenation will be used
section
section number in man pages
Variables for ms
fontfamily
font family (e.g. T or P )
indent
paragraph indent (e.g. 2m )
lineheight
line height (e.g. 12p )
pointsize
point size (e.g. 10p )
Structural variables
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.
toc
non-null value if --toc/--table-of-contents was specified
toc-title
title of table of contents (works only with EPUB, opendocument, odt, docx, pptx, beamer, LaTeX)
Using variables in templates
Variable names are sequences of alphanumerics, - , and _ , starting with a letter. A variable name surrounded by $ signs will be replaced by its value. For example, the string $title$ in
<title>$title$</title>
will be replaced by the document title.
To write a literal $ in a template, use $$ .
Templates may contain conditionals. The syntax is as follows:
$if(variable)$
X
$else$
Y
$endif$
This will include X in the template if variable has a truthy value; otherwise it will include Y . Here a truthy value is any of the following:
- a string that is not entirely white space,
- a non-empty array where the first value is truthy,
- any number (including zero),
- any object,
- the boolean
true (to specify the boolean true value using YAML metadata or the --metadata flag, use true , True , or TRUE ; with the --variable flag, simply omit a value for the variable, e.g. --variable draft ).
X and Y are placeholders for any valid template text, and may include interpolated variables or other conditionals. The $else$ section may be omitted.
When variables can have multiple values (for example, author in a multi-author document), you can use the $for$ keyword:
$for(author)$
<meta name="author" content="$author$" />
$endfor$
You can optionally specify a separator to be used between consecutive items:
$for(author)$$author$$sep$, $endfor$
Note that the separator needs to be specified immediately before the $endfor keyword.
A dot can be used to select a field of a variable that takes an object as its value. So, for example:
$author.name$ ($author.affiliation$)
The value of a variable will be indented to the same level as the variable.
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.
Templates may contain comments: anything on a line after $-- will be treated as a comment and ignored.
|