6112 lines
173 KiB
Groff
6112 lines
173 KiB
Groff
.\"t
|
|
.TH PANDOC 1 "September 16, 2018" "pandoc 2.3"
|
|
.SH NAME
|
|
pandoc - general markup converter
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[C]pandoc\f[] [\f[I]options\f[]] [\f[I]input\-file\f[]]...
|
|
.SH DESCRIPTION
|
|
.PP
|
|
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[C]\-\-from\f[] and \f[C]\-\-to\f[] options below.
|
|
Pandoc can also produce PDF output: see creating a PDF, below.
|
|
.PP
|
|
Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
|
|
definition lists, metadata blocks, footnotes, citations, math, and much
|
|
more.
|
|
See below under Pandoc\[aq]s 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[] 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\[aq]s 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\[aq]s simple document model.
|
|
While conversions from pandoc\[aq]s Markdown to all formats aspire to be
|
|
perfect, conversions from formats more expressive than pandoc\[aq]s
|
|
Markdown can be expected to be lossy.
|
|
.SS Using \f[C]pandoc\f[]
|
|
.PP
|
|
If no \f[I]input\-files\f[] are specified, input is read from
|
|
\f[I]stdin\f[].
|
|
Output goes to \f[I]stdout\f[] by default.
|
|
For output to a file, use the \f[C]\-o\f[] option:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-o\ output.html\ input.txt
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
By default, pandoc produces a document fragment.
|
|
To produce a standalone document (e.g.
|
|
a valid HTML file including \f[C]<head>\f[] and \f[C]<body>\f[]), use
|
|
the \f[C]\-s\f[] or \f[C]\-\-standalone\f[] flag:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-s\ \-o\ output.html\ input.txt
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
For more information on how standalone documents are produced, see
|
|
Templates below.
|
|
.PP
|
|
If multiple input files are given, \f[C]pandoc\f[] will concatenate them
|
|
all (with blank lines between them) before parsing.
|
|
(Use \f[C]\-\-file\-scope\f[] to parse files individually.)
|
|
.SS Specifying formats
|
|
.PP
|
|
The format of the input and output can be specified explicitly using
|
|
command\-line options.
|
|
The input format can be specified using the \f[C]\-f/\-\-from\f[]
|
|
option, the output format using the \f[C]\-t/\-\-to\f[] option.
|
|
Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could
|
|
type:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-f\ markdown\ \-t\ latex\ hello.txt
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
To convert \f[C]hello.html\f[] from HTML to Markdown:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-f\ html\ \-t\ markdown\ hello.html
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Supported input and output formats are listed below under Options (see
|
|
\f[C]\-f\f[] for input formats and \f[C]\-t\f[] for output formats).
|
|
You can also use \f[C]pandoc\ \-\-list\-input\-formats\f[] and
|
|
\f[C]pandoc\ \-\-list\-output\-formats\f[] to print lists of supported
|
|
formats.
|
|
.PP
|
|
If the input or output format is not specified explicitly,
|
|
\f[C]pandoc\f[] will attempt to guess it from the extensions of the
|
|
filenames.
|
|
Thus, for example,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-o\ hello.tex\ hello.txt
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
will convert \f[C]hello.txt\f[] from Markdown to LaTeX.
|
|
If no output file is specified (so that output goes to \f[I]stdout\f[]),
|
|
or if the output file\[aq]s 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[]),
|
|
or if the input files\[aq] extensions are unknown, the input format will
|
|
be assumed to be Markdown.
|
|
.SS Character encoding
|
|
.PP
|
|
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[C]iconv\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
iconv\ \-t\ utf\-8\ input.txt\ |\ pandoc\ |\ iconv\ \-f\ utf\-8
|
|
\f[]
|
|
.fi
|
|
.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[C]\-s/\-\-standalone\f[] option.
|
|
.SS Creating a PDF
|
|
.PP
|
|
To produce a PDF, specify an output file with a \f[C]\&.pdf\f[]
|
|
extension:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ test.txt\ \-o\ test.pdf
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
By default, pandoc will use LaTeX to create the PDF, which requires that
|
|
a LaTeX engine be installed (see \f[C]\-\-pdf\-engine\f[] below).
|
|
.PP
|
|
Alternatively, pandoc can use ConTeXt, \f[C]pdfroff\f[], or any of the
|
|
following HTML/CSS\-to\-PDF\-engines, to create a PDF:
|
|
\f[C]wkhtmltopdf\f[], \f[C]weasyprint\f[] or \f[C]prince\f[].
|
|
To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as
|
|
before, but add the \f[C]\-\-pdf\-engine\f[] option or
|
|
\f[C]\-t\ context\f[], \f[C]\-t\ html\f[], or \f[C]\-t\ ms\f[] to the
|
|
command line (\f[C]\-t\ html\f[] defaults to
|
|
\f[C]\-\-pdf\-engine=wkhtmltopdf\f[]).
|
|
.PP
|
|
PDF output can be controlled using variables for LaTeX (if LaTeX is
|
|
used) and variables for ConTeXt (if ConTeXt is used).
|
|
When using an HTML/CSS\-to\-PDF\-engine, \f[C]\-\-css\f[] affects the
|
|
output.
|
|
If \f[C]wkhtmltopdf\f[] is used, then the variables
|
|
\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[],
|
|
\f[C]margin\-bottom\f[], \f[C]footer\-html\f[], \f[C]header\-html\f[]
|
|
and \f[C]papersize\f[] will affect the output.
|
|
.PP
|
|
To debug the PDF creation, it can be useful to look at the intermediate
|
|
representation: instead of \f[C]\-o\ test.pdf\f[], use for example
|
|
\f[C]\-s\ \-o\ test.tex\f[] to output the generated LaTeX.
|
|
You can then test it with \f[C]pdflatex\ test.tex\f[].
|
|
.PP
|
|
When using LaTeX, the following packages need to be available (they are
|
|
included with all recent versions of TeX Live): \f[C]amsfonts\f[],
|
|
\f[C]amsmath\f[], \f[C]lm\f[], \f[C]unicode\-math\f[], \f[C]ifxetex\f[],
|
|
\f[C]ifluatex\f[], \f[C]listings\f[] (if the \f[C]\-\-listings\f[]
|
|
option is used), \f[C]fancyvrb\f[], \f[C]longtable\f[],
|
|
\f[C]booktabs\f[], \f[C]graphicx\f[] and \f[C]grffile\f[] (if the
|
|
document contains images), \f[C]hyperref\f[], \f[C]xcolor\f[] (with
|
|
\f[C]colorlinks\f[]), \f[C]ulem\f[], \f[C]geometry\f[] (with the
|
|
\f[C]geometry\f[] variable set), \f[C]setspace\f[] (with
|
|
\f[C]linestretch\f[]), and \f[C]babel\f[] (with \f[C]lang\f[]).
|
|
The use of \f[C]xelatex\f[] or \f[C]lualatex\f[] as the LaTeX engine
|
|
requires \f[C]fontspec\f[].
|
|
\f[C]xelatex\f[] uses \f[C]polyglossia\f[] (with \f[C]lang\f[]),
|
|
\f[C]xecjk\f[], and \f[C]bidi\f[] (with the \f[C]dir\f[] variable set).
|
|
If the \f[C]mathspec\f[] variable is set, \f[C]xelatex\f[] will use
|
|
\f[C]mathspec\f[] instead of \f[C]unicode\-math\f[].
|
|
The \f[C]upquote\f[] and \f[C]microtype\f[] packages are used if
|
|
available, and \f[C]csquotes\f[] will be used for typography if
|
|
\f[C]\\usepackage{csquotes}\f[] is present in the template or included
|
|
via \f[C]/H/\-\-include\-in\-header\f[].
|
|
The \f[C]natbib\f[], \f[C]biblatex\f[], \f[C]bibtex\f[], and
|
|
\f[C]biber\f[] packages can optionally be used for citation rendering.
|
|
.SS Reading from the Web
|
|
.PP
|
|
Instead of an input file, an absolute URI may be given.
|
|
In this case pandoc will fetch the content using HTTP:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
It is possible to supply a custom User\-Agent string or other header
|
|
when requesting a document from a URL:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-f\ html\ \-t\ markdown\ \-\-request\-header\ User\-Agent:"Mozilla/5.0"\ \\
|
|
\ \ http://www.fsf.org
|
|
\f[]
|
|
.fi
|
|
.SH OPTIONS
|
|
.SS General options
|
|
.TP
|
|
.B \f[C]\-f\f[] \f[I]FORMAT\f[], \f[C]\-r\f[] \f[I]FORMAT\f[], \f[C]\-\-from=\f[]\f[I]FORMAT\f[], \f[C]\-\-read=\f[]\f[I]FORMAT\f[]
|
|
Specify input format.
|
|
\f[I]FORMAT\f[] can be:
|
|
.RS
|
|
.IP \[bu] 2
|
|
\f[C]commonmark\f[] (CommonMark Markdown)
|
|
.IP \[bu] 2
|
|
\f[C]creole\f[] (Creole 1.0)
|
|
.IP \[bu] 2
|
|
\f[C]docbook\f[] (DocBook)
|
|
.IP \[bu] 2
|
|
\f[C]docx\f[] (Word docx)
|
|
.IP \[bu] 2
|
|
\f[C]epub\f[] (EPUB)
|
|
.IP \[bu] 2
|
|
\f[C]fb2\f[] (FictionBook2 e\-book)
|
|
.IP \[bu] 2
|
|
\f[C]gfm\f[] (GitHub\-Flavored Markdown), or the deprecated and less
|
|
accurate \f[C]markdown_github\f[]; use \f[C]markdown_github\f[] only if
|
|
you need extensions not supported in \f[C]gfm\f[].
|
|
.IP \[bu] 2
|
|
\f[C]haddock\f[] (Haddock markup)
|
|
.IP \[bu] 2
|
|
\f[C]html\f[] (HTML)
|
|
.IP \[bu] 2
|
|
\f[C]jats\f[] (JATS XML)
|
|
.IP \[bu] 2
|
|
\f[C]json\f[] (JSON version of native AST)
|
|
.IP \[bu] 2
|
|
\f[C]latex\f[] (LaTeX)
|
|
.IP \[bu] 2
|
|
\f[C]markdown\f[] (Pandoc\[aq]s Markdown)
|
|
.IP \[bu] 2
|
|
\f[C]markdown_mmd\f[] (MultiMarkdown)
|
|
.IP \[bu] 2
|
|
\f[C]markdown_phpextra\f[] (PHP Markdown Extra)
|
|
.IP \[bu] 2
|
|
\f[C]markdown_strict\f[] (original unextended Markdown)
|
|
.IP \[bu] 2
|
|
\f[C]mediawiki\f[] (MediaWiki markup)
|
|
.IP \[bu] 2
|
|
\f[C]muse\f[] (Muse)
|
|
.IP \[bu] 2
|
|
\f[C]native\f[] (native Haskell)
|
|
.IP \[bu] 2
|
|
\f[C]odt\f[] (ODT)
|
|
.IP \[bu] 2
|
|
\f[C]opml\f[] (OPML)
|
|
.IP \[bu] 2
|
|
\f[C]org\f[] (Emacs Org mode)
|
|
.IP \[bu] 2
|
|
\f[C]rst\f[] (reStructuredText)
|
|
.IP \[bu] 2
|
|
\f[C]t2t\f[] (txt2tags)
|
|
.IP \[bu] 2
|
|
\f[C]textile\f[] (Textile)
|
|
.IP \[bu] 2
|
|
\f[C]tikiwiki\f[] (TikiWiki markup)
|
|
.IP \[bu] 2
|
|
\f[C]twiki\f[] (TWiki markup)
|
|
.IP \[bu] 2
|
|
\f[C]vimwiki\f[] (Vimwiki)
|
|
.PP
|
|
Extensions can be individually enabled or disabled by appending
|
|
\f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format name.
|
|
See Extensions below, for a list of extensions and their names.
|
|
See \f[C]\-\-list\-input\-formats\f[] and \f[C]\-\-list\-extensions\f[],
|
|
below.
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-t\f[] \f[I]FORMAT\f[], \f[C]\-w\f[] \f[I]FORMAT\f[], \f[C]\-\-to=\f[]\f[I]FORMAT\f[], \f[C]\-\-write=\f[]\f[I]FORMAT\f[]
|
|
Specify output format.
|
|
\f[I]FORMAT\f[] can be:
|
|
.RS
|
|
.IP \[bu] 2
|
|
\f[C]asciidoc\f[] (AsciiDoc)
|
|
.IP \[bu] 2
|
|
\f[C]beamer\f[] (LaTeX beamer slide show)
|
|
.IP \[bu] 2
|
|
\f[C]commonmark\f[] (CommonMark Markdown)
|
|
.IP \[bu] 2
|
|
\f[C]context\f[] (ConTeXt)
|
|
.IP \[bu] 2
|
|
\f[C]docbook\f[] or \f[C]docbook4\f[] (DocBook 4)
|
|
.IP \[bu] 2
|
|
\f[C]docbook5\f[] (DocBook 5)
|
|
.IP \[bu] 2
|
|
\f[C]docx\f[] (Word docx)
|
|
.IP \[bu] 2
|
|
\f[C]dokuwiki\f[] (DokuWiki markup)
|
|
.IP \[bu] 2
|
|
\f[C]epub\f[] or \f[C]epub3\f[] (EPUB v3 book)
|
|
.IP \[bu] 2
|
|
\f[C]epub2\f[] (EPUB v2)
|
|
.IP \[bu] 2
|
|
\f[C]fb2\f[] (FictionBook2 e\-book)
|
|
.IP \[bu] 2
|
|
\f[C]gfm\f[] (GitHub\-Flavored Markdown), or the deprecated and less
|
|
accurate \f[C]markdown_github\f[]; use \f[C]markdown_github\f[] only if
|
|
you need extensions not supported in \f[C]gfm\f[].
|
|
.IP \[bu] 2
|
|
\f[C]haddock\f[] (Haddock markup)
|
|
.IP \[bu] 2
|
|
\f[C]html\f[] or \f[C]html5\f[] (HTML, i.e.
|
|
HTML5/XHTML polyglot markup)
|
|
.IP \[bu] 2
|
|
\f[C]html4\f[] (XHTML 1.0 Transitional)
|
|
.IP \[bu] 2
|
|
\f[C]icml\f[] (InDesign ICML)
|
|
.IP \[bu] 2
|
|
\f[C]jats\f[] (JATS XML)
|
|
.IP \[bu] 2
|
|
\f[C]json\f[] (JSON version of native AST)
|
|
.IP \[bu] 2
|
|
\f[C]latex\f[] (LaTeX)
|
|
.IP \[bu] 2
|
|
\f[C]man\f[] (groff man)
|
|
.IP \[bu] 2
|
|
\f[C]markdown\f[] (Pandoc\[aq]s Markdown)
|
|
.IP \[bu] 2
|
|
\f[C]markdown_mmd\f[] (MultiMarkdown)
|
|
.IP \[bu] 2
|
|
\f[C]markdown_phpextra\f[] (PHP Markdown Extra)
|
|
.IP \[bu] 2
|
|
\f[C]markdown_strict\f[] (original unextended Markdown)
|
|
.IP \[bu] 2
|
|
\f[C]mediawiki\f[] (MediaWiki markup)
|
|
.IP \[bu] 2
|
|
\f[C]ms\f[] (groff ms)
|
|
.IP \[bu] 2
|
|
\f[C]muse\f[] (Muse),
|
|
.IP \[bu] 2
|
|
\f[C]native\f[] (native Haskell),
|
|
.IP \[bu] 2
|
|
\f[C]odt\f[] (OpenOffice text document)
|
|
.IP \[bu] 2
|
|
\f[C]opml\f[] (OPML)
|
|
.IP \[bu] 2
|
|
\f[C]opendocument\f[] (OpenDocument)
|
|
.IP \[bu] 2
|
|
\f[C]org\f[] (Emacs Org mode)
|
|
.IP \[bu] 2
|
|
\f[C]plain\f[] (plain text),
|
|
.IP \[bu] 2
|
|
\f[C]pptx\f[] (PowerPoint slide show)
|
|
.IP \[bu] 2
|
|
\f[C]rst\f[] (reStructuredText)
|
|
.IP \[bu] 2
|
|
\f[C]rtf\f[] (Rich Text Format)
|
|
.IP \[bu] 2
|
|
\f[C]texinfo\f[] (GNU Texinfo)
|
|
.IP \[bu] 2
|
|
\f[C]textile\f[] (Textile)
|
|
.IP \[bu] 2
|
|
\f[C]slideous\f[] (Slideous HTML and JavaScript slide show)
|
|
.IP \[bu] 2
|
|
\f[C]slidy\f[] (Slidy HTML and JavaScript slide show)
|
|
.IP \[bu] 2
|
|
\f[C]dzslides\f[] (DZSlides HTML5 + JavaScript slide show),
|
|
.IP \[bu] 2
|
|
\f[C]revealjs\f[] (reveal.js HTML5 + JavaScript slide show)
|
|
.IP \[bu] 2
|
|
\f[C]s5\f[] (S5 HTML and JavaScript slide show)
|
|
.IP \[bu] 2
|
|
\f[C]tei\f[] (TEI Simple)
|
|
.IP \[bu] 2
|
|
\f[C]zimwiki\f[] (ZimWiki markup)
|
|
.IP \[bu] 2
|
|
the path of a custom lua writer, see Custom writers below
|
|
.PP
|
|
Note that \f[C]odt\f[], \f[C]docx\f[], and \f[C]epub\f[] output will not
|
|
be directed to \f[I]stdout\f[] unless forced with \f[C]\-o\ \-\f[].
|
|
.PP
|
|
Extensions can be individually enabled or disabled by appending
|
|
\f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format name.
|
|
See Extensions below, for a list of extensions and their names.
|
|
See \f[C]\-\-list\-output\-formats\f[] and
|
|
\f[C]\-\-list\-extensions\f[], below.
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-o\f[] \f[I]FILE\f[], \f[C]\-\-output=\f[]\f[I]FILE\f[]
|
|
Write output to \f[I]FILE\f[] instead of \f[I]stdout\f[].
|
|
If \f[I]FILE\f[] is \f[C]\-\f[], output will go to \f[I]stdout\f[], even
|
|
if a non\-textual format (\f[C]docx\f[], \f[C]odt\f[], \f[C]epub2\f[],
|
|
\f[C]epub3\f[]) is specified.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-data\-dir=\f[]\f[I]DIRECTORY\f[]
|
|
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.
|
|
This is, in UNIX:
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$HOME/.pandoc
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
in Windows XP:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\pandoc
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
and in Windows Vista or later:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
C:\\Users\\USERNAME\\AppData\\Roaming\\pandoc
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
You can find the default user data directory on your system by looking
|
|
at the output of \f[C]pandoc\ \-\-version\f[].
|
|
A \f[C]reference.odt\f[], \f[C]reference.docx\f[], \f[C]epub.css\f[],
|
|
\f[C]templates\f[], \f[C]slidy\f[], \f[C]slideous\f[], or \f[C]s5\f[]
|
|
directory placed in this directory will override pandoc\[aq]s normal
|
|
defaults.
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-bash\-completion\f[]
|
|
Generate a bash completion script.
|
|
To enable bash completion with pandoc, add this to your
|
|
\f[C]\&.bashrc\f[]:
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
eval\ "$(pandoc\ \-\-bash\-completion)"
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-verbose\f[]
|
|
Give verbose debugging output.
|
|
Currently this only has an effect with PDF output.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-quiet\f[]
|
|
Suppress warning messages.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-fail\-if\-warnings\f[]
|
|
Exit with error status if there are any warnings.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-log=\f[]\f[I]FILE\f[]
|
|
Write log messages in machine\-readable JSON format to \f[I]FILE\f[].
|
|
All messages above DEBUG level will be written, regardless of verbosity
|
|
settings (\f[C]\-\-verbose\f[], \f[C]\-\-quiet\f[]).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-list\-input\-formats\f[]
|
|
List supported input formats, one per line.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-list\-output\-formats\f[]
|
|
List supported output formats, one per line.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-list\-extensions\f[][\f[C]=\f[]\f[I]FORMAT\f[]]
|
|
List supported extensions, one per line, preceded by a \f[C]+\f[] or
|
|
\f[C]\-\f[] indicating whether it is enabled by default in
|
|
\f[I]FORMAT\f[].
|
|
If \f[I]FORMAT\f[] is not specified, defaults for pandoc\[aq]s Markdown
|
|
are given.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-list\-highlight\-languages\f[]
|
|
List supported languages for syntax highlighting, one per line.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-list\-highlight\-styles\f[]
|
|
List supported styles for syntax highlighting, one per line.
|
|
See \f[C]\-\-highlight\-style\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-v\f[], \f[C]\-\-version\f[]
|
|
Print version.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-h\f[], \f[C]\-\-help\f[]
|
|
Show usage message.
|
|
.RS
|
|
.RE
|
|
.SS Reader options
|
|
.TP
|
|
.B \f[C]\-\-base\-header\-level=\f[]\f[I]NUMBER\f[]
|
|
Specify the base level for headers (defaults to 1).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-strip\-empty\-paragraphs\f[]
|
|
\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension
|
|
instead.\f[] Ignore paragraphs with no content.
|
|
This option is useful for converting word processing documents where
|
|
users have used empty paragraphs to create inter\-paragraph space.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-indented\-code\-classes=\f[]\f[I]CLASSES\f[]
|
|
Specify classes to use for indented code blocks\-\-for example,
|
|
\f[C]perl,numberLines\f[] or \f[C]haskell\f[].
|
|
Multiple classes may be separated by spaces or commas.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-default\-image\-extension=\f[]\f[I]EXTENSION\f[]
|
|
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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-file\-scope\f[]
|
|
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[C]\-\-file\-scope\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-F\f[] \f[I]PROGRAM\f[], \f[C]\-\-filter=\f[]\f[I]PROGRAM\f[]
|
|
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\[aq]s own JSON input and output.
|
|
The name of the output format will be passed to the filter as the first
|
|
argument.
|
|
Hence,
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-\-filter\ ./caps.py\ \-t\ latex
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
is equivalent to
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-t\ json\ |\ ./caps.py\ latex\ |\ pandoc\ \-f\ json\ \-t\ latex
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The latter form may be useful for debugging filters.
|
|
.PP
|
|
Filters may be written in any language.
|
|
\f[C]Text.Pandoc.JSON\f[] exports \f[C]toJSONFilter\f[] to facilitate
|
|
writing filters in Haskell.
|
|
Those who would prefer to write filters in python can use the module
|
|
\f[C]pandocfilters\f[], 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[C]$DATADIR/filters\f[] (executable or non\-executable) where
|
|
\f[C]$DATADIR\f[] is the user data directory (see
|
|
\f[C]\-\-data\-dir\f[], above).
|
|
.IP "3." 3
|
|
\f[C]$PATH\f[] (executable only)
|
|
.PP
|
|
Filters and lua\-filters are applied in the order specified on the
|
|
command line.
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-lua\-filter=\f[]\f[I]SCRIPT\f[]
|
|
Transform the document in a similar fashion as JSON filters (see
|
|
\f[C]\-\-filter\f[]), but use pandoc\[aq]s build\-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[C]pandoc\f[] lua module provides helper functions for element
|
|
creation.
|
|
It is always loaded into the script\[aq]s lua environment.
|
|
.PP
|
|
The following is an example lua script for macro\-expansion:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
function\ expand_hello_world(inline)
|
|
\ \ if\ inline.c\ ==\ \[aq]{{helloworld}}\[aq]\ then
|
|
\ \ \ \ return\ pandoc.Emph{\ pandoc.Str\ "Hello,\ World"\ }
|
|
\ \ else
|
|
\ \ \ \ return\ inline
|
|
\ \ end
|
|
end
|
|
|
|
return\ {{Str\ =\ expand_hello_world}}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
In order of preference, pandoc will look for lua filters in
|
|
.IP "1." 3
|
|
a specified full or relative path (executable or non\-executable)
|
|
.IP "2." 3
|
|
\f[C]$DATADIR/filters\f[] (executable or non\-executable) where
|
|
\f[C]$DATADIR\f[] is the user data directory (see
|
|
\f[C]\-\-data\-dir\f[], above).
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-M\f[] \f[I]KEY\f[][\f[C]=\f[]\f[I]VAL\f[]], \f[C]\-\-metadata=\f[]\f[I]KEY\f[][\f[C]:\f[]\f[I]VAL\f[]]
|
|
Set the metadata field \f[I]KEY\f[] to the value \f[I]VAL\f[].
|
|
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[C]\-\-variable\f[], \f[C]\-\-metadata\f[] causes template
|
|
variables to be set.
|
|
But unlike \f[C]\-\-variable\f[], \f[C]\-\-metadata\f[] 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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-metadata\-file=\f[]\f[I]FILE\f[]
|
|
Read metadata from the supplied YAML (or JSON) file.
|
|
This option can be used with every input format, but string scalars in
|
|
the YAML file will always be parsed as Markdown.
|
|
Generally, the input will be handled the same as in YAML metadata
|
|
blocks.
|
|
Metadata values specified inside the document, or by using \f[C]\-M\f[],
|
|
overwrite values specified with this option.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-p\f[], \f[C]\-\-preserve\-tabs\f[]
|
|
Preserve tabs instead of converting them to spaces (the default).
|
|
Note that this will only affect tabs in literal code spans and code
|
|
blocks; tabs in regular text will be treated as spaces.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-tab\-stop=\f[]\f[I]NUMBER\f[]
|
|
Specify the number of spaces per tab (default is 4).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-track\-changes=accept\f[]|\f[C]reject\f[]|\f[C]all\f[]
|
|
Specifies what to do with insertions, deletions, and comments produced
|
|
by the MS Word "Track Changes" feature.
|
|
\f[C]accept\f[] (the default), inserts all insertions, and ignores all
|
|
deletions.
|
|
\f[C]reject\f[] inserts all deletions and ignores insertions.
|
|
Both \f[C]accept\f[] and \f[C]reject\f[] ignore comments.
|
|
\f[C]all\f[] puts in insertions, deletions, and comments, wrapped in
|
|
spans with \f[C]insertion\f[], \f[C]deletion\f[],
|
|
\f[C]comment\-start\f[], and \f[C]comment\-end\f[] classes,
|
|
respectively.
|
|
The author and time of change is included.
|
|
\f[C]all\f[] 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[C]track\-changes=all\f[]
|
|
produces a span with the class
|
|
\f[C]paragraph\-insertion\f[]/\f[C]paragraph\-deletion\f[] before the
|
|
affected paragraph break.
|
|
This option only affects the docx reader.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-extract\-media=\f[]\f[I]DIR\f[]
|
|
Extract images and other media contained in or linked from the source
|
|
document to the path \f[I]DIR\f[], creating it if necessary, and adjust
|
|
the images references in the document so they point to the extracted
|
|
files.
|
|
If the source format is a binary container (docx, epub, or odt), the
|
|
media is extracted from the container and the original filenames are
|
|
used.
|
|
Otherwise the media is read from the file system or downloaded, and new
|
|
filenames are constructed based on SHA1 hashes of the contents.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-abbreviations=\f[]\f[I]FILE\f[]
|
|
Specifies a custom abbreviations file, with abbreviations one to a line.
|
|
If this option is not specified, pandoc will read the data file
|
|
\f[C]abbreviations\f[] from the user data directory or fall back on a
|
|
system default.
|
|
To see the system default, use
|
|
\f[C]pandoc\ \-\-print\-default\-data\-file=abbreviations\f[].
|
|
The only use pandoc makes of this list is in the Markdown reader.
|
|
Strings ending in a period that are found in this list will be followed
|
|
by a nonbreaking space, so that the period will not produce
|
|
sentence\-ending space in formats like LaTeX.
|
|
.RS
|
|
.RE
|
|
.SS General writer options
|
|
.TP
|
|
.B \f[C]\-s\f[], \f[C]\-\-standalone\f[]
|
|
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[C]pdf\f[], \f[C]epub\f[],
|
|
\f[C]epub3\f[], \f[C]fb2\f[], \f[C]docx\f[], and \f[C]odt\f[] output.
|
|
For \f[C]native\f[] output, this option causes metadata to be included;
|
|
otherwise, metadata is suppressed.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-template=\f[]\f[I]FILE\f[]|\f[I]URL\f[]
|
|
Use the specified file as a custom template for the generated document.
|
|
Implies \f[C]\-\-standalone\f[].
|
|
See Templates, below, for a description of template syntax.
|
|
If no extension is specified, an extension corresponding to the writer
|
|
will be added, so that \f[C]\-\-template=special\f[] looks for
|
|
\f[C]special.html\f[] for HTML output.
|
|
If the template is not found, pandoc will search for it in the
|
|
\f[C]templates\f[] subdirectory of the user data directory (see
|
|
\f[C]\-\-data\-dir\f[]).
|
|
If this option is not used, a default template appropriate for the
|
|
output format will be used (see
|
|
\f[C]\-D/\-\-print\-default\-template\f[]).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-V\f[] \f[I]KEY\f[][\f[C]=\f[]\f[I]VAL\f[]], \f[C]\-\-variable=\f[]\f[I]KEY\f[][\f[C]:\f[]\f[I]VAL\f[]]
|
|
Set the template variable \f[I]KEY\f[] to the value \f[I]VAL\f[] when
|
|
rendering the document in standalone mode.
|
|
This is generally only useful when the \f[C]\-\-template\f[] option is
|
|
used to specify a custom template, since pandoc automatically sets the
|
|
variables used in the default templates.
|
|
If no \f[I]VAL\f[] is specified, the key will be given the value
|
|
\f[C]true\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-D\f[] \f[I]FORMAT\f[], \f[C]\-\-print\-default\-template=\f[]\f[I]FORMAT\f[]
|
|
Print the system default template for an output \f[I]FORMAT\f[].
|
|
(See \f[C]\-t\f[] for a list of possible \f[I]FORMAT\f[]s.) Templates in
|
|
the user data directory are ignored.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-print\-default\-data\-file=\f[]\f[I]FILE\f[]
|
|
Print a system default data file.
|
|
Files in the user data directory are ignored.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-eol=crlf\f[]|\f[C]lf\f[]|\f[C]native\f[]
|
|
Manually specify line endings: \f[C]crlf\f[] (Windows), \f[C]lf\f[]
|
|
(macOS/Linux/UNIX), or \f[C]native\f[] (line endings appropriate to the
|
|
OS on which pandoc is being run).
|
|
The default is \f[C]native\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-dpi\f[]=\f[I]NUMBER\f[]
|
|
Specify the dpi (dots per inch) value for conversion from pixels to
|
|
inch/centimeters and vice versa.
|
|
The default is 96dpi.
|
|
Technically, the correct term would be ppi (pixels per inch).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-wrap=auto\f[]|\f[C]none\f[]|\f[C]preserve\f[]
|
|
Determine how text is wrapped in the output (the source code, not the
|
|
rendered version).
|
|
With \f[C]auto\f[] (the default), pandoc will attempt to wrap lines to
|
|
the column width specified by \f[C]\-\-columns\f[] (default 72).
|
|
With \f[C]none\f[], pandoc will not wrap lines at all.
|
|
With \f[C]preserve\f[], 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).
|
|
Automatic wrapping does not currently work in HTML output.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-columns=\f[]\f[I]NUMBER\f[]
|
|
Specify length of lines in characters.
|
|
This affects text wrapping in the generated source code (see
|
|
\f[C]\-\-wrap\f[]).
|
|
It also affects calculation of column widths for plain text tables (see
|
|
Tables below).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-toc\f[], \f[C]\-\-table\-of\-contents\f[]
|
|
Include an automatically generated table of contents (or, in the case of
|
|
\f[C]latex\f[], \f[C]context\f[], \f[C]docx\f[], \f[C]odt\f[],
|
|
\f[C]opendocument\f[], \f[C]rst\f[], or \f[C]ms\f[], an instruction to
|
|
create one) in the output document.
|
|
This option has no effect unless \f[C]\-s/\-\-standalone\f[] is used,
|
|
and it has no effect on \f[C]man\f[], \f[C]docbook4\f[],
|
|
\f[C]docbook5\f[], or \f[C]jats\f[] output.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-toc\-depth=\f[]\f[I]NUMBER\f[]
|
|
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 headers will be
|
|
listed in the contents).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-strip\-comments\f[]
|
|
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[C]markdown_in_html_blocks\f[] extension is not set.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-no\-highlight\f[]
|
|
Disables syntax highlighting for code blocks and inlines, even when a
|
|
language attribute is given.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-highlight\-style=\f[]\f[I]STYLE\f[]|\f[I]FILE\f[]
|
|
Specifies the coloring style to be used in highlighted source code.
|
|
Options are \f[C]pygments\f[] (the default), \f[C]kate\f[],
|
|
\f[C]monochrome\f[], \f[C]breezeDark\f[], \f[C]espresso\f[],
|
|
\f[C]zenburn\f[], \f[C]haddock\f[], and \f[C]tango\f[].
|
|
For more information on syntax highlighting in pandoc, see Syntax
|
|
highlighting, below.
|
|
See also \f[C]\-\-list\-highlight\-styles\f[].
|
|
.RS
|
|
.PP
|
|
Instead of a \f[I]STYLE\f[] name, a JSON file with extension
|
|
\f[C]\&.theme\f[] 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[C]\-\-print\-highlight\-style\f[].
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-print\-highlight\-style=\f[]\f[I]STYLE\f[]|\f[I]FILE\f[]
|
|
Prints a JSON version of a highlighting style, which can be modified,
|
|
saved with a \f[C]\&.theme\f[] extension, and used with
|
|
\f[C]\-\-highlight\-style\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-syntax\-definition=\f[]\f[I]FILE\f[]
|
|
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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-H\f[] \f[I]FILE\f[], \f[C]\-\-include\-in\-header=\f[]\f[I]FILE\f[]
|
|
Include contents of \f[I]FILE\f[], 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[C]\-\-standalone\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-B\f[] \f[I]FILE\f[], \f[C]\-\-include\-before\-body=\f[]\f[I]FILE\f[]
|
|
Include contents of \f[I]FILE\f[], verbatim, at the beginning of the
|
|
document body (e.g.
|
|
after the \f[C]<body>\f[] tag in HTML, or the \f[C]\\begin{document}\f[]
|
|
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[C]\-\-standalone\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-A\f[] \f[I]FILE\f[], \f[C]\-\-include\-after\-body=\f[]\f[I]FILE\f[]
|
|
Include contents of \f[I]FILE\f[], verbatim, at the end of the document
|
|
body (before the \f[C]</body>\f[] tag in HTML, or the
|
|
\f[C]\\end{document}\f[] command in LaTeX).
|
|
This option can be used repeatedly to include multiple files.
|
|
They will be included in the order specified.
|
|
Implies \f[C]\-\-standalone\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-resource\-path=\f[]\f[I]SEARCHPATH\f[]
|
|
List of paths to search for images and other resources.
|
|
The paths should be separated by \f[C]:\f[] on Linux, UNIX, and macOS
|
|
systems, and by \f[C];\f[] on Windows.
|
|
If \f[C]\-\-resource\-path\f[] is not specified, the default resource
|
|
path is the working directory.
|
|
Note that, if \f[C]\-\-resource\-path\f[] is specified, the working
|
|
directory must be explicitly listed or it will not be searched.
|
|
For example: \f[C]\-\-resource\-path=.:test\f[] will search the working
|
|
directory and the \f[C]test\f[] subdirectory, in that order.
|
|
.RS
|
|
.PP
|
|
\f[C]\-\-resource\-path\f[] only has an effect if (a) the output format
|
|
embeds images (for example, \f[C]docx\f[], \f[C]pdf\f[], or
|
|
\f[C]html\f[] with \f[C]\-\-self\-contained\f[]) or (b) it is used
|
|
together with \f[C]\-\-extract\-media\f[].
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-request\-header=\f[]\f[I]NAME\f[]\f[C]:\f[]\f[I]VAL\f[]
|
|
Set the request header \f[I]NAME\f[] to the value \f[I]VAL\f[] 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\[aq]re behind a proxy, you also need to set the environment
|
|
variable \f[C]http_proxy\f[] to \f[C]http://...\f[].
|
|
.RS
|
|
.RE
|
|
.SS Options affecting specific writers
|
|
.TP
|
|
.B \f[C]\-\-self\-contained\f[]
|
|
Produce a standalone HTML file with no external dependencies, using
|
|
\f[C]data:\f[] URIs to incorporate the contents of linked scripts,
|
|
stylesheets, images, and videos.
|
|
Implies \f[C]\-\-standalone\f[].
|
|
The resulting file should be "self\-contained," 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[C]html4\f[], \f[C]html5\f[], \f[C]html+lhs\f[], \f[C]html5+lhs\f[],
|
|
\f[C]s5\f[], \f[C]slidy\f[], \f[C]slideous\f[], \f[C]dzslides\f[], and
|
|
\f[C]revealjs\f[].
|
|
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[C]data\-external="1"\f[] 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, \f[C]\-\-self\-contained\f[] does
|
|
not work with \f[C]\-\-mathjax\f[], and some advanced features (e.g.
|
|
zoom or speaker notes) may not work in an offline "self\-contained"
|
|
\f[C]reveal.js\f[] slide show.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-html\-q\-tags\f[]
|
|
Use \f[C]<q>\f[] tags for quotes in HTML.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-ascii\f[]
|
|
Use only ASCII characters in output.
|
|
Currently supported for XML and HTML formats (which use numerical
|
|
entities instead of UTF\-8 when this option is selected) and for groff
|
|
ms and man (which use hexadecimal escapes).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-reference\-links\f[]
|
|
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[C]\-\-reference\-location\f[] option.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-reference\-location\ =\ block\f[]|\f[C]section\f[]|\f[C]document\f[]
|
|
Specify whether footnotes (and references, if \f[C]reference\-links\f[]
|
|
is set) are placed at the end of the current (top\-level) block, the
|
|
current section, or the document.
|
|
The default is \f[C]document\f[].
|
|
Currently only affects the markdown writer.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-atx\-headers\f[]
|
|
Use ATX\-style headers in Markdown and AsciiDoc output.
|
|
The default is to use setext\-style headers for levels 1\-2, and then
|
|
ATX headers.
|
|
(Note: for \f[C]gfm\f[] output, ATX headers are always used.)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-top\-level\-division=[default|section|chapter|part]\f[]
|
|
Treat top\-level headers as the given division type in LaTeX, ConTeXt,
|
|
DocBook, and TEI output.
|
|
The hierarchy order is part, chapter, then section; all headers are
|
|
shifted such that the top\-level header becomes the specified type.
|
|
The default behavior is to determine the best division type via
|
|
heuristics: unless other conditions apply, \f[C]section\f[] is chosen.
|
|
When the LaTeX document class is set to \f[C]report\f[], \f[C]book\f[],
|
|
or \f[C]memoir\f[] (unless the \f[C]article\f[] option is specified),
|
|
\f[C]chapter\f[] is implied as the setting for this option.
|
|
If \f[C]beamer\f[] is the output format, specifying either
|
|
\f[C]chapter\f[] or \f[C]part\f[] will cause top\-level headers to
|
|
become \f[C]\\part{..}\f[], while second\-level headers remain as their
|
|
default type.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-N\f[], \f[C]\-\-number\-sections\f[]
|
|
Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
|
|
By default, sections are not numbered.
|
|
Sections with class \f[C]unnumbered\f[] will never be numbered, even if
|
|
\f[C]\-\-number\-sections\f[] is specified.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-number\-offset=\f[]\f[I]NUMBER\f[][\f[C],\f[]\f[I]NUMBER\f[]\f[C],\f[]\f[I]...\f[]]
|
|
Offset for section headings in HTML output (ignored in other output
|
|
formats).
|
|
The first number is added to the section number for top\-level headers,
|
|
the second for second\-level headers, and so on.
|
|
So, for example, if you want the first top\-level header in your
|
|
document to be numbered "6", specify \f[C]\-\-number\-offset=5\f[].
|
|
If your document starts with a level\-2 header which you want to be
|
|
numbered "1.5", specify \f[C]\-\-number\-offset=1,4\f[].
|
|
Offsets are 0 by default.
|
|
Implies \f[C]\-\-number\-sections\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-listings\f[]
|
|
Use the \f[C]listings\f[] 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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-i\f[], \f[C]\-\-incremental\f[]
|
|
Make list items in slide shows display incrementally (one by one).
|
|
The default is for lists to be displayed all at once.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-slide\-level=\f[]\f[I]NUMBER\f[]
|
|
Specifies that headers with the specified level create slides (for
|
|
\f[C]beamer\f[], \f[C]s5\f[], \f[C]slidy\f[], \f[C]slideous\f[],
|
|
\f[C]dzslides\f[]).
|
|
Headers above this level in the hierarchy are used to divide the slide
|
|
show into sections; headers below this level create subheads within a
|
|
slide.
|
|
Note that content that is not contained under slide\-level headers will
|
|
not appear in the slide show.
|
|
The default is to set the slide level based on the contents of the
|
|
document; see Structuring the slide show.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-section\-divs\f[]
|
|
Wrap sections in \f[C]<section>\f[] tags (or \f[C]<div>\f[] tags for
|
|
\f[C]html4\f[]), and attach identifiers to the enclosing
|
|
\f[C]<section>\f[] (or \f[C]<div>\f[]) rather than the header itself.
|
|
See Header identifiers, below.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-email\-obfuscation=none\f[]|\f[C]javascript\f[]|\f[C]references\f[]
|
|
Specify a method for obfuscating \f[C]mailto:\f[] links in HTML
|
|
documents.
|
|
\f[C]none\f[] leaves \f[C]mailto:\f[] links as they are.
|
|
\f[C]javascript\f[] obfuscates them using JavaScript.
|
|
\f[C]references\f[] obfuscates them by printing their letters as decimal
|
|
or hexadecimal character references.
|
|
The default is \f[C]none\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-id\-prefix=\f[]\f[I]STRING\f[]
|
|
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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-T\f[] \f[I]STRING\f[], \f[C]\-\-title\-prefix=\f[]\f[I]STRING\f[]
|
|
Specify \f[I]STRING\f[] 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[C]\-\-standalone\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-c\f[] \f[I]URL\f[], \f[C]\-\-css=\f[]\f[I]URL\f[]
|
|
Link to a CSS style sheet.
|
|
This option can be used repeatedly to include multiple files.
|
|
They will be included in the order specified.
|
|
.RS
|
|
.PP
|
|
A stylesheet is required for generating EPUB.
|
|
If none is provided using this option (or the \f[C]stylesheet\f[]
|
|
metadata field), pandoc will look for a file \f[C]epub.css\f[] in the
|
|
user data directory (see \f[C]\-\-data\-dir\f[]).
|
|
If it is not found there, sensible defaults will be used.
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-reference\-doc=\f[]\f[I]FILE\f[]
|
|
Use the specified file as a style reference in producing a docx or ODT
|
|
file.
|
|
.RS
|
|
.TP
|
|
.B 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[C]reference.docx\f[] in the user data directory (see
|
|
\f[C]\-\-data\-dir\f[]).
|
|
If this is not found either, sensible defaults will be used.
|
|
.RS
|
|
.PP
|
|
To produce a custom \f[C]reference.docx\f[], first get a copy of the
|
|
default \f[C]reference.docx\f[]:
|
|
\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.docx\ >\ custom\-reference.docx\f[].
|
|
Then open \f[C]custom\-reference.docx\f[] in Word, 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: [paragraph] Normal, Body Text, First
|
|
Paragraph, Compact, Title, Subtitle, Author, Date, Abstract,
|
|
Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5,
|
|
Heading 6, Heading 7, Heading 8, Heading 9, Block Text, Footnote Text,
|
|
Definition Term, Definition, Caption, Table Caption, Image Caption,
|
|
Figure, Captioned Figure, TOC Heading; [character] Default Paragraph
|
|
Font, Body Text Char, Verbatim Char, Footnote Reference, Hyperlink;
|
|
[table] Table.
|
|
.RE
|
|
.TP
|
|
.B 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[C]reference.odt\f[] in the user data directory (see
|
|
\f[C]\-\-data\-dir\f[]).
|
|
If this is not found either, sensible defaults will be used.
|
|
.RS
|
|
.PP
|
|
To produce a custom \f[C]reference.odt\f[], first get a copy of the
|
|
default \f[C]reference.odt\f[]:
|
|
\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.odt\ >\ custom\-reference.odt\f[].
|
|
Then open \f[C]custom\-reference.odt\f[] in LibreOffice, modify the
|
|
styles as you wish, and save the file.
|
|
.RE
|
|
.TP
|
|
.B PowerPoint
|
|
Any template included with a recent install of Microsoft PowerPoint
|
|
(either with \f[C]\&.pptx\f[] or \f[C]\&.potx\f[] extension) should
|
|
work, as will most templates derived from these.
|
|
.RS
|
|
.PP
|
|
The specific requirement is that the template should contain the
|
|
following four layouts as its first four layouts:
|
|
.IP "1." 3
|
|
Title Slide
|
|
.IP "2." 3
|
|
Title and Content
|
|
.IP "3." 3
|
|
Section Header
|
|
.IP "4." 3
|
|
Two Content
|
|
.PP
|
|
All templates included with a recent version of MS PowerPoint will fit
|
|
these criteria.
|
|
(You can click on \f[C]Layout\f[] under the \f[C]Home\f[] menu to
|
|
check.)
|
|
.PP
|
|
You can also modify the default \f[C]reference.pptx\f[]: first run
|
|
\f[C]pandoc\ \-\-print\-default\-data\-file\ reference.pptx\ >\ custom\-reference.pptx\f[],
|
|
and then modify \f[C]custom\-reference.pptx\f[] in MS PowerPoint (pandoc
|
|
will use the first four layout slides, as mentioned above).
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-epub\-cover\-image=\f[]\f[I]FILE\f[]
|
|
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[C]cover\-image\f[] in a YAML metadata block (see EPUB Metadata,
|
|
below).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-epub\-metadata=\f[]\f[I]FILE\f[]
|
|
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
|
|
.nf
|
|
\f[C]
|
|
\ <dc:rights>Creative\ Commons</dc:rights>
|
|
\ <dc:language>es\-AR</dc:language>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
By default, pandoc will include the following metadata elements:
|
|
\f[C]<dc:title>\f[] (from the document title), \f[C]<dc:creator>\f[]
|
|
(from the document authors), \f[C]<dc:date>\f[] (from the document date,
|
|
which should be in ISO 8601 format), \f[C]<dc:language>\f[] (from the
|
|
\f[C]lang\f[] variable, or, if is not set, the locale), and
|
|
\f[C]<dc:identifier\ id="BookId">\f[] (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
|
|
.B \f[C]\-\-epub\-embed\-font=\f[]\f[I]FILE\f[]
|
|
Embed the specified font in the EPUB.
|
|
This option can be repeated to embed multiple fonts.
|
|
Wildcards can also be used: for example, \f[C]DejaVuSans\-*.ttf\f[].
|
|
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[C]\-\-css\f[]):
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\@font\-face\ {
|
|
font\-family:\ DejaVuSans;
|
|
font\-style:\ normal;
|
|
font\-weight:\ normal;
|
|
src:url("DejaVuSans\-Regular.ttf");
|
|
}
|
|
\@font\-face\ {
|
|
font\-family:\ DejaVuSans;
|
|
font\-style:\ normal;
|
|
font\-weight:\ bold;
|
|
src:url("DejaVuSans\-Bold.ttf");
|
|
}
|
|
\@font\-face\ {
|
|
font\-family:\ DejaVuSans;
|
|
font\-style:\ italic;
|
|
font\-weight:\ normal;
|
|
src:url("DejaVuSans\-Oblique.ttf");
|
|
}
|
|
\@font\-face\ {
|
|
font\-family:\ DejaVuSans;
|
|
font\-style:\ italic;
|
|
font\-weight:\ bold;
|
|
src:url("DejaVuSans\-BoldOblique.ttf");
|
|
}
|
|
body\ {\ font\-family:\ "DejaVuSans";\ }
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-epub\-chapter\-level=\f[]\f[I]NUMBER\f[]
|
|
Specify the header level at which to split the EPUB into separate
|
|
"chapter" files.
|
|
The default is to split into chapters at level 1 headers.
|
|
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 headers, one might want to use a
|
|
chapter level of 2 or 3.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-epub\-subdirectory=\f[]\f[I]DIRNAME\f[]
|
|
Specify the subdirectory in the OCF container that is to hold the
|
|
EPUB\-specific contents.
|
|
The default is \f[C]EPUB\f[].
|
|
To put the EPUB contents in the top level, use an empty string.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-pdf\-engine=pdflatex\f[]|\f[C]lualatex\f[]|\f[C]xelatex\f[]|\f[C]wkhtmltopdf\f[]|\f[C]weasyprint\f[]|\f[C]prince\f[]|\f[C]context\f[]|\f[C]pdfroff\f[]
|
|
Use the specified engine when producing PDF output.
|
|
The default is \f[C]pdflatex\f[].
|
|
If the engine is not in your PATH, the full path of the engine may be
|
|
specified here.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-pdf\-engine\-opt=\f[]\f[I]STRING\f[]
|
|
Use the given string as a command\-line argument to the
|
|
\f[C]pdf\-engine\f[].
|
|
If used multiple times, the arguments are provided with spaces between
|
|
them.
|
|
Note that no check for duplicate options is done.
|
|
.RS
|
|
.RE
|
|
.SS Citation rendering
|
|
.TP
|
|
.B \f[C]\-\-bibliography=\f[]\f[I]FILE\f[]
|
|
Set the \f[C]bibliography\f[] field in the document\[aq]s metadata to
|
|
\f[I]FILE\f[], overriding any value set in the metadata, and process
|
|
citations using \f[C]pandoc\-citeproc\f[].
|
|
(This is equivalent to
|
|
\f[C]\-\-metadata\ bibliography=FILE\ \-\-filter\ pandoc\-citeproc\f[].)
|
|
If \f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] is also supplied,
|
|
\f[C]pandoc\-citeproc\f[] is not used, making this equivalent to
|
|
\f[C]\-\-metadata\ bibliography=FILE\f[].
|
|
If you supply this argument multiple times, each \f[I]FILE\f[] will be
|
|
added to bibliography.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-csl=\f[]\f[I]FILE\f[]
|
|
Set the \f[C]csl\f[] field in the document\[aq]s metadata to
|
|
\f[I]FILE\f[], overriding any value set in the metadata.
|
|
(This is equivalent to \f[C]\-\-metadata\ csl=FILE\f[].) This option is
|
|
only relevant with \f[C]pandoc\-citeproc\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-citation\-abbreviations=\f[]\f[I]FILE\f[]
|
|
Set the \f[C]citation\-abbreviations\f[] field in the document\[aq]s
|
|
metadata to \f[I]FILE\f[], overriding any value set in the metadata.
|
|
(This is equivalent to
|
|
\f[C]\-\-metadata\ citation\-abbreviations=FILE\f[].) This option is
|
|
only relevant with \f[C]pandoc\-citeproc\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-natbib\f[]
|
|
Use \f[C]natbib\f[] for citations in LaTeX output.
|
|
This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or
|
|
with PDF output.
|
|
It is intended for use in producing a LaTeX file that can be processed
|
|
with \f[C]bibtex\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-biblatex\f[]
|
|
Use \f[C]biblatex\f[] for citations in LaTeX output.
|
|
This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or
|
|
with PDF output.
|
|
It is intended for use in producing a LaTeX file that can be processed
|
|
with \f[C]bibtex\f[] or \f[C]biber\f[].
|
|
.RS
|
|
.RE
|
|
.SS Math rendering in HTML
|
|
.PP
|
|
The default is to render TeX math as far as possible using Unicode
|
|
characters.
|
|
Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], 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[C]\-\-mathjax\f[] or another of the following
|
|
options.
|
|
.TP
|
|
.B \f[C]\-\-mathjax\f[][\f[C]=\f[]\f[I]URL\f[]]
|
|
Use MathJax to display embedded TeX math in HTML output.
|
|
TeX math will be put between \f[C]\\(...\\)\f[] (for inline math) or
|
|
\f[C]\\[...\\]\f[] (for display math) and wrapped in \f[C]<span>\f[]
|
|
tags with class \f[C]math\f[].
|
|
Then the MathJax JavaScript will render it.
|
|
The \f[I]URL\f[] should point to the \f[C]MathJax.js\f[] load script.
|
|
If a \f[I]URL\f[] is not provided, a link to the Cloudflare CDN will be
|
|
inserted.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-mathml\f[]
|
|
Convert TeX math to MathML (in \f[C]epub3\f[], \f[C]docbook4\f[],
|
|
\f[C]docbook5\f[], \f[C]jats\f[], \f[C]html4\f[] and \f[C]html5\f[]).
|
|
This is the default in \f[C]odt\f[] output.
|
|
Note that currently only Firefox and Safari (and select e\-book readers)
|
|
natively support MathML.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-webtex\f[][\f[C]=\f[]\f[I]URL\f[]]
|
|
Convert TeX formulas to \f[C]<img>\f[] 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[C]\-\-webtex\ https://latex.codecogs.com/svg.latex?\f[].
|
|
If no URL is specified, the CodeCogs URL generating PNGs will be used
|
|
(\f[C]https://latex.codecogs.com/png.latex?\f[]).
|
|
Note: the \f[C]\-\-webtex\f[] option will affect Markdown output as well
|
|
as HTML, which is useful if you\[aq]re targeting a version of Markdown
|
|
without native math support.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-katex\f[][\f[C]=\f[]\f[I]URL\f[]]
|
|
Use KaTeX to display embedded TeX math in HTML output.
|
|
The \f[I]URL\f[] is the base URL for the KaTeX library.
|
|
That directory should contain a \f[C]katex.min.js\f[] and a
|
|
\f[C]katex.min.css\f[] file.
|
|
If a \f[I]URL\f[] is not provided, a link to the KaTeX CDN will be
|
|
inserted.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-gladtex\f[]
|
|
Enclose TeX math in \f[C]<eq>\f[] tags in HTML output.
|
|
The resulting HTML can then be processed by GladTeX to produce images of
|
|
the typeset formulas and an HTML file with links to these images.
|
|
So, the procedure is:
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-s\ \-\-gladtex\ input.md\ \-o\ myfile.htex
|
|
gladtex\ \-d\ myfile\-images\ myfile.htex
|
|
#\ produces\ myfile.html\ and\ images\ in\ myfile\-images
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.SS Options for wrapper scripts
|
|
.TP
|
|
.B \f[C]\-\-dump\-args\f[]
|
|
Print information about command\-line arguments to \f[I]stdout\f[], 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[C]\-o\f[] option, or \f[C]\-\f[] (for \f[I]stdout\f[]) 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[C]\-\-\f[] separator at the end
|
|
of the line.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]\-\-ignore\-args\f[]
|
|
Ignore command\-line arguments (for use in wrapper scripts).
|
|
Regular pandoc options are not ignored.
|
|
Thus, for example,
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-\-ignore\-args\ \-o\ foo.html\ \-s\ foo.txt\ \-\-\ \-e\ latin1
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
is equivalent to
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-o\ foo.html\ \-s
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.SH TEMPLATES
|
|
.PP
|
|
When the \f[C]\-s/\-\-standalone\f[] 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
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-D\ *FORMAT*
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
where \f[I]FORMAT\f[] is the name of the output format.
|
|
A custom template can be specified using the \f[C]\-\-template\f[]
|
|
option.
|
|
You can also override the system default templates for a given output
|
|
format \f[I]FORMAT\f[] by putting a file
|
|
\f[C]templates/default.*FORMAT*\f[] in the user data directory (see
|
|
\f[C]\-\-data\-dir\f[], above).
|
|
\f[I]Exceptions:\f[]
|
|
.IP \[bu] 2
|
|
For \f[C]odt\f[] output, customize the \f[C]default.opendocument\f[]
|
|
template.
|
|
.IP \[bu] 2
|
|
For \f[C]pdf\f[] output, customize the \f[C]default.latex\f[] template
|
|
(or the \f[C]default.context\f[] template, if you use
|
|
\f[C]\-t\ context\f[], or the \f[C]default.ms\f[] template, if you use
|
|
\f[C]\-t\ ms\f[], or the \f[C]default.html\f[] template, if you use
|
|
\f[C]\-t\ html\f[]).
|
|
.IP \[bu] 2
|
|
\f[C]docx\f[] has no template (however, you can use
|
|
\f[C]\-\-reference\-doc\f[] to customize the output).
|
|
.PP
|
|
Templates contain \f[I]variables\f[], 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[C]\-V/\-\-variable\f[]
|
|
option.
|
|
If a variable is not set, pandoc will look for the key in the
|
|
document\[aq]s metadata \[en] which can be set using either YAML
|
|
metadata blocks or with the \f[C]\-\-metadata\f[] option.
|
|
.SS Variables set by pandoc
|
|
.PP
|
|
Some variables are set automatically by pandoc.
|
|
These vary somewhat depending on the output format, but include the
|
|
following:
|
|
.TP
|
|
.B \f[C]sourcefile\f[], \f[C]outputfile\f[]
|
|
source and destination filenames, as given on the command line.
|
|
\f[C]sourcefile\f[] 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
|
|
.nf
|
|
\f[C]
|
|
$if(sourcefile)$
|
|
$for(sourcefile)$
|
|
$sourcefile$
|
|
$endfor$
|
|
$else$
|
|
(stdin)
|
|
$endif$
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Similarly, \f[C]outputfile\f[] can be \f[C]\-\f[] if output goes to the
|
|
terminal.
|
|
.RE
|
|
.TP
|
|
.B \f[C]title\f[], \f[C]author\f[], \f[C]date\f[]
|
|
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
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
author:
|
|
\-\ Aristotle
|
|
\-\ Peter\ Abelard
|
|
\&...
|
|
\f[]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B \f[C]subtitle\f[]
|
|
document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word
|
|
docx; renders in LaTeX only when using a document class that supports
|
|
\f[C]\\subtitle\f[], such as \f[C]beamer\f[] or the KOMA\-Script series
|
|
(\f[C]scrartcl\f[], \f[C]scrreprt\f[], \f[C]scrbook\f[]).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]institute\f[]
|
|
author affiliations (in LaTeX and Beamer only).
|
|
Can be a list, when there are multiple authors.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]abstract\f[]
|
|
document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]keywords\f[]
|
|
list of keywords to be included in HTML, PDF, and AsciiDoc metadata; may
|
|
be repeated as for \f[C]author\f[], above
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]header\-includes\f[]
|
|
contents specified by \f[C]\-H/\-\-include\-in\-header\f[] (may have
|
|
multiple values)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]toc\f[]
|
|
non\-null value if \f[C]\-\-toc/\-\-table\-of\-contents\f[] was
|
|
specified
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]toc\-title\f[]
|
|
title of table of contents (works only with EPUB, opendocument, odt,
|
|
docx, pptx, beamer, LaTeX)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]include\-before\f[]
|
|
contents specified by \f[C]\-B/\-\-include\-before\-body\f[] (may have
|
|
multiple values)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]include\-after\f[]
|
|
contents specified by \f[C]\-A/\-\-include\-after\-body\f[] (may have
|
|
multiple values)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]body\f[]
|
|
body of document
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]meta\-json\f[]
|
|
JSON representation of all of the document\[aq]s metadata.
|
|
Field values are transformed to the selected output format.
|
|
.RS
|
|
.RE
|
|
.SS Language variables
|
|
.TP
|
|
.B \f[C]lang\f[]
|
|
identifies the main language of the document, using a code according to
|
|
BCP 47 (e.g.
|
|
\f[C]en\f[] or \f[C]en\-GB\f[]).
|
|
For some output formats, pandoc will convert it to an appropriate format
|
|
stored in the additional variables \f[C]babel\-lang\f[],
|
|
\f[C]polyglossia\-lang\f[] (LaTeX) and \f[C]context\-lang\f[] (ConTeXt).
|
|
.RS
|
|
.PP
|
|
Native pandoc Spans and Divs with the lang attribute (value in BCP 47)
|
|
can be used to switch the language in that range.
|
|
In LaTeX output, \f[C]babel\-otherlangs\f[] and
|
|
\f[C]polyglossia\-otherlangs\f[] variables will be generated
|
|
automatically based on the \f[C]lang\f[] attributes of Spans and Divs in
|
|
the document.
|
|
.RE
|
|
.TP
|
|
.B \f[C]dir\f[]
|
|
the base direction of the document, either \f[C]rtl\f[]
|
|
(right\-to\-left) or \f[C]ltr\f[] (left\-to\-right).
|
|
.RS
|
|
.PP
|
|
For bidirectional documents, native pandoc \f[C]span\f[]s and
|
|
\f[C]div\f[]s with the \f[C]dir\f[] attribute (value \f[C]rtl\f[] or
|
|
\f[C]ltr\f[]) can be used to override the base direction in some output
|
|
formats.
|
|
This may not always be necessary if the final renderer (e.g.
|
|
the browser, when generating HTML) supports the Unicode Bidirectional
|
|
Algorithm.
|
|
.PP
|
|
When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[]
|
|
engine is fully supported (use \f[C]\-\-pdf\-engine=xelatex\f[]).
|
|
.RE
|
|
.SS Variables for slides
|
|
.PP
|
|
Variables are available for producing slide shows with pandoc, including
|
|
all reveal.js configuration options.
|
|
.TP
|
|
.B \f[C]titlegraphic\f[]
|
|
title graphic for Beamer documents
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]logo\f[]
|
|
logo for Beamer documents
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]slidy\-url\f[]
|
|
base URL for Slidy documents (defaults to
|
|
\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]slideous\-url\f[]
|
|
base URL for Slideous documents (defaults to \f[C]slideous\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]s5\-url\f[]
|
|
base URL for S5 documents (defaults to \f[C]s5/default\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]revealjs\-url\f[]
|
|
base URL for reveal.js documents (defaults to \f[C]reveal.js\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]theme\f[], \f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], \f[C]outertheme\f[]
|
|
themes for LaTeX \f[C]beamer\f[] documents
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]themeoptions\f[]
|
|
options for LaTeX beamer themes (a list).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]navigation\f[]
|
|
controls navigation symbols in \f[C]beamer\f[] documents (default is
|
|
\f[C]empty\f[] for no navigation symbols; other valid values are
|
|
\f[C]frame\f[], \f[C]vertical\f[], and \f[C]horizontal\f[]).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]section\-titles\f[]
|
|
enables on "title pages" for new sections in \f[C]beamer\f[] documents
|
|
(default = true).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]beamerarticle\f[]
|
|
when true, the \f[C]beamerarticle\f[] package is loaded (for producing
|
|
an article from beamer slides).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]aspectratio\f[]
|
|
aspect ratio of slides (for beamer only, \f[C]1610\f[] for 16:10,
|
|
\f[C]169\f[] for 16:9, \f[C]149\f[] for 14:9, \f[C]141\f[] for 1.41:1,
|
|
\f[C]54\f[] for 5:4, \f[C]43\f[] for 4:3 which is the default, and
|
|
\f[C]32\f[] for 3:2).
|
|
.RS
|
|
.RE
|
|
.SS Variables for LaTeX
|
|
.PP
|
|
LaTeX variables are used when creating a PDF.
|
|
.TP
|
|
.B \f[C]papersize\f[]
|
|
paper size, e.g.
|
|
\f[C]letter\f[], \f[C]a4\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]fontsize\f[]
|
|
font size for body text (e.g.
|
|
\f[C]10pt\f[], \f[C]12pt\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]documentclass\f[]
|
|
document class, e.g.
|
|
\f[C]article\f[], \f[C]report\f[], \f[C]book\f[], \f[C]memoir\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]classoption\f[]
|
|
option for document class, e.g.
|
|
\f[C]oneside\f[]; may be repeated for multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]beameroption\f[]
|
|
In beamer, add extra beamer option with \f[C]\\setbeameroption{}\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]geometry\f[]
|
|
option for \f[C]geometry\f[] package, e.g.
|
|
\f[C]margin=1in\f[]; may be repeated for multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[]
|
|
sets margins, if \f[C]geometry\f[] is not used (otherwise
|
|
\f[C]geometry\f[] overrides these)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]linestretch\f[]
|
|
adjusts line spacing using the \f[C]setspace\f[] package, e.g.
|
|
\f[C]1.25\f[], \f[C]1.5\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]fontfamily\f[]
|
|
font package for use with \f[C]pdflatex\f[]: TeX Live includes many
|
|
options, documented in the LaTeX Font Catalogue.
|
|
The default is Latin Modern.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]fontfamilyoptions\f[]
|
|
options for package used as \f[C]fontfamily\f[]: e.g.
|
|
\f[C]osf,sc\f[] with \f[C]fontfamily\f[] set to \f[C]mathpazo\f[]
|
|
provides Palatino with old\-style figures and true small caps; may be
|
|
repeated for multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[]
|
|
font families for use with \f[C]xelatex\f[] or \f[C]lualatex\f[]: take
|
|
the name of any system font, using the \f[C]fontspec\f[] package.
|
|
Note that if \f[C]CJKmainfont\f[] is used, the \f[C]xecjk\f[] package
|
|
must be available.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]mainfontoptions\f[], \f[C]sansfontoptions\f[], \f[C]monofontoptions\f[], \f[C]mathfontoptions\f[], \f[C]CJKoptions\f[]
|
|
options to use with \f[C]mainfont\f[], \f[C]sansfont\f[],
|
|
\f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[] in
|
|
\f[C]xelatex\f[] and \f[C]lualatex\f[].
|
|
Allow for any choices available through \f[C]fontspec\f[], such as the
|
|
OpenType features \f[C]Numbers=OldStyle,Numbers=Proportional\f[].
|
|
May be repeated for multiple options.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]fontenc\f[]
|
|
allows font encoding to be specified through \f[C]fontenc\f[] package
|
|
(with \f[C]pdflatex\f[]); default is \f[C]T1\f[] (see guide to LaTeX
|
|
font encodings)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]microtypeoptions\f[]
|
|
options to pass to the microtype package
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]colorlinks\f[]
|
|
add color to link text; automatically enabled if any of
|
|
\f[C]linkcolor\f[], \f[C]filecolor\f[], \f[C]citecolor\f[],
|
|
\f[C]urlcolor\f[], or \f[C]toccolor\f[] are set
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]linkcolor\f[], \f[C]filecolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[]
|
|
color for internal links, external links, citation links, linked URLs,
|
|
and links in table of contents, respectively: uses options allowed by
|
|
\f[C]xcolor\f[], including the \f[C]dvipsnames\f[], \f[C]svgnames\f[],
|
|
and \f[C]x11names\f[] lists
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]links\-as\-notes\f[]
|
|
causes links to be printed as footnotes
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]indent\f[]
|
|
uses document class settings for indentation (the default LaTeX template
|
|
otherwise removes indentation and adds space between paragraphs)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]subparagraph\f[]
|
|
disables default behavior of LaTeX template that redefines
|
|
(sub)paragraphs as sections, changing the appearance of nested headings
|
|
in some classes
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]thanks\f[]
|
|
specifies contents of acknowledgments footnote after document title.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]toc\f[]
|
|
include table of contents (can also be set using
|
|
\f[C]\-\-toc/\-\-table\-of\-contents\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]toc\-depth\f[]
|
|
level of section to include in table of contents
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]secnumdepth\f[]
|
|
numbering depth for sections, if sections are numbered
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]lof\f[], \f[C]lot\f[]
|
|
include list of figures, list of tables
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]bibliography\f[]
|
|
bibliography to use for resolving references
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]biblio\-style\f[]
|
|
bibliography style, when used with \f[C]\-\-natbib\f[] and
|
|
\f[C]\-\-biblatex\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]biblio\-title\f[]
|
|
bibliography title, when used with \f[C]\-\-natbib\f[] and
|
|
\f[C]\-\-biblatex\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]biblatexoptions\f[]
|
|
list of options for biblatex.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]natbiboptions\f[]
|
|
list of options for natbib.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]pagestyle\f[]
|
|
An option for LaTeX\[aq]s \f[C]\\pagestyle{}\f[].
|
|
The default article class supports \[aq]plain\[aq] (default),
|
|
\[aq]empty\[aq], and \[aq]headings\[aq]; headings puts section titles in
|
|
the header.
|
|
.RS
|
|
.RE
|
|
.SS Variables for ConTeXt
|
|
.TP
|
|
.B \f[C]papersize\f[]
|
|
paper size, e.g.
|
|
\f[C]letter\f[], \f[C]A4\f[], \f[C]landscape\f[] (see ConTeXt Paper
|
|
Setup); may be repeated for multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]layout\f[]
|
|
options for page margins and text arrangement (see ConTeXt Layout); may
|
|
be repeated for multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[]
|
|
sets margins, if \f[C]layout\f[] is not used (otherwise \f[C]layout\f[]
|
|
overrides these)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]fontsize\f[]
|
|
font size for body text (e.g.
|
|
\f[C]10pt\f[], \f[C]12pt\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[]
|
|
font families: take the name of any system font (see ConTeXt Font
|
|
Switching)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]linkcolor\f[], \f[C]contrastcolor\f[]
|
|
color for links outside and inside a page, e.g.
|
|
\f[C]red\f[], \f[C]blue\f[] (see ConTeXt Color)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]linkstyle\f[]
|
|
typeface style for links, e.g.
|
|
\f[C]normal\f[], \f[C]bold\f[], \f[C]slanted\f[], \f[C]boldslanted\f[],
|
|
\f[C]type\f[], \f[C]cap\f[], \f[C]small\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]indenting\f[]
|
|
controls indentation of paragraphs, e.g.
|
|
\f[C]yes,small,next\f[] (see ConTeXt Indentation); may be repeated for
|
|
multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]whitespace\f[]
|
|
spacing between paragraphs, e.g.
|
|
\f[C]none\f[], \f[C]small\f[] (using \f[C]setupwhitespace\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]interlinespace\f[]
|
|
adjusts line spacing, e.g.
|
|
\f[C]4ex\f[] (using \f[C]setupinterlinespace\f[]); may be repeated for
|
|
multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]headertext\f[], \f[C]footertext\f[]
|
|
text to be placed in running header or footer (see ConTeXt Headers and
|
|
Footers); may be repeated up to four times for different placement
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]pagenumbering\f[]
|
|
page number style and location (using \f[C]setuppagenumbering\f[]); may
|
|
be repeated for multiple options
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]toc\f[]
|
|
include table of contents (can also be set using
|
|
\f[C]\-\-toc/\-\-table\-of\-contents\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]lof\f[], \f[C]lot\f[]
|
|
include list of figures, list of tables
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]pdfa\f[]
|
|
adds to the preamble the setup necessary to generate PDF/A\-1b:2005.
|
|
To successfully generate PDF/A the required ICC color profiles have to
|
|
be available and the content and all included files (such as images)
|
|
have to be standard conforming.
|
|
The ICC profiles can be obtained from ConTeXt ICC Profiles.
|
|
See also ConTeXt PDFA for more details.
|
|
.RS
|
|
.RE
|
|
.SS Variables for man pages
|
|
.TP
|
|
.B \f[C]section\f[]
|
|
section number in man pages
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]header\f[]
|
|
header in man pages
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]footer\f[]
|
|
footer in man pages
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]adjusting\f[]
|
|
adjusts text to left (\f[C]l\f[]), right (\f[C]r\f[]), center
|
|
(\f[C]c\f[]), or both (\f[C]b\f[]) margins
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]hyphenate\f[]
|
|
if \f[C]true\f[] (the default), hyphenation will be used
|
|
.RS
|
|
.RE
|
|
.SS Variables for ms
|
|
.TP
|
|
.B \f[C]pointsize\f[]
|
|
point size (e.g.
|
|
\f[C]10p\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]lineheight\f[]
|
|
line height (e.g.
|
|
\f[C]12p\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]fontfamily\f[]
|
|
font family (e.g.
|
|
\f[C]T\f[] or \f[C]P\f[])
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]indent\f[]
|
|
paragraph indent (e.g.
|
|
\f[C]2m\f[])
|
|
.RS
|
|
.RE
|
|
.SS Using variables in templates
|
|
.PP
|
|
Variable names are sequences of alphanumerics, \f[C]\-\f[], and
|
|
\f[C]_\f[], starting with a letter.
|
|
A variable name surrounded by \f[C]$\f[] signs will be replaced by its
|
|
value.
|
|
For example, the string \f[C]$title$\f[] in
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<title>$title$</title>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
will be replaced by the document title.
|
|
.PP
|
|
To write a literal \f[C]$\f[] in a template, use \f[C]$$\f[].
|
|
.PP
|
|
Templates may contain conditionals.
|
|
The syntax is as follows:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$if(variable)$
|
|
X
|
|
$else$
|
|
Y
|
|
$endif$
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This will include \f[C]X\f[] in the template if \f[C]variable\f[] has a
|
|
truthy value; otherwise it will include \f[C]Y\f[].
|
|
Here a truthy value is any of the following:
|
|
.IP \[bu] 2
|
|
a string that is not entirely white space,
|
|
.IP \[bu] 2
|
|
a non\-empty array where the first value is truthy,
|
|
.IP \[bu] 2
|
|
any number (including zero),
|
|
.IP \[bu] 2
|
|
any object,
|
|
.IP \[bu] 2
|
|
the boolean \f[C]true\f[] (to specify the boolean \f[C]true\f[] value
|
|
using YAML metadata or the \f[C]\-\-metadata\f[] flag, use
|
|
\f[C]true\f[], \f[C]True\f[], or \f[C]TRUE\f[]; with the
|
|
\f[C]\-\-variable\f[] flag, simply omit a value for the variable, e.g.
|
|
\f[C]\-\-variable\ draft\f[]).
|
|
.PP
|
|
\f[C]X\f[] and \f[C]Y\f[] are placeholders for any valid template text,
|
|
and may include interpolated variables or other conditionals.
|
|
The \f[C]$else$\f[] section may be omitted.
|
|
.PP
|
|
When variables can have multiple values (for example, \f[C]author\f[] in
|
|
a multi\-author document), you can use the \f[C]$for$\f[] keyword:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$for(author)$
|
|
<meta\ name="author"\ content="$author$"\ />
|
|
$endfor$
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
You can optionally specify a separator to be used between consecutive
|
|
items:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$for(author)$$author$$sep$,\ $endfor$
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
A dot can be used to select a field of a variable that takes an object
|
|
as its value.
|
|
So, for example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$author.name$\ ($author.affiliation$)
|
|
\f[]
|
|
.fi
|
|
.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.
|
|
.PP
|
|
Templates may contain comments: anything on a line after \f[C]$\-\-\f[]
|
|
will be treated as a comment and ignored.
|
|
.SH EXTENSIONS
|
|
.PP
|
|
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[C]+EXTENSION\f[] to the format
|
|
name and disabled by adding \f[C]\-EXTENSION\f[].
|
|
For example, \f[C]\-\-from\ markdown_strict+footnotes\f[] is strict
|
|
Markdown with footnotes enabled, while
|
|
\f[C]\-\-from\ markdown\-footnotes\-pipe_tables\f[] is pandoc\[aq]s
|
|
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\[aq]s Markdown below (See Markdown variants for
|
|
\f[C]commonmark\f[] and \f[C]gfm\f[].) In the following, extensions that
|
|
also work for other formats are covered.
|
|
.SS Typography
|
|
.SS Extension: \f[C]smart\f[]
|
|
.PP
|
|
Interpret straight quotes as curly quotes, \f[C]\-\-\-\f[] as
|
|
em\-dashes, \f[C]\-\-\f[] as en\-dashes, and \f[C]\&...\f[] as ellipses.
|
|
Nonbreaking spaces are inserted after certain abbreviations, such as
|
|
"Mr."
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
.B input formats
|
|
\f[C]markdown\f[], \f[C]commonmark\f[], \f[C]latex\f[],
|
|
\f[C]mediawiki\f[], \f[C]org\f[], \f[C]rst\f[], \f[C]twiki\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B output formats
|
|
\f[C]markdown\f[], \f[C]latex\f[], \f[C]context\f[], \f[C]rst\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B enabled by default in
|
|
\f[C]markdown\f[], \f[C]latex\f[], \f[C]context\f[] (both input and
|
|
output)
|
|
.RS
|
|
.RE
|
|
.PP
|
|
Note: If you are \f[I]writing\f[] Markdown, then the \f[C]smart\f[]
|
|
extension has the reverse effect: what would have been curly quotes
|
|
comes out straight.
|
|
.PP
|
|
In LaTeX, \f[C]smart\f[] means to use the standard TeX ligatures for
|
|
quotation marks (\f[C]``\f[] and \f[C]\[aq]\[aq]\f[] for double quotes,
|
|
\f[C]`\f[] and \f[C]\[aq]\f[] for single quotes) and dashes
|
|
(\f[C]\-\-\f[] for en\-dash and \f[C]\-\-\-\f[] for em\-dash).
|
|
If \f[C]smart\f[] is disabled, then in reading LaTeX pandoc will parse
|
|
these characters literally.
|
|
In writing LaTeX, enabling \f[C]smart\f[] tells pandoc to use the
|
|
ligatures when possible; if \f[C]smart\f[] is disabled pandoc will use
|
|
unicode quotation mark and dash characters.
|
|
.SS Headers and sections
|
|
.SS Extension: \f[C]auto_identifiers\f[]
|
|
.PP
|
|
A header without an explicitly specified identifier will be
|
|
automatically assigned a unique identifier based on the header text.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
.B input formats
|
|
\f[C]markdown\f[], \f[C]latex\f[], \f[C]rst\f[], \f[C]mediawiki\f[],
|
|
\f[C]textile\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B output formats
|
|
\f[C]markdown\f[], \f[C]muse\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B enabled by default in
|
|
\f[C]markdown\f[], \f[C]muse\f[]
|
|
.RS
|
|
.RE
|
|
.PP
|
|
The algorithm used to derive the identifier from the header text is:
|
|
.IP \[bu] 2
|
|
Remove all formatting, links, etc.
|
|
.IP \[bu] 2
|
|
Remove all footnotes.
|
|
.IP \[bu] 2
|
|
Remove all punctuation, 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[C]section\f[].
|
|
.PP
|
|
Thus, for example,
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
Header
|
|
T}@T{
|
|
Identifier
|
|
T}
|
|
_
|
|
T{
|
|
\f[C]Header\ identifiers\ in\ HTML\f[]
|
|
T}@T{
|
|
\f[C]header\-identifiers\-in\-html\f[]
|
|
T}
|
|
T{
|
|
\f[C]*Dogs*?\-\-in\ *my*\ house?\f[]
|
|
T}@T{
|
|
\f[C]dogs\-\-in\-my\-house\f[]
|
|
T}
|
|
T{
|
|
\f[C][HTML],\ [S5],\ or\ [RTF]?\f[]
|
|
T}@T{
|
|
\f[C]html\-s5\-or\-rtf\f[]
|
|
T}
|
|
T{
|
|
\f[C]3.\ Applications\f[]
|
|
T}@T{
|
|
\f[C]applications\f[]
|
|
T}
|
|
T{
|
|
\f[C]33\f[]
|
|
T}@T{
|
|
\f[C]section\f[]
|
|
T}
|
|
.TE
|
|
.PP
|
|
These rules should, in most cases, allow one to determine the identifier
|
|
from the header text.
|
|
The exception is when several headers 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[C]\-1\f[] appended; the third with
|
|
\f[C]\-2\f[]; and so on.
|
|
.PP
|
|
These identifiers are used to provide link targets in the table of
|
|
contents generated by the \f[C]\-\-toc|\-\-table\-of\-contents\f[]
|
|
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
|
|
.nf
|
|
\f[C]
|
|
See\ the\ section\ on
|
|
[header\ identifiers](#header\-identifiers\-in\-html\-latex\-and\-context).
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note, however, that this method of providing links to sections works
|
|
only in HTML, LaTeX, and ConTeXt formats.
|
|
.PP
|
|
If the \f[C]\-\-section\-divs\f[] option is specified, then each section
|
|
will be wrapped in a \f[C]section\f[] (or a \f[C]div\f[], if
|
|
\f[C]html4\f[] was specified), and the identifier will be attached to
|
|
the enclosing \f[C]<section>\f[] (or \f[C]<div>\f[]) tag rather than the
|
|
header itself.
|
|
This allows entire sections to be manipulated using JavaScript or
|
|
treated differently in CSS.
|
|
.SS Extension: \f[C]ascii_identifiers\f[]
|
|
.PP
|
|
Causes the identifiers produced by \f[C]auto_identifiers\f[] to be pure
|
|
ASCII.
|
|
Accents are stripped off of accented Latin letters, and non\-Latin
|
|
letters are omitted.
|
|
.SS Math Input
|
|
.PP
|
|
The extensions \f[C]tex_math_dollars\f[],
|
|
\f[C]tex_math_single_backslash\f[], and
|
|
\f[C]tex_math_double_backslash\f[] are described in the section about
|
|
Pandoc\[aq]s 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
|
|
.PP
|
|
The following extensions (especially how they affect Markdown
|
|
input/output) are also described in more detail in their respective
|
|
sections of Pandoc\[aq]s Markdown.
|
|
.SS Extension: \f[C]raw_html\f[]
|
|
.PP
|
|
When converting from HTML, parse elements to raw HTML which are not
|
|
representable in pandoc\[aq]s AST.
|
|
By default, this is disabled for HTML input.
|
|
.SS Extension: \f[C]raw_tex\f[]
|
|
.PP
|
|
Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats (in
|
|
addition to \f[C]markdown\f[]):
|
|
.TP
|
|
.B input formats
|
|
\f[C]latex\f[], \f[C]org\f[], \f[C]textile\f[], \f[C]html\f[]
|
|
(environments, \f[C]\\ref\f[], and \f[C]\\eqref\f[] only)
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B output formats
|
|
\f[C]textile\f[], \f[C]commonmark\f[]
|
|
.RS
|
|
.RE
|
|
.SS Extension: \f[C]native_divs\f[]
|
|
.PP
|
|
This extension is enabled by default for HTML input.
|
|
This means that \f[C]div\f[]s are parsed to pandoc native elements.
|
|
(Alternatively, you can parse them to raw HTML using
|
|
\f[C]\-f\ html\-native_divs+raw_html\f[].)
|
|
.PP
|
|
When converting HTML to Markdown, for example, you may want to drop all
|
|
\f[C]div\f[]s and \f[C]span\f[]s:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-f\ html\-native_divs\-native_spans\ \-t\ markdown
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]native_spans\f[]
|
|
.PP
|
|
Analogous to \f[C]native_divs\f[] above.
|
|
.SS Literate Haskell support
|
|
.SS Extension: \f[C]literate_haskell\f[]
|
|
.PP
|
|
Treat the document as literate Haskell source.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
.B input formats
|
|
\f[C]markdown\f[], \f[C]rst\f[], \f[C]latex\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B output formats
|
|
\f[C]markdown\f[], \f[C]rst\f[], \f[C]latex\f[], \f[C]html\f[]
|
|
.RS
|
|
.RE
|
|
.PP
|
|
If you append \f[C]+lhs\f[] (or \f[C]+literate_haskell\f[]) to one of
|
|
the formats above, pandoc will treat the document as literate Haskell
|
|
source.
|
|
This means that
|
|
.IP \[bu] 2
|
|
In Markdown input, "bird track" sections will be parsed as Haskell code
|
|
rather than block quotations.
|
|
Text between \f[C]\\begin{code}\f[] and \f[C]\\end{code}\f[] will also
|
|
be treated as Haskell code.
|
|
For ATX\-style headers the character \[aq]=\[aq] will be used instead of
|
|
\[aq]#\[aq].
|
|
.IP \[bu] 2
|
|
In Markdown output, code blocks with classes \f[C]haskell\f[] and
|
|
\f[C]literate\f[] 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, headers will be rendered setext\-style (with underlines)
|
|
rather than ATX\-style (with \[aq]#\[aq] characters).
|
|
(This is because ghc treats \[aq]#\[aq] characters in column 1 as
|
|
introducing line numbers.)
|
|
.IP \[bu] 2
|
|
In restructured text input, "bird track" sections will be parsed as
|
|
Haskell code.
|
|
.IP \[bu] 2
|
|
In restructured text output, code blocks with class \f[C]haskell\f[]
|
|
will be rendered using bird tracks.
|
|
.IP \[bu] 2
|
|
In LaTeX input, text in \f[C]code\f[] environments will be parsed as
|
|
Haskell code.
|
|
.IP \[bu] 2
|
|
In LaTeX output, code blocks with class \f[C]haskell\f[] will be
|
|
rendered inside \f[C]code\f[] environments.
|
|
.IP \[bu] 2
|
|
In HTML output, code blocks with class \f[C]haskell\f[] will be rendered
|
|
with class \f[C]literatehaskell\f[] and bird tracks.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-f\ markdown+lhs\ \-t\ html
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
reads literate Haskell source formatted with Markdown conventions and
|
|
writes ordinary HTML (without bird tracks).
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-f\ markdown+lhs\ \-t\ html+lhs
|
|
\f[]
|
|
.fi
|
|
.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[C]empty_paragraphs\f[]
|
|
.PP
|
|
Allows empty paragraphs.
|
|
By default empty paragraphs are omitted.
|
|
.PP
|
|
This extension can be enabled/disabled for the following formats:
|
|
.TP
|
|
.B input formats
|
|
\f[C]docx\f[], \f[C]html\f[]
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B output formats
|
|
\f[C]docx\f[], \f[C]odt\f[], \f[C]opendocument\f[], \f[C]html\f[]
|
|
.RS
|
|
.RE
|
|
.SS Extension: \f[C]styles\f[]
|
|
.PP
|
|
Read all docx styles as divs (for paragraph styles) and spans (for
|
|
character styles) regardless of whether pandoc understands the meaning
|
|
of these styles.
|
|
This can be used with docx custom styles.
|
|
Disabled by default.
|
|
.TP
|
|
.B input formats
|
|
\f[C]docx\f[]
|
|
.RS
|
|
.RE
|
|
.SS Extension: \f[C]amuse\f[]
|
|
.PP
|
|
In the \f[C]muse\f[] input format, this enables Text::Amuse extensions
|
|
to Emacs Muse markup.
|
|
.SS Extension: \f[C]citations\f[]
|
|
.PP
|
|
Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted
|
|
in \f[C]org\f[] input.
|
|
.SS Extension: \f[C]ntb\f[]
|
|
.PP
|
|
In the \f[C]context\f[] 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.
|
|
.SH PANDOC\[aq]S MARKDOWN
|
|
.PP
|
|
Pandoc understands an extended and slightly revised version of John
|
|
Gruber\[aq]s Markdown syntax.
|
|
This document explains the syntax, noting differences from standard
|
|
Markdown.
|
|
Except where noted, these differences can be suppressed by using the
|
|
\f[C]markdown_strict\f[] format instead of \f[C]markdown\f[].
|
|
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
|
|
.PP
|
|
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\[aq]s been marked up with tags or
|
|
formatting instructions.
|
|
\-\- John Gruber
|
|
.RE
|
|
.PP
|
|
This principle has guided pandoc\[aq]s decisions in finding syntax for
|
|
tables, footnotes, and other extensions.
|
|
.PP
|
|
There is, however, one respect in which pandoc\[aq]s 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
|
|
.PP
|
|
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[C]escaped_line_breaks\f[]
|
|
.PP
|
|
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 Headers
|
|
.PP
|
|
There are two kinds of headers: Setext and ATX.
|
|
.SS Setext\-style headers
|
|
.PP
|
|
A setext\-style header is a line of text "underlined" with a row of
|
|
\f[C]=\f[] signs (for a level one header) or \f[C]\-\f[] signs (for a
|
|
level two header):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
A\ level\-one\ header
|
|
==================
|
|
|
|
A\ level\-two\ header
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The header text can contain inline formatting, such as emphasis (see
|
|
Inline formatting, below).
|
|
.SS ATX\-style headers
|
|
.PP
|
|
An ATX\-style header consists of one to six \f[C]#\f[] signs and a line
|
|
of text, optionally followed by any number of \f[C]#\f[] signs.
|
|
The number of \f[C]#\f[] signs at the beginning of the line is the
|
|
header level:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
##\ A\ level\-two\ header
|
|
|
|
###\ A\ level\-three\ header\ ###
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
As with setext\-style headers, the header text can contain formatting:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ A\ level\-one\ header\ with\ a\ [link](/url)\ and\ *emphasis*
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]blank_before_header\f[]
|
|
.PP
|
|
Standard Markdown syntax does not require a blank line before a header.
|
|
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[C]#\f[] to end up at the beginning of a line by accident (perhaps
|
|
through line wrapping).
|
|
Consider, for example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
I\ like\ several\ of\ their\ flavors\ of\ ice\ cream:
|
|
#22,\ for\ example,\ and\ #5.
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]space_in_atx_header\f[]
|
|
.PP
|
|
Many Markdown implementations do not require a space between the opening
|
|
\f[C]#\f[]s of an ATX header and the header text, so that
|
|
\f[C]#5\ bolt\f[] and \f[C]#hashtag\f[] count as headers.
|
|
With this extension, pandoc does require the space.
|
|
.SS Header identifiers
|
|
.PP
|
|
See also the \f[C]auto_identifiers\f[] extension above.
|
|
.SS Extension: \f[C]header_attributes\f[]
|
|
.PP
|
|
Headers can be assigned attributes using this syntax at the end of the
|
|
line containing the header text:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
{#identifier\ .class\ .class\ key=value\ key=value}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Thus, for example, the following headers will all be assigned the
|
|
identifier \f[C]foo\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ My\ header\ {#foo}
|
|
|
|
##\ My\ header\ ##\ \ \ \ {#foo}
|
|
|
|
My\ other\ header\ \ \ {#foo}
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\f[]
|
|
.fi
|
|
.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\[aq]t 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, and AsciiDoc writers.
|
|
.PP
|
|
Headers with the class \f[C]unnumbered\f[] will not be numbered, even if
|
|
\f[C]\-\-number\-sections\f[] is specified.
|
|
A single hyphen (\f[C]\-\f[]) in an attribute context is equivalent to
|
|
\f[C]\&.unnumbered\f[], and preferable in non\-English documents.
|
|
So,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ My\ header\ {\-}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
is just the same as
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ My\ header\ {.unnumbered}
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]implicit_header_references\f[]
|
|
.PP
|
|
Pandoc behaves as if reference links have been defined for each header.
|
|
So, to link to a header
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ Header\ identifiers\ in\ HTML
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
you can simply write
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[Header\ identifiers\ in\ HTML]
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[Header\ identifiers\ in\ HTML][]
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[the\ section\ on\ header\ identifiers][header\ identifiers\ in
|
|
HTML]
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
instead of giving the identifier explicitly:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[Header\ identifiers\ in\ HTML](#header\-identifiers\-in\-html)
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If there are multiple headers 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
|
|
header references.
|
|
So, in the following example, the link will point to \f[C]bar\f[], not
|
|
to \f[C]#foo\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ Foo
|
|
|
|
[foo]:\ bar
|
|
|
|
See\ [foo]
|
|
\f[]
|
|
.fi
|
|
.SS Block quotations
|
|
.PP
|
|
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 headers), with each line preceded by a \f[C]>\f[]
|
|
character and an optional space.
|
|
(The \f[C]>\f[] need not start at the left margin, but it should not be
|
|
indented more than three spaces.)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
>\ This\ is\ a\ block\ quote.\ This
|
|
>\ paragraph\ has\ two\ lines.
|
|
>
|
|
>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
|
|
>\ 2.\ Second\ item.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
A "lazy" form, which requires the \f[C]>\f[] character only on the first
|
|
line of each block, is also allowed:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
>\ This\ is\ a\ block\ quote.\ This
|
|
paragraph\ has\ two\ lines.
|
|
|
|
>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
|
|
2.\ Second\ item.
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
>\ This\ is\ a\ block\ quote.
|
|
>
|
|
>\ >\ A\ block\ quote\ within\ a\ block\ quote.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If the \f[C]>\f[] 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[C]>\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
>\ \ \ \ \ code
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]blank_before_blockquote\f[]
|
|
.PP
|
|
Standard 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[C]>\f[] to end up at the beginning of a line by accident (perhaps
|
|
through line wrapping).
|
|
So, unless the \f[C]markdown_strict\f[] format is used, the following
|
|
does not produce a nested block quote in pandoc:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
>\ This\ is\ a\ block\ quote.
|
|
>>\ Nested.
|
|
\f[]
|
|
.fi
|
|
.SS Verbatim (code) blocks
|
|
.SS Indented code blocks
|
|
.PP
|
|
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
|
|
.nf
|
|
\f[C]
|
|
\ \ \ \ if\ (a\ >\ 3)\ {
|
|
\ \ \ \ \ \ moveShip(5\ *\ gravity,\ DOWN);
|
|
\ \ \ \ }
|
|
\f[]
|
|
.fi
|
|
.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[C]fenced_code_blocks\f[]
|
|
.PP
|
|
In addition to standard indented code blocks, pandoc supports
|
|
\f[I]fenced\f[] code blocks.
|
|
These begin with a row of three or more tildes (\f[C]~\f[]) 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
|
|
.nf
|
|
\f[C]
|
|
~~~~~~~
|
|
if\ (a\ >\ 3)\ {
|
|
\ \ moveShip(5\ *\ gravity,\ DOWN);
|
|
}
|
|
~~~~~~~
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
~~~~~~~~~~~~~~~~
|
|
~~~~~~~~~~
|
|
code\ including\ tildes
|
|
~~~~~~~~~~
|
|
~~~~~~~~~~~~~~~~
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]backtick_code_blocks\f[]
|
|
.PP
|
|
Same as \f[C]fenced_code_blocks\f[], but uses backticks (\f[C]`\f[])
|
|
instead of tildes (\f[C]~\f[]).
|
|
.SS Extension: \f[C]fenced_code_attributes\f[]
|
|
.PP
|
|
Optionally, you may attach attributes to fenced or backtick code block
|
|
using this syntax:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
~~~~\ {#mycode\ .haskell\ .numberLines\ startFrom="100"}
|
|
qsort\ []\ \ \ \ \ =\ []
|
|
qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Here \f[C]mycode\f[] is an identifier, \f[C]haskell\f[] and
|
|
\f[C]numberLines\f[] are classes, and \f[C]startFrom\f[] is an attribute
|
|
with value \f[C]100\f[].
|
|
Some output formats can use this information to do syntax highlighting.
|
|
Currently, the only output formats that uses 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[C]pandoc\ \-\-list\-highlight\-languages\f[].) Otherwise, the code
|
|
block above will appear as follows:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<pre\ id="mycode"\ class="haskell\ numberLines"\ startFrom="100">
|
|
\ \ <code>
|
|
\ \ ...
|
|
\ \ </code>
|
|
</pre>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The \f[C]numberLines\f[] (or \f[C]number\-lines\f[]) class will cause
|
|
the lines of the code block to be numbered, starting with \f[C]1\f[] or
|
|
the value of the \f[C]startFrom\f[] attribute.
|
|
The \f[C]lineAnchors\f[] (or \f[C]line\-anchors\f[]) 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
|
|
.nf
|
|
\f[C]
|
|
```haskell
|
|
qsort\ []\ =\ []
|
|
```
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This is equivalent to:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
```\ {.haskell}
|
|
qsort\ []\ =\ []
|
|
```
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If the \f[C]fenced_code_attributes\f[] 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[C]\-\-no\-highlight\f[] flag.
|
|
To set the highlighting style, use \f[C]\-\-highlight\-style\f[].
|
|
For more information on highlighting, see Syntax highlighting, below.
|
|
.SS Line blocks
|
|
.SS Extension: \f[C]line_blocks\f[]
|
|
.PP
|
|
A line block is a sequence of lines beginning with a vertical bar
|
|
(\f[C]|\f[]) 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
|
|
.nf
|
|
\f[C]
|
|
|\ The\ limerick\ packs\ laughs\ anatomical
|
|
|\ In\ space\ that\ is\ quite\ economical.
|
|
|\ \ \ \ But\ the\ good\ ones\ I\[aq]ve\ seen
|
|
|\ \ \ \ So\ seldom\ are\ clean
|
|
|\ And\ the\ clean\ ones\ so\ seldom\ are\ comical
|
|
|
|
|\ 200\ Main\ St.
|
|
|\ Berkeley,\ CA\ 94718
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The lines can be hard\-wrapped if needed, but the continuation line must
|
|
begin with a space.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
|\ The\ Right\ Honorable\ Most\ Venerable\ and\ Righteous\ Samuel\ L.
|
|
\ \ Constable,\ Jr.
|
|
|\ 200\ Main\ St.
|
|
|\ Berkeley,\ CA\ 94718
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This syntax is borrowed from reStructuredText.
|
|
.SS Lists
|
|
.SS Bullet lists
|
|
.PP
|
|
A bullet list is a list of bulleted list items.
|
|
A bulleted list item begins with a bullet (\f[C]*\f[], \f[C]+\f[], or
|
|
\f[C]\-\f[]).
|
|
Here is a simple example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
*\ one
|
|
*\ two
|
|
*\ three
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This will produce a "compact" list.
|
|
If you want a "loose" list, in which each item is formatted as a
|
|
paragraph, put spaces between the items:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
*\ one
|
|
|
|
*\ two
|
|
|
|
*\ three
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
*\ here\ is\ my\ first
|
|
\ \ list\ item.
|
|
*\ and\ my\ second.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
But Markdown also allows a "lazy" format:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
*\ here\ is\ my\ first
|
|
list\ item.
|
|
*\ and\ my\ second.
|
|
\f[]
|
|
.fi
|
|
.SS Block content in list items
|
|
.PP
|
|
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
|
|
.nf
|
|
\f[C]
|
|
\ \ *\ First\ paragraph.
|
|
|
|
\ \ \ \ Continued.
|
|
|
|
\ \ *\ Second\ paragraph.\ With\ a\ code\ block,\ which\ must\ be\ indented
|
|
\ \ \ \ eight\ spaces:
|
|
|
|
\ \ \ \ \ \ \ \ {\ code\ }
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
*\ \ \ \ \ code
|
|
|
|
\ \ continuation\ paragraph
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
*\ fruits
|
|
\ \ +\ apples
|
|
\ \ \ \ \-\ macintosh
|
|
\ \ \ \ \-\ red\ delicious
|
|
\ \ +\ pears
|
|
\ \ +\ peaches
|
|
*\ vegetables
|
|
\ \ +\ broccoli
|
|
\ \ +\ chard
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
As noted above, Markdown allows you to write list items "lazily,"
|
|
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
|
|
.nf
|
|
\f[C]
|
|
+\ A\ lazy,\ lazy,\ list
|
|
item.
|
|
|
|
+\ Another\ one;\ this\ looks
|
|
bad\ but\ is\ legal.
|
|
|
|
\ \ \ \ Second\ paragraph\ of\ second
|
|
list\ item.
|
|
\f[]
|
|
.fi
|
|
.SS Ordered lists
|
|
.PP
|
|
Ordered lists work just like bulleted lists, except that the items begin
|
|
with enumerators rather than bullets.
|
|
.PP
|
|
In standard 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
|
|
.nf
|
|
\f[C]
|
|
1.\ \ one
|
|
2.\ \ two
|
|
3.\ \ three
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
and this one:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
5.\ \ one
|
|
7.\ \ two
|
|
1.\ \ three
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]fancy_lists\f[]
|
|
.PP
|
|
Unlike standard 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\-parentheses 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[C]fancy_lists\f[] extension also allows \[aq]\f[C]#\f[]\[aq] to
|
|
be used as an ordered list marker in place of a numeral:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#.\ one
|
|
#.\ two
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]startnum\f[]
|
|
.PP
|
|
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
|
|
.nf
|
|
\f[C]
|
|
\ 9)\ \ Ninth
|
|
10)\ \ Tenth
|
|
11)\ \ Eleventh
|
|
\ \ \ \ \ \ \ i.\ subone
|
|
\ \ \ \ \ \ ii.\ subtwo
|
|
\ \ \ \ \ iii.\ subthree
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
(2)\ Two
|
|
(5)\ Three
|
|
1.\ \ Four
|
|
*\ \ \ Five
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If default list markers are desired, use \f[C]#.\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#.\ \ one
|
|
#.\ \ two
|
|
#.\ \ three
|
|
\f[]
|
|
.fi
|
|
.SS Definition lists
|
|
.SS Extension: \f[C]definition_lists\f[]
|
|
.PP
|
|
Pandoc supports definition lists, using the syntax of PHP Markdown Extra
|
|
with some extensions.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Term\ 1
|
|
|
|
:\ \ \ Definition\ 1
|
|
|
|
Term\ 2\ with\ *inline\ markup*
|
|
|
|
:\ \ \ Definition\ 2
|
|
|
|
\ \ \ \ \ \ \ \ {\ some\ code,\ part\ of\ Definition\ 2\ }
|
|
|
|
\ \ \ \ Third\ paragraph\ of\ definition\ 2.
|
|
\f[]
|
|
.fi
|
|
.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 block elements (paragraph, code block, list, etc.), each
|
|
indented four spaces or one tab stop.
|
|
The body of the definition (including the first line, aside from the
|
|
colon or tilde) should be indented four spaces.
|
|
However, as with other Markdown lists, you can "lazily" omit indentation
|
|
except at the beginning of a paragraph or other block element:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Term\ 1
|
|
|
|
:\ \ \ Definition
|
|
with\ lazy\ continuation.
|
|
|
|
\ \ \ \ Second\ paragraph\ of\ the\ definition.
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
Term\ 1
|
|
\ \ ~\ Definition\ 1
|
|
|
|
Term\ 2
|
|
\ \ ~\ Definition\ 2a
|
|
\ \ ~\ Definition\ 2b
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note that space between items in a definition list is required.
|
|
(A variant that loosens this requirement, but disallows "lazy" hard
|
|
wrapping, can be activated with \f[C]compact_definition_lists\f[]: see
|
|
Non\-pandoc extensions, below.)
|
|
.SS Numbered example lists
|
|
.SS Extension: \f[C]example_lists\f[]
|
|
.PP
|
|
The special list marker \f[C]\@\f[] can be used for sequentially
|
|
numbered examples.
|
|
The first list item with a \f[C]\@\f[] marker will be numbered
|
|
\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
|
|
The numbered examples need not occur in a single list; each new list
|
|
using \f[C]\@\f[] will take up where the last stopped.
|
|
So, for example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
(\@)\ \ My\ first\ example\ will\ be\ numbered\ (1).
|
|
(\@)\ \ My\ second\ example\ will\ be\ numbered\ (2).
|
|
|
|
Explanation\ of\ examples.
|
|
|
|
(\@)\ \ My\ third\ example\ will\ be\ numbered\ (3).
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Numbered examples can be labeled and referred to elsewhere in the
|
|
document:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
(\@good)\ \ This\ is\ a\ good\ example.
|
|
|
|
As\ (\@good)\ illustrates,\ ...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The label can be any string of alphanumeric characters, underscores, or
|
|
hyphens.
|
|
.PP
|
|
Note: 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[C]four_space_rule\f[]
|
|
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.
|
|
.SS Compact and loose lists
|
|
.PP
|
|
Pandoc behaves differently from \f[C]Markdown.pl\f[] on some "edge
|
|
cases" involving lists.
|
|
Consider this source:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
+\ \ \ First
|
|
+\ \ \ Second:
|
|
\ \ \ \ \-\ \ \ Fee
|
|
\ \ \ \ \-\ \ \ Fie
|
|
\ \ \ \ \-\ \ \ Foe
|
|
|
|
+\ \ \ Third
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Pandoc transforms this into a "compact list" (with no \f[C]<p>\f[] tags
|
|
around "First", "Second", or "Third"), while Markdown puts \f[C]<p>\f[]
|
|
tags around "Second" and "Third" (but not "First"), because of the blank
|
|
space around "Third".
|
|
Pandoc follows a simple rule: if the text is followed by a blank line,
|
|
it is treated as a paragraph.
|
|
Since "Second" is followed by a list, and not a blank line, it isn\[aq]t
|
|
treated as a paragraph.
|
|
The fact that the list is followed by a blank line is irrelevant.
|
|
(Note: Pandoc works this way even when the \f[C]markdown_strict\f[]
|
|
format is specified.
|
|
This behavior is consistent with the official Markdown syntax
|
|
description, even though it is different from that of
|
|
\f[C]Markdown.pl\f[].)
|
|
.SS Ending a list
|
|
.PP
|
|
What if you want to put an indented code block after a list?
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\ \ \ item\ one
|
|
\-\ \ \ item\ two
|
|
|
|
\ \ \ \ {\ my\ code\ block\ }
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Trouble! Here pandoc (like other Markdown implementations) will treat
|
|
\f[C]{\ my\ code\ block\ }\f[] as the second paragraph of item two, and
|
|
not as a code block.
|
|
.PP
|
|
To "cut off" the list after item two, you can insert some non\-indented
|
|
content, like an HTML comment, which won\[aq]t produce visible output in
|
|
any format:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\ \ \ item\ one
|
|
\-\ \ \ item\ two
|
|
|
|
<!\-\-\ end\ of\ list\ \-\->
|
|
|
|
\ \ \ \ {\ my\ code\ block\ }
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
You can use the same trick if you want two consecutive lists instead of
|
|
one big list:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
1.\ \ one
|
|
2.\ \ two
|
|
3.\ \ three
|
|
|
|
<!\-\-\ \-\->
|
|
|
|
1.\ \ uno
|
|
2.\ \ dos
|
|
3.\ \ tres
|
|
\f[]
|
|
.fi
|
|
.SS Horizontal rules
|
|
.PP
|
|
A line containing a row of three or more \f[C]*\f[], \f[C]\-\f[], or
|
|
\f[C]_\f[] characters (optionally separated by spaces) produces a
|
|
horizontal rule:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
*\ \ *\ \ *\ \ *
|
|
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\f[]
|
|
.fi
|
|
.SS Tables
|
|
.PP
|
|
Four kinds of tables may be used.
|
|
The first three kinds presuppose the use of a fixed\-width font, such as
|
|
Courier.
|
|
The fourth kind can be used with proportionally spaced fonts, as it does
|
|
not require lining up columns.
|
|
.SS Extension: \f[C]table_captions\f[]
|
|
.PP
|
|
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[C]Table:\f[] (or
|
|
just \f[C]:\f[]), which will be stripped off.
|
|
It may appear either before or after the table.
|
|
.SS Extension: \f[C]simple_tables\f[]
|
|
.PP
|
|
Simple tables look like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default
|
|
\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\-
|
|
\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12
|
|
\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123
|
|
\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1
|
|
|
|
Table:\ \ Demonstration\ of\ simple\ table\ syntax.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The headers 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 headers may be omitted, provided a dashed line is used to end
|
|
the table.
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\-
|
|
\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12
|
|
\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123
|
|
\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1
|
|
\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\-
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
When headers are 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[C]multiline_tables\f[]
|
|
.PP
|
|
Multiline tables allow headers 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
|
|
.nf
|
|
\f[C]
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ 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\[aq]s\ another\ one.\ Note
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|
|
Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span
|
|
multiple\ lines.
|
|
\f[]
|
|
.fi
|
|
.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
|
|
headers are 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
|
|
Headers may be omitted in multiline tables as well as simple tables:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
|
|
|
|
\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
|
|
\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|
|
:\ Here\[aq]s\ a\ multiline\ table\ without\ headers.
|
|
\f[]
|
|
.fi
|
|
.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[C]grid_tables\f[]
|
|
.PP
|
|
Grid tables look like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
:\ Sample\ grid\ table.
|
|
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
|\ Fruit\ \ \ \ \ \ \ \ \ |\ Price\ \ \ \ \ \ \ \ \ |\ Advantages\ \ \ \ \ \ \ \ \ |
|
|
+===============+===============+====================+
|
|
|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ \-\ built\-in\ wrapper\ |
|
|
|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \-\ bright\ color\ \ \ \ \ |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
|\ Oranges\ \ \ \ \ \ \ |\ $2.10\ \ \ \ \ \ \ \ \ |\ \-\ cures\ scurvy\ \ \ \ \ |
|
|
|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \-\ tasty\ \ \ \ \ \ \ \ \ \ \ \ |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The row of \f[C]=\f[]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.).
|
|
Cells that span multiple columns or rows are not supported.
|
|
Grid tables can be created easily using Emacs table mode.
|
|
.PP
|
|
Alignments can be specified as with pipe tables, by putting colons at
|
|
the boundaries of the separator line after the header:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
|\ Right\ \ \ \ \ \ \ \ \ |\ Left\ \ \ \ \ \ \ \ \ \ |\ Centered\ \ \ \ \ \ \ \ \ \ \ |
|
|
+==============:+:==============+:==================:+
|
|
|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ built\-in\ wrapper\ \ \ |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
For headerless tables, the colons go on the top line instead:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-+:\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-:+
|
|
|\ Right\ \ \ \ \ \ \ \ \ |\ Left\ \ \ \ \ \ \ \ \ \ |\ Centered\ \ \ \ \ \ \ \ \ \ \ |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
\f[]
|
|
.fi
|
|
.SS Grid Table Limitations
|
|
.PP
|
|
Pandoc does not support grid tables with row spans or column spans.
|
|
This means that neither variable numbers of columns across rows nor
|
|
variable numbers of rows across columns are supported by Pandoc.
|
|
All grid tables must have the same number of columns in each row, and
|
|
the same number of rows in each column.
|
|
For example, the Docutils sample grid tables will not render as expected
|
|
with Pandoc.
|
|
.SS Extension: \f[C]pipe_tables\f[]
|
|
.PP
|
|
Pipe tables look like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
|\ Right\ |\ Left\ |\ Default\ |\ Center\ |
|
|
|\-\-\-\-\-\-:|:\-\-\-\-\-|\-\-\-\-\-\-\-\-\-|:\-\-\-\-\-\-:|
|
|
|\ \ \ 12\ \ |\ \ 12\ \ |\ \ \ \ 12\ \ \ |\ \ \ \ 12\ \ |
|
|
|\ \ 123\ \ |\ \ 123\ |\ \ \ 123\ \ \ |\ \ \ 123\ \ |
|
|
|\ \ \ \ 1\ \ |\ \ \ \ 1\ |\ \ \ \ \ 1\ \ \ |\ \ \ \ \ 1\ \ |
|
|
|
|
\ \ :\ Demonstration\ of\ pipe\ table\ syntax.
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
fruit|\ price
|
|
\-\-\-\-\-|\-\-\-\-\-:
|
|
apple|2.05
|
|
pear|1.37
|
|
orange|3.09
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The cells of pipe tables cannot contain block elements like paragraphs
|
|
and lists, and cannot span multiple lines.
|
|
If a pipe table contains a row whose printable content is wider than the
|
|
column width (see \f[C]\-\-columns\f[]), 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[C]\-\-\-|\-\f[] 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\[aq] orgtbl\-mode:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
|\ One\ |\ Two\ \ \ |
|
|
|\-\-\-\-\-+\-\-\-\-\-\-\-|
|
|
|\ my\ \ |\ table\ |
|
|
|\ is\ \ |\ nice\ \ |
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The difference is that \f[C]+\f[] is used instead of \f[C]|\f[].
|
|
Other orgtbl features are not supported.
|
|
In particular, to get non\-default column alignment, you\[aq]ll need to
|
|
add colons as above.
|
|
.SS Metadata blocks
|
|
.SS Extension: \f[C]pandoc_title_block\f[]
|
|
.PP
|
|
If the file begins with a title block
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
%\ title
|
|
%\ author(s)\ (separated\ by\ semicolons)
|
|
%\ date
|
|
\f[]
|
|
.fi
|
|
.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 title 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
|
|
.nf
|
|
\f[C]
|
|
%
|
|
%\ Author
|
|
|
|
%\ My\ title
|
|
%
|
|
%\ June\ 15,\ 2006
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The title may occupy multiple lines, but continuation lines must begin
|
|
with leading space, thus:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
%\ My\ title
|
|
\ \ on\ multiple\ lines
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
%\ Author\ One
|
|
\ \ Author\ Two
|
|
|
|
%\ Author\ One;\ Author\ Two
|
|
|
|
%\ Author\ One;
|
|
\ \ Author\ Two
|
|
\f[]
|
|
.fi
|
|
.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[C]\-\-standalone\f[] (\f[C]\-s\f[]) option is chosen.
|
|
In HTML output, titles will appear twice: once in the document head \-\-
|
|
this is the title that will appear at the top of the window in a browser
|
|
\-\- and once at the beginning of the document body.
|
|
The title in the document head can have an optional prefix attached
|
|
(\f[C]\-\-title\-prefix\f[] or \f[C]\-T\f[] option).
|
|
The title in the body appears as an H1 element with class "title", so it
|
|
can be suppressed or reformatted with CSS.
|
|
If a title prefix is specified with \f[C]\-T\f[] 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[C]|\f[]) should be used to separate the
|
|
footer text from the header text.
|
|
Thus,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
%\ PANDOC(1)
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
will yield a man page with the title \f[C]PANDOC\f[] and section 1.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
%\ PANDOC(1)\ Pandoc\ User\ Manuals
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
will also have "Pandoc User Manuals" in the footer.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
will also have "Version 4.0" in the header.
|
|
.SS Extension: \f[C]yaml_metadata_block\f[]
|
|
.PP
|
|
A YAML metadata block is a valid YAML object, delimited by a line of
|
|
three hyphens (\f[C]\-\-\-\f[]) at the top and a line of three hyphens
|
|
(\f[C]\-\-\-\f[]) or three dots (\f[C]\&...\f[]) at the bottom.
|
|
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, 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
|
|
.nf
|
|
\f[C]
|
|
pandoc\ chap1.md\ chap2.md\ chap3.md\ metadata.yaml\ \-s\ \-o\ book.html
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Just be sure that the YAML file begins with \f[C]\-\-\-\f[] and ends
|
|
with \f[C]\-\-\-\f[] or \f[C]\&...\f[].) Alternatively, you can use the
|
|
\f[C]\-\-metadata\-file\f[] 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[C]yes\f[], \f[C]True\f[], and \f[C]15\f[] cannot be used as field
|
|
names).
|
|
.PP
|
|
A document may contain multiple metadata blocks.
|
|
The metadata fields will be combined through a \f[I]left\-biased
|
|
union\f[]: if two metadata blocks attempt to set the same field, the
|
|
value from the first block will be taken.
|
|
.PP
|
|
When pandoc is used with \f[C]\-t\ markdown\f[] to create a Markdown
|
|
document, a YAML metadata block will be produced only if the
|
|
\f[C]\-s/\-\-standalone\f[] 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.
|
|
The pipe character (\f[C]|\f[]) 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
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
title:\ \ \[aq]This\ 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.
|
|
\&...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Template variables will be set automatically from the metadata.
|
|
Thus, for example, in writing HTML, the variable \f[C]abstract\f[] will
|
|
be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[]
|
|
field:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<p>This\ is\ the\ abstract.</p>
|
|
<p>It\ consists\ of\ two\ paragraphs.</p>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Variables can contain arbitrary YAML structures, but the template must
|
|
match this structure.
|
|
The \f[C]author\f[] 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
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
title:\ The\ document\ title
|
|
author:
|
|
\-\ name:\ Author\ One
|
|
\ \ affiliation:\ University\ of\ Somewhere
|
|
\-\ name:\ Author\ Two
|
|
\ \ affiliation:\ University\ of\ Nowhere
|
|
\&...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
To use the structured authors in the example above, you would need a
|
|
custom template:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$for(author)$
|
|
$if(author.name)$
|
|
$author.name$$if(author.affiliation)$\ ($author.affiliation$)$endif$
|
|
$else$
|
|
$author$
|
|
$endif$
|
|
$endfor$
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Raw content to include in the document\[aq]s header may be specified
|
|
using \f[C]header\-includes\f[]; however, it is important to mark up
|
|
this content as raw code for a particular output format, using the
|
|
\f[C]raw_attribute\f[] extension), or it will be interpreted as
|
|
markdown.
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
header\-includes:
|
|
\-\ |
|
|
\ \ ```{=latex}
|
|
\ \ \\let\\oldsection\\section
|
|
\ \ \\renewcommand{\\section}[1]{\\clearpage\\oldsection{#1}}
|
|
\ \ ```
|
|
\f[]
|
|
.fi
|
|
.SS Backslash escapes
|
|
.SS Extension: \f[C]all_symbols_escapable\f[]
|
|
.PP
|
|
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
|
|
.nf
|
|
\f[C]
|
|
*\\*hello\\**
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
one will get
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<em>*hello*</em>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
instead of
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<strong>hello</strong>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This rule is easier to remember than standard Markdown\[aq]s rule, which
|
|
allows only the following characters to be backslash\-escaped:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\\`*_{}[]()>#+\-.!
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
(However, if the \f[C]markdown_strict\f[] format is used, the standard
|
|
Markdown rule will be used.)
|
|
.PP
|
|
A backslash\-escaped space is parsed as a nonbreaking space.
|
|
It will appear in TeX output as \f[C]~\f[] and in HTML and XML as
|
|
\f[C]\\ \f[] or \f[C]\\ \f[].
|
|
.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[C]\\\\\f[] and in HTML as
|
|
\f[C]<br\ />\f[].
|
|
This is a nice alternative to Markdown\[aq]s "invisible" 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
|
|
.PP
|
|
To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or
|
|
\f[C]_\f[], like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this
|
|
is\ *emphasized\ with\ asterisks*.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
This\ is\ **strong\ emphasis**\ and\ __with\ underscores__.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or
|
|
backslash\-escaped, will not trigger emphasis:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*.
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]intraword_underscores\f[]
|
|
.PP
|
|
Because \f[C]_\f[] is sometimes used inside words and identifiers,
|
|
pandoc does not interpret a \f[C]_\f[] surrounded by alphanumeric
|
|
characters as an emphasis marker.
|
|
If you want to emphasize just part of a word, use \f[C]*\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
feas*ible*,\ not\ feas*able*.
|
|
\f[]
|
|
.fi
|
|
.SS Strikeout
|
|
.SS Extension: \f[C]strikeout\f[]
|
|
.PP
|
|
To strikeout a section of text with a horizontal line, begin and end it
|
|
with \f[C]~~\f[].
|
|
Thus, for example,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
This\ ~~is\ deleted\ text.~~
|
|
\f[]
|
|
.fi
|
|
.SS Superscripts and subscripts
|
|
.SS Extension: \f[C]superscript\f[], \f[C]subscript\f[]
|
|
.PP
|
|
Superscripts may be written by surrounding the superscripted text by
|
|
\f[C]^\f[] characters; subscripts may be written by surrounding the
|
|
subscripted text by \f[C]~\f[] characters.
|
|
Thus, for example,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
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[C]~\f[] and \f[C]^\f[].) Thus, if you want the
|
|
letter P with \[aq]a cat\[aq] in subscripts, use \f[C]P~a\\\ cat~\f[],
|
|
not \f[C]P~a\ cat~\f[].
|
|
.SS Verbatim
|
|
.PP
|
|
To make a short span of text verbatim, put it inside backticks:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
What\ is\ the\ difference\ between\ `>>=`\ and\ `>>`?
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If the verbatim text includes a backtick, use double backticks:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Here\ is\ a\ literal\ backtick\ ``\ `\ ``.
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ `\\*`.
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]inline_code_attributes\f[]
|
|
.PP
|
|
Attributes can be attached to verbatim text, just as with fenced code
|
|
blocks:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
`<$>`{.haskell}
|
|
\f[]
|
|
.fi
|
|
.SS Small caps
|
|
.PP
|
|
To write small caps, use the \f[C]smallcaps\f[] class:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[Small\ caps]{.smallcaps}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Or, without the \f[C]bracketed_spans\f[] extension:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<span\ class="smallcaps">Small\ caps</span>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
For compatibility with other Markdown flavors, CSS is also supported:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<span\ style="font\-variant:small\-caps;">Small\ caps</span>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This will work in all output formats that support small caps.
|
|
.SS Math
|
|
.SS Extension: \f[C]tex_math_dollars\f[]
|
|
.PP
|
|
Anything between two \f[C]$\f[] characters will be treated as TeX math.
|
|
The opening \f[C]$\f[] must have a non\-space character immediately to
|
|
its right, while the closing \f[C]$\f[] must have a non\-space character
|
|
immediately to its left, and must not be followed immediately by a
|
|
digit.
|
|
Thus, \f[C]$20,000\ and\ $30,000\f[] won\[aq]t parse as math.
|
|
If for some reason you need to enclose text in literal \f[C]$\f[]
|
|
characters, backslash\-escape them and they won\[aq]t be treated as math
|
|
delimiters.
|
|
.PP
|
|
TeX math will be printed in all output formats.
|
|
How it is rendered depends on the output format:
|
|
.TP
|
|
.B LaTeX
|
|
It will appear verbatim surrounded by \f[C]\\(...\\)\f[] (for inline
|
|
math) or \f[C]\\[...\\]\f[] (for display math).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B Markdown, Emacs Org mode, ConTeXt, ZimWiki
|
|
It will appear verbatim surrounded by \f[C]$...$\f[] (for inline math)
|
|
or \f[C]$$...$$\f[] (for display math).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B reStructuredText
|
|
It will be rendered using an interpreted text role \f[C]:math:\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B AsciiDoc
|
|
It will be rendered as \f[C]latexmath:[...]\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B Texinfo
|
|
It will be rendered inside a \f[C]\@math\f[] command.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B groff man
|
|
It will be rendered verbatim without \f[C]$\f[]\[aq]s.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B MediaWiki, DokuWiki
|
|
It will be rendered inside \f[C]<math>\f[] tags.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B Textile
|
|
It will be rendered inside \f[C]<span\ class="math">\f[] tags.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B RTF, OpenDocument
|
|
It will be rendered, if possible, using Unicode characters, and will
|
|
otherwise appear verbatim.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B ODT
|
|
It will be rendered, if possible, using MathML.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B DocBook
|
|
If the \f[C]\-\-mathml\f[] flag is used, it will be rendered using
|
|
MathML in an \f[C]inlineequation\f[] or \f[C]informalequation\f[] tag.
|
|
Otherwise it will be rendered, if possible, using Unicode characters.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B Docx
|
|
It will be rendered using OMML math markup.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B FictionBook2
|
|
If the \f[C]\-\-webtex\f[] 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.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B 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.
|
|
.RS
|
|
.RE
|
|
.SS Raw HTML
|
|
.SS Extension: \f[C]raw_html\f[]
|
|
.PP
|
|
Markdown allows you to insert raw HTML (or DocBook) anywhere in a
|
|
document (except verbatim contexts, where \f[C]<\f[], \f[C]>\f[], and
|
|
\f[C]&\f[] 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, Emacs Org mode, and Textile output, and
|
|
suppressed in other formats.
|
|
.SS Extension: \f[C]markdown_in_html_blocks\f[]
|
|
.PP
|
|
Standard Markdown allows you to include HTML "blocks": 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[C]*\f[] does not signify emphasis.
|
|
.PP
|
|
Pandoc behaves this way when the \f[C]markdown_strict\f[] format is
|
|
used; but by default, pandoc interprets material between HTML block tags
|
|
as Markdown.
|
|
Thus, for example, pandoc will turn
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<table>
|
|
<tr>
|
|
<td>*one*</td>
|
|
<td>[a\ link](http://google.com)</td>
|
|
</tr>
|
|
</table>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
into
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<table>
|
|
<tr>
|
|
<td><em>one</em></td>
|
|
<td><a\ href="http://google.com">a\ link</a></td>
|
|
</tr>
|
|
</table>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
whereas \f[C]Markdown.pl\f[] will preserve it as is.
|
|
.PP
|
|
There is one exception to this rule: text between \f[C]<script>\f[] and
|
|
\f[C]<style>\f[] tags is not interpreted as Markdown.
|
|
.PP
|
|
This departure from standard Markdown should make it easier to mix
|
|
Markdown with HTML block elements.
|
|
For example, one can surround a block of Markdown text with
|
|
\f[C]<div>\f[] tags without preventing it from being interpreted as
|
|
Markdown.
|
|
.SS Extension: \f[C]native_divs\f[]
|
|
.PP
|
|
Use native pandoc \f[C]Div\f[] blocks for content inside \f[C]<div>\f[]
|
|
tags.
|
|
For the most part this should give the same output as
|
|
\f[C]markdown_in_html_blocks\f[], but it makes it easier to write pandoc
|
|
filters to manipulate groups of blocks.
|
|
.SS Extension: \f[C]native_spans\f[]
|
|
.PP
|
|
Use native pandoc \f[C]Span\f[] blocks for content inside
|
|
\f[C]<span>\f[] tags.
|
|
For the most part this should give the same output as \f[C]raw_html\f[],
|
|
but it makes it easier to write pandoc filters to manipulate groups of
|
|
inlines.
|
|
.SS Extension: \f[C]raw_tex\f[]
|
|
.PP
|
|
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
|
|
.nf
|
|
\f[C]
|
|
This\ result\ was\ proved\ in\ \\cite{jones.1967}.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note that in LaTeX environments, like
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\\begin{tabular}{|l|l|}\\hline
|
|
Age\ &\ Frequency\ \\\\\ \\hline
|
|
18\-\-25\ \ &\ 15\ \\\\
|
|
26\-\-35\ \ &\ 33\ \\\\
|
|
36\-\-45\ \ &\ 22\ \\\\\ \\hline
|
|
\\end{tabular}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
the material between the begin and end tags will be interpreted as raw
|
|
LaTeX, not as Markdown.
|
|
.PP
|
|
Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
|
|
Emacs Org mode, and ConTeXt.
|
|
.SS Generic raw attribute
|
|
.SS Extension: \f[C]raw_attribute\f[]
|
|
.PP
|
|
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 groff \f[C]ms\f[] block:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
```{=ms}
|
|
\&.MYMACRO
|
|
blah\ blah
|
|
```
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
And the following produces a raw \f[C]html\f[] inline element:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
This\ is\ `<a>html</a>`{=html}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
This can be useful to insert raw xml into \f[C]docx\f[] documents, e.g.
|
|
a pagebreak:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
```{=openxml}
|
|
<w:p>
|
|
\ \ <w:r>
|
|
\ \ \ \ <w:br\ w:type="page"/>
|
|
\ \ </w:r>
|
|
</w:p>
|
|
```
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The format name should match the target format name (see
|
|
\f[C]\-t/\-\-to\f[], above, for a list, or use
|
|
\f[C]pandoc\ \-\-list\-output\-formats\f[]).
|
|
Use \f[C]openxml\f[] for \f[C]docx\f[] output, \f[C]opendocument\f[] for
|
|
\f[C]odt\f[] output, \f[C]html5\f[] for \f[C]epub3\f[] output,
|
|
\f[C]html4\f[] for \f[C]epub2\f[] output, and \f[C]latex\f[],
|
|
\f[C]beamer\f[], \f[C]ms\f[], or \f[C]html5\f[] for \f[C]pdf\f[] output
|
|
(depending on what you use for \f[C]\-\-pdf\-engine\f[]).
|
|
.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[C]backtick_code_blocks\f[] must be enabled.
|
|
.PP
|
|
The raw attribute cannot be combined with regular attributes.
|
|
.SS LaTeX macros
|
|
.SS Extension: \f[C]latex_macros\f[]
|
|
.PP
|
|
For output formats other than LaTeX, 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
|
|
.nf
|
|
\f[C]
|
|
\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle}
|
|
|
|
$\\tuple{a,\ b,\ c}$
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note that LaTeX macros will not be applied if they occur inside inside a
|
|
raw span or block marked with the \f[C]raw_attribute\f[] extension.
|
|
.PP
|
|
When \f[C]latex_macros\f[] 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
|
|
Whether or not \f[C]latex_macros\f[] is enabled, the macro definitions
|
|
will still be passed through as raw LaTeX.
|
|
.SS Links
|
|
.PP
|
|
Markdown allows links to be specified in several ways.
|
|
.SS Automatic links
|
|
.PP
|
|
If you enclose a URL or email address in pointy brackets, it will become
|
|
a link:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<http://google.com>
|
|
<sam\@green.eggs.ham>
|
|
\f[]
|
|
.fi
|
|
.SS Inline links
|
|
.PP
|
|
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
|
|
.nf
|
|
\f[C]
|
|
This\ is\ an\ [inline\ link](/url),\ and\ here\[aq]s\ [one\ with
|
|
a\ title](http://fsf.org\ "click\ here\ for\ a\ good\ time!").
|
|
\f[]
|
|
.fi
|
|
.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[C]mailto\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[Write\ me!](mailto:sam\@green.eggs.ham)
|
|
\f[]
|
|
.fi
|
|
.SS Reference links
|
|
.PP
|
|
An \f[I]explicit\f[] 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[C]spaced_reference_links\f[] extension is enabled.) 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[C]citations\f[] extension is enabled): citations take precedence over
|
|
link labels.
|
|
.PP
|
|
Here are some examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[my\ label\ 1]:\ /foo/bar.html\ \ "My\ title,\ optional"
|
|
[my\ label\ 2]:\ /foo
|
|
[my\ label\ 3]:\ http://fsf.org\ (The\ free\ software\ foundation)
|
|
[my\ label\ 4]:\ /bar#special\ \ \[aq]A\ title\ in\ single\ quotes\[aq]
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The URL may optionally be surrounded by angle brackets:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[my\ label\ 5]:\ <http://foo.bar.baz>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The title may go on the next line:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[my\ label\ 3]:\ http://fsf.org
|
|
\ \ "The\ free\ software\ foundation"
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note that link labels are not case sensitive.
|
|
So, this will work:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Here\ is\ [my\ link][FOO]
|
|
|
|
[Foo]:\ /bar/baz
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
In an \f[I]implicit\f[] reference link, the second pair of brackets is
|
|
empty:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
See\ [my\ website][].
|
|
|
|
[my\ website]:\ http://foo.bar.baz
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note: In \f[C]Markdown.pl\f[] and most other 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 most other
|
|
implementations:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
>\ My\ block\ [quote].
|
|
>
|
|
>\ [quote]:\ /foo
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]shortcut_reference_links\f[]
|
|
.PP
|
|
In a \f[I]shortcut\f[] reference link, the second pair of brackets may
|
|
be omitted entirely:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
See\ [my\ website].
|
|
|
|
[my\ website]:\ http://foo.bar.baz
|
|
\f[]
|
|
.fi
|
|
.SS Internal links
|
|
.PP
|
|
To link to another section of the same document, use the automatically
|
|
generated identifier (see Header identifiers).
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
See\ the\ [Introduction](#introduction).
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
See\ the\ [Introduction].
|
|
|
|
[Introduction]:\ #introduction
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Internal links are currently supported for HTML formats (including HTML
|
|
slide shows and EPUB), LaTeX, and ConTeXt.
|
|
.SS Images
|
|
.PP
|
|
A link immediately preceded by a \f[C]!\f[] will be treated as an image.
|
|
The link text will be used as the image\[aq]s alt text:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
|
|
|
|
![movie\ reel]
|
|
|
|
[movie\ reel]:\ movie.gif
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]implicit_figures\f[]
|
|
.PP
|
|
An image with nonempty alt text, occurring by itself in a paragraph,
|
|
will be rendered as a figure with a caption.
|
|
The image\[aq]s alt text will be used as the caption.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
|
|
\f[]
|
|
.fi
|
|
.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\[aq]ll 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
|
|
.nf
|
|
\f[C]
|
|
![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note that in reveal.js slide shows, an image in a paragraph by itself
|
|
that has the \f[C]stretch\f[] class will fill the screen, and the
|
|
caption and figure tags will be omitted.
|
|
.SS Extension: \f[C]link_attributes\f[]
|
|
.PP
|
|
Attributes can be set on links and images:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
An\ inline\ {#id\ .class\ width=30\ height=20px}
|
|
and\ a\ reference\ ![image][ref]\ with\ attributes.
|
|
|
|
[ref]:\ foo.jpg\ "optional\ title"\ {#id\ .class\ key=val\ key2="val\ 2"}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
(This syntax is compatible with PHP Markdown Extra when only
|
|
\f[C]#id\f[] and \f[C]\&.class\f[] are used.)
|
|
.PP
|
|
For HTML and EPUB, all attributes except \f[C]width\f[] and
|
|
\f[C]height\f[] (but including \f[C]srcset\f[] and \f[C]sizes\f[]) are
|
|
passed through as is.
|
|
The other writers ignore attributes that are not supported by their
|
|
output format.
|
|
.PP
|
|
The \f[C]width\f[] and \f[C]height\f[] 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[C]px\f[],
|
|
\f[C]cm\f[], \f[C]mm\f[], \f[C]in\f[], \f[C]inch\f[] and \f[C]%\f[].
|
|
There must not be any spaces between the number and the unit.
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
{\ width=50%\ }
|
|
\f[]
|
|
.fi
|
|
.IP \[bu] 2
|
|
Dimensions are converted to inches for output in page\-based formats
|
|
like LaTeX.
|
|
Dimensions are converted to pixels for output in HTML\-like formats.
|
|
Use the \f[C]\-\-dpi\f[] option to specify the number of pixels per
|
|
inch.
|
|
The default is 96dpi.
|
|
.IP \[bu] 2
|
|
The \f[C]%\f[] unit is generally relative to some available space.
|
|
For example the above example will render to
|
|
\f[C]<img\ href="file.jpg"\ style="width:\ 50%;"\ />\f[] (HTML),
|
|
\f[C]\\includegraphics[width=0.5\\textwidth]{file.jpg}\f[] (LaTeX), or
|
|
\f[C]\\externalfigure[file.jpg][width=0.5\\textwidth]\f[] (ConTeXt).
|
|
.IP \[bu] 2
|
|
Some output formats have a notion of a class (ConTeXt) or a unique
|
|
identifier (LaTeX \f[C]\\caption\f[]), or both (HTML).
|
|
.IP \[bu] 2
|
|
When no \f[C]width\f[] or \f[C]height\f[] 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
|
|
.PP
|
|
Using the \f[C]native_divs\f[] and \f[C]native_spans\f[] extensions (see
|
|
above), HTML syntax can be used as part of markdown to create native
|
|
\f[C]Div\f[] and \f[C]Span\f[] elements in the pandoc AST (as opposed to
|
|
raw HTML).
|
|
However, there is also nicer syntax available:
|
|
.SS Extension: \f[C]fenced_divs\f[]
|
|
.PP
|
|
Allow special fenced syntax for native \f[C]Div\f[] 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.
|
|
The attribute syntax is exactly as in fenced code blocks (see Extension:
|
|
\f[C]fenced_code_attributes\f[]).
|
|
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
|
|
.nf
|
|
\f[C]
|
|
:::::\ {#special\ .sidebar}
|
|
Here\ is\ a\ paragraph.
|
|
|
|
And\ another.
|
|
:::::
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Fenced divs can be nested.
|
|
Opening fences are distinguished because they \f[I]must\f[] have
|
|
attributes:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
:::\ Warning\ ::::::
|
|
This\ is\ a\ warning.
|
|
|
|
:::\ Danger
|
|
This\ is\ a\ warning\ within\ a\ warning.
|
|
:::
|
|
::::::::::::::::::
|
|
\f[]
|
|
.fi
|
|
.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[C]bracketed_spans\f[]
|
|
.PP
|
|
A bracketed sequence of inlines, as one would use to begin a link, will
|
|
be treated as a \f[C]Span\f[] with attributes if it is followed
|
|
immediately by attributes:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[This\ is\ *some\ text*]{.class\ key="val"}
|
|
\f[]
|
|
.fi
|
|
.SS Footnotes
|
|
.SS Extension: \f[C]footnotes\f[]
|
|
.PP
|
|
Pandoc\[aq]s Markdown allows footnotes, using the following syntax:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Here\ is\ a\ footnote\ reference,[^1]\ and\ another.[^longnote]
|
|
|
|
[^1]:\ Here\ is\ the\ footnote.
|
|
|
|
[^longnote]:\ Here\[aq]s\ 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\[aq]t\ be\ part\ of\ the\ note,\ because\ it
|
|
isn\[aq]t\ indented.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The identifiers in footnote references may not contain spaces, tabs, or
|
|
newlines.
|
|
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[C]inline_notes\f[]
|
|
.PP
|
|
Inline footnotes are also allowed (though, unlike regular notes, they
|
|
cannot contain multiple paragraphs).
|
|
The syntax is as follows:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Here\ is\ an\ inline\ note.^[Inlines\ notes\ are\ easier\ to\ write,\ since
|
|
you\ don\[aq]t\ have\ to\ pick\ an\ identifier\ and\ move\ down\ to\ type\ the
|
|
note.]
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Inline and regular footnotes may be mixed freely.
|
|
.SS Citations
|
|
.SS Extension: \f[C]citations\f[]
|
|
.PP
|
|
Using an external filter, \f[C]pandoc\-citeproc\f[], pandoc can
|
|
automatically generate citations and a bibliography in a number of
|
|
styles.
|
|
Basic usage is
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-\-filter\ pandoc\-citeproc\ myinput.txt
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
In order to use this feature, you will need to specify a bibliography
|
|
file using the \f[C]bibliography\f[] metadata field in a YAML metadata
|
|
section, or \f[C]\-\-bibliography\f[] command line argument.
|
|
You can supply multiple \f[C]\-\-bibliography\f[] arguments or set
|
|
\f[C]bibliography\f[] metadata field to YAML array, if you want to use
|
|
multiple bibliography files.
|
|
The bibliography may have any of these formats:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
Format
|
|
T}@T{
|
|
File extension
|
|
T}
|
|
_
|
|
T{
|
|
BibLaTeX
|
|
T}@T{
|
|
\&.bib
|
|
T}
|
|
T{
|
|
BibTeX
|
|
T}@T{
|
|
\&.bibtex
|
|
T}
|
|
T{
|
|
Copac
|
|
T}@T{
|
|
\&.copac
|
|
T}
|
|
T{
|
|
CSL JSON
|
|
T}@T{
|
|
\&.json
|
|
T}
|
|
T{
|
|
CSL YAML
|
|
T}@T{
|
|
\&.yaml
|
|
T}
|
|
T{
|
|
EndNote
|
|
T}@T{
|
|
\&.enl
|
|
T}
|
|
T{
|
|
EndNote XML
|
|
T}@T{
|
|
\&.xml
|
|
T}
|
|
T{
|
|
ISI
|
|
T}@T{
|
|
\&.wos
|
|
T}
|
|
T{
|
|
MEDLINE
|
|
T}@T{
|
|
\&.medline
|
|
T}
|
|
T{
|
|
MODS
|
|
T}@T{
|
|
\&.mods
|
|
T}
|
|
T{
|
|
RIS
|
|
T}@T{
|
|
\&.ris
|
|
T}
|
|
.TE
|
|
.PP
|
|
Note that \f[C]\&.bib\f[] can be used with both BibTeX and BibLaTeX
|
|
files; use \f[C]\&.bibtex\f[] to force BibTeX.
|
|
.PP
|
|
Note that \f[C]pandoc\-citeproc\ \-\-bib2json\f[] and
|
|
\f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce \f[C]\&.json\f[] and
|
|
\f[C]\&.yaml\f[] files from any of the supported formats.
|
|
.PP
|
|
In\-field markup: In BibTeX and BibLaTeX databases, pandoc\-citeproc
|
|
parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown;
|
|
and in CSL JSON databases, an HTML\-like markup:
|
|
.TP
|
|
.B \f[C]<i>...</i>\f[]
|
|
italics
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]<b>...</b>\f[]
|
|
bold
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]<span\ style="font\-variant:small\-caps;">...</span>\f[] or \f[C]<sc>...</sc>\f[]
|
|
small capitals
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]<sub>...</sub>\f[]
|
|
subscript
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]<sup>...</sup>\f[]
|
|
superscript
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]<span\ class="nocase">...</span>\f[]
|
|
prevent a phrase from being capitalized as title case
|
|
.RS
|
|
.RE
|
|
.PP
|
|
\f[C]pandoc\-citeproc\ \-j\f[] and \f[C]\-y\f[] interconvert the CSL
|
|
JSON and CSL YAML formats as far as possible.
|
|
.PP
|
|
As an alternative to specifying a bibliography file using
|
|
\f[C]\-\-bibliography\f[] or the YAML metadata field
|
|
\f[C]bibliography\f[], you can include the citation data directly in the
|
|
\f[C]references\f[] field of the document\[aq]s YAML metadata.
|
|
The field should contain an array of YAML\-encoded references, for
|
|
example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
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:\ \[aq]Molecular\ 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:\ http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
|
|
\ \ language:\ en\-GB
|
|
\&...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
(\f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce these from a
|
|
bibliography file in one of the supported formats.)
|
|
.PP
|
|
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[C]\-\-csl\f[] option or the
|
|
\f[C]csl\f[] metadata field.
|
|
By default, \f[C]pandoc\-citeproc\f[] will use the Chicago Manual of
|
|
Style author\-date format.
|
|
The CSL project provides further information on finding and editing
|
|
styles.
|
|
.PP
|
|
To make your citations hyperlinks to the corresponding bibliography
|
|
entries, add \f[C]link\-citations:\ true\f[] to your YAML metadata.
|
|
.PP
|
|
Citations go inside square brackets and are separated by semicolons.
|
|
Each citation must have a key, composed of \[aq]\@\[aq] + the citation
|
|
identifier from the database, and may optionally have a prefix, a
|
|
locator, and a suffix.
|
|
The citation key must begin with a letter, digit, or \f[C]_\f[], and may
|
|
contain alphanumerics, \f[C]_\f[], and internal punctuation characters
|
|
(\f[C]:.#$%&\-+?<>~/\f[]).
|
|
Here are some examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Blah\ blah\ [see\ \@doe99,\ pp.\ 33\-35;\ also\ \@smith04,\ chap.\ 1].
|
|
|
|
Blah\ blah\ [\@doe99,\ pp.\ 33\-35,\ 38\-39\ and\ *passim*].
|
|
|
|
Blah\ blah\ [\@smith04;\ \@doe99].
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
\f[C]pandoc\-citeproc\f[] detects locator terms in the CSL locale files.
|
|
Either abbreviated or unabbreviated forms are accepted.
|
|
In the \f[C]en\-US\f[] locale, locator terms can be written in either
|
|
singular or plural forms, as \f[C]book\f[], \f[C]bk.\f[]/\f[C]bks.\f[];
|
|
\f[C]chapter\f[], \f[C]chap.\f[]/\f[C]chaps.\f[]; \f[C]column\f[],
|
|
\f[C]col.\f[]/\f[C]cols.\f[]; \f[C]figure\f[],
|
|
\f[C]fig.\f[]/\f[C]figs.\f[]; \f[C]folio\f[],
|
|
\f[C]fol.\f[]/\f[C]fols.\f[]; \f[C]number\f[],
|
|
\f[C]no.\f[]/\f[C]nos.\f[]; \f[C]line\f[], \f[C]l.\f[]/\f[C]ll.\f[];
|
|
\f[C]note\f[], \f[C]n.\f[]/\f[C]nn.\f[]; \f[C]opus\f[],
|
|
\f[C]op.\f[]/\f[C]opp.\f[]; \f[C]page\f[], \f[C]p.\f[]/\f[C]pp.\f[];
|
|
\f[C]paragraph\f[], \f[C]para.\f[]/\f[C]paras.\f[]; \f[C]part\f[],
|
|
\f[C]pt.\f[]/\f[C]pts.\f[]; \f[C]section\f[],
|
|
\f[C]sec.\f[]/\f[C]secs.\f[]; \f[C]sub\ verbo\f[],
|
|
\f[C]s.v.\f[]/\f[C]s.vv.\f[]; \f[C]verse\f[], \f[C]v.\f[]/\f[C]vv.\f[];
|
|
\f[C]volume\f[], \f[C]vol.\f[]/\f[C]vols.\f[]; \f[C]¶\f[]/\f[C]¶¶\f[];
|
|
\f[C]§\f[]/\f[C]§§\f[].
|
|
If no locator term is used, "page" is assumed.
|
|
.PP
|
|
A minus sign (\f[C]\-\f[]) before the \f[C]\@\f[] will suppress mention
|
|
of the author in the citation.
|
|
This can be useful when the author is already mentioned in the text:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Smith\ says\ blah\ [\-\@smith04].
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
You can also write an in\-text citation, as follows:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\@smith04\ says\ blah.
|
|
|
|
\@smith04\ [p.\ 33]\ says\ blah.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If the style calls for a list of works cited, it will be placed at the
|
|
end of the document.
|
|
Normally, you will want to end your document with an appropriate header:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
last\ paragraph...
|
|
|
|
#\ References
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The bibliography will be inserted after this header.
|
|
Note that the \f[C]unnumbered\f[] class will be added to this header, so
|
|
that the section will not be numbered.
|
|
.PP
|
|
If you want to include items in the bibliography without actually citing
|
|
them in the body text, you can define a dummy \f[C]nocite\f[] metadata
|
|
field and put the citations there:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
nocite:\ |
|
|
\ \ \@item1,\ \@item2
|
|
\&...
|
|
|
|
\@item3
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
In this example, the document will contain a citation for \f[C]item3\f[]
|
|
only, but the bibliography will contain entries for \f[C]item1\f[],
|
|
\f[C]item2\f[], and \f[C]item3\f[].
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
nocite:\ |
|
|
\ \ \@*
|
|
\&...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
For LaTeX output, you can also use \f[C]natbib\f[] or \f[C]biblatex\f[]
|
|
to render the bibliography.
|
|
In order to do so, specify bibliography files as outlined above, and add
|
|
\f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] argument to \f[C]pandoc\f[]
|
|
invocation.
|
|
Bear in mind that bibliography files have to be in respective format
|
|
(either BibTeX or BibLaTeX).
|
|
.PP
|
|
For more information, see the pandoc\-citeproc man page.
|
|
.SS Non\-pandoc extensions
|
|
.PP
|
|
The following Markdown syntax extensions are not enabled by default in
|
|
pandoc, but may be enabled by adding \f[C]+EXTENSION\f[] to the format
|
|
name, where \f[C]EXTENSION\f[] is the name of the extension.
|
|
Thus, for example, \f[C]markdown+hard_line_breaks\f[] is Markdown with
|
|
hard line breaks.
|
|
.SS Extension: \f[C]old_dashes\f[]
|
|
.PP
|
|
Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
|
|
\f[C]\-\f[] before a numeral is an en\-dash, and \f[C]\-\-\f[] is an
|
|
em\-dash.
|
|
This option only has an effect if \f[C]smart\f[] is enabled.
|
|
It is selected automatically for \f[C]textile\f[] input.
|
|
.SS Extension: \f[C]angle_brackets_escapable\f[]
|
|
.PP
|
|
Allow \f[C]<\f[] and \f[C]>\f[] to be backslash\-escaped, as they can be
|
|
in GitHub flavored Markdown but not original Markdown.
|
|
This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[].
|
|
.SS Extension: \f[C]lists_without_preceding_blankline\f[]
|
|
.PP
|
|
Allow a list to occur right after a paragraph, with no intervening blank
|
|
space.
|
|
.SS Extension: \f[C]four_space_rule\f[]
|
|
.PP
|
|
Selects the pandoc <= 2.0 behavior for parsing lists, so that four
|
|
spaces indent are needed for list item continuation paragraphs.
|
|
.SS Extension: \f[C]spaced_reference_links\f[]
|
|
.PP
|
|
Allow whitespace between the two components of a reference link, for
|
|
example,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[foo]\ [bar].
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]hard_line_breaks\f[]
|
|
.PP
|
|
Causes all newlines within a paragraph to be interpreted as hard line
|
|
breaks instead of spaces.
|
|
.SS Extension: \f[C]ignore_line_breaks\f[]
|
|
.PP
|
|
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[C]east_asian_line_breaks\f[]
|
|
.PP
|
|
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[C]ignore_line_breaks\f[] for texts that
|
|
include a mix of East Asian wide characters and other characters.
|
|
.SS Extension: \f[C]emoji\f[]
|
|
.PP
|
|
Parses textual emojis like \f[C]:smile:\f[] as Unicode emoticons.
|
|
.SS Extension: \f[C]tex_math_single_backslash\f[]
|
|
.PP
|
|
Causes anything between \f[C]\\(\f[] and \f[C]\\)\f[] to be interpreted
|
|
as inline TeX math, and anything between \f[C]\\[\f[] and \f[C]\\]\f[]
|
|
to be interpreted as display TeX math.
|
|
Note: a drawback of this extension is that it precludes escaping
|
|
\f[C](\f[] and \f[C][\f[].
|
|
.SS Extension: \f[C]tex_math_double_backslash\f[]
|
|
.PP
|
|
Causes anything between \f[C]\\\\(\f[] and \f[C]\\\\)\f[] to be
|
|
interpreted as inline TeX math, and anything between \f[C]\\\\[\f[] and
|
|
\f[C]\\\\]\f[] to be interpreted as display TeX math.
|
|
.SS Extension: \f[C]markdown_attribute\f[]
|
|
.PP
|
|
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[C]markdown=1\f[].
|
|
.SS Extension: \f[C]mmd_title_block\f[]
|
|
.PP
|
|
Enables a MultiMarkdown style title block at the top of the document,
|
|
for example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Title:\ \ \ My\ title
|
|
Author:\ \ John\ Doe
|
|
Date:\ \ \ \ September\ 1,\ 2008
|
|
Comment:\ This\ is\ a\ sample\ mmd\ title\ block,\ with
|
|
\ \ \ \ \ \ \ \ \ a\ field\ spanning\ multiple\ lines.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
See the MultiMarkdown documentation for details.
|
|
If \f[C]pandoc_title_block\f[] or \f[C]yaml_metadata_block\f[] is
|
|
enabled, it will take precedence over \f[C]mmd_title_block\f[].
|
|
.SS Extension: \f[C]abbreviations\f[]
|
|
.PP
|
|
Parses PHP Markdown Extra abbreviation keys, like
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
*[HTML]:\ Hypertext\ Markup\ Language
|
|
\f[]
|
|
.fi
|
|
.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[C]autolink_bare_uris\f[]
|
|
.PP
|
|
Makes all absolute URIs into links, even when not surrounded by pointy
|
|
braces \f[C]<...>\f[].
|
|
.SS Extension: \f[C]mmd_link_attributes\f[]
|
|
.PP
|
|
Parses multimarkdown style key\-value attributes on link and image
|
|
references.
|
|
This extension should not be confused with the \f[C]link_attributes\f[]
|
|
extension.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
This\ is\ a\ reference\ ![image][ref]\ with\ multimarkdown\ attributes.
|
|
|
|
[ref]:\ http://path.to/image\ "Image\ title"\ width=20px\ height=30px
|
|
\ \ \ \ \ \ \ id=myId\ class="myClass1\ myClass2"
|
|
\f[]
|
|
.fi
|
|
.SS Extension: \f[C]mmd_header_identifiers\f[]
|
|
.PP
|
|
Parses multimarkdown style header identifiers (in square brackets, after
|
|
the header but before any trailing \f[C]#\f[]s in an ATX header).
|
|
.SS Extension: \f[C]compact_definition_lists\f[]
|
|
.PP
|
|
Activates the definition list syntax of pandoc 1.12.x and earlier.
|
|
This syntax differs from the one described above under Definition lists
|
|
in several respects:
|
|
.IP \[bu] 2
|
|
No blank line is required between consecutive items of the definition
|
|
list.
|
|
.IP \[bu] 2
|
|
To get a "tight" or "compact" list, omit space between consecutive
|
|
items; the space between a term and its definition does not affect
|
|
anything.
|
|
.IP \[bu] 2
|
|
Lazy wrapping of paragraphs is not allowed: the entire definition must
|
|
be indented four spaces.
|
|
.SS Markdown variants
|
|
.PP
|
|
In addition to pandoc\[aq]s extended Markdown, the following Markdown
|
|
variants are supported:
|
|
.TP
|
|
.B \f[C]markdown_phpextra\f[] (PHP Markdown Extra)
|
|
\f[C]footnotes\f[], \f[C]pipe_tables\f[], \f[C]raw_html\f[],
|
|
\f[C]markdown_attribute\f[], \f[C]fenced_code_blocks\f[],
|
|
\f[C]definition_lists\f[], \f[C]intraword_underscores\f[],
|
|
\f[C]header_attributes\f[], \f[C]link_attributes\f[],
|
|
\f[C]abbreviations\f[], \f[C]shortcut_reference_links\f[],
|
|
\f[C]spaced_reference_links\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]markdown_github\f[] (deprecated GitHub\-Flavored Markdown)
|
|
\f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]fenced_code_blocks\f[],
|
|
\f[C]gfm_auto_identifiers\f[], \f[C]ascii_identifiers\f[],
|
|
\f[C]backtick_code_blocks\f[], \f[C]autolink_bare_uris\f[],
|
|
\f[C]space_in_atx_header\f[], \f[C]intraword_underscores\f[],
|
|
\f[C]strikeout\f[], \f[C]emoji\f[], \f[C]shortcut_reference_links\f[],
|
|
\f[C]angle_brackets_escapable\f[],
|
|
\f[C]lists_without_preceding_blankline\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]markdown_mmd\f[] (MultiMarkdown)
|
|
\f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]markdown_attribute\f[],
|
|
\f[C]mmd_link_attributes\f[], \f[C]tex_math_double_backslash\f[],
|
|
\f[C]intraword_underscores\f[], \f[C]mmd_title_block\f[],
|
|
\f[C]footnotes\f[], \f[C]definition_lists\f[],
|
|
\f[C]all_symbols_escapable\f[], \f[C]implicit_header_references\f[],
|
|
\f[C]auto_identifiers\f[], \f[C]mmd_header_identifiers\f[],
|
|
\f[C]shortcut_reference_links\f[], \f[C]implicit_figures\f[],
|
|
\f[C]superscript\f[], \f[C]subscript\f[], \f[C]backtick_code_blocks\f[],
|
|
\f[C]spaced_reference_links\f[], \f[C]raw_attribute\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]markdown_strict\f[] (Markdown.pl)
|
|
\f[C]raw_html\f[], \f[C]shortcut_reference_links\f[],
|
|
\f[C]spaced_reference_links\f[].
|
|
.RS
|
|
.RE
|
|
.PP
|
|
We also support \f[C]commonmark\f[] and \f[C]gfm\f[] (GitHub\-Flavored
|
|
Markdown, which is implemented as a set of extensions on
|
|
\f[C]commonmark\f[]).
|
|
.PP
|
|
Note, however, that \f[C]commonmark\f[] and \f[C]gfm\f[] have limited
|
|
support for extensions.
|
|
Only those listed below (and \f[C]smart\f[] and \f[C]raw_tex\f[]) will
|
|
work.
|
|
The extensions can, however, all be individually disabled.
|
|
Also, \f[C]raw_tex\f[] only affects \f[C]gfm\f[] output, not input.
|
|
.TP
|
|
.B \f[C]gfm\f[] (GitHub\-Flavored Markdown)
|
|
\f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]fenced_code_blocks\f[],
|
|
\f[C]gfm_auto_identifiers\f[], \f[C]ascii_identifiers\f[],
|
|
\f[C]backtick_code_blocks\f[], \f[C]autolink_bare_uris\f[],
|
|
\f[C]intraword_underscores\f[], \f[C]strikeout\f[],
|
|
\f[C]hard_line_breaks\f[], \f[C]emoji\f[],
|
|
\f[C]shortcut_reference_links\f[], \f[C]angle_brackets_escapable\f[].
|
|
.RS
|
|
.RE
|
|
.SH PRODUCING SLIDE SHOWS WITH PANDOC
|
|
.PP
|
|
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[C]beamer\f[], or
|
|
slides shows in Microsoft PowerPoint format.
|
|
.PP
|
|
Here\[aq]s the Markdown source for a simple slide show,
|
|
\f[C]habits.txt\f[]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
%\ 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
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
To produce an HTML/JavaScript slide show, simply type
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-t\ FORMAT\ \-s\ habits.txt\ \-o\ habits.html
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
where \f[C]FORMAT\f[] is either \f[C]s5\f[], \f[C]slidy\f[],
|
|
\f[C]slideous\f[], \f[C]dzslides\f[], or \f[C]revealjs\f[].
|
|
.PP
|
|
For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with
|
|
the \f[C]\-s/\-\-standalone\f[] option embeds a link to JavaScript and
|
|
CSS files, which are assumed to be available at the relative path
|
|
\f[C]s5/default\f[] (for S5), \f[C]slideous\f[] (for Slideous),
|
|
\f[C]reveal.js\f[] (for reveal.js), or at the Slidy website at
|
|
\f[C]w3.org\f[] (for Slidy).
|
|
(These paths can be changed by setting the \f[C]slidy\-url\f[],
|
|
\f[C]slideous\-url\f[], \f[C]revealjs\-url\f[], or \f[C]s5\-url\f[]
|
|
variables; see Variables for 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[C]\-\-self\-contained\f[] 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
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-t\ beamer\ habits.txt\ \-o\ habits.pdf
|
|
\f[]
|
|
.fi
|
|
.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
|
|
.nf
|
|
\f[C]
|
|
pandoc\ habits.txt\ \-o\ habits.pptx
|
|
\f[]
|
|
.fi
|
|
.SS Structuring the slide show
|
|
.PP
|
|
By default, the \f[I]slide level\f[] is the highest header level in the
|
|
hierarchy that is followed immediately by content, and not another
|
|
header, somewhere in the document.
|
|
In the example above, level 1 headers are always followed by level 2
|
|
headers, which are followed by content, so 2 is the slide level.
|
|
This default can be overridden using the \f[C]\-\-slide\-level\f[]
|
|
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 header at the slide level always starts a new slide.
|
|
.IP \[bu] 2
|
|
Headers \f[I]below\f[] the slide level in the hierarchy create headers
|
|
\f[I]within\f[] a slide.
|
|
.IP \[bu] 2
|
|
Headers \f[I]above\f[] the slide level in the hierarchy create "title
|
|
slides," which just contain the section title and help to break the
|
|
slide show into sections.
|
|
.IP \[bu] 2
|
|
Content \f[I]above\f[] the slide level will not appear in the slide
|
|
show.
|
|
.IP \[bu] 2
|
|
A title page is constructed automatically from the document\[aq]s 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\[aq]t care about structuring your slides into sections and
|
|
subsections, you can just use level 1 headers for all each slide.
|
|
(In that case, level 1 will be the slide level.) But you can also
|
|
structure the slide show into sections, as in the example above.
|
|
.PP
|
|
Note: in reveal.js slide shows, if slide level is 2, a two\-dimensional
|
|
layout will be produced, with level 1 headers building horizontally and
|
|
level 2 headers building vertically.
|
|
It is not recommended that you use deeper nesting of section levels with
|
|
reveal.js.
|
|
.SS Incremental lists
|
|
.PP
|
|
By default, these writers produce lists that display "all at once." If
|
|
you want your lists to display incrementally (one item at a time), use
|
|
the \f[C]\-i\f[] option.
|
|
If you want a particular list to depart from the default, put it in a
|
|
\f[C]div\f[] block with class \f[C]incremental\f[] or
|
|
\f[C]nonincremental\f[].
|
|
So, for example, using the \f[C]fenced\ div\f[] syntax, the following
|
|
would be incremental regardless of the document default:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
:::\ incremental
|
|
|
|
\-\ Eat\ spaghetti
|
|
\-\ Drink\ wine
|
|
|
|
:::
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
or
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
:::\ nonincremental
|
|
|
|
\-\ Eat\ spaghetti
|
|
\-\ Drink\ wine
|
|
|
|
:::
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
While using \f[C]incremental\f[] and \f[C]nonincremental\f[] divs are
|
|
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[C]\-i\f[] option and all at once
|
|
with the \f[C]\-i\f[] option):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
>\ \-\ Eat\ spaghetti
|
|
>\ \-\ Drink\ wine
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Both methods allow incremental and nonincremental lists to be mixed in a
|
|
single document.
|
|
.SS Inserting pauses
|
|
.PP
|
|
You can add "pauses" within a slide by including a paragraph containing
|
|
three dots, separated by spaces:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ Slide\ with\ a\ pause
|
|
|
|
content\ before\ the\ pause
|
|
|
|
\&.\ .\ .
|
|
|
|
content\ after\ the\ pause
|
|
\f[]
|
|
.fi
|
|
.SS Styling the slides
|
|
.PP
|
|
You can change the style of HTML slides by putting customized CSS files
|
|
in \f[C]$DATADIR/s5/default\f[] (for S5), \f[C]$DATADIR/slidy\f[] (for
|
|
Slidy), or \f[C]$DATADIR/slideous\f[] (for Slideous), where
|
|
\f[C]$DATADIR\f[] is the user data directory (see
|
|
\f[C]\-\-data\-dir\f[], above).
|
|
The originals may be found in pandoc\[aq]s system data directory
|
|
(generally \f[C]$CABALDIR/pandoc\-VERSION/s5/default\f[]).
|
|
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[C]theme\f[] variable:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-V\ theme=moon
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Or you can specify a custom stylesheet using the \f[C]\-\-css\f[]
|
|
option.
|
|
.PP
|
|
To style beamer slides, you can specify a \f[C]theme\f[],
|
|
\f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], and
|
|
\f[C]outertheme\f[], using the \f[C]\-V\f[] option:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-t\ beamer\ habits.txt\ \-V\ theme:Warsaw\ \-o\ habits.pdf
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Note that header attributes will turn into slide attributes (on a
|
|
\f[C]<div>\f[] or \f[C]<section>\f[]) in HTML slide formats, allowing
|
|
you to style individual slides.
|
|
In beamer, the only header attribute that affects slides is the
|
|
\f[C]allowframebreaks\f[] class, which sets the
|
|
\f[C]allowframebreaks\f[] option, causing multiple slides to be created
|
|
if the content overfills the frame.
|
|
This is recommended especially for bibliographies:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ References\ {.allowframebreaks}
|
|
\f[]
|
|
.fi
|
|
.SS Speaker notes
|
|
.PP
|
|
Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
|
|
You can add notes to your Markdown document thus:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
:::\ notes
|
|
|
|
This\ is\ my\ note.
|
|
|
|
\-\ It\ can\ contain\ Markdown
|
|
\-\ like\ this\ list
|
|
|
|
:::
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
To show the notes window in reveal.js, press \f[C]s\f[] 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 Columns
|
|
.PP
|
|
To put material in side by side columns, you can use a native div
|
|
container with class \f[C]columns\f[], containing two or more div
|
|
containers with class \f[C]column\f[] and a \f[C]width\f[] attribute:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
::::::::::::::\ {.columns}
|
|
:::\ {.column\ width="40%"}
|
|
contents...
|
|
:::
|
|
:::\ {.column\ width="60%"}
|
|
contents...
|
|
:::
|
|
::::::::::::::
|
|
\f[]
|
|
.fi
|
|
.SS Frame attributes in beamer
|
|
.PP
|
|
Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[] option to
|
|
a frame in beamer (for example, when using the \f[C]minted\f[]
|
|
environment).
|
|
This can be forced by adding the \f[C]fragile\f[] class to the header
|
|
introducing the slide:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ Fragile\ slide\ {.fragile}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
All of the other frame attributes described in Section 8.1 of the Beamer
|
|
User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[],
|
|
\f[C]allowframebreaks\f[], \f[C]b\f[], \f[C]c\f[], \f[C]t\f[],
|
|
\f[C]environment\f[], \f[C]label\f[], \f[C]plain\f[], \f[C]shrink\f[],
|
|
\f[C]standout\f[], \f[C]noframenumbering\f[].
|
|
.SS Background in reveal.js and beamer
|
|
.PP
|
|
Background images can be added to self\-contained reveal.js slideshows
|
|
and to beamer slideshows.
|
|
.PP
|
|
For the same image on every slide, use the configuration option
|
|
\f[C]background\-image\f[] either in the YAML metadata block or as a
|
|
command\-line variable.
|
|
(There are no other options in beamer and the rest of this section
|
|
concerns reveal.js slideshows.)
|
|
.PP
|
|
For reveal.js, you can instead use the reveal.js\-native option
|
|
\f[C]parallaxBackgroundImage\f[].
|
|
You can also set \f[C]parallaxBackgroundHorizontal\f[] and
|
|
\f[C]parallaxBackgroundVertical\f[] the same way and must also set
|
|
\f[C]parallaxBackgroundSize\f[] to have your values take effect.
|
|
.PP
|
|
To set an image for a particular reveal.js slide, add
|
|
\f[C]{data\-background\-image="/path/to/image"}\f[] to the first
|
|
slide\-level header on the slide (which may even be empty).
|
|
.PP
|
|
In reveal.js\[aq]s overview mode, the parallaxBackgroundImage will show
|
|
up only on the first slide.
|
|
.PP
|
|
Other reveal.js background settings also work on individual slides,
|
|
including \f[C]data\-background\-size\f[],
|
|
\f[C]data\-background\-repeat\f[], \f[C]data\-background\-color\f[],
|
|
\f[C]data\-transition\f[], and \f[C]data\-transition\-speed\f[].
|
|
.PP
|
|
See the reveal.js documentation for more details.
|
|
.PP
|
|
For example in reveal.js:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
title:\ My\ Slideshow
|
|
parallaxBackgroundImage:\ /path/to/my/background_image.png
|
|
\-\-\-
|
|
|
|
##\ Slide\ One
|
|
|
|
Slide\ 1\ has\ background_image.png\ as\ its\ background.
|
|
|
|
##\ {data\-background\-image="/path/to/special_image.jpg"}
|
|
|
|
Slide\ 2\ has\ a\ special\ image\ for\ its\ background,\ even\ though\ the\ header\ has\ no\ content.
|
|
\f[]
|
|
.fi
|
|
.SH CREATING EPUBS WITH PANDOC
|
|
.SS EPUB Metadata
|
|
.PP
|
|
EPUB metadata may be specified using the \f[C]\-\-epub\-metadata\f[]
|
|
option, but if the source document is Markdown, it is better to use a
|
|
YAML metadata block.
|
|
Here is an example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\-\-\-
|
|
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:\ doi:10.234234.234/33
|
|
publisher:\ \ My\ Press
|
|
rights:\ ©\ 2007\ John\ Smith,\ CC\ BY\-NC
|
|
ibooks:
|
|
\ \ version:\ 1.3.4
|
|
\&...
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
The following fields are recognized:
|
|
.TP
|
|
.B \f[C]identifier\f[]
|
|
Either a string value or an object with fields \f[C]text\f[] and
|
|
\f[C]scheme\f[].
|
|
Valid values for \f[C]scheme\f[] are \f[C]ISBN\-10\f[],
|
|
\f[C]GTIN\-13\f[], \f[C]UPC\f[], \f[C]ISMN\-10\f[], \f[C]DOI\f[],
|
|
\f[C]LCCN\f[], \f[C]GTIN\-14\f[], \f[C]ISBN\-13\f[],
|
|
\f[C]Legal\ deposit\ number\f[], \f[C]URN\f[], \f[C]OCLC\f[],
|
|
\f[C]ISMN\-13\f[], \f[C]ISBN\-A\f[], \f[C]JP\f[], \f[C]OLCC\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]title\f[]
|
|
Either a string value, or an object with fields \f[C]file\-as\f[] and
|
|
\f[C]type\f[], or a list of such objects.
|
|
Valid values for \f[C]type\f[] are \f[C]main\f[], \f[C]subtitle\f[],
|
|
\f[C]short\f[], \f[C]collection\f[], \f[C]edition\f[],
|
|
\f[C]extended\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]creator\f[]
|
|
Either a string value, or an object with fields \f[C]role\f[],
|
|
\f[C]file\-as\f[], and \f[C]text\f[], or a list of such objects.
|
|
Valid values for \f[C]role\f[] are MARC relators, but pandoc will
|
|
attempt to translate the human\-readable versions (like "author" and
|
|
"editor") to the appropriate marc relators.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]contributor\f[]
|
|
Same format as \f[C]creator\f[].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]date\f[]
|
|
A string value in \f[C]YYYY\-MM\-DD\f[] format.
|
|
(Only the year is necessary.) Pandoc will attempt to convert other
|
|
common date formats.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]lang\f[] (or legacy: \f[C]language\f[])
|
|
A string value in BCP 47 format.
|
|
Pandoc will default to the local language if nothing is specified.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]subject\f[]
|
|
A string value or a list of such values.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]description\f[]
|
|
A string value.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]type\f[]
|
|
A string value.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]format\f[]
|
|
A string value.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]relation\f[]
|
|
A string value.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]coverage\f[]
|
|
A string value.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]rights\f[]
|
|
A string value.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]cover\-image\f[]
|
|
A string value (path to cover image).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]stylesheet\f[]
|
|
A string value (path to CSS stylesheet).
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]page\-progression\-direction\f[]
|
|
Either \f[C]ltr\f[] or \f[C]rtl\f[].
|
|
Specifies the \f[C]page\-progression\-direction\f[] attribute for the
|
|
\f[C]spine\f[] element.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[C]ibooks\f[]
|
|
iBooks\-specific metadata, with the following fields:
|
|
.RS
|
|
.IP \[bu] 2
|
|
\f[C]version\f[]: (string)
|
|
.IP \[bu] 2
|
|
\f[C]specified\-fonts\f[]: \f[C]true\f[]|\f[C]false\f[] (default
|
|
\f[C]false\f[])
|
|
.IP \[bu] 2
|
|
\f[C]ipad\-orientation\-lock\f[]:
|
|
\f[C]portrait\-only\f[]|\f[C]landscape\-only\f[]
|
|
.IP \[bu] 2
|
|
\f[C]iphone\-orientation\-lock\f[]:
|
|
\f[C]portrait\-only\f[]|\f[C]landscape\-only\f[]
|
|
.IP \[bu] 2
|
|
\f[C]binding\f[]: \f[C]true\f[]|\f[C]false\f[] (default \f[C]true\f[])
|
|
.IP \[bu] 2
|
|
\f[C]scroll\-axis\f[]:
|
|
\f[C]vertical\f[]|\f[C]horizontal\f[]|\f[C]default\f[]
|
|
.RE
|
|
.SS The \f[C]epub:type\f[] attribute
|
|
.PP
|
|
You can mark up the header that corresponds to an EPUB chapter using the
|
|
\f[C]epub:type\f[] attribute.
|
|
For example, to set the attribute to the value \f[C]prologue\f[], use
|
|
this markdown:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
#\ My\ chapter\ {epub:type=prologue}
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Which will result in:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<body\ epub:type="frontmatter">
|
|
\ \ <section\ epub:type="prologue">
|
|
\ \ \ \ <h1>My\ chapter</h1>
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Pandoc will output \f[C]<body\ epub:type="bodymatter">\f[], unless you
|
|
use one of the following values, in which case either
|
|
\f[C]frontmatter\f[] or \f[C]backmatter\f[] will be output.
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[C]epub:type\f[] of first section
|
|
T}@T{
|
|
\f[C]epub:type\f[] of body
|
|
T}
|
|
_
|
|
T{
|
|
prologue
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
abstract
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
acknowledgments
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
copyright\-page
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
dedication
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
foreword
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
halftitle,
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
introduction
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
preface
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
seriespage
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
titlepage
|
|
T}@T{
|
|
frontmatter
|
|
T}
|
|
T{
|
|
afterword
|
|
T}@T{
|
|
backmatter
|
|
T}
|
|
T{
|
|
appendix
|
|
T}@T{
|
|
backmatter
|
|
T}
|
|
T{
|
|
colophon
|
|
T}@T{
|
|
backmatter
|
|
T}
|
|
T{
|
|
conclusion
|
|
T}@T{
|
|
backmatter
|
|
T}
|
|
T{
|
|
epigraph
|
|
T}@T{
|
|
backmatter
|
|
T}
|
|
.TE
|
|
.SS Linked media
|
|
.PP
|
|
By default, pandoc will download media referenced from any
|
|
\f[C]<img>\f[], \f[C]<audio>\f[], \f[C]<video>\f[] or \f[C]<source>\f[]
|
|
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[C]data\-external="1"\f[] to the tag with the
|
|
\f[C]src\f[] attribute.
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<audio\ controls="1">
|
|
\ \ <source\ src="http://example.com/music/toccata.mp3"
|
|
\ \ \ \ \ \ \ \ \ \ data\-external="1"\ type="audio/mpeg">
|
|
\ \ </source>
|
|
</audio>
|
|
\f[]
|
|
.fi
|
|
.SH SYNTAX HIGHLIGHTING
|
|
.PP
|
|
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, and
|
|
LaTeX/PDF output.
|
|
To see a list of language names that pandoc will recognize, type
|
|
\f[C]pandoc\ \-\-list\-highlight\-languages\f[].
|
|
.PP
|
|
The color scheme can be selected using the \f[C]\-\-highlight\-style\f[]
|
|
option.
|
|
The default color scheme is \f[C]pygments\f[], 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[C]pandoc\ \-\-list\-highlight\-styles\f[].
|
|
.PP
|
|
If you are not satisfied with the predefined styles, you can use
|
|
\f[C]\-\-print\-highlight\-style\f[] to generate a JSON
|
|
\f[C]\&.theme\f[] file which can be modified and used as the argument to
|
|
\f[C]\-\-highlight\-style\f[].
|
|
To get a JSON version of the \f[C]pygments\f[] style, for example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-\-print\-highlight\-style\ pygments\ >\ my.theme
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Then edit \f[C]my.theme\f[] and use it like this:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-\-highlight\-style\ my.theme
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
If you are not satisfied with the built\-in highlighting, or you want
|
|
highlight a language that isn\[aq]t supported, you can use the
|
|
\f[C]\-\-syntax\-definition\f[] option to load a KDE\-style XML syntax
|
|
definition file.
|
|
Before writing your own, have a look at KDE\[aq]s repository of syntax
|
|
definitions.
|
|
.PP
|
|
To disable highlighting, use the \f[C]\-\-no\-highlight\f[] option.
|
|
.SH CUSTOM STYLES IN DOCX
|
|
.SS Input
|
|
.PP
|
|
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\[aq]s styles.
|
|
.PP
|
|
By enabling the \f[C]styles\f[] extension in the docx reader
|
|
(\f[C]\-f\ docx+styles\f[]), you can produce output that maintains the
|
|
styles of the input document, using the \f[C]custom\-style\f[] class.
|
|
Paragraph styles are interpreted as divs, while character styles are
|
|
interpreted as spans.
|
|
.PP
|
|
For example, using the \f[C]custom\-style\-reference.docx\f[] file in
|
|
the test directory, we have the following different outputs:
|
|
.PP
|
|
Without the \f[C]+styles\f[] extension:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ 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.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
And with the extension:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
$\ pandoc\ test/docx/custom\-style\-reference.docx\ \-f\ docx+styles\ \-t\ markdown
|
|
|
|
:::\ {custom\-style="FirstParagraph"}
|
|
This\ is\ some\ text.
|
|
:::
|
|
|
|
:::\ {custom\-style="BodyText"}
|
|
This\ is\ text\ with\ an\ [emphasized]{custom\-style="Emphatic"}\ text\ style.
|
|
And\ this\ is\ text\ with\ a\ [strengthened]{custom\-style="Strengthened"}
|
|
text\ style.
|
|
:::
|
|
|
|
:::\ {custom\-style="MyBlockStyle"}
|
|
>\ Here\ is\ a\ styled\ paragraph\ that\ inherits\ from\ Block\ Text.
|
|
:::
|
|
\f[]
|
|
.fi
|
|
.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.
|
|
.SS Output
|
|
.PP
|
|
By default, pandoc\[aq]s docx 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
|
|
\f[C]reference.docx\f[] 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[C]div\f[]s and \f[C]span\f[]s, respectively.
|
|
.PP
|
|
If you define a \f[C]div\f[] or \f[C]span\f[] with the attribute
|
|
\f[C]custom\-style\f[], pandoc will apply your specified style to the
|
|
contained elements.
|
|
So, for example using the \f[C]bracketed_spans\f[] syntax,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[Get\ out]{custom\-style="Emphatically"},\ he\ said.
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
would produce a docx file with "Get out" styled with character style
|
|
\f[C]Emphatically\f[].
|
|
Similarly, using the \f[C]fenced_divs\f[] syntax,
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Dickinson\ starts\ the\ poem\ simply:
|
|
|
|
:::\ {custom\-style="Poetry"}
|
|
|\ A\ Bird\ came\ down\ the\ Walk\-\-\-
|
|
|\ He\ did\ not\ know\ I\ saw\-\-\-
|
|
:::
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
would style the two contained lines with the \f[C]Poetry\f[] paragraph
|
|
style.
|
|
.PP
|
|
If the styles are not yet in your reference.docx, they will be defined
|
|
in the output file as inheriting from normal text.
|
|
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[C]Emphasis\f[]
|
|
character style (perhaps to change their color), you can write a filter
|
|
which will transform all italicized inlines to inlines within an
|
|
\f[C]Emphasis\f[] custom\-style \f[C]span\f[].
|
|
.SH CUSTOM WRITERS
|
|
.PP
|
|
Pandoc can be extended with custom writers written in lua.
|
|
(Pandoc includes a lua interpreter, so lua need not be installed
|
|
separately.)
|
|
.PP
|
|
To use a custom writer, simply specify the path to the lua script in
|
|
place of the output format.
|
|
For example:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-t\ data/sample.lua
|
|
\f[]
|
|
.fi
|
|
.PP
|
|
Creating a custom writer requires writing a lua function for each
|
|
possible element in a pandoc document.
|
|
To get a documented example which you can modify according to your
|
|
needs, do
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
pandoc\ \-\-print\-default\-data\-file\ sample.lua
|
|
\f[]
|
|
.fi
|
|
.SH AUTHORS
|
|
.PP
|
|
Copyright 2006\-2017 John MacFarlane (jgm\@berkeley.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 and all documentation may be downloaded
|
|
from <http://pandoc.org>.
|