2.TH PANDOC 1 "December 12, 2019" "pandoc 2.9"
4pandoc - general markup converter
7\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]...
10Pandoc is a Haskell library for converting from one markup format to
11another, and a command-line tool that uses this library.
13Pandoc can convert between numerous markup and word processing formats,
14including, but not limited to, various flavors of Markdown, HTML, LaTeX
16For the full lists of input and output formats, see the \f[C]--from\f[R]
17and \f[C]--to\f[R] options below.
18Pandoc can also produce PDF output: see creating a PDF, below.
20Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
21definition lists, metadata blocks, footnotes, citations, math, and much
23See below under Pandoc\[aq]s Markdown.
25Pandoc has a modular design: it consists of a set of readers, which
26parse text in a given format and produce a native representation of the
27document (an \f[I]abstract syntax tree\f[R] or AST), and a set of
28writers, which convert this native representation into a target format.
29Thus, adding an input or output format requires only adding a reader or
31Users can also run custom pandoc filters to modify the intermediate AST.
33Because pandoc\[aq]s intermediate representation of a document is less
34expressive than many of the formats it converts between, one should not
35expect perfect conversions between every format and every other.
36Pandoc attempts to preserve the structural elements of a document, but
37not formatting details such as margin size.
38And some document elements, such as complex tables, may not fit into
39pandoc\[aq]s simple document model.
40While conversions from pandoc\[aq]s Markdown to all formats aspire to be
41perfect, conversions from formats more expressive than pandoc\[aq]s
42Markdown can be expected to be lossy.
45If no \f[I]input-files\f[R] are specified, input is read from
47Output goes to \f[I]stdout\f[R] by default.
48For output to a file, use the \f[C]-o\f[R] option:
52pandoc -o output.html input.txt
56By default, pandoc produces a document fragment.
57To produce a standalone document (e.g.
58a valid HTML file including \f[C]<head>\f[R] and \f[C]<body>\f[R]), use
59the \f[C]-s\f[R] or \f[C]--standalone\f[R] flag:
63pandoc -s -o output.html input.txt
67For more information on how standalone documents are produced, see
70If multiple input files are given, \f[C]pandoc\f[R] will concatenate
71them all (with blank lines between them) before parsing.
72(Use \f[C]--file-scope\f[R] to parse files individually.)
75The format of the input and output can be specified explicitly using
77The input format can be specified using the \f[C]-f/--from\f[R] option,
78the output format using the \f[C]-t/--to\f[R] option.
79Thus, to convert \f[C]hello.txt\f[R] from Markdown to LaTeX, you could
84pandoc -f markdown -t latex hello.txt
88To convert \f[C]hello.html\f[R] from HTML to Markdown:
92pandoc -f html -t markdown hello.html
96Supported input and output formats are listed below under Options (see
97\f[C]-f\f[R] for input formats and \f[C]-t\f[R] for output formats).
98You can also use \f[C]pandoc --list-input-formats\f[R] and
99\f[C]pandoc --list-output-formats\f[R] to print lists of supported
102If the input or output format is not specified explicitly,
103\f[C]pandoc\f[R] will attempt to guess it from the extensions of the
109pandoc -o hello.tex hello.txt
113will convert \f[C]hello.txt\f[R] from Markdown to LaTeX.
114If no output file is specified (so that output goes to
115\f[I]stdout\f[R]), or if the output file\[aq]s extension is unknown, the
116output format will default to HTML.
117If no input file is specified (so that input comes from
118\f[I]stdin\f[R]), or if the input files\[aq] extensions are unknown, the
119input format will be assumed to be Markdown.
120.SS Character encoding
122Pandoc uses the UTF-8 character encoding for both input and output.
123If your local character encoding is not UTF-8, you should pipe input and
124output through \f[C]iconv\f[R]:
128iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
132Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
133OPML, DocBook, and Texinfo), information about the character encoding is
134included in the document header, which will only be included if you use
135the \f[C]-s/--standalone\f[R] option.
138To produce a PDF, specify an output file with a \f[C].pdf\f[R]
143pandoc test.txt -o test.pdf
147By default, pandoc will use LaTeX to create the PDF, which requires that
148a LaTeX engine be installed (see \f[C]--pdf-engine\f[R] below).
149Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an
151To do this, specify an output file with a \f[C].pdf\f[R] extension, as
152before, but add the \f[C]--pdf-engine\f[R] option or
153\f[C]-t context\f[R], \f[C]-t html\f[R], or \f[C]-t ms\f[R] to the
155The tool used to generate the PDF from the intermediate format may be
156specified using \f[C]--pdf-engine\f[R].
158You can control the PDF style using variables, depending on the
159intermediate format used: see variables for LaTeX, variables for
160ConTeXt, variables for \f[C]wkhtmltopdf\f[R], variables for ms.
161When HTML is used as an intermediate format, the output can be styled
162using \f[C]--css\f[R].
164To debug the PDF creation, it can be useful to look at the intermediate
165representation: instead of \f[C]-o test.pdf\f[R], use for example
166\f[C]-s -o test.tex\f[R] to output the generated LaTeX.
167You can then test it with \f[C]pdflatex test.tex\f[R].
169When using LaTeX, the following packages need to be available (they are
170included with all recent versions of TeX Live): \f[C]amsfonts\f[R],
171\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],
172\f[C]ifxetex\f[R], \f[C]ifluatex\f[R], \f[C]listings\f[R] (if the
173\f[C]--listings\f[R] option is used), \f[C]fancyvrb\f[R],
174\f[C]longtable\f[R], \f[C]booktabs\f[R], \f[C]graphicx\f[R] (if the
175document contains images), \f[C]hyperref\f[R], \f[C]xcolor\f[R],
176\f[C]ulem\f[R], \f[C]geometry\f[R] (with the \f[C]geometry\f[R] variable
177set), \f[C]setspace\f[R] (with \f[C]linestretch\f[R]), and
178\f[C]babel\f[R] (with \f[C]lang\f[R]).
179The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
180requires \f[C]fontspec\f[R].
181\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),
182\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
184If the \f[C]mathspec\f[R] variable is set, \f[C]xelatex\f[R] will use
185\f[C]mathspec\f[R] instead of \f[C]unicode-math\f[R].
186The \f[C]upquote\f[R] and \f[C]microtype\f[R] packages are used if
187available, and \f[C]csquotes\f[R] will be used for typography if the
188\f[C]csquotes\f[R] variable or metadata field is set to a true value.
189The \f[C]natbib\f[R], \f[C]biblatex\f[R], \f[C]bibtex\f[R], and
190\f[C]biber\f[R] packages can optionally be used for citation rendering.
191The following packages will be used to improve output quality if
192present, but pandoc does not require them to be present:
193\f[C]upquote\f[R] (for straight quotes in verbatim environments),
194\f[C]microtype\f[R] (for better spacing adjustments), \f[C]parskip\f[R]
195(for better inter-paragraph spaces), \f[C]xurl\f[R] (for better line
196breaks in URLs), \f[C]bookmark\f[R] (for better PDF bookmarks), and
197\f[C]footnotehyper\f[R] or \f[C]footnote\f[R] (to allow footnotes in
199.SS Reading from the Web
201Instead of an input file, an absolute URI may be given.
202In this case pandoc will fetch the content using HTTP:
206pandoc -f html -t markdown http://www.fsf.org
210It is possible to supply a custom User-Agent string or other header when
211requesting a document from a URL:
215pandoc -f html -t markdown --request-header User-Agent:\[dq]Mozilla/5.0\[dq] \[rs]
222\f[B]\f[CB]-f\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]-r\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--from=\f[B]\f[R]\f[I]FORMAT\f[R], \f[B]\f[CB]--read=\f[B]\f[R]\f[I]FORMAT\f[R]
224\f[I]FORMAT\f[R] can be:
227\f[C]commonmark\f[R] (CommonMark Markdown)
229\f[C]creole\f[R] (Creole 1.0)
231\f[C]docbook\f[R] (DocBook)
233\f[C]docx\f[R] (Word docx)
235\f[C]dokuwiki\f[R] (DokuWiki markup)
239\f[C]fb2\f[R] (FictionBook2 e-book)
241\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
242accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
243if you need extensions not supported in \f[C]gfm\f[R].
245\f[C]haddock\f[R] (Haddock markup)
249\f[C]ipynb\f[R] (Jupyter notebook)
251\f[C]jats\f[R] (JATS XML)
253\f[C]json\f[R] (JSON version of native AST)
255\f[C]latex\f[R] (LaTeX)
257\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
259\f[C]markdown_mmd\f[R] (MultiMarkdown)
261\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
263\f[C]markdown_strict\f[R] (original unextended Markdown)
265\f[C]mediawiki\f[R] (MediaWiki markup)
267\f[C]man\f[R] (roff man)
271\f[C]native\f[R] (native Haskell)
277\f[C]org\f[R] (Emacs Org mode)
279\f[C]rst\f[R] (reStructuredText)
281\f[C]t2t\f[R] (txt2tags)
283\f[C]textile\f[R] (Textile)
285\f[C]tikiwiki\f[R] (TikiWiki markup)
287\f[C]twiki\f[R] (TWiki markup)
289\f[C]vimwiki\f[R] (Vimwiki)
291Extensions can be individually enabled or disabled by appending
292\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
293See Extensions below, for a list of extensions and their names.
294See \f[C]--list-input-formats\f[R] and \f[C]--list-extensions\f[R],
298\f[B]\f[CB]-t\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]-w\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--to=\f[B]\f[R]\f[I]FORMAT\f[R], \f[B]\f[CB]--write=\f[B]\f[R]\f[I]FORMAT\f[R]
299Specify output format.
300\f[I]FORMAT\f[R] can be:
303\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor)
305\f[C]beamer\f[R] (LaTeX beamer slide show)
307\f[C]commonmark\f[R] (CommonMark Markdown)
309\f[C]context\f[R] (ConTeXt)
311\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)
313\f[C]docbook5\f[R] (DocBook 5)
315\f[C]docx\f[R] (Word docx)
317\f[C]dokuwiki\f[R] (DokuWiki markup)
319\f[C]epub\f[R] or \f[C]epub3\f[R] (EPUB v3 book)
321\f[C]epub2\f[R] (EPUB v2)
323\f[C]fb2\f[R] (FictionBook2 e-book)
325\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
326accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
327if you need extensions not supported in \f[C]gfm\f[R].
329\f[C]haddock\f[R] (Haddock markup)
331\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.
332HTML5/XHTML polyglot markup)
334\f[C]html4\f[R] (XHTML 1.0 Transitional)
336\f[C]icml\f[R] (InDesign ICML)
338\f[C]ipynb\f[R] (Jupyter notebook)
340\f[C]jats\f[R] (JATS XML)
342\f[C]jira\f[R] (Jira wiki markup)
344\f[C]json\f[R] (JSON version of native AST)
346\f[C]latex\f[R] (LaTeX)
348\f[C]man\f[R] (roff man)
350\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
352\f[C]markdown_mmd\f[R] (MultiMarkdown)
354\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
356\f[C]markdown_strict\f[R] (original unextended Markdown)
358\f[C]mediawiki\f[R] (MediaWiki markup)
360\f[C]ms\f[R] (roff ms)
362\f[C]muse\f[R] (Muse),
364\f[C]native\f[R] (native Haskell),
366\f[C]odt\f[R] (OpenOffice text document)
370\f[C]opendocument\f[R] (OpenDocument)
372\f[C]org\f[R] (Emacs Org mode)
376\f[C]plain\f[R] (plain text),
378\f[C]pptx\f[R] (PowerPoint slide show)
380\f[C]rst\f[R] (reStructuredText)
382\f[C]rtf\f[R] (Rich Text Format)
384\f[C]texinfo\f[R] (GNU Texinfo)
386\f[C]textile\f[R] (Textile)
388\f[C]slideous\f[R] (Slideous HTML and JavaScript slide show)
390\f[C]slidy\f[R] (Slidy HTML and JavaScript slide show)
392\f[C]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show),
394\f[C]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)
396\f[C]s5\f[R] (S5 HTML and JavaScript slide show)
398\f[C]tei\f[R] (TEI Simple)
400\f[C]xwiki\f[R] (XWiki markup)
402\f[C]zimwiki\f[R] (ZimWiki markup)
404the path of a custom lua writer, see Custom writers below
406Note that \f[C]odt\f[R], \f[C]docx\f[R], \f[C]epub\f[R], and
407\f[C]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless
408forced with \f[C]-o -\f[R].
410Extensions can be individually enabled or disabled by appending
411\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
412See Extensions below, for a list of extensions and their names.
413See \f[C]--list-output-formats\f[R] and \f[C]--list-extensions\f[R],
417\f[B]\f[CB]-o\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--output=\f[B]\f[R]\f[I]FILE\f[R]
418Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].
419If \f[I]FILE\f[R] is \f[C]-\f[R], output will go to \f[I]stdout\f[R],
420even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],
421\f[C]epub2\f[R], \f[C]epub3\f[R]) is specified.
423\f[B]\f[CB]--data-dir=\f[B]\f[R]\f[I]DIRECTORY\f[R]
424Specify the user data directory to search for pandoc data files.
425If this option is not specified, the default user data directory will be
427On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
428of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
429overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
431If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
432(for backwards compatibility).
433In Windows the default user data directory is
434\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
435You can find the default user data directory on your system by looking
436at the output of \f[C]pandoc --version\f[R].
437A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
438\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
439\f[C]s5\f[R] directory placed in this directory will override
440pandoc\[aq]s normal defaults.
442\f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]
443Specify a set of default option settings.
444\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line
446All options for document conversion, including input and output files,
447can be set using a defaults file.
448The file will be searched for first in the working directory, and then
449in the \f[C]defaults\f[R] subdirectory of the user data directory (see
450\f[C]--data-dir\f[R]).
451The \f[C].yaml\f[R] extension may be omitted.
452See the section Default files for more information on the file format.
453Settings from the defaults file may be overridden or extended by
454subsequent options on the command line.
456\f[B]\f[CB]--bash-completion\f[B]\f[R]
457Generate a bash completion script.
458To enable bash completion with pandoc, add this to your
464eval \[dq]$(pandoc --bash-completion)\[dq]
469\f[B]\f[CB]--verbose\f[B]\f[R]
470Give verbose debugging output.
471Currently this only has an effect with PDF output.
473\f[B]\f[CB]--quiet\f[B]\f[R]
474Suppress warning messages.
476\f[B]\f[CB]--fail-if-warnings\f[B]\f[R]
477Exit with error status if there are any warnings.
479\f[B]\f[CB]--log=\f[B]\f[R]\f[I]FILE\f[R]
480Write log messages in machine-readable JSON format to \f[I]FILE\f[R].
481All messages above DEBUG level will be written, regardless of verbosity
482settings (\f[C]--verbose\f[R], \f[C]--quiet\f[R]).
484\f[B]\f[CB]--list-input-formats\f[B]\f[R]
485List supported input formats, one per line.
487\f[B]\f[CB]--list-output-formats\f[B]\f[R]
488List supported output formats, one per line.
490\f[B]\f[CB]--list-extensions\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]FORMAT\f[R]]
491List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
492by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by
493default in \f[I]FORMAT\f[R].
494If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[aq]s Markdown
497\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]
498List supported languages for syntax highlighting, one per line.
500\f[B]\f[CB]--list-highlight-styles\f[B]\f[R]
501List supported styles for syntax highlighting, one per line.
502See \f[C]--highlight-style\f[R].
504\f[B]\f[CB]-v\f[B]\f[R], \f[B]\f[CB]--version\f[B]\f[R]
507\f[B]\f[CB]-h\f[B]\f[R], \f[B]\f[CB]--help\f[B]\f[R]
511\f[B]\f[CB]--shift-heading-level-by=\f[B]\f[R]\f[I]NUMBER\f[R]
512Shift heading levels by a positive or negative integer.
513For example, with \f[C]--shift-heading-level-by=-1\f[R], level 2
514headings become level 1 headings, and level 3 headings become level 2
516Headings cannot have a level less than 1, so a heading that would be
517shifted below level 1 becomes a regular paragraph.
518Exception: with a shift of -N, a level-N heading at the beginning of the
519document replaces the metadata title.
520\f[C]--shift-heading-level-by=-1\f[R] is a good choice when converting
521HTML or Markdown documents that use an initial level-1 heading for the
522document title and level-2+ headings for sections.
523\f[C]--shift-heading-level-by=1\f[R] may be a good choice for converting
524Markdown documents that use level-1 headings for sections to HTML, since
525pandoc uses a level-1 heading to render the document title.
527\f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R]
528\f[I]Deprecated. Use \f[CI]--shift-heading-level-by\f[I] instead.\f[R]
529Specify the base level for headings (defaults to 1).
531\f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R]
532\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension
533instead.\f[R] Ignore paragraphs with no content.
534This option is useful for converting word processing documents where
535users have used empty paragraphs to create inter-paragraph space.
537\f[B]\f[CB]--indented-code-classes=\f[B]\f[R]\f[I]CLASSES\f[R]
538Specify classes to use for indented code blocks--for example,
539\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].
540Multiple classes may be separated by spaces or commas.
542\f[B]\f[CB]--default-image-extension=\f[B]\f[R]\f[I]EXTENSION\f[R]
543Specify a default extension to use when image paths/URLs have no
545This allows you to use the same source for formats that require
546different kinds of images.
547Currently this option only affects the Markdown and LaTeX readers.
549\f[B]\f[CB]--file-scope\f[B]\f[R]
550Parse each file individually before combining for multifile documents.
551This will allow footnotes in different files with the same identifiers
553If this option is set, footnotes and links will not work across files.
554Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].
556\f[B]\f[CB]-F\f[B]\f[R] \f[I]PROGRAM\f[R], \f[B]\f[CB]--filter=\f[B]\f[R]\f[I]PROGRAM\f[R]
557Specify an executable to be used as a filter transforming the pandoc AST
558after the input is parsed and before the output is written.
559The executable should read JSON from stdin and write JSON to stdout.
560The JSON must be formatted like pandoc\[aq]s own JSON input and output.
561The name of the output format will be passed to the filter as the first
568pandoc --filter ./caps.py -t latex
576pandoc -t json | ./caps.py latex | pandoc -f json -t latex
580The latter form may be useful for debugging filters.
582Filters may be written in any language.
583\f[C]Text.Pandoc.JSON\f[R] exports \f[C]toJSONFilter\f[R] to facilitate
584writing filters in Haskell.
585Those who would prefer to write filters in python can use the module
586\f[C]pandocfilters\f[R], installable from PyPI.
587There are also pandoc filter libraries in PHP, perl, and
590In order of preference, pandoc will look for filters in
592a specified full or relative path (executable or non-executable)
594\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
595\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
598\f[C]$PATH\f[R] (executable only)
600Filters and lua-filters are applied in the order specified on the
604\f[B]\f[CB]-L\f[B]\f[R] \f[I]SCRIPT\f[R], \f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]
605Transform the document in a similar fashion as JSON filters (see
606\f[C]--filter\f[R]), but use pandoc\[aq]s build-in lua filtering system.
607The given lua script is expected to return a list of lua filters which
608will be applied in order.
609Each lua filter must contain element-transforming functions indexed by
610the name of the AST element on which the filter function should be
614The \f[C]pandoc\f[R] lua module provides helper functions for element
616It is always loaded into the script\[aq]s lua environment.
618The following is an example lua script for macro-expansion:
622function expand_hello_world(inline)
623 if inline.c == \[aq]{{helloworld}}\[aq] then
624 return pandoc.Emph{ pandoc.Str \[dq]Hello, World\[dq] }
630return {{Str = expand_hello_world}}
634In order of preference, pandoc will look for lua filters in
636a specified full or relative path (executable or non-executable)
638\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
639\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
643\f[B]\f[CB]-M\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--metadata=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]
644Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].
645A value specified on the command line overrides a value specified in the
646document using YAML metadata blocks.
647Values will be parsed as YAML boolean or string values.
648If no value is specified, the value will be treated as Boolean true.
649Like \f[C]--variable\f[R], \f[C]--metadata\f[R] causes template
651But unlike \f[C]--variable\f[R], \f[C]--metadata\f[R] affects the
652metadata of the underlying document (which is accessible from filters
653and may be printed in some output formats) and metadata values will be
654escaped when inserted into the template.
656\f[B]\f[CB]--metadata-file=\f[B]\f[R]\f[I]FILE\f[R]
657Read metadata from the supplied YAML (or JSON) file.
658This option can be used with every input format, but string scalars in
659the YAML file will always be parsed as Markdown.
660Generally, the input will be handled the same as in YAML metadata
662This option can be used repeatedly to include multiple metadata files;
663values in files specified later on the command line will be preferred
664over those specified in earlier files.
665Metadata values specified inside the document, or by using \f[C]-M\f[R],
666overwrite values specified with this option.
668\f[B]\f[CB]-p\f[B]\f[R], \f[B]\f[CB]--preserve-tabs\f[B]\f[R]
669Preserve tabs instead of converting them to spaces.
670(By default, pandoc converts tabs to spaces before parsing its input.)
671Note that this will only affect tabs in literal code spans and code
673Tabs in regular text are always treated as spaces.
675\f[B]\f[CB]--tab-stop=\f[B]\f[R]\f[I]NUMBER\f[R]
676Specify the number of spaces per tab (default is 4).
678\f[B]\f[CB]--track-changes=accept\f[B]\f[R]|\f[B]\f[CB]reject\f[B]\f[R]|\f[B]\f[CB]all\f[B]\f[R]
679Specifies what to do with insertions, deletions, and comments produced
680by the MS Word \[dq]Track Changes\[dq] feature.
681\f[C]accept\f[R] (the default), inserts all insertions, and ignores all
683\f[C]reject\f[R] inserts all deletions and ignores insertions.
684Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.
685\f[C]all\f[R] puts in insertions, deletions, and comments, wrapped in
686spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
687\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,
689The author and time of change is included.
690\f[C]all\f[R] is useful for scripting: only accepting changes from a
691certain reviewer, say, or before a certain date.
692If a paragraph is inserted or deleted, \f[C]track-changes=all\f[R]
693produces a span with the class
694\f[C]paragraph-insertion\f[R]/\f[C]paragraph-deletion\f[R] before the
695affected paragraph break.
696This option only affects the docx reader.
698\f[B]\f[CB]--extract-media=\f[B]\f[R]\f[I]DIR\f[R]
699Extract images and other media contained in or linked from the source
700document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
701the images references in the document so they point to the extracted
703If the source format is a binary container (docx, epub, or odt), the
704media is extracted from the container and the original filenames are
706Otherwise the media is read from the file system or downloaded, and new
707filenames are constructed based on SHA1 hashes of the contents.
709\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
710Specifies a custom abbreviations file, with abbreviations one to a line.
711If this option is not specified, pandoc will read the data file
712\f[C]abbreviations\f[R] from the user data directory or fall back on a
714To see the system default, use
715\f[C]pandoc --print-default-data-file=abbreviations\f[R].
716The only use pandoc makes of this list is in the Markdown reader.
717Strings ending in a period that are found in this list will be followed
718by a nonbreaking space, so that the period will not produce
719sentence-ending space in formats like LaTeX.
720.SS General writer options
722\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]
723Produce output with an appropriate header and footer (e.g.
724a standalone HTML, LaTeX, TEI, or RTF file, not a fragment).
725This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],
726\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]
728For \f[C]native\f[R] output, this option causes metadata to be included;
729otherwise, metadata is suppressed.
731\f[B]\f[CB]--template=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
732Use the specified file as a custom template for the generated document.
733Implies \f[C]--standalone\f[R].
734See Templates, below, for a description of template syntax.
735If no extension is specified, an extension corresponding to the writer
736will be added, so that \f[C]--template=special\f[R] looks for
737\f[C]special.html\f[R] for HTML output.
738If the template is not found, pandoc will search for it in the
739\f[C]templates\f[R] subdirectory of the user data directory (see
740\f[C]--data-dir\f[R]).
741If this option is not used, a default template appropriate for the
742output format will be used (see \f[C]-D/--print-default-template\f[R]).
744\f[B]\f[CB]-V\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--variable=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]
745Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when
746rendering the document in standalone mode.
747If no \f[I]VAL\f[R] is specified, the key will be given the value
750\f[B]\f[CB]-D\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--print-default-template=\f[B]\f[R]\f[I]FORMAT\f[R]
751Print the system default template for an output \f[I]FORMAT\f[R].
752(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates
753in the user data directory are ignored.
754This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
755output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
756\f[C]--print-default-template\f[R] on the command line.
759Note that some of the default templates use partials, for example
760\f[C]styles.html\f[R].
761To print the partials, use \f[C]--print-default-data-file\f[R]: for
762example, \f[C]--print-default-data-file=templates/styles.html\f[R].
765\f[B]\f[CB]--print-default-data-file=\f[B]\f[R]\f[I]FILE\f[R]
766Print a system default data file.
767Files in the user data directory are ignored.
768This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
769output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
770\f[C]--print-default-data-file\f[R] on the command line.
772\f[B]\f[CB]--eol=crlf\f[B]\f[R]|\f[B]\f[CB]lf\f[B]\f[R]|\f[B]\f[CB]native\f[B]\f[R]
773Manually specify line endings: \f[C]crlf\f[R] (Windows), \f[C]lf\f[R]
774(macOS/Linux/UNIX), or \f[C]native\f[R] (line endings appropriate to the
775OS on which pandoc is being run).
776The default is \f[C]native\f[R].
778\f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R]
779Specify the default dpi (dots per inch) value for conversion from pixels
780to inch/centimeters and vice versa.
781(Technically, the correct term would be ppi: pixels per inch.) The
783When images contain information about dpi internally, the encoded value
784is used instead of the default specified by this option.
786\f[B]\f[CB]--wrap=auto\f[B]\f[R]|\f[B]\f[CB]none\f[B]\f[R]|\f[B]\f[CB]preserve\f[B]\f[R]
787Determine how text is wrapped in the output (the source code, not the
789With \f[C]auto\f[R] (the default), pandoc will attempt to wrap lines to
790the column width specified by \f[C]--columns\f[R] (default 72).
791With \f[C]none\f[R], pandoc will not wrap lines at all.
792With \f[C]preserve\f[R], pandoc will attempt to preserve the wrapping
793from the source document (that is, where there are nonsemantic newlines
794in the source, there will be nonsemantic newlines in the output as
796Automatic wrapping does not currently work in HTML output.
797In \f[C]ipynb\f[R] output, this option affects wrapping of the contents
800\f[B]\f[CB]--columns=\f[B]\f[R]\f[I]NUMBER\f[R]
801Specify length of lines in characters.
802This affects text wrapping in the generated source code (see
804It also affects calculation of column widths for plain text tables (see
807\f[B]\f[CB]--toc\f[B]\f[R], \f[B]\f[CB]--table-of-contents\f[B]\f[R]
808Include an automatically generated table of contents (or, in the case of
809\f[C]latex\f[R], \f[C]context\f[R], \f[C]docx\f[R], \f[C]odt\f[R],
810\f[C]opendocument\f[R], \f[C]rst\f[R], or \f[C]ms\f[R], an instruction
811to create one) in the output document.
812This option has no effect unless \f[C]-s/--standalone\f[R] is used, and
813it has no effect on \f[C]man\f[R], \f[C]docbook4\f[R],
814\f[C]docbook5\f[R], or \f[C]jats\f[R] output.
817Note that if you are producing a PDF via \f[C]ms\f[R], the table of
818contents will appear at the beginning of the document, before the title.
819If you would prefer it to be at the end of the document, use the option
820\f[C]--pdf-engine-opt=--no-toc-relocation\f[R].
823\f[B]\f[CB]--toc-depth=\f[B]\f[R]\f[I]NUMBER\f[R]
824Specify the number of section levels to include in the table of
826The default is 3 (which means that level-1, 2, and 3 headings will be
827listed in the contents).
829\f[B]\f[CB]--strip-comments\f[B]\f[R]
830Strip out HTML comments in the Markdown or Textile source, rather than
831passing them on to Markdown, Textile or HTML output as raw HTML.
832This does not apply to HTML comments inside raw HTML blocks when the
833\f[C]markdown_in_html_blocks\f[R] extension is not set.
835\f[B]\f[CB]--no-highlight\f[B]\f[R]
836Disables syntax highlighting for code blocks and inlines, even when a
837language attribute is given.
839\f[B]\f[CB]--highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
840Specifies the coloring style to be used in highlighted source code.
841Options are \f[C]pygments\f[R] (the default), \f[C]kate\f[R],
842\f[C]monochrome\f[R], \f[C]breezeDark\f[R], \f[C]espresso\f[R],
843\f[C]zenburn\f[R], \f[C]haddock\f[R], and \f[C]tango\f[R].
844For more information on syntax highlighting in pandoc, see Syntax
846See also \f[C]--list-highlight-styles\f[R].
849Instead of a \f[I]STYLE\f[R] name, a JSON file with extension
850\f[C].theme\f[R] may be supplied.
851This will be parsed as a KDE syntax highlighting theme and (if valid)
852used as the highlighting style.
854To generate the JSON version of an existing style, use
855\f[C]--print-highlight-style\f[R].
858\f[B]\f[CB]--print-highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
859Prints a JSON version of a highlighting style, which can be modified,
860saved with a \f[C].theme\f[R] extension, and used with
861\f[C]--highlight-style\f[R].
862This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
863output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
864\f[C]--print-highlight-style\f[R] on the command line.
866\f[B]\f[CB]--syntax-definition=\f[B]\f[R]\f[I]FILE\f[R]
867Instructs pandoc to load a KDE XML syntax definition file, which will be
868used for syntax highlighting of appropriately marked code blocks.
869This can be used to add support for new languages or to use altered
870syntax definitions for existing languages.
871This option may be repeated to add multiple syntax definitions.
873\f[B]\f[CB]-H\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-in-header=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
874Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.
875This can be used, for example, to include special CSS or JavaScript in
877This option can be used repeatedly to include multiple files in the
879They will be included in the order specified.
880Implies \f[C]--standalone\f[R].
882\f[B]\f[CB]-B\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-before-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
883Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the
885after the \f[C]<body>\f[R] tag in HTML, or the
886\f[C]\[rs]begin{document}\f[R] command in LaTeX).
887This can be used to include navigation bars or banners in HTML
889This option can be used repeatedly to include multiple files.
890They will be included in the order specified.
891Implies \f[C]--standalone\f[R].
893\f[B]\f[CB]-A\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-after-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
894Include contents of \f[I]FILE\f[R], verbatim, at the end of the document
895body (before the \f[C]</body>\f[R] tag in HTML, or the
896\f[C]\[rs]end{document}\f[R] command in LaTeX).
897This option can be used repeatedly to include multiple files.
898They will be included in the order specified.
899Implies \f[C]--standalone\f[R].
901\f[B]\f[CB]--resource-path=\f[B]\f[R]\f[I]SEARCHPATH\f[R]
902List of paths to search for images and other resources.
903The paths should be separated by \f[C]:\f[R] on Linux, UNIX, and macOS
904systems, and by \f[C];\f[R] on Windows.
905If \f[C]--resource-path\f[R] is not specified, the default resource path
906is the working directory.
907Note that, if \f[C]--resource-path\f[R] is specified, the working
908directory must be explicitly listed or it will not be searched.
909For example: \f[C]--resource-path=.:test\f[R] will search the working
910directory and the \f[C]test\f[R] subdirectory, in that order.
913\f[C]--resource-path\f[R] only has an effect if (a) the output format
914embeds images (for example, \f[C]docx\f[R], \f[C]pdf\f[R], or
915\f[C]html\f[R] with \f[C]--self-contained\f[R]) or (b) it is used
916together with \f[C]--extract-media\f[R].
919\f[B]\f[CB]--request-header=\f[B]\f[R]\f[I]NAME\f[R]\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]
920Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
921making HTTP requests (for example, when a URL is given on the command
922line, or when resources used in a document must be downloaded).
923If you\[aq]re behind a proxy, you also need to set the environment
924variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].
925.SS Options affecting specific writers
927\f[B]\f[CB]--self-contained\f[B]\f[R]
928Produce a standalone HTML file with no external dependencies, using
929\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,
930stylesheets, images, and videos.
931Implies \f[C]--standalone\f[R].
932The resulting file should be \[dq]self-contained,\[dq] in the sense that
933it needs no external files and no net access to be displayed properly by
935This option works only with HTML output formats, including
936\f[C]html4\f[R], \f[C]html5\f[R], \f[C]html+lhs\f[R],
937\f[C]html5+lhs\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
938\f[C]dzslides\f[R], and \f[C]revealjs\f[R].
939Scripts, images, and stylesheets at absolute URLs will be downloaded;
940those at relative URLs will be sought relative to the working directory
941(if the first source file is local) or relative to the base URL (if the
942first source file is remote).
943Elements with the attribute \f[C]data-external=\[dq]1\[dq]\f[R] will be
944left alone; the documents they link to will not be incorporated in the
946Limitation: resources that are loaded dynamically through JavaScript
947cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not
948work with \f[C]--mathjax\f[R], and some advanced features (e.g.
949zoom or speaker notes) may not work in an offline
950\[dq]self-contained\[dq] \f[C]reveal.js\f[R] slide show.
952\f[B]\f[CB]--html-q-tags\f[B]\f[R]
953Use \f[C]<q>\f[R] tags for quotes in HTML.
955\f[B]\f[CB]--ascii\f[B]\f[R]
956Use only ASCII characters in output.
957Currently supported for XML and HTML formats (which use entities instead
958of UTF-8 when this option is selected), CommonMark, gfm, and Markdown
959(which use entities), roff ms (which use hexadecimal escapes), and to a
960limited degree LaTeX (which uses standard commands for accented
961characters when possible).
962roff man output uses ASCII by default.
964\f[B]\f[CB]--reference-links\f[B]\f[R]
965Use reference-style links, rather than inline links, in writing Markdown
967By default inline links are used.
968The placement of link references is affected by the
969\f[C]--reference-location\f[R] option.
971\f[B]\f[CB]--reference-location = block\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]document\f[B]\f[R]
972Specify whether footnotes (and references, if \f[C]reference-links\f[R]
973is set) are placed at the end of the current (top-level) block, the
974current section, or the document.
975The default is \f[C]document\f[R].
976Currently only affects the markdown writer.
978\f[B]\f[CB]--atx-headers\f[B]\f[R]
979Use ATX-style headings in Markdown output.
980The default is to use setext-style headings for levels 1 to 2, and then
982(Note: for \f[C]gfm\f[R] output, ATX headings are always used.) This
983option also affects markdown cells in \f[C]ipynb\f[R] output.
985\f[B]\f[CB]--top-level-division=[default|section|chapter|part]\f[B]\f[R]
986Treat top-level headings as the given division type in LaTeX, ConTeXt,
987DocBook, and TEI output.
988The hierarchy order is part, chapter, then section; all headings are
989shifted such that the top-level heading becomes the specified type.
990The default behavior is to determine the best division type via
991heuristics: unless other conditions apply, \f[C]section\f[R] is chosen.
992When the \f[C]documentclass\f[R] variable is set to \f[C]report\f[R],
993\f[C]book\f[R], or \f[C]memoir\f[R] (unless the \f[C]article\f[R] option
994is specified), \f[C]chapter\f[R] is implied as the setting for this
996If \f[C]beamer\f[R] is the output format, specifying either
997\f[C]chapter\f[R] or \f[C]part\f[R] will cause top-level headings to
998become \f[C]\[rs]part{..}\f[R], while second-level headings remain as
1001\f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]
1002Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
1003By default, sections are not numbered.
1004Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
1005\f[C]--number-sections\f[R] is specified.
1007\f[B]\f[CB]--number-offset=\f[B]\f[R]\f[I]NUMBER\f[R][\f[B]\f[CB],\f[B]\f[R]\f[I]NUMBER\f[R]\f[B]\f[CB],\f[B]\f[R]\f[I]...\f[R]]
1008Offset for section headings in HTML output (ignored in other output
1010The first number is added to the section number for top-level headings,
1011the second for second-level headings, and so on.
1012So, for example, if you want the first top-level heading in your
1013document to be numbered \[dq]6\[dq], specify
1014\f[C]--number-offset=5\f[R].
1015If your document starts with a level-2 heading which you want to be
1016numbered \[dq]1.5\[dq], specify \f[C]--number-offset=1,4\f[R].
1017Offsets are 0 by default.
1018Implies \f[C]--number-sections\f[R].
1020\f[B]\f[CB]--listings\f[B]\f[R]
1021Use the \f[C]listings\f[R] package for LaTeX code blocks.
1022The package does not support multi-byte encoding for source code.
1023To handle UTF-8 you would need to use a custom template.
1024This issue is fully documented here: Encoding issue with the listings
1027\f[B]\f[CB]-i\f[B]\f[R], \f[B]\f[CB]--incremental\f[B]\f[R]
1028Make list items in slide shows display incrementally (one by one).
1029The default is for lists to be displayed all at once.
1031\f[B]\f[CB]--slide-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1032Specifies that headings with the specified level create slides (for
1033\f[C]beamer\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
1035Headings above this level in the hierarchy are used to divide the slide
1036show into sections; headings below this level create subheads within a
1038Note that content that is not contained under slide-level headings will
1039not appear in the slide show.
1040The default is to set the slide level based on the contents of the
1041document; see Structuring the slide show.
1043\f[B]\f[CB]--section-divs\f[B]\f[R]
1044Wrap sections in \f[C]<section>\f[R] tags (or \f[C]<div>\f[R] tags for
1045\f[C]html4\f[R]), and attach identifiers to the enclosing
1046\f[C]<section>\f[R] (or \f[C]<div>\f[R]) rather than the heading itself.
1047See Heading identifiers, below.
1049\f[B]\f[CB]--email-obfuscation=none\f[B]\f[R]|\f[B]\f[CB]javascript\f[B]\f[R]|\f[B]\f[CB]references\f[B]\f[R]
1050Specify a method for obfuscating \f[C]mailto:\f[R] links in HTML
1052\f[C]none\f[R] leaves \f[C]mailto:\f[R] links as they are.
1053\f[C]javascript\f[R] obfuscates them using JavaScript.
1054\f[C]references\f[R] obfuscates them by printing their letters as
1055decimal or hexadecimal character references.
1056The default is \f[C]none\f[R].
1058\f[B]\f[CB]--id-prefix=\f[B]\f[R]\f[I]STRING\f[R]
1059Specify a prefix to be added to all identifiers and internal links in
1060HTML and DocBook output, and to footnote numbers in Markdown and Haddock
1062This is useful for preventing duplicate identifiers when generating
1063fragments to be included in other pages.
1065\f[B]\f[CB]-T\f[B]\f[R] \f[I]STRING\f[R], \f[B]\f[CB]--title-prefix=\f[B]\f[R]\f[I]STRING\f[R]
1066Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that
1067appears in the HTML header (but not in the title as it appears at the
1068beginning of the HTML body).
1069Implies \f[C]--standalone\f[R].
1071\f[B]\f[CB]-c\f[B]\f[R] \f[I]URL\f[R], \f[B]\f[CB]--css=\f[B]\f[R]\f[I]URL\f[R]
1072Link to a CSS style sheet.
1073This option can be used repeatedly to include multiple files.
1074They will be included in the order specified.
1077A stylesheet is required for generating EPUB.
1078If none is provided using this option (or the \f[C]css\f[R] or
1079\f[C]stylesheet\f[R] metadata fields), pandoc will look for a file
1080\f[C]epub.css\f[R] in the user data directory (see
1081\f[C]--data-dir\f[R]).
1082If it is not found there, sensible defaults will be used.
1085\f[B]\f[CB]--reference-doc=\f[B]\f[R]\f[I]FILE\f[R]
1086Use the specified file as a style reference in producing a docx or ODT
1091For best results, the reference docx should be a modified version of a
1092docx file produced using pandoc.
1093The contents of the reference docx are ignored, but its stylesheets and
1094document properties (including margins, page size, header, and footer)
1095are used in the new docx.
1096If no reference docx is specified on the command line, pandoc will look
1097for a file \f[C]reference.docx\f[R] in the user data directory (see
1098\f[C]--data-dir\f[R]).
1099If this is not found either, sensible defaults will be used.
1102To produce a custom \f[C]reference.docx\f[R], first get a copy of the
1103default \f[C]reference.docx\f[R]:
1104\f[C]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R].
1105Then open \f[C]custom-reference.docx\f[R] in Word, modify the styles as
1106you wish, and save the file.
1107For best results, do not make changes to this file other than modifying
1108the styles used by pandoc:
1172Default Paragraph Font
1188For best results, the reference ODT should be a modified version of an
1189ODT produced using pandoc.
1190The contents of the reference ODT are ignored, but its stylesheets are
1192If no reference ODT is specified on the command line, pandoc will look
1193for a file \f[C]reference.odt\f[R] in the user data directory (see
1194\f[C]--data-dir\f[R]).
1195If this is not found either, sensible defaults will be used.
1198To produce a custom \f[C]reference.odt\f[R], first get a copy of the
1199default \f[C]reference.odt\f[R]:
1200\f[C]pandoc -o custom-reference.odt --print-default-data-file reference.odt\f[R].
1201Then open \f[C]custom-reference.odt\f[R] in LibreOffice, modify the
1202styles as you wish, and save the file.
1206Templates included with Microsoft PowerPoint 2013 (either with
1207\f[C].pptx\f[R] or \f[C].potx\f[R] extension) are known to work, as are
1208most templates derived from these.
1211The specific requirement is that the template should begin with the
1212following first four layouts:
1222All templates included with a recent version of MS PowerPoint will fit
1224(You can click on \f[C]Layout\f[R] under the \f[C]Home\f[R] menu to
1227You can also modify the default \f[C]reference.pptx\f[R]: first run
1228\f[C]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R],
1229and then modify \f[C]custom-reference.pptx\f[R] in MS PowerPoint (pandoc
1230will use the first four layout slides, as mentioned above).
1234\f[B]\f[CB]--epub-cover-image=\f[B]\f[R]\f[I]FILE\f[R]
1235Use the specified image as the EPUB cover.
1236It is recommended that the image be less than 1000px in width and
1238Note that in a Markdown source document you can also specify
1239\f[C]cover-image\f[R] in a YAML metadata block (see EPUB Metadata,
1242\f[B]\f[CB]--epub-metadata=\f[B]\f[R]\f[I]FILE\f[R]
1243Look in the specified XML file for metadata for the EPUB.
1244The file should contain a series of Dublin Core elements.
1250 <dc:rights>Creative Commons</dc:rights>
1251 <dc:language>es-AR</dc:language>
1255By default, pandoc will include the following metadata elements:
1256\f[C]<dc:title>\f[R] (from the document title), \f[C]<dc:creator>\f[R]
1257(from the document authors), \f[C]<dc:date>\f[R] (from the document
1258date, which should be in ISO 8601 format), \f[C]<dc:language>\f[R] (from
1259the \f[C]lang\f[R] variable, or, if is not set, the locale), and
1260\f[C]<dc:identifier id=\[dq]BookId\[dq]>\f[R] (a randomly generated
1262Any of these may be overridden by elements in the metadata file.
1264Note: if the source document is Markdown, a YAML metadata block in the
1265document can be used instead.
1266See below under EPUB Metadata.
1269\f[B]\f[CB]--epub-embed-font=\f[B]\f[R]\f[I]FILE\f[R]
1270Embed the specified font in the EPUB.
1271This option can be repeated to embed multiple fonts.
1272Wildcards can also be used: for example, \f[C]DejaVuSans-*.ttf\f[R].
1273However, if you use wildcards on the command line, be sure to escape
1274them or put the whole filename in single quotes, to prevent them from
1275being interpreted by the shell.
1276To use the embedded fonts, you will need to add declarations like the
1277following to your CSS (see \f[C]--css\f[R]):
1283font-family: DejaVuSans;
1286src:url(\[dq]DejaVuSans-Regular.ttf\[dq]);
1289font-family: DejaVuSans;
1292src:url(\[dq]DejaVuSans-Bold.ttf\[dq]);
1295font-family: DejaVuSans;
1298src:url(\[dq]DejaVuSans-Oblique.ttf\[dq]);
1301font-family: DejaVuSans;
1304src:url(\[dq]DejaVuSans-BoldOblique.ttf\[dq]);
1306body { font-family: \[dq]DejaVuSans\[dq]; }
1311\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1312Specify the heading level at which to split the EPUB into separate
1313\[dq]chapter\[dq] files.
1314The default is to split into chapters at level-1 headings.
1315This option only affects the internal composition of the EPUB, not the
1316way chapters and sections are displayed to users.
1317Some readers may be slow if the chapter files are too large, so for
1318large documents with few level-1 headings, one might want to use a
1319chapter level of 2 or 3.
1321\f[B]\f[CB]--epub-subdirectory=\f[B]\f[R]\f[I]DIRNAME\f[R]
1322Specify the subdirectory in the OCF container that is to hold the
1323EPUB-specific contents.
1324The default is \f[C]EPUB\f[R].
1325To put the EPUB contents in the top level, use an empty string.
1327\f[B]\f[CB]--ipynb-output=all|none|best\f[B]\f[R]
1328Determines how ipynb output cells are treated.
1329\f[C]all\f[R] means that all of the data formats included in the
1330original are preserved.
1331\f[C]none\f[R] means that the contents of data cells are omitted.
1332\f[C]best\f[R] causes pandoc to try to pick the richest data block in
1333each output cell that is compatible with the output format.
1334The default is \f[C]best\f[R].
1336\f[B]\f[CB]--pdf-engine=\f[B]\f[R]\f[I]PROGRAM\f[R]
1337Use the specified engine when producing PDF output.
1338Valid values are \f[C]pdflatex\f[R], \f[C]lualatex\f[R],
1339\f[C]xelatex\f[R], \f[C]latexmk\f[R], \f[C]tectonic\f[R],
1340\f[C]wkhtmltopdf\f[R], \f[C]weasyprint\f[R], \f[C]prince\f[R],
1341\f[C]context\f[R], and \f[C]pdfroff\f[R].
1342If the engine is not in your PATH, the full path of the engine may be
1344If this option is not specified, pandoc uses the following defaults
1345depending on the output format specified using \f[C]-t/--to\f[R]:
1348\f[C]-t latex\f[R] or none: \f[C]pdflatex\f[R] (other options:
1349\f[C]xelatex\f[R], \f[C]lualatex\f[R], \f[C]tectonic\f[R],
1352\f[C]-t context\f[R]: \f[C]context\f[R]
1354\f[C]-t html\f[R]: \f[C]wkhtmltopdf\f[R] (other options:
1355\f[C]prince\f[R], \f[C]weasyprint\f[R])
1357\f[C]-t ms\f[R]: \f[C]pdfroff\f[R]
1360\f[B]\f[CB]--pdf-engine-opt=\f[B]\f[R]\f[I]STRING\f[R]
1361Use the given string as a command-line argument to the
1362\f[C]pdf-engine\f[R].
1363For example, to use a persistent directory \f[C]foo\f[R] for
1364\f[C]latexmk\f[R]\[aq]s auxiliary files, use
1365\f[C]--pdf-engine-opt=-outdir=foo\f[R].
1366Note that no check for duplicate options is done.
1367.SS Citation rendering
1369\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]
1370Set the \f[C]bibliography\f[R] field in the document\[aq]s metadata to
1371\f[I]FILE\f[R], overriding any value set in the metadata, and process
1372citations using \f[C]pandoc-citeproc\f[R].
1373(This is equivalent to
1374\f[C]--metadata bibliography=FILE --filter pandoc-citeproc\f[R].) If
1375\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] is also supplied,
1376\f[C]pandoc-citeproc\f[R] is not used, making this equivalent to
1377\f[C]--metadata bibliography=FILE\f[R].
1378If you supply this argument multiple times, each \f[I]FILE\f[R] will be
1379added to bibliography.
1381\f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R]
1382Set the \f[C]csl\f[R] field in the document\[aq]s metadata to
1383\f[I]FILE\f[R], overriding any value set in the metadata.
1384(This is equivalent to \f[C]--metadata csl=FILE\f[R].) This option is
1385only relevant with \f[C]pandoc-citeproc\f[R].
1387\f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
1388Set the \f[C]citation-abbreviations\f[R] field in the document\[aq]s
1389metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
1390(This is equivalent to
1391\f[C]--metadata citation-abbreviations=FILE\f[R].) This option is only
1392relevant with \f[C]pandoc-citeproc\f[R].
1394\f[B]\f[CB]--natbib\f[B]\f[R]
1395Use \f[C]natbib\f[R] for citations in LaTeX output.
1396This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1398It is intended for use in producing a LaTeX file that can be processed
1399with \f[C]bibtex\f[R].
1401\f[B]\f[CB]--biblatex\f[B]\f[R]
1402Use \f[C]biblatex\f[R] for citations in LaTeX output.
1403This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1405It is intended for use in producing a LaTeX file that can be processed
1406with \f[C]bibtex\f[R] or \f[C]biber\f[R].
1407.SS Math rendering in HTML
1409The default is to render TeX math as far as possible using Unicode
1411Formulas are put inside a \f[C]span\f[R] with
1412\f[C]class=\[dq]math\[dq]\f[R], so that they may be styled differently
1413from the surrounding text if needed.
1414However, this gives acceptable results only for basic math, usually you
1415will want to use \f[C]--mathjax\f[R] or another of the following
1418\f[B]\f[CB]--mathjax\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1419Use MathJax to display embedded TeX math in HTML output.
1420TeX math will be put between \f[C]\[rs](...\[rs])\f[R] (for inline math)
1421or \f[C]\[rs][...\[rs]]\f[R] (for display math) and wrapped in
1422\f[C]<span>\f[R] tags with class \f[C]math\f[R].
1423Then the MathJax JavaScript will render it.
1424The \f[I]URL\f[R] should point to the \f[C]MathJax.js\f[R] load script.
1425If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be
1428\f[B]\f[CB]--mathml\f[B]\f[R]
1429Convert TeX math to MathML (in \f[C]epub3\f[R], \f[C]docbook4\f[R],
1430\f[C]docbook5\f[R], \f[C]jats\f[R], \f[C]html4\f[R] and
1432This is the default in \f[C]odt\f[R] output.
1433Note that currently only Firefox and Safari (and select e-book readers)
1434natively support MathML.
1436\f[B]\f[CB]--webtex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1437Convert TeX formulas to \f[C]<img>\f[R] tags that link to an external
1438script that converts formulas to images.
1439The formula will be URL-encoded and concatenated with the URL provided.
1440For SVG images you can for example use
1441\f[C]--webtex https://latex.codecogs.com/svg.latex?\f[R].
1442If no URL is specified, the CodeCogs URL generating PNGs will be used
1443(\f[C]https://latex.codecogs.com/png.latex?\f[R]).
1444Note: the \f[C]--webtex\f[R] option will affect Markdown output as well
1445as HTML, which is useful if you\[aq]re targeting a version of Markdown
1446without native math support.
1448\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1449Use KaTeX to display embedded TeX math in HTML output.
1450The \f[I]URL\f[R] is the base URL for the KaTeX library.
1451That directory should contain a \f[C]katex.min.js\f[R] and a
1452\f[C]katex.min.css\f[R] file.
1453If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be
1456\f[B]\f[CB]--gladtex\f[B]\f[R]
1457Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.
1458The resulting HTML can then be processed by GladTeX to produce images of
1459the typeset formulas and an HTML file with links to these images.
1460So, the procedure is:
1465pandoc -s --gladtex input.md -o myfile.htex
1466gladtex -d myfile-images myfile.htex
1467# produces myfile.html and images in myfile-images
1471.SS Options for wrapper scripts
1473\f[B]\f[CB]--dump-args\f[B]\f[R]
1474Print information about command-line arguments to \f[I]stdout\f[R], then
1476This option is intended primarily for use in wrapper scripts.
1477The first line of output contains the name of the output file specified
1478with the \f[C]-o\f[R] option, or \f[C]-\f[R] (for \f[I]stdout\f[R]) if
1479no output file was specified.
1480The remaining lines contain the command-line arguments, one per line, in
1481the order they appear.
1482These do not include regular pandoc options and their arguments, but do
1483include any options appearing after a \f[C]--\f[R] separator at the end
1486\f[B]\f[CB]--ignore-args\f[B]\f[R]
1487Ignore command-line arguments (for use in wrapper scripts).
1488Regular pandoc options are not ignored.
1494pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1502pandoc -o foo.html -s
1508If pandoc completes successfully, it will return exit code 0.
1509Nonzero exit codes have the following meanings:
1523PandocFailOnWarningError
1543PandocUnknownReaderError
1548PandocUnknownWriterError
1553PandocUnsupportedExtensionError
1558PandocEpubSubdirectoryError
1568PandocPDFProgramNotFoundError
1578PandocShouldNeverHappenError
1618PandocUTF8DecodingError
1623PandocIpynbDecodingError
1628PandocCouldNotFindDataFileError
1633PandocResourceNotFound
1638The \f[C]--defaults\f[R] option may be used to specify a package of
1640Here is a sample defaults file demonstrating all of the fields that may
1646# reader: may be used instead of from:
1648# writer: may be used instead of to:
1650# leave blank for output to stdout:
1652# leave blank for input from stdin, use [] for no input:
1656# or you may use input-file: with a single value
1660self-contained: false
1662# note that structured variables may be specified:
1669# metadata values specified here are parsed as literal
1670# string text, not markdown:
1677# or you may use metadata-file: with a single value
1679# Note that these take files, not their contents:
1680include-before-body: []
1681include-after-body: []
1682include-in-header: []
1683resource-path: [\[dq].\[dq]]
1685# filters will be assumed to be lua filters if they have
1686# the .lua extension, and json filters otherwise. But
1687# the filter type can also be specified explicitly, as shown:
1698# ERROR, WARNING, or INFO
1702# citeproc, natbib, or biblatex
1703cite-method: citeproc
1704# part, chapter, section, or default:
1705top-level-division: chapter
1710- \[dq]-shell-escape\[dq]
1711# you may also use pdf-engine-opt: with a single option
1712# pdf-engine-opt: \[dq]-shell-escape\[dq]
1714# auto, preserve, or none
1719extract-media: mediadir
1721table-of-contents: true
1723number-sections: false
1724# a list of offsets at each heading level
1725number-offset: [0,0,0,0,0,0]
1726# toc: may also be used instead of table-of-contents:
1727shift-heading-level-by: 1
1729identifier-prefix: foo
1730title-prefix: \[dq]\[dq]
1731strip-empty-paragraphs: true
1732# lf, crlf, or native
1734strip-comments: false
1735indented-code-classes: []
1737default-image-extension: \[dq].jpg\[dq]
1739# either a style name of a style definition file:
1740highlight-style: pygments
1743# or you may use syntax-definition: with a single value
1746reference-doc: myref.docx
1748# method is plain, webtex, gladtex, mathml, mathjax, katex
1749# you may specify a url with webtex, mathjax, katex
1752 url: \[dq]https://cdn.jsdelivr.net/npm/mathjax\[at]3/es5/tex-mml-chtml.js\[dq]
1753# none, references, or javascript
1754email-obfuscation: javascript
1762epub-subdirectory: EPUB
1763epub-metadata: meta.xml
1766epub-chapter-level: 1
1767epub-cover-image: cover.jpg
1769reference-links: true
1770# block, section, or document
1771reference-location: block
1774# accept, reject, or all
1775track-changes: accept
1784# A list of two-element lists
1786- [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]
1788fail-if-warnings: false
1795Fields that are omitted will just have their regular default values.
1796So a defaults file can be as simple as one line:
1804Default files can be placed in the \f[C]defaults\f[R] subdirectory of
1805the user data directory and used from any directory.
1806For example, one could create a file specifying defaults for writing
1807letters, save it as \f[C]letter.yaml\f[R] in the \f[C]defaults\f[R]
1808subdirectory of the user data directory, and then invoke these defaults
1809from any directory using \f[C]pandoc --defaults letter\f[R] or
1810\f[C]pandoc -dletter\f[R].
1812When multiple defaults are used, their contents will be combined.
1814Note that, where command-line arguments may be repeated
1815(\f[C]--metadata-file\f[R], \f[C]--css\f[R],
1816\f[C]--include-in-header\f[R], \f[C]--include-before-body\f[R],
1817\f[C]--include-after-body\f[R], \f[C]--variable\f[R],
1818\f[C]--metadata\f[R], \f[C]--syntax-definition\f[R]), the values
1819specified on the command line will combine with values specified in the
1820defaults file, rather than replacing them.
1823When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a
1824template to add header and footer material that is needed for a
1825self-standing document.
1826To see the default template that is used, just type
1834where \f[I]FORMAT\f[R] is the name of the output format.
1835A custom template can be specified using the \f[C]--template\f[R]
1837You can also override the system default templates for a given output
1838format \f[I]FORMAT\f[R] by putting a file
1839\f[C]templates/default.*FORMAT*\f[R] in the user data directory (see
1840\f[C]--data-dir\f[R], above).
1841\f[I]Exceptions:\f[R]
1843For \f[C]odt\f[R] output, customize the \f[C]default.opendocument\f[R]
1846For \f[C]pdf\f[R] output, customize the \f[C]default.latex\f[R] template
1847(or the \f[C]default.context\f[R] template, if you use
1848\f[C]-t context\f[R], or the \f[C]default.ms\f[R] template, if you use
1849\f[C]-t ms\f[R], or the \f[C]default.html\f[R] template, if you use
1852\f[C]docx\f[R] and \f[C]pptx\f[R] have no template (however, you can use
1853\f[C]--reference-doc\f[R] to customize the output).
1855Templates contain \f[I]variables\f[R], which allow for the inclusion of
1856arbitrary information at any point in the file.
1857They may be set at the command line using the \f[C]-V/--variable\f[R]
1859If a variable is not set, pandoc will look for the key in the
1860document\[aq]s metadata, which can be set using either YAML metadata
1861blocks or with the \f[C]-M/--metadata\f[R] option.
1862In addition, some variables are given default values by pandoc.
1863See Variables below for a list of variables used in pandoc\[aq]s default
1866If you use custom templates, you may need to revise them as pandoc
1868We recommend tracking the changes in the default templates, and
1869modifying your custom templates accordingly.
1870An easy way to do this is to fork the pandoc-templates repository and
1871merge in changes after each pandoc release.
1875Anything between the sequence \f[C]$--\f[R] and the end of the line will
1876be treated as a comment and omitted from the output.
1879To mark variables and control structures in the template, either
1880\f[C]$\f[R]...\f[C]$\f[R] or \f[C]${\f[R]...\f[C]}\f[R] may be used as
1882The styles may also be mixed in the same template, but the opening and
1883closing delimiter must match in each case.
1884The opening delimiter may be followed by one or more spaces or tabs,
1885which will be ignored.
1886The closing delimiter may be followed by one or more spaces or tabs,
1887which will be ignored.
1889To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].
1890.SS Interpolated variables
1892A slot for an interpolated variable is a variable name surrounded by
1894Variable names must begin with a letter and can contain letters,
1895numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].
1896The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],
1897\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may
1898not be used as variable names.
1914Variable names with periods are used to get at structured variable
1916So, for example, \f[C]employee.salary\f[R] will return the value of the
1917\f[C]salary\f[R] field of the object that is the value of the
1918\f[C]employee\f[R] field.
1920If the value of the variable is simple value, it will be rendered
1922(Note that no escaping is done; the assumption is that the calling
1923program will escape the strings appropriately for the output format.)
1925If the value is a list, the values will be concatenated.
1927If the value is a map, the string \f[C]true\f[R] will be rendered.
1929Every other value will be rendered as the empty string.
1932A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched
1933delimiters) and ends with \f[C]endif\f[R] (enclosed in matched
1935It may optionally contain an \f[C]else\f[R] (enclosed in matched
1937The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty
1938value, otherwise the \f[C]else\f[R] section is used (if present).
1955${if(foo)}bar${endif}
1969The keyword \f[C]elseif\f[R] may be used to simplify complex nested
1985A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched
1986delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched
1989If \f[C]variable\f[R] is an array, the material inside the loop will be
1990evaluated repeatedly, with \f[C]variable\f[R] being set to each value of
1991the array in turn, and concatenated.
1993If \f[C]variable\f[R] is a map, the material inside will be set to the
1996If the value of the associated variable is not an array or a map, a
1997single iteration will be performed on its value.
2003$for(foo)$$foo$$sep$, $endfor$
2006 - $foo.last$, $foo.first$
2010 - ${ foo.bar.last }, ${ foo.bar.first }
2014$it.name$: $it.office$
2019You may optionally specify a separator between consecutive values using
2020\f[C]sep\f[R] (enclosed in matched delimiters).
2021The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the
2026${ for(foo) }${ foo }${ sep }, ${ endfor }
2030Instead of using \f[C]variable\f[R] inside the loop, the special
2031anaphoric keyword \f[C]it\f[R] may be used.
2036 - ${ it.last }, ${ it.first }
2042Partials (subtemplates stored in different files) may be included using
2051Partials will be sought in the directory containing the main template,
2052and will be assumed to have the same extension as the main template if
2053they lack an explicit extension.
2054(If the partials are not found here, they will also be sought in the
2055\f[C]templates\f[R] subdirectory of the user data directory.)
2057Partials may optionally be applied to variables using a colon:
2063${ articles:bibentry() }
2067If \f[C]articles\f[R] is an array, this will iterate over its values,
2068applying the partial \f[C]bibentry()\f[R] to each one.
2069So the second example above is equivalent to
2079Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating
2081In the above examples, the \f[C]bibentry\f[R] partial should contain
2082\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].
2084Final newlines are omitted from included partials.
2086Partials may include other partials.
2088A separator between values of an array may be specified in square
2089brackets, immediately after the variable name or partial:
2095${articles:bibentry()[; ]$
2099The separator in this case is literal and (unlike with \f[C]sep\f[R] in
2100an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or
2101other template directives.
2104To ensure that content is \[dq]nested,\[dq] that is, subsequent lines
2105indented, use the \f[C]\[ha]\f[R] directive:
2109$item.number$ $\[ha]$$item.description$ ($item.price$)
2113In this example, if \f[C]item.description\f[R] has multiple lines, they
2114will all be indented to line up with the first line:
211800123 A fine bottle of 18-year old
2119 Oban whiskey. ($148)
2123To nest multiple lines to the same level, align them with the
2124\f[C]\[ha]\f[R] directive in the template.
2129$item.number$ $\[ha]$$item.description$ ($item.price$)
2130 (Available til $item.sellby$.)
213800123 A fine bottle of 18-year old
2139 Oban whiskey. ($148)
2140 (Available til March 30, 2020.)
2144If a variable occurs by itself on a line, preceded by whitespace and not
2145followed by further text or directives on the same line, and the
2146variable\[aq]s value contains multiple lines, it will be nested
2150Normally, spaces in the template itself (as opposed to values of the
2151interpolated variables) are not breakable, but they can be made
2152breakable in part of the template by using the \f[C]\[ti]\f[R] keyword
2153(ended with another \f[C]\[ti]\f[R]).
2157$\[ti]$This long line may break if the document is rendered
2158with a short line length.$\[ti]$
2163A pipe transforms the value of a variable or partial.
2164Pipes are specified using a slash (\f[C]/\f[R]) between the variable
2165name (or partial) and the pipe name.
2174$for(metadata/pairs)$
2175- $it.key$: $it.value$
2178$employee:name()/uppercase$
2182Pipes may be chained:
2186$for(employees/pairs)$
2187$it.key/alpha/uppercase$. $it.name$
2192Some pipes take parameters:
2196|----------------------|------------|
2198$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$
2200|----------------------|------------|
2204Currently the following pipes are predefined:
2206\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with
2207\f[C]key\f[R] and \f[C]value\f[R] fields.
2208If the original value was an array, the \f[C]key\f[R] will be the array
2209index, starting with 1.
2211\f[C]uppercase\f[R]: Converts text to uppercase.
2213\f[C]lowercase\f[R]: Converts text to lowercase.
2215\f[C]length\f[R]: Returns the length of the value: number of characters
2216for a textual value, number of elements for a map or array.
2218\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect
2221\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).
2223\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.
2225\f[C]alpha\f[R]: Converts textual values that can be read as an integer
2226into lowercase alphabetic characters \f[C]a..z\f[R] (mod 26).
2227This can be used to get lettered enumeration from array indices.
2228To get uppercase letters, chain with \f[C]uppercase\f[R].
2230\f[C]roman\f[R]: Converts textual values that can be read as an integer
2231into lowercase roman numerials.
2232This can be used to get lettered enumeration from array indices.
2233To get uppercase roman, chain with \f[C]uppercase\f[R].
2235\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2236textual value in a block of width \f[C]n\f[R], aligned to the left, with
2237an optional left and right border.
2238Has no effect on other values.
2239This can be used to align material in tables.
2240Widths are positive integers indicating the number of characters.
2241Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and
2242\f[C]\[rs]\f[R] characters must be backslash-escaped.
2244\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2245textual value in a block of width \f[C]n\f[R], aligned to the right, and
2246has no effect on other values.
2248\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2249textual value in a block of width \f[C]n\f[R], aligned to the center,
2250and has no effect on other values.
2252.SS Metadata variables
2254\f[B]\f[CB]title\f[B]\f[R], \f[B]\f[CB]author\f[B]\f[R], \f[B]\f[CB]date\f[B]\f[R]
2255allow identification of basic aspects of the document.
2256Included in PDF metadata through LaTeX and ConTeXt.
2257These can be set through a pandoc title block, which allows for multiple
2258authors, or through a YAML metadata block:
2271Note that if you just want to set PDF or HTML metadata, without
2272including a title block in the document itself, you can set the
2273\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]
2275(By default these are set automatically, based on \f[C]title\f[R],
2276\f[C]author\f[R], and \f[C]date\f[R].)
2279\f[B]\f[CB]subtitle\f[B]\f[R]
2280document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx
2283\f[B]\f[CB]abstract\f[B]\f[R]
2284document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
2287\f[B]\f[CB]keywords\f[B]\f[R]
2288list of keywords to be included in HTML, PDF, ODT, pptx, docx and
2289AsciiDoc metadata; repeat as for \f[C]author\f[R], above
2291\f[B]\f[CB]subject\f[B]\f[R]
2292document subject, included in ODT, PDF, docx and pptx metadata
2294\f[B]\f[CB]description\f[B]\f[R]
2295document description, included in ODT, docx and pptx metadata.
2296Some applications show this as \f[C]Comments\f[R] metadata.
2298\f[B]\f[CB]category\f[B]\f[R]
2299document category, included in docx and pptx metadata
2301Additionally, any root-level string metadata, not included in ODT, docx
2302or pptx metadata is added as a \f[I]custom property\f[R].
2303The following YAML metadata block for instance:
2308title: \[aq]This is the title\[aq]
2309subtitle: \[dq]This is the subtitle\[dq]
2317 It consists of two paragraphs
2322will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]
2323as standard document properties and \f[C]subtitle\f[R] as a custom
2324property when converting to docx, ODT or pptx.
2325.SS Language variables
2327\f[B]\f[CB]lang\f[B]\f[R]
2328identifies the main language of the document using IETF language tags
2329(following the BCP 47 standard), such as \f[C]en\f[R] or
2331The Language subtag lookup tool can look up or verify these tags.
2332This affects most formats, and controls hyphenation in PDF output when
2333using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or
2337Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to
2346Text in the main document language (British English).
2349> Cette citation est \['e]crite en fran\[,c]ais canadien.
2352More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}
2357\f[B]\f[CB]dir\f[B]\f[R]
2358the base script direction, either \f[C]rtl\f[R] (right-to-left) or
2359\f[C]ltr\f[R] (left-to-right).
2362For bidirectional documents, native pandoc \f[C]span\f[R]s and
2363\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or
2364\f[C]ltr\f[R]) can be used to override the base direction in some output
2366This may not always be necessary if the final renderer (e.g.
2367the browser, when generating HTML) supports the Unicode Bidirectional
2370When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
2371engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
2373.SS Variables for HTML math
2375\f[B]\f[CB]classoption\f[B]\f[R]
2376when using KaTeX, you can render display math equations flush left using
2377YAML metadata or with \f[C]-M classoption=fleqn\f[R].
2378.SS Variables for HTML slides
2380These affect HTML output when producing slide shows with pandoc.
2382All reveal.js configuration options are available as variables.
2383To turn off boolean flags that default to true in reveal.js, use
2386\f[B]\f[CB]revealjs-url\f[B]\f[R]
2387base URL for reveal.js documents (defaults to \f[C]reveal.js\f[R])
2389\f[B]\f[CB]s5-url\f[B]\f[R]
2390base URL for S5 documents (defaults to \f[C]s5/default\f[R])
2392\f[B]\f[CB]slidy-url\f[B]\f[R]
2393base URL for Slidy documents (defaults to
2394\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])
2396\f[B]\f[CB]slideous-url\f[B]\f[R]
2397base URL for Slideous documents (defaults to \f[C]slideous\f[R])
2399\f[B]\f[CB]title-slide-attributes\f[B]\f[R]
2400additional attributes for the title slide of reveal.js slide shows.
2401See background in reveal.js and beamer for an example.
2402.SS Variables for Beamer slides
2404These variables change the appearance of PDF slides using
2407\f[B]\f[CB]aspectratio\f[B]\f[R]
2408slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for
240916:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]
2410for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)
2412\f[B]\f[CB]beamerarticle\f[B]\f[R]
2413produce an article from Beamer slides
2415\f[B]\f[CB]beameroption\f[B]\f[R]
2416add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]
2418\f[B]\f[CB]institute\f[B]\f[R]
2419author affiliations: can be a list when there are multiple authors
2421\f[B]\f[CB]logo\f[B]\f[R]
2422logo image for slides
2424\f[B]\f[CB]navigation\f[B]\f[R]
2425controls navigation symbols (default is \f[C]empty\f[R] for no
2426navigation symbols; other valid values are \f[C]frame\f[R],
2427\f[C]vertical\f[R], and \f[C]horizontal\f[R])
2429\f[B]\f[CB]section-titles\f[B]\f[R]
2430enables \[dq]title pages\[dq] for new sections (default is true)
2432\f[B]\f[CB]theme\f[B]\f[R], \f[B]\f[CB]colortheme\f[B]\f[R], \f[B]\f[CB]fonttheme\f[B]\f[R], \f[B]\f[CB]innertheme\f[B]\f[R], \f[B]\f[CB]outertheme\f[B]\f[R]
2435\f[B]\f[CB]themeoptions\f[B]\f[R]
2436options for LaTeX beamer themes (a list).
2438\f[B]\f[CB]titlegraphic\f[B]\f[R]
2439image for title slide
2440.SS Variables for PowerPoint
2442These variables control the visual aspects of a slide show that are not
2443easily controlled via templates.
2445\f[B]\f[CB]monofont\f[B]\f[R]
2446font to use for code.
2447.SS Variables for LaTeX
2449Pandoc uses these variables when creating a PDF with a LaTeX engine.
2452\f[B]\f[CB]block-headings\f[B]\f[R]
2453make \f[C]\[rs]paragraph\f[R] and \f[C]\[rs]subparagraph\f[R] (fourth-
2454and fifth-level headings, or fifth- and sixth-level with book classes)
2455free-standing rather than run-in; requires further formatting to
2456distinguish from \f[C]\[rs]subsubsection\f[R] (third- or fourth-level
2458Instead of using this option, KOMA-Script can adjust headings more
2465documentclass: scrartcl
2467 \[rs]RedeclareSectionCommand[
2468 beforeskip=-10pt plus -2pt minus -1pt,
2469 afterskip=1sp plus -1sp minus 1sp,
2470 font=\[rs]normalfont\[rs]itshape]{paragraph}
2471 \[rs]RedeclareSectionCommand[
2472 beforeskip=-10pt plus -2pt minus -1pt,
2473 afterskip=1sp plus -1sp minus 1sp,
2474 font=\[rs]normalfont\[rs]scshape,
2475 indent=0pt]{subparagraph}
2481\f[B]\f[CB]classoption\f[B]\f[R]
2482option for document class, e.g.
2483\f[C]oneside\f[R]; repeat for multiple options:
2497\f[B]\f[CB]documentclass\f[B]\f[R]
2498document class: usually one of the standard classes, \f[C]article\f[R],
2499\f[C]book\f[R], and \f[C]report\f[R]; the KOMA-Script equivalents,
2500\f[C]scrartcl\f[R], \f[C]scrbook\f[R], and \f[C]scrreprt\f[R], which
2501default to smaller margins; or \f[C]memoir\f[R]
2503\f[B]\f[CB]geometry\f[B]\f[R]
2504option for \f[C]geometry\f[R] package, e.g.
2505\f[C]margin=1in\f[R]; repeat for multiple options:
2520\f[B]\f[CB]hyperrefoptions\f[B]\f[R]
2521option for \f[C]hyperref\f[R] package, e.g.
2522\f[C]linktoc=all\f[R]; repeat for multiple options:
2531- pdfpagemode=FullScreen
2537\f[B]\f[CB]indent\f[B]\f[R]
2538uses document class settings for indentation (the default LaTeX template
2539otherwise removes indentation and adds space between paragraphs)
2541\f[B]\f[CB]linestretch\f[B]\f[R]
2542adjusts line spacing using the \f[C]setspace\f[R] package, e.g.
2543\f[C]1.25\f[R], \f[C]1.5\f[R]
2545\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]
2546sets margins if \f[C]geometry\f[R] is not used (otherwise
2547\f[C]geometry\f[R] overrides these)
2549\f[B]\f[CB]pagestyle\f[B]\f[R]
2550control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports
2551\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page
2552numbers), and \f[C]headings\f[R] (section titles in running heads)
2554\f[B]\f[CB]papersize\f[B]\f[R]
2556\f[C]letter\f[R], \f[C]a4\f[R]
2558\f[B]\f[CB]secnumdepth\f[B]\f[R]
2559numbering depth for sections (with \f[C]--number-sections\f[R] option or
2560\f[C]numbersections\f[R] variable)
2563\f[B]\f[CB]fontenc\f[B]\f[R]
2564allows font encoding to be specified through \f[C]fontenc\f[R] package
2565(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font
2568\f[B]\f[CB]fontfamily\f[B]\f[R]
2569font package for use with \f[C]pdflatex\f[R]: TeX Live includes many
2570options, documented in the LaTeX Font Catalogue.
2571The default is Latin Modern.
2573\f[B]\f[CB]fontfamilyoptions\f[B]\f[R]
2574options for package used as \f[C]fontfamily\f[R]; repeat for multiple
2576For example, to use the Libertine font with proportional lowercase
2577(old-style) figures through the \f[C]libertinus\f[R] package:
2583fontfamily: libertinus
2592\f[B]\f[CB]fontsize\f[B]\f[R]
2593font size for body text.
2594The standard classes allow 10pt, 11pt, and 12pt.
2595To use another size, set \f[C]documentclass\f[R] to one of the
2596KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].
2598\f[B]\f[CB]mainfont\f[B]\f[R], \f[B]\f[CB]sansfont\f[B]\f[R], \f[B]\f[CB]monofont\f[B]\f[R], \f[B]\f[CB]mathfont\f[B]\f[R], \f[B]\f[CB]CJKmainfont\f[B]\f[R]
2599font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take
2600the name of any system font, using the \f[C]fontspec\f[R] package.
2601\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.
2603\f[B]\f[CB]mainfontoptions\f[B]\f[R], \f[B]\f[CB]sansfontoptions\f[B]\f[R], \f[B]\f[CB]monofontoptions\f[B]\f[R], \f[B]\f[CB]mathfontoptions\f[B]\f[R], \f[B]\f[CB]CJKoptions\f[B]\f[R]
2604options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],
2605\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in
2606\f[C]xelatex\f[R] and \f[C]lualatex\f[R].
2607Allow for any choices available through \f[C]fontspec\f[R]; repeat for
2609For example, to use the TeX Gyre version of Palatino with lowercase
2616mainfont: TeX Gyre Pagella
2619- Numbers=Proportional
2625\f[B]\f[CB]microtypeoptions\f[B]\f[R]
2626options to pass to the microtype package
2629\f[B]\f[CB]colorlinks\f[B]\f[R]
2630add color to link text; automatically enabled if any of
2631\f[C]linkcolor\f[R], \f[C]filecolor\f[R], \f[C]citecolor\f[R],
2632\f[C]urlcolor\f[R], or \f[C]toccolor\f[R] are set
2634\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]filecolor\f[B]\f[R], \f[B]\f[CB]citecolor\f[B]\f[R], \f[B]\f[CB]urlcolor\f[B]\f[R], \f[B]\f[CB]toccolor\f[B]\f[R]
2635color for internal links, external links, citation links, linked URLs,
2636and links in table of contents, respectively: uses options allowed by
2637\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],
2638\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists
2640\f[B]\f[CB]links-as-notes\f[B]\f[R]
2641causes links to be printed as footnotes
2644\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2645include list of figures, list of tables
2647\f[B]\f[CB]thanks\f[B]\f[R]
2648contents of acknowledgments footnote after document title
2650\f[B]\f[CB]toc\f[B]\f[R]
2651include table of contents (can also be set using
2652\f[C]--toc/--table-of-contents\f[R])
2654\f[B]\f[CB]toc-depth\f[B]\f[R]
2655level of section to include in table of contents
2656.SS BibLaTeX Bibliographies
2658These variables function when using BibLaTeX for citation rendering.
2660\f[B]\f[CB]biblatexoptions\f[B]\f[R]
2661list of options for biblatex
2663\f[B]\f[CB]biblio-style\f[B]\f[R]
2664bibliography style, when used with \f[C]--natbib\f[R] and
2665\f[C]--biblatex\f[R].
2667\f[B]\f[CB]biblio-title\f[B]\f[R]
2668bibliography title, when used with \f[C]--natbib\f[R] and
2669\f[C]--biblatex\f[R].
2671\f[B]\f[CB]bibliography\f[B]\f[R]
2672bibliography to use for resolving references
2674\f[B]\f[CB]natbiboptions\f[B]\f[R]
2675list of options for natbib
2676.SS Variables for ConTeXt
2678Pandoc uses these variables when creating a PDF with ConTeXt.
2680\f[B]\f[CB]fontsize\f[B]\f[R]
2681font size for body text (e.g.
2682\f[C]10pt\f[R], \f[C]12pt\f[R])
2684\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]
2685text to be placed in running header or footer (see ConTeXt Headers and
2686Footers); repeat up to four times for different placement
2688\f[B]\f[CB]indenting\f[B]\f[R]
2689controls indentation of paragraphs, e.g.
2690\f[C]yes,small,next\f[R] (see ConTeXt Indentation); repeat for multiple
2693\f[B]\f[CB]interlinespace\f[B]\f[R]
2694adjusts line spacing, e.g.
2695\f[C]4ex\f[R] (using \f[C]setupinterlinespace\f[R]); repeat for multiple
2698\f[B]\f[CB]layout\f[B]\f[R]
2699options for page margins and text arrangement (see ConTeXt Layout);
2700repeat for multiple options
2702\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]
2703color for links outside and inside a page, e.g.
2704\f[C]red\f[R], \f[C]blue\f[R] (see ConTeXt Color)
2706\f[B]\f[CB]linkstyle\f[B]\f[R]
2707typeface style for links, e.g.
2708\f[C]normal\f[R], \f[C]bold\f[R], \f[C]slanted\f[R],
2709\f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R], \f[C]small\f[R]
2711\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2712include list of figures, list of tables
2714\f[B]\f[CB]mainfont\f[B]\f[R], \f[B]\f[CB]sansfont\f[B]\f[R], \f[B]\f[CB]monofont\f[B]\f[R], \f[B]\f[CB]mathfont\f[B]\f[R]
2715font families: take the name of any system font (see ConTeXt Font
2718\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]
2719sets margins, if \f[C]layout\f[R] is not used (otherwise
2720\f[C]layout\f[R] overrides these)
2722\f[B]\f[CB]pagenumbering\f[B]\f[R]
2723page number style and location (using \f[C]setuppagenumbering\f[R]);
2724repeat for multiple options
2726\f[B]\f[CB]papersize\f[B]\f[R]
2728\f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R] (see ConTeXt Paper
2729Setup); repeat for multiple options
2731\f[B]\f[CB]pdfa\f[B]\f[R]
2732adds to the preamble the setup necessary to generate PDF/A of the type
2734\f[C]1a:2005\f[R], \f[C]2a\f[R].
2735If no type is specified (i.e.
2736the value is set to True, by e.g.
2737\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata
2738block), \f[C]1b:2005\f[R] will be used as default, for reasons of
2739backwards compatibility.
2740Using \f[C]--variable=pdfa\f[R] without specified value is not
2742To successfully generate PDF/A the required ICC color profiles have to
2743be available and the content and all included files (such as images)
2744have to be standard conforming.
2745The ICC profiles and output intent may be specified using the variables
2746\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].
2747See also ConTeXt PDFA for more details.
2749\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]
2750when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile
2751to use in the PDF, e.g.
2752\f[C]default.cmyk\f[R].
2753If left unspecified, \f[C]sRGB.icc\f[R] is used as default.
2754May be repeated to include multiple profiles.
2755Note that the profiles have to be available on the system.
2756They can be obtained from ConTeXt ICC Profiles.
2758\f[B]\f[CB]pdfaintent\f[B]\f[R]
2759when used in conjunction with \f[C]pdfa\f[R], specifies the output
2760intent for the colors, e.g.
2761\f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If left
2762unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
2764\f[B]\f[CB]toc\f[B]\f[R]
2765include table of contents (can also be set using
2766\f[C]--toc/--table-of-contents\f[R])
2768\f[B]\f[CB]whitespace\f[B]\f[R]
2769spacing between paragraphs, e.g.
2770\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])
2772\f[B]\f[CB]includesource\f[B]\f[R]
2773include all source documents as file attachments in the PDF file
2774.SS Variables for \f[C]wkhtmltopdf\f[R]
2776Pandoc uses these variables when creating a PDF with
2777\f[C]wkhtmltopdf\f[R].
2778The \f[C]--css\f[R] option also affects the output.
2780\f[B]\f[CB]footer-html\f[B]\f[R], \f[B]\f[CB]header-html\f[B]\f[R]
2781add information to the header and footer
2783\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]
2786\f[B]\f[CB]papersize\f[B]\f[R]
2787sets the PDF paper size
2788.SS Variables for man pages
2790\f[B]\f[CB]adjusting\f[B]\f[R]
2791adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center
2792(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins
2794\f[B]\f[CB]footer\f[B]\f[R]
2797\f[B]\f[CB]header\f[B]\f[R]
2800\f[B]\f[CB]hyphenate\f[B]\f[R]
2801if \f[C]true\f[R] (the default), hyphenation will be used
2803\f[B]\f[CB]section\f[B]\f[R]
2804section number in man pages
2807\f[B]\f[CB]fontfamily\f[B]\f[R]
2809\f[C]T\f[R] or \f[C]P\f[R])
2811\f[B]\f[CB]indent\f[B]\f[R]
2812paragraph indent (e.g.
2815\f[B]\f[CB]lineheight\f[B]\f[R]
2819\f[B]\f[CB]pointsize\f[B]\f[R]
2822.SS Variables set automatically
2824Pandoc sets these variables automatically in response to options or
2825document contents; users can also modify them.
2826These vary depending on the output format, and include the following:
2828\f[B]\f[CB]body\f[B]\f[R]
2831\f[B]\f[CB]date-meta\f[B]\f[R]
2832the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included
2833in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,
2834s5, slideous, slidy).
2835The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],
2836\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),
2837\f[C]dd MM yyyy\f[R] (e.g.
2838either \f[C]02 Apr 2018\f[R] or \f[C]02 April 2018\f[R]),
2839\f[C]MM dd, yyyy\f[R] (e.g.
2840\f[C]Apr. 02, 2018\f[R] or
2841\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,
2842\f[C]201804\f[R] or \f[C]2018\f[R]).
2844\f[B]\f[CB]header-includes\f[B]\f[R]
2845contents specified by \f[C]-H/--include-in-header\f[R] (may have
2848\f[B]\f[CB]include-before\f[B]\f[R]
2849contents specified by \f[C]-B/--include-before-body\f[R] (may have
2852\f[B]\f[CB]include-after\f[B]\f[R]
2853contents specified by \f[C]-A/--include-after-body\f[R] (may have
2856\f[B]\f[CB]meta-json\f[B]\f[R]
2857JSON representation of all of the document\[aq]s metadata.
2858Field values are transformed to the selected output format.
2860\f[B]\f[CB]numbersections\f[B]\f[R]
2861non-null value if \f[C]-N/--number-sections\f[R] was specified
2863\f[B]\f[CB]sourcefile\f[B]\f[R], \f[B]\f[CB]outputfile\f[B]\f[R]
2864source and destination filenames, as given on the command line.
2865\f[C]sourcefile\f[R] can also be a list if input comes from multiple
2866files, or empty if input is from stdin.
2867You can use the following snippet in your template to distinguish them:
2882Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the
2885If you need absolute paths, use e.g.
2886\f[C]$curdir$/$sourcefile$\f[R].
2889\f[B]\f[CB]curdir\f[B]\f[R]
2890working directory from which pandoc is run.
2892\f[B]\f[CB]toc\f[B]\f[R]
2893non-null value if \f[C]--toc/--table-of-contents\f[R] was specified
2895\f[B]\f[CB]toc-title\f[B]\f[R]
2896title of table of contents (works only with EPUB, HTML, opendocument,
2897odt, docx, pptx, beamer, LaTeX)
2900The behavior of some of the readers and writers can be adjusted by
2901enabling or disabling various extensions.
2903An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format
2904name and disabled by adding \f[C]-EXTENSION\f[R].
2905For example, \f[C]--from markdown_strict+footnotes\f[R] is strict
2906Markdown with footnotes enabled, while
2907\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[aq]s Markdown
2908without footnotes or pipe tables.
2910The markdown reader and writer make by far the most use of extensions.
2911Extensions only used by them are therefore covered in the section
2912Pandoc\[aq]s Markdown below (See Markdown variants for
2913\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
2914that also work for other formats are covered.
2916Note that markdown extensions added to the \f[C]ipynb\f[R] format affect
2917Markdown cells in Jupyter notebooks (as do command-line options like
2918\f[C]--atx-headers\f[R]).
2920.SS Extension: \f[C]smart\f[R]
2922Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,
2923\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.
2924Nonbreaking spaces are inserted after certain abbreviations, such as
2927This extension can be enabled/disabled for the following formats:
2930\f[C]markdown\f[R], \f[C]commonmark\f[R], \f[C]latex\f[R],
2931\f[C]mediawiki\f[R], \f[C]org\f[R], \f[C]rst\f[R], \f[C]twiki\f[R]
2934\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R], \f[C]rst\f[R]
2936enabled by default in
2937\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R] (both input and
2940Note: If you are \f[I]writing\f[R] Markdown, then the \f[C]smart\f[R]
2941extension has the reverse effect: what would have been curly quotes
2944In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for
2945quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for
2946double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)
2947and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).
2948If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse
2949these characters literally.
2950In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the
2951ligatures when possible; if \f[C]smart\f[R] is disabled pandoc will use
2952unicode quotation mark and dash characters.
2953.SS Headings and sections
2954.SS Extension: \f[C]auto_identifiers\f[R]
2956A heading without an explicitly specified identifier will be
2957automatically assigned a unique identifier based on the heading text.
2959This extension can be enabled/disabled for the following formats:
2962\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]rst\f[R], \f[C]mediawiki\f[R],
2966\f[C]markdown\f[R], \f[C]muse\f[R]
2968enabled by default in
2969\f[C]markdown\f[R], \f[C]muse\f[R]
2971The default algorithm used to derive the identifier from the heading
2974Remove all formatting, links, etc.
2976Remove all footnotes.
2978Remove all non-alphanumeric characters, except underscores, hyphens, and
2981Replace all spaces and newlines with hyphens.
2983Convert all alphabetic characters to lowercase.
2985Remove everything up to the first letter (identifiers may not begin with
2986a number or punctuation mark).
2988If nothing is left after this, use the identifier \f[C]section\f[R].
3002\f[C]Heading identifiers in HTML\f[R]
3004\f[C]heading-identifiers-in-html\f[R]
3007\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]
3009\f[C]ma\[^i]tre-dh\[^o]tel\f[R]
3012\f[C]*Dogs*?--in *my* house?\f[R]
3014\f[C]dogs--in-my-house\f[R]
3017\f[C][HTML], [S5], or [RTF]?\f[R]
3019\f[C]html-s5-or-rtf\f[R]
3022\f[C]3. Applications\f[R]
3024\f[C]applications\f[R]
3033These rules should, in most cases, allow one to determine the identifier
3034from the heading text.
3035The exception is when several headings have the same text; in this case,
3036the first will get an identifier as described above; the second will get
3037the same identifier with \f[C]-1\f[R] appended; the third with
3038\f[C]-2\f[R]; and so on.
3040(However, a different algorithm is used if
3041\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)
3043These identifiers are used to provide link targets in the table of
3044contents generated by the \f[C]--toc|--table-of-contents\f[R] option.
3045They also make it easy to provide links from one section of a document
3047A link to this section, for example, might look like this:
3052[heading identifiers](#heading-identifiers-in-html-latex-and-context).
3056Note, however, that this method of providing links to sections works
3057only in HTML, LaTeX, and ConTeXt formats.
3059If the \f[C]--section-divs\f[R] option is specified, then each section
3060will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if
3061\f[C]html4\f[R] was specified), and the identifier will be attached to
3062the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than
3064This allows entire sections to be manipulated using JavaScript or
3065treated differently in CSS.
3066.SS Extension: \f[C]ascii_identifiers\f[R]
3068Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure
3070Accents are stripped off of accented Latin letters, and non-Latin
3072.SS Extension: \f[C]gfm_auto_identifiers\f[R]
3074Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
3076Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
3077lowercase characters, and punctuation characters other than \f[C]-\f[R]
3078and \f[C]_\f[R] are removed.
3079Emojis are replaced by their names.
3082The extensions \f[C]tex_math_dollars\f[R],
3083\f[C]tex_math_single_backslash\f[R], and
3084\f[C]tex_math_double_backslash\f[R] are described in the section about
3085Pandoc\[aq]s Markdown.
3087However, they can also be used with HTML input.
3088This is handy for reading web pages formatted using MathJax, for
3092The following extensions (especially how they affect Markdown
3093input/output) are also described in more detail in their respective
3094sections of Pandoc\[aq]s Markdown.
3095.SS Extension: \f[C]raw_html\f[R]
3097When converting from HTML, parse elements to raw HTML which are not
3098representable in pandoc\[aq]s AST.
3099By default, this is disabled for HTML input.
3100.SS Extension: \f[C]raw_tex\f[R]
3102Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
3104This extension can be enabled/disabled for the following formats (in
3105addition to \f[C]markdown\f[R]):
3108\f[C]latex\f[R], \f[C]org\f[R], \f[C]textile\f[R], \f[C]html\f[R]
3109(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only),
3113\f[C]textile\f[R], \f[C]commonmark\f[R]
3115Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and
3116\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data
3117with mime type \f[C]text/html\f[R] in output cells.
3118Since the \f[C]ipynb\f[R] reader attempts to preserve the richest
3119possible outputs when several options are given, you will get best
3120results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when
3121converting to formats like \f[C]docx\f[R] which don\[aq]t allow raw
3122\f[C]html\f[R] or \f[C]tex\f[R].
3123.SS Extension: \f[C]native_divs\f[R]
3125This extension is enabled by default for HTML input.
3126This means that \f[C]div\f[R]s are parsed to pandoc native elements.
3127(Alternatively, you can parse them to raw HTML using
3128\f[C]-f html-native_divs+raw_html\f[R].)
3130When converting HTML to Markdown, for example, you may want to drop all
3131\f[C]div\f[R]s and \f[C]span\f[R]s:
3135pandoc -f html-native_divs-native_spans -t markdown
3138.SS Extension: \f[C]native_spans\f[R]
3140Analogous to \f[C]native_divs\f[R] above.
3141.SS Literate Haskell support
3142.SS Extension: \f[C]literate_haskell\f[R]
3144Treat the document as literate Haskell source.
3146This extension can be enabled/disabled for the following formats:
3149\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R]
3152\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R], \f[C]html\f[R]
3154If you append \f[C]+lhs\f[R] (or \f[C]+literate_haskell\f[R]) to one of
3155the formats above, pandoc will treat the document as literate Haskell
3159In Markdown input, \[dq]bird track\[dq] sections will be parsed as
3160Haskell code rather than block quotations.
3161Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]
3162will also be treated as Haskell code.
3163For ATX-style headings the character \[aq]=\[aq] will be used instead of
3166In Markdown output, code blocks with classes \f[C]haskell\f[R] and
3167\f[C]literate\f[R] will be rendered using bird tracks, and block
3168quotations will be indented one space, so they will not be treated as
3170In addition, headings will be rendered setext-style (with underlines)
3171rather than ATX-style (with \[aq]#\[aq] characters).
3172(This is because ghc treats \[aq]#\[aq] characters in column 1 as
3173introducing line numbers.)
3175In restructured text input, \[dq]bird track\[dq] sections will be parsed
3178In restructured text output, code blocks with class \f[C]haskell\f[R]
3179will be rendered using bird tracks.
3181In LaTeX input, text in \f[C]code\f[R] environments will be parsed as
3184In LaTeX output, code blocks with class \f[C]haskell\f[R] will be
3185rendered inside \f[C]code\f[R] environments.
3187In HTML output, code blocks with class \f[C]haskell\f[R] will be
3188rendered with class \f[C]literatehaskell\f[R] and bird tracks.
3194pandoc -f markdown+lhs -t html
3198reads literate Haskell source formatted with Markdown conventions and
3199writes ordinary HTML (without bird tracks).
3203pandoc -f markdown+lhs -t html+lhs
3207writes HTML with the Haskell code in bird tracks, so it can be copied
3208and pasted as literate Haskell source.
3210Note that GHC expects the bird tracks in the first column, so indented
3211literate code blocks (e.g.
3212inside an itemized environment) will not be picked up by the Haskell
3215.SS Extension: \f[C]empty_paragraphs\f[R]
3217Allows empty paragraphs.
3218By default empty paragraphs are omitted.
3220This extension can be enabled/disabled for the following formats:
3223\f[C]docx\f[R], \f[C]html\f[R]
3226\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]
3227.SS Extension: \f[C]native_numbering\f[R]
3229Enables native numbering of figures and tables.
3230Enumeration starts at 1.
3232This extension can be enabled/disabled for the following formats:
3235\f[C]odt\f[R], \f[C]opendocument\f[R]
3236.SS Extension: \f[C]styles\f[R]
3238When converting from docx, read all docx styles as divs (for paragraph
3239styles) and spans (for character styles) regardless of whether pandoc
3240understands the meaning of these styles.
3241This can be used with docx custom styles.
3246.SS Extension: \f[C]amuse\f[R]
3248In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions
3249to Emacs Muse markup.
3250.SS Extension: \f[C]citations\f[R]
3252Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted
3253in \f[C]org\f[R] input.
3254.SS Extension: \f[C]ntb\f[R]
3256In the \f[C]context\f[R] output format this enables the use of Natural
3257Tables (TABLE) instead of the default Extreme Tables (xtables).
3258Natural tables allow more fine-grained global customization but come at
3259a performance penalty compared to extreme tables.
3260.SH PANDOC\[aq]S MARKDOWN
3262Pandoc understands an extended and slightly revised version of John
3263Gruber\[aq]s Markdown syntax.
3264This document explains the syntax, noting differences from standard
3266Except where noted, these differences can be suppressed by using the
3267\f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R].
3268Extensions can be enabled or disabled to specify the behavior more
3270They are described in the following.
3271See also Extensions above, for extensions that work also on other
3275Markdown is designed to be easy to write, and, even more importantly,
3279A Markdown-formatted document should be publishable as-is, as plain
3280text, without looking like it\[aq]s been marked up with tags or
3281formatting instructions.
3285This principle has guided pandoc\[aq]s decisions in finding syntax for
3286tables, footnotes, and other extensions.
3288There is, however, one respect in which pandoc\[aq]s aims are different
3289from the original aims of Markdown.
3290Whereas Markdown was originally designed with HTML generation in mind,
3291pandoc is designed for multiple output formats.
3292Thus, while pandoc allows the embedding of raw HTML, it discourages it,
3293and provides other, non-HTMLish ways of representing important document
3294elements like definition lists, tables, mathematics, and footnotes.
3297A paragraph is one or more lines of text followed by one or more blank
3299Newlines are treated as spaces, so you can reflow your paragraphs as you
3301If you need a hard line break, put two or more spaces at the end of a
3303.SS Extension: \f[C]escaped_line_breaks\f[R]
3305A backslash followed by a newline is also a hard line break.
3306Note: in multiline and grid table cells, this is the only way to create
3307a hard line break, since trailing spaces in the cells are ignored.
3310There are two kinds of headings: Setext and ATX.
3311.SS Setext-style headings
3313A setext-style heading is a line of text \[dq]underlined\[dq] with a row
3314of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for
3315a level-two heading):
3327The heading text can contain inline formatting, such as emphasis (see
3328Inline formatting, below).
3329.SS ATX-style headings
3331An ATX-style heading consists of one to six \f[C]#\f[R] signs and a line
3332of text, optionally followed by any number of \f[C]#\f[R] signs.
3333The number of \f[C]#\f[R] signs at the beginning of the line is the
3338## A level-two heading
3340### A level-three heading ###
3344As with setext-style headings, the heading text can contain formatting:
3348# A level-one heading with a [link](/url) and *emphasis*
3351.SS Extension: \f[C]blank_before_header\f[R]
3353Standard Markdown syntax does not require a blank line before a heading.
3354Pandoc does require this (except, of course, at the beginning of the
3356The reason for the requirement is that it is all too easy for a
3357\f[C]#\f[R] to end up at the beginning of a line by accident (perhaps
3358through line wrapping).
3359Consider, for example:
3363I like several of their flavors of ice cream:
3364#22, for example, and #5.
3367.SS Extension: \f[C]space_in_atx_header\f[R]
3369Many Markdown implementations do not require a space between the opening
3370\f[C]#\f[R]s of an ATX heading and the heading text, so that
3371\f[C]#5 bolt\f[R] and \f[C]#hashtag\f[R] count as headings.
3372With this extension, pandoc does require the space.
3373.SS Heading identifiers
3375See also the \f[C]auto_identifiers\f[R] extension above.
3376.SS Extension: \f[C]header_attributes\f[R]
3378Headings can be assigned attributes using this syntax at the end of the
3379line containing the heading text:
3383{#identifier .class .class key=value key=value}
3387Thus, for example, the following headings will all be assigned the
3388identifier \f[C]foo\f[R]:
3394## My heading ## {#foo}
3396My other heading {#foo}
3401(This syntax is compatible with PHP Markdown Extra.)
3403Note that although this syntax allows assignment of classes and
3404key/value attributes, writers generally don\[aq]t use all of this
3406Identifiers, classes, and key/value attributes are used in HTML and
3407HTML-based formats such as EPUB and slidy.
3408Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,
3409Textile, Jira markup, and AsciiDoc writers.
3411Headings with the class \f[C]unnumbered\f[R] will not be numbered, even
3412if \f[C]--number-sections\f[R] is specified.
3413A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to
3414\f[C].unnumbered\f[R], and preferable in non-English documents.
3427# My heading {.unnumbered}
3431If the \f[C]unlisted\f[R] class is present in addition to
3432\f[C]unnumbered\f[R], the heading will not be included in a table of
3434(Currently this feature is only implemented for certain formats: those
3435based on LaTeX and HTML, PowerPoint, and RTF.)
3436.SS Extension: \f[C]implicit_header_references\f[R]
3438Pandoc behaves as if reference links have been defined for each heading.
3439So, to link to a heading
3443# Heading identifiers in HTML
3451[Heading identifiers in HTML]
3459[Heading identifiers in HTML][]
3467[the section on heading identifiers][heading identifiers in
3472instead of giving the identifier explicitly:
3476[Heading identifiers in HTML](#heading-identifiers-in-html)
3480If there are multiple headings with identical text, the corresponding
3481reference will link to the first one only, and you will need to use
3482explicit links to link to the others, as described above.
3484Like regular reference links, these references are case-insensitive.
3486Explicit link reference definitions always take priority over implicit
3488So, in the following example, the link will point to \f[C]bar\f[R], not
3502Markdown uses email conventions for quoting blocks of text.
3503A block quotation is one or more paragraphs or other block elements
3504(such as lists or headings), with each line preceded by a \f[C]>\f[R]
3505character and an optional space.
3506(The \f[C]>\f[R] need not start at the left margin, but it should not be
3507indented more than three spaces.)
3511> This is a block quote. This
3512> paragraph has two lines.
3514> 1. This is a list inside a block quote.
3519A \[dq]lazy\[dq] form, which requires the \f[C]>\f[R] character only on
3520the first line of each block, is also allowed:
3524> This is a block quote. This
3525paragraph has two lines.
3527> 1. This is a list inside a block quote.
3532Among the block elements that can be contained in a block quote are
3534That is, block quotes can be nested:
3538> This is a block quote.
3540> > A block quote within a block quote.
3544If the \f[C]>\f[R] character is followed by an optional space, that
3545space will be considered part of the block quote marker and not part of
3546the indentation of the contents.
3547Thus, to put an indented code block in a block quote, you need five
3548spaces after the \f[C]>\f[R]:
3555.SS Extension: \f[C]blank_before_blockquote\f[R]
3557Standard Markdown syntax does not require a blank line before a block
3559Pandoc does require this (except, of course, at the beginning of the
3561The reason for the requirement is that it is all too easy for a
3562\f[C]>\f[R] to end up at the beginning of a line by accident (perhaps
3563through line wrapping).
3564So, unless the \f[C]markdown_strict\f[R] format is used, the following
3565does not produce a nested block quote in pandoc:
3569> This is a block quote.
3573.SS Verbatim (code) blocks
3574.SS Indented code blocks
3576A block of text indented four spaces (or one tab) is treated as verbatim
3577text: that is, special characters do not trigger special formatting, and
3578all spaces and line breaks are preserved.
3584 moveShip(5 * gravity, DOWN);
3589The initial (four space or one tab) indentation is not considered part
3590of the verbatim text, and is removed in the output.
3592Note: blank lines in the verbatim text need not begin with four spaces.
3593.SS Fenced code blocks
3594.SS Extension: \f[C]fenced_code_blocks\f[R]
3596In addition to standard indented code blocks, pandoc supports
3597\f[I]fenced\f[R] code blocks.
3598These begin with a row of three or more tildes (\f[C]\[ti]\f[R]) and end
3599with a row of tildes that must be at least as long as the starting row.
3600Everything between these lines is treated as code.
3601No indentation is necessary:
3605\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3607 moveShip(5 * gravity, DOWN);
3609\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3613Like regular code blocks, fenced code blocks must be separated from
3614surrounding text by blank lines.
3616If the code itself contains a row of tildes or backticks, just use a
3617longer row of tildes or backticks at the start and end:
3621\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3622\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3623code including tildes
3624\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3625\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3628.SS Extension: \f[C]backtick_code_blocks\f[R]
3630Same as \f[C]fenced_code_blocks\f[R], but uses backticks
3631(\f[C]\[ga]\f[R]) instead of tildes (\f[C]\[ti]\f[R]).
3632.SS Extension: \f[C]fenced_code_attributes\f[R]
3634Optionally, you may attach attributes to fenced or backtick code block
3639\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}
3641qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3642 qsort (filter (>= x) xs)
3643\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3647Here \f[C]mycode\f[R] is an identifier, \f[C]haskell\f[R] and
3648\f[C]numberLines\f[R] are classes, and \f[C]startFrom\f[R] is an
3649attribute with value \f[C]100\f[R].
3650Some output formats can use this information to do syntax highlighting.
3651Currently, the only output formats that uses this information are HTML,
3652LaTeX, Docx, Ms, and PowerPoint.
3653If highlighting is supported for your output format and language, then
3654the code block above will appear highlighted, with numbered lines.
3655(To see which languages are supported, type
3656\f[C]pandoc --list-highlight-languages\f[R].) Otherwise, the code block
3657above will appear as follows:
3661<pre id=\[dq]mycode\[dq] class=\[dq]haskell numberLines\[dq] startFrom=\[dq]100\[dq]>
3669The \f[C]numberLines\f[R] (or \f[C]number-lines\f[R]) class will cause
3670the lines of the code block to be numbered, starting with \f[C]1\f[R] or
3671the value of the \f[C]startFrom\f[R] attribute.
3672The \f[C]lineAnchors\f[R] (or \f[C]line-anchors\f[R]) class will cause
3673the lines to be clickable anchors in HTML output.
3675A shortcut form can also be used for specifying the language of the code
3680\[ga]\[ga]\[ga]haskell
3686This is equivalent to:
3690\[ga]\[ga]\[ga] {.haskell}
3696If the \f[C]fenced_code_attributes\f[R] extension is disabled, but input
3697contains class attribute(s) for the code block, the first class
3698attribute will be printed after the opening fence as a bare word.
3700To prevent all highlighting, use the \f[C]--no-highlight\f[R] flag.
3701To set the highlighting style, use \f[C]--highlight-style\f[R].
3702For more information on highlighting, see Syntax highlighting, below.
3704.SS Extension: \f[C]line_blocks\f[R]
3706A line block is a sequence of lines beginning with a vertical bar
3707(\f[C]|\f[R]) followed by a space.
3708The division into lines will be preserved in the output, as will any
3709leading spaces; otherwise, the lines will be formatted as Markdown.
3710This is useful for verse and addresses:
3714| The limerick packs laughs anatomical
3715| In space that is quite economical.
3716| But the good ones I\[aq]ve seen
3717| So seldom are clean
3718| And the clean ones so seldom are comical
3725The lines can be hard-wrapped if needed, but the continuation line must
3730| The Right Honorable Most Venerable and Righteous Samuel L.
3737This syntax is borrowed from reStructuredText.
3741A bullet list is a list of bulleted list items.
3742A bulleted list item begins with a bullet (\f[C]*\f[R], \f[C]+\f[R], or
3744Here is a simple example:
3754This will produce a \[dq]compact\[dq] list.
3755If you want a \[dq]loose\[dq] list, in which each item is formatted as a
3756paragraph, put spaces between the items:
3768The bullets need not be flush with the left margin; they may be indented
3769one, two, or three spaces.
3770The bullet must be followed by whitespace.
3772List items look best if subsequent lines are flush with the first line
3783But Markdown also allows a \[dq]lazy\[dq] format:
3792.SS Block content in list items
3794A list item may contain multiple paragraphs and other block-level
3796However, subsequent paragraphs must be preceded by a blank line and
3797indented to line up with the first non-space content after the list
3806 * Second paragraph. With a code block, which must be indented
3813Exception: if the list marker is followed by an indented code block,
3814which must begin 5 spaces after the list marker, then subsequent
3815paragraphs must begin two columns after the last character of the list
3822 continuation paragraph
3826List items may include other lists.
3827In this case the preceding blank line is optional.
3828The nested list must be indented to line up with the first non-space
3829character after the list marker of the containing list item.
3845As noted above, Markdown allows you to write list items
3846\[dq]lazily,\[dq] instead of indenting continuation lines.
3847However, if there are multiple paragraphs or other blocks in a list
3848item, the first line of each must be indented.
3855+ Another one; this looks
3858 Second paragraph of second
3864Ordered lists work just like bulleted lists, except that the items begin
3865with enumerators rather than bullets.
3867In standard Markdown, enumerators are decimal numbers followed by a
3869The numbers themselves are ignored, so there is no difference between
3889.SS Extension: \f[C]fancy_lists\f[R]
3891Unlike standard Markdown, pandoc allows ordered list items to be marked
3892with uppercase and lowercase letters and roman numerals, in addition to
3894List markers may be enclosed in parentheses or followed by a single
3895right-parentheses or period.
3896They must be separated from the text that follows by at least one space,
3897and, if the list marker is a capital letter with a period, by at least
3900The \f[C]fancy_lists\f[R] extension also allows \[aq]\f[C]#\f[R]\[aq] to
3901be used as an ordered list marker in place of a numeral:
3909.SS Extension: \f[C]startnum\f[R]
3911Pandoc also pays attention to the type of list marker used, and to the
3912starting number, and both of these are preserved where possible in the
3914Thus, the following yields a list with numbers followed by a single
3915parenthesis, starting with 9, and a sublist with lowercase roman
3929Pandoc will start a new list each time a different type of list marker
3931So, the following will create three lists:
3942If default list markers are desired, use \f[C]#.\f[R]:
3951.SS Extension: \f[C]task_lists\f[R]
3953Pandoc supports task lists, using the syntax of GitHub-Flavored
3958- [ ] an unchecked task list item
3963.SS Extension: \f[C]definition_lists\f[R]
3965Pandoc supports definition lists, using the syntax of PHP Markdown Extra
3966with some extensions.
3974Term 2 with *inline markup*
3978 { some code, part of Definition 2 }
3980 Third paragraph of definition 2.
3984Each term must fit on one line, which may optionally be followed by a
3985blank line, and must be followed by one or more definitions.
3986A definition begins with a colon or tilde, which may be indented one or
3989A term may have multiple definitions, and each definition may consist of
3990one or more block elements (paragraph, code block, list, etc.), each
3991indented four spaces or one tab stop.
3992The body of the definition (including the first line, aside from the
3993colon or tilde) should be indented four spaces.
3994However, as with other Markdown lists, you can \[dq]lazily\[dq] omit
3995indentation except at the beginning of a paragraph or other block
4003with lazy continuation.
4005 Second paragraph of the definition.
4009If you leave space before the definition (as in the example above), the
4010text of the definition will be treated as a paragraph.
4011In some output formats, this will mean greater spacing between
4012term/definition pairs.
4013For a more compact definition list, omit the space before the
4027Note that space between items in a definition list is required.
4028(A variant that loosens this requirement, but disallows \[dq]lazy\[dq]
4029hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
4030see Non-pandoc extensions, below.)
4031.SS Numbered example lists
4032.SS Extension: \f[C]example_lists\f[R]
4034The special list marker \f[C]\[at]\f[R] can be used for sequentially
4036The first list item with a \f[C]\[at]\f[R] marker will be numbered
4037\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
4038The numbered examples need not occur in a single list; each new list
4039using \f[C]\[at]\f[R] will take up where the last stopped.
4044(\[at]) My first example will be numbered (1).
4045(\[at]) My second example will be numbered (2).
4047Explanation of examples.
4049(\[at]) My third example will be numbered (3).
4053Numbered examples can be labeled and referred to elsewhere in the
4058(\[at]good) This is a good example.
4060As (\[at]good) illustrates, ...
4064The label can be any string of alphanumeric characters, underscores, or
4067Note: continuation paragraphs in example lists must always be indented
4068four spaces, regardless of the length of the list marker.
4069That is, example lists always behave as if the \f[C]four_space_rule\f[R]
4071This is because example labels tend to be long, and indenting content to
4072the first non-space character after the label would be awkward.
4073.SS Compact and loose lists
4075Pandoc behaves differently from \f[C]Markdown.pl\f[R] on some \[dq]edge
4076cases\[dq] involving lists.
4077Consider this source:
4091Pandoc transforms this into a \[dq]compact list\[dq] (with no
4092\f[C]<p>\f[R] tags around \[dq]First\[dq], \[dq]Second\[dq], or
4093\[dq]Third\[dq]), while Markdown puts \f[C]<p>\f[R] tags around
4094\[dq]Second\[dq] and \[dq]Third\[dq] (but not \[dq]First\[dq]), because
4095of the blank space around \[dq]Third\[dq].
4096Pandoc follows a simple rule: if the text is followed by a blank line,
4097it is treated as a paragraph.
4098Since \[dq]Second\[dq] is followed by a list, and not a blank line, it
4099isn\[aq]t treated as a paragraph.
4100The fact that the list is followed by a blank line is irrelevant.
4101(Note: Pandoc works this way even when the \f[C]markdown_strict\f[R]
4103This behavior is consistent with the official Markdown syntax
4104description, even though it is different from that of
4105\f[C]Markdown.pl\f[R].)
4108What if you want to put an indented code block after a list?
4119Trouble! Here pandoc (like other Markdown implementations) will treat
4120\f[C]{ my code block }\f[R] as the second paragraph of item two, and not
4123To \[dq]cut off\[dq] the list after item two, you can insert some
4124non-indented content, like an HTML comment, which won\[aq]t produce
4125visible output in any format:
4138You can use the same trick if you want two consecutive lists instead of
4156A line containing a row of three or more \f[C]*\f[R], \f[C]-\f[R], or
4157\f[C]_\f[R] characters (optionally separated by spaces) produces a
4169Four kinds of tables may be used.
4170The first three kinds presuppose the use of a fixed-width font, such as
4172The fourth kind can be used with proportionally spaced fonts, as it does
4173not require lining up columns.
4174.SS Extension: \f[C]table_captions\f[R]
4176A caption may optionally be provided with all 4 kinds of tables (as
4177illustrated in the examples below).
4178A caption is a paragraph beginning with the string \f[C]Table:\f[R] (or
4179just \f[C]:\f[R]), which will be stripped off.
4180It may appear either before or after the table.
4181.SS Extension: \f[C]simple_tables\f[R]
4183Simple tables look like this:
4187 Right Left Center Default
4188------- ------ ---------- -------
4193Table: Demonstration of simple table syntax.
4197The header and table rows must each fit on one line.
4198Column alignments are determined by the position of the header text
4199relative to the dashed line below it:
4201If the dashed line is flush with the header text on the right side but
4202extends beyond it on the left, the column is right-aligned.
4204If the dashed line is flush with the header text on the left side but
4205extends beyond it on the right, the column is left-aligned.
4207If the dashed line extends beyond the header text on both sides, the
4210If the dashed line is flush with the header text on both sides, the
4211default alignment is used (in most cases, this will be left).
4213The table must end with a blank line, or a line of dashes followed by a
4216The column header row may be omitted, provided a dashed line is used to
4222------- ------ ---------- -------
4226------- ------ ---------- -------
4230When the header row is omitted, column alignments are determined on the
4231basis of the first line of the table body.
4232So, in the tables above, the columns would be right, left, center, and
4233right aligned, respectively.
4234.SS Extension: \f[C]multiline_tables\f[R]
4236Multiline tables allow header and table rows to span multiple lines of
4237text (but cells that span multiple columns or rows of the table are not
4243-------------------------------------------------------------
4244 Centered Default Right Left
4245 Header Aligned Aligned Aligned
4246----------- ------- --------------- -------------------------
4247 First row 12.0 Example of a row that
4248 spans multiple lines.
4250 Second row 5.0 Here\[aq]s another one. Note
4251 the blank line between
4253-------------------------------------------------------------
4255Table: Here\[aq]s the caption. It, too, may span
4260These work like simple tables, but with the following differences:
4262They must begin with a row of dashes, before the header text (unless the
4263header row is omitted).
4265They must end with a row of dashes, then a blank line.
4267The rows must be separated by blank lines.
4269In multiline tables, the table parser pays attention to the widths of
4270the columns, and the writers try to reproduce these relative widths in
4272So, if you find that one of the columns is too narrow in the output, try
4273widening it in the Markdown source.
4275The header may be omitted in multiline tables as well as simple tables:
4279----------- ------- --------------- -------------------------
4280 First row 12.0 Example of a row that
4281 spans multiple lines.
4283 Second row 5.0 Here\[aq]s another one. Note
4284 the blank line between
4286----------- ------- --------------- -------------------------
4288: Here\[aq]s a multiline table without a header.
4292It is possible for a multiline table to have just one row, but the row
4293should be followed by a blank line (and then the row of dashes that ends
4294the table), or the table may be interpreted as a simple table.
4295.SS Extension: \f[C]grid_tables\f[R]
4297Grid tables look like this:
4303+---------------+---------------+--------------------+
4304| Fruit | Price | Advantages |
4305+===============+===============+====================+
4306| Bananas | $1.34 | - built-in wrapper |
4307| | | - bright color |
4308+---------------+---------------+--------------------+
4309| Oranges | $2.10 | - cures scurvy |
4311+---------------+---------------+--------------------+
4315The row of \f[C]=\f[R]s separates the header from the table body, and
4316can be omitted for a headerless table.
4317The cells of grid tables may contain arbitrary block elements (multiple
4318paragraphs, code blocks, lists, etc.).
4319Cells that span multiple columns or rows are not supported.
4320Grid tables can be created easily using Emacs\[aq] table-mode
4321(\f[C]M-x table-insert\f[R]).
4323Alignments can be specified as with pipe tables, by putting colons at
4324the boundaries of the separator line after the header:
4328+---------------+---------------+--------------------+
4329| Right | Left | Centered |
4330+==============:+:==============+:==================:+
4331| Bananas | $1.34 | built-in wrapper |
4332+---------------+---------------+--------------------+
4336For headerless tables, the colons go on the top line instead:
4340+--------------:+:--------------+:------------------:+
4341| Right | Left | Centered |
4342+---------------+---------------+--------------------+
4345.SS Grid Table Limitations
4347Pandoc does not support grid tables with row spans or column spans.
4348This means that neither variable numbers of columns across rows nor
4349variable numbers of rows across columns are supported by Pandoc.
4350All grid tables must have the same number of columns in each row, and
4351the same number of rows in each column.
4352For example, the Docutils sample grid tables will not render as expected
4354.SS Extension: \f[C]pipe_tables\f[R]
4356Pipe tables look like this:
4360| Right | Left | Default | Center |
4361|------:|:-----|---------|:------:|
4362| 12 | 12 | 12 | 12 |
4363| 123 | 123 | 123 | 123 |
4366 : Demonstration of pipe table syntax.
4370The syntax is identical to PHP Markdown Extra tables.
4371The beginning and ending pipe characters are optional, but pipes are
4372required between all columns.
4373The colons indicate column alignment as shown.
4374The header cannot be omitted.
4375To simulate a headerless table, include a header with blank cells.
4377Since the pipes indicate column boundaries, columns need not be
4378vertically aligned, as they are in the above example.
4379So, this is a perfectly legal (though ugly) pipe table:
4391The cells of pipe tables cannot contain block elements like paragraphs
4392and lists, and cannot span multiple lines.
4393If a pipe table contains a row whose printable content is wider than the
4394column width (see \f[C]--columns\f[R]), then the table will take up the
4395full text width and the cell contents will wrap, with the relative cell
4396widths determined by the number of dashes in the line separating the
4397table header from the table body.
4398(For example \f[C]---|-\f[R] would make the first column 3/4 and the
4399second column 1/4 of the full text width.) On the other hand, if no
4400lines are wider than column width, then cell contents will not be
4401wrapped, and the cells will be sized to their contents.
4403Note: pandoc also recognizes pipe tables of the following form, as can
4404be produced by Emacs\[aq] orgtbl-mode:
4415The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].
4416Other orgtbl features are not supported.
4417In particular, to get non-default column alignment, you\[aq]ll need to
4420.SS Extension: \f[C]pandoc_title_block\f[R]
4422If the file begins with a title block
4427% author(s) (separated by semicolons)
4432it will be parsed as bibliographic information, not regular text.
4433(It will be used, for example, in the title of standalone LaTeX or HTML
4434output.) The block may contain just a title, a title and an author, or
4436If you want to include an author but no title, or a title and a date but
4437no author, you need a blank line:
4450The title may occupy multiple lines, but continuation lines must begin
4451with leading space, thus:
4460If a document has multiple authors, the authors may be put on separate
4461lines with leading space, or separated by semicolons, or both.
4462So, all of the following are equivalent:
4469% Author One; Author Two
4476The date must fit on one line.
4478All three metadata fields may contain standard inline formatting
4479(italics, links, footnotes, etc.).
4481Title blocks will always be parsed, but they will affect the output only
4482when the \f[C]--standalone\f[R] (\f[C]-s\f[R]) option is chosen.
4483In HTML output, titles will appear twice: once in the document head --
4484this is the title that will appear at the top of the window in a browser
4485-- and once at the beginning of the document body.
4486The title in the document head can have an optional prefix attached
4487(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).
4488The title in the body appears as an H1 element with class
4489\[dq]title\[dq], so it can be suppressed or reformatted with CSS.
4490If a title prefix is specified with \f[C]-T\f[R] and no title block
4491appears in the document, the title prefix will be used by itself as the
4494The man page writer extracts a title, man page section number, and other
4495header and footer information from the title line.
4496The title is assumed to be the first word on the title line, which may
4497optionally end with a (single-digit) section number in parentheses.
4498(There should be no space between the title and the parentheses.)
4499Anything after this is assumed to be additional footer and header text.
4500A single pipe character (\f[C]|\f[R]) should be used to separate the
4501footer text from the header text.
4510will yield a man page with the title \f[C]PANDOC\f[R] and section 1.
4514% PANDOC(1) Pandoc User Manuals
4518will also have \[dq]Pandoc User Manuals\[dq] in the footer.
4522% PANDOC(1) Pandoc User Manuals | Version 4.0
4526will also have \[dq]Version 4.0\[dq] in the header.
4527.SS Extension: \f[C]yaml_metadata_block\f[R]
4529A YAML metadata block is a valid YAML object, delimited by a line of
4530three hyphens (\f[C]---\f[R]) at the top and a line of three hyphens
4531(\f[C]---\f[R]) or three dots (\f[C]...\f[R]) at the bottom.
4532A YAML metadata block may occur anywhere in the document, but if it is
4533not at the beginning, it must be preceded by a blank line.
4534(Note that, because of the way pandoc concatenates input files when
4535several are provided, you may also keep the metadata in a separate YAML
4536file and pass it to pandoc as an argument, along with your Markdown
4541pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
4545Just be sure that the YAML file begins with \f[C]---\f[R] and ends with
4546\f[C]---\f[R] or \f[C]...\f[R].) Alternatively, you can use the
4547\f[C]--metadata-file\f[R] option.
4548Using that approach however, you cannot reference content (like
4549footnotes) from the main markdown input document.
4551Metadata will be taken from the fields of the YAML object and added to
4552any existing document metadata.
4553Metadata can contain lists and objects (nested arbitrarily), but all
4554string scalars will be interpreted as Markdown.
4555Fields with names ending in an underscore will be ignored by pandoc.
4556(They may be given a role by external processors.) Field names must not
4557be interpretable as YAML numbers or boolean values (so, for example,
4558\f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot be used as field
4561A document may contain multiple metadata blocks.
4562If two metadata blocks attempt to set the same field, the value from the
4563second block will be taken.
4565When pandoc is used with \f[C]-t markdown\f[R] to create a Markdown
4566document, a YAML metadata block will be produced only if the
4567\f[C]-s/--standalone\f[R] option is used.
4568All of the metadata will appear in a single block at the beginning of
4571Note that YAML escaping rules must be followed.
4572Thus, for example, if a title contains a colon, it must be quoted.
4573The pipe character (\f[C]|\f[R]) can be used to begin an indented block
4574that will be interpreted literally, without need for escaping.
4575This form is necessary when the field contains blank lines or
4576block-level formatting:
4581title: \[aq]This is the title: it contains a colon\[aq]
4585keywords: [nothing, nothingness]
4587 This is the abstract.
4589 It consists of two paragraphs.
4594Template variables will be set automatically from the metadata.
4595Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will
4596be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]
4601<p>This is the abstract.</p>
4602<p>It consists of two paragraphs.</p>
4606Variables can contain arbitrary YAML structures, but the template must
4607match this structure.
4608The \f[C]author\f[R] variable in the default templates expects a simple
4609list or string, but can be changed to support more complicated
4611The following combination, for example, would add an affiliation to the
4612author if one is given:
4617title: The document title
4620 affiliation: University of Somewhere
4622 affiliation: University of Nowhere
4627To use the structured authors in the example above, you would need a
4634$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
4642Raw content to include in the document\[aq]s header may be specified
4643using \f[C]header-includes\f[R]; however, it is important to mark up
4644this content as raw code for a particular output format, using the
4645\f[C]raw_attribute\f[R] extension), or it will be interpreted as
4653 \[ga]\[ga]\[ga]{=latex}
4654 \[rs]let\[rs]oldsection\[rs]section
4655 \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}}
4659.SS Backslash escapes
4660.SS Extension: \f[C]all_symbols_escapable\f[R]
4662Except inside a code block or inline code, any punctuation or space
4663character preceded by a backslash will be treated literally, even if it
4664would normally indicate formatting.
4665Thus, for example, if one writes
4685<strong>hello</strong>
4689This rule is easier to remember than standard Markdown\[aq]s rule, which
4690allows only the following characters to be backslash-escaped:
4694\[rs]\[ga]*_{}[]()>#+-.!
4698(However, if the \f[C]markdown_strict\f[R] format is used, the standard
4699Markdown rule will be used.)
4701A backslash-escaped space is parsed as a nonbreaking space.
4702It will appear in TeX output as \f[C]\[ti]\f[R] and in HTML and XML as
4703\f[C]\[rs] \f[R] or \f[C]\[rs] \f[R].
4705A backslash-escaped newline (i.e.
4706a backslash occurring at the end of a line) is parsed as a hard line
4708It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as
4710This is a nice alternative to Markdown\[aq]s \[dq]invisible\[dq] way of
4711indicating hard line breaks using two trailing spaces on a line.
4713Backslash escapes do not work in verbatim contexts.
4714.SS Inline formatting
4717To \f[I]emphasize\f[R] some text, surround it with \f[C]*\f[R]s or
4718\f[C]_\f[R], like this:
4722This text is _emphasized with underscores_, and this
4723is *emphasized with asterisks*.
4727Double \f[C]*\f[R] or \f[C]_\f[R] produces \f[B]strong emphasis\f[R]:
4731This is **strong emphasis** and __with underscores__.
4735A \f[C]*\f[R] or \f[C]_\f[R] character surrounded by spaces, or
4736backslash-escaped, will not trigger emphasis:
4740This is * not emphasized *, and \[rs]*neither is this\[rs]*.
4743.SS Extension: \f[C]intraword_underscores\f[R]
4745Because \f[C]_\f[R] is sometimes used inside words and identifiers,
4746pandoc does not interpret a \f[C]_\f[R] surrounded by alphanumeric
4747characters as an emphasis marker.
4748If you want to emphasize just part of a word, use \f[C]*\f[R]:
4752feas*ible*, not feas*able*.
4756.SS Extension: \f[C]strikeout\f[R]
4758To strikeout a section of text with a horizontal line, begin and end it
4759with \f[C]\[ti]\[ti]\f[R].
4764This \[ti]\[ti]is deleted text.\[ti]\[ti]
4767.SS Superscripts and subscripts
4768.SS Extension: \f[C]superscript\f[R], \f[C]subscript\f[R]
4770Superscripts may be written by surrounding the superscripted text by
4771\f[C]\[ha]\f[R] characters; subscripts may be written by surrounding the
4772subscripted text by \f[C]\[ti]\f[R] characters.
4777H\[ti]2\[ti]O is a liquid. 2\[ha]10\[ha] is 1024.
4781The text between \f[C]\[ha]...\[ha]\f[R] or \f[C]\[ti]...\[ti]\f[R] may
4782not contain spaces or newlines.
4783If the superscripted or subscripted text contains spaces, these spaces
4784must be escaped with backslashes.
4785(This is to prevent accidental superscripting and subscripting through
4786the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad
4787interactions with footnotes.) Thus, if you want the letter P with \[aq]a
4788cat\[aq] in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
4789\f[C]P\[ti]a cat\[ti]\f[R].
4792To make a short span of text verbatim, put it inside backticks:
4796What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]?
4800If the verbatim text includes a backtick, use double backticks:
4804Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga].
4808(The spaces after the opening backticks and before the closing backticks
4811The general rule is that a verbatim span starts with a string of
4812consecutive backticks (optionally followed by a space) and ends with a
4813string of the same number of backticks (optionally preceded by a space).
4815Note that backslash-escapes (and other Markdown constructs) do not work
4816in verbatim contexts:
4820This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga].
4823.SS Extension: \f[C]inline_code_attributes\f[R]
4825Attributes can be attached to verbatim text, just as with fenced code
4830\[ga]<$>\[ga]{.haskell}
4835To write small caps, use the \f[C]smallcaps\f[R] class:
4839[Small caps]{.smallcaps}
4843Or, without the \f[C]bracketed_spans\f[R] extension:
4847<span class=\[dq]smallcaps\[dq]>Small caps</span>
4851For compatibility with other Markdown flavors, CSS is also supported:
4855<span style=\[dq]font-variant:small-caps;\[dq]>Small caps</span>
4859This will work in all output formats that support small caps.
4861.SS Extension: \f[C]tex_math_dollars\f[R]
4863Anything between two \f[C]$\f[R] characters will be treated as TeX math.
4864The opening \f[C]$\f[R] must have a non-space character immediately to
4865its right, while the closing \f[C]$\f[R] must have a non-space character
4866immediately to its left, and must not be followed immediately by a
4868Thus, \f[C]$20,000 and $30,000\f[R] won\[aq]t parse as math.
4869If for some reason you need to enclose text in literal \f[C]$\f[R]
4870characters, backslash-escape them and they won\[aq]t be treated as math
4873For display math, use \f[C]$$\f[R] delimiters.
4874(In this case, the delimiters may be separated from the formula by
4877TeX math will be printed in all output formats.
4878How it is rendered depends on the output format:
4881It will appear verbatim surrounded by \f[C]\[rs](...\[rs])\f[R] (for
4882inline math) or \f[C]\[rs][...\[rs]]\f[R] (for display math).
4884Markdown, Emacs Org mode, ConTeXt, ZimWiki
4885It will appear verbatim surrounded by \f[C]$...$\f[R] (for inline math)
4886or \f[C]$$...$$\f[R] (for display math).
4889It will appear verbatim surrounded by
4890\f[C]{{formula}}..{{/formula}}\f[R].
4893It will be rendered using an interpreted text role \f[C]:math:\f[R].
4896For AsciiDoc output format (\f[C]-t asciidoc\f[R]) it will appear
4897verbatim surrounded by \f[C]latexmath:[$...$]\f[R] (for inline math) or
4898\f[C][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math).
4899For AsciiDoctor output format (\f[C]-t asciidoctor\f[R]) the LaTex
4900delimiters (\f[C]$..$\f[R] and \f[C]\[rs][..\[rs]]\f[R]) are omitted.
4903It will be rendered inside a \f[C]\[at]math\f[R] command.
4905roff man, Jira markup
4906It will be rendered verbatim without \f[C]$\f[R]\[aq]s.
4909It will be rendered inside \f[C]<math>\f[R] tags.
4912It will be rendered inside \f[C]<span class=\[dq]math\[dq]>\f[R] tags.
4915It will be rendered, if possible, using Unicode characters, and will
4916otherwise appear verbatim.
4919It will be rendered, if possible, using MathML.
4922If the \f[C]--mathml\f[R] flag is used, it will be rendered using MathML
4923in an \f[C]inlineequation\f[R] or \f[C]informalequation\f[R] tag.
4924Otherwise it will be rendered, if possible, using Unicode characters.
4927It will be rendered using OMML math markup.
4930If the \f[C]--webtex\f[R] option is used, formulas are rendered as
4931images using CodeCogs or other compatible web service, downloaded and
4932embedded in the e-book.
4933Otherwise, they will appear verbatim.
4935HTML, Slidy, DZSlides, S5, EPUB
4936The way math is rendered in HTML will depend on the command-line options
4938Therefore see Math rendering in HTML above.
4940.SS Extension: \f[C]raw_html\f[R]
4942Markdown allows you to insert raw HTML (or DocBook) anywhere in a
4943document (except verbatim contexts, where \f[C]<\f[R], \f[C]>\f[R], and
4944\f[C]&\f[R] are interpreted literally).
4945(Technically this is not an extension, since standard Markdown allows
4946it, but it has been made an extension so that it can be disabled if
4949The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
4950DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile
4951output, and suppressed in other formats.
4953For a more explicit way of including raw HTML in a Markdown document,
4954see the \f[C]raw_attribute\f[R] extension.
4956In the CommonMark format, if \f[C]raw_html\f[R] is enabled,
4957superscripts, subscripts, strikeouts and small capitals will be
4959Otherwise, plain-text fallbacks will be used.
4960Note that even if \f[C]raw_html\f[R] is disabled, tables will be
4961rendered with HTML syntax if they cannot use pipe syntax.
4962.SS Extension: \f[C]markdown_in_html_blocks\f[R]
4964Standard Markdown allows you to include HTML \[dq]blocks\[dq]: blocks of
4965HTML between balanced tags that are separated from the surrounding text
4966with blank lines, and start and end at the left margin.
4967Within these blocks, everything is interpreted as HTML, not Markdown; so
4968(for example), \f[C]*\f[R] does not signify emphasis.
4970Pandoc behaves this way when the \f[C]markdown_strict\f[R] format is
4971used; but by default, pandoc interprets material between HTML block tags
4973Thus, for example, pandoc will turn
4980<td>[a link](http://google.com)</td>
4992<td><em>one</em></td>
4993<td><a href=\[dq]http://google.com\[dq]>a link</a></td>
4999whereas \f[C]Markdown.pl\f[R] will preserve it as is.
5001There is one exception to this rule: text between \f[C]<script>\f[R] and
5002\f[C]<style>\f[R] tags is not interpreted as Markdown.
5004This departure from standard Markdown should make it easier to mix
5005Markdown with HTML block elements.
5006For example, one can surround a block of Markdown text with
5007\f[C]<div>\f[R] tags without preventing it from being interpreted as
5009.SS Extension: \f[C]native_divs\f[R]
5011Use native pandoc \f[C]Div\f[R] blocks for content inside
5012\f[C]<div>\f[R] tags.
5013For the most part this should give the same output as
5014\f[C]markdown_in_html_blocks\f[R], but it makes it easier to write
5015pandoc filters to manipulate groups of blocks.
5016.SS Extension: \f[C]native_spans\f[R]
5018Use native pandoc \f[C]Span\f[R] blocks for content inside
5019\f[C]<span>\f[R] tags.
5020For the most part this should give the same output as
5021\f[C]raw_html\f[R], but it makes it easier to write pandoc filters to
5022manipulate groups of inlines.
5023.SS Extension: \f[C]raw_tex\f[R]
5025In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
5026included in a document.
5027Inline TeX commands will be preserved and passed unchanged to the LaTeX
5029Thus, for example, you can use LaTeX to include BibTeX citations:
5033This result was proved in \[rs]cite{jones.1967}.
5037Note that in LaTeX environments, like
5041\[rs]begin{tabular}{|l|l|}\[rs]hline
5042Age & Frequency \[rs]\[rs] \[rs]hline
504318--25 & 15 \[rs]\[rs]
504426--35 & 33 \[rs]\[rs]
504536--45 & 22 \[rs]\[rs] \[rs]hline
5050the material between the begin and end tags will be interpreted as raw
5051LaTeX, not as Markdown.
5053For a more explicit and flexible way of including raw TeX in a Markdown
5054document, see the \f[C]raw_attribute\f[R] extension.
5056Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
5057Emacs Org mode, and ConTeXt.
5058.SS Generic raw attribute
5059.SS Extension: \f[C]raw_attribute\f[R]
5061Inline spans and fenced code blocks with a special kind of attribute
5062will be parsed as raw content with the designated format.
5063For example, the following produces a raw roff \f[C]ms\f[R] block:
5074And the following produces a raw \f[C]html\f[R] inline element:
5078This is \[ga]<a>html</a>\[ga]{=html}
5082This can be useful to insert raw xml into \f[C]docx\f[R] documents, e.g.
5087\[ga]\[ga]\[ga]{=openxml}
5090 <w:br w:type=\[dq]page\[dq]/>
5097The format name should match the target format name (see
5098\f[C]-t/--to\f[R], above, for a list, or use
5099\f[C]pandoc --list-output-formats\f[R]).
5100Use \f[C]openxml\f[R] for \f[C]docx\f[R] output, \f[C]opendocument\f[R]
5101for \f[C]odt\f[R] output, \f[C]html5\f[R] for \f[C]epub3\f[R] output,
5102\f[C]html4\f[R] for \f[C]epub2\f[R] output, and \f[C]latex\f[R],
5103\f[C]beamer\f[R], \f[C]ms\f[R], or \f[C]html5\f[R] for \f[C]pdf\f[R]
5104output (depending on what you use for \f[C]--pdf-engine\f[R]).
5106This extension presupposes that the relevant kind of inline code or
5107fenced code block is enabled.
5108Thus, for example, to use a raw attribute with a backtick code block,
5109\f[C]backtick_code_blocks\f[R] must be enabled.
5111The raw attribute cannot be combined with regular attributes.
5113.SS Extension: \f[C]latex_macros\f[R]
5115When this extension is enabled, pandoc will parse LaTeX macro
5116definitions and apply the resulting macros to all LaTeX math and raw
5118So, for example, the following will work in all output formats, not just
5123\[rs]newcommand{\[rs]tuple}[1]{\[rs]langle #1 \[rs]rangle}
5125$\[rs]tuple{a, b, c}$
5129Note that LaTeX macros will not be applied if they occur inside a raw
5130span or block marked with the \f[C]raw_attribute\f[R] extension.
5132When \f[C]latex_macros\f[R] is disabled, the raw LaTeX and math will not
5134This is usually a better approach when you are targeting LaTeX or PDF.
5136Macro definitions in LaTeX will be passed through as raw LaTeX only if
5137\f[C]latex_macros\f[R] is not enabled.
5138Macro definitions in Markdown source (or other formats allowing
5139\f[C]raw_tex\f[R]) will be passed through regardless of whether
5140\f[C]latex_macros\f[R] is enabled.
5143Markdown allows links to be specified in several ways.
5146If you enclose a URL or email address in pointy brackets, it will become
5152<sam\[at]green.eggs.ham>
5157An inline link consists of the link text in square brackets, followed by
5158the URL in parentheses.
5159(Optionally, the URL can be followed by a link title, in quotes.)
5163This is an [inline link](/url), and here\[aq]s [one with
5164a title](http://fsf.org \[dq]click here for a good time!\[dq]).
5168There can be no space between the bracketed part and the parenthesized
5170The link text can contain formatting (such as emphasis), but the title
5173Email addresses in inline links are not autodetected, so they have to be
5174prefixed with \f[C]mailto\f[R]:
5178[Write me!](mailto:sam\[at]green.eggs.ham)
5183An \f[I]explicit\f[R] reference link has two parts, the link itself and
5184the link definition, which may occur elsewhere in the document (either
5185before or after the link).
5187The link consists of link text in square brackets, followed by a label
5189(There cannot be space between the two unless the
5190\f[C]spaced_reference_links\f[R] extension is enabled.) The link
5191definition consists of the bracketed label, followed by a colon and a
5192space, followed by the URL, and optionally (after a space) a link title
5193either in quotes or in parentheses.
5194The label must not be parseable as a citation (assuming the
5195\f[C]citations\f[R] extension is enabled): citations take precedence
5198Here are some examples:
5202[my label 1]: /foo/bar.html \[dq]My title, optional\[dq]
5204[my label 3]: http://fsf.org (The free software foundation)
5205[my label 4]: /bar#special \[aq]A title in single quotes\[aq]
5209The URL may optionally be surrounded by angle brackets:
5213[my label 5]: <http://foo.bar.baz>
5217The title may go on the next line:
5221[my label 3]: http://fsf.org
5222 \[dq]The free software foundation\[dq]
5226Note that link labels are not case sensitive.
5231Here is [my link][FOO]
5237In an \f[I]implicit\f[R] reference link, the second pair of brackets is
5244[my website]: http://foo.bar.baz
5248Note: In \f[C]Markdown.pl\f[R] and most other Markdown implementations,
5249reference link definitions cannot occur in nested constructions such as
5250list items or block quotes.
5251Pandoc lifts this arbitrary seeming restriction.
5252So the following is fine in pandoc, though not in most other
5262.SS Extension: \f[C]shortcut_reference_links\f[R]
5264In a \f[I]shortcut\f[R] reference link, the second pair of brackets may
5271[my website]: http://foo.bar.baz
5276To link to another section of the same document, use the automatically
5277generated identifier (see Heading identifiers).
5282See the [Introduction](#introduction).
5290See the [Introduction].
5292[Introduction]: #introduction
5296Internal links are currently supported for HTML formats (including HTML
5297slide shows and EPUB), LaTeX, and ConTeXt.
5300A link immediately preceded by a \f[C]!\f[R] will be treated as an
5302The link text will be used as the image\[aq]s alt text:
5306
5310[movie reel]: movie.gif
5313.SS Extension: \f[C]implicit_figures\f[R]
5315An image with nonempty alt text, occurring by itself in a paragraph,
5316will be rendered as a figure with a caption.
5317The image\[aq]s alt text will be used as the caption.
5321
5325How this is rendered depends on the output format.
5326Some output formats (e.g.
5327RTF) do not yet support figures.
5328In those formats, you\[aq]ll just get an image in a paragraph by itself,
5331If you just want a regular inline image, just make sure it is not the
5332only thing in the paragraph.
5333One way to do this is to insert a nonbreaking space after the image:
5337![This image won\[aq]t be a figure](/url/of/image.png)\[rs]
5341Note that in reveal.js slide shows, an image in a paragraph by itself
5342that has the \f[C]stretch\f[R] class will fill the screen, and the
5343caption and figure tags will be omitted.
5344.SS Extension: \f[C]link_attributes\f[R]
5346Attributes can be set on links and images:
5350An inline {#id .class width=30 height=20px}
5351and a reference ![image][ref] with attributes.
5353[ref]: foo.jpg \[dq]optional title\[dq] {#id .class key=val key2=\[dq]val 2\[dq]}
5357(This syntax is compatible with PHP Markdown Extra when only
5358\f[C]#id\f[R] and \f[C].class\f[R] are used.)
5360For HTML and EPUB, all known HTML5 attributes except \f[C]width\f[R] and
5361\f[C]height\f[R] (but including \f[C]srcset\f[R] and \f[C]sizes\f[R])
5362are passed through as is.
5363Unknown attributes are passed through as custom attributes, with
5364\f[C]data-\f[R] prepended.
5365The other writers ignore attributes that are not specifically supported
5366by their output format.
5368The \f[C]width\f[R] and \f[C]height\f[R] attributes on images are
5370When used without a unit, the unit is assumed to be pixels.
5371However, any of the following unit identifiers can be used:
5372\f[C]px\f[R], \f[C]cm\f[R], \f[C]mm\f[R], \f[C]in\f[R], \f[C]inch\f[R]
5374There must not be any spaces between the number and the unit.
5379{ width=50% }
5383Dimensions are converted to inches for output in page-based formats like
5385Dimensions are converted to pixels for output in HTML-like formats.
5386Use the \f[C]--dpi\f[R] option to specify the number of pixels per inch.
5387The default is 96dpi.
5389The \f[C]%\f[R] unit is generally relative to some available space.
5390For example the above example will render to the following.
5394\f[C]<img href=\[dq]file.jpg\[dq] style=\[dq]width: 50%;\[dq] />\f[R]
5397\f[C]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]
5398(If you\[aq]re using a custom template, you need to configure
5399\f[C]graphicx\f[R] as in the default template.)
5402\f[C]\[rs]externalfigure[file.jpg][width=0.5\[rs]textwidth]\f[R]
5405Some output formats have a notion of a class (ConTeXt) or a unique
5406identifier (LaTeX \f[C]\[rs]caption\f[R]), or both (HTML).
5408When no \f[C]width\f[R] or \f[C]height\f[R] attributes are specified,
5409the fallback is to look at the image resolution and the dpi metadata
5410embedded in the image file.
5413Using the \f[C]native_divs\f[R] and \f[C]native_spans\f[R] extensions
5414(see above), HTML syntax can be used as part of markdown to create
5415native \f[C]Div\f[R] and \f[C]Span\f[R] elements in the pandoc AST (as
5416opposed to raw HTML).
5417However, there is also nicer syntax available:
5418.SS Extension: \f[C]fenced_divs\f[R]
5420Allow special fenced syntax for native \f[C]Div\f[R] blocks.
5421A Div starts with a fence containing at least three consecutive colons
5422plus some attributes.
5423The attributes may optionally be followed by another string of
5425The attribute syntax is exactly as in fenced code blocks (see Extension:
5426\f[C]fenced_code_attributes\f[R]).
5427As with fenced code blocks, one can use either attributes in curly
5428braces or a single unbraced word, which will be treated as a class name.
5429The Div ends with another line containing a string of at least three
5431The fenced Div should be separated by blank lines from preceding and
5438::::: {#special .sidebar}
5446Fenced divs can be nested.
5447Opening fences are distinguished because they \f[I]must\f[R] have
5456This is a warning within a warning.
5462Fences without attributes are always closing fences.
5463Unlike with fenced code blocks, the number of colons in the closing
5464fence need not match the number in the opening fence.
5465However, it can be helpful for visual clarity to use fences of different
5466lengths to distinguish nested divs from their parents.
5467.SS Extension: \f[C]bracketed_spans\f[R]
5469A bracketed sequence of inlines, as one would use to begin a link, will
5470be treated as a \f[C]Span\f[R] with attributes if it is followed
5471immediately by attributes:
5475[This is *some text*]{.class key=\[dq]val\[dq]}
5479.SS Extension: \f[C]footnotes\f[R]
5481Pandoc\[aq]s Markdown allows footnotes, using the following syntax:
5485Here is a footnote reference,[\[ha]1] and another.[\[ha]longnote]
5487[\[ha]1]: Here is the footnote.
5489[\[ha]longnote]: Here\[aq]s one with multiple blocks.
5491 Subsequent paragraphs are indented to show that they
5492belong to the previous footnote.
5496 The whole paragraph can be indented, or just the first
5497 line. In this way, multi-paragraph footnotes work like
5498 multi-paragraph list items.
5500This paragraph won\[aq]t be part of the note, because it
5505The identifiers in footnote references may not contain spaces, tabs, or
5507These identifiers are used only to correlate the footnote reference with
5508the note itself; in the output, footnotes will be numbered sequentially.
5510The footnotes themselves need not be placed at the end of the document.
5511They may appear anywhere except inside other block elements (lists,
5512block quotes, tables, etc.).
5513Each footnote should be separated from surrounding content (including
5514other footnotes) by blank lines.
5515.SS Extension: \f[C]inline_notes\f[R]
5517Inline footnotes are also allowed (though, unlike regular notes, they
5518cannot contain multiple paragraphs).
5519The syntax is as follows:
5523Here is an inline note.\[ha][Inlines notes are easier to write, since
5524you don\[aq]t have to pick an identifier and move down to type the
5529Inline and regular footnotes may be mixed freely.
5531.SS Extension: \f[C]citations\f[R]
5533Using an external filter, \f[C]pandoc-citeproc\f[R], pandoc can
5534automatically generate citations and a bibliography in a number of
5540pandoc --filter pandoc-citeproc myinput.txt
5544In order to use this feature, you will need to specify a bibliography
5545file using the \f[C]bibliography\f[R] metadata field in a YAML metadata
5546section, or \f[C]--bibliography\f[R] command line argument.
5547You can supply multiple \f[C]--bibliography\f[R] arguments or set
5548\f[C]bibliography\f[R] metadata field to YAML array, if you want to use
5549multiple bibliography files.
5550The bibliography may have any of these formats:
5618Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX
5619files; use \f[C].bibtex\f[R] to force BibTeX.
5621Note that \f[C]pandoc-citeproc --bib2json\f[R] and
5622\f[C]pandoc-citeproc --bib2yaml\f[R] can produce \f[C].json\f[R] and
5623\f[C].yaml\f[R] files from any of the supported formats.
5625In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
5626parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown;
5627and in CSL JSON databases, an HTML-like markup:
5629\f[B]\f[CB]<i>...</i>\f[B]\f[R]
5632\f[B]\f[CB]<b>...</b>\f[B]\f[R]
5635\f[B]\f[CB]<span style=\[dq]font-variant:small-caps;\[dq]>...</span>\f[B]\f[R] or \f[B]\f[CB]<sc>...</sc>\f[B]\f[R]
5638\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]
5641\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]
5644\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]
5645prevent a phrase from being capitalized as title case
5647\f[C]pandoc-citeproc -j\f[R] and \f[C]-y\f[R] interconvert the CSL JSON
5648and CSL YAML formats as far as possible.
5650As an alternative to specifying a bibliography file using
5651\f[C]--bibliography\f[R] or the YAML metadata field
5652\f[C]bibliography\f[R], you can include the citation data directly in
5653the \f[C]references\f[R] field of the document\[aq]s YAML metadata.
5654The field should contain an array of YAML-encoded references, for
5661- type: article-journal
5673 title: \[aq]Molecular structure of nucleic acids: a structure for deoxyribose
5675 title-short: Molecular structure of nucleic acids
5676 container-title: Nature
5680 DOI: 10.1038/171737a0
5681 URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
5687(\f[C]pandoc-citeproc --bib2yaml\f[R] can produce these from a
5688bibliography file in one of the supported formats.)
5690Citations and references can be formatted using any style supported by
5691the Citation Style Language, listed in the Zotero Style Repository.
5692These files are specified using the \f[C]--csl\f[R] option or the
5693\f[C]csl\f[R] metadata field.
5694By default, \f[C]pandoc-citeproc\f[R] will use the Chicago Manual of
5695Style author-date format.
5696The CSL project provides further information on finding and editing
5699To make your citations hyperlinks to the corresponding bibliography
5700entries, add \f[C]link-citations: true\f[R] to your YAML metadata.
5702Citations go inside square brackets and are separated by semicolons.
5703Each citation must have a key, composed of \[aq]\[at]\[aq] + the
5704citation identifier from the database, and may optionally have a prefix,
5705a locator, and a suffix.
5706The citation key must begin with a letter, digit, or \f[C]_\f[R], and
5707may contain alphanumerics, \f[C]_\f[R], and internal punctuation
5708characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]).
5709Here are some examples:
5713Blah blah [see \[at]doe99, pp. 33-35; also \[at]smith04, chap. 1].
5715Blah blah [\[at]doe99, pp. 33-35, 38-39 and *passim*].
5717Blah blah [\[at]smith04; \[at]doe99].
5721\f[C]pandoc-citeproc\f[R] detects locator terms in the CSL locale files.
5722Either abbreviated or unabbreviated forms are accepted.
5723In the \f[C]en-US\f[R] locale, locator terms can be written in either
5724singular or plural forms, as \f[C]book\f[R],
5725\f[C]bk.\f[R]/\f[C]bks.\f[R]; \f[C]chapter\f[R],
5726\f[C]chap.\f[R]/\f[C]chaps.\f[R]; \f[C]column\f[R],
5727\f[C]col.\f[R]/\f[C]cols.\f[R]; \f[C]figure\f[R],
5728\f[C]fig.\f[R]/\f[C]figs.\f[R]; \f[C]folio\f[R],
5729\f[C]fol.\f[R]/\f[C]fols.\f[R]; \f[C]number\f[R],
5730\f[C]no.\f[R]/\f[C]nos.\f[R]; \f[C]line\f[R],
5731\f[C]l.\f[R]/\f[C]ll.\f[R]; \f[C]note\f[R], \f[C]n.\f[R]/\f[C]nn.\f[R];
5732\f[C]opus\f[R], \f[C]op.\f[R]/\f[C]opp.\f[R]; \f[C]page\f[R],
5733\f[C]p.\f[R]/\f[C]pp.\f[R]; \f[C]paragraph\f[R],
5734\f[C]para.\f[R]/\f[C]paras.\f[R]; \f[C]part\f[R],
5735\f[C]pt.\f[R]/\f[C]pts.\f[R]; \f[C]section\f[R],
5736\f[C]sec.\f[R]/\f[C]secs.\f[R]; \f[C]sub verbo\f[R],
5737\f[C]s.v.\f[R]/\f[C]s.vv.\f[R]; \f[C]verse\f[R],
5738\f[C]v.\f[R]/\f[C]vv.\f[R]; \f[C]volume\f[R],
5739\f[C]vol.\f[R]/\f[C]vols.\f[R]; \f[C]\[ps]\f[R]/\f[C]\[ps]\[ps]\f[R];
5740\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
5741If no locator term is used, \[dq]page\[dq] is assumed.
5743\f[C]pandoc-citeproc\f[R] will use heuristics to distinguish the locator
5745In complex cases, the locator can be enclosed in curly braces (using
5746\f[C]pandoc-citeproc\f[R] 0.15 and higher only):
5750[\[at]smith{ii, A, D-Z}, with a suffix]
5751[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
5755A minus sign (\f[C]-\f[R]) before the \f[C]\[at]\f[R] will suppress
5756mention of the author in the citation.
5757This can be useful when the author is already mentioned in the text:
5761Smith says blah [-\[at]smith04].
5765You can also write an in-text citation, as follows:
5769\[at]smith04 says blah.
5771\[at]smith04 [p. 33] says blah.
5775If the style calls for a list of works cited, it will be placed in a div
5776with id \f[C]refs\f[R], if one exists:
5785Otherwise, it will be placed at the end of the document.
5786Generation of the bibliography can be suppressed by setting
5787\f[C]suppress-bibliography: true\f[R] in the YAML metadata.
5789If you wish the bibliography to have a section heading, you can set
5790\f[C]reference-section-title\f[R] in the metadata, or put the heading at
5791the beginning of the div with id \f[C]refs\f[R] (if you are using it) or
5792at the end of your document:
5802The bibliography will be inserted after this heading.
5803Note that the \f[C]unnumbered\f[R] class will be added to this heading,
5804so that the section will not be numbered.
5806If you want to include items in the bibliography without actually citing
5807them in the body text, you can define a dummy \f[C]nocite\f[R] metadata
5808field and put the citations there:
5814 \[at]item1, \[at]item2
5821In this example, the document will contain a citation for
5822\f[C]item3\f[R] only, but the bibliography will contain entries for
5823\f[C]item1\f[R], \f[C]item2\f[R], and \f[C]item3\f[R].
5825It is possible to create a bibliography with all the citations, whether
5826or not they appear in the document, by using a wildcard:
5837For LaTeX output, you can also use \f[C]natbib\f[R] or
5838\f[C]biblatex\f[R] to render the bibliography.
5839In order to do so, specify bibliography files as outlined above, and add
5840\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]
5842Bear in mind that bibliography files have to be in respective format
5843(either BibTeX or BibLaTeX).
5845For more information, see the pandoc-citeproc man page.
5846.SS Non-pandoc extensions
5848The following Markdown syntax extensions are not enabled by default in
5849pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
5850name, where \f[C]EXTENSION\f[R] is the name of the extension.
5851Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with
5853.SS Extension: \f[C]old_dashes\f[R]
5855Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
5856\f[C]-\f[R] before a numeral is an en-dash, and \f[C]--\f[R] is an
5858This option only has an effect if \f[C]smart\f[R] is enabled.
5859It is selected automatically for \f[C]textile\f[R] input.
5860.SS Extension: \f[C]angle_brackets_escapable\f[R]
5862Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can
5863be in GitHub flavored Markdown but not original Markdown.
5864This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[R].
5865.SS Extension: \f[C]lists_without_preceding_blankline\f[R]
5867Allow a list to occur right after a paragraph, with no intervening blank
5869.SS Extension: \f[C]four_space_rule\f[R]
5871Selects the pandoc <= 2.0 behavior for parsing lists, so that four
5872spaces indent are needed for list item continuation paragraphs.
5873.SS Extension: \f[C]spaced_reference_links\f[R]
5875Allow whitespace between the two components of a reference link, for
5883.SS Extension: \f[C]hard_line_breaks\f[R]
5885Causes all newlines within a paragraph to be interpreted as hard line
5886breaks instead of spaces.
5887.SS Extension: \f[C]ignore_line_breaks\f[R]
5889Causes newlines within a paragraph to be ignored, rather than being
5890treated as spaces or as hard line breaks.
5891This option is intended for use with East Asian languages where spaces
5892are not used between words, but text is divided into lines for
5894.SS Extension: \f[C]east_asian_line_breaks\f[R]
5896Causes newlines within a paragraph to be ignored, rather than being
5897treated as spaces or as hard line breaks, when they occur between two
5898East Asian wide characters.
5899This is a better choice than \f[C]ignore_line_breaks\f[R] for texts that
5900include a mix of East Asian wide characters and other characters.
5901.SS Extension: \f[C]emoji\f[R]
5903Parses textual emojis like \f[C]:smile:\f[R] as Unicode emoticons.
5904.SS Extension: \f[C]tex_math_single_backslash\f[R]
5906Causes anything between \f[C]\[rs](\f[R] and \f[C]\[rs])\f[R] to be
5907interpreted as inline TeX math, and anything between \f[C]\[rs][\f[R]
5908and \f[C]\[rs]]\f[R] to be interpreted as display TeX math.
5909Note: a drawback of this extension is that it precludes escaping
5910\f[C](\f[R] and \f[C][\f[R].
5911.SS Extension: \f[C]tex_math_double_backslash\f[R]
5913Causes anything between \f[C]\[rs]\[rs](\f[R] and \f[C]\[rs]\[rs])\f[R]
5914to be interpreted as inline TeX math, and anything between
5915\f[C]\[rs]\[rs][\f[R] and \f[C]\[rs]\[rs]]\f[R] to be interpreted as
5917.SS Extension: \f[C]markdown_attribute\f[R]
5919By default, pandoc interprets material inside block-level tags as
5921This extension changes the behavior so that Markdown is only parsed
5922inside block-level tags if the tags have the attribute
5923\f[C]markdown=1\f[R].
5924.SS Extension: \f[C]mmd_title_block\f[R]
5926Enables a MultiMarkdown style title block at the top of the document,
5933Date: September 1, 2008
5934Comment: This is a sample mmd title block, with
5935 a field spanning multiple lines.
5939See the MultiMarkdown documentation for details.
5940If \f[C]pandoc_title_block\f[R] or \f[C]yaml_metadata_block\f[R] is
5941enabled, it will take precedence over \f[C]mmd_title_block\f[R].
5942.SS Extension: \f[C]abbreviations\f[R]
5944Parses PHP Markdown Extra abbreviation keys, like
5948*[HTML]: Hypertext Markup Language
5952Note that the pandoc document model does not support abbreviations, so
5953if this extension is enabled, abbreviation keys are simply skipped (as
5954opposed to being parsed as paragraphs).
5955.SS Extension: \f[C]autolink_bare_uris\f[R]
5957Makes all absolute URIs into links, even when not surrounded by pointy
5958braces \f[C]<...>\f[R].
5959.SS Extension: \f[C]mmd_link_attributes\f[R]
5961Parses multimarkdown style key-value attributes on link and image
5963This extension should not be confused with the \f[C]link_attributes\f[R]
5968This is a reference ![image][ref] with multimarkdown attributes.
5970[ref]: http://path.to/image \[dq]Image title\[dq] width=20px height=30px
5971 id=myId class=\[dq]myClass1 myClass2\[dq]
5974.SS Extension: \f[C]mmd_header_identifiers\f[R]
5976Parses multimarkdown style heading identifiers (in square brackets,
5977after the heading but before any trailing \f[C]#\f[R]s in an ATX
5979.SS Extension: \f[C]compact_definition_lists\f[R]
5981Activates the definition list syntax of pandoc 1.12.x and earlier.
5982This syntax differs from the one described above under Definition lists
5985No blank line is required between consecutive items of the definition
5988To get a \[dq]tight\[dq] or \[dq]compact\[dq] list, omit space between
5989consecutive items; the space between a term and its definition does not
5992Lazy wrapping of paragraphs is not allowed: the entire definition must
5993be indented four spaces.
5994.SS Extension: \f[C]gutenberg\f[R]
5996Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
5997for strong emphasis, surround by underscores for regular emphasis, add
5998extra blank space around headings.
5999.SS Markdown variants
6001In addition to pandoc\[aq]s extended Markdown, the following Markdown
6002variants are supported:
6004\f[B]\f[CB]markdown_phpextra\f[B]\f[R] (PHP Markdown Extra)
6005\f[C]footnotes\f[R], \f[C]pipe_tables\f[R], \f[C]raw_html\f[R],
6006\f[C]markdown_attribute\f[R], \f[C]fenced_code_blocks\f[R],
6007\f[C]definition_lists\f[R], \f[C]intraword_underscores\f[R],
6008\f[C]header_attributes\f[R], \f[C]link_attributes\f[R],
6009\f[C]abbreviations\f[R], \f[C]shortcut_reference_links\f[R],
6010\f[C]spaced_reference_links\f[R].
6012\f[B]\f[CB]markdown_github\f[B]\f[R] (deprecated GitHub-Flavored Markdown)
6013\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
6014\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
6015\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
6016\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
6017\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
6018\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6019\f[C]lists_without_preceding_blankline\f[R].
6021\f[B]\f[CB]markdown_mmd\f[B]\f[R] (MultiMarkdown)
6022\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]markdown_attribute\f[R],
6023\f[C]mmd_link_attributes\f[R], \f[C]tex_math_double_backslash\f[R],
6024\f[C]intraword_underscores\f[R], \f[C]mmd_title_block\f[R],
6025\f[C]footnotes\f[R], \f[C]definition_lists\f[R],
6026\f[C]all_symbols_escapable\f[R], \f[C]implicit_header_references\f[R],
6027\f[C]auto_identifiers\f[R], \f[C]mmd_header_identifiers\f[R],
6028\f[C]shortcut_reference_links\f[R], \f[C]implicit_figures\f[R],
6029\f[C]superscript\f[R], \f[C]subscript\f[R],
6030\f[C]backtick_code_blocks\f[R], \f[C]spaced_reference_links\f[R],
6031\f[C]raw_attribute\f[R].
6033\f[B]\f[CB]markdown_strict\f[B]\f[R] (Markdown.pl)
6034\f[C]raw_html\f[R], \f[C]shortcut_reference_links\f[R],
6035\f[C]spaced_reference_links\f[R].
6037We also support \f[C]commonmark\f[R] and \f[C]gfm\f[R] (GitHub-Flavored
6038Markdown, which is implemented as a set of extensions on
6039\f[C]commonmark\f[R]).
6041Note, however, that \f[C]commonmark\f[R] and \f[C]gfm\f[R] have limited
6042support for extensions.
6043Only those listed below (and \f[C]smart\f[R], \f[C]raw_tex\f[R], and
6044\f[C]hard_line_breaks\f[R]) will work.
6045The extensions can, however, all be individually disabled.
6046Also, \f[C]raw_tex\f[R] only affects \f[C]gfm\f[R] output, not input.
6048\f[B]\f[CB]gfm\f[B]\f[R] (GitHub-Flavored Markdown)
6049\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
6050\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
6051\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
6052\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
6053\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
6054\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6055\f[C]lists_without_preceding_blankline\f[R].
6056.SH PRODUCING SLIDE SHOWS WITH PANDOC
6058You can use pandoc to produce an HTML + JavaScript slide presentation
6059that can be viewed via a web browser.
6060There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or
6062You can also produce a PDF slide show using LaTeX \f[C]beamer\f[R], or
6063slides shows in Microsoft PowerPoint format.
6065Here\[aq]s the Markdown source for a simple slide show,
6066\f[C]habits.txt\f[R]:
6095
6104To produce an HTML/JavaScript slide show, simply type
6108pandoc -t FORMAT -s habits.txt -o habits.html
6112where \f[C]FORMAT\f[R] is either \f[C]s5\f[R], \f[C]slidy\f[R],
6113\f[C]slideous\f[R], \f[C]dzslides\f[R], or \f[C]revealjs\f[R].
6115For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with
6116the \f[C]-s/--standalone\f[R] option embeds a link to JavaScript and CSS
6117files, which are assumed to be available at the relative path
6118\f[C]s5/default\f[R] (for S5), \f[C]slideous\f[R] (for Slideous),
6119\f[C]reveal.js\f[R] (for reveal.js), or at the Slidy website at
6120\f[C]w3.org\f[R] (for Slidy).
6121(These paths can be changed by setting the \f[C]slidy-url\f[R],
6122\f[C]slideous-url\f[R], \f[C]revealjs-url\f[R], or \f[C]s5-url\f[R]
6123variables; see Variables for HTML slides, above.) For DZSlides, the
6124(relatively short) JavaScript and CSS are included in the file by
6127With all HTML slide formats, the \f[C]--self-contained\f[R] option can
6128be used to produce a single file that contains all of the data necessary
6129to display the slide show, including linked scripts, stylesheets,
6132To produce a PDF slide show using beamer, type
6136pandoc -t beamer habits.txt -o habits.pdf
6140Note that a reveal.js slide show can also be converted to a PDF by
6141printing it to a file from the browser.
6143To produce a Powerpoint slide show, type
6147pandoc habits.txt -o habits.pptx
6150.SS Structuring the slide show
6152By default, the \f[I]slide level\f[R] is the highest heading level in
6153the hierarchy that is followed immediately by content, and not another
6154heading, somewhere in the document.
6155In the example above, level-1 headings are always followed by level-2
6156headings, which are followed by content, so the slide level is 2.
6157This default can be overridden using the \f[C]--slide-level\f[R] option.
6159The document is carved up into slides according to the following rules:
6161A horizontal rule always starts a new slide.
6163A heading at the slide level always starts a new slide.
6165Headings \f[I]below\f[R] the slide level in the hierarchy create
6166headings \f[I]within\f[R] a slide.
6168Headings \f[I]above\f[R] the slide level in the hierarchy create
6169\[dq]title slides,\[dq] which just contain the section title and help to
6170break the slide show into sections.
6171Non-slide content under these headings will be included on the title
6172slide (for HTML slide shows) or in a subsequent slide with the same
6175A title page is constructed automatically from the document\[aq]s title
6177(In the case of beamer, this can be disabled by commenting out some
6178lines in the default template.)
6180These rules are designed to support many different styles of slide show.
6181If you don\[aq]t care about structuring your slides into sections and
6182subsections, you can just use level-1 headings for all each slide.
6183(In that case, level-1 will be the slide level.) But you can also
6184structure the slide show into sections, as in the example above.
6186Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
6187layout will be produced, with level-1 headings building horizontally and
6188level-2 headings building vertically.
6189It is not recommended that you use deeper nesting of section levels with
6191.SS Incremental lists
6193By default, these writers produce lists that display \[dq]all at
6194once.\[dq] If you want your lists to display incrementally (one item at
6195a time), use the \f[C]-i\f[R] option.
6196If you want a particular list to depart from the default, put it in a
6197\f[C]div\f[R] block with class \f[C]incremental\f[R] or
6198\f[C]nonincremental\f[R].
6199So, for example, using the \f[C]fenced div\f[R] syntax, the following
6200would be incremental regardless of the document default:
6226While using \f[C]incremental\f[R] and \f[C]nonincremental\f[R] divs are
6227the recommended method of setting incremental lists on a per-case basis,
6228an older method is also supported: putting lists inside a blockquote
6229will depart from the document default (that is, it will display
6230incrementally without the \f[C]-i\f[R] option and all at once with the
6231\f[C]-i\f[R] option):
6240Both methods allow incremental and nonincremental lists to be mixed in a
6243Note: Neither the \f[C]-i/--incremental\f[R] option nor any of the
6244methods described here currently works for PowerPoint output.
6247You can add \[dq]pauses\[dq] within a slide by including a paragraph
6248containing three dots, separated by spaces:
6254content before the pause
6258content after the pause
6262Note: this feature is not yet implemented for PowerPoint output.
6263.SS Styling the slides
6265You can change the style of HTML slides by putting customized CSS files
6266in \f[C]$DATADIR/s5/default\f[R] (for S5), \f[C]$DATADIR/slidy\f[R] (for
6267Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where
6268\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
6270The originals may be found in pandoc\[aq]s system data directory
6271(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).
6272Pandoc will look there for any files it does not find in the user data
6275For dzslides, the CSS is included in the HTML file itself, and may be
6278All reveal.js configuration options can be set through variables.
6279For example, themes can be used by setting the \f[C]theme\f[R] variable:
6287Or you can specify a custom stylesheet using the \f[C]--css\f[R] option.
6289To style beamer slides, you can specify a \f[C]theme\f[R],
6290\f[C]colortheme\f[R], \f[C]fonttheme\f[R], \f[C]innertheme\f[R], and
6291\f[C]outertheme\f[R], using the \f[C]-V\f[R] option:
6295pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
6299Note that heading attributes will turn into slide attributes (on a
6300\f[C]<div>\f[R] or \f[C]<section>\f[R]) in HTML slide formats, allowing
6301you to style individual slides.
6302In beamer, the only heading attribute that affects slides is the
6303\f[C]allowframebreaks\f[R] class, which sets the
6304\f[C]allowframebreaks\f[R] option, causing multiple slides to be created
6305if the content overfills the frame.
6306This is recommended especially for bibliographies:
6310# References {.allowframebreaks}
6315Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
6316You can add notes to your Markdown document thus:
6324- It can contain Markdown
6331To show the notes window in reveal.js, press \f[C]s\f[R] while viewing
6333Speaker notes in PowerPoint will be available, as usual, in handouts and
6336Notes are not yet supported for other slide formats, but the notes will
6337not appear on the slides themselves.
6340To put material in side by side columns, you can use a native div
6341container with class \f[C]columns\f[R], containing two or more div
6342containers with class \f[C]column\f[R] and a \f[C]width\f[R] attribute:
6346:::::::::::::: {.columns}
6347::: {.column width=\[dq]40%\[dq]}
6350::: {.column width=\[dq]60%\[dq]}
6356.SS Frame attributes in beamer
6358Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[R] option to
6359a frame in beamer (for example, when using the \f[C]minted\f[R]
6361This can be forced by adding the \f[C]fragile\f[R] class to the heading
6362introducing the slide:
6366# Fragile slide {.fragile}
6370All of the other frame attributes described in Section 8.1 of the Beamer
6371User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
6372\f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],
6373\f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],
6374\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
6375.SS Background in reveal.js and beamer
6377Background images can be added to self-contained reveal.js slideshows
6378and to beamer slideshows.
6380For the same image on every slide, use the configuration option
6381\f[C]background-image\f[R] either in the YAML metadata block or as a
6382command-line variable.
6383(There are no other options in beamer and the rest of this section
6384concerns reveal.js slideshows.)
6386For reveal.js, you can instead use the reveal.js-native option
6387\f[C]parallaxBackgroundImage\f[R].
6388You can also set \f[C]parallaxBackgroundHorizontal\f[R] and
6389\f[C]parallaxBackgroundVertical\f[R] the same way and must also set
6390\f[C]parallaxBackgroundSize\f[R] to have your values take effect.
6392To set an image for a particular reveal.js slide, add
6393\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
6394slide-level heading on the slide (which may even be empty).
6396In reveal.js\[aq]s overview mode, the parallaxBackgroundImage will show
6397up only on the first slide.
6399Other reveal.js background settings also work on individual slides,
6400including \f[C]data-background-size\f[R],
6401\f[C]data-background-repeat\f[R], \f[C]data-background-color\f[R],
6402\f[C]data-transition\f[R], and \f[C]data-transition-speed\f[R].
6404To add a background image to the automatically generated title slide,
6405use the \f[C]title-slide-attributes\f[R] variable in the YAML metadata
6407It must contain a map of attribute names and values.
6409See the reveal.js documentation for more details.
6411For example in reveal.js:
6417parallaxBackgroundImage: /path/to/my/background_image.png
6418title-slide-attributes:
6419 data-background-image: /path/to/title_image.png
6420 data-background-size: contain
6425Slide 1 has background_image.png as its background.
6427## {data-background-image=\[dq]/path/to/special_image.jpg\[dq]}
6429Slide 2 has a special image for its background, even though the heading has no content.
6432.SH CREATING EPUBS WITH PANDOC
6435EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]
6436option, but if the source document is Markdown, it is better to use a
6447 text: An investigation of metadata
6455 text: doi:10.234234.234/33
6457rights: \[co] 2007 John Smith, CC BY-NC
6464The following fields are recognized:
6466\f[B]\f[CB]identifier\f[B]\f[R]
6467Either a string value or an object with fields \f[C]text\f[R] and
6469Valid values for \f[C]scheme\f[R] are \f[C]ISBN-10\f[R],
6470\f[C]GTIN-13\f[R], \f[C]UPC\f[R], \f[C]ISMN-10\f[R], \f[C]DOI\f[R],
6471\f[C]LCCN\f[R], \f[C]GTIN-14\f[R], \f[C]ISBN-13\f[R],
6472\f[C]Legal deposit number\f[R], \f[C]URN\f[R], \f[C]OCLC\f[R],
6473\f[C]ISMN-13\f[R], \f[C]ISBN-A\f[R], \f[C]JP\f[R], \f[C]OLCC\f[R].
6475\f[B]\f[CB]title\f[B]\f[R]
6476Either a string value, or an object with fields \f[C]file-as\f[R] and
6477\f[C]type\f[R], or a list of such objects.
6478Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],
6479\f[C]short\f[R], \f[C]collection\f[R], \f[C]edition\f[R],
6482\f[B]\f[CB]creator\f[B]\f[R]
6483Either a string value, or an object with fields \f[C]role\f[R],
6484\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.
6485Valid values for \f[C]role\f[R] are MARC relators, but pandoc will
6486attempt to translate the human-readable versions (like \[dq]author\[dq]
6487and \[dq]editor\[dq]) to the appropriate marc relators.
6489\f[B]\f[CB]contributor\f[B]\f[R]
6490Same format as \f[C]creator\f[R].
6492\f[B]\f[CB]date\f[B]\f[R]
6493A string value in \f[C]YYYY-MM-DD\f[R] format.
6494(Only the year is necessary.) Pandoc will attempt to convert other
6497\f[B]\f[CB]lang\f[B]\f[R] (or legacy: \f[B]\f[CB]language\f[B]\f[R])
6498A string value in BCP 47 format.
6499Pandoc will default to the local language if nothing is specified.
6501\f[B]\f[CB]subject\f[B]\f[R]
6502A string value or a list of such values.
6504\f[B]\f[CB]description\f[B]\f[R]
6507\f[B]\f[CB]type\f[B]\f[R]
6510\f[B]\f[CB]format\f[B]\f[R]
6513\f[B]\f[CB]relation\f[B]\f[R]
6516\f[B]\f[CB]coverage\f[B]\f[R]
6519\f[B]\f[CB]rights\f[B]\f[R]
6522\f[B]\f[CB]cover-image\f[B]\f[R]
6523A string value (path to cover image).
6525\f[B]\f[CB]css\f[B]\f[R] (or legacy: \f[B]\f[CB]stylesheet\f[B]\f[R])
6526A string value (path to CSS stylesheet).
6528\f[B]\f[CB]page-progression-direction\f[B]\f[R]
6529Either \f[C]ltr\f[R] or \f[C]rtl\f[R].
6530Specifies the \f[C]page-progression-direction\f[R] attribute for the
6531\f[C]spine\f[R] element.
6533\f[B]\f[CB]ibooks\f[B]\f[R]
6534iBooks-specific metadata, with the following fields:
6537\f[C]version\f[R]: (string)
6539\f[C]specified-fonts\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
6542\f[C]ipad-orientation-lock\f[R]:
6543\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
6545\f[C]iphone-orientation-lock\f[R]:
6546\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
6548\f[C]binding\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
6551\f[C]scroll-axis\f[R]:
6552\f[C]vertical\f[R]|\f[C]horizontal\f[R]|\f[C]default\f[R]
6554.SS The \f[C]epub:type\f[R] attribute
6556For \f[C]epub3\f[R] output, you can mark up the heading that corresponds
6557to an EPUB chapter using the \f[C]epub:type\f[R] attribute.
6558For example, to set the attribute to the value \f[C]prologue\f[R], use
6563# My chapter {epub:type=prologue}
6567Which will result in:
6571<body epub:type=\[dq]frontmatter\[dq]>
6572 <section epub:type=\[dq]prologue\[dq]>
6577Pandoc will output \f[C]<body epub:type=\[dq]bodymatter\[dq]>\f[R],
6578unless you use one of the following values, in which case either
6579\f[C]frontmatter\f[R] or \f[C]backmatter\f[R] will be output.
6585\f[C]epub:type\f[R] of first section
6587\f[C]epub:type\f[R] of body
6708By default, pandoc will download media referenced from any
6709\f[C]<img>\f[R], \f[C]<audio>\f[R], \f[C]<video>\f[R] or
6710\f[C]<source>\f[R] element present in the generated EPUB, and include it
6711in the EPUB container, yielding a completely self-contained EPUB.
6712If you want to link to external media resources instead, use raw HTML in
6713your source and add \f[C]data-external=\[dq]1\[dq]\f[R] to the tag with
6714the \f[C]src\f[R] attribute.
6719<audio controls=\[dq]1\[dq]>
6720 <source src=\[dq]http://example.com/music/toccata.mp3\[dq]
6721 data-external=\[dq]1\[dq] type=\[dq]audio/mpeg\[dq]>
6726.SH CREATING JUPYTER NOTEBOOKS WITH PANDOC
6728When creating a Jupyter notebook, pandoc will try to infer the notebook
6730Code blocks with the class \f[C]code\f[R] will be taken as code cells,
6731and intervening content will be taken as Markdown cells.
6732Attachments will automatically be created for images in Markdown cells.
6733Metadata will be taken from the \f[C]jupyter\f[R] metadata field.
6744 display_name: Python 2
6751 file_extension: \[dq].py\[dq]
6752 mimetype: \[dq]text/x-python\[dq]
6753 name: \[dq]python\[dq]
6754 nbconvert_exporter: \[dq]python\[dq]
6755 pygments_lexer: \[dq]ipython2\[dq]
6756 version: \[dq]2.7.15\[dq]
6761**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6762bibendum felis dictum sodales.
6765print(\[dq]hello\[dq])
6771from IPython.display import HTML
6774console.log(\[dq]hello\[dq]);
6782This image  will be
6783included as a cell attachment.
6787If you want to add cell attributes, group cells differently, or add
6788output to code cells, then you need to include divs to indicate the
6790You can use either fenced divs or native divs for this.
6795:::::: {.cell .markdown}
6798**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6799bibendum felis dictum sodales.
6802:::::: {.cell .code execution_count=1}
6803\[ga]\[ga]\[ga] {.python}
6804print(\[dq]hello\[dq])
6807::: {.output .stream .stdout}
6814:::::: {.cell .code execution_count=2}
6815\[ga]\[ga]\[ga] {.python}
6816from IPython.display import HTML
6819console.log(\[dq]hello\[dq]);
6825::: {.output .execute_result execution_count=2}
6826\[ga]\[ga]\[ga]{=html}
6828console.log(\[dq]hello\[dq]);
6838If you include raw HTML or TeX in an output cell, use the [raw
6839attribute][Extension: \f[C]fenced_attribute\f[R]], as shown in the last
6840cell of the example above.
6841Although pandoc can process \[dq]bare\[dq] raw HTML and TeX, the result
6842is often interspersed raw elements and normal textual elements, and in
6843an output cell pandoc expects a single, connected raw block.
6844To avoid using raw HTML or TeX except when marked explicitly using raw
6845attributes, we recommend specifying the extensions
6846\f[C]-raw_html-raw_tex+raw_attribute\f[R] when translating between
6847Markdown and ipynb notebooks.
6849Note that options and extensions that affect reading and writing of
6850Markdown will also affect Markdown cells in ipynb notebooks.
6851For example, \f[C]--wrap=preserve\f[R] will preserve soft line breaks in
6852Markdown cells; \f[C]--atx-headers\f[R] will cause ATX-style headings to
6853be used; and \f[C]--preserve-tabs\f[R] will prevent tabs from being
6855.SH SYNTAX HIGHLIGHTING
6857Pandoc will automatically highlight syntax in fenced code blocks that
6858are marked with a language name.
6859The Haskell library skylighting is used for highlighting.
6860Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and
6862To see a list of language names that pandoc will recognize, type
6863\f[C]pandoc --list-highlight-languages\f[R].
6865The color scheme can be selected using the \f[C]--highlight-style\f[R]
6867The default color scheme is \f[C]pygments\f[R], which imitates the
6868default color scheme used by the Python library pygments (though
6869pygments is not actually used to do the highlighting).
6870To see a list of highlight styles, type
6871\f[C]pandoc --list-highlight-styles\f[R].
6873If you are not satisfied with the predefined styles, you can use
6874\f[C]--print-highlight-style\f[R] to generate a JSON \f[C].theme\f[R]
6875file which can be modified and used as the argument to
6876\f[C]--highlight-style\f[R].
6877To get a JSON version of the \f[C]pygments\f[R] style, for example:
6881pandoc --print-highlight-style pygments > my.theme
6885Then edit \f[C]my.theme\f[R] and use it like this:
6889pandoc --highlight-style my.theme
6893If you are not satisfied with the built-in highlighting, or you want
6894highlight a language that isn\[aq]t supported, you can use the
6895\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax
6897Before writing your own, have a look at KDE\[aq]s repository of syntax
6900To disable highlighting, use the \f[C]--no-highlight\f[R] option.
6903Custom styles can be used in the docx and ICML formats.
6906By default, pandoc\[aq]s docx and ICML output applies a predefined set
6907of styles for blocks such as paragraphs and block quotes, and uses
6908largely default formatting (italics, bold) for inlines.
6909This will work for most purposes, especially alongside a
6910\f[C]reference.docx\f[R] file.
6911However, if you need to apply your own styles to blocks, or match a
6912preexisting set of styles, pandoc allows you to define custom styles for
6913blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.
6915If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute
6916\f[C]custom-style\f[R], pandoc will apply your specified style to the
6917contained elements (with the exception of elements whose function
6918depends on a style, like headings, code blocks, block quotes, or links).
6919So, for example, using the \f[C]bracketed_spans\f[R] syntax,
6923[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
6927would produce a docx file with \[dq]Get out\[dq] styled with character
6928style \f[C]Emphatically\f[R].
6929Similarly, using the \f[C]fenced_divs\f[R] syntax,
6933Dickinson starts the poem simply:
6935::: {custom-style=\[dq]Poetry\[dq]}
6936| A Bird came down the Walk---
6937| He did not know I saw---
6942would style the two contained lines with the \f[C]Poetry\f[R] paragraph
6945For docx output, styles will be defined in the output file as inheriting
6946from normal text, if the styles are not yet in your reference.docx.
6947If they are already defined, pandoc will not alter the definition.
6949This feature allows for greatest customization in conjunction with
6951If you want all paragraphs after block quotes to be indented, you can
6952write a filter to apply the styles necessary.
6953If you want all italics to be transformed to the \f[C]Emphasis\f[R]
6954character style (perhaps to change their color), you can write a filter
6955which will transform all italicized inlines to inlines within an
6956\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
6958For docx output, you don\[aq]t need to enable any extensions for custom
6962The docx reader, by default, only reads those styles that it can convert
6963into pandoc elements, either by direct conversion or interpreting the
6964derivation of the input document\[aq]s styles.
6966By enabling the \f[C]styles\f[R] extension in the docx reader
6967(\f[C]-f docx+styles\f[R]), you can produce output that maintains the
6968styles of the input document, using the \f[C]custom-style\f[R] class.
6969Paragraph styles are interpreted as divs, while character styles are
6970interpreted as spans.
6972For example, using the \f[C]custom-style-reference.docx\f[R] file in the
6973test directory, we have the following different outputs:
6975Without the \f[C]+styles\f[R] extension:
6979$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
6982This is text with an *emphasized* text style. And this is text with a
6983**strengthened** text style.
6985> Here is a styled paragraph that inherits from Block Text.
6989And with the extension:
6993$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
6995::: {custom-style=\[dq]First Paragraph\[dq]}
6999::: {custom-style=\[dq]Body Text\[dq]}
7000This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style.
7001And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]}
7005::: {custom-style=\[dq]My Block Style\[dq]}
7006> Here is a styled paragraph that inherits from Block Text.
7011With these custom styles, you can use your input document as a
7012reference-doc while creating docx output (see below), and maintain the
7013same styles in your input and output files.
7016Pandoc can be extended with custom writers written in lua.
7017(Pandoc includes a lua interpreter, so lua need not be installed
7020To use a custom writer, simply specify the path to the lua script in
7021place of the output format.
7026pandoc -t data/sample.lua
7030Creating a custom writer requires writing a lua function for each
7031possible element in a pandoc document.
7032To get a documented example which you can modify according to your
7037pandoc --print-default-data-file sample.lua
7041Note that custom writers have no default template.
7042If you want to use \f[C]--standalone\f[R] with a custom writer, you will
7043need to specify a template manually using \f[C]--template\f[R] or add a
7044new default template with the name
7045\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
7046subdirectory of your user data directory (see Templates).
7047.SH A NOTE ON SECURITY
7049If you use pandoc to convert user-contributed content in a web
7050application, here are some things to keep in mind:
7052Although pandoc itself will not create or modify any files other than
7053those you explicitly ask it create (with the exception of temporary
7054files used in producing PDFs), a filter or custom writer could in
7055principle do anything on your file system.
7056Please audit filters and custom writers very carefully before using
7059If your application uses pandoc as a Haskell library (rather than
7060shelling out to the executable), it is possible to use it in a mode that
7061fully isolates pandoc from your file system, by running the pandoc
7062operations in the \f[C]PandocPure\f[R] monad.
7063See the document Using the pandoc API for more details.
7065Pandoc\[aq]s parsers can exhibit pathological performance on some corner
7067It is wise to put any pandoc operations under a timeout, to avoid DOS
7068attacks that exploit these issues.
7069If you are using the pandoc executable, you can add the command line
7070options \f[C]+RTS -M512M -RTS\f[R] (for example) to limit the heap size
7073The HTML generated by pandoc is not guaranteed to be safe.
7074If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
7075inject arbitrary HTML.
7076Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
7077content in attributes for headings, spans, and code blocks.
7078To be safe, you should run all the generated HTML through an HTML
7082Copyright 2006--2019 John MacFarlane (jgm\[at]berkeley.edu).
7083Released under the GPL, version 2 or greater.
7084This software carries no warranty of any kind.
7085(See COPYRIGHT for full copyright and warranty notices.) For a full list
7086of contributors, see the file AUTHORS.md in the pandoc source code.
7088The Pandoc source code and all documentation may be downloaded
7089from <http://pandoc.org>.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list