mirror of
https://github.com/jgm/pandoc.git
synced 2026-09-21 15:05:47 +00:00
8437 lines
289 KiB
Groff
8437 lines
289 KiB
Groff
.\" Automatically generated by Pandoc 3.10.2
|
|
.\"
|
|
.TH "pandoc" "1" "2026\-08\-11" "pandoc 3.10.2" "Pandoc User\[cq]s Guide"
|
|
.SH NAME
|
|
pandoc - general markup converter
|
|
.SH SYNOPSIS
|
|
\f[CR]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input\-file\f[R]]\&...
|
|
.SH DESCRIPTION
|
|
Pandoc is a Haskell library for converting from one markup format to
|
|
another, and a command\-line tool that uses this library.
|
|
.PP
|
|
Pandoc can convert between numerous markup and word processing formats,
|
|
including, but not limited to, various flavors of Markdown, HTML, LaTeX
|
|
and Word docx.
|
|
For the full lists of input and output formats, see the
|
|
\f[CR]\-\-from\f[R] and \f[CR]\-\-to\f[R] options below.
|
|
Pandoc can also produce PDF output: see creating a PDF, below.
|
|
.PP
|
|
Pandoc\(cqs enhanced version of Markdown includes syntax for tables,
|
|
definition lists, metadata blocks, footnotes, citations, math, and much
|
|
more.
|
|
See below under Pandoc\(cqs Markdown.
|
|
.PP
|
|
Pandoc has a modular design: it consists of a set of readers, which
|
|
parse text in a given format and produce a native representation of the
|
|
document (an \f[I]abstract syntax tree\f[R] or AST), and a set of
|
|
writers, which convert this native representation into a target format.
|
|
Thus, adding an input or output format requires only adding a reader or
|
|
writer.
|
|
Users can also run custom pandoc filters to modify the intermediate AST.
|
|
.PP
|
|
Because pandoc\(cqs intermediate representation of a document is less
|
|
expressive than many of the formats it converts between, one should not
|
|
expect perfect conversions between every format and every other.
|
|
Pandoc attempts to preserve the structural elements of a document, but
|
|
not formatting details such as margin size.
|
|
And some document elements, such as complex tables, may not fit into
|
|
pandoc\(cqs simple document model.
|
|
While conversions from pandoc\(cqs Markdown to all formats aspire to be
|
|
perfect, conversions from formats more expressive than pandoc\(cqs
|
|
Markdown can be expected to be lossy.
|
|
.SS Using pandoc
|
|
If no \f[I]input\-files\f[R] are specified, input is read from
|
|
\f[I]stdin\f[R].
|
|
Output goes to \f[I]stdout\f[R] by default.
|
|
For output to a file, use the \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R]
|
|
option:
|
|
.IP
|
|
.EX
|
|
pandoc \-o output.html input.txt
|
|
.EE
|
|
.PP
|
|
By default, pandoc produces a document fragment.
|
|
To produce a standalone document (e.g.\ a valid HTML file including
|
|
\f[CR]<head>\f[R] and \f[CR]<body>\f[R]), use the \f[CR]\-s\f[R] or
|
|
\f[CR]\-\-standalone\f[R] flag:
|
|
.IP
|
|
.EX
|
|
pandoc \-s \-o output.html input.txt
|
|
.EE
|
|
.PP
|
|
For more information on how standalone documents are produced, see
|
|
Templates below.
|
|
.PP
|
|
If multiple input files are given, pandoc will concatenate them all
|
|
(with blank lines between them) before parsing.
|
|
(Use \f[CR]\-\-file\-scope\f[R] to parse files individually.)
|
|
.SS Specifying formats
|
|
The format of the input and output can be specified explicitly using
|
|
command\-line options.
|
|
The input format can be specified using the \f[CR]\-f/\-\-from\f[R]
|
|
option, the output format using the \f[CR]\-t/\-\-to\f[R] option.
|
|
Thus, to convert \f[CR]hello.txt\f[R] from Markdown to LaTeX, you could
|
|
type:
|
|
.IP
|
|
.EX
|
|
pandoc \-f markdown \-t latex hello.txt
|
|
.EE
|
|
.PP
|
|
To convert \f[CR]hello.html\f[R] from HTML to Markdown:
|
|
.IP
|
|
.EX
|
|
pandoc \-f html \-t markdown hello.html
|
|
.EE
|
|
.PP
|
|
Supported input and output formats are listed below under Options (see
|
|
\f[CR]\-f\f[R] for input formats and \f[CR]\-t\f[R] for output formats).
|
|
You can also use \f[CR]pandoc \-\-list\-input\-formats\f[R] and
|
|
\f[CR]pandoc \-\-list\-output\-formats\f[R] to print lists of supported
|
|
formats.
|
|
.PP
|
|
If the input or output format is not specified explicitly, pandoc will
|
|
attempt to guess it from the extensions of the filenames.
|
|
Thus, for example,
|
|
.IP
|
|
.EX
|
|
pandoc \-o hello.tex hello.txt
|
|
.EE
|
|
.PP
|
|
will convert \f[CR]hello.txt\f[R] from Markdown to LaTeX.
|
|
If no output file is specified (so that output goes to
|
|
\f[I]stdout\f[R]), or if the output file\(cqs extension is unknown, the
|
|
output format will default to HTML.
|
|
If no input file is specified (so that input comes from
|
|
\f[I]stdin\f[R]), or if the input files\(cq extensions are unknown, the
|
|
input format will be assumed to be Markdown.
|
|
.SS Character encoding
|
|
Pandoc uses the UTF\-8 character encoding for both input and output.
|
|
If your local character encoding is not UTF\-8, you should pipe input
|
|
and output through \f[CR]iconv\f[R]:
|
|
.IP
|
|
.EX
|
|
iconv \-t utf\-8 input.txt | pandoc | iconv \-f utf\-8
|
|
.EE
|
|
.PP
|
|
Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
|
|
OPML, DocBook, and Texinfo), information about the character encoding is
|
|
included in the document header, which will only be included if you use
|
|
the \f[CR]\-s/\-\-standalone\f[R] option.
|
|
.SS Creating a PDF
|
|
To produce a PDF, specify an output file with a \f[CR].pdf\f[R]
|
|
extension:
|
|
.IP
|
|
.EX
|
|
pandoc test.txt \-o test.pdf
|
|
.EE
|
|
.PP
|
|
By default, pandoc will use LaTeX to create the PDF, which requires that
|
|
a LaTeX engine be installed (see \f[CR]\-\-pdf\-engine\f[R] below).
|
|
Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an
|
|
intermediate format.
|
|
To do this, specify an output file with a \f[CR].pdf\f[R] extension, as
|
|
before, but add the \f[CR]\-\-pdf\-engine\f[R] option or
|
|
\f[CR]\-t context\f[R], \f[CR]\-t html\f[R], or \f[CR]\-t ms\f[R] to the
|
|
command line.
|
|
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.
|
|
When HTML is used as an intermediate format, the output can be styled
|
|
using \f[CR]\-\-css\f[R].
|
|
.PP
|
|
To debug the PDF creation, it can be useful to look at the intermediate
|
|
representation: instead of \f[CR]\-o test.pdf\f[R], use for example
|
|
\f[CR]\-s \-o test.tex\f[R] to output the generated LaTeX.
|
|
You can then test it with \f[CR]pdflatex test.tex\f[R].
|
|
.PP
|
|
When using LaTeX, the following packages need to be available (they are
|
|
included with all recent versions of TeX Live): \f[CR]amsfonts\f[R],
|
|
\f[CR]amsmath\f[R], \f[CR]lm\f[R], \f[CR]unicode\-math\f[R],
|
|
\f[CR]iftex\f[R], \f[CR]listings\f[R] (if the \f[CR]\-\-listings\f[R]
|
|
option is used), \f[CR]fancyvrb\f[R], \f[CR]longtable\f[R],
|
|
\f[CR]caption\f[R], \f[CR]booktabs\f[R], \f[CR]multirow\f[R] (if the
|
|
document contains a table with cells that cross multiple rows),
|
|
\f[CR]graphicx\f[R] (if the document contains images),
|
|
\f[CR]bookmark\f[R], \f[CR]xcolor\f[R], \f[CR]soul\f[R],
|
|
\f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] variable set),
|
|
\f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and \f[CR]babel\f[R]
|
|
(with \f[CR]lang\f[R]).
|
|
If \f[CR]CJKmainfont\f[R] is set, \f[CR]xeCJK\f[R] is needed if
|
|
\f[CR]xelatex\f[R] is used, else \f[CR]luatexja\f[R] is needed if
|
|
\f[CR]lualatex\f[R] is used.
|
|
\f[CR]framed\f[R] is required if code is highlighted in a scheme that
|
|
use a colored background.
|
|
The use of \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R] as the PDF engine
|
|
requires \f[CR]fontspec\f[R].
|
|
\f[CR]lualatex\f[R] uses \f[CR]selnolig\f[R] and \f[CR]lua\-ul\f[R].
|
|
\f[CR]xelatex\f[R] uses \f[CR]bidi\f[R] (with the \f[CR]dir\f[R]
|
|
variable set).
|
|
If the \f[CR]mathspec\f[R] variable is set, \f[CR]xelatex\f[R] will use
|
|
\f[CR]mathspec\f[R] instead of \f[CR]unicode\-math\f[R].
|
|
The \f[CR]csquotes\f[R] package will be used for typography if the
|
|
\f[CR]csquotes\f[R] variable or metadata field is set to a true value.
|
|
The \f[CR]natbib\f[R], \f[CR]biblatex\f[R], \f[CR]bibtex\f[R], and
|
|
\f[CR]biber\f[R] packages can optionally be used for citation rendering.
|
|
If math with \f[CR]\(rscancel\f[R], \f[CR]\(rsbcancel\f[R], or
|
|
\f[CR]\(rsxcancel\f[R] is used, the \f[CR]cancel\f[R] package is needed.
|
|
The following packages will be used to improve output quality if
|
|
present, but pandoc does not require them to be present:
|
|
\f[CR]upquote\f[R] (for straight quotes in verbatim environments),
|
|
\f[CR]microtype\f[R] (for better spacing adjustments),
|
|
\f[CR]parskip\f[R] (for better inter\-paragraph spaces), \f[CR]xurl\f[R]
|
|
(for better line breaks in URLs), and \f[CR]footnotehyper\f[R] or
|
|
\f[CR]footnote\f[R] (to allow footnotes in tables).
|
|
.SS Reading from the Web
|
|
Instead of an input file, an absolute URI may be given.
|
|
In this case pandoc will fetch the content using HTTP:
|
|
.IP
|
|
.EX
|
|
pandoc \-f html \-t markdown https://www.fsf.org
|
|
.EE
|
|
.PP
|
|
It is possible to supply a custom User\-Agent string or other header
|
|
when requesting a document from a URL:
|
|
.IP
|
|
.EX
|
|
pandoc \-f html \-t markdown \-\-request\-header User\-Agent:\(dqMozilla/5.0\(dq \(rs
|
|
https://www.fsf.org
|
|
.EE
|
|
.SH OPTIONS
|
|
.SS General options
|
|
.TP
|
|
\f[CR]\-f\f[R] \f[I]FORMAT\f[R], \f[CR]\-r\f[R] \f[I]FORMAT\f[R], \f[CR]\-\-from=\f[R]\f[I]FORMAT\f[R], \f[CR]\-\-read=\f[R]\f[I]FORMAT\f[R]
|
|
Specify input format.
|
|
\f[I]FORMAT\f[R] can be:
|
|
.RS
|
|
.IP \(bu 2
|
|
\f[CR]asciidoc\f[R] (AsciiDoc markup)
|
|
.IP \(bu 2
|
|
\f[CR]bibtex\f[R] (BibTeX bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]biblatex\f[R] (BibLaTeX bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]bits\f[R] (BITS XML, alias for \f[CR]jats\f[R])
|
|
.IP \(bu 2
|
|
\f[CR]commonmark\f[R] (CommonMark Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]commonmark_x\f[R] (CommonMark Markdown with extensions)
|
|
.IP \(bu 2
|
|
\f[CR]creole\f[R] (Creole 1.0)
|
|
.IP \(bu 2
|
|
\f[CR]csljson\f[R] (CSL JSON bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]csv\f[R] (CSV table)
|
|
.IP \(bu 2
|
|
\f[CR]tsv\f[R] (TSV table)
|
|
.IP \(bu 2
|
|
\f[CR]djot\f[R] (Djot markup)
|
|
.IP \(bu 2
|
|
\f[CR]docbook\f[R] (DocBook)
|
|
.IP \(bu 2
|
|
\f[CR]docx\f[R] (Word docx)
|
|
.IP \(bu 2
|
|
\f[CR]dokuwiki\f[R] (DokuWiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]endnotexml\f[R] (EndNote XML bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]epub\f[R] (EPUB)
|
|
.IP \(bu 2
|
|
\f[CR]fb2\f[R] (FictionBook2 e\-book)
|
|
.IP \(bu 2
|
|
\f[CR]gfm\f[R] (GitHub\-Flavored Markdown), or the deprecated and less
|
|
accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only
|
|
if you need extensions not supported in \f[CR]gfm\f[R].
|
|
.IP \(bu 2
|
|
\f[CR]haddock\f[R] (Haddock markup)
|
|
.IP \(bu 2
|
|
\f[CR]html\f[R] (HTML)
|
|
.IP \(bu 2
|
|
\f[CR]ipynb\f[R] (Jupyter notebook)
|
|
.IP \(bu 2
|
|
\f[CR]jats\f[R] (JATS XML)
|
|
.IP \(bu 2
|
|
\f[CR]jira\f[R] (Jira/Confluence wiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]json\f[R] (JSON version of native AST)
|
|
.IP \(bu 2
|
|
\f[CR]latex\f[R] (LaTeX)
|
|
.IP \(bu 2
|
|
\f[CR]markdown\f[R] (Pandoc\(cqs Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_mmd\f[R] (MultiMarkdown)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_phpextra\f[R] (PHP Markdown Extra)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_strict\f[R] (original unextended Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]mediawiki\f[R] (MediaWiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]man\f[R] (roff man)
|
|
.IP \(bu 2
|
|
\f[CR]mdoc\f[R] (mdoc manual page markup)
|
|
.IP \(bu 2
|
|
\f[CR]muse\f[R] (Muse)
|
|
.IP \(bu 2
|
|
\f[CR]native\f[R] (native Haskell)
|
|
.IP \(bu 2
|
|
\f[CR]odt\f[R] (OpenDocument text document)
|
|
.IP \(bu 2
|
|
\f[CR]opml\f[R] (OPML)
|
|
.IP \(bu 2
|
|
\f[CR]org\f[R] (Emacs Org mode)
|
|
.IP \(bu 2
|
|
\f[CR]pod\f[R] (Perl\(cqs Plain Old Documentation)
|
|
.IP \(bu 2
|
|
\f[CR]pptx\f[R] (PowerPoint)
|
|
.IP \(bu 2
|
|
\f[CR]ris\f[R] (RIS bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]rtf\f[R] (Rich Text Format)
|
|
.IP \(bu 2
|
|
\f[CR]rst\f[R] (reStructuredText)
|
|
.IP \(bu 2
|
|
\f[CR]t2t\f[R] (txt2tags)
|
|
.IP \(bu 2
|
|
\f[CR]textile\f[R] (Textile)
|
|
.IP \(bu 2
|
|
\f[CR]tikiwiki\f[R] (TikiWiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]twiki\f[R] (TWiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]typst\f[R] (typst)
|
|
.IP \(bu 2
|
|
\f[CR]vimwiki\f[R] (Vimwiki)
|
|
.IP \(bu 2
|
|
\f[CR]xlsx\f[R] (Excel spreadsheet)
|
|
.IP \(bu 2
|
|
\f[CR]xml\f[R] (XML version of native AST)
|
|
.IP \(bu 2
|
|
the path of a custom Lua reader, see Custom readers and writers below
|
|
.PP
|
|
Extensions can be individually enabled or disabled by appending
|
|
\f[CR]+EXTENSION\f[R] or \f[CR]\-EXTENSION\f[R] to the format name.
|
|
See Extensions below, for a list of extensions and their names.
|
|
See \f[CR]\-\-list\-input\-formats\f[R] and
|
|
\f[CR]\-\-list\-extensions\f[R], below.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-t\f[R] \f[I]FORMAT\f[R], \f[CR]\-w\f[R] \f[I]FORMAT\f[R], \f[CR]\-\-to=\f[R]\f[I]FORMAT\f[R], \f[CR]\-\-write=\f[R]\f[I]FORMAT\f[R]
|
|
Specify output format.
|
|
\f[I]FORMAT\f[R] can be:
|
|
.RS
|
|
.IP \(bu 2
|
|
\f[CR]ansi\f[R] (text with ANSI escape codes, for terminal viewing)
|
|
.IP \(bu 2
|
|
\f[CR]asciidoc\f[R] (modern AsciiDoc as interpreted by Asciidoctor)
|
|
.IP \(bu 2
|
|
\f[CR]asciidoc_legacy\f[R] (AsciiDoc as interpreted by
|
|
\f[CR]asciidoc\-py\f[R]).
|
|
.IP \(bu 2
|
|
\f[CR]asciidoctor\f[R] (deprecated synonym for \f[CR]asciidoc\f[R])
|
|
.IP \(bu 2
|
|
\f[CR]bbcode\f[R] BBCode
|
|
.IP \(bu 2
|
|
\f[CR]bbcode_fluxbb\f[R] BBCode (FluxBB)
|
|
.IP \(bu 2
|
|
\f[CR]bbcode_phpbb\f[R] BBCode (phpBB)
|
|
.IP \(bu 2
|
|
\f[CR]bbcode_steam\f[R] BBCode (Steam)
|
|
.IP \(bu 2
|
|
\f[CR]bbcode_hubzilla\f[R] BBCode (Hubzilla)
|
|
.IP \(bu 2
|
|
\f[CR]bbcode_xenforo\f[R] BBCode (xenForo)
|
|
.IP \(bu 2
|
|
\f[CR]beamer\f[R] (LaTeX beamer slide show)
|
|
.IP \(bu 2
|
|
\f[CR]bibtex\f[R] (BibTeX bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]biblatex\f[R] (BibLaTeX bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]chunkedhtml\f[R] (zip archive of multiple linked HTML files)
|
|
.IP \(bu 2
|
|
\f[CR]commonmark\f[R] (CommonMark Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]commonmark_x\f[R] (CommonMark Markdown with extensions)
|
|
.IP \(bu 2
|
|
\f[CR]context\f[R] (ConTeXt)
|
|
.IP \(bu 2
|
|
\f[CR]csljson\f[R] (CSL JSON bibliography)
|
|
.IP \(bu 2
|
|
\f[CR]djot\f[R] (Djot markup)
|
|
.IP \(bu 2
|
|
\f[CR]docbook\f[R] or \f[CR]docbook4\f[R] (DocBook 4)
|
|
.IP \(bu 2
|
|
\f[CR]docbook5\f[R] (DocBook 5)
|
|
.IP \(bu 2
|
|
\f[CR]docx\f[R] (Word docx)
|
|
.IP \(bu 2
|
|
\f[CR]dokuwiki\f[R] (DokuWiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]epub\f[R] or \f[CR]epub3\f[R] (EPUB v3 book)
|
|
.IP \(bu 2
|
|
\f[CR]epub2\f[R] (EPUB v2)
|
|
.IP \(bu 2
|
|
\f[CR]fb2\f[R] (FictionBook2 e\-book)
|
|
.IP \(bu 2
|
|
\f[CR]gfm\f[R] (GitHub\-Flavored Markdown), or the deprecated and less
|
|
accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only
|
|
if you need extensions not supported in \f[CR]gfm\f[R].
|
|
.IP \(bu 2
|
|
\f[CR]haddock\f[R] (Haddock markup)
|
|
.IP \(bu 2
|
|
\f[CR]html\f[R] or \f[CR]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot
|
|
markup)
|
|
.IP \(bu 2
|
|
\f[CR]html4\f[R] (XHTML 1.0 Transitional)
|
|
.IP \(bu 2
|
|
\f[CR]icml\f[R] (InDesign ICML)
|
|
.IP \(bu 2
|
|
\f[CR]ipynb\f[R] (Jupyter notebook)
|
|
.IP \(bu 2
|
|
\f[CR]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set)
|
|
.IP \(bu 2
|
|
\f[CR]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set)
|
|
.IP \(bu 2
|
|
\f[CR]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set)
|
|
.IP \(bu 2
|
|
\f[CR]jats\f[R] (alias for \f[CR]jats_archiving\f[R])
|
|
.IP \(bu 2
|
|
\f[CR]jira\f[R] (Jira/Confluence wiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]json\f[R] (JSON version of native AST)
|
|
.IP \(bu 2
|
|
\f[CR]latex\f[R] (LaTeX)
|
|
.IP \(bu 2
|
|
\f[CR]man\f[R] (roff man)
|
|
.IP \(bu 2
|
|
\f[CR]markdown\f[R] (Pandoc\(cqs Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_mmd\f[R] (MultiMarkdown)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_phpextra\f[R] (PHP Markdown Extra)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_strict\f[R] (original unextended Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]markua\f[R] (Markua)
|
|
.IP \(bu 2
|
|
\f[CR]mediawiki\f[R] (MediaWiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]ms\f[R] (roff ms)
|
|
.IP \(bu 2
|
|
\f[CR]muse\f[R] (Muse)
|
|
.IP \(bu 2
|
|
\f[CR]native\f[R] (native Haskell)
|
|
.IP \(bu 2
|
|
\f[CR]odt\f[R] (OpenDocument text document)
|
|
.IP \(bu 2
|
|
\f[CR]opml\f[R] (OPML)
|
|
.IP \(bu 2
|
|
\f[CR]opendocument\f[R] (OpenDocument XML)
|
|
.IP \(bu 2
|
|
\f[CR]org\f[R] (Emacs Org mode)
|
|
.IP \(bu 2
|
|
\f[CR]pdf\f[R] (PDF)
|
|
.IP \(bu 2
|
|
\f[CR]plain\f[R] (plain text)
|
|
.IP \(bu 2
|
|
\f[CR]pptx\f[R] (PowerPoint slide show)
|
|
.IP \(bu 2
|
|
\f[CR]rst\f[R] (reStructuredText)
|
|
.IP \(bu 2
|
|
\f[CR]rtf\f[R] (Rich Text Format)
|
|
.IP \(bu 2
|
|
\f[CR]texinfo\f[R] (GNU Texinfo)
|
|
.IP \(bu 2
|
|
\f[CR]textile\f[R] (Textile)
|
|
.IP \(bu 2
|
|
\f[CR]t2t\f[R] (txt2tags)
|
|
.IP \(bu 2
|
|
\f[CR]slideous\f[R] (Slideous HTML and JavaScript slide show)
|
|
.IP \(bu 2
|
|
\f[CR]slidy\f[R] (Slidy HTML and JavaScript slide show)
|
|
.IP \(bu 2
|
|
\f[CR]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show)
|
|
.IP \(bu 2
|
|
\f[CR]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)
|
|
.IP \(bu 2
|
|
\f[CR]s5\f[R] (S5 HTML and JavaScript slide show)
|
|
.IP \(bu 2
|
|
\f[CR]tei\f[R] (TEI Simple)
|
|
.IP \(bu 2
|
|
\f[CR]typst\f[R] (typst)
|
|
.IP \(bu 2
|
|
\f[CR]vimdoc\f[R] (Vimdoc)
|
|
.IP \(bu 2
|
|
\f[CR]xml\f[R] (XML version of native AST)
|
|
.IP \(bu 2
|
|
\f[CR]xwiki\f[R] (XWiki markup)
|
|
.IP \(bu 2
|
|
\f[CR]zimwiki\f[R] (ZimWiki markup)
|
|
.IP \(bu 2
|
|
the path of a custom Lua writer, see Custom readers and writers below
|
|
.PP
|
|
Note that \f[CR]odt\f[R], \f[CR]docx\f[R], \f[CR]epub\f[R], and
|
|
\f[CR]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless
|
|
forced with \f[CR]\-o \-\f[R].
|
|
.PP
|
|
Extensions can be individually enabled or disabled by appending
|
|
\f[CR]+EXTENSION\f[R] or \f[CR]\-EXTENSION\f[R] to the format name.
|
|
See Extensions below, for a list of extensions and their names.
|
|
See \f[CR]\-\-list\-output\-formats\f[R] and
|
|
\f[CR]\-\-list\-extensions\f[R], below.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-o\f[R] \f[I]FILE\f[R], \f[CR]\-\-output=\f[R]\f[I]FILE\f[R]
|
|
Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].
|
|
If \f[I]FILE\f[R] is \f[CR]\-\f[R], output will go to \f[I]stdout\f[R],
|
|
even if a non\-textual format (\f[CR]docx\f[R], \f[CR]odt\f[R],
|
|
\f[CR]epub2\f[R], \f[CR]epub3\f[R]) is specified.
|
|
If the output format is \f[CR]chunkedhtml\f[R] and \f[I]FILE\f[R] has no
|
|
extension, then instead of producing a \f[CR].zip\f[R] file pandoc will
|
|
create a directory \f[I]FILE\f[R] and unpack the zip archive there
|
|
(unless \f[I]FILE\f[R] already exists, in which case an error will be
|
|
raised).
|
|
.TP
|
|
\f[CR]\-\-data\-dir=\f[R]\f[I]DIRECTORY\f[R]
|
|
Specify the user data directory to search for pandoc data files.
|
|
If this option is not specified, the default user data directory will be
|
|
used.
|
|
On *nix and macOS systems this will be the \f[CR]pandoc\f[R]
|
|
subdirectory of the XDG data directory (by default,
|
|
\f[CR]$HOME/.local/share\f[R], overridable by setting the
|
|
\f[CR]XDG_DATA_HOME\f[R] environment variable).
|
|
If that directory does not exist and \f[CR]$HOME/.pandoc\f[R] exists, it
|
|
will be used (for backwards compatibility).
|
|
On Windows the default user data directory is
|
|
\f[CR]%APPDATA%\(rspandoc\f[R].
|
|
You can find the default user data directory on your system by looking
|
|
at the output of \f[CR]pandoc \-\-version\f[R].
|
|
Data files placed in this directory (for example,
|
|
\f[CR]reference.odt\f[R], \f[CR]reference.docx\f[R],
|
|
\f[CR]epub.css\f[R], \f[CR]templates\f[R]) will override pandoc\(cqs
|
|
normal defaults.
|
|
(Note that the user data directory is not created by pandoc, so you will
|
|
need to create it yourself if you want to make use of it.)
|
|
.TP
|
|
\f[CR]\-d\f[R] \f[I]FILE\f[R], \f[CR]\-\-defaults=\f[R]\f[I]FILE\f[R]
|
|
Specify a set of default option settings.
|
|
\f[I]FILE\f[R] is a YAML or JSON file whose fields correspond to
|
|
command\-line option settings.
|
|
All options for document conversion, including input and output files,
|
|
can be set using a defaults file.
|
|
The file will be searched for first in the working directory, and then
|
|
in the \f[CR]defaults\f[R] subdirectory of the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R]).
|
|
If \f[I]FILE\f[R] lacks an extension, pandoc will also try adding the
|
|
\f[CR].yaml\f[R] extension if \f[I]FILE\f[R] is not found.
|
|
See the section Defaults files for more information on the file format.
|
|
Settings from the defaults file may be overridden or extended by
|
|
subsequent options on the command line.
|
|
.TP
|
|
\f[CR]\-\-bash\-completion\f[R]
|
|
Generate a bash completion script.
|
|
To enable bash completion with pandoc, add this to your
|
|
\f[CR].bashrc\f[R]:
|
|
.RS
|
|
.IP
|
|
.EX
|
|
eval \(dq$(pandoc \-\-bash\-completion)\(dq
|
|
.EE
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-sandbox[=true|false]\f[R]
|
|
Run pandoc in a sandbox, limiting IO operations in readers and writers
|
|
to reading the files specified on the command line.
|
|
Note that this option does not limit IO operations by filters or in the
|
|
production of PDF documents.
|
|
But it does offer security against, for example, disclosure of files
|
|
through the use of \f[CR]include\f[R] directives.
|
|
Anyone using pandoc on untrusted user input should use this option.
|
|
.RS
|
|
.PP
|
|
Note: some readers and writers (e.g., \f[CR]docx\f[R]) need access to
|
|
data files.
|
|
If these are stored on the file system, then pandoc will not be able to
|
|
find them when run in \f[CR]\-\-sandbox\f[R] mode and will raise an
|
|
error.
|
|
For these applications, we recommend using a pandoc binary compiled with
|
|
the \f[CR]embed_data_files\f[R] option, which causes the data files to
|
|
be baked into the binary instead of being stored on the file system.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-verbose\f[R]
|
|
Give verbose debugging output.
|
|
.TP
|
|
\f[CR]\-\-quiet\f[R]
|
|
Suppress warning messages.
|
|
.TP
|
|
\f[CR]\-\-fail\-if\-warnings[=true|false]\f[R]
|
|
Exit with error status if there are any warnings.
|
|
.TP
|
|
\f[CR]\-\-log=\f[R]\f[I]FILE\f[R]
|
|
Write log messages in machine\-readable JSON format to \f[I]FILE\f[R].
|
|
All messages above DEBUG level will be written, regardless of verbosity
|
|
settings (\f[CR]\-\-verbose\f[R], \f[CR]\-\-quiet\f[R]).
|
|
.TP
|
|
\f[CR]\-\-list\-input\-formats\f[R]
|
|
List supported input formats, one per line.
|
|
.TP
|
|
\f[CR]\-\-list\-output\-formats\f[R]
|
|
List supported output formats, one per line.
|
|
.TP
|
|
\f[CR]\-\-list\-extensions\f[R][\f[CR]=\f[R]\f[I]FORMAT\f[R]]
|
|
List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
|
|
by a \f[CR]+\f[R] or \f[CR]\-\f[R] indicating whether it is enabled by
|
|
default in \f[I]FORMAT\f[R].
|
|
If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\(cqs Markdown
|
|
are given.
|
|
.TP
|
|
\f[CR]\-\-list\-highlight\-languages\f[R]
|
|
List supported languages for syntax highlighting, one per line.
|
|
.TP
|
|
\f[CR]\-\-list\-highlight\-styles\f[R]
|
|
List supported styles for syntax highlighting, one per line.
|
|
See \f[CR]\-\-syntax\-highlighting\f[R].
|
|
.TP
|
|
\f[CR]\-v\f[R], \f[CR]\-\-version\f[R]
|
|
Print version.
|
|
.TP
|
|
\f[CR]\-h\f[R], \f[CR]\-\-help\f[R]
|
|
Show usage message.
|
|
.SS Reader options
|
|
.TP
|
|
\f[CR]\-\-shift\-heading\-level\-by=\f[R]\f[I]NUMBER\f[R]
|
|
Shift heading levels by a positive or negative integer.
|
|
For example, with \f[CR]\-\-shift\-heading\-level\-by=\-1\f[R], level 2
|
|
headings become level 1 headings, and level 3 headings become level 2
|
|
headings.
|
|
Headings cannot have a level less than 1, so a heading that would be
|
|
shifted below level 1 becomes a regular paragraph.
|
|
Exception: with a shift of \-N, a level\-N heading at the beginning of
|
|
the document replaces the metadata title.
|
|
\f[CR]\-\-shift\-heading\-level\-by=\-1\f[R] is a good choice when
|
|
converting HTML or Markdown documents that use an initial level\-1
|
|
heading for the document title and level\-2+ headings for sections.
|
|
\f[CR]\-\-shift\-heading\-level\-by=1\f[R] may be a good choice for
|
|
converting Markdown documents that use level\-1 headings for sections to
|
|
HTML, since pandoc uses a level\-1 heading to render the document title.
|
|
.TP
|
|
\f[CR]\-\-base\-header\-level=\f[R]\f[I]NUMBER\f[R]
|
|
\f[I]Deprecated.
|
|
Use \f[CI]\-\-shift\-heading\-level\-by\f[I]=X instead, where X = NUMBER
|
|
\- 1.\f[R] Specify the base level for headings (defaults to 1).
|
|
.TP
|
|
\f[CR]\-\-indented\-code\-classes=\f[R]\f[I]CLASSES\f[R]
|
|
Specify classes to use for indented code blocks\(emfor example,
|
|
\f[CR]perl,numberLines\f[R] or \f[CR]haskell\f[R].
|
|
Multiple classes may be separated by spaces or commas.
|
|
.TP
|
|
\f[CR]\-\-default\-image\-extension=\f[R]\f[I]EXTENSION\f[R]
|
|
Specify a default extension to use when image paths/URLs have no
|
|
extension.
|
|
This allows you to use the same source for formats that require
|
|
different kinds of images.
|
|
Currently this option only affects the Markdown and LaTeX readers.
|
|
.TP
|
|
\f[CR]\-\-file\-scope[=true|false]\f[R]
|
|
Parse each file individually before combining for multifile documents.
|
|
This will allow footnotes in different files with the same identifiers
|
|
to work as expected.
|
|
If this option is set, footnotes and links will not work across files.
|
|
Reading binary files (docx, odt, epub) implies
|
|
\f[CR]\-\-file\-scope\f[R].
|
|
.RS
|
|
.PP
|
|
If two or more files are processed using \f[CR]\-\-file\-scope\f[R],
|
|
prefixes based on the filenames will be added to identifiers in order to
|
|
disambiguate them, and internal links will be adjusted accordingly.
|
|
For example, a header with identifier \f[CR]foo\f[R] in
|
|
\f[CR]subdir/file1.txt\f[R] will have its identifier changed to
|
|
\f[CR]subdir__file1.txt__foo\f[R].
|
|
.RE
|
|
.TP
|
|
\f[CR]\-F\f[R] \f[I]PROGRAM\f[R], \f[CR]\-\-filter=\f[R]\f[I]PROGRAM\f[R]
|
|
Specify an executable to be used as a filter transforming the pandoc AST
|
|
after the input is parsed and before the output is written.
|
|
The executable should read JSON from stdin and write JSON to stdout.
|
|
The JSON must be formatted like pandoc\(cqs own JSON input and output.
|
|
The name of the output format will be passed to the filter as the first
|
|
argument.
|
|
Hence,
|
|
.RS
|
|
.IP
|
|
.EX
|
|
pandoc \-\-filter ./caps.py \-t latex
|
|
.EE
|
|
.PP
|
|
is equivalent to
|
|
.IP
|
|
.EX
|
|
pandoc \-t json | ./caps.py latex | pandoc \-f json \-t latex
|
|
.EE
|
|
.PP
|
|
The latter form may be useful for debugging filters.
|
|
.PP
|
|
Filters may be written in any language.
|
|
\f[CR]Text.Pandoc.JSON\f[R] exports \f[CR]toJSONFilter\f[R] to
|
|
facilitate writing filters in Haskell.
|
|
Those who would prefer to write filters in python can use the module
|
|
\f[CR]pandocfilters\f[R], installable from PyPI.
|
|
There are also pandoc filter libraries in PHP, perl, and
|
|
JavaScript/node.js.
|
|
.PP
|
|
In order of preference, pandoc will look for filters in
|
|
.IP "1." 3
|
|
a specified full or relative path (executable or non\-executable),
|
|
.IP "2." 3
|
|
\f[CR]$DATADIR/filters\f[R] (executable or non\-executable) where
|
|
\f[CR]$DATADIR\f[R] is the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R], above),
|
|
.IP "3." 3
|
|
\f[CR]$PATH\f[R] (executable only).
|
|
.PP
|
|
Filters, Lua\-filters, and citeproc processing are applied in the order
|
|
specified on the command line.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-L\f[R] \f[I]SCRIPT\f[R], \f[CR]\-\-lua\-filter=\f[R]\f[I]SCRIPT\f[R]
|
|
Transform the document in a similar fashion as JSON filters (see
|
|
\f[CR]\-\-filter\f[R]), but use pandoc\(cqs built\-in Lua filtering
|
|
system.
|
|
The given Lua script is expected to return a list of Lua filters which
|
|
will be applied in order.
|
|
Each Lua filter must contain element\-transforming functions indexed by
|
|
the name of the AST element on which the filter function should be
|
|
applied.
|
|
.RS
|
|
.PP
|
|
The \f[CR]pandoc\f[R] Lua module provides helper functions for element
|
|
creation.
|
|
It is always loaded into the script\(cqs Lua environment.
|
|
.PP
|
|
See the Lua filters documentation for further details.
|
|
.PP
|
|
In order of preference, pandoc will look for Lua filters in
|
|
.IP "1." 3
|
|
a specified full or relative path,
|
|
.IP "2." 3
|
|
\f[CR]$DATADIR/filters\f[R] where \f[CR]$DATADIR\f[R] is the user data
|
|
directory (see \f[CR]\-\-data\-dir\f[R], above).
|
|
.PP
|
|
Filters, Lua filters, and citeproc processing are applied in the order
|
|
specified on the command line.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-M\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]\-\-metadata=\f[R]\f[I]KEY\f[R][\f[CR]:\f[R]\f[I]VAL\f[R]]
|
|
Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].
|
|
A value specified on the command line overrides a value specified in the
|
|
document using YAML metadata blocks.
|
|
Values will be parsed as YAML boolean or string values.
|
|
If no value is specified, the value will be treated as Boolean true.
|
|
Like \f[CR]\-\-variable\f[R], \f[CR]\-\-metadata\f[R] causes template
|
|
variables to be set.
|
|
But unlike \f[CR]\-\-variable\f[R], \f[CR]\-\-metadata\f[R] affects the
|
|
metadata of the underlying document (which is accessible from filters
|
|
and may be printed in some output formats) and metadata values will be
|
|
escaped when inserted into the template.
|
|
.TP
|
|
\f[CR]\-\-metadata\-file=\f[R]\f[I]FILE\f[R]
|
|
Read metadata from the supplied YAML (or JSON) file.
|
|
This option can be used with every input format, but string scalars in
|
|
the metadata file will always be parsed as Markdown.
|
|
(If the input format is Markdown or a Markdown variant, then the same
|
|
variant will be used to parse the metadata file; if it is a
|
|
non\-Markdown format, pandoc\(cqs default Markdown extensions will be
|
|
used.)
|
|
This option can be used repeatedly to include multiple metadata files;
|
|
values in files specified later on the command line will be preferred
|
|
over those specified in earlier files.
|
|
Metadata values specified inside the document, or by using
|
|
\f[CR]\-M\f[R], overwrite values specified with this option.
|
|
The file will be searched for first in the working directory, and then
|
|
in the \f[CR]metadata\f[R] subdirectory of the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R]).
|
|
.TP
|
|
\f[CR]\-p\f[R], \f[CR]\-\-preserve\-tabs[=true|false]\f[R]
|
|
Preserve tabs instead of converting them to spaces.
|
|
(By default, pandoc converts tabs to spaces before parsing its input.)
|
|
Note that this will only affect tabs in literal code spans and code
|
|
blocks.
|
|
Tabs in regular text are always treated as spaces.
|
|
.TP
|
|
\f[CR]\-\-tab\-stop=\f[R]\f[I]NUMBER\f[R]
|
|
Specify the number of spaces per tab (default is 4).
|
|
.TP
|
|
\f[CR]\-\-track\-changes=accept\f[R]|\f[CR]reject\f[R]|\f[CR]all\f[R]
|
|
Specifies what to do with insertions, deletions, and comments produced
|
|
by the MS Word \(lqTrack Changes\(rq feature.
|
|
\f[CR]accept\f[R] (the default) processes all the insertions and
|
|
deletions.
|
|
\f[CR]reject\f[R] ignores them.
|
|
Both \f[CR]accept\f[R] and \f[CR]reject\f[R] ignore comments.
|
|
\f[CR]all\f[R] includes all insertions, deletions, and comments, wrapped
|
|
in spans with \f[CR]insertion\f[R], \f[CR]deletion\f[R],
|
|
\f[CR]comment\-start\f[R], and \f[CR]comment\-end\f[R] classes,
|
|
respectively.
|
|
The author and time of change is included.
|
|
\f[CR]all\f[R] is useful for scripting: only accepting changes from a
|
|
certain reviewer, say, or before a certain date.
|
|
If a paragraph is inserted or deleted, \f[CR]track\-changes=all\f[R]
|
|
produces a span with the class
|
|
\f[CR]paragraph\-insertion\f[R]/\f[CR]paragraph\-deletion\f[R] before
|
|
the affected paragraph break.
|
|
This option only affects the docx reader.
|
|
.TP
|
|
\f[CR]\-\-extract\-media=\f[R]\f[I]DIR\f[R]|\f[I]FILE\f[R]\f[CR].zip\f[R]
|
|
Extract images and other media contained in or linked from the source
|
|
document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
|
|
the images references in the document so they point to the extracted
|
|
files.
|
|
Media are downloaded, read from the file system, or extracted from a
|
|
binary container (e.g.\ docx), as needed.
|
|
The original file paths are used if they are relative paths not
|
|
containing \f[CR]..\f[R].
|
|
Otherwise filenames are constructed from the SHA1 hash of the contents.
|
|
.RS
|
|
.PP
|
|
If the path given ends in \f[CR].zip\f[R], then instead of creating a
|
|
directory, pandoc will create a zip archive containing the media files.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-abbreviations=\f[R]\f[I]FILE\f[R]
|
|
Specifies a custom abbreviations file, with abbreviations one to a line.
|
|
If this option is not specified, pandoc will read the data file
|
|
\f[CR]abbreviations\f[R] from the user data directory or fall back on a
|
|
system default.
|
|
To see the system default, use
|
|
\f[CR]pandoc \-\-print\-default\-data\-file=abbreviations\f[R].
|
|
The only use pandoc makes of this list is in the Markdown reader.
|
|
Strings found in this list will be followed by a nonbreaking space, and
|
|
the period will not produce sentence\-ending space in formats like
|
|
LaTeX.
|
|
The strings may not contain spaces.
|
|
.TP
|
|
\f[CR]\-\-typst\-input=\f[R]\f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]]
|
|
Set a parameter value that will be made available to the typst parser in
|
|
\f[CR]sys.inputs\f[R], like \f[CR]\-\-input\f[R] in the \f[CR]typst\f[R]
|
|
CLI.
|
|
Either \f[CR]:\f[R] or \f[CR]=\f[R] may be used to separate
|
|
\f[I]KEY\f[R] from \f[I]VAL\f[R].
|
|
Values containing spaces must be quoted.
|
|
.TP
|
|
\f[CR]\-\-trace[=true|false]\f[R]
|
|
Print diagnostic output tracing parser progress to stderr.
|
|
This option is intended for use by developers in diagnosing performance
|
|
issues.
|
|
.SS General writer options
|
|
.TP
|
|
\f[CR]\-s\f[R], \f[CR]\-\-standalone\f[R]
|
|
Produce output with an appropriate header and footer (e.g.\ a standalone
|
|
HTML, LaTeX, TEI, or RTF file, not a fragment).
|
|
This option is set automatically for \f[CR]pdf\f[R], \f[CR]epub\f[R],
|
|
\f[CR]epub3\f[R], \f[CR]fb2\f[R], \f[CR]docx\f[R], and \f[CR]odt\f[R]
|
|
output.
|
|
For \f[CR]native\f[R] output, this option causes metadata to be
|
|
included; otherwise, metadata is suppressed.
|
|
.TP
|
|
\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.
|
|
If the template is not found, pandoc will search for it in the
|
|
\f[CR]templates\f[R] subdirectory of the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R]).
|
|
If no extension is specified and an extensionless template is not found,
|
|
pandoc will look for a template with an extension corresponding to the
|
|
writer, so that \f[CR]\-\-template=special\f[R] looks for
|
|
\f[CR]special.html\f[R] for HTML output.
|
|
If this option is not used, a default template appropriate for the
|
|
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 string value
|
|
\f[I]VAL\f[R] when rendering the document in standalone mode.
|
|
Either \f[CR]:\f[R] or \f[CR]=\f[R] may be used to separate
|
|
\f[I]KEY\f[R] from \f[I]VAL\f[R].
|
|
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 or using the \f[CR]\-\-variable\-json\f[R] option.
|
|
If the variable already has a \f[I]list\f[R] value, the value will be
|
|
added to the list.
|
|
If it already has another kind of value, it will be made into a list
|
|
containing the previous and the new value.
|
|
For example, \f[CR]\-V author=Joe \-V author=Sue\f[R] makes
|
|
\f[CR]author\f[R] contain a list of strings: \f[CR]Joe\f[R] and
|
|
\f[CR]Sue\f[R].
|
|
.TP
|
|
\f[CR]\-\-variable\-json=\f[R]\f[I]KEY\f[R][\f[CR]=\f[R]\f[I]JSON\f[R]]
|
|
Set the template variable \f[I]KEY\f[R] to the value specified by a JSON
|
|
string (this may be a boolean, a string, a list, or a mapping; a number
|
|
will be treated as a string).
|
|
For example, \f[CR]\-\-variable\-json foo=false\f[R] will give
|
|
\f[CR]foo\f[R] the boolean false value, while
|
|
\f[CR]\-\-variable\-json foo=\(aq\(dqfalse\(dq\(aq\f[R] will give it the
|
|
string value \f[CR]\(dqfalse\(dq\f[R].
|
|
Either \f[CR]:\f[R] or \f[CR]=\f[R] may be used to separate
|
|
\f[I]KEY\f[R] from \f[I]VAL\f[R].
|
|
If the variable already has a value, this value will be replaced.
|
|
.TP
|
|
\f[CR]\-D\f[R] \f[I]FORMAT\f[R], \f[CR]\-\-print\-default\-template=\f[R]\f[I]FORMAT\f[R]
|
|
Print the system default template for an output \f[I]FORMAT\f[R].
|
|
(See \f[CR]\-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.)
|
|
Templates in the user data directory are ignored.
|
|
This option may be used with \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] to
|
|
redirect output to a file, but \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] must
|
|
come before \f[CR]\-\-print\-default\-template\f[R] on the command line.
|
|
.RS
|
|
.PP
|
|
Note that some of the default templates use partials, for example
|
|
\f[CR]styles.html\f[R].
|
|
To print the partials, use \f[CR]\-\-print\-default\-data\-file\f[R]:
|
|
for example,
|
|
\f[CR]\-\-print\-default\-data\-file=templates/styles.html\f[R].
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-print\-default\-data\-file=\f[R]\f[I]FILE\f[R]
|
|
Print a system default data file.
|
|
Files in the user data directory are ignored.
|
|
This option may be used with \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] to
|
|
redirect output to a file, but \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] must
|
|
come before \f[CR]\-\-print\-default\-data\-file\f[R] on the command
|
|
line.
|
|
.TP
|
|
\f[CR]\-\-eol=crlf\f[R]|\f[CR]lf\f[R]|\f[CR]native\f[R]
|
|
Manually specify line endings: \f[CR]crlf\f[R] (Windows), \f[CR]lf\f[R]
|
|
(macOS/Linux/UNIX), or \f[CR]native\f[R] (line endings appropriate to
|
|
the OS on which pandoc is being run).
|
|
The default is \f[CR]native\f[R].
|
|
.TP
|
|
\f[CR]\-\-dpi\f[R]=\f[I]NUMBER\f[R]
|
|
Specify the default dpi (dots per inch) value for conversion from pixels
|
|
to inch/centimeters and vice versa.
|
|
(Technically, the correct term would be ppi: pixels per inch.)
|
|
The default is 96dpi.
|
|
When images contain information about dpi internally, the encoded value
|
|
is used instead of the default specified by this option.
|
|
.TP
|
|
\f[CR]\-\-wrap=auto\f[R]|\f[CR]none\f[R]|\f[CR]preserve\f[R]
|
|
Determine how text is wrapped in the output (the source code, not the
|
|
rendered version).
|
|
With \f[CR]auto\f[R] (the default), pandoc will attempt to wrap lines to
|
|
the column width specified by \f[CR]\-\-columns\f[R] (default 72).
|
|
With \f[CR]none\f[R], pandoc will not wrap lines at all.
|
|
With \f[CR]preserve\f[R], pandoc will attempt to preserve the wrapping
|
|
from the source document (that is, where there are nonsemantic newlines
|
|
in the source, there will be nonsemantic newlines in the output as
|
|
well).
|
|
In \f[CR]ipynb\f[R] output, this option affects wrapping of the contents
|
|
of Markdown cells.
|
|
.TP
|
|
\f[CR]\-\-columns=\f[R]\f[I]NUMBER\f[R]
|
|
Specify length of lines in characters.
|
|
This affects text wrapping in the generated source code (see
|
|
\f[CR]\-\-wrap\f[R]).
|
|
It also affects calculation of column widths for plain text tables (see
|
|
Tables below).
|
|
.TP
|
|
\f[CR]\-\-toc[=true|false]\f[R], \f[CR]\-\-table\-of\-contents[=true|false]\f[R]
|
|
Include an automatically generated table of contents (or, in the case of
|
|
\f[CR]latex\f[R], \f[CR]context\f[R], \f[CR]docx\f[R], \f[CR]odt\f[R],
|
|
\f[CR]opendocument\f[R], \f[CR]rst\f[R], or \f[CR]ms\f[R], an
|
|
instruction to create one) in the output document.
|
|
This option has no effect unless \f[CR]\-s/\-\-standalone\f[R] is used,
|
|
and it has no effect on \f[CR]man\f[R], \f[CR]docbook4\f[R],
|
|
\f[CR]docbook5\f[R], or \f[CR]jats\f[R] output.
|
|
.RS
|
|
.PP
|
|
Note that if you are producing a PDF via \f[CR]ms\f[R] and using (the
|
|
default) \f[CR]groff\f[R] as a \f[CR]\-\-pdf\-engine\f[R], the table of
|
|
contents will appear at the end of the document.
|
|
If you would prefer it to be at the beginning of the document, before
|
|
the title, you can use \f[CR]\-\-pdf\-engine=pdfroff\f[R].
|
|
.PP
|
|
Because the entries in a table of contents need heading identifiers to
|
|
link to, this option forces the \f[CR]auto_identifiers\f[R] extension on
|
|
for the input format, even when it is off by default (as it is for
|
|
\f[CR]typst\f[R]).
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-toc\-depth=\f[R]\f[I]NUMBER\f[R]
|
|
Specify the number of section levels to include in the table of
|
|
contents.
|
|
The default is 3 (which means that level\-1, 2, and 3 headings will be
|
|
listed in the contents).
|
|
.TP
|
|
\f[CR]\-\-lof[=true|false]\f[R], \f[CR]\-\-list\-of\-figures[=true|false]\f[R]
|
|
Include an automatically generated list of figures (or, in some formats,
|
|
an instruction to create one) in the output document.
|
|
This option has no effect unless \f[CR]\-s/\-\-standalone\f[R] is used,
|
|
and it only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and
|
|
\f[CR]docx\f[R] output.
|
|
.TP
|
|
\f[CR]\-\-lot[=true|false]\f[R], \f[CR]\-\-list\-of\-tables[=true|false]\f[R]
|
|
Include an automatically generated list of tables (or, in some formats,
|
|
an instruction to create one) in the output document.
|
|
This option has no effect unless \f[CR]\-s/\-\-standalone\f[R] is used,
|
|
and it only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and
|
|
\f[CR]docx\f[R] output.
|
|
.TP
|
|
\f[CR]\-\-strip\-comments[=true|false]\f[R]
|
|
Strip out HTML comments in the Markdown or Textile source, rather than
|
|
passing them on to Markdown, Textile or HTML output as raw HTML.
|
|
This does not apply to HTML comments inside raw HTML blocks when the
|
|
\f[CR]markdown_in_html_blocks\f[R] extension is not set.
|
|
.TP
|
|
\f[CR]\-\-syntax\-highlighting=default|none|idiomatic|\f[R]\f[I]STYLE\f[R]\f[CR]|\f[R]\f[I]FILE\f[R]
|
|
The method to use for code syntax highlighting.
|
|
Setting a specific \f[I]STYLE\f[R] causes highlighting to be performed
|
|
with the internal highlighting engine, using KDE syntax definitions and
|
|
styles.
|
|
The \f[CR]idiomatic\f[R] method uses a format\-specific highlighter if
|
|
one is available, or the default style if the target format has no
|
|
idiomatic highlighting method.
|
|
Setting this option to \f[CR]none\f[R] disables all syntax highlighting.
|
|
The \f[CR]default\f[R] method uses a format\-specific default.
|
|
.RS
|
|
.PP
|
|
The default for HTML, EPUB, Docx, Ms, Man, and LaTeX output is to use
|
|
the internal highlighter with the default style; for Typst it is to use
|
|
Typst\(cqs own syntax highlighting system.
|
|
.PP
|
|
Style options are \f[CR]pygments\f[R] (the default), \f[CR]kate\f[R],
|
|
\f[CR]monochrome\f[R], \f[CR]breezeDark\f[R], \f[CR]espresso\f[R],
|
|
\f[CR]zenburn\f[R], \f[CR]haddock\f[R], and \f[CR]tango\f[R].
|
|
For more information on syntax highlighting in pandoc, see Syntax
|
|
highlighting, below.
|
|
See also \f[CR]\-\-list\-highlight\-styles\f[R].
|
|
.PP
|
|
Instead of a \f[I]STYLE\f[R] name, a JSON file with extension
|
|
\f[CR].theme\f[R] may be supplied.
|
|
This will be parsed as a KDE syntax highlighting theme and (if valid)
|
|
used as the highlighting style.
|
|
.PP
|
|
To generate the JSON version of an existing style, use
|
|
\f[CR]\-\-print\-highlight\-style\f[R].
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-no\-highlight\f[R]
|
|
\f[I]Deprecated, use \f[CI]\-\-syntax\-highlighting=none\f[I]
|
|
instead.\f[R]
|
|
.RS
|
|
.PP
|
|
Disables syntax highlighting for code blocks and inlines, even when a
|
|
language attribute is given.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-highlight\-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
|
|
\f[I]Deprecated, use
|
|
\f[CI]\-\-syntax\-highlighting=\f[I]\f[R]STYLE\f[I]|\f[R]FILE\f[I]
|
|
instead.\f[R]
|
|
.RS
|
|
.PP
|
|
Specifies the coloring style to be used in highlighted source code.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-print\-highlight\-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
|
|
Prints a JSON version of a highlighting style, which can be modified,
|
|
saved with a \f[CR].theme\f[R] extension, and used with
|
|
\f[CR]\-\-syntax\-highlighting\f[R].
|
|
This option may be used with \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] to
|
|
redirect output to a file, but \f[CR]\-o\f[R]/\f[CR]\-\-output\f[R] must
|
|
come before \f[CR]\-\-print\-highlight\-style\f[R] on the command line.
|
|
.TP
|
|
\f[CR]\-\-syntax\-definition=\f[R]\f[I]FILE\f[R]
|
|
Instructs pandoc to load a KDE XML syntax definition file, which will be
|
|
used for syntax highlighting of appropriately marked code blocks.
|
|
This can be used to add support for new languages or to use altered
|
|
syntax definitions for existing languages.
|
|
This option may be repeated to add multiple syntax definitions.
|
|
.TP
|
|
\f[CR]\-H\f[R] \f[I]FILE\f[R], \f[CR]\-\-include\-in\-header=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
|
|
Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.
|
|
This can be used, for example, to include special CSS or JavaScript in
|
|
HTML documents.
|
|
This option can be used repeatedly to include multiple files in the
|
|
header.
|
|
They will be included in the order specified.
|
|
Implies \f[CR]\-\-standalone\f[R].
|
|
.TP
|
|
\f[CR]\-B\f[R] \f[I]FILE\f[R], \f[CR]\-\-include\-before\-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
|
|
Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the
|
|
document body (e.g.\ after the \f[CR]<body>\f[R] tag in HTML, or the
|
|
\f[CR]\(rsbegin{document}\f[R] command in LaTeX).
|
|
This can be used to include navigation bars or banners in HTML
|
|
documents.
|
|
This option can be used repeatedly to include multiple files.
|
|
They will be included in the order specified.
|
|
Implies \f[CR]\-\-standalone\f[R].
|
|
Note that if the output format is \f[CR]odt\f[R], this file must be in
|
|
OpenDocument XML format suitable for insertion into the body of the
|
|
document, and if the output is \f[CR]docx\f[R], this file must be in
|
|
appropriate OpenXML format.
|
|
.TP
|
|
\f[CR]\-A\f[R] \f[I]FILE\f[R], \f[CR]\-\-include\-after\-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
|
|
Include contents of \f[I]FILE\f[R], verbatim, at the end of the document
|
|
body (before the \f[CR]</body>\f[R] tag in HTML, or the
|
|
\f[CR]\(rsend{document}\f[R] command in LaTeX).
|
|
This option can be used repeatedly to include multiple files.
|
|
They will be included in the order specified.
|
|
Implies \f[CR]\-\-standalone\f[R].
|
|
Note that if the output format is \f[CR]odt\f[R], this file must be in
|
|
OpenDocument XML format suitable for insertion into the body of the
|
|
document, and if the output is \f[CR]docx\f[R], this file must be in
|
|
appropriate OpenXML format.
|
|
.TP
|
|
\f[CR]\-\-resource\-path=\f[R]\f[I]SEARCHPATH\f[R]
|
|
List of paths to search for images and other resources.
|
|
The paths should be separated by \f[CR]:\f[R] on Linux, UNIX, and macOS
|
|
systems, and by \f[CR];\f[R] on Windows.
|
|
If \f[CR]\-\-resource\-path\f[R] is not specified, the default resource
|
|
path is the working directory.
|
|
Note that, if \f[CR]\-\-resource\-path\f[R] is specified, the working
|
|
directory must be explicitly listed or it will not be searched.
|
|
For example: \f[CR]\-\-resource\-path=.:test\f[R] will search the
|
|
working directory and the \f[CR]test\f[R] subdirectory, in that order.
|
|
This option can be used repeatedly.
|
|
Search path components that come later on the command line will be
|
|
searched before those that come earlier, so
|
|
\f[CR]\-\-resource\-path foo:bar \-\-resource\-path baz:bim\f[R] is
|
|
equivalent to \f[CR]\-\-resource\-path baz:bim:foo:bar\f[R].
|
|
Note that this option only has an effect when pandoc itself needs to
|
|
find an image (e.g., in producing a PDF or docx, or when
|
|
\f[CR]\-\-embed\-resources\f[R] is used.)
|
|
It will not cause image paths to be rewritten in other cases (e.g., when
|
|
pandoc is generating LaTeX or HTML).
|
|
.TP
|
|
\f[CR]\-\-request\-header=\f[R]\f[I]NAME\f[R]\f[CR]:\f[R]\f[I]VAL\f[R]
|
|
Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
|
|
making HTTP requests (for example, when a URL is given on the command
|
|
line, or when resources used in a document must be downloaded).
|
|
If you\(cqre behind a proxy, you also need to set the environment
|
|
variable \f[CR]http_proxy\f[R] to \f[CR]http://...\f[R].
|
|
.TP
|
|
\f[CR]\-\-no\-check\-certificate[=true|false]\f[R]
|
|
Disable the certificate verification to allow access to unsecure HTTP
|
|
resources (for example when the certificate is no longer valid or self
|
|
signed).
|
|
.SS Options affecting specific writers
|
|
.TP
|
|
\f[CR]\-\-self\-contained[=true|false]\f[R]
|
|
\f[I]Deprecated synonym for
|
|
\f[CI]\-\-embed\-resources \-\-standalone\f[I].\f[R]
|
|
.TP
|
|
\f[CR]\-\-embed\-resources[=true|false]\f[R]
|
|
Produce a standalone HTML file with no external dependencies, using
|
|
\f[CR]data:\f[R] URIs to incorporate the contents of linked scripts,
|
|
stylesheets, images, and videos.
|
|
The resulting file should be \(lqself\-contained,\(rq in the sense that
|
|
it needs no external files and no net access to be displayed properly by
|
|
a browser.
|
|
This option works only with HTML output formats, including
|
|
\f[CR]html4\f[R], \f[CR]html5\f[R], \f[CR]html+lhs\f[R],
|
|
\f[CR]html5+lhs\f[R], \f[CR]s5\f[R], \f[CR]slidy\f[R],
|
|
\f[CR]slideous\f[R], \f[CR]dzslides\f[R], and \f[CR]revealjs\f[R].
|
|
Scripts, images, and stylesheets at absolute URLs will be downloaded;
|
|
those at relative URLs will be sought relative to the working directory
|
|
(if the first source file is local) or relative to the base URL (if the
|
|
first source file is remote).
|
|
Elements with the attribute \f[CR]data\-external=\(dq1\(dq\f[R] will be
|
|
left alone; the documents they link to will not be incorporated in the
|
|
document.
|
|
Limitation: resources that are loaded dynamically through JavaScript
|
|
cannot be incorporated; as a result, fonts may be missing when
|
|
\f[CR]\-\-mathjax\f[R] is used, and some advanced features (e.g.\ zoom
|
|
or speaker notes) may not work in an offline \(lqself\-contained\(rq
|
|
\f[CR]reveal.js\f[R] slide show.
|
|
.RS
|
|
.PP
|
|
For SVG images, \f[CR]img\f[R] tags with \f[CR]data:\f[R] URIs are used,
|
|
unless the image has the class \f[CR]inline\-svg\f[R], in which case an
|
|
inline SVG element is inserted.
|
|
This approach is recommended when there are many occurrences of the same
|
|
SVG in a document, as \f[CR]<use>\f[R] elements will be used to reduce
|
|
duplication.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-link\-images[=true|false]\f[R]
|
|
Include links to images instead of embedding the images in ODT.
|
|
(This option currently only affects ODT output.)
|
|
.TP
|
|
\f[CR]\-\-html\-q\-tags[=true|false]\f[R]
|
|
Use \f[CR]<q>\f[R] tags for quotes in HTML.
|
|
(This option only has an effect if the \f[CR]smart\f[R] extension is
|
|
enabled for the input format used.)
|
|
.TP
|
|
\f[CR]\-\-ascii[=true|false]\f[R]
|
|
Use only ASCII characters in output.
|
|
Currently supported for XML and HTML formats (which use entities instead
|
|
of UTF\-8 when this option is selected), CommonMark, gfm, and Markdown
|
|
(which use entities), roff man and ms (which use hexadecimal escapes),
|
|
and to a limited degree LaTeX (which uses standard commands for accented
|
|
characters when possible).
|
|
.TP
|
|
\f[CR]\-\-reference\-links[=true|false]\f[R]
|
|
Use reference\-style links, rather than inline links, in writing
|
|
Markdown or reStructuredText.
|
|
By default inline links are used.
|
|
The placement of link references is affected by the
|
|
\f[CR]\-\-reference\-location\f[R] option.
|
|
.TP
|
|
\f[CR]\-\-reference\-location=block\f[R]|\f[CR]section\f[R]|\f[CR]document\f[R]
|
|
Specify whether footnotes (and references, if
|
|
\f[CR]reference\-links\f[R] is set) are placed at the end of the current
|
|
(top\-level) block, the current section, or the document.
|
|
The default is \f[CR]document\f[R].
|
|
Currently this option only affects the \f[CR]markdown\f[R],
|
|
\f[CR]muse\f[R], \f[CR]html\f[R], \f[CR]epub\f[R], \f[CR]slidy\f[R],
|
|
\f[CR]s5\f[R], \f[CR]slideous\f[R], \f[CR]dzslides\f[R], and
|
|
\f[CR]revealjs\f[R] writers.
|
|
In slide formats, specifying \f[CR]\-\-reference\-location=section\f[R]
|
|
will cause notes to be rendered at the bottom of a slide.
|
|
.TP
|
|
\f[CR]\-\-figure\-caption\-position=above\f[R]|\f[CR]below\f[R]
|
|
Specify whether figure captions go above or below figures (default is
|
|
\f[CR]below\f[R]).
|
|
This option only affects HTML, LaTeX, Docx, ODT, and Typst output.
|
|
.TP
|
|
\f[CR]\-\-table\-caption\-position=above\f[R]|\f[CR]below\f[R]
|
|
Specify whether table captions go above or below tables (default is
|
|
\f[CR]above\f[R]).
|
|
This option only affects HTML, LaTeX, Docx, ODT, and Typst output.
|
|
.TP
|
|
\f[CR]\-\-markdown\-headings=setext\f[R]|\f[CR]atx\f[R]
|
|
Specify whether to use ATX\-style (\f[CR]#\f[R]\-prefixed) or
|
|
Setext\-style (underlined) headings for level 1 and 2 headings in
|
|
Markdown output.
|
|
(The default is \f[CR]atx\f[R].)
|
|
ATX\-style headings are always used for levels 3+.
|
|
This option also affects Markdown cells in \f[CR]ipynb\f[R] output.
|
|
.TP
|
|
\f[CR]\-\-list\-tables[=true|false]\f[R]
|
|
Render tables as list tables in RST output.
|
|
.TP
|
|
\f[CR]\-\-top\-level\-division=default\f[R]|\f[CR]section\f[R]|\f[CR]chapter\f[R]|\f[CR]part\f[R]
|
|
Treat top\-level headings as the given division type in LaTeX, ConTeXt,
|
|
DocBook, and TEI output.
|
|
The hierarchy order is part, chapter, then section; all headings are
|
|
shifted such that the top\-level heading becomes the specified type.
|
|
The default behavior is to determine the best division type via
|
|
heuristics: unless other conditions apply, \f[CR]section\f[R] is chosen.
|
|
When the \f[CR]documentclass\f[R] variable is set to \f[CR]report\f[R],
|
|
\f[CR]book\f[R], or \f[CR]memoir\f[R] (unless the \f[CR]article\f[R]
|
|
option is specified), \f[CR]chapter\f[R] is implied as the setting for
|
|
this option.
|
|
If \f[CR]beamer\f[R] is the output format, specifying either
|
|
\f[CR]chapter\f[R] or \f[CR]part\f[R] will cause top\-level headings to
|
|
become \f[CR]\(rspart{..}\f[R], while second\-level headings remain as
|
|
their default type.
|
|
.RS
|
|
.PP
|
|
In Docx output, this option adds section breaks before first\-level
|
|
headings if \f[CR]chapter\f[R] is selected, and before first\- and
|
|
second\-level headings if \f[CR]part\f[R] is selected.
|
|
Footnote numbers will restart with each section break unless the
|
|
reference doc modifies this.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-N\f[R], \f[CR]\-\-number\-sections=[true|false]\f[R]
|
|
Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB
|
|
output.
|
|
By default, sections are not numbered.
|
|
Sections with class \f[CR]unnumbered\f[R] will never be numbered, even
|
|
if \f[CR]\-\-number\-sections\f[R] is specified.
|
|
.TP
|
|
\f[CR]\-\-number\-offset=\f[R]\f[I]NUMBER\f[R][\f[CR],\f[R]\f[I]NUMBER\f[R]\f[CR],\f[R]\f[I]\&...\f[R]]
|
|
Offsets for section heading numbers.
|
|
The first number is added to the section number for level\-1 headings,
|
|
the second for level\-2 headings, and so on.
|
|
So, for example, if you want the first level\-1 heading in your document
|
|
to be numbered \(lq6\(rq instead of \(lq1\(rq, specify
|
|
\f[CR]\-\-number\-offset=5\f[R].
|
|
If your document starts with a level\-2 heading which you want to be
|
|
numbered \(lq1.5\(rq, specify \f[CR]\-\-number\-offset=1,4\f[R].
|
|
\f[CR]\-\-number\-offset\f[R] only directly affects the number of the
|
|
first section heading in a document; subsequent numbers increment in the
|
|
normal way.
|
|
Implies \f[CR]\-\-number\-sections\f[R].
|
|
Currently this feature only affects HTML and Docx output.
|
|
.TP
|
|
\f[CR]\-\-listings[=true|false]\f[R]
|
|
*Deprecated, use \f[CR]\-\-syntax\-highlighting=idiomatic\f[R] or
|
|
\f[CR]\-\-syntax\-highlighting=default\f[R] instead.
|
|
.RS
|
|
.PP
|
|
Use the \f[CR]listings\f[R] package for LaTeX code blocks.
|
|
The package does not support multi\-byte encoding for source code.
|
|
To handle UTF\-8 you would need to use a custom template.
|
|
This issue is fully documented here: Encoding issue with the listings
|
|
package.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-i\f[R], \f[CR]\-\-incremental[=true|false]\f[R]
|
|
Make list items in slide shows display incrementally (one by one).
|
|
The default is for lists to be displayed all at once.
|
|
.TP
|
|
\f[CR]\-\-slide\-level=\f[R]\f[I]NUMBER\f[R]
|
|
Specifies that headings with the specified level create slides (for
|
|
\f[CR]beamer\f[R], \f[CR]revealjs\f[R], \f[CR]pptx\f[R], \f[CR]s5\f[R],
|
|
\f[CR]slidy\f[R], \f[CR]slideous\f[R], \f[CR]dzslides\f[R]).
|
|
Headings above this level in the hierarchy are used to divide the slide
|
|
show into sections; headings below this level create subheads within a
|
|
slide.
|
|
Valid values are 0\-6.
|
|
If a slide level of 0 is specified, slides will not be split
|
|
automatically on headings, and horizontal rules must be used to indicate
|
|
slide boundaries.
|
|
If a slide level is not specified explicitly, the slide level will be
|
|
set automatically based on the contents of the document; see Structuring
|
|
the slide show.
|
|
.TP
|
|
\f[CR]\-\-section\-divs[=true|false]\f[R]
|
|
Wrap sections in \f[CR]<section>\f[R] tags (or \f[CR]<div>\f[R] tags for
|
|
\f[CR]html4\f[R]), and attach identifiers to the enclosing
|
|
\f[CR]<section>\f[R] (or \f[CR]<div>\f[R]) rather than the heading
|
|
itself (see Heading identifiers, below).
|
|
This option only affects HTML output (and does not affect HTML slide
|
|
formats).
|
|
.TP
|
|
\f[CR]\-\-email\-obfuscation=none\f[R]|\f[CR]javascript\f[R]|\f[CR]references\f[R]
|
|
Specify a method for obfuscating \f[CR]mailto:\f[R] links in HTML
|
|
documents.
|
|
\f[CR]none\f[R] leaves \f[CR]mailto:\f[R] links as they are.
|
|
\f[CR]javascript\f[R] obfuscates them using JavaScript.
|
|
\f[CR]references\f[R] obfuscates them by printing their letters as
|
|
decimal or hexadecimal character references.
|
|
The default is \f[CR]none\f[R].
|
|
.TP
|
|
\f[CR]\-\-id\-prefix=\f[R]\f[I]STRING\f[R]
|
|
Specify a prefix to be added to all identifiers and internal links in
|
|
HTML and DocBook output, and to footnote numbers in Markdown and Haddock
|
|
output.
|
|
This is useful for preventing duplicate identifiers when generating
|
|
fragments to be included in other pages.
|
|
.TP
|
|
\f[CR]\-T\f[R] \f[I]STRING\f[R], \f[CR]\-\-title\-prefix=\f[R]\f[I]STRING\f[R]
|
|
Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that
|
|
appears in the HTML header (but not in the title as it appears at the
|
|
beginning of the HTML body).
|
|
Implies \f[CR]\-\-standalone\f[R].
|
|
.TP
|
|
\f[CR]\-c\f[R] \f[I]URL\f[R], \f[CR]\-\-css=\f[R]\f[I]URL\f[R]
|
|
Link to a CSS style sheet.
|
|
This option can be used repeatedly to include multiple files.
|
|
They will be included in the order specified.
|
|
This option only affects HTML (including HTML slide shows) and EPUB
|
|
output.
|
|
It should be used together with \f[CR]\-s/\-\-standalone\f[R], because
|
|
the link to the stylesheet goes in the document header.
|
|
.RS
|
|
.PP
|
|
A stylesheet is required for generating EPUB.
|
|
If none is provided using this option (or the \f[CR]css\f[R] or
|
|
\f[CR]stylesheet\f[R] metadata fields), pandoc will look for a file
|
|
\f[CR]epub.css\f[R] in the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R]).
|
|
If it is not found there, sensible defaults will be used.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-reference\-doc=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
|
|
Use the specified file as a style reference in producing a docx or ODT
|
|
file.
|
|
.RS
|
|
.TP
|
|
Docx
|
|
For best results, the reference docx should be a modified version of a
|
|
docx file produced using pandoc.
|
|
The contents of the reference docx are ignored, but its stylesheets and
|
|
document properties (including margins, page size, header, and footer)
|
|
are used in the new docx.
|
|
If no reference docx is specified on the command line, pandoc will look
|
|
for a file \f[CR]reference.docx\f[R] in the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R]).
|
|
If this is not found either, sensible defaults will be used.
|
|
.RS
|
|
.PP
|
|
To produce a custom \f[CR]reference.docx\f[R], first get a copy of the
|
|
default \f[CR]reference.docx\f[R]:
|
|
\f[CR]pandoc \-o custom\-reference.docx \-\-print\-default\-data\-file reference.docx\f[R].
|
|
Then open \f[CR]custom\-reference.docx\f[R] in Word or LibreOffice,
|
|
modify the styles as you wish, and save the file.
|
|
For best results, do not make changes to this file other than modifying
|
|
the styles used by pandoc:
|
|
.PP
|
|
Paragraph styles:
|
|
.IP \(bu 2
|
|
Normal
|
|
.IP \(bu 2
|
|
Body Text
|
|
.IP \(bu 2
|
|
First Paragraph
|
|
.IP \(bu 2
|
|
Compact
|
|
.IP \(bu 2
|
|
Title
|
|
.IP \(bu 2
|
|
Subtitle
|
|
.IP \(bu 2
|
|
Author
|
|
.IP \(bu 2
|
|
Date
|
|
.IP \(bu 2
|
|
Abstract
|
|
.IP \(bu 2
|
|
AbstractTitle
|
|
.IP \(bu 2
|
|
Bibliography
|
|
.IP \(bu 2
|
|
Heading 1
|
|
.IP \(bu 2
|
|
Heading 2
|
|
.IP \(bu 2
|
|
Heading 3
|
|
.IP \(bu 2
|
|
Heading 4
|
|
.IP \(bu 2
|
|
Heading 5
|
|
.IP \(bu 2
|
|
Heading 6
|
|
.IP \(bu 2
|
|
Heading 7
|
|
.IP \(bu 2
|
|
Heading 8
|
|
.IP \(bu 2
|
|
Heading 9
|
|
.IP \(bu 2
|
|
Block Text [for block quotes]
|
|
.IP \(bu 2
|
|
Footnote Block Text [for block quotes in footnotes]
|
|
.IP \(bu 2
|
|
Source Code
|
|
.IP \(bu 2
|
|
Footnote Text
|
|
.IP \(bu 2
|
|
Definition Term
|
|
.IP \(bu 2
|
|
Definition
|
|
.IP \(bu 2
|
|
Caption
|
|
.IP \(bu 2
|
|
Table Caption
|
|
.IP \(bu 2
|
|
Image Caption
|
|
.IP \(bu 2
|
|
Figure
|
|
.IP \(bu 2
|
|
Captioned Figure
|
|
.IP \(bu 2
|
|
TOC Heading
|
|
.PP
|
|
Character styles:
|
|
.IP \(bu 2
|
|
Default Paragraph Font
|
|
.IP \(bu 2
|
|
Verbatim Char
|
|
.IP \(bu 2
|
|
Footnote Reference
|
|
.IP \(bu 2
|
|
Hyperlink
|
|
.IP \(bu 2
|
|
Section Number
|
|
.PP
|
|
Table style:
|
|
.IP \(bu 2
|
|
Table
|
|
.RE
|
|
.TP
|
|
ODT
|
|
For best results, the reference ODT should be a modified version of an
|
|
ODT produced using pandoc.
|
|
The contents of the reference ODT are ignored, but its stylesheets are
|
|
used in the new ODT.
|
|
If no reference ODT is specified on the command line, pandoc will look
|
|
for a file \f[CR]reference.odt\f[R] in the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R]).
|
|
If this is not found either, sensible defaults will be used.
|
|
.RS
|
|
.PP
|
|
To produce a custom \f[CR]reference.odt\f[R], first get a copy of the
|
|
default \f[CR]reference.odt\f[R]:
|
|
\f[CR]pandoc \-o custom\-reference.odt \-\-print\-default\-data\-file reference.odt\f[R].
|
|
Then open \f[CR]custom\-reference.odt\f[R] in LibreOffice, modify the
|
|
styles as you wish, and save the file.
|
|
.RE
|
|
.TP
|
|
PowerPoint
|
|
Templates included with Microsoft PowerPoint 2013 (either with
|
|
\f[CR].pptx\f[R] or \f[CR].potx\f[R] extension) are known to work, as
|
|
are most templates derived from these.
|
|
.RS
|
|
.PP
|
|
The specific requirement is that the template should contain layouts
|
|
with the following names (as seen within PowerPoint):
|
|
.IP \(bu 2
|
|
Title Slide
|
|
.IP \(bu 2
|
|
Title and Content
|
|
.IP \(bu 2
|
|
Section Header
|
|
.IP \(bu 2
|
|
Two Content
|
|
.IP \(bu 2
|
|
Comparison
|
|
.IP \(bu 2
|
|
Content with Caption
|
|
.IP \(bu 2
|
|
Blank
|
|
.PP
|
|
For each name, the first layout found with that name will be used.
|
|
If no layout is found with one of the names, pandoc will output a
|
|
warning and use the layout with that name from the default reference doc
|
|
instead.
|
|
(How these layouts are used is described in PowerPoint layout choice.)
|
|
.PP
|
|
All templates included with a recent version of MS PowerPoint will fit
|
|
these criteria.
|
|
(You can click on \f[CR]Layout\f[R] under the \f[CR]Home\f[R] menu to
|
|
check.)
|
|
.PP
|
|
You can also modify the default \f[CR]reference.pptx\f[R]: first run
|
|
\f[CR]pandoc \-o custom\-reference.pptx \-\-print\-default\-data\-file reference.pptx\f[R],
|
|
and then modify \f[CR]custom\-reference.pptx\f[R] in MS PowerPoint
|
|
(pandoc will use the layouts with the names listed above).
|
|
.RE
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-split\-level=\f[R]\f[I]NUMBER\f[R]
|
|
Specify the heading level at which to split an EPUB or chunked HTML
|
|
document into separate files.
|
|
The default is to split into chapters at level\-1 headings.
|
|
In the case of EPUB, this option only affects the internal composition
|
|
of the EPUB, not the way chapters and sections are displayed to users.
|
|
Some readers may be slow if the chapter files are too large, so for
|
|
large documents with few level\-1 headings, one might want to use a
|
|
chapter level of 2 or 3.
|
|
For chunked HTML, this option determines how much content goes in each
|
|
\(lqchunk.\(rq
|
|
.TP
|
|
\f[CR]\-\-chunk\-template=\f[R]\f[I]PATHTEMPLATE\f[R]
|
|
Specify a template for the filenames in a \f[CR]chunkedhtml\f[R]
|
|
document.
|
|
In the template, \f[CR]%n\f[R] will be replaced by the chunk number
|
|
(padded with leading 0s to 3 digits), \f[CR]%s\f[R] with the section
|
|
number of the chunk, \f[CR]%h\f[R] with the heading text (with
|
|
formatting removed), \f[CR]%i\f[R] with the section identifier.
|
|
For example, \f[CR]section\-%s\-%i.html\f[R] might be resolved to
|
|
\f[CR]section\-1.1\-introduction.html\f[R].
|
|
The characters \f[CR]/\f[R] and \f[CR]\(rs\f[R] are not allowed in chunk
|
|
templates and will be ignored.
|
|
The default is \f[CR]%s\-%i.html\f[R].
|
|
.TP
|
|
\f[CR]\-\-epub\-chapter\-level=\f[R]\f[I]NUMBER\f[R]
|
|
\f[I]Deprecated synonym for \f[CI]\-\-split\-level\f[I].\f[R]
|
|
.TP
|
|
\f[CR]\-\-epub\-cover\-image=\f[R]\f[I]FILE\f[R]
|
|
Use the specified image as the EPUB cover.
|
|
It is recommended that the image be less than 1000px in width and
|
|
height.
|
|
Note that in a Markdown source document you can also specify
|
|
\f[CR]cover\-image\f[R] in a YAML metadata block (see EPUB Metadata,
|
|
below).
|
|
.TP
|
|
\f[CR]\-\-epub\-title\-page=true\f[R]|\f[CR]false\f[R]
|
|
Determines whether a the title page is included in the EPUB (default is
|
|
\f[CR]true\f[R]).
|
|
.TP
|
|
\f[CR]\-\-epub\-metadata=\f[R]\f[I]FILE\f[R]
|
|
Look in the specified XML file for metadata for the EPUB.
|
|
The file should contain a series of Dublin Core elements.
|
|
For example:
|
|
.RS
|
|
.IP
|
|
.EX
|
|
<dc:rights>Creative Commons</dc:rights>
|
|
<dc:language>es\-AR</dc:language>
|
|
.EE
|
|
.PP
|
|
By default, pandoc will include the following metadata elements:
|
|
\f[CR]<dc:title>\f[R] (from the document title), \f[CR]<dc:creator>\f[R]
|
|
(from the document authors), \f[CR]<dc:date>\f[R] (from the document
|
|
date, which should be in ISO 8601 format), \f[CR]<dc:language>\f[R]
|
|
(from the \f[CR]lang\f[R] variable, or, if is not set, the locale), and
|
|
\f[CR]<dc:identifier id=\(dqBookId\(dq>\f[R] (a randomly generated
|
|
UUID).
|
|
Any of these may be overridden by elements in the metadata file.
|
|
.PP
|
|
Note: if the source document is Markdown, a YAML metadata block in the
|
|
document can be used instead.
|
|
See below under EPUB Metadata.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-epub\-embed\-font=\f[R]\f[I]FILE\f[R]
|
|
Embed the specified font in the EPUB.
|
|
This option can be repeated to embed multiple fonts.
|
|
Wildcards can also be used: for example, \f[CR]DejaVuSans\-*.ttf\f[R].
|
|
However, if you use wildcards on the command line, be sure to escape
|
|
them or put the whole filename in single quotes, to prevent them from
|
|
being interpreted by the shell.
|
|
To use the embedded fonts, you will need to add declarations like the
|
|
following to your CSS (see \f[CR]\-\-css\f[R]):
|
|
.RS
|
|
.IP
|
|
.EX
|
|
\(atfont\-face {
|
|
font\-family: DejaVuSans;
|
|
font\-style: normal;
|
|
font\-weight: normal;
|
|
src:url(\(dq../fonts/DejaVuSans\-Regular.ttf\(dq);
|
|
}
|
|
\(atfont\-face {
|
|
font\-family: DejaVuSans;
|
|
font\-style: normal;
|
|
font\-weight: bold;
|
|
src:url(\(dq../fonts/DejaVuSans\-Bold.ttf\(dq);
|
|
}
|
|
\(atfont\-face {
|
|
font\-family: DejaVuSans;
|
|
font\-style: italic;
|
|
font\-weight: normal;
|
|
src:url(\(dq../fonts/DejaVuSans\-Oblique.ttf\(dq);
|
|
}
|
|
\(atfont\-face {
|
|
font\-family: DejaVuSans;
|
|
font\-style: italic;
|
|
font\-weight: bold;
|
|
src:url(\(dq../fonts/DejaVuSans\-BoldOblique.ttf\(dq);
|
|
}
|
|
body { font\-family: \(dqDejaVuSans\(dq; }
|
|
.EE
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-epub\-subdirectory=\f[R]\f[I]DIRNAME\f[R]
|
|
Specify the subdirectory in the OCF container that is to hold the
|
|
EPUB\-specific contents.
|
|
The default is \f[CR]EPUB\f[R].
|
|
To put the EPUB contents in the top level, use an empty string.
|
|
.TP
|
|
\f[CR]\-\-ipynb\-output=all|none|best\f[R]
|
|
Determines how ipynb output cells are treated.
|
|
\f[CR]all\f[R] means that all of the data formats included in the
|
|
original are preserved.
|
|
\f[CR]none\f[R] means that the contents of data cells are omitted.
|
|
\f[CR]best\f[R] causes pandoc to try to pick the richest data block in
|
|
each output cell that is compatible with the output format.
|
|
The default is \f[CR]best\f[R].
|
|
.TP
|
|
\f[CR]\-\-pdf\-engine=\f[R]\f[I]PROGRAM\f[R]
|
|
Use the specified engine when producing PDF output.
|
|
Valid values are \f[CR]pdflatex\f[R], \f[CR]lualatex\f[R],
|
|
\f[CR]xelatex\f[R], \f[CR]latexmk\f[R], \f[CR]tectonic\f[R],
|
|
\f[CR]wkhtmltopdf\f[R], \f[CR]weasyprint\f[R], \f[CR]pagedjs\-cli\f[R],
|
|
\f[CR]prince\f[R], \f[CR]context\f[R], \f[CR]groff\f[R],
|
|
\f[CR]pdfroff\f[R], and \f[CR]typst\f[R].
|
|
If the engine is not in your PATH, the full path of the engine may be
|
|
specified here.
|
|
If this option is not specified, pandoc uses the following defaults
|
|
depending on the output format specified using \f[CR]\-t/\-\-to\f[R]:
|
|
.RS
|
|
.IP \(bu 2
|
|
\f[CR]\-t latex\f[R] or none: \f[CR]pdflatex\f[R] (other options:
|
|
\f[CR]xelatex\f[R], \f[CR]lualatex\f[R], \f[CR]tectonic\f[R],
|
|
\f[CR]latexmk\f[R])
|
|
.IP \(bu 2
|
|
\f[CR]\-t context\f[R]: \f[CR]context\f[R]
|
|
.IP \(bu 2
|
|
\f[CR]\-t html\f[R]: \f[CR]weasyprint\f[R] (other options:
|
|
\f[CR]prince\f[R], \f[CR]wkhtmltopdf\f[R], \f[CR]pagedjs\-cli\f[R]; see
|
|
print\-css.rocks for a good introduction to PDF generation from
|
|
HTML/CSS)
|
|
.IP \(bu 2
|
|
\f[CR]\-t ms\f[R]: \f[CR]groff\f[R]
|
|
.IP \(bu 2
|
|
\f[CR]\-t typst\f[R]: \f[CR]typst\f[R]
|
|
.PP
|
|
This option is normally intended to be used when a PDF file is specified
|
|
as \f[CR]\-o/\-\-output\f[R].
|
|
However, it may still have an effect when other output formats are
|
|
requested.
|
|
For example, \f[CR]ms\f[R] output will include \f[CR].pdfhref\f[R]
|
|
macros only if a \f[CR]\-\-pdf\-engine\f[R] is selected, and the macros
|
|
will be differently encoded depending on whether \f[CR]groff\f[R] or
|
|
\f[CR]pdfroff\f[R] is specified.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-pdf\-engine\-opt=\f[R]\f[I]STRING\f[R]
|
|
Use the given string as a command\-line argument to the
|
|
\f[CR]pdf\-engine\f[R].
|
|
For example, to use a persistent directory \f[CR]foo\f[R] for
|
|
\f[CR]latexmk\f[R]\(cqs auxiliary files, use
|
|
\f[CR]\-\-pdf\-engine\-opt=\-outdir=foo\f[R].
|
|
Note that no check for duplicate options is done.
|
|
.SS Citation rendering
|
|
.TP
|
|
\f[CR]\-C\f[R], \f[CR]\-\-citeproc\f[R]
|
|
Process the citations in the file, replacing them with rendered
|
|
citations and adding a bibliography.
|
|
Citation processing will not take place unless bibliographic data is
|
|
supplied, either through an external file specified using the
|
|
\f[CR]\-\-bibliography\f[R] option or the \f[CR]bibliography\f[R] field
|
|
in metadata, or via a \f[CR]references\f[R] section in metadata
|
|
containing a list of citations in CSL YAML format with Markdown
|
|
formatting.
|
|
The style is controlled by a CSL stylesheet specified using the
|
|
\f[CR]\-\-csl\f[R] option or the \f[CR]csl\f[R] field in metadata.
|
|
(If no stylesheet is specified, the \f[CR]chicago\-author\-date\f[R]
|
|
style will be used by default.)
|
|
The citation processing transformation may be applied before or after
|
|
filters or Lua filters (see \f[CR]\-\-filter\f[R],
|
|
\f[CR]\-\-lua\-filter\f[R]): these transformations are applied in the
|
|
order they appear on the command line.
|
|
For more information, see the section on Citations.
|
|
.RS
|
|
.PP
|
|
Note: if this option is specified, the \f[CR]citations\f[R] extension
|
|
will be disabled automatically in the writer, to ensure that the
|
|
citeproc\-generated citations will be rendered instead of the
|
|
format\(cqs own citation syntax.
|
|
.RE
|
|
.TP
|
|
\f[CR]\-\-bibliography=\f[R]\f[I]FILE\f[R]
|
|
Set the \f[CR]bibliography\f[R] field in the document\(cqs metadata to
|
|
\f[I]FILE\f[R], overriding any value set in the metadata.
|
|
If you supply this argument multiple times, each \f[I]FILE\f[R] will be
|
|
added to bibliography.
|
|
If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.
|
|
If \f[I]FILE\f[R] is not found relative to the working directory, it
|
|
will be sought in the resource path (see \f[CR]\-\-resource\-path\f[R]).
|
|
.TP
|
|
\f[CR]\-\-csl=\f[R]\f[I]FILE\f[R]
|
|
Set the \f[CR]csl\f[R] field in the document\(cqs metadata to
|
|
\f[I]FILE\f[R], overriding any value set in the metadata.
|
|
(This is equivalent to \f[CR]\-\-metadata csl=FILE\f[R].)
|
|
If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.
|
|
If \f[I]FILE\f[R] is not found relative to the working directory, it
|
|
will be sought in the resource path (see \f[CR]\-\-resource\-path\f[R])
|
|
and finally in the \f[CR]csl\f[R] subdirectory of the pandoc user data
|
|
directory.
|
|
.TP
|
|
\f[CR]\-\-citation\-abbreviations=\f[R]\f[I]FILE\f[R]
|
|
Set the \f[CR]citation\-abbreviations\f[R] field in the document\(cqs
|
|
metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
|
|
(This is equivalent to
|
|
\f[CR]\-\-metadata citation\-abbreviations=FILE\f[R].)
|
|
If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.
|
|
If \f[I]FILE\f[R] is not found relative to the working directory, it
|
|
will be sought in the resource path (see \f[CR]\-\-resource\-path\f[R])
|
|
and finally in the \f[CR]csl\f[R] subdirectory of the pandoc user data
|
|
directory.
|
|
.TP
|
|
\f[CR]\-\-natbib\f[R]
|
|
Use \f[CR]natbib\f[R] for citations in LaTeX output.
|
|
This option is not for use with the \f[CR]\-\-citeproc\f[R] option or
|
|
with PDF output.
|
|
It is intended for use in producing a LaTeX file that can be processed
|
|
with \f[CR]bibtex\f[R].
|
|
.TP
|
|
\f[CR]\-\-biblatex\f[R]
|
|
Use \f[CR]biblatex\f[R] for citations in LaTeX output.
|
|
This option is not for use with the \f[CR]\-\-citeproc\f[R] option or
|
|
with PDF output.
|
|
It is intended for use in producing a LaTeX file that can be processed
|
|
with \f[CR]bibtex\f[R] or \f[CR]biber\f[R].
|
|
.SS Math rendering in HTML
|
|
The default is to render TeX math as far as possible using Unicode
|
|
characters.
|
|
Formulas are put inside a \f[CR]span\f[R] with
|
|
\f[CR]class=\(dqmath\(dq\f[R], so that they may be styled differently
|
|
from the surrounding text if needed.
|
|
However, this gives acceptable results only for basic math, usually you
|
|
will want to use \f[CR]\-\-mathjax\f[R] or another of the following
|
|
options.
|
|
.TP
|
|
\f[CR]\-\-mathjax\f[R][\f[CR]=\f[R]\f[I]URL\f[R]]
|
|
Use MathJax to display embedded TeX math in HTML output.
|
|
TeX math will be put between \f[CR]\(rs(...\(rs)\f[R] (for inline math)
|
|
or \f[CR]\(rs[...\(rs]\f[R] (for display math) and wrapped in
|
|
\f[CR]<span>\f[R] tags with class \f[CR]math\f[R].
|
|
Then the MathJax JavaScript will render it.
|
|
The \f[I]URL\f[R] should point to the \f[CR]MathJax.js\f[R] load script.
|
|
If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be
|
|
inserted.
|
|
.TP
|
|
\f[CR]\-\-mathml\f[R]
|
|
Convert TeX math to MathML (in \f[CR]epub3\f[R], \f[CR]docbook4\f[R],
|
|
\f[CR]docbook5\f[R], \f[CR]jats\f[R], \f[CR]html4\f[R] and
|
|
\f[CR]html5\f[R]).
|
|
This is the default in \f[CR]odt\f[R] output.
|
|
MathML is supported natively by the main web browsers and select e\-book
|
|
readers.
|
|
.TP
|
|
\f[CR]\-\-webtex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]]
|
|
Convert TeX formulas to \f[CR]<img>\f[R] tags that link to an external
|
|
script that converts formulas to images.
|
|
The formula will be URL\-encoded and concatenated with the URL provided.
|
|
For SVG images you can for example use
|
|
\f[CR]\-\-webtex https://latex.codecogs.com/svg.latex?\f[R].
|
|
If no URL is specified, the CodeCogs URL generating PNGs will be used
|
|
(\f[CR]https://latex.codecogs.com/png.latex?\f[R]).
|
|
Note: the \f[CR]\-\-webtex\f[R] option will affect Markdown output as
|
|
well as HTML, which is useful if you\(cqre targeting a version of
|
|
Markdown without native math support.
|
|
.TP
|
|
\f[CR]\-\-katex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]]
|
|
Use KaTeX to display embedded TeX math in HTML output.
|
|
The \f[I]URL\f[R] is the base URL for the KaTeX library.
|
|
That directory should contain a \f[CR]katex.min.js\f[R] and a
|
|
\f[CR]katex.min.css\f[R] file.
|
|
If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be
|
|
inserted.
|
|
.TP
|
|
\f[CR]\-\-gladtex\f[R]
|
|
Enclose TeX math in \f[CR]<eq>\f[R] tags in HTML output.
|
|
The resulting HTML can then be processed by GladTeX to produce SVG
|
|
images of the typeset formulas and an HTML file with these images
|
|
embedded.
|
|
.RS
|
|
.IP
|
|
.EX
|
|
pandoc \-s \-\-gladtex input.md \-o myfile.htex
|
|
gladtex \-d image_dir myfile.htex
|
|
# produces myfile.html and images in image_dir
|
|
.EE
|
|
.RE
|
|
.SS Options for wrapper scripts
|
|
.TP
|
|
\f[CR]\-\-dump\-args[=true|false]\f[R]
|
|
Print information about command\-line arguments to \f[I]stdout\f[R],
|
|
then exit.
|
|
This option is intended primarily for use in wrapper scripts.
|
|
The first line of output contains the name of the output file specified
|
|
with the \f[CR]\-o\f[R] option, or \f[CR]\-\f[R] (for \f[I]stdout\f[R])
|
|
if no output file was specified.
|
|
The remaining lines contain the command\-line arguments, one per line,
|
|
in the order they appear.
|
|
These do not include regular pandoc options and their arguments, but do
|
|
include any options appearing after a \f[CR]\-\-\f[R] separator at the
|
|
end of the line.
|
|
.TP
|
|
\f[CR]\-\-ignore\-args[=true|false]\f[R]
|
|
Ignore command\-line arguments (for use in wrapper scripts).
|
|
Regular pandoc options are not ignored.
|
|
Thus, for example,
|
|
.RS
|
|
.IP
|
|
.EX
|
|
pandoc \-\-ignore\-args \-o foo.html \-s foo.txt \-\- \-e latin1
|
|
.EE
|
|
.PP
|
|
is equivalent to
|
|
.IP
|
|
.EX
|
|
pandoc \-o foo.html \-s
|
|
.EE
|
|
.RE
|
|
.SH EXIT CODES
|
|
If pandoc completes successfully, it will return exit code 0.
|
|
Nonzero exit codes have the following meanings:
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
Code Error
|
|
\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
1 PandocIOError
|
|
3 PandocFailOnWarningError
|
|
4 PandocAppError
|
|
5 PandocTemplateError
|
|
6 PandocOptionError
|
|
21 PandocUnknownReaderError
|
|
22 PandocUnknownWriterError
|
|
23 PandocUnsupportedExtensionError
|
|
24 PandocCiteprocError
|
|
25 PandocBibliographyError
|
|
31 PandocEpubSubdirectoryError
|
|
43 PandocPDFError
|
|
44 PandocXMLError
|
|
47 PandocPDFProgramNotFoundError
|
|
61 PandocHttpError
|
|
62 PandocShouldNeverHappenError
|
|
63 PandocSomeError
|
|
64 PandocParseError
|
|
66 PandocMakePDFError
|
|
67 PandocSyntaxMapError
|
|
83 PandocFilterError
|
|
84 PandocLuaError
|
|
89 PandocNoScriptingEngine
|
|
91 PandocMacroLoop
|
|
92 PandocUTF8DecodingError
|
|
93 PandocIpynbDecodingError
|
|
94 PandocUnsupportedCharsetError
|
|
95 PandocInputNotTextError
|
|
97 PandocCouldNotFindDataFileError
|
|
98 PandocCouldNotFindMetadataFileError
|
|
99 PandocResourceNotFound
|
|
.EE
|
|
.RE
|
|
.SH DEFAULTS FILES
|
|
The \f[CR]\-\-defaults\f[R] option may be used to specify a package of
|
|
options, in the form of a YAML or JSON file.
|
|
Examples in this section will be given in YAML, but the equivalent forms
|
|
in JSON will also work.
|
|
.PP
|
|
Fields that are omitted will just have their regular default values.
|
|
So a defaults file can be as simple as one line:
|
|
.IP
|
|
.EX
|
|
verbosity\f[B]:\f[R] INFO
|
|
.EE
|
|
.PP
|
|
or in JSON:
|
|
.IP
|
|
.EX
|
|
{ \(dqverbosity\(dq: \(dqINFO\(dq }
|
|
.EE
|
|
.PP
|
|
In fields that expect a file path (or list of file paths), the following
|
|
syntax may be used to interpolate environment variables:
|
|
.IP
|
|
.EX
|
|
csl\f[B]:\f[R] ${HOME}/mycsldir/special.csl
|
|
.EE
|
|
.PP
|
|
\f[CR]${USERDATA}\f[R] may also be used; this will always resolve to the
|
|
user data directory that is current when the defaults file is parsed,
|
|
regardless of the setting of the environment variable
|
|
\f[CR]USERDATA\f[R].
|
|
.PP
|
|
\f[CR]${.}\f[R] will resolve to the directory containing the defaults
|
|
file itself.
|
|
This allows you to refer to resources contained in that directory:
|
|
.IP
|
|
.EX
|
|
epub\-cover\-image\f[B]:\f[R] ${.}/cover.jpg
|
|
epub\-metadata\f[B]:\f[R] ${.}/meta.xml
|
|
resource\-path\f[B]:\f[R]
|
|
\f[B]\-\f[R] .\f[I] # the working directory from which pandoc is run\f[R]
|
|
\f[B]\-\f[R] ${.}/images\f[I] # the images subdirectory of the directory\f[R]
|
|
\f[I] # containing this defaults file\f[R]
|
|
.EE
|
|
.PP
|
|
This environment variable interpolation syntax \f[I]only\f[R] works in
|
|
fields that expect file paths.
|
|
.PP
|
|
Defaults files can be placed in the \f[CR]defaults\f[R] subdirectory of
|
|
the user data directory and used from any directory.
|
|
For example, one could create a file specifying defaults for writing
|
|
letters, save it as \f[CR]letter.yaml\f[R] in the \f[CR]defaults\f[R]
|
|
subdirectory of the user data directory, and then invoke these defaults
|
|
from any directory using \f[CR]pandoc \-\-defaults letter\f[R] or
|
|
\f[CR]pandoc \-dletter\f[R].
|
|
.PP
|
|
When multiple defaults are used, their contents will be combined.
|
|
.PP
|
|
Note that, where command\-line arguments may be repeated
|
|
(\f[CR]\-\-metadata\-file\f[R], \f[CR]\-\-css\f[R],
|
|
\f[CR]\-\-include\-in\-header\f[R],
|
|
\f[CR]\-\-include\-before\-body\f[R],
|
|
\f[CR]\-\-include\-after\-body\f[R], \f[CR]\-\-variable\f[R],
|
|
\f[CR]\-\-metadata\f[R], \f[CR]\-\-syntax\-definition\f[R]), the values
|
|
specified on the command line will combine with values specified in the
|
|
defaults file, rather than replacing them.
|
|
.PP
|
|
The following tables show the mapping between the command line and
|
|
defaults file entries.
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
foo.md input\-file: foo.md
|
|
|
|
foo.md bar.md input\-files:
|
|
\- foo.md
|
|
\- bar.md
|
|
|
|
.EE
|
|
.RE
|
|
.PP
|
|
The value of \f[CR]input\-files\f[R] may be left empty to indicate input
|
|
from stdin, and it can be an empty sequence \f[CR][]\f[R] for no input.
|
|
.SS General options
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-from markdown+emoji from: markdown+emoji
|
|
|
|
reader: markdown+emoji
|
|
|
|
\-\-to markdown+hard_line_breaks to: markdown+hard_line_breaks
|
|
|
|
writer: markdown+hard_line_breaks
|
|
|
|
\-\-output foo.pdf output\-file: foo.pdf
|
|
|
|
\-\-output \- output\-file:
|
|
|
|
\-\-data\-dir dir data\-dir: dir
|
|
|
|
\-\-defaults file defaults:
|
|
\- file
|
|
|
|
\-\-verbose verbosity: INFO
|
|
|
|
\-\-quiet verbosity: ERROR
|
|
|
|
\-\-fail\-if\-warnings fail\-if\-warnings: true
|
|
|
|
\-\-sandbox sandbox: true
|
|
|
|
\-\-log=FILE log\-file: FILE
|
|
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Options specified in a defaults file itself always have priority over
|
|
those in another file included with a \f[CR]defaults:\f[R] entry.
|
|
.PP
|
|
\f[CR]verbosity\f[R] can have the values \f[CR]ERROR\f[R],
|
|
\f[CR]WARNING\f[R], or \f[CR]INFO\f[R].
|
|
.SS Reader options
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-shift\-heading\-level\-by \-1 shift\-heading\-level\-by: \-1
|
|
|
|
\-\-indented\-code\-classes python indented\-code\-classes:
|
|
\- python
|
|
|
|
\-\-default\-image\-extension \(dq.jpg\(dq default\-image\-extension: \(aq.jpg\(aq
|
|
|
|
\-\-file\-scope file\-scope: true
|
|
|
|
\-\-citeproc \(rs filters:
|
|
\-\-lua\-filter count\-words.lua \(rs \- citeproc
|
|
\-\-filter special.lua \- count\-words.lua
|
|
\- type: json
|
|
path: special.lua
|
|
|
|
\-\-metadata key=value \(rs metadata:
|
|
\-\-metadata key2 key: value
|
|
key2: true
|
|
|
|
\-\-metadata\-file meta.yaml metadata\-files:
|
|
\- meta.yaml
|
|
|
|
metadata\-file: meta.yaml
|
|
|
|
\-\-preserve\-tabs preserve\-tabs: true
|
|
|
|
\-\-tab\-stop 8 tab\-stop: 8
|
|
|
|
\-\-track\-changes accept track\-changes: accept
|
|
|
|
\-\-extract\-media dir extract\-media: dir
|
|
|
|
\-\-abbreviations abbrevs.txt abbreviations: abbrevs.txt
|
|
|
|
\-\-typst\-input foo=bar typst\-inputs:
|
|
foo: bar
|
|
|
|
\-\-trace trace: true
|
|
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Metadata values specified in a defaults file are parsed as literal
|
|
string text, not Markdown.
|
|
.PP
|
|
Filters will be assumed to be Lua filters if they have the
|
|
\f[CR].lua\f[R] extension, and JSON filters otherwise.
|
|
But the filter type can also be specified explicitly, as shown.
|
|
Filters are run in the order specified.
|
|
To include the built\-in citeproc filter, use either \f[CR]citeproc\f[R]
|
|
or \f[CR]{type: citeproc}\f[R].
|
|
.SS General writer options
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-standalone standalone: true
|
|
|
|
\-\-template letter template: letter
|
|
|
|
\-\-variable key=val \(rs variables:
|
|
\-\-variable key2 key: val
|
|
key2: true
|
|
|
|
\-\-eol nl eol: nl
|
|
|
|
\-\-dpi 300 dpi: 300
|
|
|
|
\-\-wrap preserve wrap: \(dqpreserve\(dq
|
|
|
|
\-\-columns 72 columns: 72
|
|
|
|
\-\-table\-of\-contents table\-of\-contents: true
|
|
|
|
\-\-toc toc: true
|
|
|
|
\-\-toc\-depth 3 toc\-depth: 3
|
|
|
|
\-\-strip\-comments strip\-comments: true
|
|
|
|
\-\-no\-highlight syntax\-highlighting: \(aqnone\(aq
|
|
|
|
\-\-syntax\-highlighting kate syntax\-highlighting: kate
|
|
|
|
\-\-syntax\-definition mylang.xml syntax\-definitions:
|
|
\- mylang.xml
|
|
|
|
syntax\-definition: mylang.xml
|
|
|
|
\-\-include\-in\-header inc.tex include\-in\-header:
|
|
\- inc.tex
|
|
|
|
\-\-include\-before\-body inc.tex include\-before\-body:
|
|
\- inc.tex
|
|
|
|
\-\-include\-after\-body inc.tex include\-after\-body:
|
|
\- inc.tex
|
|
|
|
\-\-resource\-path .:foo resource\-path: [\(aq.\(aq,\(aqfoo\(aq]
|
|
|
|
\-\-request\-header foo:bar request\-headers:
|
|
\- [\(dqUser\-Agent\(dq, \(dqMozilla/5.0\(dq]
|
|
|
|
\-\-no\-check\-certificate no\-check\-certificate: true
|
|
|
|
.EE
|
|
.RE
|
|
.SS Options affecting specific writers
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-self\-contained self\-contained: true
|
|
|
|
\-\-link\-images link\-images: true
|
|
|
|
\-\-html\-q\-tags html\-q\-tags: true
|
|
|
|
\-\-ascii ascii: true
|
|
|
|
\-\-reference\-links reference\-links: true
|
|
|
|
\-\-reference\-location block reference\-location: block
|
|
|
|
\-\-figure\-caption\-position=above figure\-caption\-position: above
|
|
|
|
\-\-table\-caption\-position=below table\-caption\-position: below
|
|
|
|
\-\-markdown\-headings atx markdown\-headings: atx
|
|
|
|
\-\-list\-tables list\-tables: true
|
|
|
|
\-\-top\-level\-division chapter top\-level\-division: chapter
|
|
|
|
\-\-number\-sections number\-sections: true
|
|
|
|
\-\-number\-offset=1,4 number\-offset: \(rs[1,4\(rs]
|
|
|
|
\-\-listings listings: true
|
|
|
|
\-\-list\-of\-figures list\-of\-figures: true
|
|
|
|
\-\-lof lof: true
|
|
|
|
\-\-list\-of\-tables list\-of\-tables: true
|
|
|
|
\-\-lot lot: true
|
|
|
|
\-\-incremental incremental: true
|
|
|
|
\-\-slide\-level 2 slide\-level: 2
|
|
|
|
\-\-section\-divs section\-divs: true
|
|
|
|
\-\-email\-obfuscation references email\-obfuscation: references
|
|
|
|
\-\-id\-prefix ch1 identifier\-prefix: ch1
|
|
|
|
\-\-title\-prefix MySite title\-prefix: MySite
|
|
|
|
\-\-css styles/screen.css \(rs css:
|
|
\-\-css styles/special.css \- styles/screen.css
|
|
\- styles/special.css
|
|
|
|
\-\-reference\-doc my.docx reference\-doc: my.docx
|
|
|
|
\-\-epub\-cover\-image cover.jpg epub\-cover\-image: cover.jpg
|
|
|
|
\-\-epub\-title\-page=false epub\-title\-page: false
|
|
|
|
\-\-epub\-metadata meta.xml epub\-metadata: meta.xml
|
|
|
|
\-\-epub\-embed\-font special.otf \(rs epub\-fonts:
|
|
\-\-epub\-embed\-font headline.otf \- special.otf
|
|
\- headline.otf
|
|
|
|
\-\-split\-level 2 split\-level: 2
|
|
|
|
\-\-chunk\-template=\(dq%i.html\(dq chunk\-template: \(dq%i.html\(dq
|
|
|
|
\-\-epub\-subdirectory=\(dq\(dq epub\-subdirectory: \(aq\(aq
|
|
|
|
\-\-ipynb\-output best ipynb\-output: best
|
|
|
|
\-\-pdf\-engine xelatex pdf\-engine: xelatex
|
|
|
|
\-\-pdf\-engine\-opt=\-\-shell\-escape pdf\-engine\-opts:
|
|
\- \(aq\-shell\-escape\(aq
|
|
|
|
pdf\-engine\-opt: \(aq\-shell\-escape\(aq
|
|
|
|
.EE
|
|
.RE
|
|
.SS Citation rendering
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-citeproc citeproc: true
|
|
|
|
\-\-bibliography logic.bib bibliography: logic.bib
|
|
|
|
\-\-csl ieee.csl csl: ieee.csl
|
|
|
|
\-\-citation\-abbreviations ab.json citation\-abbreviations: ab.json
|
|
|
|
\-\-natbib cite\-method: natbib
|
|
|
|
\-\-biblatex cite\-method: biblatex
|
|
|
|
.EE
|
|
.RE
|
|
.PP
|
|
\f[CR]cite\-method\f[R] can be \f[CR]citeproc\f[R], \f[CR]natbib\f[R],
|
|
or \f[CR]biblatex\f[R].
|
|
This only affects LaTeX output.
|
|
If you want to use citeproc to format citations, you should also set
|
|
`citeproc: true'.
|
|
.PP
|
|
If you need control over when the citeproc processing is done relative
|
|
to other filters, you should instead use \f[CR]citeproc\f[R] in the list
|
|
of \f[CR]filters\f[R] (see Reader options).
|
|
.SS Math rendering in HTML
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-mathjax html\-math\-method:
|
|
method: mathjax
|
|
|
|
\-\-mathml html\-math\-method:
|
|
method: mathml
|
|
|
|
\-\-webtex html\-math\-method:
|
|
method: webtex
|
|
|
|
\-\-katex html\-math\-method:
|
|
method: katex
|
|
|
|
\-\-gladtex html\-math\-method:
|
|
method: gladtex
|
|
|
|
.EE
|
|
.RE
|
|
.PP
|
|
In addition to the values listed above, \f[CR]method\f[R] can have the
|
|
value \f[CR]plain\f[R].
|
|
.PP
|
|
If the command line option accepts a URL argument, an \f[CR]url:\f[R]
|
|
field can be added to \f[CR]html\-math\-method:\f[R].
|
|
.SS Options for wrapper scripts
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
|
|
command line defaults file
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-dump\-args dump\-args: true
|
|
|
|
\-\-ignore\-args ignore\-args: true
|
|
|
|
.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]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\(cqs 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\(cqs 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 \(lqnested,\(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\(cqs 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 \(dqleftborder\(dq \(dqrightborder\(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 \(dqleftborder\(dq \(dqrightborder\(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 \(dqleftborder\(dq \(dqrightborder\(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
|
|
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, docx, and Typst.
|
|
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: \(aqThis is the title\(aq
|
|
subtitle: \(dqThis 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
|
|
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. [\(aqZitat 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
|
|
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.
|
|
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\(cqd 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 36em).
|
|
.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: |
|
|
<style>
|
|
blockquote {
|
|
font\-style: italic;
|
|
}
|
|
tr.even {
|
|
background\-color: #f0f0f0;
|
|
}
|
|
td, th {
|
|
padding: 0.5em 2em 0.5em 0.5em;
|
|
}
|
|
tbody {
|
|
border\-bottom: none;
|
|
}
|
|
</style>
|
|
\-\-\-
|
|
.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\(ha5\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.
|
|
.TP
|
|
\f[CR]highlightjs\-theme\f[R]
|
|
highlight.js theme for code highlighting when using
|
|
\f[CR]\-\-syntax\-highlighting=idiomatic\f[R] with reveal.js (defaults
|
|
to \f[CR]monokai\f[R]).
|
|
See the highlight.js demo page for available themes.
|
|
.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]\(rssetbeameroption{}\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]logooptions\f[R]
|
|
options for logo image (e.g., \f[CR]width\f[R], \f[CR]height\f[R])
|
|
.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 \(lqtitle 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 (e.g., \f[CR]width\f[R],
|
|
\f[CR]height\f[R])
|
|
.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]\(rsparagraph\f[R] and \f[CR]\(rssubparagraph\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]\(rssubsubsection\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: |
|
|
\(rsRedeclareSectionCommand[
|
|
beforeskip=\-10pt plus \-2pt minus \-1pt,
|
|
afterskip=1sp plus \-1sp minus 1sp,
|
|
font=\(rsnormalfont\(rsitshape]{paragraph}
|
|
\(rsRedeclareSectionCommand[
|
|
beforeskip=\-10pt plus \-2pt minus \-1pt,
|
|
afterskip=1sp plus \-1sp minus 1sp,
|
|
font=\(rsnormalfont\(rsscshape,
|
|
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]shorthands\f[R]
|
|
Enable language\-specific shorthands when loading \f[CR]babel\f[R].
|
|
(By default, pandoc includes \f[CR]shorthands=off\f[R] when loading
|
|
\f[CR]babel\f[R], disabling language\-specific shorthands.)
|
|
.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]\(rspagestyle{}\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)
|
|
.TP
|
|
\f[CR]csquotes\f[R]
|
|
load \f[CR]csquotes\f[R] package and use \f[CR]\(rsenquote\f[R] or
|
|
\f[CR]\(rsenquote*\f[R] for quoted text.
|
|
.TP
|
|
\f[CR]csquotesoptions\f[R]
|
|
options to use for \f[CR]csquotes\f[R] package (repeat for multiple
|
|
options).
|
|
.TP
|
|
\f[CR]babeloptions\f[R]
|
|
options to pass to the babel package (may be repeated for multiple
|
|
options).
|
|
This defaults to \f[CR]provide=*\f[R] if the main language isn\(cqt a
|
|
European language written with Latin or Cyrillic script or Vietnamese.
|
|
Most users will not need to adjust the default setting.
|
|
.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\(cqt 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:
|
|
\- \(dqFreeSans:\(dq
|
|
\- \(dqNotoColorEmoji:mode=harf\(dq
|
|
\&...
|
|
.EE
|
|
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: \(dqNoto Serif CJK TC\(dq
|
|
russian: \(dqNoto 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 Other
|
|
.TP
|
|
\f[CR]pdf\-trailer\-id\f[R]
|
|
the PDF trailer ID; must be two PDF byte strings if set, conventionally
|
|
with 16 bytes each.
|
|
E.g.,
|
|
\f[CR]<00112233445566778899aabbccddeeff> <00112233445566778899aabbccddeeff>\f[R].
|
|
.RS
|
|
See the section on reproducible builds.
|
|
.RE
|
|
.TP
|
|
\f[CR]pdfstandard\f[R]
|
|
PDF standard(s) for the document, e.g.\ \f[CR]ua\-2\f[R],
|
|
\f[CR]a\-4f\f[R].
|
|
Supports PDF/A, PDF/X, and PDF/UA variants.
|
|
Requires LuaLaTeX and LaTeX 2023+.
|
|
Repeat for multiple standards:
|
|
.RS
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
pdfstandard:
|
|
\- ua\-2
|
|
\- a\-4f
|
|
\&...
|
|
.EE
|
|
.RE
|
|
.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]\(rsdefinefallbackfamily\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\(rsletterpercent\(rsspace (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]template\f[R]
|
|
Typst template to use (relative path only).
|
|
.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.
|
|
.TP
|
|
\f[CR]thanks\f[R]
|
|
contents of acknowledgments footnote after document title
|
|
.TP
|
|
\f[CR]mathfont\f[R], \f[CR]codefont\f[R]
|
|
Name of system font to use for math and code, respectively.
|
|
.TP
|
|
\f[CR]linestretch\f[R]
|
|
adjusts line spacing, e.g.\ \f[CR]1.25\f[R], \f[CR]1.5\f[R]
|
|
.TP
|
|
\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R]
|
|
color for external links, internal links, and citation links,
|
|
respectively: expects a hexadecimal color code
|
|
.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 for RTF
|
|
.TP
|
|
\f[CR]fontsize\f[R]
|
|
font size for body text, e.g.\ \f[CR]12pt\f[R] or \f[CR]12.5pt\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\(cqs 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
|
|
Similarly, \f[CR]outputfile\f[R] can be \f[CR]\-\f[R] if output goes to
|
|
the terminal.
|
|
If you need absolute paths, use e.g.\ \f[CR]$curdir$/$sourcefile$\f[R].
|
|
.RE
|
|
.TP
|
|
\f[CR]pdf\-engine\f[R]
|
|
name of PDF engine if provided using \f[CR]\-\-pdf\-engine\f[R], or the
|
|
default engine for the format if PDF output is requested.
|
|
.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.
|
|
.PP
|
|
An extension can be enabled by adding \f[CR]+EXTENSION\f[R] to the
|
|
format name and disabled by adding \f[CR]\-EXTENSION\f[R].
|
|
For example, \f[CR]\-\-from markdown_strict+footnotes\f[R] is strict
|
|
Markdown with footnotes enabled, while
|
|
\f[CR]\-\-from markdown\-footnotes\-pipe_tables\f[R] is pandoc\(cqs
|
|
Markdown without footnotes or pipe tables.
|
|
.PP
|
|
The Markdown reader and writer make by far the most use of extensions.
|
|
Extensions only used by them are therefore covered in the section
|
|
Pandoc\(cqs Markdown below (see Markdown variants for
|
|
\f[CR]commonmark\f[R] and \f[CR]gfm\f[R]).
|
|
In the following, extensions that also work for other formats are
|
|
covered.
|
|
.PP
|
|
Note that Markdown extensions added to the \f[CR]ipynb\f[R] format
|
|
affect Markdown cells in Jupyter notebooks (as do command\-line options
|
|
like \f[CR]\-\-markdown\-headings\f[R]).
|
|
.SS Typography
|
|
.SS Extension: \f[CR]smart\f[R]
|
|
Interpret straight quotes as curly quotes, \f[CR]\-\-\-\f[R] as
|
|
em\-dashes, \f[CR]\-\-\f[R] as en\-dashes, and \f[CR]...\f[R] as
|
|
ellipses.
|
|
Nonbreaking spaces are inserted after certain abbreviations, such as
|
|
\(lqMr.\(rq
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
input formats
|
|
\f[CR]markdown\f[R], \f[CR]commonmark\f[R], \f[CR]latex\f[R],
|
|
\f[CR]mediawiki\f[R], \f[CR]org\f[R], \f[CR]rst\f[R], \f[CR]twiki\f[R],
|
|
\f[CR]html\f[R]
|
|
.TP
|
|
output formats
|
|
\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R],
|
|
\f[CR]org\f[R], \f[CR]rst\f[R]
|
|
.TP
|
|
enabled by default in
|
|
\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R] (both input
|
|
and output)
|
|
.PP
|
|
Note: If you are \f[I]writing\f[R] Markdown, then the \f[CR]smart\f[R]
|
|
extension has the reverse effect: what would have been curly quotes
|
|
comes out straight.
|
|
.PP
|
|
In LaTeX, \f[CR]smart\f[R] means to use the standard TeX ligatures for
|
|
quotation marks (\f[CR]\(ga\(ga\f[R] and \f[CR]\(aq\(aq\f[R] for double
|
|
quotes, \f[CR]\(ga\f[R] and \f[CR]\(aq\f[R] for single quotes) and
|
|
dashes (\f[CR]\-\-\f[R] for en\-dash and \f[CR]\-\-\-\f[R] for
|
|
em\-dash).
|
|
If \f[CR]smart\f[R] is disabled, then in reading LaTeX pandoc will parse
|
|
these characters literally.
|
|
In writing LaTeX, enabling \f[CR]smart\f[R] tells pandoc to use the
|
|
ligatures when possible; if \f[CR]smart\f[R] is disabled pandoc will use
|
|
unicode quotation mark and dash characters.
|
|
.SS Headings and sections
|
|
.SS Extension: \f[CR]auto_identifiers\f[R]
|
|
A heading without an explicitly specified identifier will be
|
|
automatically assigned a unique identifier based on the heading text.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
input formats
|
|
\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]rst\f[R],
|
|
\f[CR]mediawiki\f[R], \f[CR]textile\f[R], \f[CR]man\f[R],
|
|
\f[CR]typst\f[R]
|
|
.TP
|
|
output formats
|
|
\f[CR]markdown\f[R], \f[CR]muse\f[R]
|
|
.TP
|
|
enabled by default in
|
|
\f[CR]markdown\f[R], \f[CR]muse\f[R], \f[CR]man\f[R]
|
|
.PP
|
|
The default algorithm used to derive the identifier from the heading
|
|
text is:
|
|
.IP \(bu 2
|
|
Remove all formatting, links, etc.
|
|
.IP \(bu 2
|
|
Remove all footnotes.
|
|
.IP \(bu 2
|
|
Remove all non\-alphanumeric characters, except underscores, hyphens,
|
|
and periods.
|
|
.IP \(bu 2
|
|
Replace all spaces and newlines with hyphens.
|
|
.IP \(bu 2
|
|
Convert all alphabetic characters to lowercase.
|
|
.IP \(bu 2
|
|
Remove everything up to the first letter (identifiers may not begin with
|
|
a number or punctuation mark).
|
|
.IP \(bu 2
|
|
If nothing is left after this, use the identifier \f[CR]section\f[R].
|
|
.PP
|
|
Thus, for example,
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
Heading Identifier
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
Heading identifiers in HTML heading\-identifiers\-in\-html
|
|
Maître d\(aqhôtel maître\-dhôtel
|
|
*Dogs*?\-\-in *my* house? dogs\-\-in\-my\-house
|
|
[HTML], [S5], or [RTF]? html\-s5\-or\-rtf
|
|
3. Applications applications
|
|
33 section
|
|
.EE
|
|
.RE
|
|
.PP
|
|
These rules should, in most cases, allow one to determine the identifier
|
|
from the heading text.
|
|
The exception is when several headings have the same text; in this case,
|
|
the first will get an identifier as described above; the second will get
|
|
the same identifier with \f[CR]\-1\f[R] appended; the third with
|
|
\f[CR]\-2\f[R]; and so on.
|
|
.PP
|
|
(However, a different algorithm is used if
|
|
\f[CR]gfm_auto_identifiers\f[R] is enabled; see below.)
|
|
.PP
|
|
These identifiers are used to provide link targets in the table of
|
|
contents generated by the \f[CR]\-\-toc|\-\-table\-of\-contents\f[R]
|
|
option.
|
|
They also make it easy to provide links from one section of a document
|
|
to another.
|
|
A link to this section, for example, might look like this:
|
|
.IP
|
|
.EX
|
|
See the section on
|
|
[heading identifiers](#heading\-identifiers\-in\-html\-latex\-and\-context).
|
|
.EE
|
|
.PP
|
|
Note, however, that this method of providing links to sections works
|
|
only in HTML, LaTeX, and ConTeXt formats.
|
|
.PP
|
|
If the \f[CR]\-\-section\-divs\f[R] option is specified, then each
|
|
section will be wrapped in a \f[CR]section\f[R] (or a \f[CR]div\f[R], if
|
|
\f[CR]html4\f[R] was specified), and the identifier will be attached to
|
|
the enclosing \f[CR]<section>\f[R] (or \f[CR]<div>\f[R]) tag rather than
|
|
the heading itself.
|
|
This allows entire sections to be manipulated using JavaScript or
|
|
treated differently in CSS.
|
|
.SS Extension: \f[CR]ascii_identifiers\f[R]
|
|
Causes the identifiers produced by \f[CR]auto_identifiers\f[R] to be
|
|
pure ASCII.
|
|
Accents are stripped off of accented Latin letters, and non\-Latin
|
|
letters are omitted.
|
|
.SS Extension: \f[CR]gfm_auto_identifiers\f[R]
|
|
Changes the algorithm used by \f[CR]auto_identifiers\f[R] to conform to
|
|
GitHub\(cqs method.
|
|
Spaces are converted to dashes (\f[CR]\-\f[R]), uppercase characters to
|
|
lowercase characters, and punctuation characters other than
|
|
\f[CR]\-\f[R] and \f[CR]_\f[R] are removed.
|
|
Emojis are replaced by their names.
|
|
.SS Math Input
|
|
The extensions \f[CR]tex_math_dollars\f[R], \f[CR]tex_math_gfm\f[R],
|
|
\f[CR]tex_math_single_backslash\f[R], and
|
|
\f[CR]tex_math_double_backslash\f[R] are described in the section about
|
|
Pandoc\(cqs Markdown.
|
|
.PP
|
|
However, they can also be used with HTML input.
|
|
This is handy for reading web pages formatted using MathJax, for
|
|
example.
|
|
.SS Raw HTML/TeX
|
|
The following extensions are described in more detail in their
|
|
respective sections of Pandoc\(cqs Markdown:
|
|
.IP \(bu 2
|
|
\f[CR]raw_html\f[R] allows HTML elements which are not representable in
|
|
pandoc\(cqs AST to be parsed as raw HTML.
|
|
By default, this is disabled for HTML input.
|
|
.IP \(bu 2
|
|
\f[CR]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in
|
|
a document.
|
|
This extension can be enabled/disabled for the following formats (in
|
|
addition to \f[CR]markdown\f[R]):
|
|
.RS 2
|
|
.TP
|
|
input formats
|
|
\f[CR]latex\f[R], \f[CR]textile\f[R], \f[CR]html\f[R] (environments,
|
|
\f[CR]\(rsref\f[R], and \f[CR]\(rseqref\f[R] only), \f[CR]ipynb\f[R]
|
|
.TP
|
|
output formats
|
|
\f[CR]textile\f[R], \f[CR]commonmark\f[R]
|
|
.PP
|
|
Note: as applied to \f[CR]ipynb\f[R], \f[CR]raw_html\f[R] and
|
|
\f[CR]raw_tex\f[R] affect not only raw TeX in Markdown cells, but data
|
|
with mime type \f[CR]text/html\f[R] in output cells.
|
|
Since the \f[CR]ipynb\f[R] reader attempts to preserve the richest
|
|
possible outputs when several options are given, you will get best
|
|
results if you disable \f[CR]raw_html\f[R] and \f[CR]raw_tex\f[R] when
|
|
converting to formats like \f[CR]docx\f[R] which don\(cqt allow raw
|
|
\f[CR]html\f[R] or \f[CR]tex\f[R].
|
|
.RE
|
|
.IP \(bu 2
|
|
\f[CR]native_divs\f[R] causes HTML \f[CR]div\f[R] elements to be parsed
|
|
as native pandoc Div blocks.
|
|
If you want them to be parsed as raw HTML, use
|
|
\f[CR]\-f html\-native_divs+raw_html\f[R].
|
|
.IP \(bu 2
|
|
\f[CR]native_spans\f[R] causes HTML \f[CR]span\f[R] elements to be
|
|
parsed as native pandoc Span inlines.
|
|
If you want them to be parsed as raw HTML, use
|
|
\f[CR]\-f html\-native_spans+raw_html\f[R].
|
|
If you want to drop all \f[CR]div\f[R]s and \f[CR]span\f[R]s when
|
|
converting HTML to Markdown, you can use
|
|
\f[CR]pandoc \-f html\-native_divs\-native_spans \-t markdown\f[R].
|
|
.SS Literate Haskell support
|
|
.SS Extension: \f[CR]literate_haskell\f[R]
|
|
Treat the document as literate Haskell source.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
input formats
|
|
\f[CR]markdown\f[R], \f[CR]rst\f[R], \f[CR]latex\f[R]
|
|
.TP
|
|
output formats
|
|
\f[CR]markdown\f[R], \f[CR]rst\f[R], \f[CR]latex\f[R], \f[CR]html\f[R]
|
|
.PP
|
|
If you append \f[CR]+lhs\f[R] (or \f[CR]+literate_haskell\f[R]) to one
|
|
of the formats above, pandoc will treat the document as literate Haskell
|
|
source.
|
|
This means that
|
|
.IP \(bu 2
|
|
In Markdown input, \(lqbird track\(rq sections will be parsed as Haskell
|
|
code rather than block quotations.
|
|
Text between \f[CR]\(rsbegin{code}\f[R] and \f[CR]\(rsend{code}\f[R]
|
|
will also be treated as Haskell code.
|
|
For ATX\-style headings the character `=' will be used instead of `#'.
|
|
.IP \(bu 2
|
|
In Markdown output, code blocks with classes \f[CR]haskell\f[R] and
|
|
\f[CR]literate\f[R] will be rendered using bird tracks, and block
|
|
quotations will be indented one space, so they will not be treated as
|
|
Haskell code.
|
|
In addition, headings will be rendered setext\-style (with underlines)
|
|
rather than ATX\-style (with `#' characters).
|
|
(This is because ghc treats `#' characters in column 1 as introducing
|
|
line numbers.)
|
|
.IP \(bu 2
|
|
In restructured text input, \(lqbird track\(rq sections will be parsed
|
|
as Haskell code.
|
|
.IP \(bu 2
|
|
In restructured text output, code blocks with class \f[CR]haskell\f[R]
|
|
will be rendered using bird tracks.
|
|
.IP \(bu 2
|
|
In LaTeX input, text in \f[CR]code\f[R] environments will be parsed as
|
|
Haskell code.
|
|
.IP \(bu 2
|
|
In LaTeX output, code blocks with class \f[CR]haskell\f[R] will be
|
|
rendered inside \f[CR]code\f[R] environments.
|
|
.IP \(bu 2
|
|
In HTML output, code blocks with class \f[CR]haskell\f[R] will be
|
|
rendered with class \f[CR]literatehaskell\f[R] and bird tracks.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
pandoc \-f markdown+lhs \-t html
|
|
.EE
|
|
.PP
|
|
reads literate Haskell source formatted with Markdown conventions and
|
|
writes ordinary HTML (without bird tracks).
|
|
.IP
|
|
.EX
|
|
pandoc \-f markdown+lhs \-t html+lhs
|
|
.EE
|
|
.PP
|
|
writes HTML with the Haskell code in bird tracks, so it can be copied
|
|
and pasted as literate Haskell source.
|
|
.PP
|
|
Note that GHC expects the bird tracks in the first column, so indented
|
|
literate code blocks (e.g.\ inside an itemized environment) will not be
|
|
picked up by the Haskell compiler.
|
|
.SS Other extensions
|
|
.SS Extension: \f[CR]empty_paragraphs\f[R]
|
|
Allows empty paragraphs.
|
|
By default empty paragraphs are omitted.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
input formats
|
|
\f[CR]docx\f[R], \f[CR]html\f[R]
|
|
.TP
|
|
output formats
|
|
\f[CR]docx\f[R], \f[CR]odt\f[R], \f[CR]opendocument\f[R],
|
|
\f[CR]html\f[R], \f[CR]latex\f[R]
|
|
.SS Extension: \f[CR]native_numbering\f[R]
|
|
Enables numbering of figures and tables via counter fields specific to
|
|
the target format.
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
output formats
|
|
\f[CR]odt\f[R], \f[CR]opendocument\f[R], \f[CR]docx\f[R]
|
|
.PP
|
|
If this extension is not enabled, tables and figures in these formats
|
|
will not be numbered.
|
|
.SS Extension: \f[CR]xrefs_name\f[R]
|
|
Links to headings, figures and tables inside the document are
|
|
substituted with cross\-references that will use the name or caption of
|
|
the referenced item.
|
|
The original link text is replaced once the generated document is
|
|
refreshed.
|
|
This extension can be combined with \f[CR]xrefs_number\f[R] in which
|
|
case numbers will appear before the name.
|
|
.PP
|
|
Text in cross\-references is only made consistent with the referenced
|
|
item once the document has been refreshed.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
output formats
|
|
\f[CR]odt\f[R], \f[CR]opendocument\f[R]
|
|
.SS Extension: \f[CR]xrefs_number\f[R]
|
|
Links to headings, figures and tables inside the document are
|
|
substituted with cross\-references that will use the number of the
|
|
referenced item.
|
|
The original link text is discarded.
|
|
This extension can be combined with \f[CR]xrefs_name\f[R] in which case
|
|
the name or caption numbers will appear after the number.
|
|
.PP
|
|
For the \f[CR]xrefs_number\f[R] to be useful heading numbers must be
|
|
enabled in the generated document, also table and figure captions must
|
|
be enabled using for example the \f[CR]native_numbering\f[R] extension.
|
|
.PP
|
|
Numbers in cross\-references are only visible in the final document once
|
|
it has been refreshed.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
output formats
|
|
\f[CR]odt\f[R], \f[CR]opendocument\f[R]
|
|
.SS Extension: \f[CR]styles\f[R]
|
|
When converting from docx, add \f[CR]custom\-styles\f[R] attributes for
|
|
all docx styles, regardless of whether pandoc understands the meanings
|
|
of these styles.
|
|
Because attributes cannot be added directly to paragraphs or text in the
|
|
pandoc AST, paragraph styles will cause Divs to be created and character
|
|
styles will cause Spans to be created to hold the attributes.
|
|
(Table styles will be added to the Table elements directly.)
|
|
This extension can be used with docx custom styles.
|
|
.TP
|
|
input formats
|
|
\f[CR]docx\f[R]
|
|
.SS Extension: \f[CR]amuse\f[R]
|
|
In the \f[CR]muse\f[R] input format, this enables Text::Amuse extensions
|
|
to Emacs Muse markup.
|
|
.SS Extension: \f[CR]raw_markdown\f[R]
|
|
In the \f[CR]ipynb\f[R] input format, this causes Markdown cells to be
|
|
included as raw Markdown blocks (allowing lossless round\-tripping)
|
|
rather than being parsed.
|
|
Use this only when you are targeting \f[CR]ipynb\f[R] or a
|
|
Markdown\-based output format.
|
|
.SS Extension: \f[CR]citations\f[R] (typst)
|
|
When the \f[CR]citations\f[R] extension is enabled in \f[CR]typst\f[R]
|
|
(as it is by default), \f[CR]typst\f[R] citations will be parsed as
|
|
native pandoc citations, and native pandoc citations will be rendered as
|
|
\f[CR]typst\f[R] citations.
|
|
.SS Extension: \f[CR]citations\f[R] (org)
|
|
When the \f[CR]citations\f[R] extension is enabled in \f[CR]org\f[R],
|
|
org\-cite and org\-ref style citations will be parsed as native pandoc
|
|
citations, and org\-cite citations will be used to render native pandoc
|
|
citations.
|
|
.SS Extension: \f[CR]citations\f[R] (docx)
|
|
When \f[CR]citations\f[R] is enabled in \f[CR]docx\f[R], citations
|
|
inserted by Zotero or Mendeley or EndNote plugins will be parsed as
|
|
native pandoc citations.
|
|
(Otherwise, the formatted citations generated by the bibliographic
|
|
software will be parsed as regular text.)
|
|
.SS Extension: \f[CR]fancy_lists\f[R] (org)
|
|
Some aspects of Pandoc\(cqs Markdown fancy lists are also accepted in
|
|
\f[CR]org\f[R] input, mimicking the option
|
|
\f[CR]org\-list\-allow\-alphabetical\f[R] in Emacs.
|
|
As in Org Mode, enabling this extension allows lowercase and uppercase
|
|
alphabetical markers for ordered lists to be parsed in addition to
|
|
arabic ones.
|
|
Note that for Org, this does not include roman numerals or the
|
|
\f[CR]#\f[R] placeholder that are enabled by the extension in
|
|
Pandoc\(cqs Markdown.
|
|
.SS Extension: \f[CR]element_citations\f[R]
|
|
In the \f[CR]jats\f[R] output formats, this causes reference items to be
|
|
replaced with \f[CR]<element\-citation>\f[R] elements.
|
|
These elements are not influenced by CSL styles, but all information on
|
|
the item is included in tags.
|
|
.SS Extension: \f[CR]ntb\f[R]
|
|
In the \f[CR]context\f[R] output format this enables the use of Natural
|
|
Tables (TABLE) instead of the default Extreme Tables (xtables).
|
|
Natural tables allow more fine\-grained global customization but come at
|
|
a performance penalty compared to extreme tables.
|
|
.SS Extension: \f[CR]smart_quotes\f[R] (org)
|
|
Interpret straight quotes as curly quotes during parsing.
|
|
When \f[I]writing\f[R] Org, then the \f[CR]smart_quotes\f[R] extension
|
|
has the reverse effect: what would have been curly quotes comes out
|
|
straight.
|
|
.PP
|
|
This extension is implied if \f[CR]smart\f[R] is enabled.
|
|
.SS Extension: \f[CR]special_strings\f[R] (org)
|
|
Interpret \f[CR]\-\-\-\f[R] as em\-dashes, \f[CR]\-\-\f[R] as
|
|
en\-dashes, \f[CR]\(rs\-\f[R] as shy hyphen, and \f[CR]...\f[R] as
|
|
ellipses.
|
|
.PP
|
|
This extension is implied if \f[CR]smart\f[R] is enabled.
|
|
.SS Extension: \f[CR]tagging\f[R]
|
|
Enabling this extension with \f[CR]context\f[R] output will produce
|
|
markup suitable for the production of tagged PDFs.
|
|
This includes additional markers for paragraphs and alternative markup
|
|
for emphasized text.
|
|
The \f[CR]emphasis\-command\f[R] template variable is set if the
|
|
extension is enabled.
|
|
.SH PANDOC\(cqS MARKDOWN
|
|
Pandoc understands an extended and slightly revised version of John
|
|
Gruber\(cqs Markdown syntax.
|
|
This document explains the syntax, noting differences from original
|
|
Markdown.
|
|
Except where noted, these differences can be suppressed by using the
|
|
\f[CR]markdown_strict\f[R] format instead of \f[CR]markdown\f[R].
|
|
Extensions can be enabled or disabled to specify the behavior more
|
|
granularly.
|
|
They are described in the following.
|
|
See also Extensions above, for extensions that work also on other
|
|
formats.
|
|
.SS Philosophy
|
|
Markdown is designed to be easy to write, and, even more importantly,
|
|
easy to read:
|
|
.RS
|
|
.PP
|
|
A Markdown\-formatted document should be publishable as\-is, as plain
|
|
text, without looking like it\(cqs been marked up with tags or
|
|
formatting instructions.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\(en John Gruber
|
|
.RE
|
|
.PP
|
|
This principle has guided pandoc\(cqs decisions in finding syntax for
|
|
tables, footnotes, and other extensions.
|
|
.PP
|
|
There is, however, one respect in which pandoc\(cqs aims are different
|
|
from the original aims of Markdown.
|
|
Whereas Markdown was originally designed with HTML generation in mind,
|
|
pandoc is designed for multiple output formats.
|
|
Thus, while pandoc allows the embedding of raw HTML, it discourages it,
|
|
and provides other, non\-HTMLish ways of representing important document
|
|
elements like definition lists, tables, mathematics, and footnotes.
|
|
.SS Paragraphs
|
|
A paragraph is one or more lines of text followed by one or more blank
|
|
lines.
|
|
Newlines are treated as spaces, so you can reflow your paragraphs as you
|
|
like.
|
|
If you need a hard line break, put two or more spaces at the end of a
|
|
line.
|
|
.SS Extension: \f[CR]escaped_line_breaks\f[R]
|
|
A backslash followed by a newline is also a hard line break.
|
|
Note: in multiline and grid table cells, this is the only way to create
|
|
a hard line break, since trailing spaces in the cells are ignored.
|
|
.SS Headings
|
|
There are two kinds of headings: Setext and ATX.
|
|
.SS Setext\-style headings
|
|
A setext\-style heading is a line of text \(lqunderlined\(rq with a row
|
|
of \f[CR]=\f[R] signs (for a level\-one heading) or \f[CR]\-\f[R] signs
|
|
(for a level\-two heading):
|
|
.IP
|
|
.EX
|
|
A level\-one heading
|
|
===================
|
|
|
|
A level\-two heading
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
.EE
|
|
.PP
|
|
The heading text can contain inline formatting, such as emphasis (see
|
|
Inline formatting, below).
|
|
.SS ATX\-style headings
|
|
An ATX\-style heading consists of one to six \f[CR]#\f[R] signs and a
|
|
line of text, optionally followed by any number of \f[CR]#\f[R] signs.
|
|
The number of \f[CR]#\f[R] signs at the beginning of the line is the
|
|
heading level:
|
|
.IP
|
|
.EX
|
|
## A level\-two heading
|
|
|
|
### A level\-three heading ###
|
|
.EE
|
|
.PP
|
|
As with setext\-style headings, the heading text can contain formatting:
|
|
.IP
|
|
.EX
|
|
# A level\-one heading with a [link](/url) and *emphasis*
|
|
.EE
|
|
.SS Extension: \f[CR]blank_before_header\f[R]
|
|
Original Markdown syntax does not require a blank line before a heading.
|
|
Pandoc does require this (except, of course, at the beginning of the
|
|
document).
|
|
The reason for the requirement is that it is all too easy for a
|
|
\f[CR]#\f[R] to end up at the beginning of a line by accident (perhaps
|
|
through line wrapping).
|
|
Consider, for example:
|
|
.IP
|
|
.EX
|
|
I like several of their flavors of ice cream:
|
|
#22, for example, and #5.
|
|
.EE
|
|
.SS Extension: \f[CR]space_in_atx_header\f[R]
|
|
Many Markdown implementations do not require a space between the opening
|
|
\f[CR]#\f[R]s of an ATX heading and the heading text, so that
|
|
\f[CR]#5 bolt\f[R] and \f[CR]#hashtag\f[R] count as headings.
|
|
With this extension, pandoc does require the space.
|
|
.SS Heading identifiers
|
|
See also the \f[CR]auto_identifiers\f[R] extension above.
|
|
.SS Extension: \f[CR]header_attributes\f[R]
|
|
Headings can be assigned attributes using this syntax at the end of the
|
|
line containing the heading text:
|
|
.IP
|
|
.EX
|
|
{#identifier .class .class key=value key=value}
|
|
.EE
|
|
.PP
|
|
Thus, for example, the following headings will all be assigned the
|
|
identifier \f[CR]foo\f[R]:
|
|
.IP
|
|
.EX
|
|
# My heading {#foo}
|
|
|
|
## My heading ## {#foo}
|
|
|
|
My other heading {#foo}
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
.EE
|
|
.PP
|
|
(This syntax is compatible with PHP Markdown Extra.)
|
|
.PP
|
|
Note that although this syntax allows assignment of classes and
|
|
key/value attributes, writers generally don\(cqt use all of this
|
|
information.
|
|
Identifiers, classes, and key/value attributes are used in HTML and
|
|
HTML\-based formats such as EPUB and slidy.
|
|
Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,
|
|
Textile, Jira markup, and AsciiDoc writers.
|
|
.PP
|
|
Headings with the class \f[CR]unnumbered\f[R] will not be numbered, even
|
|
if \f[CR]\-\-number\-sections\f[R] is specified.
|
|
A single hyphen (\f[CR]\-\f[R]) in an attribute context is equivalent to
|
|
\f[CR].unnumbered\f[R], and preferable in non\-English documents.
|
|
So,
|
|
.IP
|
|
.EX
|
|
# My heading {\-}
|
|
.EE
|
|
.PP
|
|
is just the same as
|
|
.IP
|
|
.EX
|
|
# My heading {.unnumbered}
|
|
.EE
|
|
.PP
|
|
If the \f[CR]unlisted\f[R] class is present in addition to
|
|
\f[CR]unnumbered\f[R], the heading will not be included in a table of
|
|
contents.
|
|
(Currently this feature is only implemented for certain formats: those
|
|
based on LaTeX and HTML, PowerPoint, and RTF.)
|
|
.SS Extension: \f[CR]implicit_header_references\f[R]
|
|
Pandoc behaves as if reference links have been defined for each heading.
|
|
So, to link to a heading
|
|
.IP
|
|
.EX
|
|
# Heading identifiers in HTML
|
|
.EE
|
|
.PP
|
|
you can simply write
|
|
.IP
|
|
.EX
|
|
[Heading identifiers in HTML]
|
|
.EE
|
|
.PP
|
|
or
|
|
.IP
|
|
.EX
|
|
[Heading identifiers in HTML][]
|
|
.EE
|
|
.PP
|
|
or
|
|
.IP
|
|
.EX
|
|
[the section on heading identifiers][heading identifiers in
|
|
HTML]
|
|
.EE
|
|
.PP
|
|
instead of giving the identifier explicitly:
|
|
.IP
|
|
.EX
|
|
[Heading identifiers in HTML](#heading\-identifiers\-in\-html)
|
|
.EE
|
|
.PP
|
|
If there are multiple headings with identical text, the corresponding
|
|
reference will link to the first one only, and you will need to use
|
|
explicit links to link to the others, as described above.
|
|
.PP
|
|
Like regular reference links, these references are case\-insensitive.
|
|
.PP
|
|
Explicit link reference definitions always take priority over implicit
|
|
heading references.
|
|
So, in the following example, the link will point to \f[CR]bar\f[R], not
|
|
to \f[CR]#foo\f[R]:
|
|
.IP
|
|
.EX
|
|
# Foo
|
|
|
|
[foo]: bar
|
|
|
|
See [foo]
|
|
.EE
|
|
.SS Block quotations
|
|
Markdown uses email conventions for quoting blocks of text.
|
|
A block quotation is one or more paragraphs or other block elements
|
|
(such as lists or headings), with each line preceded by a \f[CR]>\f[R]
|
|
character and an optional space.
|
|
(The \f[CR]>\f[R] need not start at the left margin, but it should not
|
|
be indented more than three spaces.)
|
|
.IP
|
|
.EX
|
|
> This is a block quote. This
|
|
> paragraph has two lines.
|
|
>
|
|
> 1. This is a list inside a block quote.
|
|
> 2. Second item.
|
|
.EE
|
|
.PP
|
|
A \(lqlazy\(rq form, which requires the \f[CR]>\f[R] character only on
|
|
the first line of each block, is also allowed:
|
|
.IP
|
|
.EX
|
|
> This is a block quote. This
|
|
paragraph has two lines.
|
|
|
|
> 1. This is a list inside a block quote.
|
|
2. Second item.
|
|
.EE
|
|
.PP
|
|
Among the block elements that can be contained in a block quote are
|
|
other block quotes.
|
|
That is, block quotes can be nested:
|
|
.IP
|
|
.EX
|
|
> This is a block quote.
|
|
>
|
|
> > A block quote within a block quote.
|
|
.EE
|
|
.PP
|
|
If the \f[CR]>\f[R] character is followed by an optional space, that
|
|
space will be considered part of the block quote marker and not part of
|
|
the indentation of the contents.
|
|
Thus, to put an indented code block in a block quote, you need five
|
|
spaces after the \f[CR]>\f[R]:
|
|
.IP
|
|
.EX
|
|
> code
|
|
.EE
|
|
.SS Extension: \f[CR]blank_before_blockquote\f[R]
|
|
Original Markdown syntax does not require a blank line before a block
|
|
quote.
|
|
Pandoc does require this (except, of course, at the beginning of the
|
|
document).
|
|
The reason for the requirement is that it is all too easy for a
|
|
\f[CR]>\f[R] to end up at the beginning of a line by accident (perhaps
|
|
through line wrapping).
|
|
So, unless the \f[CR]markdown_strict\f[R] format is used, the following
|
|
does not produce a nested block quote in pandoc:
|
|
.IP
|
|
.EX
|
|
> This is a block quote.
|
|
>> Not nested, since \(gablank_before_blockquote\(ga is enabled by default
|
|
.EE
|
|
.SS Verbatim (code) blocks
|
|
.SS Indented code blocks
|
|
A block of text indented four spaces (or one tab) is treated as verbatim
|
|
text: that is, special characters do not trigger special formatting, and
|
|
all spaces and line breaks are preserved.
|
|
For example,
|
|
.IP
|
|
.EX
|
|
if (a > 3) {
|
|
moveShip(5 * gravity, DOWN);
|
|
}
|
|
.EE
|
|
.PP
|
|
The initial (four space or one tab) indentation is not considered part
|
|
of the verbatim text, and is removed in the output.
|
|
.PP
|
|
Note: blank lines in the verbatim text need not begin with four spaces.
|
|
.SS Fenced code blocks
|
|
.SS Extension: \f[CR]fenced_code_blocks\f[R]
|
|
In addition to standard indented code blocks, pandoc supports
|
|
\f[I]fenced\f[R] code blocks.
|
|
These begin with a row of three or more tildes (\f[CR]\(ti\f[R]) and end
|
|
with a row of tildes that must be at least as long as the starting row.
|
|
Everything between these lines is treated as code.
|
|
No indentation is necessary:
|
|
.IP
|
|
.EX
|
|
\(ti\(ti\(ti\(ti\(ti\(ti\(ti
|
|
if (a > 3) {
|
|
moveShip(5 * gravity, DOWN);
|
|
}
|
|
\(ti\(ti\(ti\(ti\(ti\(ti\(ti
|
|
.EE
|
|
.PP
|
|
Like regular code blocks, fenced code blocks must be separated from
|
|
surrounding text by blank lines.
|
|
.PP
|
|
If the code itself contains a row of tildes or backticks, just use a
|
|
longer row of tildes or backticks at the start and end:
|
|
.IP
|
|
.EX
|
|
\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti
|
|
\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti
|
|
code including tildes
|
|
\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti
|
|
\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti
|
|
.EE
|
|
.SS Extension: \f[CR]backtick_code_blocks\f[R]
|
|
Same as \f[CR]fenced_code_blocks\f[R], but uses backticks
|
|
(\f[CR]\(ga\f[R]) instead of tildes (\f[CR]\(ti\f[R]).
|
|
.SS Extension: \f[CR]fenced_code_attributes\f[R]
|
|
Optionally, you may attach attributes to fenced or backtick code block
|
|
using this syntax:
|
|
.IP
|
|
.EX
|
|
\(ti\(ti\(ti\(ti {#mycode .haskell .numberLines startFrom=\(dq100\(dq}
|
|
qsort [] = []
|
|
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
|
|
qsort (filter (>= x) xs)
|
|
\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti\(ti
|
|
.EE
|
|
.PP
|
|
Here \f[CR]mycode\f[R] is an identifier, \f[CR]haskell\f[R] and
|
|
\f[CR]numberLines\f[R] are classes, and \f[CR]startFrom\f[R] is an
|
|
attribute with value \f[CR]100\f[R].
|
|
Some output formats can use this information to do syntax highlighting.
|
|
Currently, the only output formats that use this information are HTML,
|
|
LaTeX, Docx, Ms, and PowerPoint.
|
|
If highlighting is supported for your output format and language, then
|
|
the code block above will appear highlighted, with numbered lines.
|
|
(To see which languages are supported, type
|
|
\f[CR]pandoc \-\-list\-highlight\-languages\f[R].)
|
|
Otherwise, the code block above will appear as follows:
|
|
.IP
|
|
.EX
|
|
<pre id=\(dqmycode\(dq class=\(dqhaskell numberLines\(dq startFrom=\(dq100\(dq>
|
|
<code>
|
|
...
|
|
</code>
|
|
</pre>
|
|
.EE
|
|
.PP
|
|
The \f[CR]numberLines\f[R] (or \f[CR]number\-lines\f[R]) class will
|
|
cause the lines of the code block to be numbered, starting with
|
|
\f[CR]1\f[R] or the value of the \f[CR]startFrom\f[R] attribute.
|
|
The \f[CR]lineAnchors\f[R] (or \f[CR]line\-anchors\f[R]) class will
|
|
cause the lines to be clickable anchors in HTML output.
|
|
.PP
|
|
A shortcut form can also be used for specifying the language of the code
|
|
block:
|
|
.IP
|
|
.EX
|
|
\(ga\(ga\(gahaskell
|
|
qsort [] = []
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.PP
|
|
This is equivalent to:
|
|
.IP
|
|
.EX
|
|
\(ga\(ga\(ga {.haskell}
|
|
qsort [] = []
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.PP
|
|
This shortcut form may be combined with attributes:
|
|
.IP
|
|
.EX
|
|
\(ga\(ga\(gahaskell {.numberLines}
|
|
qsort [] = []
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.PP
|
|
Which is equivalent to:
|
|
.IP
|
|
.EX
|
|
\(ga\(ga\(ga {.haskell .numberLines}
|
|
qsort [] = []
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.PP
|
|
If the \f[CR]fenced_code_attributes\f[R] extension is disabled, but
|
|
input contains class attribute(s) for the code block, the first class
|
|
attribute will be printed after the opening fence as a bare word.
|
|
.PP
|
|
To prevent all highlighting, use the
|
|
\f[CR]\-\-syntax\-highlighting=none\f[R] option.
|
|
To set the highlighting style or method, use
|
|
\f[CR]\-\-syntax\-highlighting\f[R].
|
|
For more information on highlighting, see Syntax highlighting, below.
|
|
.SS Line blocks
|
|
.SS Extension: \f[CR]line_blocks\f[R]
|
|
A line block is a sequence of lines beginning with a vertical bar
|
|
(\f[CR]|\f[R]) followed by a space.
|
|
The division into lines will be preserved in the output, as will any
|
|
leading spaces; otherwise, the lines will be formatted as Markdown.
|
|
This is useful for verse and addresses:
|
|
.IP
|
|
.EX
|
|
| The limerick packs laughs anatomical
|
|
| In space that is quite economical.
|
|
| But the good ones I\(aqve seen
|
|
| So seldom are clean
|
|
| And the clean ones so seldom are comical
|
|
|
|
| 200 Main St.
|
|
| Berkeley, CA 94718
|
|
.EE
|
|
.PP
|
|
The lines can be hard\-wrapped if needed, but the continuation line must
|
|
begin with a space.
|
|
.IP
|
|
.EX
|
|
| The Right Honorable Most Venerable and Righteous Samuel L.
|
|
Constable, Jr.
|
|
| 200 Main St.
|
|
| Berkeley, CA 94718
|
|
.EE
|
|
.PP
|
|
Inline formatting (such as emphasis) is allowed in the content (though
|
|
it can\(cqt cross line boundaries).
|
|
Block\-level formatting (such as block quotes or lists) is not
|
|
recognized.
|
|
.PP
|
|
This syntax is borrowed from reStructuredText.
|
|
.SS Lists
|
|
.SS Bullet lists
|
|
A bullet list is a list of bulleted list items.
|
|
A bulleted list item begins with a bullet (\f[CR]*\f[R], \f[CR]+\f[R],
|
|
or \f[CR]\-\f[R]).
|
|
Here is a simple example:
|
|
.IP
|
|
.EX
|
|
* one
|
|
* two
|
|
* three
|
|
.EE
|
|
.PP
|
|
This will produce a \(lqcompact\(rq list.
|
|
If you want a \(lqloose\(rq list, in which each item is formatted as a
|
|
paragraph, put spaces between the items:
|
|
.IP
|
|
.EX
|
|
* one
|
|
|
|
* two
|
|
|
|
* three
|
|
.EE
|
|
.PP
|
|
The bullets need not be flush with the left margin; they may be indented
|
|
one, two, or three spaces.
|
|
The bullet must be followed by whitespace.
|
|
.PP
|
|
List items look best if subsequent lines are flush with the first line
|
|
(after the bullet):
|
|
.IP
|
|
.EX
|
|
* here is my first
|
|
list item.
|
|
* and my second.
|
|
.EE
|
|
.PP
|
|
But Markdown also allows a \(lqlazy\(rq format:
|
|
.IP
|
|
.EX
|
|
* here is my first
|
|
list item.
|
|
* and my second.
|
|
.EE
|
|
.SS Block content in list items
|
|
A list item may contain multiple paragraphs and other block\-level
|
|
content.
|
|
However, subsequent paragraphs must be preceded by a blank line and
|
|
indented to line up with the first non\-space content after the list
|
|
marker.
|
|
.IP
|
|
.EX
|
|
* First paragraph.
|
|
|
|
Continued.
|
|
|
|
* Second paragraph. With a code block, which must be indented
|
|
eight spaces:
|
|
|
|
{ code }
|
|
.EE
|
|
.PP
|
|
Exception: if the list marker is followed by an indented code block,
|
|
which must begin 5 spaces after the list marker, then subsequent
|
|
paragraphs must begin two columns after the last character of the list
|
|
marker:
|
|
.IP
|
|
.EX
|
|
* code
|
|
|
|
continuation paragraph
|
|
.EE
|
|
.PP
|
|
List items may include other lists.
|
|
In this case the preceding blank line is optional.
|
|
The nested list must be indented to line up with the first non\-space
|
|
character after the list marker of the containing list item.
|
|
.IP
|
|
.EX
|
|
* fruits
|
|
+ apples
|
|
\- macintosh
|
|
\- red delicious
|
|
+ pears
|
|
+ peaches
|
|
* vegetables
|
|
+ broccoli
|
|
+ chard
|
|
.EE
|
|
.PP
|
|
As noted above, Markdown allows you to write list items \(lqlazily,\(rq
|
|
instead of indenting continuation lines.
|
|
However, if there are multiple paragraphs or other blocks in a list
|
|
item, the first line of each must be indented.
|
|
.IP
|
|
.EX
|
|
+ A lazy, lazy, list
|
|
item.
|
|
|
|
+ Another one; this looks
|
|
bad but is legal.
|
|
|
|
Second paragraph of second
|
|
list item.
|
|
.EE
|
|
.SS Ordered lists
|
|
Ordered lists work just like bulleted lists, except that the items begin
|
|
with enumerators rather than bullets.
|
|
.PP
|
|
In original Markdown, enumerators are decimal numbers followed by a
|
|
period and a space.
|
|
The numbers themselves are ignored, so there is no difference between
|
|
this list:
|
|
.IP
|
|
.EX
|
|
1. one
|
|
2. two
|
|
3. three
|
|
.EE
|
|
.PP
|
|
and this one:
|
|
.IP
|
|
.EX
|
|
5. one
|
|
7. two
|
|
1. three
|
|
.EE
|
|
.SS Extension: \f[CR]fancy_lists\f[R]
|
|
Unlike original Markdown, pandoc allows ordered list items to be marked
|
|
with uppercase and lowercase letters and roman numerals, in addition to
|
|
Arabic numerals.
|
|
List markers may be enclosed in parentheses or followed by a single
|
|
right\-parenthesis or period.
|
|
They must be separated from the text that follows by at least one space,
|
|
and, if the list marker is a capital letter with a period, by at least
|
|
two spaces.
|
|
.PP
|
|
The \f[CR]fancy_lists\f[R] extension also allows `\f[CR]#\f[R]' to be
|
|
used as an ordered list marker in place of a numeral:
|
|
.IP
|
|
.EX
|
|
#. one
|
|
#. two
|
|
.EE
|
|
.PP
|
|
Note: the `\f[CR]#\f[R]' ordered list marker doesn\(cqt work with
|
|
\f[CR]commonmark\f[R].
|
|
.PP
|
|
As with \f[CR]commonmark\f[R], ordered sublists must start with
|
|
\f[CR]1\f[R] or the equivalent (e.g., \f[CR]i\f[R] or \f[CR]a\f[R]).
|
|
This helps avoid unintentional lists caused by things like parenthesized
|
|
dates.
|
|
.SS Extension: \f[CR]startnum\f[R]
|
|
Pandoc also pays attention to the type of list marker used, and to the
|
|
starting number, and both of these are preserved where possible in the
|
|
output format.
|
|
Thus, the following yields a list with numbers followed by a single
|
|
parenthesis, starting with 9, and a sublist with lowercase roman
|
|
numerals:
|
|
.IP
|
|
.EX
|
|
9) Ninth
|
|
10) Tenth
|
|
11) Eleventh
|
|
i. subone
|
|
ii. subtwo
|
|
iii. subthree
|
|
.EE
|
|
.PP
|
|
Pandoc will start a new list each time a different type of list marker
|
|
is used.
|
|
So, the following will create three lists:
|
|
.IP
|
|
.EX
|
|
(2) Two
|
|
(5) Three
|
|
1. Four
|
|
* Five
|
|
.EE
|
|
.PP
|
|
If default list markers are desired, use \f[CR]#.\f[R]:
|
|
.IP
|
|
.EX
|
|
#. one
|
|
#. two
|
|
#. three
|
|
.EE
|
|
.SS Extension: \f[CR]task_lists\f[R]
|
|
Pandoc supports task lists, using the syntax of GitHub\-Flavored
|
|
Markdown.
|
|
.IP
|
|
.EX
|
|
\- [ ] an unchecked task list item
|
|
\- [x] checked item
|
|
.EE
|
|
.SS Definition lists
|
|
.SS Extension: \f[CR]definition_lists\f[R]
|
|
Pandoc supports definition lists, using the syntax of PHP Markdown Extra
|
|
with some extensions.
|
|
.IP
|
|
.EX
|
|
Term 1
|
|
|
|
: Definition 1
|
|
|
|
Term 2 with *inline markup*
|
|
|
|
: Definition 2
|
|
|
|
{ some code, part of Definition 2 }
|
|
|
|
Third paragraph of definition 2.
|
|
.EE
|
|
.PP
|
|
Each term must fit on one line, which may optionally be followed by a
|
|
blank line, and must be followed by one or more definitions.
|
|
A definition begins with a colon or tilde, which may be indented one or
|
|
two spaces.
|
|
.PP
|
|
A term may have multiple definitions, and each definition may consist of
|
|
one or more indented block elements (paragraph, code block, list, etc.).
|
|
The blocks in the definition should be indented to the column of the
|
|
first non\-space content after the \f[CR]:\f[R] or \f[CR]\(ti\f[R]
|
|
marker, or (if the \f[CR]four_space_rule\f[R] extension is enabled) four
|
|
spaces or one tab stop.
|
|
As with other Markdown lists, you can \(lqlazily\(rq omit indentation in
|
|
paragraph continuation lines:
|
|
.IP
|
|
.EX
|
|
Term 1
|
|
|
|
: Definition
|
|
with lazy continuation.
|
|
|
|
Second paragraph of the definition.
|
|
.EE
|
|
.PP
|
|
If you leave space before the definition (as in the example above), the
|
|
text of the definition will be treated as a paragraph.
|
|
In some output formats, this will mean greater spacing between
|
|
term/definition pairs.
|
|
For a more compact definition list, omit the space before the
|
|
definition:
|
|
.IP
|
|
.EX
|
|
Term 1
|
|
\(ti Definition 1
|
|
|
|
Term 2
|
|
\(ti Definition 2a
|
|
\(ti Definition 2b
|
|
.EE
|
|
.PP
|
|
Note that space between items in a definition list is required.
|
|
.SS Numbered example lists
|
|
.SS Extension: \f[CR]example_lists\f[R]
|
|
The special list marker \f[CR]\(at\f[R] can be used for sequentially
|
|
numbered examples.
|
|
The first list item with a \f[CR]\(at\f[R] marker will be numbered `1',
|
|
the next `2', and so on, throughout the document.
|
|
The numbered examples need not occur in a single list; each new list
|
|
using \f[CR]\(at\f[R] will take up where the last stopped.
|
|
So, for example:
|
|
.IP
|
|
.EX
|
|
(\(at) My first example will be numbered (1).
|
|
(\(at) My second example will be numbered (2).
|
|
|
|
Explanation of examples.
|
|
|
|
(\(at) My third example will be numbered (3).
|
|
.EE
|
|
.PP
|
|
Numbered examples can be labeled and referred to elsewhere in the
|
|
document:
|
|
.IP
|
|
.EX
|
|
(\(atgood) This is a good example.
|
|
|
|
As (\(atgood) illustrates, ...
|
|
.EE
|
|
.PP
|
|
The label can be any string of alphanumeric characters, underscores, or
|
|
hyphens.
|
|
.PP
|
|
Continuation paragraphs in example lists must always be indented four
|
|
spaces, regardless of the length of the list marker.
|
|
That is, example lists always behave as if the
|
|
\f[CR]four_space_rule\f[R] extension is set.
|
|
This is because example labels tend to be long, and indenting content to
|
|
the first non\-space character after the label would be awkward.
|
|
.PP
|
|
You can repeat an earlier numbered example by re\-using its label:
|
|
.IP
|
|
.EX
|
|
(\(atfoo) Sample sentence.
|
|
|
|
Intervening text...
|
|
|
|
This theory can explain the case we saw earlier (repeated):
|
|
|
|
(\(atfoo) Sample sentence.
|
|
.EE
|
|
.PP
|
|
This only works reliably, though, if the repeated item is in a list by
|
|
itself, because each numbered example list will be numbered continuously
|
|
from its starting number.
|
|
.SS Ending a list
|
|
What if you want to put an indented code block after a list?
|
|
.IP
|
|
.EX
|
|
\- item one
|
|
\- item two
|
|
|
|
{ my code block }
|
|
.EE
|
|
.PP
|
|
Trouble!
|
|
Here pandoc (like other Markdown implementations) will treat
|
|
\f[CR]{ my code block }\f[R] as the second paragraph of item two, and
|
|
not as a code block.
|
|
.PP
|
|
To \(lqcut off\(rq the list after item two, you can insert some
|
|
non\-indented content, like an HTML comment, which won\(cqt produce
|
|
visible output in any format:
|
|
.IP
|
|
.EX
|
|
\- item one
|
|
\- item two
|
|
|
|
<!\-\- end of list \-\->
|
|
|
|
{ my code block }
|
|
.EE
|
|
.PP
|
|
You can use the same trick if you want two consecutive lists instead of
|
|
one big list:
|
|
.IP
|
|
.EX
|
|
1. one
|
|
2. two
|
|
3. three
|
|
|
|
<!\-\- \-\->
|
|
|
|
1. uno
|
|
2. dos
|
|
3. tres
|
|
.EE
|
|
.SS Horizontal rules
|
|
A line containing a row of three or more \f[CR]*\f[R], \f[CR]\-\f[R], or
|
|
\f[CR]_\f[R] characters (optionally separated by spaces) produces a
|
|
horizontal rule:
|
|
.IP
|
|
.EX
|
|
* * * *
|
|
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
.EE
|
|
.PP
|
|
We strongly recommend that horizontal rules be separated from
|
|
surrounding text by blank lines.
|
|
If a horizontal rule is not followed by a blank line, pandoc may try to
|
|
interpret the lines that follow as a YAML metadata block or a table.
|
|
.SS Tables
|
|
Four kinds of tables may be used.
|
|
The first three kinds (simple, multiline, and grid) require lining up
|
|
columns and thus presuppose the use of a fixed\-width font, such as
|
|
Courier.
|
|
The fourth kind (pipe tables) can be used with proportionally spaced
|
|
fonts, as it does not require lining up columns.
|
|
.SS Extension: \f[CR]table_captions\f[R]
|
|
A caption may optionally be provided with all 4 kinds of tables (as
|
|
illustrated in the examples below).
|
|
A caption is a paragraph beginning with the string \f[CR]Table:\f[R] (or
|
|
\f[CR]table:\f[R] or just \f[CR]:\f[R]), which will be stripped off.
|
|
It may appear either before or after the table.
|
|
.SS Extension: \f[CR]simple_tables\f[R]
|
|
Simple tables look like this:
|
|
.IP
|
|
.EX
|
|
Right Left Center Default
|
|
\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
|
|
12 12 12 12
|
|
123 123 123 123
|
|
1 1 1 1
|
|
|
|
Table: Demonstration of simple table syntax.
|
|
.EE
|
|
.PP
|
|
The header and table rows must each fit on one line.
|
|
Column alignments are determined by the position of the header text
|
|
relative to the dashed line below it:
|
|
.IP \(bu 2
|
|
If the dashed line is flush with the header text on the right side but
|
|
extends beyond it on the left, the column is right\-aligned.
|
|
.IP \(bu 2
|
|
If the dashed line is flush with the header text on the left side but
|
|
extends beyond it on the right, the column is left\-aligned.
|
|
.IP \(bu 2
|
|
If the dashed line extends beyond the header text on both sides, the
|
|
column is centered.
|
|
.IP \(bu 2
|
|
If the dashed line is flush with the header text on both sides, the
|
|
default alignment is used (in most cases, this will be left).
|
|
.PP
|
|
The table must end with a blank line, or a line of dashes followed by a
|
|
blank line.
|
|
.PP
|
|
The column header row may be omitted, provided a dashed line is used to
|
|
end the table.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
|
|
12 12 12 12
|
|
123 123 123 123
|
|
1 1 1 1
|
|
\-\-\-\-\-\-\- \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
|
|
.EE
|
|
.PP
|
|
When the header row is omitted, column alignments are determined on the
|
|
basis of the first line of the table body.
|
|
So, in the tables above, the columns would be right, left, center, and
|
|
right aligned, respectively.
|
|
.SS Extension: \f[CR]multiline_tables\f[R]
|
|
Multiline tables allow header and table rows to span multiple lines of
|
|
text (but cells that span multiple columns or rows of the table are not
|
|
supported).
|
|
Here is an example:
|
|
.IP
|
|
.EX
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
Centered Default Right Left
|
|
Header Aligned Aligned Aligned
|
|
\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
First row 12.0 Example of a row that
|
|
spans multiple lines.
|
|
|
|
Second row 5.0 Here\(aqs another one. Note
|
|
the blank line between
|
|
rows.
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|
|
Table: Here\(aqs the caption. It, too, may span
|
|
multiple lines.
|
|
.EE
|
|
.PP
|
|
These work like simple tables, but with the following differences:
|
|
.IP \(bu 2
|
|
They must begin with a row of dashes, before the header text (unless the
|
|
header row is omitted).
|
|
.IP \(bu 2
|
|
They must end with a row of dashes, then a blank line.
|
|
.IP \(bu 2
|
|
The rows must be separated by blank lines.
|
|
.PP
|
|
In multiline tables, the table parser pays attention to the widths of
|
|
the columns, and the writers try to reproduce these relative widths in
|
|
the output.
|
|
So, if you find that one of the columns is too narrow in the output, try
|
|
widening it in the Markdown source.
|
|
.PP
|
|
The header may be omitted in multiline tables as well as simple tables:
|
|
.IP
|
|
.EX
|
|
\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
First row 12.0 Example of a row that
|
|
spans multiple lines.
|
|
|
|
Second row 5.0 Here\(aqs another one. Note
|
|
the blank line between
|
|
rows.
|
|
\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|
|
: Here\(aqs a multiline table without a header.
|
|
.EE
|
|
.PP
|
|
It is possible for a multiline table to have just one row, but the row
|
|
should be followed by a blank line (and then the row of dashes that ends
|
|
the table), or the table may be interpreted as a simple table.
|
|
.SS Extension: \f[CR]grid_tables\f[R]
|
|
Grid tables look like this:
|
|
.IP
|
|
.EX
|
|
: Sample grid table.
|
|
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
| Fruit | Price | Advantages |
|
|
+===============+===============+====================+
|
|
| Bananas | $1.34 | \- built\-in wrapper |
|
|
| | | \- bright color |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
| Oranges | $2.10 | \- cures scurvy |
|
|
| | | \- tasty |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
.EE
|
|
.PP
|
|
The row of \f[CR]=\f[R]s separates the header from the table body, and
|
|
can be omitted for a headerless table.
|
|
The cells of grid tables may contain arbitrary block elements (multiple
|
|
paragraphs, code blocks, lists, etc.).
|
|
.PP
|
|
Cells can span multiple columns or rows:
|
|
.IP
|
|
.EX
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
|
|
| Property | Earth |
|
|
+=============+=======+==========+
|
|
| | min | \-89.2 °C |
|
|
| Temperature +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
|
|
| 1961\-1990 | mean | 14 °C |
|
|
| +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
|
|
| | max | 56.7 °C |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
|
|
.EE
|
|
.PP
|
|
A table header may contain more than one row:
|
|
.IP
|
|
.EX
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
| Location | Temperature 1961\-1990 |
|
|
| | in degree Celsius |
|
|
| +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+
|
|
| | min | mean | max |
|
|
+=====================+=======+=======+=======+
|
|
| Antarctica | \-89.2 | N/A | 19.8 |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+
|
|
| Earth | \-89.2 | 14 | 56.7 |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+
|
|
.EE
|
|
.PP
|
|
Alignments can be specified as with pipe tables, by putting colons at
|
|
the boundaries of the separator line after the header:
|
|
.IP
|
|
.EX
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
| Right | Left | Centered |
|
|
+==============:+:==============+:==================:+
|
|
| Bananas | $1.34 | built\-in wrapper |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
.EE
|
|
.PP
|
|
For headerless tables, the colons go on the top line instead:
|
|
.IP
|
|
.EX
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+
|
|
| Right | Left | Centered |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
.EE
|
|
.PP
|
|
A table foot can be defined by enclosing it with separator lines that
|
|
use \f[CR]=\f[R] instead of \f[CR]\-\f[R]:
|
|
.IP
|
|
.EX
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
| Fruit | Price |
|
|
+===============+===============+
|
|
| Bananas | $1.34 |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
| Oranges | $2.10 |
|
|
+===============+===============+
|
|
| Sum | $3.44 |
|
|
+===============+===============+
|
|
.EE
|
|
.PP
|
|
The foot must always be placed at the very bottom of the table.
|
|
.PP
|
|
Grid tables can be created easily using Emacs\(cq table\-mode
|
|
(\f[CR]M\-x table\-insert\f[R]).
|
|
.SS Extension: \f[CR]pipe_tables\f[R]
|
|
Pipe tables look like this:
|
|
.IP
|
|
.EX
|
|
| Right | Left | Default | Center |
|
|
|\-\-\-\-\-\-:|:\-\-\-\-\-|\-\-\-\-\-\-\-\-\-|:\-\-\-\-\-\-:|
|
|
| 12 | 12 | 12 | 12 |
|
|
| 123 | 123 | 123 | 123 |
|
|
| 1 | 1 | 1 | 1 |
|
|
|
|
: Demonstration of pipe table syntax.
|
|
.EE
|
|
.PP
|
|
The syntax is identical to PHP Markdown Extra tables.
|
|
The beginning and ending pipe characters are optional, but pipes are
|
|
required between all columns.
|
|
The colons indicate column alignment as shown.
|
|
The header cannot be omitted.
|
|
To simulate a headerless table, include a header with blank cells.
|
|
.PP
|
|
Since the pipes indicate column boundaries, columns need not be
|
|
vertically aligned, as they are in the above example.
|
|
So, this is a perfectly legal (though ugly) pipe table:
|
|
.IP
|
|
.EX
|
|
fruit| price
|
|
\-\-\-\-\-|\-\-\-\-\-:
|
|
apple|2.05
|
|
pear|1.37
|
|
orange|3.09
|
|
.EE
|
|
.PP
|
|
The cells of pipe tables cannot contain block elements like paragraphs
|
|
and lists, and cannot span multiple lines.
|
|
If any line of the Markdown source is longer than the column width (see
|
|
\f[CR]\-\-columns\f[R]), then the table will take up the full text width
|
|
and the cell contents will wrap, with the relative cell widths
|
|
determined by the number of dashes in the line separating the table
|
|
header from the table body.
|
|
(For example \f[CR]\-\-\-|\-\f[R] would make the first column 3/4 and
|
|
the second column 1/4 of the full text width.)
|
|
On the other hand, if no lines are wider than column width, then cell
|
|
contents will not be wrapped, and the cells will be sized to their
|
|
contents.
|
|
.PP
|
|
Note: pandoc also recognizes pipe tables of the following form, as can
|
|
be produced by Emacs\(cq orgtbl\-mode:
|
|
.IP
|
|
.EX
|
|
| One | Two |
|
|
|\-\-\-\-\-+\-\-\-\-\-\-\-|
|
|
| my | table |
|
|
| is | nice |
|
|
.EE
|
|
.PP
|
|
The difference is that \f[CR]+\f[R] is used instead of \f[CR]|\f[R].
|
|
Other orgtbl features are not supported.
|
|
In particular, to get non\-default column alignment, you\(cqll need to
|
|
add colons as above.
|
|
.SS Extension: \f[CR]table_attributes\f[R]
|
|
Attributes may be attached to tables by including them at the end of the
|
|
caption.
|
|
(For the syntax, see \f[CR]header_attributes\f[R].)
|
|
.IP
|
|
.EX
|
|
: Here\(aqs the caption. {#ident .class key=\(dqvalue\(dq}
|
|
.EE
|
|
.SS Table placement in LaTeX
|
|
By default, pandoc will render tables in LaTeX using the
|
|
\f[CR]longtable\f[R] environment.
|
|
The tables will not \(lqfloat\(rq and they can span page boundaries.
|
|
If you prefer standard \(lqfloating\(rq tables (which are limited to
|
|
what can fit on one page), add the \f[CR]float\f[R] class to the
|
|
table\(cqs attributes (which can be specified after the caption).
|
|
Optionally, the \f[CR]latex\-placement\f[R] attribute may be used to
|
|
pass parameters affecting the float placement:
|
|
.IP
|
|
.EX
|
|
: The caption of the table. {#ident .float latex\-placement=\(dqht\(dq}
|
|
.EE
|
|
.PP
|
|
Note that \f[CR]longtable\f[R] does not work with two\-column layouts,
|
|
so if you are producing a two\-column document using LaTeX, you will
|
|
need to specify the \f[CR]float\f[R] class on every table, or use this
|
|
small Lua filter to add it automatically:
|
|
.IP
|
|
.EX
|
|
\f[B]function\f[R] Table(el)
|
|
el.classes:insert(\(dqfloat\(dq)
|
|
\f[B]return\f[R] el
|
|
\f[B]end\f[R]
|
|
.EE
|
|
.SS Metadata blocks
|
|
.SS Extension: \f[CR]pandoc_title_block\f[R]
|
|
If the file begins with a title block
|
|
.IP
|
|
.EX
|
|
% title
|
|
% author(s) (separated by semicolons)
|
|
% date
|
|
.EE
|
|
.PP
|
|
it will be parsed as bibliographic information, not regular text.
|
|
(It will be used, for example, in the title of standalone LaTeX or HTML
|
|
output.)
|
|
The block may contain just a title, a date and an author, or all three
|
|
elements.
|
|
If you want to include an author but no title, or a title and a date but
|
|
no author, you need a blank line:
|
|
.IP
|
|
.EX
|
|
%
|
|
% Author
|
|
.EE
|
|
.IP
|
|
.EX
|
|
% My title
|
|
%
|
|
% June 15, 2006
|
|
.EE
|
|
.PP
|
|
The title may occupy multiple lines, but continuation lines must begin
|
|
with leading space, thus:
|
|
.IP
|
|
.EX
|
|
% My title
|
|
on multiple lines
|
|
.EE
|
|
.PP
|
|
If a document has multiple authors, the authors may be put on separate
|
|
lines with leading space, or separated by semicolons, or both.
|
|
So, all of the following are equivalent:
|
|
.IP
|
|
.EX
|
|
% Author One
|
|
Author Two
|
|
.EE
|
|
.IP
|
|
.EX
|
|
% Author One; Author Two
|
|
.EE
|
|
.IP
|
|
.EX
|
|
% Author One;
|
|
Author Two
|
|
.EE
|
|
.PP
|
|
The date must fit on one line.
|
|
.PP
|
|
All three metadata fields may contain standard inline formatting
|
|
(italics, links, footnotes, etc.).
|
|
.PP
|
|
Title blocks will always be parsed, but they will affect the output only
|
|
when the \f[CR]\-\-standalone\f[R] (\f[CR]\-s\f[R]) option is chosen.
|
|
In HTML output, titles will appear twice: once in the document
|
|
head\(emthis is the title that will appear at the top of the window in a
|
|
browser\(emand once at the beginning of the document body.
|
|
The title in the document head can have an optional prefix attached
|
|
(\f[CR]\-\-title\-prefix\f[R] or \f[CR]\-T\f[R] option).
|
|
The title in the body appears as an H1 element with class \(lqtitle\(rq,
|
|
so it can be suppressed or reformatted with CSS.
|
|
If a title prefix is specified with \f[CR]\-T\f[R] and no title block
|
|
appears in the document, the title prefix will be used by itself as the
|
|
HTML title.
|
|
.PP
|
|
The man page writer extracts a title, man page section number, and other
|
|
header and footer information from the title line.
|
|
The title is assumed to be the first word on the title line, which may
|
|
optionally end with a (single\-digit) section number in parentheses.
|
|
(There should be no space between the title and the parentheses.)
|
|
Anything after this is assumed to be additional footer and header text.
|
|
A single pipe character (\f[CR]|\f[R]) should be used to separate the
|
|
footer text from the header text.
|
|
Thus,
|
|
.IP
|
|
.EX
|
|
% PANDOC(1)
|
|
.EE
|
|
.PP
|
|
will yield a man page with the title \f[CR]PANDOC\f[R] and section 1.
|
|
.IP
|
|
.EX
|
|
% PANDOC(1) Pandoc User Manuals
|
|
.EE
|
|
.PP
|
|
will also have \(lqPandoc User Manuals\(rq in the footer.
|
|
.IP
|
|
.EX
|
|
% PANDOC(1) Pandoc User Manuals | Version 4.0
|
|
.EE
|
|
.PP
|
|
will also have \(lqVersion 4.0\(rq in the header.
|
|
.SS Extension: \f[CR]yaml_metadata_block\f[R]
|
|
A YAML metadata block is a valid YAML object, delimited by a line of
|
|
three hyphens (\f[CR]\-\-\-\f[R]) at the top and a line of three hyphens
|
|
(\f[CR]\-\-\-\f[R]) or three dots (\f[CR]...\f[R]) at the bottom.
|
|
The initial line \f[CR]\-\-\-\f[R] must not be followed by a blank line.
|
|
A YAML metadata block may occur anywhere in the document, but if it is
|
|
not at the beginning, it must be preceded by a blank line.
|
|
(Note that JSON may be used as well, because JSON is a subset of YAML.)
|
|
.PP
|
|
Note that, because of the way pandoc concatenates input files when
|
|
several are provided, you may also keep the metadata in a separate YAML
|
|
file and pass it to pandoc as an argument, along with your Markdown
|
|
files:
|
|
.IP
|
|
.EX
|
|
pandoc chap1.md chap2.md chap3.md metadata.yaml \-s \-o book.html
|
|
.EE
|
|
.PP
|
|
Just be sure that the YAML file begins with \f[CR]\-\-\-\f[R] and ends
|
|
with \f[CR]\-\-\-\f[R] or \f[CR]...\f[R].
|
|
Alternatively, you can use the \f[CR]\-\-metadata\-file\f[R] option.
|
|
Using that approach however, you cannot reference content (like
|
|
footnotes) from the main Markdown input document.
|
|
.PP
|
|
Metadata will be taken from the fields of the YAML object and added to
|
|
any existing document metadata.
|
|
Metadata can contain lists and objects (nested arbitrarily), but all
|
|
string scalars will be interpreted as Markdown.
|
|
Fields with names ending in an underscore will be ignored by pandoc.
|
|
(They may be given a role by external processors.)
|
|
Field names must not be interpretable as YAML numbers or boolean values
|
|
(so, for example, \f[CR]yes\f[R], \f[CR]True\f[R], and \f[CR]15\f[R]
|
|
cannot be used as field names).
|
|
.PP
|
|
A document may contain multiple metadata blocks.
|
|
If two metadata blocks attempt to set the same field, the value from the
|
|
second block will be taken.
|
|
.PP
|
|
Each metadata block is handled internally as an independent YAML
|
|
document.
|
|
This means, for example, that any YAML anchors defined in a block cannot
|
|
be referenced in another block.
|
|
.PP
|
|
When pandoc is used with \f[CR]\-t markdown\f[R] to create a Markdown
|
|
document, a YAML metadata block will be produced only if the
|
|
\f[CR]\-s/\-\-standalone\f[R] option is used.
|
|
All of the metadata will appear in a single block at the beginning of
|
|
the document.
|
|
.PP
|
|
Note that YAML escaping rules must be followed.
|
|
Thus, for example, if a title contains a colon, it must be quoted, and
|
|
if it contains a backslash escape, then it must be ensured that it is
|
|
not treated as a YAML escape sequence.
|
|
The pipe character (\f[CR]|\f[R]) can be used to begin an indented block
|
|
that will be interpreted literally, without need for escaping.
|
|
This form is necessary when the field contains blank lines or
|
|
block\-level formatting:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
title: \(aqThis is the title: it contains a colon\(aq
|
|
author:
|
|
\- Author One
|
|
\- Author Two
|
|
keywords: [nothing, nothingness]
|
|
abstract: |
|
|
This is the abstract.
|
|
|
|
It consists of two paragraphs.
|
|
\&...
|
|
.EE
|
|
.PP
|
|
The literal block after the \f[CR]|\f[R] must be indented relative to
|
|
the line containing the \f[CR]|\f[R].
|
|
If it is not, the YAML will be invalid and pandoc will not interpret it
|
|
as metadata.
|
|
For an overview of the complex rules governing YAML, see the Wikipedia
|
|
entry on YAML syntax.
|
|
.PP
|
|
Template variables will be set automatically from the metadata.
|
|
Thus, for example, in writing HTML, the variable \f[CR]abstract\f[R]
|
|
will be set to the HTML equivalent of the Markdown in the
|
|
\f[CR]abstract\f[R] field:
|
|
.IP
|
|
.EX
|
|
<p>This is the abstract.</p>
|
|
<p>It consists of two paragraphs.</p>
|
|
.EE
|
|
.PP
|
|
Variables can contain arbitrary YAML structures, but the template must
|
|
match this structure.
|
|
The \f[CR]author\f[R] variable in the default templates expects a simple
|
|
list or string, but can be changed to support more complicated
|
|
structures.
|
|
The following combination, for example, would add an affiliation to the
|
|
author if one is given:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
title: The document title
|
|
author:
|
|
\- name: Author One
|
|
affiliation: University of Somewhere
|
|
\- name: Author Two
|
|
affiliation: University of Nowhere
|
|
\&...
|
|
.EE
|
|
.PP
|
|
To use the structured authors in the example above, you would need a
|
|
custom template:
|
|
.IP
|
|
.EX
|
|
$for(author)$
|
|
$if(author.name)$
|
|
$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
|
|
$else$
|
|
$author$
|
|
$endif$
|
|
$endfor$
|
|
.EE
|
|
.PP
|
|
Raw content to include in the document\(cqs header may be specified
|
|
using \f[CR]header\-includes\f[R]; however, it is important to mark up
|
|
this content as raw code for a particular output format, using the
|
|
\f[CR]raw_attribute\f[R] extension, or it will be interpreted as
|
|
Markdown.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
header\-includes:
|
|
\- |
|
|
\(ga\(ga\(ga{=latex}
|
|
\(rslet\(rsoldsection\(rssection
|
|
\(rsrenewcommand{\(rssection}[1]{\(rsclearpage\(rsoldsection{#1}}
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.PP
|
|
Note: the \f[CR]yaml_metadata_block\f[R] extension works not just with
|
|
\f[CR]markdown\f[R] but with \f[CR]commonmark\f[R] (and it is enabled by
|
|
default in \f[CR]gfm\f[R] and \f[CR]commonmark_x\f[R]).
|
|
However, in \f[CR]commonmark\f[R], \f[CR]gfm\f[R], and
|
|
\f[CR]commonmark_x\f[R], the following restrictions apply:
|
|
.IP \(bu 2
|
|
The YAML metadata block must occur at the beginning of the document (and
|
|
there can be only one).
|
|
If multiple files are given as arguments to pandoc, only the first can
|
|
be a YAML metadata block.
|
|
.IP \(bu 2
|
|
The leaf nodes of the YAML structure are parsed in isolation from each
|
|
other and from the rest of the document.
|
|
So, for example, you can\(cqt use a reference link in these contexts if
|
|
the link definition is somewhere else in the document.
|
|
.SS Backslash escapes
|
|
.SS Extension: \f[CR]all_symbols_escapable\f[R]
|
|
Except inside a code block or inline code, any punctuation or space
|
|
character preceded by a backslash will be treated literally, even if it
|
|
would normally indicate formatting.
|
|
Thus, for example, if one writes
|
|
.IP
|
|
.EX
|
|
*\(rs*hello\(rs**
|
|
.EE
|
|
.PP
|
|
one will get
|
|
.IP
|
|
.EX
|
|
<em>*hello*</em>
|
|
.EE
|
|
.PP
|
|
instead of
|
|
.IP
|
|
.EX
|
|
<strong>hello</strong>
|
|
.EE
|
|
.PP
|
|
This rule is easier to remember than original Markdown\(cqs rule, which
|
|
allows only the following characters to be backslash\-escaped:
|
|
.IP
|
|
.EX
|
|
\(rs\(ga*_{}[]()>#+\-.!
|
|
.EE
|
|
.PP
|
|
(However, if the \f[CR]markdown_strict\f[R] format is used, the original
|
|
Markdown rule will be used.)
|
|
.PP
|
|
A backslash\-escaped space is parsed as a nonbreaking space.
|
|
In TeX output, it will appear as \f[CR]\(ti\f[R].
|
|
In HTML and XML output, it will appear as a literal unicode nonbreaking
|
|
space character (note that it will thus actually look \(lqinvisible\(rq
|
|
in the generated HTML source; you can still use the \f[CR]\-\-ascii\f[R]
|
|
command\-line option to make it appear as an explicit entity).
|
|
.PP
|
|
A backslash\-escaped newline (i.e.\ a backslash occurring at the end of
|
|
a line) is parsed as a hard line break.
|
|
It will appear in TeX output as \f[CR]\(rs\(rs\f[R] and in HTML as
|
|
\f[CR]<br />\f[R].
|
|
This is a nice alternative to Markdown\(cqs \(lqinvisible\(rq way of
|
|
indicating hard line breaks using two trailing spaces on a line.
|
|
.PP
|
|
Backslash escapes do not work in verbatim contexts.
|
|
.SS Inline formatting
|
|
.SS Emphasis
|
|
To \f[I]emphasize\f[R] some text, surround it with \f[CR]*\f[R]s or
|
|
\f[CR]_\f[R], like this:
|
|
.IP
|
|
.EX
|
|
This text is _emphasized with underscores_, and this
|
|
is *emphasized with asterisks*.
|
|
.EE
|
|
.PP
|
|
Double \f[CR]*\f[R] or \f[CR]_\f[R] produces \f[B]strong emphasis\f[R]:
|
|
.IP
|
|
.EX
|
|
This is **strong emphasis** and __with underscores__.
|
|
.EE
|
|
.PP
|
|
A \f[CR]*\f[R] or \f[CR]_\f[R] character surrounded by spaces, or
|
|
backslash\-escaped, will not trigger emphasis:
|
|
.IP
|
|
.EX
|
|
This is * not emphasized *, and \(rs*neither is this\(rs*.
|
|
.EE
|
|
.SS Extension: \f[CR]intraword_underscores\f[R]
|
|
Because \f[CR]_\f[R] is sometimes used inside words and identifiers,
|
|
pandoc does not interpret a \f[CR]_\f[R] surrounded by alphanumeric
|
|
characters as an emphasis marker.
|
|
If you want to emphasize just part of a word, use \f[CR]*\f[R]:
|
|
.IP
|
|
.EX
|
|
feas*ible*, not feas*able*.
|
|
.EE
|
|
.SS Strikeout
|
|
.SS Extension: \f[CR]strikeout\f[R]
|
|
To strike out a section of text with a horizontal line, begin and end it
|
|
with \f[CR]\(ti\(ti\f[R].
|
|
Thus, for example,
|
|
.IP
|
|
.EX
|
|
This \(ti\(tiis deleted text.\(ti\(ti
|
|
.EE
|
|
.SS Superscripts and subscripts
|
|
.SS Extension: \f[CR]superscript\f[R], \f[CR]subscript\f[R]
|
|
Superscripts may be written by surrounding the superscripted text by
|
|
\f[CR]\(ha\f[R] characters; subscripts may be written by surrounding the
|
|
subscripted text by \f[CR]\(ti\f[R] characters.
|
|
Thus, for example,
|
|
.IP
|
|
.EX
|
|
H\(ti2\(tiO is a liquid. 2\(ha10\(ha is 1024.
|
|
.EE
|
|
.PP
|
|
The text between \f[CR]\(ha...\(ha\f[R] or \f[CR]\(ti...\(ti\f[R] may
|
|
not contain spaces or newlines.
|
|
If the superscripted or subscripted text contains spaces, these spaces
|
|
must be escaped with backslashes.
|
|
(This is to prevent accidental superscripting and subscripting through
|
|
the ordinary use of \f[CR]\(ti\f[R] and \f[CR]\(ha\f[R], and also bad
|
|
interactions with footnotes.)
|
|
Thus, if you want the letter P with `a cat' in subscripts, use
|
|
\f[CR]P\(tia\(rs cat\(ti\f[R], not \f[CR]P\(tia cat\(ti\f[R].
|
|
.SS Verbatim
|
|
To make a short span of text verbatim, put it inside backticks:
|
|
.IP
|
|
.EX
|
|
What is the difference between \(ga>>=\(ga and \(ga>>\(ga?
|
|
.EE
|
|
.PP
|
|
If the verbatim text includes a backtick, use double backticks:
|
|
.IP
|
|
.EX
|
|
Here is a literal backtick \(ga\(ga \(ga \(ga\(ga.
|
|
.EE
|
|
.PP
|
|
(The spaces after the opening backticks and before the closing backticks
|
|
will be ignored.)
|
|
.PP
|
|
The general rule is that a verbatim span starts with a string of
|
|
consecutive backticks (optionally followed by a space) and ends with a
|
|
string of the same number of backticks (optionally preceded by a space).
|
|
.PP
|
|
Note that backslash\-escapes (and other Markdown constructs) do not work
|
|
in verbatim contexts:
|
|
.IP
|
|
.EX
|
|
This is a backslash followed by an asterisk: \(ga\(rs*\(ga.
|
|
.EE
|
|
.SS Extension: \f[CR]inline_code_attributes\f[R]
|
|
Attributes can be attached to verbatim text, just as with fenced code
|
|
blocks:
|
|
.IP
|
|
.EX
|
|
\(ga<$>\(ga{.haskell}
|
|
.EE
|
|
.SS Underline
|
|
To underline text, use the \f[CR]underline\f[R] class:
|
|
.IP
|
|
.EX
|
|
[Underline]{.underline}
|
|
.EE
|
|
.PP
|
|
Or, without the \f[CR]bracketed_spans\f[R] extension (but with
|
|
\f[CR]native_spans\f[R]):
|
|
.IP
|
|
.EX
|
|
<span class=\(dqunderline\(dq>Underline</span>
|
|
.EE
|
|
.PP
|
|
This will work in all output formats that support underline.
|
|
.SS Small caps
|
|
To write small caps, use the \f[CR]smallcaps\f[R] class:
|
|
.IP
|
|
.EX
|
|
[Small caps]{.smallcaps}
|
|
.EE
|
|
.PP
|
|
Or, without the \f[CR]bracketed_spans\f[R] extension:
|
|
.IP
|
|
.EX
|
|
<span class=\(dqsmallcaps\(dq>Small caps</span>
|
|
.EE
|
|
.PP
|
|
For compatibility with other Markdown flavors, CSS is also supported:
|
|
.IP
|
|
.EX
|
|
<span style=\(dqfont\-variant:small\-caps;\(dq>Small caps</span>
|
|
.EE
|
|
.PP
|
|
This will work in all output formats that support small caps.
|
|
.SS Highlighting
|
|
To highlight text, use the \f[CR]mark\f[R] class:
|
|
.IP
|
|
.EX
|
|
[Mark]{.mark}
|
|
.EE
|
|
.PP
|
|
Or, without the \f[CR]bracketed_spans\f[R] extension (but with
|
|
\f[CR]native_spans\f[R]):
|
|
.IP
|
|
.EX
|
|
<span class=\(dqmark\(dq>Mark</span>
|
|
.EE
|
|
.PP
|
|
This will work in all output formats that support highlighting.
|
|
.SS Math
|
|
.SS Extension: \f[CR]tex_math_dollars\f[R]
|
|
Anything between two \f[CR]$\f[R] characters will be treated as TeX
|
|
math.
|
|
The opening \f[CR]$\f[R] must have a non\-space character immediately to
|
|
its right, while the closing \f[CR]$\f[R] must have a non\-space
|
|
character immediately to its left, and must not be followed immediately
|
|
by a digit.
|
|
Thus, \f[CR]$20,000 and $30,000\f[R] won\(cqt parse as math.
|
|
If for some reason you need to enclose text in literal \f[CR]$\f[R]
|
|
characters, backslash\-escape them and they won\(cqt be treated as math
|
|
delimiters.
|
|
.PP
|
|
For display math, use \f[CR]$$\f[R] delimiters.
|
|
(In this case, the delimiters may be separated from the formula by
|
|
whitespace.
|
|
However, there can be no blank lines between the opening and closing
|
|
\f[CR]$$\f[R] delimiters.)
|
|
.PP
|
|
TeX math will be printed in all output formats.
|
|
How it is rendered depends on the output format:
|
|
.TP
|
|
LaTeX
|
|
It will appear verbatim surrounded by \f[CR]\(rs(...\(rs)\f[R] (for
|
|
inline math) or \f[CR]\(rs[...\(rs]\f[R] (for display math).
|
|
.TP
|
|
Markdown, Emacs Org mode, ConTeXt, Txt2Tags, ZimWiki
|
|
It will appear verbatim surrounded by \f[CR]$...$\f[R] (for inline math)
|
|
or \f[CR]$$...$$\f[R] (for display math).
|
|
.TP
|
|
XWiki
|
|
It will appear verbatim surrounded by
|
|
\f[CR]{{formula}}..{{/formula}}\f[R].
|
|
.TP
|
|
reStructuredText
|
|
It will be rendered using an interpreted text role \f[CR]:math:\f[R].
|
|
.TP
|
|
AsciiDoc
|
|
For AsciiDoc output math will appear verbatim surrounded by
|
|
\f[CR]latexmath:[...]\f[R].
|
|
For \f[CR]asciidoc_legacy\f[R] the bracketed material will also include
|
|
inline or display math delimiters.
|
|
.TP
|
|
Texinfo
|
|
It will be rendered inside a \f[CR]\(atmath\f[R] command.
|
|
.TP
|
|
roff man, Jira markup
|
|
It will be rendered verbatim without \f[CR]$\f[R]\(cqs.
|
|
.TP
|
|
MediaWiki, DokuWiki
|
|
It will be rendered inside \f[CR]<math>\f[R] tags.
|
|
.TP
|
|
Textile
|
|
It will be rendered inside \f[CR]<span class=\(dqmath\(dq>\f[R] tags.
|
|
.TP
|
|
RTF, OpenDocument
|
|
It will be rendered, if possible, using Unicode characters, and will
|
|
otherwise appear verbatim.
|
|
.TP
|
|
ODT
|
|
It will be rendered, if possible, using MathML.
|
|
.TP
|
|
DocBook
|
|
If the \f[CR]\-\-mathml\f[R] flag is used, it will be rendered using
|
|
MathML in an \f[CR]inlineequation\f[R] or \f[CR]informalequation\f[R]
|
|
tag.
|
|
Otherwise it will be rendered, if possible, using Unicode characters.
|
|
.TP
|
|
Docx and PowerPoint
|
|
It will be rendered using OMML math markup.
|
|
.TP
|
|
FictionBook2
|
|
If the \f[CR]\-\-webtex\f[R] option is used, formulas are rendered as
|
|
images using CodeCogs or other compatible web service, downloaded and
|
|
embedded in the e\-book.
|
|
Otherwise, they will appear verbatim.
|
|
.TP
|
|
HTML, Slidy, DZSlides, S5, EPUB
|
|
The way math is rendered in HTML will depend on the command\-line
|
|
options selected.
|
|
Therefore see Math rendering in HTML above.
|
|
.SS Raw HTML
|
|
.SS Extension: \f[CR]raw_html\f[R]
|
|
Markdown allows you to insert raw HTML (or DocBook) anywhere in a
|
|
document (except verbatim contexts, where \f[CR]<\f[R], \f[CR]>\f[R],
|
|
and \f[CR]&\f[R] are interpreted literally).
|
|
(Technically this is not an extension, since standard Markdown allows
|
|
it, but it has been made an extension so that it can be disabled if
|
|
desired.)
|
|
.PP
|
|
The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
|
|
DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, Textile, and
|
|
Txt2Tags output, and suppressed in other formats.
|
|
.PP
|
|
For a more explicit way of including raw HTML in a Markdown document,
|
|
see the \f[CR]raw_attribute\f[R] extension.
|
|
.PP
|
|
In the CommonMark format, if \f[CR]raw_html\f[R] is enabled,
|
|
superscripts, subscripts, strikeouts and small capitals will be
|
|
represented as HTML.
|
|
Otherwise, plain\-text fallbacks will be used.
|
|
Note that even if \f[CR]raw_html\f[R] is disabled, tables will be
|
|
rendered with HTML syntax if they cannot use pipe syntax.
|
|
.SS Extension: \f[CR]markdown_in_html_blocks\f[R]
|
|
Original Markdown allows you to include HTML \(lqblocks\(rq: blocks of
|
|
HTML between balanced tags that are separated from the surrounding text
|
|
with blank lines, and start and end at the left margin.
|
|
Within these blocks, everything is interpreted as HTML, not Markdown; so
|
|
(for example), \f[CR]*\f[R] does not signify emphasis.
|
|
.PP
|
|
Pandoc behaves this way when the \f[CR]markdown_strict\f[R] format is
|
|
used; but by default, pandoc interprets material between HTML block tags
|
|
as Markdown.
|
|
Thus, for example, pandoc will turn
|
|
.IP
|
|
.EX
|
|
<table>
|
|
<tr>
|
|
<td>*one*</td>
|
|
<td>[a link](https://google.com)</td>
|
|
</tr>
|
|
</table>
|
|
.EE
|
|
.PP
|
|
into
|
|
.IP
|
|
.EX
|
|
<table>
|
|
<tr>
|
|
<td><em>one</em></td>
|
|
<td><a href=\(dqhttps://google.com\(dq>a link</a></td>
|
|
</tr>
|
|
</table>
|
|
.EE
|
|
.PP
|
|
whereas \f[CR]Markdown.pl\f[R] will preserve it as is.
|
|
.PP
|
|
There is one exception to this rule: text between \f[CR]<script>\f[R],
|
|
\f[CR]<style>\f[R], \f[CR]<pre>\f[R], and \f[CR]<textarea>\f[R] tags is
|
|
not interpreted as Markdown.
|
|
.PP
|
|
This departure from original Markdown should make it easier to mix
|
|
Markdown with HTML block elements.
|
|
For example, one can surround a block of Markdown text with
|
|
\f[CR]<div>\f[R] tags without preventing it from being interpreted as
|
|
Markdown.
|
|
.SS Extension: \f[CR]native_divs\f[R]
|
|
Use native pandoc \f[CR]Div\f[R] blocks for content inside
|
|
\f[CR]<div>\f[R] tags.
|
|
For the most part this should give the same output as
|
|
\f[CR]markdown_in_html_blocks\f[R], but it makes it easier to write
|
|
pandoc filters to manipulate groups of blocks.
|
|
.SS Extension: \f[CR]native_spans\f[R]
|
|
Use native pandoc \f[CR]Span\f[R] blocks for content inside
|
|
\f[CR]<span>\f[R] tags.
|
|
For the most part this should give the same output as
|
|
\f[CR]raw_html\f[R], but it makes it easier to write pandoc filters to
|
|
manipulate groups of inlines.
|
|
.SS Extension: \f[CR]raw_tex\f[R]
|
|
In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
|
|
included in a document.
|
|
Inline TeX commands will be preserved and passed unchanged to the LaTeX
|
|
and ConTeXt writers.
|
|
Thus, for example, you can use LaTeX to include BibTeX citations:
|
|
.IP
|
|
.EX
|
|
This result was proved in \(rscite{jones.1967}.
|
|
.EE
|
|
.PP
|
|
Note that in LaTeX environments, like
|
|
.IP
|
|
.EX
|
|
\(rsbegin{tabular}{|l|l|}\(rshline
|
|
Age & Frequency \(rs\(rs \(rshline
|
|
18\-\-25 & 15 \(rs\(rs
|
|
26\-\-35 & 33 \(rs\(rs
|
|
36\-\-45 & 22 \(rs\(rs \(rshline
|
|
\(rsend{tabular}
|
|
.EE
|
|
.PP
|
|
the material between the begin and end tags will be interpreted as raw
|
|
LaTeX, not as Markdown.
|
|
.PP
|
|
For a more explicit and flexible way of including raw TeX in a Markdown
|
|
document, see the \f[CR]raw_attribute\f[R] extension.
|
|
.PP
|
|
Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
|
|
Emacs Org mode, and ConTeXt.
|
|
.SS Generic raw attribute
|
|
.SS Extension: \f[CR]raw_attribute\f[R]
|
|
Inline spans and fenced code blocks with a special kind of attribute
|
|
will be parsed as raw content with the designated format.
|
|
For example, the following produces a raw roff \f[CR]ms\f[R] block:
|
|
.IP
|
|
.EX
|
|
\(ga\(ga\(ga{=ms}
|
|
\&.MYMACRO
|
|
blah blah
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.PP
|
|
And the following produces a raw \f[CR]html\f[R] inline element:
|
|
.IP
|
|
.EX
|
|
This is \(ga<a>html</a>\(ga{=html}
|
|
.EE
|
|
.PP
|
|
This can be useful to insert raw xml into \f[CR]docx\f[R] documents,
|
|
e.g.
|
|
a pagebreak:
|
|
.IP
|
|
.EX
|
|
\(ga\(ga\(ga{=openxml}
|
|
<w:p>
|
|
<w:r>
|
|
<w:br w:type=\(dqpage\(dq/>
|
|
</w:r>
|
|
</w:p>
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.PP
|
|
The format name should match the target format name (see
|
|
\f[CR]\-t/\-\-to\f[R], above, for a list, or use
|
|
\f[CR]pandoc \-\-list\-output\-formats\f[R]).
|
|
Use \f[CR]openxml\f[R] for \f[CR]docx\f[R] output,
|
|
\f[CR]opendocument\f[R] for \f[CR]odt\f[R] output, \f[CR]html5\f[R] for
|
|
\f[CR]epub3\f[R] output, \f[CR]html4\f[R] for \f[CR]epub2\f[R] output,
|
|
and \f[CR]latex\f[R], \f[CR]beamer\f[R], \f[CR]ms\f[R], or
|
|
\f[CR]html5\f[R] for \f[CR]pdf\f[R] output (depending on what you use
|
|
for \f[CR]\-\-pdf\-engine\f[R]).
|
|
.PP
|
|
This extension presupposes that the relevant kind of inline code or
|
|
fenced code block is enabled.
|
|
Thus, for example, to use a raw attribute with a backtick code block,
|
|
\f[CR]backtick_code_blocks\f[R] must be enabled.
|
|
.PP
|
|
The raw attribute cannot be combined with regular attributes.
|
|
.SS LaTeX macros
|
|
.SS Extension: \f[CR]latex_macros\f[R]
|
|
When this extension is enabled, pandoc will parse LaTeX macro
|
|
definitions and apply the resulting macros to all LaTeX math and raw
|
|
LaTeX.
|
|
So, for example, the following will work in all output formats, not just
|
|
LaTeX:
|
|
.IP
|
|
.EX
|
|
\(rsnewcommand{\(rstuple}[1]{\(rslangle #1 \(rsrangle}
|
|
|
|
$\(rstuple{a, b, c}$
|
|
.EE
|
|
.PP
|
|
Note that LaTeX macros will not be applied if they occur inside a raw
|
|
span or block marked with the \f[CR]raw_attribute\f[R] extension.
|
|
.PP
|
|
When \f[CR]latex_macros\f[R] is disabled, the raw LaTeX and math will
|
|
not have macros applied.
|
|
This is usually a better approach when you are targeting LaTeX or PDF.
|
|
.PP
|
|
Macro definitions in LaTeX will be passed through as raw LaTeX only if
|
|
\f[CR]latex_macros\f[R] is not enabled.
|
|
Macro definitions in Markdown source (or other formats allowing
|
|
\f[CR]raw_tex\f[R]) will be passed through regardless of whether
|
|
\f[CR]latex_macros\f[R] is enabled.
|
|
.SS Links
|
|
Markdown allows links to be specified in several ways.
|
|
.SS Automatic links
|
|
If you enclose a URL or email address in pointy brackets, it will become
|
|
a link:
|
|
.IP
|
|
.EX
|
|
<https://google.com>
|
|
<sam\(atgreen.eggs.ham>
|
|
.EE
|
|
.SS Inline links
|
|
An inline link consists of the link text in square brackets, followed by
|
|
the URL in parentheses.
|
|
(Optionally, the URL can be followed by a link title, in quotes.)
|
|
.IP
|
|
.EX
|
|
This is an [inline link](/url), and here\(aqs [one with
|
|
a title](https://fsf.org \(dqclick here for a good time!\(dq).
|
|
.EE
|
|
.PP
|
|
There can be no space between the bracketed part and the parenthesized
|
|
part.
|
|
The link text can contain formatting (such as emphasis), but the title
|
|
cannot.
|
|
.PP
|
|
Email addresses in inline links are not autodetected, so they have to be
|
|
prefixed with \f[CR]mailto\f[R]:
|
|
.IP
|
|
.EX
|
|
[Write me!](mailto:sam\(atgreen.eggs.ham)
|
|
.EE
|
|
.SS Reference links
|
|
An \f[I]explicit\f[R] reference link has two parts, the link itself and
|
|
the link definition, which may occur elsewhere in the document (either
|
|
before or after the link).
|
|
.PP
|
|
The link consists of link text in square brackets, followed by a label
|
|
in square brackets.
|
|
(There cannot be space between the two unless the
|
|
\f[CR]spaced_reference_links\f[R] extension is enabled.)
|
|
If the label is empty (\f[CR][]\f[R]), then it will be implicitly be
|
|
taken to be the same as the link text; thus \f[CR][foo][]\f[R] is
|
|
equivalent to \f[CR][foo][foo]\f[R].
|
|
(If the \f[CR]shortcut_reference_links\f[R] extension is enabled, the
|
|
empty \f[CR][]\f[R] may be omitted.)
|
|
.PP
|
|
The link definition consists of the bracketed label, followed by a colon
|
|
and a space, followed by the URL, and optionally (after a space) a link
|
|
title either in quotes or in parentheses.
|
|
The label must not be parseable as a citation (assuming the
|
|
\f[CR]citations\f[R] extension is enabled): citations take precedence
|
|
over link labels.
|
|
.PP
|
|
Here are some examples of reference links and link definitions;
|
|
.IP
|
|
.EX
|
|
See [the website *I* built][my website].
|
|
|
|
See [my website][] and [the bar page][1] and
|
|
the [home page of the FSF][fsf].
|
|
|
|
[my website]: http://foo.bar.baz
|
|
[1]: /foo/bar.html \(dqMy title, optional\(dq
|
|
[fsf]: https://fsf.org (The Free Software Foundation)
|
|
[special page]: /bar#special \(aqA title in single quotes\(aq
|
|
.EE
|
|
.PP
|
|
The URL in a link definition may optionally be surrounded by angle
|
|
brackets:
|
|
.IP
|
|
.EX
|
|
[my label 5]: <http://foo.bar.baz>
|
|
.EE
|
|
.PP
|
|
The title may go on the next line:
|
|
.IP
|
|
.EX
|
|
[my label 3]: https://fsf.org
|
|
\(dqThe Free Software Foundation\(dq
|
|
.EE
|
|
.PP
|
|
Note that link labels are not case sensitive.
|
|
So, this will work:
|
|
.IP
|
|
.EX
|
|
Here is [my link][FOO]
|
|
|
|
[Foo]: /bar/baz
|
|
.EE
|
|
.PP
|
|
The link definition may come either before or after a reference link
|
|
that uses the label.
|
|
.PP
|
|
Note: In some Markdown implementations, reference link definitions
|
|
cannot occur in nested constructions such as list items or block quotes.
|
|
Pandoc lifts this arbitrary\-seeming restriction.
|
|
So the following is fine in pandoc, though not in all implementations:
|
|
.IP
|
|
.EX
|
|
> My block [quote].
|
|
>
|
|
> [quote]: /foo
|
|
.EE
|
|
.SS Extension: \f[CR]shortcut_reference_links\f[R]
|
|
In a \f[I]shortcut\f[R] reference link, the second pair of brackets may
|
|
be omitted entirely:
|
|
.IP
|
|
.EX
|
|
See [my website].
|
|
|
|
[my website]: http://foo.bar.baz
|
|
.EE
|
|
.SS Internal links
|
|
To link to another section of the same document, use the automatically
|
|
generated identifier (see Heading identifiers).
|
|
For example:
|
|
.IP
|
|
.EX
|
|
See the [Introduction](#introduction).
|
|
.EE
|
|
.PP
|
|
or
|
|
.IP
|
|
.EX
|
|
See the [Introduction].
|
|
|
|
[Introduction]: #introduction
|
|
.EE
|
|
.PP
|
|
Internal links are currently supported for HTML formats (including HTML
|
|
slide shows and EPUB), LaTeX, and ConTeXt.
|
|
.SS Images
|
|
A link immediately preceded by a \f[CR]!\f[R] will be treated as an
|
|
image.
|
|
The link text (the part in square brackets) will be used as the
|
|
image\(cqs alt text:
|
|
.IP
|
|
.EX
|
|
|
|
|
|
![movie reel]
|
|
|
|
[movie reel]: movie.gif
|
|
.EE
|
|
.SS Extension: \f[CR]implicit_figures\f[R]
|
|
An image with nonempty alt text, occurring by itself in a paragraph,
|
|
will be rendered as a figure with a caption.
|
|
The image\(cqs description will be used as the caption.
|
|
.IP
|
|
.EX
|
|
|
|
.EE
|
|
.PP
|
|
How this is rendered depends on the output format.
|
|
Some output formats (e.g.\ RTF) do not yet support figures.
|
|
In those formats, you\(cqll just get an image in a paragraph by itself,
|
|
with no caption.
|
|
.PP
|
|
If you just want a regular inline image, just make sure it is not the
|
|
only thing in the paragraph.
|
|
One way to do this is to insert a nonbreaking space after the image:
|
|
.IP
|
|
.EX
|
|
\(rs
|
|
.EE
|
|
.PP
|
|
Note that in reveal.js slide shows, an image in a paragraph by itself
|
|
that has the \f[CR]r\-stretch\f[R] class will fill the screen, and the
|
|
caption and figure tags will be omitted.
|
|
.PP
|
|
To specify an alt text for the image that is different from the caption,
|
|
you can use an explicit attribute (assuming the
|
|
\f[CR]link_attributes\f[R] extension is set):
|
|
.IP
|
|
.EX
|
|
{alt=\(dqdescription of image\(dq}
|
|
.EE
|
|
.PP
|
|
For LaTeX output, you can specify a figure\(cqs positioning by adding
|
|
the \f[CR]latex\-placement\f[R] attribute.
|
|
.IP
|
|
.EX
|
|
{latex\-placement=\(dqht\(dq}
|
|
.EE
|
|
.SS Extension: \f[CR]link_attributes\f[R]
|
|
Attributes can be set on links and images:
|
|
.IP
|
|
.EX
|
|
An inline {#id .class width=30 height=20px}
|
|
and a reference ![image][ref] with attributes.
|
|
|
|
[ref]: foo.jpg \(dqoptional title\(dq {#id .class key=val key2=\(dqval 2\(dq}
|
|
.EE
|
|
.PP
|
|
(This syntax is compatible with PHP Markdown Extra when only
|
|
\f[CR]#id\f[R] and \f[CR].class\f[R] are used.)
|
|
.PP
|
|
For HTML and EPUB, all known HTML5 attributes except \f[CR]width\f[R]
|
|
and \f[CR]height\f[R] (but including \f[CR]srcset\f[R] and
|
|
\f[CR]sizes\f[R]) are passed through as is.
|
|
Unknown attributes are passed through as custom attributes, with
|
|
\f[CR]data\-\f[R] prepended.
|
|
The other writers ignore attributes that are not specifically supported
|
|
by their output format.
|
|
.PP
|
|
The \f[CR]width\f[R] and \f[CR]height\f[R] attributes on images are
|
|
treated specially.
|
|
When used without a unit, the unit is assumed to be pixels.
|
|
However, any of the following unit identifiers can be used:
|
|
\f[CR]px\f[R], \f[CR]cm\f[R], \f[CR]mm\f[R], \f[CR]in\f[R],
|
|
\f[CR]inch\f[R] and \f[CR]%\f[R].
|
|
There must not be any spaces between the number and the unit.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
{ width=50% }
|
|
.EE
|
|
.IP \(bu 2
|
|
Dimensions may be converted to a form that is compatible with the output
|
|
format (for example, dimensions given in pixels will be converted to
|
|
inches when converting HTML to LaTeX).
|
|
Conversion between pixels and physical measurements is affected by the
|
|
\f[CR]\-\-dpi\f[R] option (by default, 96 dpi is assumed, unless the
|
|
image itself contains dpi information).
|
|
.IP \(bu 2
|
|
The \f[CR]%\f[R] unit is generally relative to some available space.
|
|
For example the above example will render to the following.
|
|
.RS 2
|
|
.IP \(bu 2
|
|
HTML: \f[CR]<img href=\(dqfile.jpg\(dq style=\(dqwidth: 50%;\(dq />\f[R]
|
|
.IP \(bu 2
|
|
LaTeX:
|
|
\f[CR]\(rsincludegraphics[width=0.5\(rstextwidth,height=\(rstextheight]{file.jpg}\f[R]
|
|
(If you\(cqre using a custom template, you need to configure
|
|
\f[CR]graphicx\f[R] as in the default template.)
|
|
.IP \(bu 2
|
|
ConTeXt: \f[CR]\(rsexternalfigure[file.jpg][width=0.5\(rstextwidth]\f[R]
|
|
.RE
|
|
.IP \(bu 2
|
|
Some output formats have a notion of a class (ConTeXt) or a unique
|
|
identifier (LaTeX \f[CR]\(rscaption\f[R]), or both (HTML).
|
|
.IP \(bu 2
|
|
When no \f[CR]width\f[R] or \f[CR]height\f[R] attributes are specified,
|
|
the fallback is to look at the image resolution and the dpi metadata
|
|
embedded in the image file.
|
|
.SS Divs and Spans
|
|
Using the \f[CR]native_divs\f[R] and \f[CR]native_spans\f[R] extensions
|
|
(see above), HTML syntax can be used as part of Markdown to create
|
|
native \f[CR]Div\f[R] and \f[CR]Span\f[R] elements in the pandoc AST (as
|
|
opposed to raw HTML).
|
|
However, there is also nicer syntax available:
|
|
.SS Extension: \f[CR]fenced_divs\f[R]
|
|
Allow special fenced syntax for native \f[CR]Div\f[R] blocks.
|
|
A Div starts with a fence containing at least three consecutive colons
|
|
plus some attributes.
|
|
The attributes may optionally be followed by another string of
|
|
consecutive colons.
|
|
.PP
|
|
Note: the \f[CR]commonmark\f[R] parser doesn\(cqt permit colons after
|
|
the attributes.
|
|
.PP
|
|
The attribute syntax is exactly as in fenced code blocks (see Extension:
|
|
\f[CR]fenced_code_attributes\f[R]).
|
|
As with fenced code blocks, one can use either attributes in curly
|
|
braces or a single unbraced word, which will be treated as a class name.
|
|
The Div ends with another line containing a string of at least three
|
|
consecutive colons.
|
|
The fenced Div should be separated by blank lines from preceding and
|
|
following blocks.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
::::: {#special .sidebar}
|
|
Here is a paragraph.
|
|
|
|
And another.
|
|
:::::
|
|
.EE
|
|
.PP
|
|
Fenced divs can be nested.
|
|
Opening fences are distinguished because they \f[I]must\f[R] have
|
|
attributes:
|
|
.IP
|
|
.EX
|
|
::: Warning ::::::
|
|
This is a warning.
|
|
|
|
::: Danger
|
|
This is a warning within a warning.
|
|
:::
|
|
::::::::::::::::::
|
|
.EE
|
|
.PP
|
|
Fences without attributes are always closing fences.
|
|
Unlike with fenced code blocks, the number of colons in the closing
|
|
fence need not match the number in the opening fence.
|
|
However, it can be helpful for visual clarity to use fences of different
|
|
lengths to distinguish nested divs from their parents.
|
|
.SS Extension: \f[CR]bracketed_spans\f[R]
|
|
A bracketed sequence of inlines, as one would use to begin a link, will
|
|
be treated as a \f[CR]Span\f[R] with attributes if it is followed
|
|
immediately by attributes:
|
|
.IP
|
|
.EX
|
|
[This is *some text*]{.class key=\(dqval\(dq}
|
|
.EE
|
|
.SS Footnotes
|
|
.SS Extension: \f[CR]footnotes\f[R]
|
|
Pandoc\(cqs Markdown allows footnotes, using the following syntax:
|
|
.IP
|
|
.EX
|
|
Here is a footnote reference,[\(ha1] and another.[\(halongnote]
|
|
|
|
[\(ha1]: Here is the footnote.
|
|
|
|
[\(halongnote]: Here\(aqs one with multiple blocks.
|
|
|
|
Subsequent paragraphs are indented to show that they
|
|
belong to the previous footnote.
|
|
|
|
{ some.code }
|
|
|
|
The whole paragraph can be indented, or just the first
|
|
line. In this way, multi\-paragraph footnotes work like
|
|
multi\-paragraph list items.
|
|
|
|
This paragraph won\(aqt be part of the note, because it
|
|
isn\(aqt indented.
|
|
.EE
|
|
.PP
|
|
The identifiers in footnote references may not contain spaces, tabs,
|
|
newlines, or the characters \f[CR]\(ha\f[R], \f[CR][\f[R], or
|
|
\f[CR]]\f[R].
|
|
These identifiers are used only to correlate the footnote reference with
|
|
the note itself; in the output, footnotes will be numbered sequentially.
|
|
.PP
|
|
The footnotes themselves need not be placed at the end of the document.
|
|
They may appear anywhere except inside other block elements (lists,
|
|
block quotes, tables, etc.).
|
|
Each footnote should be separated from surrounding content (including
|
|
other footnotes) by blank lines.
|
|
.SS Extension: \f[CR]inline_notes\f[R]
|
|
Inline footnotes are also allowed (though, unlike regular notes, they
|
|
cannot contain multiple paragraphs).
|
|
The syntax is as follows:
|
|
.IP
|
|
.EX
|
|
Here is an inline note.\(ha[Inline notes are easier to write, since
|
|
you don\(aqt have to pick an identifier and move down to type the
|
|
note.]
|
|
.EE
|
|
.PP
|
|
Inline and regular footnotes may be mixed freely.
|
|
.SS Citation syntax
|
|
.SS Extension: \f[CR]citations\f[R]
|
|
To cite a bibliographic item with an identifier foo, use the syntax
|
|
\f[CR]\(atfoo\f[R].
|
|
Normal citations should be included in square brackets, with semicolons
|
|
separating distinct items:
|
|
.IP
|
|
.EX
|
|
Blah blah [\(atdoe99; \(atsmith2000; \(atsmith2004].
|
|
.EE
|
|
.PP
|
|
How this is rendered depends on the citation style.
|
|
In an author\-date style, it might render as
|
|
.IP
|
|
.EX
|
|
Blah blah (Doe 1999, Smith 2000, 2004).
|
|
.EE
|
|
.PP
|
|
In a footnote style, it might render as
|
|
.IP
|
|
.EX
|
|
Blah blah.[\(ha1]
|
|
|
|
[\(ha1]: John Doe, \(dqFrogs,\(dq *Journal of Amphibians* 44 (1999);
|
|
Susan Smith, \(dqFlies,\(dq *Journal of Insects* (2000);
|
|
Susan Smith, \(dqBees,\(dq *Journal of Insects* (2004).
|
|
.EE
|
|
.PP
|
|
See the CSL user documentation for more information about CSL styles and
|
|
how they affect rendering.
|
|
.PP
|
|
Unless a citation key starts with a letter, digit, or \f[CR]_\f[R], and
|
|
contains only alphanumerics and single internal punctuation characters
|
|
(\f[CR]:.#$%&\-+?<>\(ti/\f[R]), it must be surrounded by curly braces,
|
|
which are not considered part of the key.
|
|
In \f[CR]\(atFoo_bar.baz.\f[R], the key is \f[CR]Foo_bar.baz\f[R]
|
|
because the final period is not \f[I]internal\f[R] punctuation, so it is
|
|
not included in the key.
|
|
In \f[CR]\(at{Foo_bar.baz.}\f[R], the key is \f[CR]Foo_bar.baz.\f[R],
|
|
including the final period.
|
|
In \f[CR]\(atFoo_bar\-\-baz\f[R], the key is \f[CR]Foo_bar\f[R] because
|
|
the repeated internal punctuation characters terminate the key.
|
|
The curly braces are recommended if you use URLs as keys:
|
|
\f[CR][\(at{https://example.com/bib?name=foobar&date=2000}, p. 33]\f[R].
|
|
.PP
|
|
Citation items may optionally include a prefix, a locator, and a suffix.
|
|
In
|
|
.IP
|
|
.EX
|
|
Blah blah [see \(atdoe99, pp. 33\-35 and *passim*; \(atsmith04, chap. 1].
|
|
.EE
|
|
.PP
|
|
the first item (\f[CR]doe99\f[R]) has prefix \f[CR]see\f[R], locator
|
|
\f[CR]pp. 33\-35\f[R], and suffix \f[CR]and *passim*\f[R].
|
|
The second item (\f[CR]smith04\f[R]) has locator \f[CR]chap. 1\f[R] and
|
|
no prefix or suffix.
|
|
.PP
|
|
Pandoc uses some heuristics to separate the locator from the rest of the
|
|
subject.
|
|
It is sensitive to the locator terms defined in the CSL locale files.
|
|
Either abbreviated or unabbreviated forms are accepted.
|
|
In the \f[CR]en\-US\f[R] locale, locator terms can be written in either
|
|
singular or plural forms, as \f[CR]book\f[R],
|
|
\f[CR]bk.\f[R]/\f[CR]bks.\f[R]; \f[CR]chapter\f[R],
|
|
\f[CR]chap.\f[R]/\f[CR]chaps.\f[R]; \f[CR]column\f[R],
|
|
\f[CR]col.\f[R]/\f[CR]cols.\f[R]; \f[CR]figure\f[R],
|
|
\f[CR]fig.\f[R]/\f[CR]figs.\f[R]; \f[CR]folio\f[R],
|
|
\f[CR]fol.\f[R]/\f[CR]fols.\f[R]; \f[CR]number\f[R],
|
|
\f[CR]no.\f[R]/\f[CR]nos.\f[R]; \f[CR]line\f[R],
|
|
\f[CR]l.\f[R]/\f[CR]ll.\f[R]; \f[CR]note\f[R],
|
|
\f[CR]n.\f[R]/\f[CR]nn.\f[R]; \f[CR]opus\f[R],
|
|
\f[CR]op.\f[R]/\f[CR]opp.\f[R]; \f[CR]page\f[R],
|
|
\f[CR]p.\f[R]/\f[CR]pp.\f[R]; \f[CR]paragraph\f[R],
|
|
\f[CR]para.\f[R]/\f[CR]paras.\f[R]; \f[CR]part\f[R],
|
|
\f[CR]pt.\f[R]/\f[CR]pts.\f[R]; \f[CR]section\f[R],
|
|
\f[CR]sec.\f[R]/\f[CR]secs.\f[R]; \f[CR]sub verbo\f[R],
|
|
\f[CR]s.v.\f[R]/\f[CR]s.vv.\f[R]; \f[CR]verse\f[R],
|
|
\f[CR]v.\f[R]/\f[CR]vv.\f[R]; \f[CR]volume\f[R],
|
|
\f[CR]vol.\f[R]/\f[CR]vols.\f[R]; \f[CR]¶\f[R]/\f[CR]¶¶\f[R];
|
|
\f[CR]§\f[R]/\f[CR]§§\f[R].
|
|
If no locator term is used, \(lqpage\(rq is assumed.
|
|
.PP
|
|
In complex cases, you can force something to be treated as a locator by
|
|
enclosing it in curly braces or prevent parsing the suffix as locator by
|
|
prepending curly braces:
|
|
.IP
|
|
.EX
|
|
[\(atsmith{ii, A, D\-Z}, with a suffix]
|
|
[\(atsmith, {pp. iv, vi\-xi, (xv)\-(xvii)} with suffix here]
|
|
[\(atsmith{}, 99 years later]
|
|
.EE
|
|
.PP
|
|
A minus sign (\f[CR]\-\f[R]) before the \f[CR]\(at\f[R] will suppress
|
|
mention of the author in the citation.
|
|
This can be useful when the author is already mentioned in the text:
|
|
.IP
|
|
.EX
|
|
Smith says blah [\-\(atsmith04].
|
|
.EE
|
|
.PP
|
|
You can also write an author\-in\-text citation, by omitting the square
|
|
brackets:
|
|
.IP
|
|
.EX
|
|
\(atsmith04 says blah.
|
|
|
|
\(atsmith04 [p. 33] says blah.
|
|
.EE
|
|
.PP
|
|
This will cause the author\(cqs name to be rendered, followed by the
|
|
bibliographical details.
|
|
Use this form when you want to make the citation the subject of a
|
|
sentence.
|
|
.PP
|
|
When you are using a note style, it is usually better to let citeproc
|
|
create the footnotes from citations rather than writing an explicit
|
|
note.
|
|
If you do write an explicit note that contains a citation, note that
|
|
normal citations will be put in parentheses, while author\-in\-text
|
|
citations will not.
|
|
For this reason, it is sometimes preferable to use the author\-in\-text
|
|
style inside notes when using a note style.
|
|
.PP
|
|
Many CSL styles will format citations differently when the same source
|
|
has been cited earlier.
|
|
In documents with chapters, it is usually desirable to reset this
|
|
position information at the beginning of every chapter.
|
|
To do this, add the class \f[CR]reset\-citation\-positions\f[R] to the
|
|
heading for each chapter:
|
|
.IP
|
|
.EX
|
|
# The Beginning {.reset\-citation\-positions}
|
|
.EE
|
|
.PP
|
|
Note that this class only has an effect when placed on top\-level
|
|
headings; it is ignored in nested blocks.
|
|
.SS Non\-default extensions
|
|
The following Markdown syntax extensions are not enabled by default in
|
|
pandoc, but may be enabled by adding \f[CR]+EXTENSION\f[R] to the format
|
|
name, where \f[CR]EXTENSION\f[R] is the name of the extension.
|
|
Thus, for example, \f[CR]markdown+hard_line_breaks\f[R] is Markdown with
|
|
hard line breaks.
|
|
.SS Extension: \f[CR]rebase_relative_paths\f[R]
|
|
Rewrite relative paths for Markdown links and images, depending on the
|
|
path of the file containing the link or image link.
|
|
For each link or image, pandoc will compute the directory of the
|
|
containing file, relative to the working directory, and prepend the
|
|
resulting path to the link or image path.
|
|
.PP
|
|
The use of this extension is best understood by example.
|
|
Suppose you have a subdirectory for each chapter of a book,
|
|
\f[CR]chap1\f[R], \f[CR]chap2\f[R], \f[CR]chap3\f[R].
|
|
Each contains a file \f[CR]text.md\f[R] and a number of images used in
|
|
the chapter.
|
|
You would like to have \f[CR]\f[R] in
|
|
\f[CR]chap1/text.md\f[R] refer to \f[CR]chap1/spider.jpg\f[R] and
|
|
\f[CR]\f[R] in \f[CR]chap2/text.md\f[R] refer to
|
|
\f[CR]chap2/spider.jpg\f[R].
|
|
To do this, use
|
|
.IP
|
|
.EX
|
|
pandoc chap*/*.md \-f markdown+rebase_relative_paths
|
|
.EE
|
|
.PP
|
|
Without this extension, you would have to use
|
|
\f[CR]\f[R] in \f[CR]chap1/text.md\f[R] and
|
|
\f[CR]\f[R] in \f[CR]chap2/text.md\f[R].
|
|
Links with relative paths will be rewritten in the same way as images.
|
|
.PP
|
|
Absolute paths and URLs are not changed.
|
|
Neither are empty paths or paths consisting entirely of a fragment,
|
|
e.g., \f[CR]#foo\f[R].
|
|
.PP
|
|
Note that relative paths in reference links and images will be rewritten
|
|
relative to the file containing the link reference definition, not the
|
|
file containing the reference link or image itself, if these differ.
|
|
.SS Extension: \f[CR]mark\f[R]
|
|
To highlight out a section of text, begin and end it with with
|
|
\f[CR]==\f[R].
|
|
Thus, for example,
|
|
.IP
|
|
.EX
|
|
This ==is deleted text.==
|
|
.EE
|
|
.SS Extension: \f[CR]attributes\f[R]
|
|
Allows attributes to be attached to any inline or block\-level element
|
|
when parsing \f[CR]commonmark\f[R].
|
|
The syntax for the attributes is the same as that used in
|
|
\f[CR]header_attributes\f[R].
|
|
.IP \(bu 2
|
|
Attributes that occur immediately after an inline element affect that
|
|
element.
|
|
If they follow a space, then they belong to the space.
|
|
(Hence, this option subsumes \f[CR]inline_code_attributes\f[R] and
|
|
\f[CR]link_attributes\f[R].)
|
|
.IP \(bu 2
|
|
Attributes that occur immediately before a block element, on a line by
|
|
themselves, affect that element.
|
|
.IP \(bu 2
|
|
Consecutive attribute specifiers may be used, either for blocks or for
|
|
inlines.
|
|
Their attributes will be combined.
|
|
.IP \(bu 2
|
|
Attributes that occur at the end of the text of a Setext or ATX heading
|
|
(separated by whitespace from the text) affect the heading element.
|
|
(Hence, this option subsumes \f[CR]header_attributes\f[R].)
|
|
.IP \(bu 2
|
|
Attributes that occur after the opening fence in a fenced code block
|
|
affect the code block element.
|
|
(Hence, this option subsumes \f[CR]fenced_code_attributes\f[R].)
|
|
.IP \(bu 2
|
|
Attributes that occur at the end of a reference link definition affect
|
|
links that refer to that definition.
|
|
.PP
|
|
Note that pandoc\(cqs AST does not currently allow attributes to be
|
|
attached to arbitrary elements.
|
|
Hence a Span or Div container will be added if needed.
|
|
.SS Extension: \f[CR]old_dashes\f[R]
|
|
Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
|
|
\f[CR]\-\f[R] before a numeral is an en\-dash, and \f[CR]\-\-\f[R] is an
|
|
em\-dash.
|
|
This option only has an effect if \f[CR]smart\f[R] is enabled.
|
|
It is selected automatically for \f[CR]textile\f[R] input.
|
|
.SS Extension: \f[CR]angle_brackets_escapable\f[R]
|
|
Allow \f[CR]<\f[R] and \f[CR]>\f[R] to be backslash\-escaped, as they
|
|
can be in GitHub flavored Markdown but not original Markdown.
|
|
This is implied by pandoc\(cqs default \f[CR]all_symbols_escapable\f[R].
|
|
.SS Extension: \f[CR]lists_without_preceding_blankline\f[R]
|
|
Allow a list to occur right after a paragraph, with no intervening blank
|
|
space.
|
|
.SS Extension: \f[CR]four_space_rule\f[R]
|
|
Selects the pandoc <= 2.0 behavior for parsing lists, so that four
|
|
spaces indent are needed for list item continuation paragraphs.
|
|
.SS Extension: \f[CR]spaced_reference_links\f[R]
|
|
Allow whitespace between the two components of a reference link, for
|
|
example,
|
|
.IP
|
|
.EX
|
|
[foo] [bar].
|
|
.EE
|
|
.SS Extension: \f[CR]hard_line_breaks\f[R]
|
|
Causes all newlines within a paragraph to be interpreted as hard line
|
|
breaks instead of spaces.
|
|
.SS Extension: \f[CR]ignore_line_breaks\f[R]
|
|
Causes newlines within a paragraph to be ignored, rather than being
|
|
treated as spaces or as hard line breaks.
|
|
This option is intended for use with East Asian languages where spaces
|
|
are not used between words, but text is divided into lines for
|
|
readability.
|
|
.SS Extension: \f[CR]east_asian_line_breaks\f[R]
|
|
Causes newlines within a paragraph to be ignored, rather than being
|
|
treated as spaces or as hard line breaks, when they occur between two
|
|
East Asian wide characters.
|
|
This is a better choice than \f[CR]ignore_line_breaks\f[R] for texts
|
|
that include a mix of East Asian wide characters and other characters.
|
|
.SS Extension: \f[CR]emoji\f[R]
|
|
Parses textual emojis like \f[CR]:smile:\f[R] as Unicode emoticons.
|
|
.SS Extension: \f[CR]tex_math_gfm\f[R]
|
|
Supports two GitHub\-specific formats for math.
|
|
Inline math: \f[CR]$\(gae=mc\(ha2\(ga$\f[R].
|
|
.PP
|
|
Display math:
|
|
.IP
|
|
.EX
|
|
\(ga\(ga\(ga math
|
|
e=mc\(ha2
|
|
\(ga\(ga\(ga
|
|
.EE
|
|
.SS Extension: \f[CR]tex_math_single_backslash\f[R]
|
|
Causes anything between \f[CR]\(rs(\f[R] and \f[CR]\(rs)\f[R] to be
|
|
interpreted as inline TeX math, and anything between \f[CR]\(rs[\f[R]
|
|
and \f[CR]\(rs]\f[R] to be interpreted as display TeX math.
|
|
Note: a drawback of this extension is that it precludes escaping
|
|
\f[CR](\f[R] and \f[CR][\f[R].
|
|
.SS Extension: \f[CR]tex_math_double_backslash\f[R]
|
|
Causes anything between \f[CR]\(rs\(rs(\f[R] and \f[CR]\(rs\(rs)\f[R] to
|
|
be interpreted as inline TeX math, and anything between
|
|
\f[CR]\(rs\(rs[\f[R] and \f[CR]\(rs\(rs]\f[R] to be interpreted as
|
|
display TeX math.
|
|
.SS Extension: \f[CR]markdown_attribute\f[R]
|
|
By default, pandoc interprets material inside block\-level tags as
|
|
Markdown.
|
|
This extension changes the behavior so that Markdown is only parsed
|
|
inside block\-level tags if the tags have the attribute
|
|
\f[CR]markdown=1\f[R].
|
|
.SS Extension: \f[CR]mmd_title_block\f[R]
|
|
Enables a MultiMarkdown style title block at the top of the document,
|
|
for example:
|
|
.IP
|
|
.EX
|
|
Title: My title
|
|
Author: John Doe
|
|
Date: September 1, 2008
|
|
Comment: This is a sample mmd title block, with
|
|
a field spanning multiple lines.
|
|
.EE
|
|
.PP
|
|
See the MultiMarkdown documentation for details.
|
|
If \f[CR]pandoc_title_block\f[R] or \f[CR]yaml_metadata_block\f[R] is
|
|
enabled, it will take precedence over \f[CR]mmd_title_block\f[R].
|
|
.SS Extension: \f[CR]abbreviations\f[R]
|
|
Parses PHP Markdown Extra abbreviation keys, like
|
|
.IP
|
|
.EX
|
|
*[HTML]: Hypertext Markup Language
|
|
.EE
|
|
.PP
|
|
Note that the pandoc document model does not support abbreviations, so
|
|
if this extension is enabled, abbreviation keys are simply skipped (as
|
|
opposed to being parsed as paragraphs).
|
|
.SS Extension: \f[CR]alerts\f[R]
|
|
Supports GitHub\-style Markdown alerts, like
|
|
.IP
|
|
.EX
|
|
> [!TIP]
|
|
> Helpful advice for doing things better or more easily.
|
|
.EE
|
|
.SS Extension: \f[CR]autolink_bare_uris\f[R]
|
|
Makes all absolute URIs into links, even when not surrounded by pointy
|
|
braces \f[CR]<...>\f[R].
|
|
.SS Extension: \f[CR]mmd_link_attributes\f[R]
|
|
Parses MultiMarkdown\-style key\-value attributes on link and image
|
|
references.
|
|
This extension should not be confused with the
|
|
\f[CR]link_attributes\f[R] extension.
|
|
.IP
|
|
.EX
|
|
This is a reference ![image][ref] with MultiMarkdown attributes.
|
|
|
|
[ref]: https://path.to/image \(dqImage title\(dq width=20px height=30px
|
|
id=myId class=\(dqmyClass1 myClass2\(dq
|
|
.EE
|
|
.SS Extension: \f[CR]mmd_header_identifiers\f[R]
|
|
Parses MultiMarkdown\-style heading identifiers (in square brackets,
|
|
after the heading but before any trailing \f[CR]#\f[R]s in an ATX
|
|
heading).
|
|
.SS Extension: \f[CR]gutenberg\f[R]
|
|
Use Project Gutenberg conventions for \f[CR]plain\f[R] output: all\-caps
|
|
for strong emphasis, surround by underscores for regular emphasis, add
|
|
extra blank space around headings.
|
|
.SS Extension: \f[CR]sourcepos\f[R]
|
|
Include source position attributes when parsing \f[CR]commonmark\f[R].
|
|
For elements that accept attributes, a \f[CR]data\-pos\f[R] attribute is
|
|
added; other elements are placed in a surrounding Div or Span element
|
|
with a \f[CR]data\-pos\f[R] attribute.
|
|
.SS Extension: \f[CR]short_subsuperscripts\f[R]
|
|
Parse MultiMarkdown\-style subscripts and superscripts, which start with
|
|
a `\(ti' or `\(ha' character, respectively, and include the alphanumeric
|
|
sequence that follows.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
x\(ha2 = 4
|
|
.EE
|
|
.PP
|
|
or
|
|
.IP
|
|
.EX
|
|
Oxygen is O\(ti2.
|
|
.EE
|
|
.SS Extension: \f[CR]wikilinks_title_after_pipe\f[R]
|
|
Pandoc supports multiple Markdown wikilink syntaxes, regardless of
|
|
whether the title is before or after the pipe.
|
|
.PP
|
|
Using \f[CR]\-\-from=markdown+wikilinks_title_after_pipe\f[R] results in
|
|
.IP
|
|
.EX
|
|
[[URL|title]]
|
|
.EE
|
|
.PP
|
|
while using \f[CR]\-\-from=markdown+wikilinks_title_before_pipe\f[R]
|
|
results in
|
|
.IP
|
|
.EX
|
|
[[title|URL]]
|
|
.EE
|
|
.SS Markdown variants
|
|
In addition to pandoc\(cqs extended Markdown, the following Markdown
|
|
variants are supported:
|
|
.IP \(bu 2
|
|
\f[CR]markdown_phpextra\f[R] (PHP Markdown Extra)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_github\f[R] (deprecated GitHub\-Flavored Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_mmd\f[R] (MultiMarkdown)
|
|
.IP \(bu 2
|
|
\f[CR]markdown_strict\f[R] (Markdown.pl)
|
|
.IP \(bu 2
|
|
\f[CR]commonmark\f[R] (CommonMark)
|
|
.IP \(bu 2
|
|
\f[CR]gfm\f[R] (Github\-Flavored Markdown)
|
|
.IP \(bu 2
|
|
\f[CR]commonmark_x\f[R] (CommonMark with many pandoc extensions)
|
|
.PP
|
|
To see which extensions are supported for a given format, and which are
|
|
enabled by default, you can use the command
|
|
.IP
|
|
.EX
|
|
pandoc \-\-list\-extensions=FORMAT
|
|
.EE
|
|
.PP
|
|
where \f[CR]FORMAT\f[R] is replaced with the name of the format.
|
|
.PP
|
|
Note that the list of extensions for \f[CR]commonmark\f[R],
|
|
\f[CR]gfm\f[R], and \f[CR]commonmark_x\f[R] are defined relative to
|
|
default commonmark.
|
|
So, for example, \f[CR]backtick_code_blocks\f[R] does not appear as an
|
|
extension, since it is enabled by default and cannot be disabled.
|
|
.SH CITATIONS
|
|
When the \f[CR]\-\-citeproc\f[R] option is used, pandoc can
|
|
automatically generate citations and a bibliography in a number of
|
|
styles.
|
|
Basic usage is
|
|
.IP
|
|
.EX
|
|
pandoc \-\-citeproc myinput.txt
|
|
.EE
|
|
.PP
|
|
To use this feature, you will need to have
|
|
.IP \(bu 2
|
|
a document containing citations (see Citation syntax);
|
|
.IP \(bu 2
|
|
a source of bibliographic data: either an external bibliography file or
|
|
a list of \f[CR]references\f[R] in the document\(cqs YAML metadata;
|
|
.IP \(bu 2
|
|
optionally, a CSL citation style.
|
|
.SS Specifying bibliographic data
|
|
You can specify an external bibliography using the
|
|
\f[CR]bibliography\f[R] metadata field in a YAML metadata section or the
|
|
\f[CR]\-\-bibliography\f[R] command line argument.
|
|
If you want to use multiple bibliography files, you can supply multiple
|
|
\f[CR]\-\-bibliography\f[R] arguments or set \f[CR]bibliography\f[R]
|
|
metadata field to YAML array.
|
|
A bibliography may have any of these formats:
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
Format File extension
|
|
\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
BibLaTeX .bib
|
|
BibTeX .bibtex
|
|
CSL JSON .json
|
|
CSL YAML .yaml
|
|
RIS .ris
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Note that \f[CR].bib\f[R] can be used with both BibTeX and BibLaTeX
|
|
files; use the extension \f[CR].bibtex\f[R] to force interpretation as
|
|
BibTeX.
|
|
.PP
|
|
In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside
|
|
fields such as \f[CR]title\f[R]; in CSL YAML databases, pandoc Markdown;
|
|
and in CSL JSON databases, an HTML\-like markup:
|
|
.TP
|
|
\f[CR]<i>...</i>\f[R]
|
|
italics
|
|
.TP
|
|
\f[CR]<b>...</b>\f[R]
|
|
bold
|
|
.TP
|
|
\f[CR]<span style=\(dqfont\-variant:small\-caps;\(dq>...</span>\f[R] or \f[CR]<sc>...</sc>\f[R]
|
|
small capitals
|
|
.TP
|
|
\f[CR]<sub>...</sub>\f[R]
|
|
subscript
|
|
.TP
|
|
\f[CR]<sup>...</sup>\f[R]
|
|
superscript
|
|
.TP
|
|
\f[CR]<span class=\(dqnocase\(dq>...</span>\f[R]
|
|
prevent a phrase from being capitalized as title case
|
|
.PP
|
|
As an alternative to specifying a bibliography file using
|
|
\f[CR]\-\-bibliography\f[R] or the YAML metadata field
|
|
\f[CR]bibliography\f[R], you can include the citation data directly in
|
|
the \f[CR]references\f[R] field of the document\(cqs YAML metadata.
|
|
The field should contain an array of YAML\-encoded references, for
|
|
example:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
references:
|
|
\- type: article\-journal
|
|
id: WatsonCrick1953
|
|
author:
|
|
\- family: Watson
|
|
given: J. D.
|
|
\- family: Crick
|
|
given: F. H. C.
|
|
issued:
|
|
date\-parts:
|
|
\- \- 1953
|
|
\- 4
|
|
\- 25
|
|
title: \(aqMolecular structure of nucleic acids: a structure for
|
|
deoxyribose nucleic acid\(aq
|
|
title\-short: Molecular structure of nucleic acids
|
|
container\-title: Nature
|
|
volume: 171
|
|
issue: 4356
|
|
page: 737\-738
|
|
DOI: 10.1038/171737a0
|
|
URL: https://www.nature.com/articles/171737a0
|
|
language: en\-GB
|
|
\&...
|
|
.EE
|
|
.PP
|
|
If both an external bibliography and inline (YAML metadata) references
|
|
are provided, both will be used.
|
|
In case of conflicting \f[CR]id\f[R]s, the inline references will take
|
|
precedence.
|
|
.PP
|
|
Note that pandoc can be used to produce such a YAML metadata section
|
|
from a BibTeX, BibLaTeX, or CSL JSON bibliography:
|
|
.IP
|
|
.EX
|
|
pandoc chem.bib \-s \-f biblatex \-t markdown
|
|
pandoc chem.json \-s \-f csljson \-t markdown
|
|
.EE
|
|
.PP
|
|
Indeed, pandoc can convert between any of these citation formats:
|
|
.IP
|
|
.EX
|
|
pandoc chem.bib \-s \-f biblatex \-t csljson
|
|
pandoc chem.yaml \-s \-f markdown \-t biblatex
|
|
.EE
|
|
.PP
|
|
Running pandoc on a bibliography file with the \f[CR]\-\-citeproc\f[R]
|
|
option will create a formatted bibliography in the format of your
|
|
choice:
|
|
.IP
|
|
.EX
|
|
pandoc chem.bib \-s \-\-citeproc \-o chem.html
|
|
pandoc chem.bib \-s \-\-citeproc \-o chem.pdf
|
|
.EE
|
|
.SS Capitalization in titles
|
|
If you are using a bibtex or biblatex bibliography, then observe the
|
|
following rules:
|
|
.IP \(bu 2
|
|
English titles should be in title case.
|
|
Non\-English titles should be in sentence case, and the
|
|
\f[CR]langid\f[R] field in biblatex should be set to the relevant
|
|
language.
|
|
(The following values are treated as English: \f[CR]american\f[R],
|
|
\f[CR]british\f[R], \f[CR]canadian\f[R], \f[CR]english\f[R],
|
|
\f[CR]australian\f[R], \f[CR]newzealand\f[R], \f[CR]USenglish\f[R], or
|
|
\f[CR]UKenglish\f[R].)
|
|
.IP \(bu 2
|
|
As is standard with bibtex/biblatex, proper names should be protected
|
|
with curly braces so that they won\(cqt be lowercased in styles that
|
|
call for sentence case.
|
|
For example:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
title = {My Dinner with {Andre}}
|
|
.EE
|
|
.RE
|
|
.IP \(bu 2
|
|
In addition, words that should remain lowercase (or camelCase) should be
|
|
protected:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
title = {Spin Wave Dispersion on the {nm} Scale}
|
|
.EE
|
|
.PP
|
|
Though this is not necessary in bibtex/biblatex, it is necessary with
|
|
citeproc, which stores titles internally in sentence case, and converts
|
|
to title case in styles that require it.
|
|
Here we protect \(lqnm\(rq so that it doesn\(cqt get converted to
|
|
\(lqNm\(rq at this stage.
|
|
.RE
|
|
.PP
|
|
If you are using a CSL bibliography (either JSON or YAML), then observe
|
|
the following rules:
|
|
.IP \(bu 2
|
|
All titles should be in sentence case.
|
|
.IP \(bu 2
|
|
Use the \f[CR]language\f[R] field for non\-English titles to prevent
|
|
their conversion to title case in styles that call for this.
|
|
(Conversion happens only if \f[CR]language\f[R] begins with
|
|
\f[CR]en\f[R] or is left empty.)
|
|
.IP \(bu 2
|
|
Protect words that should not be converted to title case using this
|
|
syntax:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
Spin wave dispersion on the <span class=\(dqnocase\(dq>nm</span> scale
|
|
.EE
|
|
.RE
|
|
.SS Conference Papers, Published vs.\ Unpublished
|
|
For a formally published conference paper, use the biblatex entry type
|
|
\f[CR]inproceedings\f[R] (which will be mapped to CSL
|
|
\f[CR]paper\-conference\f[R]).
|
|
.PP
|
|
For an unpublished manuscript, use the biblatex entry type
|
|
\f[CR]unpublished\f[R] without an \f[CR]eventtitle\f[R] field (this
|
|
entry type will be mapped to CSL \f[CR]manuscript\f[R]).
|
|
.PP
|
|
For a talk, an unpublished conference paper, or a poster presentation,
|
|
use the biblatex entry type \f[CR]unpublished\f[R] with an
|
|
\f[CR]eventtitle\f[R] field (this entry type will be mapped to CSL
|
|
\f[CR]speech\f[R]).
|
|
Use the biblatex \f[CR]type\f[R] field to indicate the type,
|
|
e.g.\ \(lqPaper\(rq, or \(lqPoster\(rq.
|
|
\f[CR]venue\f[R] and \f[CR]eventdate\f[R] may be useful too, though
|
|
\f[CR]eventdate\f[R] will not be rendered by most CSL styles.
|
|
Note that \f[CR]venue\f[R] is for the event\(cqs venue, unlike
|
|
\f[CR]location\f[R] which describes the publisher\(cqs location; do not
|
|
use the latter for an unpublished conference paper.
|
|
.SS Specifying a citation style
|
|
Citations and references can be formatted using any style supported by
|
|
the Citation Style Language, listed in the Zotero Style Repository.
|
|
These files are specified using the \f[CR]\-\-csl\f[R] option or the
|
|
\f[CR]csl\f[R] (or \f[CR]citation\-style\f[R]) metadata field.
|
|
By default, pandoc will use the Chicago Manual of Style author\-date
|
|
format.
|
|
(You can override this default by copying a CSL style of your choice to
|
|
\f[CR]default.csl\f[R] in your user data directory.)
|
|
The CSL project provides further information on finding and editing
|
|
styles.
|
|
.PP
|
|
The \f[CR]\-\-citation\-abbreviations\f[R] option (or the
|
|
\f[CR]citation\-abbreviations\f[R] metadata field) may be used to
|
|
specify a JSON file containing abbreviations of journals that should be
|
|
used in formatted bibliographies when \f[CR]form=\(dqshort\(dq\f[R] is
|
|
specified.
|
|
The format of the file can be illustrated with an example:
|
|
.IP
|
|
.EX
|
|
{ \(dqdefault\(dq: {
|
|
\(dqcontainer\-title\(dq: {
|
|
\(dqLloyd\(aqs Law Reports\(dq: \(dqLloyd\(aqs Rep\(dq,
|
|
\(dqEstates Gazette\(dq: \(dqEG\(dq,
|
|
\(dqScots Law Times\(dq: \(dqSLT\(dq
|
|
}
|
|
}
|
|
}
|
|
.EE
|
|
.SS Citations in note styles
|
|
Pandoc\(cqs citation processing is designed to allow you to move between
|
|
author\-date, numerical, and note styles without modifying the Markdown
|
|
source.
|
|
When you\(cqre using a note style, avoid inserting footnotes manually.
|
|
Instead, insert citations just as you would in an author\-date
|
|
style\(emfor example,
|
|
.IP
|
|
.EX
|
|
Blah blah [\(atfoo, p. 33].
|
|
.EE
|
|
.PP
|
|
The footnote will be created automatically.
|
|
Pandoc will take care of removing the space and moving the note before
|
|
or after the period, depending on the setting of
|
|
\f[CR]notes\-after\-punctuation\f[R], as described below in Other
|
|
relevant metadata fields.
|
|
.PP
|
|
In some cases you may need to put a citation inside a regular footnote.
|
|
Normal citations in footnotes (such as \f[CR][\(atfoo, p. 33]\f[R]) will
|
|
be rendered in parentheses.
|
|
In\-text citations (such as \f[CR]\(atfoo [p. 33]\f[R]) will be rendered
|
|
without parentheses.
|
|
(A comma will be added if appropriate.)
|
|
Thus:
|
|
.IP
|
|
.EX
|
|
[\(ha1]: Some studies [\(atfoo; \(atbar, p. 33] show that
|
|
frubulicious zoosnaps are quantical. For a survey
|
|
of the literature, see \(atbaz [chap. 1].
|
|
.EE
|
|
.SS Placement of the bibliography
|
|
If the style calls for a list of works cited, it will be placed in a div
|
|
with id \f[CR]refs\f[R], if one exists:
|
|
.IP
|
|
.EX
|
|
::: {#refs}
|
|
:::
|
|
.EE
|
|
.PP
|
|
Otherwise, it will be placed at the end of the document.
|
|
Generation of the bibliography can be suppressed by setting
|
|
\f[CR]suppress\-bibliography: true\f[R] in the YAML metadata.
|
|
.PP
|
|
If you wish the bibliography to have a section heading, you can set
|
|
\f[CR]reference\-section\-title\f[R] in the metadata, or put the heading
|
|
at the beginning of the div with id \f[CR]refs\f[R] (if you are using
|
|
it) or at the end of your document:
|
|
.IP
|
|
.EX
|
|
last paragraph...
|
|
|
|
# References
|
|
.EE
|
|
.PP
|
|
The bibliography will be inserted after this heading.
|
|
Note that the \f[CR]unnumbered\f[R] class will be added to this heading,
|
|
so that the section will not be numbered.
|
|
.PP
|
|
If you want to put the bibliography into a variable in your template,
|
|
one way to do that is to put the div with id \f[CR]refs\f[R] into a
|
|
metadata field, e.g.
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
refs: |
|
|
::: {#refs}
|
|
:::
|
|
\&...
|
|
.EE
|
|
.PP
|
|
You can then put the variable \f[CR]$refs$\f[R] into your template where
|
|
you want the bibliography to be placed.
|
|
.SS Including uncited items in the bibliography
|
|
If you want to include items in the bibliography without actually citing
|
|
them in the body text, you can define a dummy \f[CR]nocite\f[R] metadata
|
|
field and put the citations there:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
nocite: |
|
|
\(atitem1, \(atitem2
|
|
\&...
|
|
|
|
\(atitem3
|
|
.EE
|
|
.PP
|
|
In this example, the document will contain a citation for
|
|
\f[CR]item3\f[R] only, but the bibliography will contain entries for
|
|
\f[CR]item1\f[R], \f[CR]item2\f[R], and \f[CR]item3\f[R].
|
|
.PP
|
|
It is possible to create a bibliography with all the citations, whether
|
|
or not they appear in the document, by using a wildcard:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
nocite: |
|
|
\(at*
|
|
\&...
|
|
.EE
|
|
.PP
|
|
For LaTeX output, you can also use \f[CR]natbib\f[R] or
|
|
\f[CR]biblatex\f[R] to render the bibliography.
|
|
In order to do so, specify bibliography files as outlined above, and add
|
|
\f[CR]\-\-natbib\f[R] or \f[CR]\-\-biblatex\f[R] argument to pandoc
|
|
invocation.
|
|
Bear in mind that bibliography files have to be in either BibTeX (for
|
|
\f[CR]\-\-natbib\f[R]) or BibLaTeX (for \f[CR]\-\-biblatex\f[R]) format.
|
|
.SS Other relevant metadata fields
|
|
A few other metadata fields affect bibliography formatting:
|
|
.TP
|
|
\f[CR]link\-citations\f[R]
|
|
If true, citations will be hyperlinked to the corresponding bibliography
|
|
entries (for author\-date and numerical styles only).
|
|
Defaults to false.
|
|
.TP
|
|
\f[CR]link\-bibliography\f[R]
|
|
If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered
|
|
as hyperlinks.
|
|
(If an entry contains a DOI, PMCID, PMID, or URL, but none of these
|
|
fields are rendered by the style, then the title, or in the absence of a
|
|
title the whole entry, will be hyperlinked.)
|
|
Defaults to true.
|
|
.TP
|
|
\f[CR]lang\f[R]
|
|
The \f[CR]lang\f[R] field will affect how the style is localized, for
|
|
example in the translation of labels, the use of quotation marks, and
|
|
the way items are sorted.
|
|
(For backwards compatibility, \f[CR]locale\f[R] may be used instead of
|
|
\f[CR]lang\f[R], but this use is deprecated.)
|
|
.RS
|
|
A BCP 47 language tag is expected: for example, \f[CR]en\f[R],
|
|
\f[CR]de\f[R], \f[CR]en\-US\f[R], \f[CR]fr\-CA\f[R],
|
|
\f[CR]ug\-Cyrl\f[R].
|
|
The unicode extension syntax (after \f[CR]\-u\-\f[R]) may be used to
|
|
specify options for collation (sorting) more precisely.
|
|
Here are some examples:
|
|
.IP \(bu 2
|
|
\f[CR]zh\-u\-co\-pinyin\f[R]: Chinese with the Pinyin collation.
|
|
.IP \(bu 2
|
|
\f[CR]es\-u\-co\-trad\f[R]: Spanish with the traditional collation (with
|
|
\f[CR]Ch\f[R] sorting after \f[CR]C\f[R]).
|
|
.IP \(bu 2
|
|
\f[CR]fr\-u\-kb\f[R]: French with \(lqbackwards\(rq accent sorting (with
|
|
\f[CR]coté\f[R] sorting after \f[CR]côte\f[R]).
|
|
.IP \(bu 2
|
|
\f[CR]en\-US\-u\-kf\-upper\f[R]: English with uppercase letters sorting
|
|
before lower (default is lower before upper).
|
|
.RE
|
|
.TP
|
|
\f[CR]notes\-after\-punctuation\f[R]
|
|
If true (the default for note styles), pandoc will put footnote
|
|
references or superscripted numerical citations after following
|
|
punctuation.
|
|
For example, if the source contains \f[CR]blah blah [\(atjones99].\f[R],
|
|
the result will look like \f[CR]blah blah.[\(ha1]\f[R], with the note
|
|
moved after the period and the space collapsed.
|
|
If false, the space will still be collapsed, but the footnote will not
|
|
be moved after the punctuation.
|
|
The option may also be used in numerical styles that use superscripts
|
|
for citation numbers (but for these styles the default is not to move
|
|
the citation).
|
|
.SH SLIDE SHOWS
|
|
You can use pandoc to produce an HTML + JavaScript slide presentation
|
|
that can be viewed via a web browser.
|
|
There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or
|
|
reveal.js.
|
|
You can also produce a PDF slide show using LaTeX \f[CR]beamer\f[R], or
|
|
slide shows in Microsoft PowerPoint format.
|
|
.PP
|
|
Here\(cqs the Markdown source for a simple slide show,
|
|
\f[CR]habits.txt\f[R]:
|
|
.IP
|
|
.EX
|
|
% Habits
|
|
% John Doe
|
|
% March 22, 2005
|
|
|
|
# In the morning
|
|
|
|
## Getting up
|
|
|
|
\- Turn off alarm
|
|
\- Get out of bed
|
|
|
|
## Breakfast
|
|
|
|
\- Eat eggs
|
|
\- Drink coffee
|
|
|
|
# In the evening
|
|
|
|
## Dinner
|
|
|
|
\- Eat spaghetti
|
|
\- Drink wine
|
|
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|
|
|
|
|
|
## Going to sleep
|
|
|
|
\- Get in bed
|
|
\- Count sheep
|
|
.EE
|
|
.PP
|
|
To produce an HTML/JavaScript slide show, simply type
|
|
.IP
|
|
.EX
|
|
pandoc \-t FORMAT \-s habits.txt \-o habits.html
|
|
.EE
|
|
.PP
|
|
where \f[CR]FORMAT\f[R] is either \f[CR]s5\f[R], \f[CR]slidy\f[R],
|
|
\f[CR]slideous\f[R], \f[CR]dzslides\f[R], or \f[CR]revealjs\f[R].
|
|
.PP
|
|
For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with
|
|
the \f[CR]\-s/\-\-standalone\f[R] option embeds a link to JavaScript and
|
|
CSS files, which are assumed to be available at the relative path
|
|
\f[CR]s5/default\f[R] (for S5), \f[CR]slideous\f[R] (for Slideous),
|
|
\f[CR]reveal.js\f[R] (for reveal.js), or at the Slidy website at
|
|
\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.)
|
|
For DZSlides, the (relatively short) JavaScript and CSS are included in
|
|
the file by default.
|
|
.PP
|
|
With all HTML slide formats, the \f[CR]\-\-self\-contained\f[R] option
|
|
can be used to produce a single file that contains all of the data
|
|
necessary to display the slide show, including linked scripts,
|
|
stylesheets, images, and videos.
|
|
.PP
|
|
To produce a PDF slide show using beamer, type
|
|
.IP
|
|
.EX
|
|
pandoc \-t beamer habits.txt \-o habits.pdf
|
|
.EE
|
|
.PP
|
|
Note that a reveal.js slide show can also be converted to a PDF by
|
|
printing it to a file from the browser.
|
|
.PP
|
|
To produce a PowerPoint slide show, type
|
|
.IP
|
|
.EX
|
|
pandoc habits.txt \-o habits.pptx
|
|
.EE
|
|
.SS Structuring the slide show
|
|
By default, the \f[I]slide level\f[R] is the highest heading level in
|
|
the hierarchy that is followed immediately by content, and not another
|
|
heading, somewhere in the document.
|
|
In the example above, level\-1 headings are always followed by level\-2
|
|
headings, which are followed by content, so the slide level is 2.
|
|
This default can be overridden using the \f[CR]\-\-slide\-level\f[R]
|
|
option.
|
|
.PP
|
|
The document is carved up into slides according to the following rules:
|
|
.IP \(bu 2
|
|
A horizontal rule always starts a new slide.
|
|
.IP \(bu 2
|
|
A heading at the slide level always starts a new slide.
|
|
.IP \(bu 2
|
|
Headings \f[I]below\f[R] the slide level in the hierarchy create
|
|
headings \f[I]within\f[R] a slide.
|
|
(In beamer, a \(lqblock\(rq will be created.
|
|
If the heading has the class \f[CR]example\f[R], an
|
|
\f[CR]exampleblock\f[R] environment will be used; if it has the class
|
|
\f[CR]alert\f[R], an \f[CR]alertblock\f[R] will be used; otherwise a
|
|
regular \f[CR]block\f[R] will be used.)
|
|
.IP \(bu 2
|
|
Headings \f[I]above\f[R] the slide level in the hierarchy create
|
|
\(lqtitle slides,\(rq which just contain the section title and help to
|
|
break the slide show into sections.
|
|
Non\-slide content under these headings will be included on the title
|
|
slide (for HTML slide shows) or in a subsequent slide with the same
|
|
title (for beamer).
|
|
.IP \(bu 2
|
|
A title page is constructed automatically from the document\(cqs title
|
|
block, if present.
|
|
(In the case of beamer, this can be disabled by commenting out some
|
|
lines in the default template.)
|
|
.PP
|
|
These rules are designed to support many different styles of slide show.
|
|
If you don\(cqt care about structuring your slides into sections and
|
|
subsections, you can either just use level\-1 headings for all slides
|
|
(in that case, level 1 will be the slide level) or you can set
|
|
\f[CR]\-\-slide\-level=0\f[R].
|
|
.PP
|
|
Note: in reveal.js slide shows, if slide level is 2, a two\-dimensional
|
|
layout will be produced, with level\-1 headings building horizontally
|
|
and level\-2 headings building vertically.
|
|
It is not recommended that you use deeper nesting of section levels with
|
|
reveal.js unless you set \f[CR]\-\-slide\-level=0\f[R] (which lets
|
|
reveal.js produce a one\-dimensional layout and only interprets
|
|
horizontal rules as slide boundaries).
|
|
.SS PowerPoint layout choice
|
|
When creating slides, the pptx writer chooses from a number of
|
|
pre\-defined layouts, based on the content of the slide:
|
|
.TP
|
|
Title Slide
|
|
This layout is used for the initial slide, which is generated and filled
|
|
from the metadata fields \f[CR]date\f[R], \f[CR]author\f[R], and
|
|
\f[CR]title\f[R], if they are present.
|
|
.TP
|
|
Section Header
|
|
This layout is used for what pandoc calls \(lqtitle slides\(rq, i.e.
|
|
slides which start with a header which is above the slide level in the
|
|
hierarchy.
|
|
.TP
|
|
Two Content
|
|
This layout is used for two\-column slides, i.e.\ slides containing a
|
|
div with class \f[CR]columns\f[R] which contains at least two divs with
|
|
class \f[CR]column\f[R].
|
|
.TP
|
|
Comparison
|
|
This layout is used instead of \(lqTwo Content\(rq for any two\-column
|
|
slides in which at least one column contains text followed by non\-text
|
|
(e.g.\ an image or a table).
|
|
.TP
|
|
Content with Caption
|
|
This layout is used for any non\-two\-column slides which contain text
|
|
followed by non\-text (e.g.\ an image or a table).
|
|
.TP
|
|
Blank
|
|
This layout is used for any slides which only contain blank content,
|
|
e.g.\ a slide containing only speaker notes, or a slide containing only
|
|
a non\-breaking space.
|
|
.TP
|
|
Title and Content
|
|
This layout is used for all slides which do not match the criteria for
|
|
another layout.
|
|
.PP
|
|
These layouts are chosen from the default pptx reference doc included
|
|
with pandoc, unless an alternative reference doc is specified using
|
|
\f[CR]\-\-reference\-doc\f[R].
|
|
.SS Incremental lists
|
|
By default, these writers produce lists that display \(lqall at
|
|
once.\(rq If you want your lists to display incrementally (one item at a
|
|
time), use the \f[CR]\-i\f[R] option.
|
|
If you want a particular list to depart from the default, put it in a
|
|
\f[CR]div\f[R] block with class \f[CR]incremental\f[R] or
|
|
\f[CR]nonincremental\f[R].
|
|
So, for example, using the \f[CR]fenced div\f[R] syntax, the following
|
|
would be incremental regardless of the document default:
|
|
.IP
|
|
.EX
|
|
::: incremental
|
|
|
|
\- Eat spaghetti
|
|
\- Drink wine
|
|
|
|
:::
|
|
.EE
|
|
.PP
|
|
or
|
|
.IP
|
|
.EX
|
|
::: nonincremental
|
|
|
|
\- Eat spaghetti
|
|
\- Drink wine
|
|
|
|
:::
|
|
.EE
|
|
.PP
|
|
While using \f[CR]incremental\f[R] and \f[CR]nonincremental\f[R] divs is
|
|
the recommended method of setting incremental lists on a per\-case
|
|
basis, an older method is also supported: putting lists inside a
|
|
blockquote will depart from the document default (that is, it will
|
|
display incrementally without the \f[CR]\-i\f[R] option and all at once
|
|
with the \f[CR]\-i\f[R] option):
|
|
.IP
|
|
.EX
|
|
> \- Eat spaghetti
|
|
> \- Drink wine
|
|
.EE
|
|
.PP
|
|
Both methods allow incremental and nonincremental lists to be mixed in a
|
|
single document.
|
|
.PP
|
|
If you want to include a block\-quoted list, you can work around this
|
|
behavior by putting the list inside a fenced div, so that it is not the
|
|
direct child of the block quote:
|
|
.IP
|
|
.EX
|
|
> ::: wrapper
|
|
> \- a
|
|
> \- list in a quote
|
|
> :::
|
|
.EE
|
|
.SS Inserting pauses
|
|
You can add \(lqpauses\(rq within a slide by including a paragraph
|
|
containing three dots, separated by spaces:
|
|
.IP
|
|
.EX
|
|
# Slide with a pause
|
|
|
|
content before the pause
|
|
|
|
\&. . .
|
|
|
|
content after the pause
|
|
.EE
|
|
.PP
|
|
Note: this feature is not yet implemented for PowerPoint output.
|
|
.SS Styling the slides
|
|
You can change the style of HTML slides by putting customized CSS files
|
|
in \f[CR]$DATADIR/s5/default\f[R] (for S5), \f[CR]$DATADIR/slidy\f[R]
|
|
(for Slidy), or \f[CR]$DATADIR/slideous\f[R] (for Slideous), where
|
|
\f[CR]$DATADIR\f[R] is the user data directory (see
|
|
\f[CR]\-\-data\-dir\f[R], above).
|
|
The originals may be found in pandoc\(cqs system data directory
|
|
(generally \f[CR]$CABALDIR/pandoc\-VERSION/s5/default\f[R]).
|
|
Pandoc will look there for any files it does not find in the user data
|
|
directory.
|
|
.PP
|
|
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.
|
|
For example, themes can be used by setting the \f[CR]theme\f[R]
|
|
variable:
|
|
.IP
|
|
.EX
|
|
\-V theme=moon
|
|
.EE
|
|
.PP
|
|
Or you can specify a custom stylesheet using the \f[CR]\-\-css\f[R]
|
|
option.
|
|
.PP
|
|
To style beamer slides, you can specify a \f[CR]theme\f[R],
|
|
\f[CR]colortheme\f[R], \f[CR]fonttheme\f[R], \f[CR]innertheme\f[R], and
|
|
\f[CR]outertheme\f[R], using the \f[CR]\-V\f[R] option:
|
|
.IP
|
|
.EX
|
|
pandoc \-t beamer habits.txt \-V theme:Warsaw \-o habits.pdf
|
|
.EE
|
|
.PP
|
|
Note that heading attributes will turn into slide attributes (on a
|
|
\f[CR]<div>\f[R] or \f[CR]<section>\f[R]) in HTML slide formats,
|
|
allowing you to style individual slides.
|
|
In beamer, a number of heading classes and attributes are recognized as
|
|
frame options and will be passed through as options to the frame: see
|
|
Frame attributes in beamer, below.
|
|
.SS Speaker notes
|
|
Speaker notes are supported in reveal.js, PowerPoint (pptx), and beamer
|
|
output.
|
|
You can add notes to your Markdown document thus:
|
|
.IP
|
|
.EX
|
|
::: notes
|
|
|
|
This is my note.
|
|
|
|
\- It can contain Markdown
|
|
\- like this list
|
|
|
|
:::
|
|
.EE
|
|
.PP
|
|
To show the notes window in reveal.js, press \f[CR]s\f[R] while viewing
|
|
the presentation.
|
|
Speaker notes in PowerPoint will be available, as usual, in handouts and
|
|
presenter view.
|
|
.PP
|
|
Notes are not yet supported for other slide formats, but the notes will
|
|
not appear on the slides themselves.
|
|
.SS Speaker notes on the title slide (PowerPoint)
|
|
For PowerPoint output, the title slide is generated from the
|
|
document\(cqs YAML metadata block.
|
|
To add speaker notes to this slide, use a \f[CR]notes\f[R] field in the
|
|
metadata:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
title: My Presentation
|
|
author: Jane Doe
|
|
notes: |
|
|
Welcome everyone to this presentation.
|
|
|
|
Remember to introduce yourself and mention the key topics.
|
|
\-\-\-
|
|
.EE
|
|
.PP
|
|
The \f[CR]notes\f[R] field can contain multiple paragraphs and Markdown
|
|
formatting.
|
|
.SS Columns
|
|
To put material in side by side columns, you can use a native div
|
|
container with class \f[CR]columns\f[R], containing two or more div
|
|
containers with class \f[CR]column\f[R] and a \f[CR]width\f[R]
|
|
attribute:
|
|
.IP
|
|
.EX
|
|
:::::::::::::: {.columns}
|
|
::: {.column width=\(dq40%\(dq}
|
|
contents...
|
|
:::
|
|
::: {.column width=\(dq60%\(dq}
|
|
contents...
|
|
:::
|
|
::::::::::::::
|
|
.EE
|
|
.PP
|
|
Note: Specifying column widths does not currently work for PowerPoint.
|
|
.SS Additional columns attributes in beamer
|
|
The div containers with classes \f[CR]columns\f[R] and \f[CR]column\f[R]
|
|
can optionally have an \f[CR]align\f[R] attribute.
|
|
The class \f[CR]columns\f[R] can optionally have a \f[CR]totalwidth\f[R]
|
|
attribute or an \f[CR]onlytextwidth\f[R] class.
|
|
.IP
|
|
.EX
|
|
:::::::::::::: {.columns align=center totalwidth=8em}
|
|
::: {.column width=\(dq40%\(dq}
|
|
contents...
|
|
:::
|
|
::: {.column width=\(dq60%\(dq align=bottom}
|
|
contents...
|
|
:::
|
|
::::::::::::::
|
|
.EE
|
|
.PP
|
|
The \f[CR]align\f[R] attributes on \f[CR]columns\f[R] and
|
|
\f[CR]column\f[R] can be used with the values \f[CR]top\f[R],
|
|
\f[CR]top\-baseline\f[R], \f[CR]center\f[R] and \f[CR]bottom\f[R] to
|
|
vertically align the columns.
|
|
It defaults to \f[CR]top\f[R] in \f[CR]columns\f[R].
|
|
.PP
|
|
The \f[CR]totalwidth\f[R] attribute limits the width of the columns to
|
|
the given value.
|
|
.IP
|
|
.EX
|
|
:::::::::::::: {.columns align=top .onlytextwidth}
|
|
::: {.column width=\(dq40%\(dq align=center}
|
|
contents...
|
|
:::
|
|
::: {.column width=\(dq60%\(dq}
|
|
contents...
|
|
:::
|
|
::::::::::::::
|
|
.EE
|
|
.PP
|
|
The class \f[CR]onlytextwidth\f[R] sets the \f[CR]totalwidth\f[R] to
|
|
\f[CR]\(rstextwidth\f[R].
|
|
.PP
|
|
See Section 12.7 of the Beamer User\(cqs Guide for more details.
|
|
.SS Frame attributes in beamer
|
|
Sometimes it is necessary to add the LaTeX \f[CR][fragile]\f[R] option
|
|
to a frame in beamer (for example, when using the \f[CR]minted\f[R]
|
|
environment).
|
|
This can be forced by adding the \f[CR]fragile\f[R] class to the heading
|
|
introducing the slide:
|
|
.IP
|
|
.EX
|
|
# Fragile slide {.fragile}
|
|
.EE
|
|
.PP
|
|
All of the other frame attributes described in Section 8.1 of the Beamer
|
|
User\(cqs Guide may also be used: \f[CR]allowdisplaybreaks\f[R],
|
|
\f[CR]allowframebreaks\f[R], \f[CR]b\f[R], \f[CR]c\f[R], \f[CR]s\f[R],
|
|
\f[CR]t\f[R], \f[CR]environment\f[R], \f[CR]label\f[R],
|
|
\f[CR]plain\f[R], \f[CR]shrink\f[R], \f[CR]standout\f[R],
|
|
\f[CR]noframenumbering\f[R], \f[CR]squeeze\f[R].
|
|
\f[CR]allowframebreaks\f[R] is recommended especially for
|
|
bibliographies, as it allows multiple slides to be created if the
|
|
content overfills the frame:
|
|
.IP
|
|
.EX
|
|
# References {.allowframebreaks}
|
|
.EE
|
|
.PP
|
|
In addition, the \f[CR]frameoptions\f[R] attribute may be used to pass
|
|
arbitrary frame options to a beamer slide:
|
|
.IP
|
|
.EX
|
|
# Heading {frameoptions=\(dqsqueeze,shrink,customoption=foobar\(dq}
|
|
.EE
|
|
.SS Background in reveal.js, beamer, and pptx
|
|
Background images can be added to self\-contained reveal.js slide shows,
|
|
beamer slide shows, and pptx slide shows.
|
|
.SS On all slides (beamer, reveal.js, pptx)
|
|
With beamer and reveal.js, the configuration option
|
|
\f[CR]background\-image\f[R] can be used either in the YAML metadata
|
|
block or as a command\-line variable to get the same image on every
|
|
slide.
|
|
.PP
|
|
Note that for reveal.js, the \f[CR]background\-image\f[R] will be used
|
|
as a \f[CR]parallaxBackgroundImage\f[R] (see below).
|
|
.PP
|
|
For pptx, you can use a \f[CR]\-\-reference\-doc\f[R] in which
|
|
background images have been set on the relevant layouts.
|
|
.SS \f[CR]parallaxBackgroundImage\f[R] (reveal.js)
|
|
For reveal.js, there is also the reveal.js\-native option
|
|
\f[CR]parallaxBackgroundImage\f[R], which produces a parallax scrolling
|
|
background.
|
|
You must also set \f[CR]parallaxBackgroundSize\f[R], and can optionally
|
|
set \f[CR]parallaxBackgroundHorizontal\f[R] and
|
|
\f[CR]parallaxBackgroundVertical\f[R] to configure the scrolling
|
|
behaviour.
|
|
See the reveal.js documentation for more details about the meaning of
|
|
these options.
|
|
.PP
|
|
In reveal.js\(cqs overview mode, the parallaxBackgroundImage will show
|
|
up only on the first slide.
|
|
.SS On individual slides (reveal.js, pptx)
|
|
To set an image for a particular reveal.js or pptx slide, add
|
|
\f[CR]{background\-image=\(dq/path/to/image\(dq}\f[R] to the first
|
|
slide\-level heading on the slide (which may even be empty).
|
|
.PP
|
|
As the HTML writers pass unknown attributes through, other reveal.js
|
|
background settings also work on individual slides, including
|
|
\f[CR]background\-size\f[R], \f[CR]background\-repeat\f[R],
|
|
\f[CR]background\-color\f[R], \f[CR]transition\f[R], and
|
|
\f[CR]transition\-speed\f[R].
|
|
(The \f[CR]data\-\f[R] prefix will automatically be added.)
|
|
.PP
|
|
Note: \f[CR]data\-background\-image\f[R] is also supported in pptx for
|
|
consistency with reveal.js \(en if \f[CR]background\-image\f[R] isn\(cqt
|
|
found, \f[CR]data\-background\-image\f[R] will be checked.
|
|
.SS On the title slide (reveal.js, pptx)
|
|
To add a background image to the automatically generated title slide for
|
|
reveal.js, use the \f[CR]title\-slide\-attributes\f[R] variable in the
|
|
YAML metadata block.
|
|
It must contain a map of attribute names and values.
|
|
(Note that the \f[CR]data\-\f[R] prefix is required here, as it isn\(cqt
|
|
added automatically.)
|
|
.PP
|
|
For pptx, pass a \f[CR]\-\-reference\-doc\f[R] with the background image
|
|
set on the \(lqTitle Slide\(rq layout.
|
|
.SS Example (reveal.js)
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
title: My Slide Show
|
|
parallaxBackgroundImage: /path/to/my/background_image.png
|
|
title\-slide\-attributes:
|
|
data\-background\-image: /path/to/title_image.png
|
|
data\-background\-size: contain
|
|
\-\-\-
|
|
|
|
## Slide One
|
|
|
|
Slide 1 has background_image.png as its background.
|
|
|
|
## {background\-image=\(dq/path/to/special_image.jpg\(dq}
|
|
|
|
Slide 2 has a special image for its background, even though the heading has no content.
|
|
.EE
|
|
.SH EPUBS
|
|
.SS EPUB Metadata
|
|
There are two ways to specify metadata for an EPUB.
|
|
The first is to use the \f[CR]\-\-epub\-metadata\f[R] option, which
|
|
takes as its argument an XML file with Dublin Core elements.
|
|
.PP
|
|
The second way is to use YAML, either in a YAML metadata block in a
|
|
Markdown document, or in a separate YAML file specified with
|
|
\f[CR]\-\-metadata\-file\f[R].
|
|
Here is an example of a YAML metadata block with EPUB metadata:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
title:
|
|
\- type: main
|
|
text: My Book
|
|
\- type: subtitle
|
|
text: An investigation of metadata
|
|
creator:
|
|
\- role: author
|
|
text: John Smith
|
|
\- role: editor
|
|
text: Sarah Jones
|
|
identifier:
|
|
\- scheme: DOI
|
|
text: \(aqurn:doi:10.234234.234/33\(aq
|
|
\- scheme: ISBN\-13
|
|
text: \(aqurn:isbn:9780000000000\(aq
|
|
publisher: My Press
|
|
rights: © 2007 John Smith, CC BY\-NC
|
|
ibooks:
|
|
version: 1.3.4
|
|
\&...
|
|
.EE
|
|
.PP
|
|
The following fields are recognized:
|
|
.TP
|
|
\f[CR]identifier\f[R]
|
|
Either a string value, or an object with fields \f[CR]text\f[R] and
|
|
\f[CR]scheme\f[R] (optional), or a list of such objects.
|
|
Valid values for \f[CR]scheme\f[R] are \f[CR]ISBN\-10\f[R],
|
|
\f[CR]GTIN\-13\f[R], \f[CR]UPC\f[R], \f[CR]ISMN\-10\f[R],
|
|
\f[CR]DOI\f[R], \f[CR]LCCN\f[R], \f[CR]GTIN\-14\f[R],
|
|
\f[CR]ISBN\-13\f[R], \f[CR]Legal deposit number\f[R], \f[CR]URN\f[R],
|
|
\f[CR]OCLC number\f[R], \f[CR]Co\-publisher\(cqs ISBN\-13\f[R],
|
|
\f[CR]ISMN\-13\f[R], \f[CR]ISBN\-A\f[R], \f[CR]JP e\-code\f[R],
|
|
\f[CR]OLCC number\f[R], \f[CR]JP Magazine ID\f[R], \f[CR]UPC\-12+5\f[R],
|
|
\f[CR]BNF Control number\f[R], \f[CR]ISSN\-13\f[R], \f[CR]ARK\f[R],
|
|
\f[CR]Digital file internal version number\f[R].
|
|
In the \f[CR]text\f[R] field, it is advisable to specify a URN as in the
|
|
examples above.
|
|
Note that quotes are needed around a YAML field containing a colon.
|
|
.TP
|
|
\f[CR]title\f[R]
|
|
Either a string value, or an object with fields \f[CR]text\f[R],
|
|
\f[CR]file\-as\f[R] (optional) and \f[CR]type\f[R] (optional), or a list
|
|
of such objects.
|
|
Valid values for \f[CR]type\f[R] are \f[CR]main\f[R],
|
|
\f[CR]subtitle\f[R], \f[CR]short\f[R], \f[CR]collection\f[R],
|
|
\f[CR]edition\f[R], \f[CR]extended\f[R].
|
|
.TP
|
|
\f[CR]creator\f[R]
|
|
Either a string value, or an object with fields \f[CR]text\f[R],
|
|
\f[CR]role\f[R] (optional), and \f[CR]file\-as\f[R] (optional), or a
|
|
list of such objects.
|
|
Valid values for \f[CR]role\f[R] are MARC relators, but pandoc will
|
|
attempt to translate the human\-readable versions (like \(lqauthor\(rq
|
|
and \(lqeditor\(rq) to the appropriate marc relators.
|
|
.TP
|
|
\f[CR]contributor\f[R]
|
|
Same format as \f[CR]creator\f[R].
|
|
.TP
|
|
\f[CR]date\f[R]
|
|
A string value in \f[CR]YYYY\-MM\-DD\f[R] format.
|
|
(Only the year is necessary.)
|
|
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.
|
|
Pandoc will default to the local language if nothing is specified.
|
|
.TP
|
|
\f[CR]subject\f[R]
|
|
Either a string value, or an object with fields \f[CR]text\f[R],
|
|
\f[CR]authority\f[R] (optional), and \f[CR]term\f[R] (optional), or a
|
|
list of such objects.
|
|
Valid values for \f[CR]authority\f[R] are either a reserved authority
|
|
value (currently \f[CR]AAT\f[R], \f[CR]BIC\f[R], \f[CR]BISAC\f[R],
|
|
\f[CR]CLC\f[R], \f[CR]DDC\f[R], \f[CR]CLIL\f[R], \f[CR]EuroVoc\f[R],
|
|
\f[CR]MEDTOP\f[R], \f[CR]LCSH\f[R], \f[CR]NDC\f[R], \f[CR]Thema\f[R],
|
|
\f[CR]UDC\f[R], and \f[CR]WGS\f[R]) or an absolute IRI identifying a
|
|
custom scheme.
|
|
Valid values for \f[CR]term\f[R] are defined by the scheme.
|
|
.TP
|
|
\f[CR]description\f[R]
|
|
A string value.
|
|
.TP
|
|
\f[CR]type\f[R]
|
|
A string value.
|
|
.TP
|
|
\f[CR]format\f[R]
|
|
A string value.
|
|
.TP
|
|
\f[CR]relation\f[R]
|
|
A string value.
|
|
.TP
|
|
\f[CR]coverage\f[R]
|
|
A string value.
|
|
.TP
|
|
\f[CR]rights\f[R]
|
|
A string value.
|
|
.TP
|
|
\f[CR]belongs\-to\-collection\f[R]
|
|
A string value.
|
|
Identifies the name of a collection to which the EPUB Publication
|
|
belongs.
|
|
.TP
|
|
\f[CR]group\-position\f[R]
|
|
The \f[CR]group\-position\f[R] field indicates the numeric position in
|
|
which the EPUB Publication belongs relative to other works belonging to
|
|
the same \f[CR]belongs\-to\-collection\f[R] field.
|
|
.TP
|
|
\f[CR]cover\-image\f[R]
|
|
A string value (path to cover image).
|
|
.TP
|
|
\f[CR]css\f[R] (or legacy: \f[CR]stylesheet\f[R])
|
|
A string value (path to CSS stylesheet).
|
|
.TP
|
|
\f[CR]page\-progression\-direction\f[R]
|
|
Either \f[CR]ltr\f[R] or \f[CR]rtl\f[R].
|
|
Specifies the \f[CR]page\-progression\-direction\f[R] attribute for the
|
|
\f[CR]spine\f[R] element.
|
|
.TP
|
|
\f[CR]accessModes\f[R]
|
|
An array of strings (schema).
|
|
Defaults to \f[CR][\(dqtextual\(dq]\f[R].
|
|
.TP
|
|
\f[CR]accessModeSufficient\f[R]
|
|
An array of strings (schema).
|
|
Defaults to \f[CR][\(dqtextual\(dq]\f[R].
|
|
.TP
|
|
\f[CR]accessibilityHazards\f[R]
|
|
An array of strings (schema).
|
|
Defaults to \f[CR][\(dqnone\(dq]\f[R].
|
|
.TP
|
|
\f[CR]accessibilityFeatures\f[R]
|
|
An array of strings (schema).
|
|
Defaults to
|
|
.RS
|
|
.IP
|
|
.EX
|
|
\- \(dqalternativeText\(dq
|
|
\- \(dqreadingOrder\(dq
|
|
\- \(dqstructuralNavigation\(dq
|
|
\- \(dqtableOfContents\(dq
|
|
.EE
|
|
.RE
|
|
.TP
|
|
\f[CR]accessibilitySummary\f[R]
|
|
A string value.
|
|
.TP
|
|
\f[CR]ibooks\f[R]
|
|
iBooks\-specific metadata, with the following fields:
|
|
.RS
|
|
.IP \(bu 2
|
|
\f[CR]version\f[R]: (string)
|
|
.IP \(bu 2
|
|
\f[CR]specified\-fonts\f[R]: \f[CR]true\f[R]|\f[CR]false\f[R] (default
|
|
\f[CR]false\f[R])
|
|
.IP \(bu 2
|
|
\f[CR]ipad\-orientation\-lock\f[R]:
|
|
\f[CR]portrait\-only\f[R]|\f[CR]landscape\-only\f[R]
|
|
.IP \(bu 2
|
|
\f[CR]iphone\-orientation\-lock\f[R]:
|
|
\f[CR]portrait\-only\f[R]|\f[CR]landscape\-only\f[R]
|
|
.IP \(bu 2
|
|
\f[CR]binding\f[R]: \f[CR]true\f[R]|\f[CR]false\f[R] (default
|
|
\f[CR]true\f[R])
|
|
.IP \(bu 2
|
|
\f[CR]scroll\-axis\f[R]:
|
|
\f[CR]vertical\f[R]|\f[CR]horizontal\f[R]|\f[CR]default\f[R]
|
|
.RE
|
|
.SS The \f[CR]epub:type\f[R] attribute
|
|
For \f[CR]epub3\f[R] output, you can mark up the heading that
|
|
corresponds to an EPUB chapter using the \f[CR]epub:type\f[R] attribute.
|
|
For example, to set the attribute to the value \f[CR]prologue\f[R], use
|
|
this Markdown:
|
|
.IP
|
|
.EX
|
|
# My chapter {epub:type=prologue}
|
|
.EE
|
|
.PP
|
|
Which will result in:
|
|
.IP
|
|
.EX
|
|
<body epub:type=\(dqfrontmatter\(dq>
|
|
<section epub:type=\(dqprologue\(dq>
|
|
<h1>My chapter</h1>
|
|
.EE
|
|
.PP
|
|
Pandoc will output \f[CR]<body epub:type=\(dqbodymatter\(dq>\f[R],
|
|
unless you use one of the following values, in which case either
|
|
\f[CR]frontmatter\f[R] or \f[CR]backmatter\f[R] will be output.
|
|
.RS -14n
|
|
.IP
|
|
.EX
|
|
epub:type of first section epub:type of body
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
prologue frontmatter
|
|
abstract frontmatter
|
|
acknowledgments frontmatter
|
|
copyright\-page frontmatter
|
|
dedication frontmatter
|
|
credits frontmatter
|
|
keywords frontmatter
|
|
imprint frontmatter
|
|
contributors frontmatter
|
|
other\-credits frontmatter
|
|
errata frontmatter
|
|
revision\-history frontmatter
|
|
titlepage frontmatter
|
|
halftitlepage frontmatter
|
|
seriespage frontmatter
|
|
foreword frontmatter
|
|
preface frontmatter
|
|
frontispiece frontmatter
|
|
appendix backmatter
|
|
colophon backmatter
|
|
bibliography backmatter
|
|
index backmatter
|
|
.EE
|
|
.RE
|
|
.SS Linked media
|
|
By default, pandoc will download media referenced from any
|
|
\f[CR]<img>\f[R], \f[CR]<audio>\f[R], \f[CR]<video>\f[R] or
|
|
\f[CR]<source>\f[R] element present in the generated EPUB, and include
|
|
it in the EPUB container, yielding a completely self\-contained EPUB.
|
|
If you want to link to external media resources instead, use raw HTML in
|
|
your source and add \f[CR]data\-external=\(dq1\(dq\f[R] to the tag with
|
|
the \f[CR]src\f[R] attribute.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
<audio controls=\(dq1\(dq>
|
|
<source src=\(dqhttps://example.com/music/toccata.mp3\(dq
|
|
data\-external=\(dq1\(dq type=\(dqaudio/mpeg\(dq>
|
|
</source>
|
|
</audio>
|
|
.EE
|
|
.PP
|
|
If the input format already is HTML then
|
|
\f[CR]data\-external=\(dq1\(dq\f[R] will work as expected for
|
|
\f[CR]<img>\f[R] elements.
|
|
Similarly, for Markdown, external images can be declared with
|
|
\f[CR]{external=1}\f[R].
|
|
Note that this only works for images; the other media elements have no
|
|
native representation in pandoc\(cqs AST and require the use of raw
|
|
HTML.
|
|
.SS EPUB styling
|
|
By default, pandoc will include some basic styling contained in its
|
|
\f[CR]epub.css\f[R] data file.
|
|
(To see this, use
|
|
\f[CR]pandoc \-\-print\-default\-data\-file epub.css\f[R].)
|
|
To use a different CSS file, just use the \f[CR]\-\-css\f[R] command
|
|
line option.
|
|
A few inline styles are defined in addition; these are essential for
|
|
correct formatting of pandoc\(cqs HTML output.
|
|
.PP
|
|
The \f[CR]document\-css\f[R] variable may be set if the more opinionated
|
|
styling of pandoc\(cqs default HTML templates is desired (and in that
|
|
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
|
|
HTML files, one for each section of the original document.
|
|
Internal links will automatically be adjusted to point to the right
|
|
place, images linked to under the working directory will be
|
|
incorporated, and navigation links will be added.
|
|
In addition, a JSON file \f[CR]sitemap.json\f[R] will be included
|
|
describing the hierarchical structure of the files.
|
|
.PP
|
|
If an output file without an extension is specified, then it will be
|
|
interpreted as a directory and the zip archive will be automatically
|
|
unpacked into it (unless it already exists, in which case an error will
|
|
be raised).
|
|
Otherwise a \f[CR].zip\f[R] file will be produced.
|
|
.PP
|
|
The navigation links can be customized by adjusting the template.
|
|
By default, a table of contents is included only on the top page.
|
|
To include it on every page, set the \f[CR]toc\f[R] variable manually.
|
|
.SH JUPYTER NOTEBOOKS
|
|
When creating a Jupyter notebook, pandoc will try to infer the notebook
|
|
structure.
|
|
Code blocks with the class \f[CR]code\f[R] will be taken as code cells,
|
|
and intervening content will be taken as Markdown cells.
|
|
Attachments will automatically be created for images in Markdown cells.
|
|
Metadata will be taken from the \f[CR]jupyter\f[R] metadata field.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
title: My notebook
|
|
jupyter:
|
|
nbformat: 4
|
|
nbformat_minor: 5
|
|
kernelspec:
|
|
display_name: Python 2
|
|
language: python
|
|
name: python2
|
|
language_info:
|
|
codemirror_mode:
|
|
name: ipython
|
|
version: 2
|
|
file_extension: \(dq.py\(dq
|
|
mimetype: \(dqtext/x\-python\(dq
|
|
name: \(dqpython\(dq
|
|
nbconvert_exporter: \(dqpython\(dq
|
|
pygments_lexer: \(dqipython2\(dq
|
|
version: \(dq2.7.15\(dq
|
|
\-\-\-
|
|
|
|
# Lorem ipsum
|
|
|
|
**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
|
|
bibendum felis dictum sodales.
|
|
|
|
\(ga\(ga\(ga code
|
|
print(\(dqhello\(dq)
|
|
\(ga\(ga\(ga
|
|
|
|
## Pyout
|
|
|
|
\(ga\(ga\(ga code
|
|
from IPython.display import HTML
|
|
HTML(\(dq\(dq\(dq
|
|
<script>
|
|
console.log(\(dqhello\(dq);
|
|
</script>
|
|
<b>HTML</b>
|
|
\(dq\(dq\(dq)
|
|
\(ga\(ga\(ga
|
|
|
|
## Image
|
|
|
|
This image  will be
|
|
included as a cell attachment.
|
|
.EE
|
|
.PP
|
|
If you want to add cell attributes, group cells differently, or add
|
|
output to code cells, then you need to include divs to indicate the
|
|
structure.
|
|
You can use either fenced divs or native divs for this.
|
|
Here is an example:
|
|
.IP
|
|
.EX
|
|
:::::: {.cell .markdown}
|
|
# Lorem
|
|
|
|
**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
|
|
bibendum felis dictum sodales.
|
|
::::::
|
|
|
|
:::::: {.cell .code execution_count=1}
|
|
\(ga\(ga\(ga {.python}
|
|
print(\(dqhello\(dq)
|
|
\(ga\(ga\(ga
|
|
|
|
::: {.output .stream .stdout}
|
|
\(ga\(ga\(ga
|
|
hello
|
|
\(ga\(ga\(ga
|
|
:::
|
|
::::::
|
|
|
|
:::::: {.cell .code execution_count=2}
|
|
\(ga\(ga\(ga {.python}
|
|
from IPython.display import HTML
|
|
HTML(\(dq\(dq\(dq
|
|
<script>
|
|
console.log(\(dqhello\(dq);
|
|
</script>
|
|
<b>HTML</b>
|
|
\(dq\(dq\(dq)
|
|
\(ga\(ga\(ga
|
|
|
|
::: {.output .execute_result execution_count=2}
|
|
\(ga\(ga\(ga{=html}
|
|
<script>
|
|
console.log(\(dqhello\(dq);
|
|
</script>
|
|
<b>HTML</b>
|
|
hello
|
|
\(ga\(ga\(ga
|
|
:::
|
|
::::::
|
|
.EE
|
|
.PP
|
|
If you include raw HTML or TeX in an output cell, use the raw attribute,
|
|
as shown in the last cell of the example above.
|
|
Although pandoc can process \(lqbare\(rq raw HTML and TeX, the result is
|
|
often interspersed raw elements and normal textual elements, and in an
|
|
output cell pandoc expects a single, connected raw block.
|
|
To avoid using raw HTML or TeX except when marked explicitly using raw
|
|
attributes, we recommend specifying the extensions
|
|
\f[CR]\-raw_html\-raw_tex+raw_attribute\f[R] when translating between
|
|
Markdown and ipynb notebooks.
|
|
.PP
|
|
Note that options and extensions that affect reading and writing of
|
|
Markdown will also affect Markdown cells in ipynb notebooks.
|
|
For example, \f[CR]\-\-wrap=preserve\f[R] will preserve soft line breaks
|
|
in Markdown cells; \f[CR]\-\-markdown\-headings=setext\f[R] will cause
|
|
Setext\-style headings to be used; and \f[CR]\-\-preserve\-tabs\f[R]
|
|
will prevent tabs from being turned to spaces.
|
|
.SH VIMDOC
|
|
Vimdoc writer generates Vim help files and makes use of the following
|
|
metadata variables:
|
|
.IP
|
|
.EX
|
|
abstract\f[B]:\f[R] \(dqA short description\(dq
|
|
author\f[B]:\f[R] Author
|
|
title\f[B]:\f[R] Title
|
|
|
|
\f[I]# Vimdoc\-specific\f[R]
|
|
filename\f[B]:\f[R] \(dqdefinition\-lists.txt\(dq
|
|
vimdoc\-prefix\f[B]:\f[R] pandoc
|
|
.EE
|
|
.PP
|
|
Complete header requires \f[CR]abstract\f[R], \f[CR]author\f[R],
|
|
\f[CR]title\f[R] and \f[CR]filename\f[R] to be set.
|
|
Compiling file with such metadata produces the following file (assumes
|
|
\f[CR]\-\-standalone\f[R], see Templates):
|
|
.IP
|
|
.EX
|
|
*definition\-lists.txt* A short description
|
|
|
|
Title by Author
|
|
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
[...]
|
|
|
|
vim:tw=72:sw=4:ts=4:ft=help:norl:et:
|
|
.EE
|
|
.PP
|
|
If \f[CR]vimdoc\-prefix\f[R] is set, all non\-command tags are prefixed
|
|
with its value, it is used to prevent tag collision: all headers have a
|
|
tag (either inferred or explicit) and multiple help pages can have the
|
|
same header names, therefore collision is to be expected.
|
|
Let our input be the following markdown file:
|
|
.IP
|
|
.EX
|
|
## Header
|
|
|
|
\f[BI]\(ga:[range]Fnl {expr}\(ga\f[R]{#:Fnl}
|
|
: Evaluates {expr} or range
|
|
|
|
\f[BI]\(gavim.b\(ga\f[R]{#vim.b}
|
|
: Buffer\-scoped (\f[BI]\(ga:h b:\(ga\f[R]) variables for the current buffer. Invalid or unset
|
|
key returns \f[BI]\(ganil\(ga\f[R]. Can be indexed with an integer to access variables for a
|
|
specific buffer.
|
|
|
|
\f[I][\f[R]Span\f[I]]\f[R]{#span}
|
|
: generic inline container for phrasing content, which does not inherently
|
|
represent anything.
|
|
.EE
|
|
.PP
|
|
Convert it to vimdoc:
|
|
.IP
|
|
.EX
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
Header *header*
|
|
|
|
:[range]Fnl {expr} *:Fnl*
|
|
Evaluates {expr} or range
|
|
\(gavim.b\(ga *vim.b*
|
|
Buffer\-scoped (|b:|) variables for the current buffer. Invalid or
|
|
unset key returns \(ganil\(ga. Can be indexed with an integer to access
|
|
variables for a specific buffer.
|
|
Span *span*
|
|
generic inline container for phrasing content, which does not
|
|
inherently represent anything.
|
|
.EE
|
|
.PP
|
|
Convert it to vimdoc with metadata variable set (e.g.\ with
|
|
\f[CR]\-M vimdoc\-prefix=pandoc\f[R])
|
|
.IP
|
|
.EX
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
Header *pandoc\-header*
|
|
|
|
:[range]Fnl {expr} *:Fnl*
|
|
Evaluates {expr} or range
|
|
\(gavim.b\(ga *pandoc\-vim.b*
|
|
Buffer\-scoped (|b:|) variables for the current buffer. Invalid or
|
|
unset key returns \(ganil\(ga. Can be indexed with an integer to access
|
|
variables for a specific buffer.
|
|
Span *pandoc\-span*
|
|
generic inline container for phrasing content, which does not
|
|
inherently represent anything.
|
|
.EE
|
|
.PP
|
|
\f[CR]vim.b\f[R] and \f[CR]Span\f[R] got their prefixes but not
|
|
\f[CR]:Fnl\f[R] because ex\-commands (those starting with \f[CR]:\f[R])
|
|
don\(cqt get a prefix, since they are considered unique across help
|
|
pages.
|
|
.PP
|
|
In both cases \f[CR]:help b:\f[R] became reference \f[CR]|b:|\f[R] (also
|
|
works with \f[CR]:h b:\f[R]).
|
|
Links pointing to either https://vimhelp.org/ or
|
|
https://neovim.io/doc/user become references too.
|
|
.PP
|
|
Vim traditionally wraps at 78, but Pandoc defaults to 72.
|
|
Use \f[CR]\-\-columns 78\f[R] to match Vim.
|
|
.SH SYNTAX HIGHLIGHTING
|
|
Pandoc will automatically highlight syntax in fenced code blocks that
|
|
are marked with a language name.
|
|
The Haskell library skylighting is used for highlighting.
|
|
Currently highlighting is supported only for HTML, EPUB, Docx, Ms, Man,
|
|
Typst, and LaTeX/PDF output.
|
|
To see a list of language names that pandoc will recognize, type
|
|
\f[CR]pandoc \-\-list\-highlight\-languages\f[R].
|
|
.PP
|
|
The color scheme can be selected using the
|
|
\f[CR]\-\-syntax\-highlighting\f[R] option.
|
|
The default color scheme is \f[CR]pygments\f[R], which imitates the
|
|
default color scheme used by the Python library pygments (though
|
|
pygments is not actually used to do the highlighting).
|
|
To see a list of highlight styles, type
|
|
\f[CR]pandoc \-\-list\-highlight\-styles\f[R].
|
|
.PP
|
|
If you are not satisfied with the predefined styles, you can use
|
|
\f[CR]\-\-print\-highlight\-style\f[R] to generate a JSON
|
|
\f[CR].theme\f[R] file which can be modified and used as the argument to
|
|
\f[CR]\-\-syntax\-highlighting\f[R].
|
|
To get a JSON version of the \f[CR]pygments\f[R] style, for example:
|
|
.IP
|
|
.EX
|
|
pandoc \-o my.theme \-\-print\-highlight\-style pygments
|
|
.EE
|
|
.PP
|
|
Then edit \f[CR]my.theme\f[R] and use it like this:
|
|
.IP
|
|
.EX
|
|
pandoc \-\-syntax\-highlighting my.theme
|
|
.EE
|
|
.PP
|
|
If you are not satisfied with the built\-in highlighting, or you want to
|
|
highlight a language that isn\(cqt supported, you can use the
|
|
\f[CR]\-\-syntax\-definition\f[R] option to load a KDE\-style XML syntax
|
|
definition file.
|
|
Before writing your own, have a look at KDE\(cqs repository of syntax
|
|
definitions.
|
|
.PP
|
|
If you receive an error that pandoc \(lqCould not read highlighting
|
|
theme\(rq, check that the JSON file is encoded with UTF\-8 and has no
|
|
Byte\-Order Mark (BOM).
|
|
.PP
|
|
To disable highlighting, use \f[CR]\-\-syntax\-highlighting=none\f[R].
|
|
.PP
|
|
To use a format\(cqs idiomatic syntax highlighting instead of
|
|
pandoc\(cqs built\-in highlighting, use
|
|
\f[CR]\-\-syntax\-highlighting=idiomatic\f[R].
|
|
Currently, \f[CR]idiomatic\f[R] only affects the following formats:
|
|
.IP \(bu 2
|
|
In reveal.js, it causes reveal.js\(cqs highlighting plugin to be used
|
|
for source code highlighting.
|
|
The style may be customized by setting the \f[CR]highlightjs\-theme\f[R]
|
|
variable.
|
|
.IP \(bu 2
|
|
In Typst, it causes Typst\(cqs built\-in highlighting to be used.
|
|
(This is also the default for Typst.)
|
|
.IP \(bu 2
|
|
In LaTeX, it causes the \f[CR]listings\f[R] package to be used.
|
|
Note that \f[CR]listings\f[R] does not support multi\-byte encoding for
|
|
source code.
|
|
To handle UTF\-8 you would need to use a custom template.
|
|
This issue is fully documented here: Encoding issue with the listings
|
|
package.
|
|
.IP \(bu 2
|
|
In other formats, \f[CR]idiomatic\f[R] will have the same result as
|
|
\f[CR]default\f[R].
|
|
.SH CUSTOM STYLES
|
|
Custom styles can be used in the docx, odt and ICML formats.
|
|
.SS Output
|
|
By default, pandoc\(cqs odt, docx and ICML output applies a predefined
|
|
set of styles for blocks such as paragraphs and block quotes, and uses
|
|
largely default formatting (italics, bold) for inlines.
|
|
This will work for most purposes, especially alongside a reference doc
|
|
file.
|
|
However, if you need to apply your own styles to blocks, or match a
|
|
preexisting set of styles, pandoc allows you to define custom styles for
|
|
blocks and text using \f[CR]div\f[R]s and \f[CR]span\f[R]s,
|
|
respectively.
|
|
.PP
|
|
If you define a Div, Span, or Table with the attribute
|
|
\f[CR]custom\-style\f[R], pandoc will apply your specified style to the
|
|
contained elements (with the exception of elements whose function
|
|
depends on a style, like headings, code blocks, block quotes, or links).
|
|
So, for example, using the \f[CR]bracketed_spans\f[R] syntax,
|
|
.IP
|
|
.EX
|
|
[Get out]{custom\-style=\(dqEmphatically\(dq}, he said.
|
|
.EE
|
|
.PP
|
|
would produce a file with \(lqGet out\(rq styled with character style
|
|
\f[CR]Emphatically\f[R].
|
|
Similarly, using the \f[CR]fenced_divs\f[R] syntax,
|
|
.IP
|
|
.EX
|
|
Dickinson starts the poem simply:
|
|
|
|
::: {custom\-style=\(dqPoetry\(dq}
|
|
| A Bird came down the Walk\-\-\-
|
|
| He did not know I saw\-\-\-
|
|
:::
|
|
.EE
|
|
.PP
|
|
would style the two contained lines with the \f[CR]Poetry\f[R] paragraph
|
|
style.
|
|
.PP
|
|
Styles will be defined in the output file as inheriting from normal text
|
|
(docx) or Default Paragraph Style (odt), if the styles are not yet in
|
|
your reference doc.
|
|
If they are already defined, pandoc will not alter the definition.
|
|
.PP
|
|
This feature allows for greatest customization in conjunction with
|
|
pandoc filters.
|
|
If you want all paragraphs after block quotes to be indented, you can
|
|
write a filter to apply the styles necessary.
|
|
If you want all italics to be transformed to the \f[CR]Emphasis\f[R]
|
|
character style (perhaps to change their color), you can write a filter
|
|
which will transform all italicized inlines to inlines within an
|
|
\f[CR]Emphasis\f[R] custom\-style \f[CR]span\f[R].
|
|
.PP
|
|
For docx or odt output, you don\(cqt need to enable any extensions for
|
|
custom styles to work.
|
|
.PP
|
|
For icml output, you can also set an \f[CR]object\-style\f[R] in images:
|
|
.IP
|
|
.EX
|
|
{object\-style=\(dqfixedSizeImage\(dq}
|
|
.EE
|
|
.PP
|
|
In InDesign you\(cqll see that object style given to the image, and
|
|
you\(cqll be able to customize it, or load its definition from a
|
|
template of yours.
|
|
.SS Input
|
|
The docx reader, by default, only reads those styles that it can convert
|
|
into pandoc elements, either by direct conversion or interpreting the
|
|
derivation of the input document\(cqs styles.
|
|
.PP
|
|
By enabling the \f[CR]styles\f[R] extension in the docx reader
|
|
(\f[CR]\-f docx+styles\f[R]), you can produce output that maintains the
|
|
styles of the input document, using the \f[CR]custom\-style\f[R] class.
|
|
A \f[CR]custom\-style\f[R] attribute will be added for each style.
|
|
Divs will be created to hold the paragraph styles, and Spans to hold the
|
|
character styles.
|
|
Table styles will be applied directly to the Table.
|
|
.PP
|
|
For example, using the \f[CR]custom\-style\-reference.docx\f[R] file in
|
|
the test directory, we have the following different outputs:
|
|
.PP
|
|
Without the \f[CR]+styles\f[R] extension:
|
|
.IP
|
|
.EX
|
|
$ pandoc test/docx/custom\-style\-reference.docx \-f docx \-t markdown
|
|
This is some text.
|
|
|
|
This is text with an *emphasized* text style. And this is text with a
|
|
**strengthened** text style.
|
|
|
|
> Here is a styled paragraph that inherits from Block Text.
|
|
.EE
|
|
.PP
|
|
And with the extension:
|
|
.IP
|
|
.EX
|
|
$ pandoc test/docx/custom\-style\-reference.docx \-f docx+styles \-t markdown
|
|
|
|
::: {custom\-style=\(dqFirst Paragraph\(dq}
|
|
This is some text.
|
|
:::
|
|
|
|
::: {custom\-style=\(dqBody Text\(dq}
|
|
This is text with an [emphasized]{custom\-style=\(dqEmphatic\(dq} text style.
|
|
And this is text with a [strengthened]{custom\-style=\(dqStrengthened\(dq}
|
|
text style.
|
|
:::
|
|
|
|
::: {custom\-style=\(dqMy Block Style\(dq}
|
|
> Here is a styled paragraph that inherits from Block Text.
|
|
:::
|
|
.EE
|
|
.PP
|
|
With these custom styles, you can use your input document as a
|
|
reference\-doc while creating docx output (see below), and maintain the
|
|
same styles in your input and output files.
|
|
.SH CUSTOM READERS AND WRITERS
|
|
Pandoc can be extended with custom readers and writers written in Lua.
|
|
(Pandoc includes a Lua interpreter, so Lua need not be installed
|
|
separately.)
|
|
.PP
|
|
To use a custom reader or writer, simply specify the path to the Lua
|
|
script in place of the input or output format.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
pandoc \-t data/sample.lua
|
|
pandoc \-f my_custom_markup_language.lua \-t latex \-s
|
|
.EE
|
|
.PP
|
|
If the script is not found relative to the working directory, it will be
|
|
sought in the \f[CR]custom\f[R] subdirectory of the user data directory
|
|
(see \f[CR]\-\-data\-dir\f[R]).
|
|
.PP
|
|
A custom reader is a Lua script that defines one function, Reader, which
|
|
takes a string as input and returns a Pandoc AST.
|
|
See the Lua filters documentation for documentation of the functions
|
|
that are available for creating pandoc AST elements.
|
|
For parsing, the lpeg parsing library is available by default.
|
|
To see a sample custom reader:
|
|
.IP
|
|
.EX
|
|
pandoc \-\-print\-default\-data\-file creole.lua
|
|
.EE
|
|
.PP
|
|
If you want your custom reader to have access to reader options
|
|
(e.g.\ the tab stop setting), you give your Reader function a second
|
|
\f[CR]options\f[R] parameter.
|
|
.PP
|
|
A custom writer is a Lua script that defines a function that specifies
|
|
how to render each element in a Pandoc AST.
|
|
See the djot\-writer.lua for a full\-featured example.
|
|
.PP
|
|
Note that custom writers have no default template.
|
|
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).
|
|
.SH REPRODUCIBLE BUILDS
|
|
Some of the document formats pandoc targets (such as EPUB, docx, and
|
|
ODT) include build timestamps in the generated document.
|
|
That means that the files generated on successive builds will differ,
|
|
even if the source does not.
|
|
To avoid this, set the \f[CR]SOURCE_DATE_EPOCH\f[R] environment
|
|
variable, and the timestamp will be taken from it instead of the current
|
|
time.
|
|
\f[CR]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp
|
|
(specifying the number of seconds since midnight UTC January 1, 1970).
|
|
.PP
|
|
For reproducible builds with LaTeX, you can either specify the
|
|
\f[CR]pdf\-trailer\-id\f[R] in the metadata or leave it undefined, in
|
|
which case pandoc will create a trailer\-id based on a hash of the
|
|
\f[CR]SOURCE_DATE_EPOCH\f[R] and the document\(cqs contents.
|
|
.PP
|
|
Some document formats also include a unique identifier.
|
|
For EPUB, this can be set explicitly by setting the
|
|
\f[CR]identifier\f[R] metadata field (see EPUB Metadata, above).
|
|
.SH ACCESSIBLE PDFS AND PDF ARCHIVING STANDARDS
|
|
PDF is a flexible format, and using PDF in certain contexts requires
|
|
additional conventions.
|
|
For example, PDFs are not accessible by default; they define how
|
|
characters are placed on a page but do not contain semantic information
|
|
on the content.
|
|
However, it is possible to generate accessible PDFs, which use tagging
|
|
to add semantic information to the document.
|
|
.PP
|
|
Pandoc defaults to LaTeX to generate PDF.
|
|
LaTeX\(cqs \f[CR]\(rsDocumentMetadata\f[R] interface supports PDF
|
|
standards and tagging when using LuaLaTeX; set the
|
|
\f[CR]pdfstandard\f[R] variable to enable this (see below).
|
|
For older LaTeX installations, alternative engines must be used.
|
|
.PP
|
|
The PDF standards PDF/A and PDF/UA define further restrictions intended
|
|
to optimize PDFs for archiving and accessibility.
|
|
Tagging is commonly used in combination with these standards to ensure
|
|
best results.
|
|
.PP
|
|
Note, however, that standard compliance depends on many things,
|
|
including the colorspace of embedded images.
|
|
Pandoc cannot check this, and external programs must be used to ensure
|
|
that generated PDFs are in compliance.
|
|
.SS LaTeX
|
|
Set the \f[CR]pdfstandard\f[R] variable to produce tagged PDFs
|
|
conforming to PDF/A, PDF/X, or PDF/UA standards.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
pandoc \-V pdfstandard=ua\-2 \-\-pdf\-engine=lualatex doc.md \-o doc.pdf
|
|
.EE
|
|
.PP
|
|
Multiple standards can be combined:
|
|
.IP
|
|
.EX
|
|
\-\-\-
|
|
pdfstandard:
|
|
\- ua\-2
|
|
\- a\-4f
|
|
\-\-\-
|
|
.EE
|
|
.PP
|
|
The required PDF version is inferred automatically.
|
|
This feature requires LuaLaTeX in TeX Live 2025 with LaTeX kernel
|
|
2025\-06\-01 or newer.
|
|
.SS ConTeXt
|
|
ConTeXt always produces tagged PDFs, but the quality depends on the
|
|
input.
|
|
The default ConTeXt markup generated by pandoc is optimized for
|
|
readability and reuse, not tagging.
|
|
Enable the \f[CR]tagging\f[R] format extension to force markup that is
|
|
optimized for tagging.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
pandoc \-t context+tagging doc.md \-o doc.pdf
|
|
.EE
|
|
.PP
|
|
A recent \f[CR]context\f[R] version should be used, as older versions
|
|
contained a bug that lead to invalid PDF metadata.
|
|
.SS WeasyPrint
|
|
The HTML\-based engine WeasyPrint includes experimental support for
|
|
PDF/A and PDF/UA since version 57.
|
|
Tagged PDFs can created with
|
|
.IP
|
|
.EX
|
|
pandoc \-\-pdf\-engine=weasyprint \(rs
|
|
\-\-pdf\-engine\-opt=\-\-pdf\-variant=pdf/ua\-1 ...
|
|
.EE
|
|
.PP
|
|
The feature is experimental and standard compliance should not be
|
|
assumed.
|
|
.SS Prince XML
|
|
The non\-free HTML\-to\-PDF converter \f[CR]prince\f[R] has extensive
|
|
support for various PDF standards as well as tagging.
|
|
E.g.:
|
|
.IP
|
|
.EX
|
|
pandoc \-\-pdf\-engine=prince \(rs
|
|
\-\-pdf\-engine\-opt=\-\-tagged\-pdf ...
|
|
.EE
|
|
.PP
|
|
See the prince documentation for more info.
|
|
.SS Typst
|
|
Typst 0.12 can produce PDF/A\-2b:
|
|
.IP
|
|
.EX
|
|
pandoc \-\-pdf\-engine=typst \-\-pdf\-engine\-opt=\-\-pdf\-standard=a\-2b ...
|
|
.EE
|
|
.SS Word Processors
|
|
Word processors like LibreOffice and MS Word can also be used to
|
|
generate standardized and tagged PDF output.
|
|
Pandoc does not support direct conversions via these tools.
|
|
However, pandoc can convert a document to a \f[CR]docx\f[R] or
|
|
\f[CR]odt\f[R] file, which can then be opened and converted to PDF with
|
|
the respective word processor.
|
|
See the documentation for Word and LibreOffice.
|
|
.SH RUNNING PANDOC AS A WEB SERVER
|
|
If you rename (or symlink) the pandoc executable to
|
|
\f[CR]pandoc\-server\f[R], or if you call pandoc with \f[CR]server\f[R]
|
|
as the first argument, it will start up a web server with a JSON API.
|
|
This server exposes most of the conversion functionality of pandoc.
|
|
For full documentation, see the pandoc\-server man page.
|
|
.PP
|
|
If you rename (or symlink) the pandoc executable to
|
|
\f[CR]pandoc\-server.cgi\f[R], it will function as a CGI program
|
|
exposing the same API as \f[CR]pandoc\-server\f[R].
|
|
.PP
|
|
\f[CR]pandoc\-server\f[R] is designed to be maximally secure; it uses
|
|
Haskell\(cqs type system to provide strong guarantees that no I/O will
|
|
be performed on the server during pandoc conversions.
|
|
.SH RUNNING PANDOC AS A LUA INTERPRETER
|
|
Calling the pandoc executable under the name \f[CR]pandoc\-lua\f[R] or
|
|
with \f[CR]lua\f[R] as the first argument will make it function as a
|
|
standalone Lua interpreter.
|
|
The behavior is mostly identical to that of the standalone
|
|
\f[CR]lua\f[R] executable, version 5.4.
|
|
All \f[CR]pandoc.*\f[R] packages, as well as the packages \f[CR]re\f[R]
|
|
and \f[CR]lpeg\f[R], are available via global variables.
|
|
Furthermore, the globals \f[CR]PANDOC_VERSION\f[R],
|
|
\f[CR]PANDOC_STATE\f[R], and \f[CR]PANDOC_API_VERSION\f[R] are set at
|
|
startup.
|
|
For full documentation, see the pandoc\-lua man page.
|
|
.SH A NOTE ON SECURITY
|
|
.IP "1." 3
|
|
Although pandoc itself will not create or modify any files other than
|
|
those you explicitly ask it create (with the exception of temporary
|
|
files used in producing PDFs), a filter or custom writer could in
|
|
principle do anything on your file system.
|
|
Please audit filters and custom writers very carefully before using
|
|
them.
|
|
.IP "2." 3
|
|
If you want to use pandoc in a web application that accepts untrusted
|
|
user input, you should be aware that running pandoc in this context
|
|
requires special precautions, or you risk exfiltration of the contents
|
|
of local files, or worse.
|
|
In particular:
|
|
.RS 4
|
|
.IP \(bu 2
|
|
Several input formats (including LaTeX, Org, RST, and Typst) support
|
|
\f[CR]include\f[R] directives that allow the contents of a file to be
|
|
included in the output.
|
|
An untrusted attacker could use these to view the contents of files on
|
|
the file system.
|
|
Using the \f[CR]\-\-sandbox\f[R] option will protect against this
|
|
threat.
|
|
.IP \(bu 2
|
|
Several output formats (including RTF, FB2, HTML with
|
|
\f[CR]\-\-self\-contained\f[R], EPUB, Docx, and ODT) will embed encoded
|
|
or raw images into the output file.
|
|
An untrusted attacker could exploit this to view the contents of
|
|
non\-image files on the file system.
|
|
Using the \f[CR]\-\-sandbox\f[R] option will protect against this
|
|
threat, but will also prevent including images in these formats.
|
|
.IP \(bu 2
|
|
In reading HTML files, pandoc will attempt to include the contents of
|
|
\f[CR]iframe\f[R] elements by fetching content from the local file or
|
|
URL specified by \f[CR]src\f[R].
|
|
If untrusted HTML is processed on a server, this has the potential to
|
|
reveal anything readable by the process running the server or to enable
|
|
server\-side request forgery (SSRF) attacks (CVE\-2025\-51591).
|
|
To mitigate such attacks, use \f[CR]\-\-sandbox\f[R] or
|
|
\f[CR]\-f html+raw_html\f[R] (which causes the whole \f[CR]iframe\f[R]
|
|
to be parsed as a raw HTML block).
|
|
.IP \(bu 2
|
|
Using pandoc with \f[CR]\-\-pdf\-engine\f[R] introduces additional
|
|
risks, which cannot be mitigated by using \f[CR]\-\-sandbox\f[R].
|
|
For example, in \f[CR]wkhtmltopdf\f[R] the \f[CR]footer\-html\f[R] and
|
|
\f[CR]header\-html\f[R] metadata fields will be passed directly to
|
|
\f[CR]wkhtmltopdf\f[R] as \f[CR]\-\-footer\-html\f[R] and
|
|
\f[CR]\-\-header\-html\f[R] arguments, and by using a \f[CR]file:\f[R]
|
|
URIs with these, one could exfiltrate local files.
|
|
In addition, using \f[CR]\-\-pdf\-engine=wkhtmltopdf\f[R] with
|
|
\f[CR]\-f html+raw_html\f[R] enables an SSRF vulnerability in
|
|
wkhtmltopdf (CVE\-2022\-35583).
|
|
Note that [\f[CR]wkhtmltopdf\f[R]) is deprecated and its authors
|
|
recommend not to use it with any untrusted input.
|
|
However, there may be similar issues with other pdf\-engines.
|
|
Anyone including a pdf\-engine in a pandoc command run on untrusted
|
|
input should audit the engine carefully and carefully control the use of
|
|
\f[CR]\-\-pdf\-engine\-opt\f[R].
|
|
.PP
|
|
Here are some alternatives for safe use of pandoc in a web application:
|
|
.IP \(bu 2
|
|
Use \f[CR]pandoc server\f[R] to spin up a local web server, and have
|
|
your application make requests to it.
|
|
The server runs in sandboxed mode and will not be able to read files or
|
|
use filters.
|
|
.IP \(bu 2
|
|
Use the WASM version of pandoc.
|
|
This allows the use of Lua filters, but everything runs in an isolated
|
|
WASM sandbox.
|
|
.IP \(bu 2
|
|
Use \f[CR]pandoc \-\-sandbox\f[R].
|
|
However, be aware that the sandbox function only affects readers and
|
|
writers, and security issues can arise if you use it together with
|
|
\f[CR]\-\-filter\f[R] or \f[CR]\-\-pdf\-engine\f[R].
|
|
.RE
|
|
.IP "3." 3
|
|
The HTML generated by pandoc is not guaranteed to be safe.
|
|
If \f[CR]raw_html\f[R] is enabled for the Markdown input, users can
|
|
inject arbitrary HTML.
|
|
Even if \f[CR]raw_html\f[R] is disabled, users can include dangerous
|
|
content in URLs and attributes.
|
|
To be safe, you should run all HTML generated from untrusted user input
|
|
through an HTML sanitizer.
|
|
.IP "4." 3
|
|
Pandoc\(cqs parsers can exhibit pathological performance on some corner
|
|
cases.
|
|
It is wise to put any pandoc operations under a timeout, to avoid DOS
|
|
attacks that exploit these issues.
|
|
If you are using the pandoc executable, you can add the command line
|
|
options \f[CR]+RTS \-M512M \-RTS\f[R] (for example) to limit the heap
|
|
size to 512MB.
|
|
Note that the \f[CR]commonmark\f[R] parser (including
|
|
\f[CR]commonmark_x\f[R] and \f[CR]gfm\f[R]) is much less vulnerable to
|
|
pathological performance than the \f[CR]markdown\f[R] parser, so it is a
|
|
better choice when processing untrusted input.
|
|
.IP "5." 3
|
|
If your application uses pandoc as a Haskell library (rather than
|
|
shelling out to the executable), it is possible to use it in a mode that
|
|
fully isolates pandoc from your file system, by running the pandoc
|
|
operations in the \f[CR]PandocPure\f[R] monad.
|
|
See the document Using the pandoc API for more details.
|
|
(This corresponds to the use of the \f[CR]\-\-sandbox\f[R] option on the
|
|
command line.)
|
|
.SH AUTHORS
|
|
Copyright 2006\(en2024 John MacFarlane (jgm\(atberkeley.edu).
|
|
Released under the GPL, version 2 or greater.
|
|
This software carries no warranty of any kind.
|
|
(See COPYRIGHT for full copyright and warranty notices.)
|
|
For a full list of contributors, see the file AUTHORS.md in the pandoc
|
|
source code.
|
|
.PP
|
|
The Pandoc source code may be downloaded
|
|
from <https://hackage.haskell.org/package/pandoc> or
|
|
<https://github.com/jgm/pandoc/releases>. Further
|
|
documentation is available at <https://pandoc.org>.
|