2.\" Automatically generated by Pandoc 2.9.1
4.TH "Pandoc User\[aq]s Guide" "" "January 5, 2020" "pandoc 2.9.1.1" ""
7pandoc - general markup converter
10\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]...
13Pandoc is a Haskell library for converting from one markup format to
14another, and a command-line tool that uses this library.
16Pandoc can convert between numerous markup and word processing formats,
17including, but not limited to, various flavors of Markdown, HTML, LaTeX
19For the full lists of input and output formats, see the \f[C]--from\f[R]
20and \f[C]--to\f[R] options below.
21Pandoc can also produce PDF output: see creating a PDF, below.
23Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
24definition lists, metadata blocks, footnotes, citations, math, and much
26See below under Pandoc\[aq]s Markdown.
28Pandoc has a modular design: it consists of a set of readers, which
29parse text in a given format and produce a native representation of the
30document (an \f[I]abstract syntax tree\f[R] or AST), and a set of
31writers, which convert this native representation into a target format.
32Thus, adding an input or output format requires only adding a reader or
34Users can also run custom pandoc filters to modify the intermediate AST.
36Because pandoc\[aq]s intermediate representation of a document is less
37expressive than many of the formats it converts between, one should not
38expect perfect conversions between every format and every other.
39Pandoc attempts to preserve the structural elements of a document, but
40not formatting details such as margin size.
41And some document elements, such as complex tables, may not fit into
42pandoc\[aq]s simple document model.
43While conversions from pandoc\[aq]s Markdown to all formats aspire to be
44perfect, conversions from formats more expressive than pandoc\[aq]s
45Markdown can be expected to be lossy.
48If no \f[I]input-files\f[R] are specified, input is read from
50Output goes to \f[I]stdout\f[R] by default.
51For output to a file, use the \f[C]-o\f[R] option:
55pandoc -o output.html input.txt
59By default, pandoc produces a document fragment.
60To produce a standalone document (e.g.
61a valid HTML file including \f[C]<head>\f[R] and \f[C]<body>\f[R]), use
62the \f[C]-s\f[R] or \f[C]--standalone\f[R] flag:
66pandoc -s -o output.html input.txt
70For more information on how standalone documents are produced, see
73If multiple input files are given, \f[C]pandoc\f[R] will concatenate
74them all (with blank lines between them) before parsing.
75(Use \f[C]--file-scope\f[R] to parse files individually.)
78The format of the input and output can be specified explicitly using
80The input format can be specified using the \f[C]-f/--from\f[R] option,
81the output format using the \f[C]-t/--to\f[R] option.
82Thus, to convert \f[C]hello.txt\f[R] from Markdown to LaTeX, you could
87pandoc -f markdown -t latex hello.txt
91To convert \f[C]hello.html\f[R] from HTML to Markdown:
95pandoc -f html -t markdown hello.html
99Supported input and output formats are listed below under Options (see
100\f[C]-f\f[R] for input formats and \f[C]-t\f[R] for output formats).
101You can also use \f[C]pandoc --list-input-formats\f[R] and
102\f[C]pandoc --list-output-formats\f[R] to print lists of supported
105If the input or output format is not specified explicitly,
106\f[C]pandoc\f[R] will attempt to guess it from the extensions of the
112pandoc -o hello.tex hello.txt
116will convert \f[C]hello.txt\f[R] from Markdown to LaTeX.
117If no output file is specified (so that output goes to
118\f[I]stdout\f[R]), or if the output file\[aq]s extension is unknown, the
119output format will default to HTML.
120If no input file is specified (so that input comes from
121\f[I]stdin\f[R]), or if the input files\[aq] extensions are unknown, the
122input format will be assumed to be Markdown.
123.SS Character encoding
125Pandoc uses the UTF-8 character encoding for both input and output.
126If your local character encoding is not UTF-8, you should pipe input and
127output through \f[C]iconv\f[R]:
131iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
135Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
136OPML, DocBook, and Texinfo), information about the character encoding is
137included in the document header, which will only be included if you use
138the \f[C]-s/--standalone\f[R] option.
141To produce a PDF, specify an output file with a \f[C].pdf\f[R]
146pandoc test.txt -o test.pdf
150By default, pandoc will use LaTeX to create the PDF, which requires that
151a LaTeX engine be installed (see \f[C]--pdf-engine\f[R] below).
152Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an
154To do this, specify an output file with a \f[C].pdf\f[R] extension, as
155before, but add the \f[C]--pdf-engine\f[R] option or
156\f[C]-t context\f[R], \f[C]-t html\f[R], or \f[C]-t ms\f[R] to the
158The tool used to generate the PDF from the intermediate format may be
159specified using \f[C]--pdf-engine\f[R].
161You can control the PDF style using variables, depending on the
162intermediate format used: see variables for LaTeX, variables for
163ConTeXt, variables for \f[C]wkhtmltopdf\f[R], variables for ms.
164When HTML is used as an intermediate format, the output can be styled
165using \f[C]--css\f[R].
167To debug the PDF creation, it can be useful to look at the intermediate
168representation: instead of \f[C]-o test.pdf\f[R], use for example
169\f[C]-s -o test.tex\f[R] to output the generated LaTeX.
170You can then test it with \f[C]pdflatex test.tex\f[R].
172When using LaTeX, the following packages need to be available (they are
173included with all recent versions of TeX Live): \f[C]amsfonts\f[R],
174\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],
175\f[C]ifxetex\f[R], \f[C]ifluatex\f[R], \f[C]listings\f[R] (if the
176\f[C]--listings\f[R] option is used), \f[C]fancyvrb\f[R],
177\f[C]longtable\f[R], \f[C]booktabs\f[R], \f[C]graphicx\f[R] (if the
178document contains images), \f[C]hyperref\f[R], \f[C]xcolor\f[R],
179\f[C]ulem\f[R], \f[C]geometry\f[R] (with the \f[C]geometry\f[R] variable
180set), \f[C]setspace\f[R] (with \f[C]linestretch\f[R]), and
181\f[C]babel\f[R] (with \f[C]lang\f[R]).
182The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
183requires \f[C]fontspec\f[R].
184\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),
185\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
187If the \f[C]mathspec\f[R] variable is set, \f[C]xelatex\f[R] will use
188\f[C]mathspec\f[R] instead of \f[C]unicode-math\f[R].
189The \f[C]upquote\f[R] and \f[C]microtype\f[R] packages are used if
190available, and \f[C]csquotes\f[R] will be used for typography if the
191\f[C]csquotes\f[R] variable or metadata field is set to a true value.
192The \f[C]natbib\f[R], \f[C]biblatex\f[R], \f[C]bibtex\f[R], and
193\f[C]biber\f[R] packages can optionally be used for citation rendering.
194The following packages will be used to improve output quality if
195present, but pandoc does not require them to be present:
196\f[C]upquote\f[R] (for straight quotes in verbatim environments),
197\f[C]microtype\f[R] (for better spacing adjustments), \f[C]parskip\f[R]
198(for better inter-paragraph spaces), \f[C]xurl\f[R] (for better line
199breaks in URLs), \f[C]bookmark\f[R] (for better PDF bookmarks), and
200\f[C]footnotehyper\f[R] or \f[C]footnote\f[R] (to allow footnotes in
202.SS Reading from the Web
204Instead of an input file, an absolute URI may be given.
205In this case pandoc will fetch the content using HTTP:
209pandoc -f html -t markdown http://www.fsf.org
213It is possible to supply a custom User-Agent string or other header when
214requesting a document from a URL:
218pandoc -f html -t markdown --request-header User-Agent:\[dq]Mozilla/5.0\[dq] \[rs]
225\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]
227\f[I]FORMAT\f[R] can be:
230\f[C]commonmark\f[R] (CommonMark Markdown)
232\f[C]creole\f[R] (Creole 1.0)
234\f[C]docbook\f[R] (DocBook)
236\f[C]docx\f[R] (Word docx)
238\f[C]dokuwiki\f[R] (DokuWiki markup)
242\f[C]fb2\f[R] (FictionBook2 e-book)
244\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
245accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
246if you need extensions not supported in \f[C]gfm\f[R].
248\f[C]haddock\f[R] (Haddock markup)
252\f[C]ipynb\f[R] (Jupyter notebook)
254\f[C]jats\f[R] (JATS XML)
256\f[C]jira\f[R] (Jira wiki markup)
258\f[C]json\f[R] (JSON version of native AST)
260\f[C]latex\f[R] (LaTeX)
262\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
264\f[C]markdown_mmd\f[R] (MultiMarkdown)
266\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
268\f[C]markdown_strict\f[R] (original unextended Markdown)
270\f[C]mediawiki\f[R] (MediaWiki markup)
272\f[C]man\f[R] (roff man)
276\f[C]native\f[R] (native Haskell)
282\f[C]org\f[R] (Emacs Org mode)
284\f[C]rst\f[R] (reStructuredText)
286\f[C]t2t\f[R] (txt2tags)
288\f[C]textile\f[R] (Textile)
290\f[C]tikiwiki\f[R] (TikiWiki markup)
292\f[C]twiki\f[R] (TWiki markup)
294\f[C]vimwiki\f[R] (Vimwiki)
296Extensions can be individually enabled or disabled by appending
297\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
298See Extensions below, for a list of extensions and their names.
299See \f[C]--list-input-formats\f[R] and \f[C]--list-extensions\f[R],
303\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]
304Specify output format.
305\f[I]FORMAT\f[R] can be:
308\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor)
310\f[C]beamer\f[R] (LaTeX beamer slide show)
312\f[C]commonmark\f[R] (CommonMark Markdown)
314\f[C]context\f[R] (ConTeXt)
316\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)
318\f[C]docbook5\f[R] (DocBook 5)
320\f[C]docx\f[R] (Word docx)
322\f[C]dokuwiki\f[R] (DokuWiki markup)
324\f[C]epub\f[R] or \f[C]epub3\f[R] (EPUB v3 book)
326\f[C]epub2\f[R] (EPUB v2)
328\f[C]fb2\f[R] (FictionBook2 e-book)
330\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
331accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
332if you need extensions not supported in \f[C]gfm\f[R].
334\f[C]haddock\f[R] (Haddock markup)
336\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.
337HTML5/XHTML polyglot markup)
339\f[C]html4\f[R] (XHTML 1.0 Transitional)
341\f[C]icml\f[R] (InDesign ICML)
343\f[C]ipynb\f[R] (Jupyter notebook)
345\f[C]jats\f[R] (JATS XML)
347\f[C]jira\f[R] (Jira wiki markup)
349\f[C]json\f[R] (JSON version of native AST)
351\f[C]latex\f[R] (LaTeX)
353\f[C]man\f[R] (roff man)
355\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
357\f[C]markdown_mmd\f[R] (MultiMarkdown)
359\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
361\f[C]markdown_strict\f[R] (original unextended Markdown)
363\f[C]mediawiki\f[R] (MediaWiki markup)
365\f[C]ms\f[R] (roff ms)
367\f[C]muse\f[R] (Muse),
369\f[C]native\f[R] (native Haskell),
371\f[C]odt\f[R] (OpenOffice text document)
375\f[C]opendocument\f[R] (OpenDocument)
377\f[C]org\f[R] (Emacs Org mode)
381\f[C]plain\f[R] (plain text),
383\f[C]pptx\f[R] (PowerPoint slide show)
385\f[C]rst\f[R] (reStructuredText)
387\f[C]rtf\f[R] (Rich Text Format)
389\f[C]texinfo\f[R] (GNU Texinfo)
391\f[C]textile\f[R] (Textile)
393\f[C]slideous\f[R] (Slideous HTML and JavaScript slide show)
395\f[C]slidy\f[R] (Slidy HTML and JavaScript slide show)
397\f[C]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show),
399\f[C]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)
401\f[C]s5\f[R] (S5 HTML and JavaScript slide show)
403\f[C]tei\f[R] (TEI Simple)
405\f[C]xwiki\f[R] (XWiki markup)
407\f[C]zimwiki\f[R] (ZimWiki markup)
409the path of a custom lua writer, see Custom writers below
411Note that \f[C]odt\f[R], \f[C]docx\f[R], \f[C]epub\f[R], and
412\f[C]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless
413forced with \f[C]-o -\f[R].
415Extensions can be individually enabled or disabled by appending
416\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
417See Extensions below, for a list of extensions and their names.
418See \f[C]--list-output-formats\f[R] and \f[C]--list-extensions\f[R],
422\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]
423Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].
424If \f[I]FILE\f[R] is \f[C]-\f[R], output will go to \f[I]stdout\f[R],
425even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],
426\f[C]epub2\f[R], \f[C]epub3\f[R]) is specified.
428\f[B]\f[CB]--data-dir=\f[B]\f[R]\f[I]DIRECTORY\f[R]
429Specify the user data directory to search for pandoc data files.
430If this option is not specified, the default user data directory will be
432On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
433of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
434overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
436If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
437(for backwards compatibility).
438In Windows the default user data directory is
439\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
440You can find the default user data directory on your system by looking
441at the output of \f[C]pandoc --version\f[R].
442A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
443\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
444\f[C]s5\f[R] directory placed in this directory will override
445pandoc\[aq]s normal defaults.
447\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]
448Specify a set of default option settings.
449\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line
451All options for document conversion, including input and output files,
452can be set using a defaults file.
453The file will be searched for first in the working directory, and then
454in the \f[C]defaults\f[R] subdirectory of the user data directory (see
455\f[C]--data-dir\f[R]).
456The \f[C].yaml\f[R] extension may be omitted.
457See the section Default files for more information on the file format.
458Settings from the defaults file may be overridden or extended by
459subsequent options on the command line.
461\f[B]\f[CB]--bash-completion\f[B]\f[R]
462Generate a bash completion script.
463To enable bash completion with pandoc, add this to your
469eval \[dq]$(pandoc --bash-completion)\[dq]
474\f[B]\f[CB]--verbose\f[B]\f[R]
475Give verbose debugging output.
476Currently this only has an effect with PDF output.
478\f[B]\f[CB]--quiet\f[B]\f[R]
479Suppress warning messages.
481\f[B]\f[CB]--fail-if-warnings\f[B]\f[R]
482Exit with error status if there are any warnings.
484\f[B]\f[CB]--log=\f[B]\f[R]\f[I]FILE\f[R]
485Write log messages in machine-readable JSON format to \f[I]FILE\f[R].
486All messages above DEBUG level will be written, regardless of verbosity
487settings (\f[C]--verbose\f[R], \f[C]--quiet\f[R]).
489\f[B]\f[CB]--list-input-formats\f[B]\f[R]
490List supported input formats, one per line.
492\f[B]\f[CB]--list-output-formats\f[B]\f[R]
493List supported output formats, one per line.
495\f[B]\f[CB]--list-extensions\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]FORMAT\f[R]]
496List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
497by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by
498default in \f[I]FORMAT\f[R].
499If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[aq]s Markdown
502\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]
503List supported languages for syntax highlighting, one per line.
505\f[B]\f[CB]--list-highlight-styles\f[B]\f[R]
506List supported styles for syntax highlighting, one per line.
507See \f[C]--highlight-style\f[R].
509\f[B]\f[CB]-v\f[B]\f[R], \f[B]\f[CB]--version\f[B]\f[R]
512\f[B]\f[CB]-h\f[B]\f[R], \f[B]\f[CB]--help\f[B]\f[R]
516\f[B]\f[CB]--shift-heading-level-by=\f[B]\f[R]\f[I]NUMBER\f[R]
517Shift heading levels by a positive or negative integer.
518For example, with \f[C]--shift-heading-level-by=-1\f[R], level 2
519headings become level 1 headings, and level 3 headings become level 2
521Headings cannot have a level less than 1, so a heading that would be
522shifted below level 1 becomes a regular paragraph.
523Exception: with a shift of -N, a level-N heading at the beginning of the
524document replaces the metadata title.
525\f[C]--shift-heading-level-by=-1\f[R] is a good choice when converting
526HTML or Markdown documents that use an initial level-1 heading for the
527document title and level-2+ headings for sections.
528\f[C]--shift-heading-level-by=1\f[R] may be a good choice for converting
529Markdown documents that use level-1 headings for sections to HTML, since
530pandoc uses a level-1 heading to render the document title.
532\f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R]
533\f[I]Deprecated. Use \f[CI]--shift-heading-level-by\f[I]=X instead,
534where X = NUMBER - 1.\f[R] Specify the base level for headings (defaults
537\f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R]
538\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension
539instead.\f[R] Ignore paragraphs with no content.
540This option is useful for converting word processing documents where
541users have used empty paragraphs to create inter-paragraph space.
543\f[B]\f[CB]--indented-code-classes=\f[B]\f[R]\f[I]CLASSES\f[R]
544Specify classes to use for indented code blocks--for example,
545\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].
546Multiple classes may be separated by spaces or commas.
548\f[B]\f[CB]--default-image-extension=\f[B]\f[R]\f[I]EXTENSION\f[R]
549Specify a default extension to use when image paths/URLs have no
551This allows you to use the same source for formats that require
552different kinds of images.
553Currently this option only affects the Markdown and LaTeX readers.
555\f[B]\f[CB]--file-scope\f[B]\f[R]
556Parse each file individually before combining for multifile documents.
557This will allow footnotes in different files with the same identifiers
559If this option is set, footnotes and links will not work across files.
560Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].
562\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]
563Specify an executable to be used as a filter transforming the pandoc AST
564after the input is parsed and before the output is written.
565The executable should read JSON from stdin and write JSON to stdout.
566The JSON must be formatted like pandoc\[aq]s own JSON input and output.
567The name of the output format will be passed to the filter as the first
574pandoc --filter ./caps.py -t latex
582pandoc -t json | ./caps.py latex | pandoc -f json -t latex
586The latter form may be useful for debugging filters.
588Filters may be written in any language.
589\f[C]Text.Pandoc.JSON\f[R] exports \f[C]toJSONFilter\f[R] to facilitate
590writing filters in Haskell.
591Those who would prefer to write filters in python can use the module
592\f[C]pandocfilters\f[R], installable from PyPI.
593There are also pandoc filter libraries in PHP, perl, and
596In order of preference, pandoc will look for filters in
598a specified full or relative path (executable or non-executable)
600\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
601\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
604\f[C]$PATH\f[R] (executable only)
606Filters and lua-filters are applied in the order specified on the
610\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]
611Transform the document in a similar fashion as JSON filters (see
612\f[C]--filter\f[R]), but use pandoc\[aq]s build-in lua filtering system.
613The given lua script is expected to return a list of lua filters which
614will be applied in order.
615Each lua filter must contain element-transforming functions indexed by
616the name of the AST element on which the filter function should be
620The \f[C]pandoc\f[R] lua module provides helper functions for element
622It is always loaded into the script\[aq]s lua environment.
624The following is an example lua script for macro-expansion:
628function expand_hello_world(inline)
629 if inline.c == \[aq]{{helloworld}}\[aq] then
630 return pandoc.Emph{ pandoc.Str \[dq]Hello, World\[dq] }
636return {{Str = expand_hello_world}}
640In order of preference, pandoc will look for lua filters in
642a specified full or relative path (executable or non-executable)
644\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
645\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
649\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]]
650Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].
651A value specified on the command line overrides a value specified in the
652document using YAML metadata blocks.
653Values will be parsed as YAML boolean or string values.
654If no value is specified, the value will be treated as Boolean true.
655Like \f[C]--variable\f[R], \f[C]--metadata\f[R] causes template
657But unlike \f[C]--variable\f[R], \f[C]--metadata\f[R] affects the
658metadata of the underlying document (which is accessible from filters
659and may be printed in some output formats) and metadata values will be
660escaped when inserted into the template.
662\f[B]\f[CB]--metadata-file=\f[B]\f[R]\f[I]FILE\f[R]
663Read metadata from the supplied YAML (or JSON) file.
664This option can be used with every input format, but string scalars in
665the YAML file will always be parsed as Markdown.
666Generally, the input will be handled the same as in YAML metadata
668This option can be used repeatedly to include multiple metadata files;
669values in files specified later on the command line will be preferred
670over those specified in earlier files.
671Metadata values specified inside the document, or by using \f[C]-M\f[R],
672overwrite values specified with this option.
674\f[B]\f[CB]-p\f[B]\f[R], \f[B]\f[CB]--preserve-tabs\f[B]\f[R]
675Preserve tabs instead of converting them to spaces.
676(By default, pandoc converts tabs to spaces before parsing its input.)
677Note that this will only affect tabs in literal code spans and code
679Tabs in regular text are always treated as spaces.
681\f[B]\f[CB]--tab-stop=\f[B]\f[R]\f[I]NUMBER\f[R]
682Specify the number of spaces per tab (default is 4).
684\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]
685Specifies what to do with insertions, deletions, and comments produced
686by the MS Word \[dq]Track Changes\[dq] feature.
687\f[C]accept\f[R] (the default), inserts all insertions, and ignores all
689\f[C]reject\f[R] inserts all deletions and ignores insertions.
690Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.
691\f[C]all\f[R] puts in insertions, deletions, and comments, wrapped in
692spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
693\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,
695The author and time of change is included.
696\f[C]all\f[R] is useful for scripting: only accepting changes from a
697certain reviewer, say, or before a certain date.
698If a paragraph is inserted or deleted, \f[C]track-changes=all\f[R]
699produces a span with the class
700\f[C]paragraph-insertion\f[R]/\f[C]paragraph-deletion\f[R] before the
701affected paragraph break.
702This option only affects the docx reader.
704\f[B]\f[CB]--extract-media=\f[B]\f[R]\f[I]DIR\f[R]
705Extract images and other media contained in or linked from the source
706document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
707the images references in the document so they point to the extracted
709If the source format is a binary container (docx, epub, or odt), the
710media is extracted from the container and the original filenames are
712Otherwise the media is read from the file system or downloaded, and new
713filenames are constructed based on SHA1 hashes of the contents.
715\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
716Specifies a custom abbreviations file, with abbreviations one to a line.
717If this option is not specified, pandoc will read the data file
718\f[C]abbreviations\f[R] from the user data directory or fall back on a
720To see the system default, use
721\f[C]pandoc --print-default-data-file=abbreviations\f[R].
722The only use pandoc makes of this list is in the Markdown reader.
723Strings ending in a period that are found in this list will be followed
724by a nonbreaking space, so that the period will not produce
725sentence-ending space in formats like LaTeX.
726.SS General writer options
728\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]
729Produce output with an appropriate header and footer (e.g.
730a standalone HTML, LaTeX, TEI, or RTF file, not a fragment).
731This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],
732\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]
734For \f[C]native\f[R] output, this option causes metadata to be included;
735otherwise, metadata is suppressed.
737\f[B]\f[CB]--template=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
738Use the specified file as a custom template for the generated document.
739Implies \f[C]--standalone\f[R].
740See Templates, below, for a description of template syntax.
741If no extension is specified, an extension corresponding to the writer
742will be added, so that \f[C]--template=special\f[R] looks for
743\f[C]special.html\f[R] for HTML output.
744If the template is not found, pandoc will search for it in the
745\f[C]templates\f[R] subdirectory of the user data directory (see
746\f[C]--data-dir\f[R]).
747If this option is not used, a default template appropriate for the
748output format will be used (see \f[C]-D/--print-default-template\f[R]).
750\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]]
751Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when
752rendering the document in standalone mode.
753If no \f[I]VAL\f[R] is specified, the key will be given the value
756\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]
757Print the system default template for an output \f[I]FORMAT\f[R].
758(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates
759in the user data directory are ignored.
760This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
761output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
762\f[C]--print-default-template\f[R] on the command line.
765Note that some of the default templates use partials, for example
766\f[C]styles.html\f[R].
767To print the partials, use \f[C]--print-default-data-file\f[R]: for
768example, \f[C]--print-default-data-file=templates/styles.html\f[R].
771\f[B]\f[CB]--print-default-data-file=\f[B]\f[R]\f[I]FILE\f[R]
772Print a system default data file.
773Files in the user data directory are ignored.
774This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
775output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
776\f[C]--print-default-data-file\f[R] on the command line.
778\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]
779Manually specify line endings: \f[C]crlf\f[R] (Windows), \f[C]lf\f[R]
780(macOS/Linux/UNIX), or \f[C]native\f[R] (line endings appropriate to the
781OS on which pandoc is being run).
782The default is \f[C]native\f[R].
784\f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R]
785Specify the default dpi (dots per inch) value for conversion from pixels
786to inch/centimeters and vice versa.
787(Technically, the correct term would be ppi: pixels per inch.) The
789When images contain information about dpi internally, the encoded value
790is used instead of the default specified by this option.
792\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]
793Determine how text is wrapped in the output (the source code, not the
795With \f[C]auto\f[R] (the default), pandoc will attempt to wrap lines to
796the column width specified by \f[C]--columns\f[R] (default 72).
797With \f[C]none\f[R], pandoc will not wrap lines at all.
798With \f[C]preserve\f[R], pandoc will attempt to preserve the wrapping
799from the source document (that is, where there are nonsemantic newlines
800in the source, there will be nonsemantic newlines in the output as
802Automatic wrapping does not currently work in HTML output.
803In \f[C]ipynb\f[R] output, this option affects wrapping of the contents
806\f[B]\f[CB]--columns=\f[B]\f[R]\f[I]NUMBER\f[R]
807Specify length of lines in characters.
808This affects text wrapping in the generated source code (see
810It also affects calculation of column widths for plain text tables (see
813\f[B]\f[CB]--toc\f[B]\f[R], \f[B]\f[CB]--table-of-contents\f[B]\f[R]
814Include an automatically generated table of contents (or, in the case of
815\f[C]latex\f[R], \f[C]context\f[R], \f[C]docx\f[R], \f[C]odt\f[R],
816\f[C]opendocument\f[R], \f[C]rst\f[R], or \f[C]ms\f[R], an instruction
817to create one) in the output document.
818This option has no effect unless \f[C]-s/--standalone\f[R] is used, and
819it has no effect on \f[C]man\f[R], \f[C]docbook4\f[R],
820\f[C]docbook5\f[R], or \f[C]jats\f[R] output.
823Note that if you are producing a PDF via \f[C]ms\f[R], the table of
824contents will appear at the beginning of the document, before the title.
825If you would prefer it to be at the end of the document, use the option
826\f[C]--pdf-engine-opt=--no-toc-relocation\f[R].
829\f[B]\f[CB]--toc-depth=\f[B]\f[R]\f[I]NUMBER\f[R]
830Specify the number of section levels to include in the table of
832The default is 3 (which means that level-1, 2, and 3 headings will be
833listed in the contents).
835\f[B]\f[CB]--strip-comments\f[B]\f[R]
836Strip out HTML comments in the Markdown or Textile source, rather than
837passing them on to Markdown, Textile or HTML output as raw HTML.
838This does not apply to HTML comments inside raw HTML blocks when the
839\f[C]markdown_in_html_blocks\f[R] extension is not set.
841\f[B]\f[CB]--no-highlight\f[B]\f[R]
842Disables syntax highlighting for code blocks and inlines, even when a
843language attribute is given.
845\f[B]\f[CB]--highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
846Specifies the coloring style to be used in highlighted source code.
847Options are \f[C]pygments\f[R] (the default), \f[C]kate\f[R],
848\f[C]monochrome\f[R], \f[C]breezeDark\f[R], \f[C]espresso\f[R],
849\f[C]zenburn\f[R], \f[C]haddock\f[R], and \f[C]tango\f[R].
850For more information on syntax highlighting in pandoc, see Syntax
852See also \f[C]--list-highlight-styles\f[R].
855Instead of a \f[I]STYLE\f[R] name, a JSON file with extension
856\f[C].theme\f[R] may be supplied.
857This will be parsed as a KDE syntax highlighting theme and (if valid)
858used as the highlighting style.
860To generate the JSON version of an existing style, use
861\f[C]--print-highlight-style\f[R].
864\f[B]\f[CB]--print-highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
865Prints a JSON version of a highlighting style, which can be modified,
866saved with a \f[C].theme\f[R] extension, and used with
867\f[C]--highlight-style\f[R].
868This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
869output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
870\f[C]--print-highlight-style\f[R] on the command line.
872\f[B]\f[CB]--syntax-definition=\f[B]\f[R]\f[I]FILE\f[R]
873Instructs pandoc to load a KDE XML syntax definition file, which will be
874used for syntax highlighting of appropriately marked code blocks.
875This can be used to add support for new languages or to use altered
876syntax definitions for existing languages.
877This option may be repeated to add multiple syntax definitions.
879\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]
880Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.
881This can be used, for example, to include special CSS or JavaScript in
883This option can be used repeatedly to include multiple files in the
885They will be included in the order specified.
886Implies \f[C]--standalone\f[R].
888\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]
889Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the
891after the \f[C]<body>\f[R] tag in HTML, or the
892\f[C]\[rs]begin{document}\f[R] command in LaTeX).
893This can be used to include navigation bars or banners in HTML
895This option can be used repeatedly to include multiple files.
896They will be included in the order specified.
897Implies \f[C]--standalone\f[R].
899\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]
900Include contents of \f[I]FILE\f[R], verbatim, at the end of the document
901body (before the \f[C]</body>\f[R] tag in HTML, or the
902\f[C]\[rs]end{document}\f[R] command in LaTeX).
903This option can be used repeatedly to include multiple files.
904They will be included in the order specified.
905Implies \f[C]--standalone\f[R].
907\f[B]\f[CB]--resource-path=\f[B]\f[R]\f[I]SEARCHPATH\f[R]
908List of paths to search for images and other resources.
909The paths should be separated by \f[C]:\f[R] on Linux, UNIX, and macOS
910systems, and by \f[C];\f[R] on Windows.
911If \f[C]--resource-path\f[R] is not specified, the default resource path
912is the working directory.
913Note that, if \f[C]--resource-path\f[R] is specified, the working
914directory must be explicitly listed or it will not be searched.
915For example: \f[C]--resource-path=.:test\f[R] will search the working
916directory and the \f[C]test\f[R] subdirectory, in that order.
919\f[C]--resource-path\f[R] only has an effect if (a) the output format
920embeds images (for example, \f[C]docx\f[R], \f[C]pdf\f[R], or
921\f[C]html\f[R] with \f[C]--self-contained\f[R]) or (b) it is used
922together with \f[C]--extract-media\f[R].
925\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]
926Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
927making HTTP requests (for example, when a URL is given on the command
928line, or when resources used in a document must be downloaded).
929If you\[aq]re behind a proxy, you also need to set the environment
930variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].
931.SS Options affecting specific writers
933\f[B]\f[CB]--self-contained\f[B]\f[R]
934Produce a standalone HTML file with no external dependencies, using
935\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,
936stylesheets, images, and videos.
937Implies \f[C]--standalone\f[R].
938The resulting file should be \[dq]self-contained,\[dq] in the sense that
939it needs no external files and no net access to be displayed properly by
941This option works only with HTML output formats, including
942\f[C]html4\f[R], \f[C]html5\f[R], \f[C]html+lhs\f[R],
943\f[C]html5+lhs\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
944\f[C]dzslides\f[R], and \f[C]revealjs\f[R].
945Scripts, images, and stylesheets at absolute URLs will be downloaded;
946those at relative URLs will be sought relative to the working directory
947(if the first source file is local) or relative to the base URL (if the
948first source file is remote).
949Elements with the attribute \f[C]data-external=\[dq]1\[dq]\f[R] will be
950left alone; the documents they link to will not be incorporated in the
952Limitation: resources that are loaded dynamically through JavaScript
953cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not
954work with \f[C]--mathjax\f[R], and some advanced features (e.g.
955zoom or speaker notes) may not work in an offline
956\[dq]self-contained\[dq] \f[C]reveal.js\f[R] slide show.
958\f[B]\f[CB]--html-q-tags\f[B]\f[R]
959Use \f[C]<q>\f[R] tags for quotes in HTML.
961\f[B]\f[CB]--ascii\f[B]\f[R]
962Use only ASCII characters in output.
963Currently supported for XML and HTML formats (which use entities instead
964of UTF-8 when this option is selected), CommonMark, gfm, and Markdown
965(which use entities), roff ms (which use hexadecimal escapes), and to a
966limited degree LaTeX (which uses standard commands for accented
967characters when possible).
968roff man output uses ASCII by default.
970\f[B]\f[CB]--reference-links\f[B]\f[R]
971Use reference-style links, rather than inline links, in writing Markdown
973By default inline links are used.
974The placement of link references is affected by the
975\f[C]--reference-location\f[R] option.
977\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]
978Specify whether footnotes (and references, if \f[C]reference-links\f[R]
979is set) are placed at the end of the current (top-level) block, the
980current section, or the document.
981The default is \f[C]document\f[R].
982Currently only affects the markdown writer.
984\f[B]\f[CB]--atx-headers\f[B]\f[R]
985Use ATX-style headings in Markdown output.
986The default is to use setext-style headings for levels 1 to 2, and then
988(Note: for \f[C]gfm\f[R] output, ATX headings are always used.) This
989option also affects markdown cells in \f[C]ipynb\f[R] output.
991\f[B]\f[CB]--top-level-division=[default|section|chapter|part]\f[B]\f[R]
992Treat top-level headings as the given division type in LaTeX, ConTeXt,
993DocBook, and TEI output.
994The hierarchy order is part, chapter, then section; all headings are
995shifted such that the top-level heading becomes the specified type.
996The default behavior is to determine the best division type via
997heuristics: unless other conditions apply, \f[C]section\f[R] is chosen.
998When the \f[C]documentclass\f[R] variable is set to \f[C]report\f[R],
999\f[C]book\f[R], or \f[C]memoir\f[R] (unless the \f[C]article\f[R] option
1000is specified), \f[C]chapter\f[R] is implied as the setting for this
1002If \f[C]beamer\f[R] is the output format, specifying either
1003\f[C]chapter\f[R] or \f[C]part\f[R] will cause top-level headings to
1004become \f[C]\[rs]part{..}\f[R], while second-level headings remain as
1007\f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]
1008Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
1009By default, sections are not numbered.
1010Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
1011\f[C]--number-sections\f[R] is specified.
1013\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]]
1014Offset for section headings in HTML output (ignored in other output
1016The first number is added to the section number for top-level headings,
1017the second for second-level headings, and so on.
1018So, for example, if you want the first top-level heading in your
1019document to be numbered \[dq]6\[dq], specify
1020\f[C]--number-offset=5\f[R].
1021If your document starts with a level-2 heading which you want to be
1022numbered \[dq]1.5\[dq], specify \f[C]--number-offset=1,4\f[R].
1023Offsets are 0 by default.
1024Implies \f[C]--number-sections\f[R].
1026\f[B]\f[CB]--listings\f[B]\f[R]
1027Use the \f[C]listings\f[R] package for LaTeX code blocks.
1028The package does not support multi-byte encoding for source code.
1029To handle UTF-8 you would need to use a custom template.
1030This issue is fully documented here: Encoding issue with the listings
1033\f[B]\f[CB]-i\f[B]\f[R], \f[B]\f[CB]--incremental\f[B]\f[R]
1034Make list items in slide shows display incrementally (one by one).
1035The default is for lists to be displayed all at once.
1037\f[B]\f[CB]--slide-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1038Specifies that headings with the specified level create slides (for
1039\f[C]beamer\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
1041Headings above this level in the hierarchy are used to divide the slide
1042show into sections; headings below this level create subheads within a
1044Note that content that is not contained under slide-level headings will
1045not appear in the slide show.
1046The default is to set the slide level based on the contents of the
1047document; see Structuring the slide show.
1049\f[B]\f[CB]--section-divs\f[B]\f[R]
1050Wrap sections in \f[C]<section>\f[R] tags (or \f[C]<div>\f[R] tags for
1051\f[C]html4\f[R]), and attach identifiers to the enclosing
1052\f[C]<section>\f[R] (or \f[C]<div>\f[R]) rather than the heading itself.
1053See Heading identifiers, below.
1055\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]
1056Specify a method for obfuscating \f[C]mailto:\f[R] links in HTML
1058\f[C]none\f[R] leaves \f[C]mailto:\f[R] links as they are.
1059\f[C]javascript\f[R] obfuscates them using JavaScript.
1060\f[C]references\f[R] obfuscates them by printing their letters as
1061decimal or hexadecimal character references.
1062The default is \f[C]none\f[R].
1064\f[B]\f[CB]--id-prefix=\f[B]\f[R]\f[I]STRING\f[R]
1065Specify a prefix to be added to all identifiers and internal links in
1066HTML and DocBook output, and to footnote numbers in Markdown and Haddock
1068This is useful for preventing duplicate identifiers when generating
1069fragments to be included in other pages.
1071\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]
1072Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that
1073appears in the HTML header (but not in the title as it appears at the
1074beginning of the HTML body).
1075Implies \f[C]--standalone\f[R].
1077\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]
1078Link to a CSS style sheet.
1079This option can be used repeatedly to include multiple files.
1080They will be included in the order specified.
1083A stylesheet is required for generating EPUB.
1084If none is provided using this option (or the \f[C]css\f[R] or
1085\f[C]stylesheet\f[R] metadata fields), pandoc will look for a file
1086\f[C]epub.css\f[R] in the user data directory (see
1087\f[C]--data-dir\f[R]).
1088If it is not found there, sensible defaults will be used.
1091\f[B]\f[CB]--reference-doc=\f[B]\f[R]\f[I]FILE\f[R]
1092Use the specified file as a style reference in producing a docx or ODT
1097For best results, the reference docx should be a modified version of a
1098docx file produced using pandoc.
1099The contents of the reference docx are ignored, but its stylesheets and
1100document properties (including margins, page size, header, and footer)
1101are used in the new docx.
1102If no reference docx is specified on the command line, pandoc will look
1103for a file \f[C]reference.docx\f[R] in the user data directory (see
1104\f[C]--data-dir\f[R]).
1105If this is not found either, sensible defaults will be used.
1108To produce a custom \f[C]reference.docx\f[R], first get a copy of the
1109default \f[C]reference.docx\f[R]:
1110\f[C]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R].
1111Then open \f[C]custom-reference.docx\f[R] in Word, modify the styles as
1112you wish, and save the file.
1113For best results, do not make changes to this file other than modifying
1114the styles used by pandoc:
1178Default Paragraph Font
1194For best results, the reference ODT should be a modified version of an
1195ODT produced using pandoc.
1196The contents of the reference ODT are ignored, but its stylesheets are
1198If no reference ODT is specified on the command line, pandoc will look
1199for a file \f[C]reference.odt\f[R] in the user data directory (see
1200\f[C]--data-dir\f[R]).
1201If this is not found either, sensible defaults will be used.
1204To produce a custom \f[C]reference.odt\f[R], first get a copy of the
1205default \f[C]reference.odt\f[R]:
1206\f[C]pandoc -o custom-reference.odt --print-default-data-file reference.odt\f[R].
1207Then open \f[C]custom-reference.odt\f[R] in LibreOffice, modify the
1208styles as you wish, and save the file.
1212Templates included with Microsoft PowerPoint 2013 (either with
1213\f[C].pptx\f[R] or \f[C].potx\f[R] extension) are known to work, as are
1214most templates derived from these.
1217The specific requirement is that the template should begin with the
1218following first four layouts:
1228All templates included with a recent version of MS PowerPoint will fit
1230(You can click on \f[C]Layout\f[R] under the \f[C]Home\f[R] menu to
1233You can also modify the default \f[C]reference.pptx\f[R]: first run
1234\f[C]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R],
1235and then modify \f[C]custom-reference.pptx\f[R] in MS PowerPoint (pandoc
1236will use the first four layout slides, as mentioned above).
1240\f[B]\f[CB]--epub-cover-image=\f[B]\f[R]\f[I]FILE\f[R]
1241Use the specified image as the EPUB cover.
1242It is recommended that the image be less than 1000px in width and
1244Note that in a Markdown source document you can also specify
1245\f[C]cover-image\f[R] in a YAML metadata block (see EPUB Metadata,
1248\f[B]\f[CB]--epub-metadata=\f[B]\f[R]\f[I]FILE\f[R]
1249Look in the specified XML file for metadata for the EPUB.
1250The file should contain a series of Dublin Core elements.
1256 <dc:rights>Creative Commons</dc:rights>
1257 <dc:language>es-AR</dc:language>
1261By default, pandoc will include the following metadata elements:
1262\f[C]<dc:title>\f[R] (from the document title), \f[C]<dc:creator>\f[R]
1263(from the document authors), \f[C]<dc:date>\f[R] (from the document
1264date, which should be in ISO 8601 format), \f[C]<dc:language>\f[R] (from
1265the \f[C]lang\f[R] variable, or, if is not set, the locale), and
1266\f[C]<dc:identifier id=\[dq]BookId\[dq]>\f[R] (a randomly generated
1268Any of these may be overridden by elements in the metadata file.
1270Note: if the source document is Markdown, a YAML metadata block in the
1271document can be used instead.
1272See below under EPUB Metadata.
1275\f[B]\f[CB]--epub-embed-font=\f[B]\f[R]\f[I]FILE\f[R]
1276Embed the specified font in the EPUB.
1277This option can be repeated to embed multiple fonts.
1278Wildcards can also be used: for example, \f[C]DejaVuSans-*.ttf\f[R].
1279However, if you use wildcards on the command line, be sure to escape
1280them or put the whole filename in single quotes, to prevent them from
1281being interpreted by the shell.
1282To use the embedded fonts, you will need to add declarations like the
1283following to your CSS (see \f[C]--css\f[R]):
1289font-family: DejaVuSans;
1292src:url(\[dq]DejaVuSans-Regular.ttf\[dq]);
1295font-family: DejaVuSans;
1298src:url(\[dq]DejaVuSans-Bold.ttf\[dq]);
1301font-family: DejaVuSans;
1304src:url(\[dq]DejaVuSans-Oblique.ttf\[dq]);
1307font-family: DejaVuSans;
1310src:url(\[dq]DejaVuSans-BoldOblique.ttf\[dq]);
1312body { font-family: \[dq]DejaVuSans\[dq]; }
1317\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1318Specify the heading level at which to split the EPUB into separate
1319\[dq]chapter\[dq] files.
1320The default is to split into chapters at level-1 headings.
1321This option only affects the internal composition of the EPUB, not the
1322way chapters and sections are displayed to users.
1323Some readers may be slow if the chapter files are too large, so for
1324large documents with few level-1 headings, one might want to use a
1325chapter level of 2 or 3.
1327\f[B]\f[CB]--epub-subdirectory=\f[B]\f[R]\f[I]DIRNAME\f[R]
1328Specify the subdirectory in the OCF container that is to hold the
1329EPUB-specific contents.
1330The default is \f[C]EPUB\f[R].
1331To put the EPUB contents in the top level, use an empty string.
1333\f[B]\f[CB]--ipynb-output=all|none|best\f[B]\f[R]
1334Determines how ipynb output cells are treated.
1335\f[C]all\f[R] means that all of the data formats included in the
1336original are preserved.
1337\f[C]none\f[R] means that the contents of data cells are omitted.
1338\f[C]best\f[R] causes pandoc to try to pick the richest data block in
1339each output cell that is compatible with the output format.
1340The default is \f[C]best\f[R].
1342\f[B]\f[CB]--pdf-engine=\f[B]\f[R]\f[I]PROGRAM\f[R]
1343Use the specified engine when producing PDF output.
1344Valid values are \f[C]pdflatex\f[R], \f[C]lualatex\f[R],
1345\f[C]xelatex\f[R], \f[C]latexmk\f[R], \f[C]tectonic\f[R],
1346\f[C]wkhtmltopdf\f[R], \f[C]weasyprint\f[R], \f[C]prince\f[R],
1347\f[C]context\f[R], and \f[C]pdfroff\f[R].
1348If the engine is not in your PATH, the full path of the engine may be
1350If this option is not specified, pandoc uses the following defaults
1351depending on the output format specified using \f[C]-t/--to\f[R]:
1354\f[C]-t latex\f[R] or none: \f[C]pdflatex\f[R] (other options:
1355\f[C]xelatex\f[R], \f[C]lualatex\f[R], \f[C]tectonic\f[R],
1358\f[C]-t context\f[R]: \f[C]context\f[R]
1360\f[C]-t html\f[R]: \f[C]wkhtmltopdf\f[R] (other options:
1361\f[C]prince\f[R], \f[C]weasyprint\f[R])
1363\f[C]-t ms\f[R]: \f[C]pdfroff\f[R]
1366\f[B]\f[CB]--pdf-engine-opt=\f[B]\f[R]\f[I]STRING\f[R]
1367Use the given string as a command-line argument to the
1368\f[C]pdf-engine\f[R].
1369For example, to use a persistent directory \f[C]foo\f[R] for
1370\f[C]latexmk\f[R]\[aq]s auxiliary files, use
1371\f[C]--pdf-engine-opt=-outdir=foo\f[R].
1372Note that no check for duplicate options is done.
1373.SS Citation rendering
1375\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]
1376Set the \f[C]bibliography\f[R] field in the document\[aq]s metadata to
1377\f[I]FILE\f[R], overriding any value set in the metadata, and process
1378citations using \f[C]pandoc-citeproc\f[R].
1379(This is equivalent to
1380\f[C]--metadata bibliography=FILE --filter pandoc-citeproc\f[R].) If
1381\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] is also supplied,
1382\f[C]pandoc-citeproc\f[R] is not used, making this equivalent to
1383\f[C]--metadata bibliography=FILE\f[R].
1384If you supply this argument multiple times, each \f[I]FILE\f[R] will be
1385added to bibliography.
1387\f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R]
1388Set the \f[C]csl\f[R] field in the document\[aq]s metadata to
1389\f[I]FILE\f[R], overriding any value set in the metadata.
1390(This is equivalent to \f[C]--metadata csl=FILE\f[R].) This option is
1391only relevant with \f[C]pandoc-citeproc\f[R].
1393\f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
1394Set the \f[C]citation-abbreviations\f[R] field in the document\[aq]s
1395metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
1396(This is equivalent to
1397\f[C]--metadata citation-abbreviations=FILE\f[R].) This option is only
1398relevant with \f[C]pandoc-citeproc\f[R].
1400\f[B]\f[CB]--natbib\f[B]\f[R]
1401Use \f[C]natbib\f[R] for citations in LaTeX output.
1402This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1404It is intended for use in producing a LaTeX file that can be processed
1405with \f[C]bibtex\f[R].
1407\f[B]\f[CB]--biblatex\f[B]\f[R]
1408Use \f[C]biblatex\f[R] for citations in LaTeX output.
1409This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1411It is intended for use in producing a LaTeX file that can be processed
1412with \f[C]bibtex\f[R] or \f[C]biber\f[R].
1413.SS Math rendering in HTML
1415The default is to render TeX math as far as possible using Unicode
1417Formulas are put inside a \f[C]span\f[R] with
1418\f[C]class=\[dq]math\[dq]\f[R], so that they may be styled differently
1419from the surrounding text if needed.
1420However, this gives acceptable results only for basic math, usually you
1421will want to use \f[C]--mathjax\f[R] or another of the following
1424\f[B]\f[CB]--mathjax\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1425Use MathJax to display embedded TeX math in HTML output.
1426TeX math will be put between \f[C]\[rs](...\[rs])\f[R] (for inline math)
1427or \f[C]\[rs][...\[rs]]\f[R] (for display math) and wrapped in
1428\f[C]<span>\f[R] tags with class \f[C]math\f[R].
1429Then the MathJax JavaScript will render it.
1430The \f[I]URL\f[R] should point to the \f[C]MathJax.js\f[R] load script.
1431If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be
1434\f[B]\f[CB]--mathml\f[B]\f[R]
1435Convert TeX math to MathML (in \f[C]epub3\f[R], \f[C]docbook4\f[R],
1436\f[C]docbook5\f[R], \f[C]jats\f[R], \f[C]html4\f[R] and
1438This is the default in \f[C]odt\f[R] output.
1439Note that currently only Firefox and Safari (and select e-book readers)
1440natively support MathML.
1442\f[B]\f[CB]--webtex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1443Convert TeX formulas to \f[C]<img>\f[R] tags that link to an external
1444script that converts formulas to images.
1445The formula will be URL-encoded and concatenated with the URL provided.
1446For SVG images you can for example use
1447\f[C]--webtex https://latex.codecogs.com/svg.latex?\f[R].
1448If no URL is specified, the CodeCogs URL generating PNGs will be used
1449(\f[C]https://latex.codecogs.com/png.latex?\f[R]).
1450Note: the \f[C]--webtex\f[R] option will affect Markdown output as well
1451as HTML, which is useful if you\[aq]re targeting a version of Markdown
1452without native math support.
1454\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1455Use KaTeX to display embedded TeX math in HTML output.
1456The \f[I]URL\f[R] is the base URL for the KaTeX library.
1457That directory should contain a \f[C]katex.min.js\f[R] and a
1458\f[C]katex.min.css\f[R] file.
1459If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be
1462\f[B]\f[CB]--gladtex\f[B]\f[R]
1463Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.
1464The resulting HTML can then be processed by GladTeX to produce images of
1465the typeset formulas and an HTML file with links to these images.
1466So, the procedure is:
1471pandoc -s --gladtex input.md -o myfile.htex
1472gladtex -d myfile-images myfile.htex
1473# produces myfile.html and images in myfile-images
1477.SS Options for wrapper scripts
1479\f[B]\f[CB]--dump-args\f[B]\f[R]
1480Print information about command-line arguments to \f[I]stdout\f[R], then
1482This option is intended primarily for use in wrapper scripts.
1483The first line of output contains the name of the output file specified
1484with the \f[C]-o\f[R] option, or \f[C]-\f[R] (for \f[I]stdout\f[R]) if
1485no output file was specified.
1486The remaining lines contain the command-line arguments, one per line, in
1487the order they appear.
1488These do not include regular pandoc options and their arguments, but do
1489include any options appearing after a \f[C]--\f[R] separator at the end
1492\f[B]\f[CB]--ignore-args\f[B]\f[R]
1493Ignore command-line arguments (for use in wrapper scripts).
1494Regular pandoc options are not ignored.
1500pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1508pandoc -o foo.html -s
1514If pandoc completes successfully, it will return exit code 0.
1515Nonzero exit codes have the following meanings:
1529PandocFailOnWarningError
1549PandocUnknownReaderError
1554PandocUnknownWriterError
1559PandocUnsupportedExtensionError
1564PandocEpubSubdirectoryError
1574PandocPDFProgramNotFoundError
1584PandocShouldNeverHappenError
1624PandocUTF8DecodingError
1629PandocIpynbDecodingError
1634PandocCouldNotFindDataFileError
1639PandocResourceNotFound
1644The \f[C]--defaults\f[R] option may be used to specify a package of
1646Here is a sample defaults file demonstrating all of the fields that may
1652# reader: may be used instead of from:
1654# writer: may be used instead of to:
1656# leave blank for output to stdout:
1658# leave blank for input from stdin, use [] for no input:
1662# or you may use input-file: with a single value
1666self-contained: false
1668# note that structured variables may be specified:
1675# metadata values specified here are parsed as literal
1676# string text, not markdown:
1683# or you may use metadata-file: with a single value
1685# Note that these take files, not their contents:
1686include-before-body: []
1687include-after-body: []
1688include-in-header: []
1689resource-path: [\[dq].\[dq]]
1691# filters will be assumed to be lua filters if they have
1692# the .lua extension, and json filters otherwise. But
1693# the filter type can also be specified explicitly, as shown:
1704# ERROR, WARNING, or INFO
1708# citeproc, natbib, or biblatex
1709cite-method: citeproc
1710# part, chapter, section, or default:
1711top-level-division: chapter
1716- \[dq]-shell-escape\[dq]
1717# you may also use pdf-engine-opt: with a single option
1718# pdf-engine-opt: \[dq]-shell-escape\[dq]
1720# auto, preserve, or none
1725extract-media: mediadir
1727table-of-contents: true
1729number-sections: false
1730# a list of offsets at each heading level
1731number-offset: [0,0,0,0,0,0]
1732# toc: may also be used instead of table-of-contents:
1733shift-heading-level-by: 1
1735identifier-prefix: foo
1736title-prefix: \[dq]\[dq]
1737strip-empty-paragraphs: true
1738# lf, crlf, or native
1740strip-comments: false
1741indented-code-classes: []
1743default-image-extension: \[dq].jpg\[dq]
1745# either a style name of a style definition file:
1746highlight-style: pygments
1749# or you may use syntax-definition: with a single value
1752reference-doc: myref.docx
1754# method is plain, webtex, gladtex, mathml, mathjax, katex
1755# you may specify a url with webtex, mathjax, katex
1758 url: \[dq]https://cdn.jsdelivr.net/npm/mathjax\[at]3/es5/tex-mml-chtml.js\[dq]
1759# none, references, or javascript
1760email-obfuscation: javascript
1768epub-subdirectory: EPUB
1769epub-metadata: meta.xml
1772epub-chapter-level: 1
1773epub-cover-image: cover.jpg
1775reference-links: true
1776# block, section, or document
1777reference-location: block
1780# accept, reject, or all
1781track-changes: accept
1790# A list of two-element lists
1792- [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]
1794fail-if-warnings: false
1801Fields that are omitted will just have their regular default values.
1802So a defaults file can be as simple as one line:
1810Default files can be placed in the \f[C]defaults\f[R] subdirectory of
1811the user data directory and used from any directory.
1812For example, one could create a file specifying defaults for writing
1813letters, save it as \f[C]letter.yaml\f[R] in the \f[C]defaults\f[R]
1814subdirectory of the user data directory, and then invoke these defaults
1815from any directory using \f[C]pandoc --defaults letter\f[R] or
1816\f[C]pandoc -dletter\f[R].
1818When multiple defaults are used, their contents will be combined.
1820Note that, where command-line arguments may be repeated
1821(\f[C]--metadata-file\f[R], \f[C]--css\f[R],
1822\f[C]--include-in-header\f[R], \f[C]--include-before-body\f[R],
1823\f[C]--include-after-body\f[R], \f[C]--variable\f[R],
1824\f[C]--metadata\f[R], \f[C]--syntax-definition\f[R]), the values
1825specified on the command line will combine with values specified in the
1826defaults file, rather than replacing them.
1829When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a
1830template to add header and footer material that is needed for a
1831self-standing document.
1832To see the default template that is used, just type
1840where \f[I]FORMAT\f[R] is the name of the output format.
1841A custom template can be specified using the \f[C]--template\f[R]
1843You can also override the system default templates for a given output
1844format \f[I]FORMAT\f[R] by putting a file
1845\f[C]templates/default.*FORMAT*\f[R] in the user data directory (see
1846\f[C]--data-dir\f[R], above).
1847\f[I]Exceptions:\f[R]
1849For \f[C]odt\f[R] output, customize the \f[C]default.opendocument\f[R]
1852For \f[C]pdf\f[R] output, customize the \f[C]default.latex\f[R] template
1853(or the \f[C]default.context\f[R] template, if you use
1854\f[C]-t context\f[R], or the \f[C]default.ms\f[R] template, if you use
1855\f[C]-t ms\f[R], or the \f[C]default.html\f[R] template, if you use
1858\f[C]docx\f[R] and \f[C]pptx\f[R] have no template (however, you can use
1859\f[C]--reference-doc\f[R] to customize the output).
1861Templates contain \f[I]variables\f[R], which allow for the inclusion of
1862arbitrary information at any point in the file.
1863They may be set at the command line using the \f[C]-V/--variable\f[R]
1865If a variable is not set, pandoc will look for the key in the
1866document\[aq]s metadata, which can be set using either YAML metadata
1867blocks or with the \f[C]-M/--metadata\f[R] option.
1868In addition, some variables are given default values by pandoc.
1869See Variables below for a list of variables used in pandoc\[aq]s default
1872If you use custom templates, you may need to revise them as pandoc
1874We recommend tracking the changes in the default templates, and
1875modifying your custom templates accordingly.
1876An easy way to do this is to fork the pandoc-templates repository and
1877merge in changes after each pandoc release.
1881Anything between the sequence \f[C]$--\f[R] and the end of the line will
1882be treated as a comment and omitted from the output.
1885To mark variables and control structures in the template, either
1886\f[C]$\f[R]...\f[C]$\f[R] or \f[C]${\f[R]...\f[C]}\f[R] may be used as
1888The styles may also be mixed in the same template, but the opening and
1889closing delimiter must match in each case.
1890The opening delimiter may be followed by one or more spaces or tabs,
1891which will be ignored.
1892The closing delimiter may be followed by one or more spaces or tabs,
1893which will be ignored.
1895To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].
1896.SS Interpolated variables
1898A slot for an interpolated variable is a variable name surrounded by
1900Variable names must begin with a letter and can contain letters,
1901numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].
1902The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],
1903\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may
1904not be used as variable names.
1920Variable names with periods are used to get at structured variable
1922So, for example, \f[C]employee.salary\f[R] will return the value of the
1923\f[C]salary\f[R] field of the object that is the value of the
1924\f[C]employee\f[R] field.
1926If the value of the variable is simple value, it will be rendered
1928(Note that no escaping is done; the assumption is that the calling
1929program will escape the strings appropriately for the output format.)
1931If the value is a list, the values will be concatenated.
1933If the value is a map, the string \f[C]true\f[R] will be rendered.
1935Every other value will be rendered as the empty string.
1938A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched
1939delimiters) and ends with \f[C]endif\f[R] (enclosed in matched
1941It may optionally contain an \f[C]else\f[R] (enclosed in matched
1943The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty
1944value, otherwise the \f[C]else\f[R] section is used (if present).
1961${if(foo)}bar${endif}
1975The keyword \f[C]elseif\f[R] may be used to simplify complex nested
1991A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched
1992delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched
1995If \f[C]variable\f[R] is an array, the material inside the loop will be
1996evaluated repeatedly, with \f[C]variable\f[R] being set to each value of
1997the array in turn, and concatenated.
1999If \f[C]variable\f[R] is a map, the material inside will be set to the
2002If the value of the associated variable is not an array or a map, a
2003single iteration will be performed on its value.
2009$for(foo)$$foo$$sep$, $endfor$
2012 - $foo.last$, $foo.first$
2016 - ${ foo.bar.last }, ${ foo.bar.first }
2020$it.name$: $it.office$
2025You may optionally specify a separator between consecutive values using
2026\f[C]sep\f[R] (enclosed in matched delimiters).
2027The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the
2032${ for(foo) }${ foo }${ sep }, ${ endfor }
2036Instead of using \f[C]variable\f[R] inside the loop, the special
2037anaphoric keyword \f[C]it\f[R] may be used.
2042 - ${ it.last }, ${ it.first }
2048Partials (subtemplates stored in different files) may be included using
2057Partials will be sought in the directory containing the main template,
2058and will be assumed to have the same extension as the main template if
2059they lack an explicit extension.
2060(If the partials are not found here, they will also be sought in the
2061\f[C]templates\f[R] subdirectory of the user data directory.)
2063Partials may optionally be applied to variables using a colon:
2069${ articles:bibentry() }
2073If \f[C]articles\f[R] is an array, this will iterate over its values,
2074applying the partial \f[C]bibentry()\f[R] to each one.
2075So the second example above is equivalent to
2085Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating
2087In the above examples, the \f[C]bibentry\f[R] partial should contain
2088\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].
2090Final newlines are omitted from included partials.
2092Partials may include other partials.
2094A separator between values of an array may be specified in square
2095brackets, immediately after the variable name or partial:
2101${articles:bibentry()[; ]$
2105The separator in this case is literal and (unlike with \f[C]sep\f[R] in
2106an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or
2107other template directives.
2110To ensure that content is \[dq]nested,\[dq] that is, subsequent lines
2111indented, use the \f[C]\[ha]\f[R] directive:
2115$item.number$ $\[ha]$$item.description$ ($item.price$)
2119In this example, if \f[C]item.description\f[R] has multiple lines, they
2120will all be indented to line up with the first line:
212400123 A fine bottle of 18-year old
2125 Oban whiskey. ($148)
2129To nest multiple lines to the same level, align them with the
2130\f[C]\[ha]\f[R] directive in the template.
2135$item.number$ $\[ha]$$item.description$ ($item.price$)
2136 (Available til $item.sellby$.)
214400123 A fine bottle of 18-year old
2145 Oban whiskey. ($148)
2146 (Available til March 30, 2020.)
2150If a variable occurs by itself on a line, preceded by whitespace and not
2151followed by further text or directives on the same line, and the
2152variable\[aq]s value contains multiple lines, it will be nested
2156Normally, spaces in the template itself (as opposed to values of the
2157interpolated variables) are not breakable, but they can be made
2158breakable in part of the template by using the \f[C]\[ti]\f[R] keyword
2159(ended with another \f[C]\[ti]\f[R]).
2163$\[ti]$This long line may break if the document is rendered
2164with a short line length.$\[ti]$
2169A pipe transforms the value of a variable or partial.
2170Pipes are specified using a slash (\f[C]/\f[R]) between the variable
2171name (or partial) and the pipe name.
2180$for(metadata/pairs)$
2181- $it.key$: $it.value$
2184$employee:name()/uppercase$
2188Pipes may be chained:
2192$for(employees/pairs)$
2193$it.key/alpha/uppercase$. $it.name$
2198Some pipes take parameters:
2202|----------------------|------------|
2204$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$
2206|----------------------|------------|
2210Currently the following pipes are predefined:
2212\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with
2213\f[C]key\f[R] and \f[C]value\f[R] fields.
2214If the original value was an array, the \f[C]key\f[R] will be the array
2215index, starting with 1.
2217\f[C]uppercase\f[R]: Converts text to uppercase.
2219\f[C]lowercase\f[R]: Converts text to lowercase.
2221\f[C]length\f[R]: Returns the length of the value: number of characters
2222for a textual value, number of elements for a map or array.
2224\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect
2227\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).
2229\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.
2231\f[C]alpha\f[R]: Converts textual values that can be read as an integer
2232into lowercase alphabetic characters \f[C]a..z\f[R] (mod 26).
2233This can be used to get lettered enumeration from array indices.
2234To get uppercase letters, chain with \f[C]uppercase\f[R].
2236\f[C]roman\f[R]: Converts textual values that can be read as an integer
2237into lowercase roman numerials.
2238This can be used to get lettered enumeration from array indices.
2239To get uppercase roman, chain with \f[C]uppercase\f[R].
2241\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2242textual value in a block of width \f[C]n\f[R], aligned to the left, with
2243an optional left and right border.
2244Has no effect on other values.
2245This can be used to align material in tables.
2246Widths are positive integers indicating the number of characters.
2247Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and
2248\f[C]\[rs]\f[R] characters must be backslash-escaped.
2250\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2251textual value in a block of width \f[C]n\f[R], aligned to the right, and
2252has no effect on other values.
2254\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2255textual value in a block of width \f[C]n\f[R], aligned to the center,
2256and has no effect on other values.
2258.SS Metadata variables
2260\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]
2261allow identification of basic aspects of the document.
2262Included in PDF metadata through LaTeX and ConTeXt.
2263These can be set through a pandoc title block, which allows for multiple
2264authors, or through a YAML metadata block:
2277Note that if you just want to set PDF or HTML metadata, without
2278including a title block in the document itself, you can set the
2279\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]
2281(By default these are set automatically, based on \f[C]title\f[R],
2282\f[C]author\f[R], and \f[C]date\f[R].)
2285\f[B]\f[CB]subtitle\f[B]\f[R]
2286document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx
2289\f[B]\f[CB]abstract\f[B]\f[R]
2290document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
2293\f[B]\f[CB]keywords\f[B]\f[R]
2294list of keywords to be included in HTML, PDF, ODT, pptx, docx and
2295AsciiDoc metadata; repeat as for \f[C]author\f[R], above
2297\f[B]\f[CB]subject\f[B]\f[R]
2298document subject, included in ODT, PDF, docx and pptx metadata
2300\f[B]\f[CB]description\f[B]\f[R]
2301document description, included in ODT, docx and pptx metadata.
2302Some applications show this as \f[C]Comments\f[R] metadata.
2304\f[B]\f[CB]category\f[B]\f[R]
2305document category, included in docx and pptx metadata
2307Additionally, any root-level string metadata, not included in ODT, docx
2308or pptx metadata is added as a \f[I]custom property\f[R].
2309The following YAML metadata block for instance:
2314title: \[aq]This is the title\[aq]
2315subtitle: \[dq]This is the subtitle\[dq]
2323 It consists of two paragraphs
2328will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]
2329as standard document properties and \f[C]subtitle\f[R] as a custom
2330property when converting to docx, ODT or pptx.
2331.SS Language variables
2333\f[B]\f[CB]lang\f[B]\f[R]
2334identifies the main language of the document using IETF language tags
2335(following the BCP 47 standard), such as \f[C]en\f[R] or
2337The Language subtag lookup tool can look up or verify these tags.
2338This affects most formats, and controls hyphenation in PDF output when
2339using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or
2343Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to
2352Text in the main document language (British English).
2355> Cette citation est \['e]crite en fran\[,c]ais canadien.
2358More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}
2363\f[B]\f[CB]dir\f[B]\f[R]
2364the base script direction, either \f[C]rtl\f[R] (right-to-left) or
2365\f[C]ltr\f[R] (left-to-right).
2368For bidirectional documents, native pandoc \f[C]span\f[R]s and
2369\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or
2370\f[C]ltr\f[R]) can be used to override the base direction in some output
2372This may not always be necessary if the final renderer (e.g.
2373the browser, when generating HTML) supports the Unicode Bidirectional
2376When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
2377engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
2379.SS Variables for HTML math
2381\f[B]\f[CB]classoption\f[B]\f[R]
2382when using KaTeX, you can render display math equations flush left using
2383YAML metadata or with \f[C]-M classoption=fleqn\f[R].
2384.SS Variables for HTML slides
2386These affect HTML output when producing slide shows with pandoc.
2388All reveal.js configuration options are available as variables.
2389To turn off boolean flags that default to true in reveal.js, use
2392\f[B]\f[CB]revealjs-url\f[B]\f[R]
2393base URL for reveal.js documents (defaults to \f[C]reveal.js\f[R])
2395\f[B]\f[CB]s5-url\f[B]\f[R]
2396base URL for S5 documents (defaults to \f[C]s5/default\f[R])
2398\f[B]\f[CB]slidy-url\f[B]\f[R]
2399base URL for Slidy documents (defaults to
2400\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])
2402\f[B]\f[CB]slideous-url\f[B]\f[R]
2403base URL for Slideous documents (defaults to \f[C]slideous\f[R])
2405\f[B]\f[CB]title-slide-attributes\f[B]\f[R]
2406additional attributes for the title slide of reveal.js slide shows.
2407See background in reveal.js and beamer for an example.
2408.SS Variables for Beamer slides
2410These variables change the appearance of PDF slides using
2413\f[B]\f[CB]aspectratio\f[B]\f[R]
2414slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for
241516:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]
2416for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)
2418\f[B]\f[CB]beamerarticle\f[B]\f[R]
2419produce an article from Beamer slides
2421\f[B]\f[CB]beameroption\f[B]\f[R]
2422add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]
2424\f[B]\f[CB]institute\f[B]\f[R]
2425author affiliations: can be a list when there are multiple authors
2427\f[B]\f[CB]logo\f[B]\f[R]
2428logo image for slides
2430\f[B]\f[CB]navigation\f[B]\f[R]
2431controls navigation symbols (default is \f[C]empty\f[R] for no
2432navigation symbols; other valid values are \f[C]frame\f[R],
2433\f[C]vertical\f[R], and \f[C]horizontal\f[R])
2435\f[B]\f[CB]section-titles\f[B]\f[R]
2436enables \[dq]title pages\[dq] for new sections (default is true)
2438\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]
2441\f[B]\f[CB]themeoptions\f[B]\f[R]
2442options for LaTeX beamer themes (a list).
2444\f[B]\f[CB]titlegraphic\f[B]\f[R]
2445image for title slide
2446.SS Variables for PowerPoint
2448These variables control the visual aspects of a slide show that are not
2449easily controlled via templates.
2451\f[B]\f[CB]monofont\f[B]\f[R]
2452font to use for code.
2453.SS Variables for LaTeX
2455Pandoc uses these variables when creating a PDF with a LaTeX engine.
2458\f[B]\f[CB]block-headings\f[B]\f[R]
2459make \f[C]\[rs]paragraph\f[R] and \f[C]\[rs]subparagraph\f[R] (fourth-
2460and fifth-level headings, or fifth- and sixth-level with book classes)
2461free-standing rather than run-in; requires further formatting to
2462distinguish from \f[C]\[rs]subsubsection\f[R] (third- or fourth-level
2464Instead of using this option, KOMA-Script can adjust headings more
2471documentclass: scrartcl
2473 \[rs]RedeclareSectionCommand[
2474 beforeskip=-10pt plus -2pt minus -1pt,
2475 afterskip=1sp plus -1sp minus 1sp,
2476 font=\[rs]normalfont\[rs]itshape]{paragraph}
2477 \[rs]RedeclareSectionCommand[
2478 beforeskip=-10pt plus -2pt minus -1pt,
2479 afterskip=1sp plus -1sp minus 1sp,
2480 font=\[rs]normalfont\[rs]scshape,
2481 indent=0pt]{subparagraph}
2487\f[B]\f[CB]classoption\f[B]\f[R]
2488option for document class, e.g.
2489\f[C]oneside\f[R]; repeat for multiple options:
2503\f[B]\f[CB]documentclass\f[B]\f[R]
2504document class: usually one of the standard classes, \f[C]article\f[R],
2505\f[C]book\f[R], and \f[C]report\f[R]; the KOMA-Script equivalents,
2506\f[C]scrartcl\f[R], \f[C]scrbook\f[R], and \f[C]scrreprt\f[R], which
2507default to smaller margins; or \f[C]memoir\f[R]
2509\f[B]\f[CB]geometry\f[B]\f[R]
2510option for \f[C]geometry\f[R] package, e.g.
2511\f[C]margin=1in\f[R]; repeat for multiple options:
2526\f[B]\f[CB]hyperrefoptions\f[B]\f[R]
2527option for \f[C]hyperref\f[R] package, e.g.
2528\f[C]linktoc=all\f[R]; repeat for multiple options:
2537- pdfpagemode=FullScreen
2543\f[B]\f[CB]indent\f[B]\f[R]
2544uses document class settings for indentation (the default LaTeX template
2545otherwise removes indentation and adds space between paragraphs)
2547\f[B]\f[CB]linestretch\f[B]\f[R]
2548adjusts line spacing using the \f[C]setspace\f[R] package, e.g.
2549\f[C]1.25\f[R], \f[C]1.5\f[R]
2551\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]
2552sets margins if \f[C]geometry\f[R] is not used (otherwise
2553\f[C]geometry\f[R] overrides these)
2555\f[B]\f[CB]pagestyle\f[B]\f[R]
2556control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports
2557\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page
2558numbers), and \f[C]headings\f[R] (section titles in running heads)
2560\f[B]\f[CB]papersize\f[B]\f[R]
2562\f[C]letter\f[R], \f[C]a4\f[R]
2564\f[B]\f[CB]secnumdepth\f[B]\f[R]
2565numbering depth for sections (with \f[C]--number-sections\f[R] option or
2566\f[C]numbersections\f[R] variable)
2569\f[B]\f[CB]fontenc\f[B]\f[R]
2570allows font encoding to be specified through \f[C]fontenc\f[R] package
2571(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font
2574\f[B]\f[CB]fontfamily\f[B]\f[R]
2575font package for use with \f[C]pdflatex\f[R]: TeX Live includes many
2576options, documented in the LaTeX Font Catalogue.
2577The default is Latin Modern.
2579\f[B]\f[CB]fontfamilyoptions\f[B]\f[R]
2580options for package used as \f[C]fontfamily\f[R]; repeat for multiple
2582For example, to use the Libertine font with proportional lowercase
2583(old-style) figures through the \f[C]libertinus\f[R] package:
2589fontfamily: libertinus
2598\f[B]\f[CB]fontsize\f[B]\f[R]
2599font size for body text.
2600The standard classes allow 10pt, 11pt, and 12pt.
2601To use another size, set \f[C]documentclass\f[R] to one of the
2602KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].
2604\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]
2605font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take
2606the name of any system font, using the \f[C]fontspec\f[R] package.
2607\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.
2609\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]
2610options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],
2611\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in
2612\f[C]xelatex\f[R] and \f[C]lualatex\f[R].
2613Allow for any choices available through \f[C]fontspec\f[R]; repeat for
2615For example, to use the TeX Gyre version of Palatino with lowercase
2622mainfont: TeX Gyre Pagella
2625- Numbers=Proportional
2631\f[B]\f[CB]microtypeoptions\f[B]\f[R]
2632options to pass to the microtype package
2635\f[B]\f[CB]colorlinks\f[B]\f[R]
2636add color to link text; automatically enabled if any of
2637\f[C]linkcolor\f[R], \f[C]filecolor\f[R], \f[C]citecolor\f[R],
2638\f[C]urlcolor\f[R], or \f[C]toccolor\f[R] are set
2640\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]
2641color for internal links, external links, citation links, linked URLs,
2642and links in table of contents, respectively: uses options allowed by
2643\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],
2644\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists
2646\f[B]\f[CB]links-as-notes\f[B]\f[R]
2647causes links to be printed as footnotes
2650\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2651include list of figures, list of tables
2653\f[B]\f[CB]thanks\f[B]\f[R]
2654contents of acknowledgments footnote after document title
2656\f[B]\f[CB]toc\f[B]\f[R]
2657include table of contents (can also be set using
2658\f[C]--toc/--table-of-contents\f[R])
2660\f[B]\f[CB]toc-depth\f[B]\f[R]
2661level of section to include in table of contents
2662.SS BibLaTeX Bibliographies
2664These variables function when using BibLaTeX for citation rendering.
2666\f[B]\f[CB]biblatexoptions\f[B]\f[R]
2667list of options for biblatex
2669\f[B]\f[CB]biblio-style\f[B]\f[R]
2670bibliography style, when used with \f[C]--natbib\f[R] and
2671\f[C]--biblatex\f[R].
2673\f[B]\f[CB]biblio-title\f[B]\f[R]
2674bibliography title, when used with \f[C]--natbib\f[R] and
2675\f[C]--biblatex\f[R].
2677\f[B]\f[CB]bibliography\f[B]\f[R]
2678bibliography to use for resolving references
2680\f[B]\f[CB]natbiboptions\f[B]\f[R]
2681list of options for natbib
2682.SS Variables for ConTeXt
2684Pandoc uses these variables when creating a PDF with ConTeXt.
2686\f[B]\f[CB]fontsize\f[B]\f[R]
2687font size for body text (e.g.
2688\f[C]10pt\f[R], \f[C]12pt\f[R])
2690\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]
2691text to be placed in running header or footer (see ConTeXt Headers and
2692Footers); repeat up to four times for different placement
2694\f[B]\f[CB]indenting\f[B]\f[R]
2695controls indentation of paragraphs, e.g.
2696\f[C]yes,small,next\f[R] (see ConTeXt Indentation); repeat for multiple
2699\f[B]\f[CB]interlinespace\f[B]\f[R]
2700adjusts line spacing, e.g.
2701\f[C]4ex\f[R] (using \f[C]setupinterlinespace\f[R]); repeat for multiple
2704\f[B]\f[CB]layout\f[B]\f[R]
2705options for page margins and text arrangement (see ConTeXt Layout);
2706repeat for multiple options
2708\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]
2709color for links outside and inside a page, e.g.
2710\f[C]red\f[R], \f[C]blue\f[R] (see ConTeXt Color)
2712\f[B]\f[CB]linkstyle\f[B]\f[R]
2713typeface style for links, e.g.
2714\f[C]normal\f[R], \f[C]bold\f[R], \f[C]slanted\f[R],
2715\f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R], \f[C]small\f[R]
2717\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2718include list of figures, list of tables
2720\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]
2721font families: take the name of any system font (see ConTeXt Font
2724\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]
2725sets margins, if \f[C]layout\f[R] is not used (otherwise
2726\f[C]layout\f[R] overrides these)
2728\f[B]\f[CB]pagenumbering\f[B]\f[R]
2729page number style and location (using \f[C]setuppagenumbering\f[R]);
2730repeat for multiple options
2732\f[B]\f[CB]papersize\f[B]\f[R]
2734\f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R] (see ConTeXt Paper
2735Setup); repeat for multiple options
2737\f[B]\f[CB]pdfa\f[B]\f[R]
2738adds to the preamble the setup necessary to generate PDF/A of the type
2740\f[C]1a:2005\f[R], \f[C]2a\f[R].
2741If no type is specified (i.e.
2742the value is set to True, by e.g.
2743\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata
2744block), \f[C]1b:2005\f[R] will be used as default, for reasons of
2745backwards compatibility.
2746Using \f[C]--variable=pdfa\f[R] without specified value is not
2748To successfully generate PDF/A the required ICC color profiles have to
2749be available and the content and all included files (such as images)
2750have to be standard conforming.
2751The ICC profiles and output intent may be specified using the variables
2752\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].
2753See also ConTeXt PDFA for more details.
2755\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]
2756when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile
2757to use in the PDF, e.g.
2758\f[C]default.cmyk\f[R].
2759If left unspecified, \f[C]sRGB.icc\f[R] is used as default.
2760May be repeated to include multiple profiles.
2761Note that the profiles have to be available on the system.
2762They can be obtained from ConTeXt ICC Profiles.
2764\f[B]\f[CB]pdfaintent\f[B]\f[R]
2765when used in conjunction with \f[C]pdfa\f[R], specifies the output
2766intent for the colors, e.g.
2767\f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If left
2768unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
2770\f[B]\f[CB]toc\f[B]\f[R]
2771include table of contents (can also be set using
2772\f[C]--toc/--table-of-contents\f[R])
2774\f[B]\f[CB]whitespace\f[B]\f[R]
2775spacing between paragraphs, e.g.
2776\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])
2778\f[B]\f[CB]includesource\f[B]\f[R]
2779include all source documents as file attachments in the PDF file
2780.SS Variables for \f[C]wkhtmltopdf\f[R]
2782Pandoc uses these variables when creating a PDF with
2783\f[C]wkhtmltopdf\f[R].
2784The \f[C]--css\f[R] option also affects the output.
2786\f[B]\f[CB]footer-html\f[B]\f[R], \f[B]\f[CB]header-html\f[B]\f[R]
2787add information to the header and footer
2789\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]
2792\f[B]\f[CB]papersize\f[B]\f[R]
2793sets the PDF paper size
2794.SS Variables for man pages
2796\f[B]\f[CB]adjusting\f[B]\f[R]
2797adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center
2798(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins
2800\f[B]\f[CB]footer\f[B]\f[R]
2803\f[B]\f[CB]header\f[B]\f[R]
2806\f[B]\f[CB]hyphenate\f[B]\f[R]
2807if \f[C]true\f[R] (the default), hyphenation will be used
2809\f[B]\f[CB]section\f[B]\f[R]
2810section number in man pages
2813\f[B]\f[CB]fontfamily\f[B]\f[R]
2815\f[C]T\f[R] or \f[C]P\f[R])
2817\f[B]\f[CB]indent\f[B]\f[R]
2818paragraph indent (e.g.
2821\f[B]\f[CB]lineheight\f[B]\f[R]
2825\f[B]\f[CB]pointsize\f[B]\f[R]
2828.SS Variables set automatically
2830Pandoc sets these variables automatically in response to options or
2831document contents; users can also modify them.
2832These vary depending on the output format, and include the following:
2834\f[B]\f[CB]body\f[B]\f[R]
2837\f[B]\f[CB]date-meta\f[B]\f[R]
2838the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included
2839in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,
2840s5, slideous, slidy).
2841The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],
2842\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),
2843\f[C]dd MM yyyy\f[R] (e.g.
2844either \f[C]02 Apr 2018\f[R] or \f[C]02 April 2018\f[R]),
2845\f[C]MM dd, yyyy\f[R] (e.g.
2846\f[C]Apr. 02, 2018\f[R] or
2847\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,
2848\f[C]201804\f[R] or \f[C]2018\f[R]).
2850\f[B]\f[CB]header-includes\f[B]\f[R]
2851contents specified by \f[C]-H/--include-in-header\f[R] (may have
2854\f[B]\f[CB]include-before\f[B]\f[R]
2855contents specified by \f[C]-B/--include-before-body\f[R] (may have
2858\f[B]\f[CB]include-after\f[B]\f[R]
2859contents specified by \f[C]-A/--include-after-body\f[R] (may have
2862\f[B]\f[CB]meta-json\f[B]\f[R]
2863JSON representation of all of the document\[aq]s metadata.
2864Field values are transformed to the selected output format.
2866\f[B]\f[CB]numbersections\f[B]\f[R]
2867non-null value if \f[C]-N/--number-sections\f[R] was specified
2869\f[B]\f[CB]sourcefile\f[B]\f[R], \f[B]\f[CB]outputfile\f[B]\f[R]
2870source and destination filenames, as given on the command line.
2871\f[C]sourcefile\f[R] can also be a list if input comes from multiple
2872files, or empty if input is from stdin.
2873You can use the following snippet in your template to distinguish them:
2888Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the
2891If you need absolute paths, use e.g.
2892\f[C]$curdir$/$sourcefile$\f[R].
2895\f[B]\f[CB]curdir\f[B]\f[R]
2896working directory from which pandoc is run.
2898\f[B]\f[CB]toc\f[B]\f[R]
2899non-null value if \f[C]--toc/--table-of-contents\f[R] was specified
2901\f[B]\f[CB]toc-title\f[B]\f[R]
2902title of table of contents (works only with EPUB, HTML, opendocument,
2903odt, docx, pptx, beamer, LaTeX)
2906The behavior of some of the readers and writers can be adjusted by
2907enabling or disabling various extensions.
2909An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format
2910name and disabled by adding \f[C]-EXTENSION\f[R].
2911For example, \f[C]--from markdown_strict+footnotes\f[R] is strict
2912Markdown with footnotes enabled, while
2913\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[aq]s Markdown
2914without footnotes or pipe tables.
2916The markdown reader and writer make by far the most use of extensions.
2917Extensions only used by them are therefore covered in the section
2918Pandoc\[aq]s Markdown below (See Markdown variants for
2919\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
2920that also work for other formats are covered.
2922Note that markdown extensions added to the \f[C]ipynb\f[R] format affect
2923Markdown cells in Jupyter notebooks (as do command-line options like
2924\f[C]--atx-headers\f[R]).
2926.SS Extension: \f[C]smart\f[R]
2928Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,
2929\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.
2930Nonbreaking spaces are inserted after certain abbreviations, such as
2933This extension can be enabled/disabled for the following formats:
2936\f[C]markdown\f[R], \f[C]commonmark\f[R], \f[C]latex\f[R],
2937\f[C]mediawiki\f[R], \f[C]org\f[R], \f[C]rst\f[R], \f[C]twiki\f[R]
2940\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R], \f[C]rst\f[R]
2942enabled by default in
2943\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R] (both input and
2946Note: If you are \f[I]writing\f[R] Markdown, then the \f[C]smart\f[R]
2947extension has the reverse effect: what would have been curly quotes
2950In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for
2951quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for
2952double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)
2953and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).
2954If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse
2955these characters literally.
2956In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the
2957ligatures when possible; if \f[C]smart\f[R] is disabled pandoc will use
2958unicode quotation mark and dash characters.
2959.SS Headings and sections
2960.SS Extension: \f[C]auto_identifiers\f[R]
2962A heading without an explicitly specified identifier will be
2963automatically assigned a unique identifier based on the heading text.
2965This extension can be enabled/disabled for the following formats:
2968\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]rst\f[R], \f[C]mediawiki\f[R],
2972\f[C]markdown\f[R], \f[C]muse\f[R]
2974enabled by default in
2975\f[C]markdown\f[R], \f[C]muse\f[R]
2977The default algorithm used to derive the identifier from the heading
2980Remove all formatting, links, etc.
2982Remove all footnotes.
2984Remove all non-alphanumeric characters, except underscores, hyphens, and
2987Replace all spaces and newlines with hyphens.
2989Convert all alphabetic characters to lowercase.
2991Remove everything up to the first letter (identifiers may not begin with
2992a number or punctuation mark).
2994If nothing is left after this, use the identifier \f[C]section\f[R].
3008\f[C]Heading identifiers in HTML\f[R]
3010\f[C]heading-identifiers-in-html\f[R]
3013\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]
3015\f[C]ma\[^i]tre-dh\[^o]tel\f[R]
3018\f[C]*Dogs*?--in *my* house?\f[R]
3020\f[C]dogs--in-my-house\f[R]
3023\f[C][HTML], [S5], or [RTF]?\f[R]
3025\f[C]html-s5-or-rtf\f[R]
3028\f[C]3. Applications\f[R]
3030\f[C]applications\f[R]
3039These rules should, in most cases, allow one to determine the identifier
3040from the heading text.
3041The exception is when several headings have the same text; in this case,
3042the first will get an identifier as described above; the second will get
3043the same identifier with \f[C]-1\f[R] appended; the third with
3044\f[C]-2\f[R]; and so on.
3046(However, a different algorithm is used if
3047\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)
3049These identifiers are used to provide link targets in the table of
3050contents generated by the \f[C]--toc|--table-of-contents\f[R] option.
3051They also make it easy to provide links from one section of a document
3053A link to this section, for example, might look like this:
3058[heading identifiers](#heading-identifiers-in-html-latex-and-context).
3062Note, however, that this method of providing links to sections works
3063only in HTML, LaTeX, and ConTeXt formats.
3065If the \f[C]--section-divs\f[R] option is specified, then each section
3066will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if
3067\f[C]html4\f[R] was specified), and the identifier will be attached to
3068the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than
3070This allows entire sections to be manipulated using JavaScript or
3071treated differently in CSS.
3072.SS Extension: \f[C]ascii_identifiers\f[R]
3074Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure
3076Accents are stripped off of accented Latin letters, and non-Latin
3078.SS Extension: \f[C]gfm_auto_identifiers\f[R]
3080Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
3082Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
3083lowercase characters, and punctuation characters other than \f[C]-\f[R]
3084and \f[C]_\f[R] are removed.
3085Emojis are replaced by their names.
3088The extensions \f[C]tex_math_dollars\f[R],
3089\f[C]tex_math_single_backslash\f[R], and
3090\f[C]tex_math_double_backslash\f[R] are described in the section about
3091Pandoc\[aq]s Markdown.
3093However, they can also be used with HTML input.
3094This is handy for reading web pages formatted using MathJax, for
3098The following extensions (especially how they affect Markdown
3099input/output) are also described in more detail in their respective
3100sections of Pandoc\[aq]s Markdown.
3101.SS Extension: \f[C]raw_html\f[R]
3103When converting from HTML, parse elements to raw HTML which are not
3104representable in pandoc\[aq]s AST.
3105By default, this is disabled for HTML input.
3106.SS Extension: \f[C]raw_tex\f[R]
3108Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
3110This extension can be enabled/disabled for the following formats (in
3111addition to \f[C]markdown\f[R]):
3114\f[C]latex\f[R], \f[C]org\f[R], \f[C]textile\f[R], \f[C]html\f[R]
3115(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only),
3119\f[C]textile\f[R], \f[C]commonmark\f[R]
3121Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and
3122\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data
3123with mime type \f[C]text/html\f[R] in output cells.
3124Since the \f[C]ipynb\f[R] reader attempts to preserve the richest
3125possible outputs when several options are given, you will get best
3126results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when
3127converting to formats like \f[C]docx\f[R] which don\[aq]t allow raw
3128\f[C]html\f[R] or \f[C]tex\f[R].
3129.SS Extension: \f[C]native_divs\f[R]
3131This extension is enabled by default for HTML input.
3132This means that \f[C]div\f[R]s are parsed to pandoc native elements.
3133(Alternatively, you can parse them to raw HTML using
3134\f[C]-f html-native_divs+raw_html\f[R].)
3136When converting HTML to Markdown, for example, you may want to drop all
3137\f[C]div\f[R]s and \f[C]span\f[R]s:
3141pandoc -f html-native_divs-native_spans -t markdown
3144.SS Extension: \f[C]native_spans\f[R]
3146Analogous to \f[C]native_divs\f[R] above.
3147.SS Literate Haskell support
3148.SS Extension: \f[C]literate_haskell\f[R]
3150Treat the document as literate Haskell source.
3152This extension can be enabled/disabled for the following formats:
3155\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R]
3158\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R], \f[C]html\f[R]
3160If you append \f[C]+lhs\f[R] (or \f[C]+literate_haskell\f[R]) to one of
3161the formats above, pandoc will treat the document as literate Haskell
3165In Markdown input, \[dq]bird track\[dq] sections will be parsed as
3166Haskell code rather than block quotations.
3167Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]
3168will also be treated as Haskell code.
3169For ATX-style headings the character \[aq]=\[aq] will be used instead of
3172In Markdown output, code blocks with classes \f[C]haskell\f[R] and
3173\f[C]literate\f[R] will be rendered using bird tracks, and block
3174quotations will be indented one space, so they will not be treated as
3176In addition, headings will be rendered setext-style (with underlines)
3177rather than ATX-style (with \[aq]#\[aq] characters).
3178(This is because ghc treats \[aq]#\[aq] characters in column 1 as
3179introducing line numbers.)
3181In restructured text input, \[dq]bird track\[dq] sections will be parsed
3184In restructured text output, code blocks with class \f[C]haskell\f[R]
3185will be rendered using bird tracks.
3187In LaTeX input, text in \f[C]code\f[R] environments will be parsed as
3190In LaTeX output, code blocks with class \f[C]haskell\f[R] will be
3191rendered inside \f[C]code\f[R] environments.
3193In HTML output, code blocks with class \f[C]haskell\f[R] will be
3194rendered with class \f[C]literatehaskell\f[R] and bird tracks.
3200pandoc -f markdown+lhs -t html
3204reads literate Haskell source formatted with Markdown conventions and
3205writes ordinary HTML (without bird tracks).
3209pandoc -f markdown+lhs -t html+lhs
3213writes HTML with the Haskell code in bird tracks, so it can be copied
3214and pasted as literate Haskell source.
3216Note that GHC expects the bird tracks in the first column, so indented
3217literate code blocks (e.g.
3218inside an itemized environment) will not be picked up by the Haskell
3221.SS Extension: \f[C]empty_paragraphs\f[R]
3223Allows empty paragraphs.
3224By default empty paragraphs are omitted.
3226This extension can be enabled/disabled for the following formats:
3229\f[C]docx\f[R], \f[C]html\f[R]
3232\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]
3233.SS Extension: \f[C]native_numbering\f[R]
3235Enables native numbering of figures and tables.
3236Enumeration starts at 1.
3238This extension can be enabled/disabled for the following formats:
3241\f[C]odt\f[R], \f[C]opendocument\f[R]
3242.SS Extension: \f[C]styles\f[R]
3244When converting from docx, read all docx styles as divs (for paragraph
3245styles) and spans (for character styles) regardless of whether pandoc
3246understands the meaning of these styles.
3247This can be used with docx custom styles.
3252.SS Extension: \f[C]amuse\f[R]
3254In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions
3255to Emacs Muse markup.
3256.SS Extension: \f[C]citations\f[R]
3258Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted
3259in \f[C]org\f[R] input.
3260.SS Extension: \f[C]ntb\f[R]
3262In the \f[C]context\f[R] output format this enables the use of Natural
3263Tables (TABLE) instead of the default Extreme Tables (xtables).
3264Natural tables allow more fine-grained global customization but come at
3265a performance penalty compared to extreme tables.
3266.SH PANDOC\[aq]S MARKDOWN
3268Pandoc understands an extended and slightly revised version of John
3269Gruber\[aq]s Markdown syntax.
3270This document explains the syntax, noting differences from standard
3272Except where noted, these differences can be suppressed by using the
3273\f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R].
3274Extensions can be enabled or disabled to specify the behavior more
3276They are described in the following.
3277See also Extensions above, for extensions that work also on other
3281Markdown is designed to be easy to write, and, even more importantly,
3285A Markdown-formatted document should be publishable as-is, as plain
3286text, without looking like it\[aq]s been marked up with tags or
3287formatting instructions.
3291This principle has guided pandoc\[aq]s decisions in finding syntax for
3292tables, footnotes, and other extensions.
3294There is, however, one respect in which pandoc\[aq]s aims are different
3295from the original aims of Markdown.
3296Whereas Markdown was originally designed with HTML generation in mind,
3297pandoc is designed for multiple output formats.
3298Thus, while pandoc allows the embedding of raw HTML, it discourages it,
3299and provides other, non-HTMLish ways of representing important document
3300elements like definition lists, tables, mathematics, and footnotes.
3303A paragraph is one or more lines of text followed by one or more blank
3305Newlines are treated as spaces, so you can reflow your paragraphs as you
3307If you need a hard line break, put two or more spaces at the end of a
3309.SS Extension: \f[C]escaped_line_breaks\f[R]
3311A backslash followed by a newline is also a hard line break.
3312Note: in multiline and grid table cells, this is the only way to create
3313a hard line break, since trailing spaces in the cells are ignored.
3316There are two kinds of headings: Setext and ATX.
3317.SS Setext-style headings
3319A setext-style heading is a line of text \[dq]underlined\[dq] with a row
3320of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for
3321a level-two heading):
3333The heading text can contain inline formatting, such as emphasis (see
3334Inline formatting, below).
3335.SS ATX-style headings
3337An ATX-style heading consists of one to six \f[C]#\f[R] signs and a line
3338of text, optionally followed by any number of \f[C]#\f[R] signs.
3339The number of \f[C]#\f[R] signs at the beginning of the line is the
3344## A level-two heading
3346### A level-three heading ###
3350As with setext-style headings, the heading text can contain formatting:
3354# A level-one heading with a [link](/url) and *emphasis*
3357.SS Extension: \f[C]blank_before_header\f[R]
3359Standard Markdown syntax does not require a blank line before a heading.
3360Pandoc does require this (except, of course, at the beginning of the
3362The reason for the requirement is that it is all too easy for a
3363\f[C]#\f[R] to end up at the beginning of a line by accident (perhaps
3364through line wrapping).
3365Consider, for example:
3369I like several of their flavors of ice cream:
3370#22, for example, and #5.
3373.SS Extension: \f[C]space_in_atx_header\f[R]
3375Many Markdown implementations do not require a space between the opening
3376\f[C]#\f[R]s of an ATX heading and the heading text, so that
3377\f[C]#5 bolt\f[R] and \f[C]#hashtag\f[R] count as headings.
3378With this extension, pandoc does require the space.
3379.SS Heading identifiers
3381See also the \f[C]auto_identifiers\f[R] extension above.
3382.SS Extension: \f[C]header_attributes\f[R]
3384Headings can be assigned attributes using this syntax at the end of the
3385line containing the heading text:
3389{#identifier .class .class key=value key=value}
3393Thus, for example, the following headings will all be assigned the
3394identifier \f[C]foo\f[R]:
3400## My heading ## {#foo}
3402My other heading {#foo}
3407(This syntax is compatible with PHP Markdown Extra.)
3409Note that although this syntax allows assignment of classes and
3410key/value attributes, writers generally don\[aq]t use all of this
3412Identifiers, classes, and key/value attributes are used in HTML and
3413HTML-based formats such as EPUB and slidy.
3414Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,
3415Textile, Jira markup, and AsciiDoc writers.
3417Headings with the class \f[C]unnumbered\f[R] will not be numbered, even
3418if \f[C]--number-sections\f[R] is specified.
3419A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to
3420\f[C].unnumbered\f[R], and preferable in non-English documents.
3433# My heading {.unnumbered}
3437If the \f[C]unlisted\f[R] class is present in addition to
3438\f[C]unnumbered\f[R], the heading will not be included in a table of
3440(Currently this feature is only implemented for certain formats: those
3441based on LaTeX and HTML, PowerPoint, and RTF.)
3442.SS Extension: \f[C]implicit_header_references\f[R]
3444Pandoc behaves as if reference links have been defined for each heading.
3445So, to link to a heading
3449# Heading identifiers in HTML
3457[Heading identifiers in HTML]
3465[Heading identifiers in HTML][]
3473[the section on heading identifiers][heading identifiers in
3478instead of giving the identifier explicitly:
3482[Heading identifiers in HTML](#heading-identifiers-in-html)
3486If there are multiple headings with identical text, the corresponding
3487reference will link to the first one only, and you will need to use
3488explicit links to link to the others, as described above.
3490Like regular reference links, these references are case-insensitive.
3492Explicit link reference definitions always take priority over implicit
3494So, in the following example, the link will point to \f[C]bar\f[R], not
3508Markdown uses email conventions for quoting blocks of text.
3509A block quotation is one or more paragraphs or other block elements
3510(such as lists or headings), with each line preceded by a \f[C]>\f[R]
3511character and an optional space.
3512(The \f[C]>\f[R] need not start at the left margin, but it should not be
3513indented more than three spaces.)
3517> This is a block quote. This
3518> paragraph has two lines.
3520> 1. This is a list inside a block quote.
3525A \[dq]lazy\[dq] form, which requires the \f[C]>\f[R] character only on
3526the first line of each block, is also allowed:
3530> This is a block quote. This
3531paragraph has two lines.
3533> 1. This is a list inside a block quote.
3538Among the block elements that can be contained in a block quote are
3540That is, block quotes can be nested:
3544> This is a block quote.
3546> > A block quote within a block quote.
3550If the \f[C]>\f[R] character is followed by an optional space, that
3551space will be considered part of the block quote marker and not part of
3552the indentation of the contents.
3553Thus, to put an indented code block in a block quote, you need five
3554spaces after the \f[C]>\f[R]:
3561.SS Extension: \f[C]blank_before_blockquote\f[R]
3563Standard Markdown syntax does not require a blank line before a block
3565Pandoc does require this (except, of course, at the beginning of the
3567The reason for the requirement is that it is all too easy for a
3568\f[C]>\f[R] to end up at the beginning of a line by accident (perhaps
3569through line wrapping).
3570So, unless the \f[C]markdown_strict\f[R] format is used, the following
3571does not produce a nested block quote in pandoc:
3575> This is a block quote.
3579.SS Verbatim (code) blocks
3580.SS Indented code blocks
3582A block of text indented four spaces (or one tab) is treated as verbatim
3583text: that is, special characters do not trigger special formatting, and
3584all spaces and line breaks are preserved.
3590 moveShip(5 * gravity, DOWN);
3595The initial (four space or one tab) indentation is not considered part
3596of the verbatim text, and is removed in the output.
3598Note: blank lines in the verbatim text need not begin with four spaces.
3599.SS Fenced code blocks
3600.SS Extension: \f[C]fenced_code_blocks\f[R]
3602In addition to standard indented code blocks, pandoc supports
3603\f[I]fenced\f[R] code blocks.
3604These begin with a row of three or more tildes (\f[C]\[ti]\f[R]) and end
3605with a row of tildes that must be at least as long as the starting row.
3606Everything between these lines is treated as code.
3607No indentation is necessary:
3611\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3613 moveShip(5 * gravity, DOWN);
3615\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3619Like regular code blocks, fenced code blocks must be separated from
3620surrounding text by blank lines.
3622If the code itself contains a row of tildes or backticks, just use a
3623longer row of tildes or backticks at the start and end:
3627\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3628\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3629code including tildes
3630\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3631\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3634.SS Extension: \f[C]backtick_code_blocks\f[R]
3636Same as \f[C]fenced_code_blocks\f[R], but uses backticks
3637(\f[C]\[ga]\f[R]) instead of tildes (\f[C]\[ti]\f[R]).
3638.SS Extension: \f[C]fenced_code_attributes\f[R]
3640Optionally, you may attach attributes to fenced or backtick code block
3645\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}
3647qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3648 qsort (filter (>= x) xs)
3649\[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]
3653Here \f[C]mycode\f[R] is an identifier, \f[C]haskell\f[R] and
3654\f[C]numberLines\f[R] are classes, and \f[C]startFrom\f[R] is an
3655attribute with value \f[C]100\f[R].
3656Some output formats can use this information to do syntax highlighting.
3657Currently, the only output formats that uses this information are HTML,
3658LaTeX, Docx, Ms, and PowerPoint.
3659If highlighting is supported for your output format and language, then
3660the code block above will appear highlighted, with numbered lines.
3661(To see which languages are supported, type
3662\f[C]pandoc --list-highlight-languages\f[R].) Otherwise, the code block
3663above will appear as follows:
3667<pre id=\[dq]mycode\[dq] class=\[dq]haskell numberLines\[dq] startFrom=\[dq]100\[dq]>
3675The \f[C]numberLines\f[R] (or \f[C]number-lines\f[R]) class will cause
3676the lines of the code block to be numbered, starting with \f[C]1\f[R] or
3677the value of the \f[C]startFrom\f[R] attribute.
3678The \f[C]lineAnchors\f[R] (or \f[C]line-anchors\f[R]) class will cause
3679the lines to be clickable anchors in HTML output.
3681A shortcut form can also be used for specifying the language of the code
3686\[ga]\[ga]\[ga]haskell
3692This is equivalent to:
3696\[ga]\[ga]\[ga] {.haskell}
3702If the \f[C]fenced_code_attributes\f[R] extension is disabled, but input
3703contains class attribute(s) for the code block, the first class
3704attribute will be printed after the opening fence as a bare word.
3706To prevent all highlighting, use the \f[C]--no-highlight\f[R] flag.
3707To set the highlighting style, use \f[C]--highlight-style\f[R].
3708For more information on highlighting, see Syntax highlighting, below.
3710.SS Extension: \f[C]line_blocks\f[R]
3712A line block is a sequence of lines beginning with a vertical bar
3713(\f[C]|\f[R]) followed by a space.
3714The division into lines will be preserved in the output, as will any
3715leading spaces; otherwise, the lines will be formatted as Markdown.
3716This is useful for verse and addresses:
3720| The limerick packs laughs anatomical
3721| In space that is quite economical.
3722| But the good ones I\[aq]ve seen
3723| So seldom are clean
3724| And the clean ones so seldom are comical
3731The lines can be hard-wrapped if needed, but the continuation line must
3736| The Right Honorable Most Venerable and Righteous Samuel L.
3743This syntax is borrowed from reStructuredText.
3747A bullet list is a list of bulleted list items.
3748A bulleted list item begins with a bullet (\f[C]*\f[R], \f[C]+\f[R], or
3750Here is a simple example:
3760This will produce a \[dq]compact\[dq] list.
3761If you want a \[dq]loose\[dq] list, in which each item is formatted as a
3762paragraph, put spaces between the items:
3774The bullets need not be flush with the left margin; they may be indented
3775one, two, or three spaces.
3776The bullet must be followed by whitespace.
3778List items look best if subsequent lines are flush with the first line
3789But Markdown also allows a \[dq]lazy\[dq] format:
3798.SS Block content in list items
3800A list item may contain multiple paragraphs and other block-level
3802However, subsequent paragraphs must be preceded by a blank line and
3803indented to line up with the first non-space content after the list
3812 * Second paragraph. With a code block, which must be indented
3819Exception: if the list marker is followed by an indented code block,
3820which must begin 5 spaces after the list marker, then subsequent
3821paragraphs must begin two columns after the last character of the list
3828 continuation paragraph
3832List items may include other lists.
3833In this case the preceding blank line is optional.
3834The nested list must be indented to line up with the first non-space
3835character after the list marker of the containing list item.
3851As noted above, Markdown allows you to write list items
3852\[dq]lazily,\[dq] instead of indenting continuation lines.
3853However, if there are multiple paragraphs or other blocks in a list
3854item, the first line of each must be indented.
3861+ Another one; this looks
3864 Second paragraph of second
3870Ordered lists work just like bulleted lists, except that the items begin
3871with enumerators rather than bullets.
3873In standard Markdown, enumerators are decimal numbers followed by a
3875The numbers themselves are ignored, so there is no difference between
3895.SS Extension: \f[C]fancy_lists\f[R]
3897Unlike standard Markdown, pandoc allows ordered list items to be marked
3898with uppercase and lowercase letters and roman numerals, in addition to
3900List markers may be enclosed in parentheses or followed by a single
3901right-parentheses or period.
3902They must be separated from the text that follows by at least one space,
3903and, if the list marker is a capital letter with a period, by at least
3906The \f[C]fancy_lists\f[R] extension also allows \[aq]\f[C]#\f[R]\[aq] to
3907be used as an ordered list marker in place of a numeral:
3915.SS Extension: \f[C]startnum\f[R]
3917Pandoc also pays attention to the type of list marker used, and to the
3918starting number, and both of these are preserved where possible in the
3920Thus, the following yields a list with numbers followed by a single
3921parenthesis, starting with 9, and a sublist with lowercase roman
3935Pandoc will start a new list each time a different type of list marker
3937So, the following will create three lists:
3948If default list markers are desired, use \f[C]#.\f[R]:
3957.SS Extension: \f[C]task_lists\f[R]
3959Pandoc supports task lists, using the syntax of GitHub-Flavored
3964- [ ] an unchecked task list item
3969.SS Extension: \f[C]definition_lists\f[R]
3971Pandoc supports definition lists, using the syntax of PHP Markdown Extra
3972with some extensions.
3980Term 2 with *inline markup*
3984 { some code, part of Definition 2 }
3986 Third paragraph of definition 2.
3990Each term must fit on one line, which may optionally be followed by a
3991blank line, and must be followed by one or more definitions.
3992A definition begins with a colon or tilde, which may be indented one or
3995A term may have multiple definitions, and each definition may consist of
3996one or more block elements (paragraph, code block, list, etc.), each
3997indented four spaces or one tab stop.
3998The body of the definition (including the first line, aside from the
3999colon or tilde) should be indented four spaces.
4000However, as with other Markdown lists, you can \[dq]lazily\[dq] omit
4001indentation except at the beginning of a paragraph or other block
4009with lazy continuation.
4011 Second paragraph of the definition.
4015If you leave space before the definition (as in the example above), the
4016text of the definition will be treated as a paragraph.
4017In some output formats, this will mean greater spacing between
4018term/definition pairs.
4019For a more compact definition list, omit the space before the
4033Note that space between items in a definition list is required.
4034(A variant that loosens this requirement, but disallows \[dq]lazy\[dq]
4035hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
4036see Non-pandoc extensions, below.)
4037.SS Numbered example lists
4038.SS Extension: \f[C]example_lists\f[R]
4040The special list marker \f[C]\[at]\f[R] can be used for sequentially
4042The first list item with a \f[C]\[at]\f[R] marker will be numbered
4043\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
4044The numbered examples need not occur in a single list; each new list
4045using \f[C]\[at]\f[R] will take up where the last stopped.
4050(\[at]) My first example will be numbered (1).
4051(\[at]) My second example will be numbered (2).
4053Explanation of examples.
4055(\[at]) My third example will be numbered (3).
4059Numbered examples can be labeled and referred to elsewhere in the
4064(\[at]good) This is a good example.
4066As (\[at]good) illustrates, ...
4070The label can be any string of alphanumeric characters, underscores, or
4073Note: continuation paragraphs in example lists must always be indented
4074four spaces, regardless of the length of the list marker.
4075That is, example lists always behave as if the \f[C]four_space_rule\f[R]
4077This is because example labels tend to be long, and indenting content to
4078the first non-space character after the label would be awkward.
4079.SS Compact and loose lists
4081Pandoc behaves differently from \f[C]Markdown.pl\f[R] on some \[dq]edge
4082cases\[dq] involving lists.
4083Consider this source:
4097Pandoc transforms this into a \[dq]compact list\[dq] (with no
4098\f[C]<p>\f[R] tags around \[dq]First\[dq], \[dq]Second\[dq], or
4099\[dq]Third\[dq]), while Markdown puts \f[C]<p>\f[R] tags around
4100\[dq]Second\[dq] and \[dq]Third\[dq] (but not \[dq]First\[dq]), because
4101of the blank space around \[dq]Third\[dq].
4102Pandoc follows a simple rule: if the text is followed by a blank line,
4103it is treated as a paragraph.
4104Since \[dq]Second\[dq] is followed by a list, and not a blank line, it
4105isn\[aq]t treated as a paragraph.
4106The fact that the list is followed by a blank line is irrelevant.
4107(Note: Pandoc works this way even when the \f[C]markdown_strict\f[R]
4109This behavior is consistent with the official Markdown syntax
4110description, even though it is different from that of
4111\f[C]Markdown.pl\f[R].)
4114What if you want to put an indented code block after a list?
4125Trouble! Here pandoc (like other Markdown implementations) will treat
4126\f[C]{ my code block }\f[R] as the second paragraph of item two, and not
4129To \[dq]cut off\[dq] the list after item two, you can insert some
4130non-indented content, like an HTML comment, which won\[aq]t produce
4131visible output in any format:
4144You can use the same trick if you want two consecutive lists instead of
4162A line containing a row of three or more \f[C]*\f[R], \f[C]-\f[R], or
4163\f[C]_\f[R] characters (optionally separated by spaces) produces a
4175Four kinds of tables may be used.
4176The first three kinds presuppose the use of a fixed-width font, such as
4178The fourth kind can be used with proportionally spaced fonts, as it does
4179not require lining up columns.
4180.SS Extension: \f[C]table_captions\f[R]
4182A caption may optionally be provided with all 4 kinds of tables (as
4183illustrated in the examples below).
4184A caption is a paragraph beginning with the string \f[C]Table:\f[R] (or
4185just \f[C]:\f[R]), which will be stripped off.
4186It may appear either before or after the table.
4187.SS Extension: \f[C]simple_tables\f[R]
4189Simple tables look like this:
4193 Right Left Center Default
4194------- ------ ---------- -------
4199Table: Demonstration of simple table syntax.
4203The header and table rows must each fit on one line.
4204Column alignments are determined by the position of the header text
4205relative to the dashed line below it:
4207If the dashed line is flush with the header text on the right side but
4208extends beyond it on the left, the column is right-aligned.
4210If the dashed line is flush with the header text on the left side but
4211extends beyond it on the right, the column is left-aligned.
4213If the dashed line extends beyond the header text on both sides, the
4216If the dashed line is flush with the header text on both sides, the
4217default alignment is used (in most cases, this will be left).
4219The table must end with a blank line, or a line of dashes followed by a
4222The column header row may be omitted, provided a dashed line is used to
4228------- ------ ---------- -------
4232------- ------ ---------- -------
4236When the header row is omitted, column alignments are determined on the
4237basis of the first line of the table body.
4238So, in the tables above, the columns would be right, left, center, and
4239right aligned, respectively.
4240.SS Extension: \f[C]multiline_tables\f[R]
4242Multiline tables allow header and table rows to span multiple lines of
4243text (but cells that span multiple columns or rows of the table are not
4249-------------------------------------------------------------
4250 Centered Default Right Left
4251 Header Aligned Aligned Aligned
4252----------- ------- --------------- -------------------------
4253 First row 12.0 Example of a row that
4254 spans multiple lines.
4256 Second row 5.0 Here\[aq]s another one. Note
4257 the blank line between
4259-------------------------------------------------------------
4261Table: Here\[aq]s the caption. It, too, may span
4266These work like simple tables, but with the following differences:
4268They must begin with a row of dashes, before the header text (unless the
4269header row is omitted).
4271They must end with a row of dashes, then a blank line.
4273The rows must be separated by blank lines.
4275In multiline tables, the table parser pays attention to the widths of
4276the columns, and the writers try to reproduce these relative widths in
4278So, if you find that one of the columns is too narrow in the output, try
4279widening it in the Markdown source.
4281The header may be omitted in multiline tables as well as simple tables:
4285----------- ------- --------------- -------------------------
4286 First row 12.0 Example of a row that
4287 spans multiple lines.
4289 Second row 5.0 Here\[aq]s another one. Note
4290 the blank line between
4292----------- ------- --------------- -------------------------
4294: Here\[aq]s a multiline table without a header.
4298It is possible for a multiline table to have just one row, but the row
4299should be followed by a blank line (and then the row of dashes that ends
4300the table), or the table may be interpreted as a simple table.
4301.SS Extension: \f[C]grid_tables\f[R]
4303Grid tables look like this:
4309+---------------+---------------+--------------------+
4310| Fruit | Price | Advantages |
4311+===============+===============+====================+
4312| Bananas | $1.34 | - built-in wrapper |
4313| | | - bright color |
4314+---------------+---------------+--------------------+
4315| Oranges | $2.10 | - cures scurvy |
4317+---------------+---------------+--------------------+
4321The row of \f[C]=\f[R]s separates the header from the table body, and
4322can be omitted for a headerless table.
4323The cells of grid tables may contain arbitrary block elements (multiple
4324paragraphs, code blocks, lists, etc.).
4325Cells that span multiple columns or rows are not supported.
4326Grid tables can be created easily using Emacs\[aq] table-mode
4327(\f[C]M-x table-insert\f[R]).
4329Alignments can be specified as with pipe tables, by putting colons at
4330the boundaries of the separator line after the header:
4334+---------------+---------------+--------------------+
4335| Right | Left | Centered |
4336+==============:+:==============+:==================:+
4337| Bananas | $1.34 | built-in wrapper |
4338+---------------+---------------+--------------------+
4342For headerless tables, the colons go on the top line instead:
4346+--------------:+:--------------+:------------------:+
4347| Right | Left | Centered |
4348+---------------+---------------+--------------------+
4351.SS Grid Table Limitations
4353Pandoc does not support grid tables with row spans or column spans.
4354This means that neither variable numbers of columns across rows nor
4355variable numbers of rows across columns are supported by Pandoc.
4356All grid tables must have the same number of columns in each row, and
4357the same number of rows in each column.
4358For example, the Docutils sample grid tables will not render as expected
4360.SS Extension: \f[C]pipe_tables\f[R]
4362Pipe tables look like this:
4366| Right | Left | Default | Center |
4367|------:|:-----|---------|:------:|
4368| 12 | 12 | 12 | 12 |
4369| 123 | 123 | 123 | 123 |
4372 : Demonstration of pipe table syntax.
4376The syntax is identical to PHP Markdown Extra tables.
4377The beginning and ending pipe characters are optional, but pipes are
4378required between all columns.
4379The colons indicate column alignment as shown.
4380The header cannot be omitted.
4381To simulate a headerless table, include a header with blank cells.
4383Since the pipes indicate column boundaries, columns need not be
4384vertically aligned, as they are in the above example.
4385So, this is a perfectly legal (though ugly) pipe table:
4397The cells of pipe tables cannot contain block elements like paragraphs
4398and lists, and cannot span multiple lines.
4399If a pipe table contains a row whose printable content is wider than the
4400column width (see \f[C]--columns\f[R]), then the table will take up the
4401full text width and the cell contents will wrap, with the relative cell
4402widths determined by the number of dashes in the line separating the
4403table header from the table body.
4404(For example \f[C]---|-\f[R] would make the first column 3/4 and the
4405second column 1/4 of the full text width.) On the other hand, if no
4406lines are wider than column width, then cell contents will not be
4407wrapped, and the cells will be sized to their contents.
4409Note: pandoc also recognizes pipe tables of the following form, as can
4410be produced by Emacs\[aq] orgtbl-mode:
4421The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].
4422Other orgtbl features are not supported.
4423In particular, to get non-default column alignment, you\[aq]ll need to
4426.SS Extension: \f[C]pandoc_title_block\f[R]
4428If the file begins with a title block
4433% author(s) (separated by semicolons)
4438it will be parsed as bibliographic information, not regular text.
4439(It will be used, for example, in the title of standalone LaTeX or HTML
4440output.) The block may contain just a title, a title and an author, or
4442If you want to include an author but no title, or a title and a date but
4443no author, you need a blank line:
4456The title may occupy multiple lines, but continuation lines must begin
4457with leading space, thus:
4466If a document has multiple authors, the authors may be put on separate
4467lines with leading space, or separated by semicolons, or both.
4468So, all of the following are equivalent:
4475% Author One; Author Two
4482The date must fit on one line.
4484All three metadata fields may contain standard inline formatting
4485(italics, links, footnotes, etc.).
4487Title blocks will always be parsed, but they will affect the output only
4488when the \f[C]--standalone\f[R] (\f[C]-s\f[R]) option is chosen.
4489In HTML output, titles will appear twice: once in the document head --
4490this is the title that will appear at the top of the window in a browser
4491-- and once at the beginning of the document body.
4492The title in the document head can have an optional prefix attached
4493(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).
4494The title in the body appears as an H1 element with class
4495\[dq]title\[dq], so it can be suppressed or reformatted with CSS.
4496If a title prefix is specified with \f[C]-T\f[R] and no title block
4497appears in the document, the title prefix will be used by itself as the
4500The man page writer extracts a title, man page section number, and other
4501header and footer information from the title line.
4502The title is assumed to be the first word on the title line, which may
4503optionally end with a (single-digit) section number in parentheses.
4504(There should be no space between the title and the parentheses.)
4505Anything after this is assumed to be additional footer and header text.
4506A single pipe character (\f[C]|\f[R]) should be used to separate the
4507footer text from the header text.
4516will yield a man page with the title \f[C]PANDOC\f[R] and section 1.
4520% PANDOC(1) Pandoc User Manuals
4524will also have \[dq]Pandoc User Manuals\[dq] in the footer.
4528% PANDOC(1) Pandoc User Manuals | Version 4.0
4532will also have \[dq]Version 4.0\[dq] in the header.
4533.SS Extension: \f[C]yaml_metadata_block\f[R]
4535A YAML metadata block is a valid YAML object, delimited by a line of
4536three hyphens (\f[C]---\f[R]) at the top and a line of three hyphens
4537(\f[C]---\f[R]) or three dots (\f[C]...\f[R]) at the bottom.
4538A YAML metadata block may occur anywhere in the document, but if it is
4539not at the beginning, it must be preceded by a blank line.
4540(Note that, because of the way pandoc concatenates input files when
4541several are provided, you may also keep the metadata in a separate YAML
4542file and pass it to pandoc as an argument, along with your Markdown
4547pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
4551Just be sure that the YAML file begins with \f[C]---\f[R] and ends with
4552\f[C]---\f[R] or \f[C]...\f[R].) Alternatively, you can use the
4553\f[C]--metadata-file\f[R] option.
4554Using that approach however, you cannot reference content (like
4555footnotes) from the main markdown input document.
4557Metadata will be taken from the fields of the YAML object and added to
4558any existing document metadata.
4559Metadata can contain lists and objects (nested arbitrarily), but all
4560string scalars will be interpreted as Markdown.
4561Fields with names ending in an underscore will be ignored by pandoc.
4562(They may be given a role by external processors.) Field names must not
4563be interpretable as YAML numbers or boolean values (so, for example,
4564\f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot be used as field
4567A document may contain multiple metadata blocks.
4568If two metadata blocks attempt to set the same field, the value from the
4569second block will be taken.
4571When pandoc is used with \f[C]-t markdown\f[R] to create a Markdown
4572document, a YAML metadata block will be produced only if the
4573\f[C]-s/--standalone\f[R] option is used.
4574All of the metadata will appear in a single block at the beginning of
4577Note that YAML escaping rules must be followed.
4578Thus, for example, if a title contains a colon, it must be quoted.
4579The pipe character (\f[C]|\f[R]) can be used to begin an indented block
4580that will be interpreted literally, without need for escaping.
4581This form is necessary when the field contains blank lines or
4582block-level formatting:
4587title: \[aq]This is the title: it contains a colon\[aq]
4591keywords: [nothing, nothingness]
4593 This is the abstract.
4595 It consists of two paragraphs.
4600Template variables will be set automatically from the metadata.
4601Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will
4602be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]
4607<p>This is the abstract.</p>
4608<p>It consists of two paragraphs.</p>
4612Variables can contain arbitrary YAML structures, but the template must
4613match this structure.
4614The \f[C]author\f[R] variable in the default templates expects a simple
4615list or string, but can be changed to support more complicated
4617The following combination, for example, would add an affiliation to the
4618author if one is given:
4623title: The document title
4626 affiliation: University of Somewhere
4628 affiliation: University of Nowhere
4633To use the structured authors in the example above, you would need a
4640$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
4648Raw content to include in the document\[aq]s header may be specified
4649using \f[C]header-includes\f[R]; however, it is important to mark up
4650this content as raw code for a particular output format, using the
4651\f[C]raw_attribute\f[R] extension), or it will be interpreted as
4659 \[ga]\[ga]\[ga]{=latex}
4660 \[rs]let\[rs]oldsection\[rs]section
4661 \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}}
4665.SS Backslash escapes
4666.SS Extension: \f[C]all_symbols_escapable\f[R]
4668Except inside a code block or inline code, any punctuation or space
4669character preceded by a backslash will be treated literally, even if it
4670would normally indicate formatting.
4671Thus, for example, if one writes
4691<strong>hello</strong>
4695This rule is easier to remember than standard Markdown\[aq]s rule, which
4696allows only the following characters to be backslash-escaped:
4700\[rs]\[ga]*_{}[]()>#+-.!
4704(However, if the \f[C]markdown_strict\f[R] format is used, the standard
4705Markdown rule will be used.)
4707A backslash-escaped space is parsed as a nonbreaking space.
4708It will appear in TeX output as \f[C]\[ti]\f[R] and in HTML and XML as
4709\f[C]\[rs] \f[R] or \f[C]\[rs] \f[R].
4711A backslash-escaped newline (i.e.
4712a backslash occurring at the end of a line) is parsed as a hard line
4714It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as
4716This is a nice alternative to Markdown\[aq]s \[dq]invisible\[dq] way of
4717indicating hard line breaks using two trailing spaces on a line.
4719Backslash escapes do not work in verbatim contexts.
4720.SS Inline formatting
4723To \f[I]emphasize\f[R] some text, surround it with \f[C]*\f[R]s or
4724\f[C]_\f[R], like this:
4728This text is _emphasized with underscores_, and this
4729is *emphasized with asterisks*.
4733Double \f[C]*\f[R] or \f[C]_\f[R] produces \f[B]strong emphasis\f[R]:
4737This is **strong emphasis** and __with underscores__.
4741A \f[C]*\f[R] or \f[C]_\f[R] character surrounded by spaces, or
4742backslash-escaped, will not trigger emphasis:
4746This is * not emphasized *, and \[rs]*neither is this\[rs]*.
4749.SS Extension: \f[C]intraword_underscores\f[R]
4751Because \f[C]_\f[R] is sometimes used inside words and identifiers,
4752pandoc does not interpret a \f[C]_\f[R] surrounded by alphanumeric
4753characters as an emphasis marker.
4754If you want to emphasize just part of a word, use \f[C]*\f[R]:
4758feas*ible*, not feas*able*.
4762.SS Extension: \f[C]strikeout\f[R]
4764To strikeout a section of text with a horizontal line, begin and end it
4765with \f[C]\[ti]\[ti]\f[R].
4770This \[ti]\[ti]is deleted text.\[ti]\[ti]
4773.SS Superscripts and subscripts
4774.SS Extension: \f[C]superscript\f[R], \f[C]subscript\f[R]
4776Superscripts may be written by surrounding the superscripted text by
4777\f[C]\[ha]\f[R] characters; subscripts may be written by surrounding the
4778subscripted text by \f[C]\[ti]\f[R] characters.
4783H\[ti]2\[ti]O is a liquid. 2\[ha]10\[ha] is 1024.
4787The text between \f[C]\[ha]...\[ha]\f[R] or \f[C]\[ti]...\[ti]\f[R] may
4788not contain spaces or newlines.
4789If the superscripted or subscripted text contains spaces, these spaces
4790must be escaped with backslashes.
4791(This is to prevent accidental superscripting and subscripting through
4792the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad
4793interactions with footnotes.) Thus, if you want the letter P with \[aq]a
4794cat\[aq] in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
4795\f[C]P\[ti]a cat\[ti]\f[R].
4798To make a short span of text verbatim, put it inside backticks:
4802What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]?
4806If the verbatim text includes a backtick, use double backticks:
4810Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga].
4814(The spaces after the opening backticks and before the closing backticks
4817The general rule is that a verbatim span starts with a string of
4818consecutive backticks (optionally followed by a space) and ends with a
4819string of the same number of backticks (optionally preceded by a space).
4821Note that backslash-escapes (and other Markdown constructs) do not work
4822in verbatim contexts:
4826This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga].
4829.SS Extension: \f[C]inline_code_attributes\f[R]
4831Attributes can be attached to verbatim text, just as with fenced code
4836\[ga]<$>\[ga]{.haskell}
4841To write small caps, use the \f[C]smallcaps\f[R] class:
4845[Small caps]{.smallcaps}
4849Or, without the \f[C]bracketed_spans\f[R] extension:
4853<span class=\[dq]smallcaps\[dq]>Small caps</span>
4857For compatibility with other Markdown flavors, CSS is also supported:
4861<span style=\[dq]font-variant:small-caps;\[dq]>Small caps</span>
4865This will work in all output formats that support small caps.
4867.SS Extension: \f[C]tex_math_dollars\f[R]
4869Anything between two \f[C]$\f[R] characters will be treated as TeX math.
4870The opening \f[C]$\f[R] must have a non-space character immediately to
4871its right, while the closing \f[C]$\f[R] must have a non-space character
4872immediately to its left, and must not be followed immediately by a
4874Thus, \f[C]$20,000 and $30,000\f[R] won\[aq]t parse as math.
4875If for some reason you need to enclose text in literal \f[C]$\f[R]
4876characters, backslash-escape them and they won\[aq]t be treated as math
4879For display math, use \f[C]$$\f[R] delimiters.
4880(In this case, the delimiters may be separated from the formula by
4883TeX math will be printed in all output formats.
4884How it is rendered depends on the output format:
4887It will appear verbatim surrounded by \f[C]\[rs](...\[rs])\f[R] (for
4888inline math) or \f[C]\[rs][...\[rs]]\f[R] (for display math).
4890Markdown, Emacs Org mode, ConTeXt, ZimWiki
4891It will appear verbatim surrounded by \f[C]$...$\f[R] (for inline math)
4892or \f[C]$$...$$\f[R] (for display math).
4895It will appear verbatim surrounded by
4896\f[C]{{formula}}..{{/formula}}\f[R].
4899It will be rendered using an interpreted text role \f[C]:math:\f[R].
4902For AsciiDoc output format (\f[C]-t asciidoc\f[R]) it will appear
4903verbatim surrounded by \f[C]latexmath:[$...$]\f[R] (for inline math) or
4904\f[C][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math).
4905For AsciiDoctor output format (\f[C]-t asciidoctor\f[R]) the LaTex
4906delimiters (\f[C]$..$\f[R] and \f[C]\[rs][..\[rs]]\f[R]) are omitted.
4909It will be rendered inside a \f[C]\[at]math\f[R] command.
4911roff man, Jira markup
4912It will be rendered verbatim without \f[C]$\f[R]\[aq]s.
4915It will be rendered inside \f[C]<math>\f[R] tags.
4918It will be rendered inside \f[C]<span class=\[dq]math\[dq]>\f[R] tags.
4921It will be rendered, if possible, using Unicode characters, and will
4922otherwise appear verbatim.
4925It will be rendered, if possible, using MathML.
4928If the \f[C]--mathml\f[R] flag is used, it will be rendered using MathML
4929in an \f[C]inlineequation\f[R] or \f[C]informalequation\f[R] tag.
4930Otherwise it will be rendered, if possible, using Unicode characters.
4933It will be rendered using OMML math markup.
4936If the \f[C]--webtex\f[R] option is used, formulas are rendered as
4937images using CodeCogs or other compatible web service, downloaded and
4938embedded in the e-book.
4939Otherwise, they will appear verbatim.
4941HTML, Slidy, DZSlides, S5, EPUB
4942The way math is rendered in HTML will depend on the command-line options
4944Therefore see Math rendering in HTML above.
4946.SS Extension: \f[C]raw_html\f[R]
4948Markdown allows you to insert raw HTML (or DocBook) anywhere in a
4949document (except verbatim contexts, where \f[C]<\f[R], \f[C]>\f[R], and
4950\f[C]&\f[R] are interpreted literally).
4951(Technically this is not an extension, since standard Markdown allows
4952it, but it has been made an extension so that it can be disabled if
4955The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
4956DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile
4957output, and suppressed in other formats.
4959For a more explicit way of including raw HTML in a Markdown document,
4960see the \f[C]raw_attribute\f[R] extension.
4962In the CommonMark format, if \f[C]raw_html\f[R] is enabled,
4963superscripts, subscripts, strikeouts and small capitals will be
4965Otherwise, plain-text fallbacks will be used.
4966Note that even if \f[C]raw_html\f[R] is disabled, tables will be
4967rendered with HTML syntax if they cannot use pipe syntax.
4968.SS Extension: \f[C]markdown_in_html_blocks\f[R]
4970Standard Markdown allows you to include HTML \[dq]blocks\[dq]: blocks of
4971HTML between balanced tags that are separated from the surrounding text
4972with blank lines, and start and end at the left margin.
4973Within these blocks, everything is interpreted as HTML, not Markdown; so
4974(for example), \f[C]*\f[R] does not signify emphasis.
4976Pandoc behaves this way when the \f[C]markdown_strict\f[R] format is
4977used; but by default, pandoc interprets material between HTML block tags
4979Thus, for example, pandoc will turn
4986<td>[a link](http://google.com)</td>
4998<td><em>one</em></td>
4999<td><a href=\[dq]http://google.com\[dq]>a link</a></td>
5005whereas \f[C]Markdown.pl\f[R] will preserve it as is.
5007There is one exception to this rule: text between \f[C]<script>\f[R] and
5008\f[C]<style>\f[R] tags is not interpreted as Markdown.
5010This departure from standard Markdown should make it easier to mix
5011Markdown with HTML block elements.
5012For example, one can surround a block of Markdown text with
5013\f[C]<div>\f[R] tags without preventing it from being interpreted as
5015.SS Extension: \f[C]native_divs\f[R]
5017Use native pandoc \f[C]Div\f[R] blocks for content inside
5018\f[C]<div>\f[R] tags.
5019For the most part this should give the same output as
5020\f[C]markdown_in_html_blocks\f[R], but it makes it easier to write
5021pandoc filters to manipulate groups of blocks.
5022.SS Extension: \f[C]native_spans\f[R]
5024Use native pandoc \f[C]Span\f[R] blocks for content inside
5025\f[C]<span>\f[R] tags.
5026For the most part this should give the same output as
5027\f[C]raw_html\f[R], but it makes it easier to write pandoc filters to
5028manipulate groups of inlines.
5029.SS Extension: \f[C]raw_tex\f[R]
5031In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
5032included in a document.
5033Inline TeX commands will be preserved and passed unchanged to the LaTeX
5035Thus, for example, you can use LaTeX to include BibTeX citations:
5039This result was proved in \[rs]cite{jones.1967}.
5043Note that in LaTeX environments, like
5047\[rs]begin{tabular}{|l|l|}\[rs]hline
5048Age & Frequency \[rs]\[rs] \[rs]hline
504918--25 & 15 \[rs]\[rs]
505026--35 & 33 \[rs]\[rs]
505136--45 & 22 \[rs]\[rs] \[rs]hline
5056the material between the begin and end tags will be interpreted as raw
5057LaTeX, not as Markdown.
5059For a more explicit and flexible way of including raw TeX in a Markdown
5060document, see the \f[C]raw_attribute\f[R] extension.
5062Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
5063Emacs Org mode, and ConTeXt.
5064.SS Generic raw attribute
5065.SS Extension: \f[C]raw_attribute\f[R]
5067Inline spans and fenced code blocks with a special kind of attribute
5068will be parsed as raw content with the designated format.
5069For example, the following produces a raw roff \f[C]ms\f[R] block:
5080And the following produces a raw \f[C]html\f[R] inline element:
5084This is \[ga]<a>html</a>\[ga]{=html}
5088This can be useful to insert raw xml into \f[C]docx\f[R] documents, e.g.
5093\[ga]\[ga]\[ga]{=openxml}
5096 <w:br w:type=\[dq]page\[dq]/>
5103The format name should match the target format name (see
5104\f[C]-t/--to\f[R], above, for a list, or use
5105\f[C]pandoc --list-output-formats\f[R]).
5106Use \f[C]openxml\f[R] for \f[C]docx\f[R] output, \f[C]opendocument\f[R]
5107for \f[C]odt\f[R] output, \f[C]html5\f[R] for \f[C]epub3\f[R] output,
5108\f[C]html4\f[R] for \f[C]epub2\f[R] output, and \f[C]latex\f[R],
5109\f[C]beamer\f[R], \f[C]ms\f[R], or \f[C]html5\f[R] for \f[C]pdf\f[R]
5110output (depending on what you use for \f[C]--pdf-engine\f[R]).
5112This extension presupposes that the relevant kind of inline code or
5113fenced code block is enabled.
5114Thus, for example, to use a raw attribute with a backtick code block,
5115\f[C]backtick_code_blocks\f[R] must be enabled.
5117The raw attribute cannot be combined with regular attributes.
5119.SS Extension: \f[C]latex_macros\f[R]
5121When this extension is enabled, pandoc will parse LaTeX macro
5122definitions and apply the resulting macros to all LaTeX math and raw
5124So, for example, the following will work in all output formats, not just
5129\[rs]newcommand{\[rs]tuple}[1]{\[rs]langle #1 \[rs]rangle}
5131$\[rs]tuple{a, b, c}$
5135Note that LaTeX macros will not be applied if they occur inside a raw
5136span or block marked with the \f[C]raw_attribute\f[R] extension.
5138When \f[C]latex_macros\f[R] is disabled, the raw LaTeX and math will not
5140This is usually a better approach when you are targeting LaTeX or PDF.
5142Macro definitions in LaTeX will be passed through as raw LaTeX only if
5143\f[C]latex_macros\f[R] is not enabled.
5144Macro definitions in Markdown source (or other formats allowing
5145\f[C]raw_tex\f[R]) will be passed through regardless of whether
5146\f[C]latex_macros\f[R] is enabled.
5149Markdown allows links to be specified in several ways.
5152If you enclose a URL or email address in pointy brackets, it will become
5158<sam\[at]green.eggs.ham>
5163An inline link consists of the link text in square brackets, followed by
5164the URL in parentheses.
5165(Optionally, the URL can be followed by a link title, in quotes.)
5169This is an [inline link](/url), and here\[aq]s [one with
5170a title](http://fsf.org \[dq]click here for a good time!\[dq]).
5174There can be no space between the bracketed part and the parenthesized
5176The link text can contain formatting (such as emphasis), but the title
5179Email addresses in inline links are not autodetected, so they have to be
5180prefixed with \f[C]mailto\f[R]:
5184[Write me!](mailto:sam\[at]green.eggs.ham)
5189An \f[I]explicit\f[R] reference link has two parts, the link itself and
5190the link definition, which may occur elsewhere in the document (either
5191before or after the link).
5193The link consists of link text in square brackets, followed by a label
5195(There cannot be space between the two unless the
5196\f[C]spaced_reference_links\f[R] extension is enabled.) The link
5197definition consists of the bracketed label, followed by a colon and a
5198space, followed by the URL, and optionally (after a space) a link title
5199either in quotes or in parentheses.
5200The label must not be parseable as a citation (assuming the
5201\f[C]citations\f[R] extension is enabled): citations take precedence
5204Here are some examples:
5208[my label 1]: /foo/bar.html \[dq]My title, optional\[dq]
5210[my label 3]: http://fsf.org (The free software foundation)
5211[my label 4]: /bar#special \[aq]A title in single quotes\[aq]
5215The URL may optionally be surrounded by angle brackets:
5219[my label 5]: <http://foo.bar.baz>
5223The title may go on the next line:
5227[my label 3]: http://fsf.org
5228 \[dq]The free software foundation\[dq]
5232Note that link labels are not case sensitive.
5237Here is [my link][FOO]
5243In an \f[I]implicit\f[R] reference link, the second pair of brackets is
5250[my website]: http://foo.bar.baz
5254Note: In \f[C]Markdown.pl\f[R] and most other Markdown implementations,
5255reference link definitions cannot occur in nested constructions such as
5256list items or block quotes.
5257Pandoc lifts this arbitrary seeming restriction.
5258So the following is fine in pandoc, though not in most other
5268.SS Extension: \f[C]shortcut_reference_links\f[R]
5270In a \f[I]shortcut\f[R] reference link, the second pair of brackets may
5277[my website]: http://foo.bar.baz
5282To link to another section of the same document, use the automatically
5283generated identifier (see Heading identifiers).
5288See the [Introduction](#introduction).
5296See the [Introduction].
5298[Introduction]: #introduction
5302Internal links are currently supported for HTML formats (including HTML
5303slide shows and EPUB), LaTeX, and ConTeXt.
5306A link immediately preceded by a \f[C]!\f[R] will be treated as an
5308The link text will be used as the image\[aq]s alt text:
5312
5316[movie reel]: movie.gif
5319.SS Extension: \f[C]implicit_figures\f[R]
5321An image with nonempty alt text, occurring by itself in a paragraph,
5322will be rendered as a figure with a caption.
5323The image\[aq]s alt text will be used as the caption.
5327
5331How this is rendered depends on the output format.
5332Some output formats (e.g.
5333RTF) do not yet support figures.
5334In those formats, you\[aq]ll just get an image in a paragraph by itself,
5337If you just want a regular inline image, just make sure it is not the
5338only thing in the paragraph.
5339One way to do this is to insert a nonbreaking space after the image:
5343![This image won\[aq]t be a figure](/url/of/image.png)\[rs]
5347Note that in reveal.js slide shows, an image in a paragraph by itself
5348that has the \f[C]stretch\f[R] class will fill the screen, and the
5349caption and figure tags will be omitted.
5350.SS Extension: \f[C]link_attributes\f[R]
5352Attributes can be set on links and images:
5356An inline {#id .class width=30 height=20px}
5357and a reference ![image][ref] with attributes.
5359[ref]: foo.jpg \[dq]optional title\[dq] {#id .class key=val key2=\[dq]val 2\[dq]}
5363(This syntax is compatible with PHP Markdown Extra when only
5364\f[C]#id\f[R] and \f[C].class\f[R] are used.)
5366For HTML and EPUB, all known HTML5 attributes except \f[C]width\f[R] and
5367\f[C]height\f[R] (but including \f[C]srcset\f[R] and \f[C]sizes\f[R])
5368are passed through as is.
5369Unknown attributes are passed through as custom attributes, with
5370\f[C]data-\f[R] prepended.
5371The other writers ignore attributes that are not specifically supported
5372by their output format.
5374The \f[C]width\f[R] and \f[C]height\f[R] attributes on images are
5376When used without a unit, the unit is assumed to be pixels.
5377However, any of the following unit identifiers can be used:
5378\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]
5380There must not be any spaces between the number and the unit.
5385{ width=50% }
5389Dimensions are converted to inches for output in page-based formats like
5391Dimensions are converted to pixels for output in HTML-like formats.
5392Use the \f[C]--dpi\f[R] option to specify the number of pixels per inch.
5393The default is 96dpi.
5395The \f[C]%\f[R] unit is generally relative to some available space.
5396For example the above example will render to the following.
5400\f[C]<img href=\[dq]file.jpg\[dq] style=\[dq]width: 50%;\[dq] />\f[R]
5403\f[C]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]
5404(If you\[aq]re using a custom template, you need to configure
5405\f[C]graphicx\f[R] as in the default template.)
5408\f[C]\[rs]externalfigure[file.jpg][width=0.5\[rs]textwidth]\f[R]
5411Some output formats have a notion of a class (ConTeXt) or a unique
5412identifier (LaTeX \f[C]\[rs]caption\f[R]), or both (HTML).
5414When no \f[C]width\f[R] or \f[C]height\f[R] attributes are specified,
5415the fallback is to look at the image resolution and the dpi metadata
5416embedded in the image file.
5419Using the \f[C]native_divs\f[R] and \f[C]native_spans\f[R] extensions
5420(see above), HTML syntax can be used as part of markdown to create
5421native \f[C]Div\f[R] and \f[C]Span\f[R] elements in the pandoc AST (as
5422opposed to raw HTML).
5423However, there is also nicer syntax available:
5424.SS Extension: \f[C]fenced_divs\f[R]
5426Allow special fenced syntax for native \f[C]Div\f[R] blocks.
5427A Div starts with a fence containing at least three consecutive colons
5428plus some attributes.
5429The attributes may optionally be followed by another string of
5431The attribute syntax is exactly as in fenced code blocks (see Extension:
5432\f[C]fenced_code_attributes\f[R]).
5433As with fenced code blocks, one can use either attributes in curly
5434braces or a single unbraced word, which will be treated as a class name.
5435The Div ends with another line containing a string of at least three
5437The fenced Div should be separated by blank lines from preceding and
5444::::: {#special .sidebar}
5452Fenced divs can be nested.
5453Opening fences are distinguished because they \f[I]must\f[R] have
5462This is a warning within a warning.
5468Fences without attributes are always closing fences.
5469Unlike with fenced code blocks, the number of colons in the closing
5470fence need not match the number in the opening fence.
5471However, it can be helpful for visual clarity to use fences of different
5472lengths to distinguish nested divs from their parents.
5473.SS Extension: \f[C]bracketed_spans\f[R]
5475A bracketed sequence of inlines, as one would use to begin a link, will
5476be treated as a \f[C]Span\f[R] with attributes if it is followed
5477immediately by attributes:
5481[This is *some text*]{.class key=\[dq]val\[dq]}
5485.SS Extension: \f[C]footnotes\f[R]
5487Pandoc\[aq]s Markdown allows footnotes, using the following syntax:
5491Here is a footnote reference,[\[ha]1] and another.[\[ha]longnote]
5493[\[ha]1]: Here is the footnote.
5495[\[ha]longnote]: Here\[aq]s one with multiple blocks.
5497 Subsequent paragraphs are indented to show that they
5498belong to the previous footnote.
5502 The whole paragraph can be indented, or just the first
5503 line. In this way, multi-paragraph footnotes work like
5504 multi-paragraph list items.
5506This paragraph won\[aq]t be part of the note, because it
5511The identifiers in footnote references may not contain spaces, tabs, or
5513These identifiers are used only to correlate the footnote reference with
5514the note itself; in the output, footnotes will be numbered sequentially.
5516The footnotes themselves need not be placed at the end of the document.
5517They may appear anywhere except inside other block elements (lists,
5518block quotes, tables, etc.).
5519Each footnote should be separated from surrounding content (including
5520other footnotes) by blank lines.
5521.SS Extension: \f[C]inline_notes\f[R]
5523Inline footnotes are also allowed (though, unlike regular notes, they
5524cannot contain multiple paragraphs).
5525The syntax is as follows:
5529Here is an inline note.\[ha][Inlines notes are easier to write, since
5530you don\[aq]t have to pick an identifier and move down to type the
5535Inline and regular footnotes may be mixed freely.
5537.SS Extension: \f[C]citations\f[R]
5539Using an external filter, \f[C]pandoc-citeproc\f[R], pandoc can
5540automatically generate citations and a bibliography in a number of
5546pandoc --filter pandoc-citeproc myinput.txt
5550In order to use this feature, you will need to specify a bibliography
5551file using the \f[C]bibliography\f[R] metadata field in a YAML metadata
5552section, or \f[C]--bibliography\f[R] command line argument.
5553You can supply multiple \f[C]--bibliography\f[R] arguments or set
5554\f[C]bibliography\f[R] metadata field to YAML array, if you want to use
5555multiple bibliography files.
5556The bibliography may have any of these formats:
5624Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX
5625files; use \f[C].bibtex\f[R] to force BibTeX.
5627Note that \f[C]pandoc-citeproc --bib2json\f[R] and
5628\f[C]pandoc-citeproc --bib2yaml\f[R] can produce \f[C].json\f[R] and
5629\f[C].yaml\f[R] files from any of the supported formats.
5631In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
5632parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown;
5633and in CSL JSON databases, an HTML-like markup:
5635\f[B]\f[CB]<i>...</i>\f[B]\f[R]
5638\f[B]\f[CB]<b>...</b>\f[B]\f[R]
5641\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]
5644\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]
5647\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]
5650\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]
5651prevent a phrase from being capitalized as title case
5653\f[C]pandoc-citeproc -j\f[R] and \f[C]-y\f[R] interconvert the CSL JSON
5654and CSL YAML formats as far as possible.
5656As an alternative to specifying a bibliography file using
5657\f[C]--bibliography\f[R] or the YAML metadata field
5658\f[C]bibliography\f[R], you can include the citation data directly in
5659the \f[C]references\f[R] field of the document\[aq]s YAML metadata.
5660The field should contain an array of YAML-encoded references, for
5667- type: article-journal
5679 title: \[aq]Molecular structure of nucleic acids: a structure for deoxyribose
5681 title-short: Molecular structure of nucleic acids
5682 container-title: Nature
5686 DOI: 10.1038/171737a0
5687 URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
5693(\f[C]pandoc-citeproc --bib2yaml\f[R] can produce these from a
5694bibliography file in one of the supported formats.)
5696Citations and references can be formatted using any style supported by
5697the Citation Style Language, listed in the Zotero Style Repository.
5698These files are specified using the \f[C]--csl\f[R] option or the
5699\f[C]csl\f[R] metadata field.
5700By default, \f[C]pandoc-citeproc\f[R] will use the Chicago Manual of
5701Style author-date format.
5702The CSL project provides further information on finding and editing
5705To make your citations hyperlinks to the corresponding bibliography
5706entries, add \f[C]link-citations: true\f[R] to your YAML metadata.
5708Citations go inside square brackets and are separated by semicolons.
5709Each citation must have a key, composed of \[aq]\[at]\[aq] + the
5710citation identifier from the database, and may optionally have a prefix,
5711a locator, and a suffix.
5712The citation key must begin with a letter, digit, or \f[C]_\f[R], and
5713may contain alphanumerics, \f[C]_\f[R], and internal punctuation
5714characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]).
5715Here are some examples:
5719Blah blah [see \[at]doe99, pp. 33-35; also \[at]smith04, chap. 1].
5721Blah blah [\[at]doe99, pp. 33-35, 38-39 and *passim*].
5723Blah blah [\[at]smith04; \[at]doe99].
5727\f[C]pandoc-citeproc\f[R] detects locator terms in the CSL locale files.
5728Either abbreviated or unabbreviated forms are accepted.
5729In the \f[C]en-US\f[R] locale, locator terms can be written in either
5730singular or plural forms, as \f[C]book\f[R],
5731\f[C]bk.\f[R]/\f[C]bks.\f[R]; \f[C]chapter\f[R],
5732\f[C]chap.\f[R]/\f[C]chaps.\f[R]; \f[C]column\f[R],
5733\f[C]col.\f[R]/\f[C]cols.\f[R]; \f[C]figure\f[R],
5734\f[C]fig.\f[R]/\f[C]figs.\f[R]; \f[C]folio\f[R],
5735\f[C]fol.\f[R]/\f[C]fols.\f[R]; \f[C]number\f[R],
5736\f[C]no.\f[R]/\f[C]nos.\f[R]; \f[C]line\f[R],
5737\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];
5738\f[C]opus\f[R], \f[C]op.\f[R]/\f[C]opp.\f[R]; \f[C]page\f[R],
5739\f[C]p.\f[R]/\f[C]pp.\f[R]; \f[C]paragraph\f[R],
5740\f[C]para.\f[R]/\f[C]paras.\f[R]; \f[C]part\f[R],
5741\f[C]pt.\f[R]/\f[C]pts.\f[R]; \f[C]section\f[R],
5742\f[C]sec.\f[R]/\f[C]secs.\f[R]; \f[C]sub verbo\f[R],
5743\f[C]s.v.\f[R]/\f[C]s.vv.\f[R]; \f[C]verse\f[R],
5744\f[C]v.\f[R]/\f[C]vv.\f[R]; \f[C]volume\f[R],
5745\f[C]vol.\f[R]/\f[C]vols.\f[R]; \f[C]\[ps]\f[R]/\f[C]\[ps]\[ps]\f[R];
5746\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
5747If no locator term is used, \[dq]page\[dq] is assumed.
5749\f[C]pandoc-citeproc\f[R] will use heuristics to distinguish the locator
5751In complex cases, the locator can be enclosed in curly braces (using
5752\f[C]pandoc-citeproc\f[R] 0.15 and higher only):
5756[\[at]smith{ii, A, D-Z}, with a suffix]
5757[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
5761A minus sign (\f[C]-\f[R]) before the \f[C]\[at]\f[R] will suppress
5762mention of the author in the citation.
5763This can be useful when the author is already mentioned in the text:
5767Smith says blah [-\[at]smith04].
5771You can also write an in-text citation, as follows:
5775\[at]smith04 says blah.
5777\[at]smith04 [p. 33] says blah.
5781If the style calls for a list of works cited, it will be placed in a div
5782with id \f[C]refs\f[R], if one exists:
5791Otherwise, it will be placed at the end of the document.
5792Generation of the bibliography can be suppressed by setting
5793\f[C]suppress-bibliography: true\f[R] in the YAML metadata.
5795If you wish the bibliography to have a section heading, you can set
5796\f[C]reference-section-title\f[R] in the metadata, or put the heading at
5797the beginning of the div with id \f[C]refs\f[R] (if you are using it) or
5798at the end of your document:
5808The bibliography will be inserted after this heading.
5809Note that the \f[C]unnumbered\f[R] class will be added to this heading,
5810so that the section will not be numbered.
5812If you want to include items in the bibliography without actually citing
5813them in the body text, you can define a dummy \f[C]nocite\f[R] metadata
5814field and put the citations there:
5820 \[at]item1, \[at]item2
5827In this example, the document will contain a citation for
5828\f[C]item3\f[R] only, but the bibliography will contain entries for
5829\f[C]item1\f[R], \f[C]item2\f[R], and \f[C]item3\f[R].
5831It is possible to create a bibliography with all the citations, whether
5832or not they appear in the document, by using a wildcard:
5843For LaTeX output, you can also use \f[C]natbib\f[R] or
5844\f[C]biblatex\f[R] to render the bibliography.
5845In order to do so, specify bibliography files as outlined above, and add
5846\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]
5848Bear in mind that bibliography files have to be in respective format
5849(either BibTeX or BibLaTeX).
5851For more information, see the pandoc-citeproc man page.
5852.SS Non-pandoc extensions
5854The following Markdown syntax extensions are not enabled by default in
5855pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
5856name, where \f[C]EXTENSION\f[R] is the name of the extension.
5857Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with
5859.SS Extension: \f[C]old_dashes\f[R]
5861Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
5862\f[C]-\f[R] before a numeral is an en-dash, and \f[C]--\f[R] is an
5864This option only has an effect if \f[C]smart\f[R] is enabled.
5865It is selected automatically for \f[C]textile\f[R] input.
5866.SS Extension: \f[C]angle_brackets_escapable\f[R]
5868Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can
5869be in GitHub flavored Markdown but not original Markdown.
5870This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[R].
5871.SS Extension: \f[C]lists_without_preceding_blankline\f[R]
5873Allow a list to occur right after a paragraph, with no intervening blank
5875.SS Extension: \f[C]four_space_rule\f[R]
5877Selects the pandoc <= 2.0 behavior for parsing lists, so that four
5878spaces indent are needed for list item continuation paragraphs.
5879.SS Extension: \f[C]spaced_reference_links\f[R]
5881Allow whitespace between the two components of a reference link, for
5889.SS Extension: \f[C]hard_line_breaks\f[R]
5891Causes all newlines within a paragraph to be interpreted as hard line
5892breaks instead of spaces.
5893.SS Extension: \f[C]ignore_line_breaks\f[R]
5895Causes newlines within a paragraph to be ignored, rather than being
5896treated as spaces or as hard line breaks.
5897This option is intended for use with East Asian languages where spaces
5898are not used between words, but text is divided into lines for
5900.SS Extension: \f[C]east_asian_line_breaks\f[R]
5902Causes newlines within a paragraph to be ignored, rather than being
5903treated as spaces or as hard line breaks, when they occur between two
5904East Asian wide characters.
5905This is a better choice than \f[C]ignore_line_breaks\f[R] for texts that
5906include a mix of East Asian wide characters and other characters.
5907.SS Extension: \f[C]emoji\f[R]
5909Parses textual emojis like \f[C]:smile:\f[R] as Unicode emoticons.
5910.SS Extension: \f[C]tex_math_single_backslash\f[R]
5912Causes anything between \f[C]\[rs](\f[R] and \f[C]\[rs])\f[R] to be
5913interpreted as inline TeX math, and anything between \f[C]\[rs][\f[R]
5914and \f[C]\[rs]]\f[R] to be interpreted as display TeX math.
5915Note: a drawback of this extension is that it precludes escaping
5916\f[C](\f[R] and \f[C][\f[R].
5917.SS Extension: \f[C]tex_math_double_backslash\f[R]
5919Causes anything between \f[C]\[rs]\[rs](\f[R] and \f[C]\[rs]\[rs])\f[R]
5920to be interpreted as inline TeX math, and anything between
5921\f[C]\[rs]\[rs][\f[R] and \f[C]\[rs]\[rs]]\f[R] to be interpreted as
5923.SS Extension: \f[C]markdown_attribute\f[R]
5925By default, pandoc interprets material inside block-level tags as
5927This extension changes the behavior so that Markdown is only parsed
5928inside block-level tags if the tags have the attribute
5929\f[C]markdown=1\f[R].
5930.SS Extension: \f[C]mmd_title_block\f[R]
5932Enables a MultiMarkdown style title block at the top of the document,
5939Date: September 1, 2008
5940Comment: This is a sample mmd title block, with
5941 a field spanning multiple lines.
5945See the MultiMarkdown documentation for details.
5946If \f[C]pandoc_title_block\f[R] or \f[C]yaml_metadata_block\f[R] is
5947enabled, it will take precedence over \f[C]mmd_title_block\f[R].
5948.SS Extension: \f[C]abbreviations\f[R]
5950Parses PHP Markdown Extra abbreviation keys, like
5954*[HTML]: Hypertext Markup Language
5958Note that the pandoc document model does not support abbreviations, so
5959if this extension is enabled, abbreviation keys are simply skipped (as
5960opposed to being parsed as paragraphs).
5961.SS Extension: \f[C]autolink_bare_uris\f[R]
5963Makes all absolute URIs into links, even when not surrounded by pointy
5964braces \f[C]<...>\f[R].
5965.SS Extension: \f[C]mmd_link_attributes\f[R]
5967Parses multimarkdown style key-value attributes on link and image
5969This extension should not be confused with the \f[C]link_attributes\f[R]
5974This is a reference ![image][ref] with multimarkdown attributes.
5976[ref]: http://path.to/image \[dq]Image title\[dq] width=20px height=30px
5977 id=myId class=\[dq]myClass1 myClass2\[dq]
5980.SS Extension: \f[C]mmd_header_identifiers\f[R]
5982Parses multimarkdown style heading identifiers (in square brackets,
5983after the heading but before any trailing \f[C]#\f[R]s in an ATX
5985.SS Extension: \f[C]compact_definition_lists\f[R]
5987Activates the definition list syntax of pandoc 1.12.x and earlier.
5988This syntax differs from the one described above under Definition lists
5991No blank line is required between consecutive items of the definition
5994To get a \[dq]tight\[dq] or \[dq]compact\[dq] list, omit space between
5995consecutive items; the space between a term and its definition does not
5998Lazy wrapping of paragraphs is not allowed: the entire definition must
5999be indented four spaces.
6000.SS Extension: \f[C]gutenberg\f[R]
6002Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
6003for strong emphasis, surround by underscores for regular emphasis, add
6004extra blank space around headings.
6005.SS Markdown variants
6007In addition to pandoc\[aq]s extended Markdown, the following Markdown
6008variants are supported:
6010\f[B]\f[CB]markdown_phpextra\f[B]\f[R] (PHP Markdown Extra)
6011\f[C]footnotes\f[R], \f[C]pipe_tables\f[R], \f[C]raw_html\f[R],
6012\f[C]markdown_attribute\f[R], \f[C]fenced_code_blocks\f[R],
6013\f[C]definition_lists\f[R], \f[C]intraword_underscores\f[R],
6014\f[C]header_attributes\f[R], \f[C]link_attributes\f[R],
6015\f[C]abbreviations\f[R], \f[C]shortcut_reference_links\f[R],
6016\f[C]spaced_reference_links\f[R].
6018\f[B]\f[CB]markdown_github\f[B]\f[R] (deprecated GitHub-Flavored Markdown)
6019\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
6020\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
6021\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
6022\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
6023\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
6024\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6025\f[C]lists_without_preceding_blankline\f[R].
6027\f[B]\f[CB]markdown_mmd\f[B]\f[R] (MultiMarkdown)
6028\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]markdown_attribute\f[R],
6029\f[C]mmd_link_attributes\f[R], \f[C]tex_math_double_backslash\f[R],
6030\f[C]intraword_underscores\f[R], \f[C]mmd_title_block\f[R],
6031\f[C]footnotes\f[R], \f[C]definition_lists\f[R],
6032\f[C]all_symbols_escapable\f[R], \f[C]implicit_header_references\f[R],
6033\f[C]auto_identifiers\f[R], \f[C]mmd_header_identifiers\f[R],
6034\f[C]shortcut_reference_links\f[R], \f[C]implicit_figures\f[R],
6035\f[C]superscript\f[R], \f[C]subscript\f[R],
6036\f[C]backtick_code_blocks\f[R], \f[C]spaced_reference_links\f[R],
6037\f[C]raw_attribute\f[R].
6039\f[B]\f[CB]markdown_strict\f[B]\f[R] (Markdown.pl)
6040\f[C]raw_html\f[R], \f[C]shortcut_reference_links\f[R],
6041\f[C]spaced_reference_links\f[R].
6043We also support \f[C]commonmark\f[R] and \f[C]gfm\f[R] (GitHub-Flavored
6044Markdown, which is implemented as a set of extensions on
6045\f[C]commonmark\f[R]).
6047Note, however, that \f[C]commonmark\f[R] and \f[C]gfm\f[R] have limited
6048support for extensions.
6049Only those listed below (and \f[C]smart\f[R], \f[C]raw_tex\f[R], and
6050\f[C]hard_line_breaks\f[R]) will work.
6051The extensions can, however, all be individually disabled.
6052Also, \f[C]raw_tex\f[R] only affects \f[C]gfm\f[R] output, not input.
6054\f[B]\f[CB]gfm\f[B]\f[R] (GitHub-Flavored Markdown)
6055\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
6056\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
6057\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
6058\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
6059\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
6060\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6061\f[C]lists_without_preceding_blankline\f[R].
6062.SH PRODUCING SLIDE SHOWS WITH PANDOC
6064You can use pandoc to produce an HTML + JavaScript slide presentation
6065that can be viewed via a web browser.
6066There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or
6068You can also produce a PDF slide show using LaTeX \f[C]beamer\f[R], or
6069slides shows in Microsoft PowerPoint format.
6071Here\[aq]s the Markdown source for a simple slide show,
6072\f[C]habits.txt\f[R]:
6101
6110To produce an HTML/JavaScript slide show, simply type
6114pandoc -t FORMAT -s habits.txt -o habits.html
6118where \f[C]FORMAT\f[R] is either \f[C]s5\f[R], \f[C]slidy\f[R],
6119\f[C]slideous\f[R], \f[C]dzslides\f[R], or \f[C]revealjs\f[R].
6121For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with
6122the \f[C]-s/--standalone\f[R] option embeds a link to JavaScript and CSS
6123files, which are assumed to be available at the relative path
6124\f[C]s5/default\f[R] (for S5), \f[C]slideous\f[R] (for Slideous),
6125\f[C]reveal.js\f[R] (for reveal.js), or at the Slidy website at
6126\f[C]w3.org\f[R] (for Slidy).
6127(These paths can be changed by setting the \f[C]slidy-url\f[R],
6128\f[C]slideous-url\f[R], \f[C]revealjs-url\f[R], or \f[C]s5-url\f[R]
6129variables; see Variables for HTML slides, above.) For DZSlides, the
6130(relatively short) JavaScript and CSS are included in the file by
6133With all HTML slide formats, the \f[C]--self-contained\f[R] option can
6134be used to produce a single file that contains all of the data necessary
6135to display the slide show, including linked scripts, stylesheets,
6138To produce a PDF slide show using beamer, type
6142pandoc -t beamer habits.txt -o habits.pdf
6146Note that a reveal.js slide show can also be converted to a PDF by
6147printing it to a file from the browser.
6149To produce a Powerpoint slide show, type
6153pandoc habits.txt -o habits.pptx
6156.SS Structuring the slide show
6158By default, the \f[I]slide level\f[R] is the highest heading level in
6159the hierarchy that is followed immediately by content, and not another
6160heading, somewhere in the document.
6161In the example above, level-1 headings are always followed by level-2
6162headings, which are followed by content, so the slide level is 2.
6163This default can be overridden using the \f[C]--slide-level\f[R] option.
6165The document is carved up into slides according to the following rules:
6167A horizontal rule always starts a new slide.
6169A heading at the slide level always starts a new slide.
6171Headings \f[I]below\f[R] the slide level in the hierarchy create
6172headings \f[I]within\f[R] a slide.
6174Headings \f[I]above\f[R] the slide level in the hierarchy create
6175\[dq]title slides,\[dq] which just contain the section title and help to
6176break the slide show into sections.
6177Non-slide content under these headings will be included on the title
6178slide (for HTML slide shows) or in a subsequent slide with the same
6181A title page is constructed automatically from the document\[aq]s title
6183(In the case of beamer, this can be disabled by commenting out some
6184lines in the default template.)
6186These rules are designed to support many different styles of slide show.
6187If you don\[aq]t care about structuring your slides into sections and
6188subsections, you can just use level-1 headings for all each slide.
6189(In that case, level-1 will be the slide level.) But you can also
6190structure the slide show into sections, as in the example above.
6192Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
6193layout will be produced, with level-1 headings building horizontally and
6194level-2 headings building vertically.
6195It is not recommended that you use deeper nesting of section levels with
6197.SS Incremental lists
6199By default, these writers produce lists that display \[dq]all at
6200once.\[dq] If you want your lists to display incrementally (one item at
6201a time), use the \f[C]-i\f[R] option.
6202If you want a particular list to depart from the default, put it in a
6203\f[C]div\f[R] block with class \f[C]incremental\f[R] or
6204\f[C]nonincremental\f[R].
6205So, for example, using the \f[C]fenced div\f[R] syntax, the following
6206would be incremental regardless of the document default:
6232While using \f[C]incremental\f[R] and \f[C]nonincremental\f[R] divs are
6233the recommended method of setting incremental lists on a per-case basis,
6234an older method is also supported: putting lists inside a blockquote
6235will depart from the document default (that is, it will display
6236incrementally without the \f[C]-i\f[R] option and all at once with the
6237\f[C]-i\f[R] option):
6246Both methods allow incremental and nonincremental lists to be mixed in a
6249Note: Neither the \f[C]-i/--incremental\f[R] option nor any of the
6250methods described here currently works for PowerPoint output.
6253You can add \[dq]pauses\[dq] within a slide by including a paragraph
6254containing three dots, separated by spaces:
6260content before the pause
6264content after the pause
6268Note: this feature is not yet implemented for PowerPoint output.
6269.SS Styling the slides
6271You can change the style of HTML slides by putting customized CSS files
6272in \f[C]$DATADIR/s5/default\f[R] (for S5), \f[C]$DATADIR/slidy\f[R] (for
6273Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where
6274\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
6276The originals may be found in pandoc\[aq]s system data directory
6277(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).
6278Pandoc will look there for any files it does not find in the user data
6281For dzslides, the CSS is included in the HTML file itself, and may be
6284All reveal.js configuration options can be set through variables.
6285For example, themes can be used by setting the \f[C]theme\f[R] variable:
6293Or you can specify a custom stylesheet using the \f[C]--css\f[R] option.
6295To style beamer slides, you can specify a \f[C]theme\f[R],
6296\f[C]colortheme\f[R], \f[C]fonttheme\f[R], \f[C]innertheme\f[R], and
6297\f[C]outertheme\f[R], using the \f[C]-V\f[R] option:
6301pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
6305Note that heading attributes will turn into slide attributes (on a
6306\f[C]<div>\f[R] or \f[C]<section>\f[R]) in HTML slide formats, allowing
6307you to style individual slides.
6308In beamer, the only heading attribute that affects slides is the
6309\f[C]allowframebreaks\f[R] class, which sets the
6310\f[C]allowframebreaks\f[R] option, causing multiple slides to be created
6311if the content overfills the frame.
6312This is recommended especially for bibliographies:
6316# References {.allowframebreaks}
6321Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
6322You can add notes to your Markdown document thus:
6330- It can contain Markdown
6337To show the notes window in reveal.js, press \f[C]s\f[R] while viewing
6339Speaker notes in PowerPoint will be available, as usual, in handouts and
6342Notes are not yet supported for other slide formats, but the notes will
6343not appear on the slides themselves.
6346To put material in side by side columns, you can use a native div
6347container with class \f[C]columns\f[R], containing two or more div
6348containers with class \f[C]column\f[R] and a \f[C]width\f[R] attribute:
6352:::::::::::::: {.columns}
6353::: {.column width=\[dq]40%\[dq]}
6356::: {.column width=\[dq]60%\[dq]}
6362.SS Frame attributes in beamer
6364Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[R] option to
6365a frame in beamer (for example, when using the \f[C]minted\f[R]
6367This can be forced by adding the \f[C]fragile\f[R] class to the heading
6368introducing the slide:
6372# Fragile slide {.fragile}
6376All of the other frame attributes described in Section 8.1 of the Beamer
6377User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
6378\f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],
6379\f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],
6380\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
6381.SS Background in reveal.js and beamer
6383Background images can be added to self-contained reveal.js slideshows
6384and to beamer slideshows.
6386For the same image on every slide, use the configuration option
6387\f[C]background-image\f[R] either in the YAML metadata block or as a
6388command-line variable.
6389(There are no other options in beamer and the rest of this section
6390concerns reveal.js slideshows.)
6392For reveal.js, you can instead use the reveal.js-native option
6393\f[C]parallaxBackgroundImage\f[R].
6394You can also set \f[C]parallaxBackgroundHorizontal\f[R] and
6395\f[C]parallaxBackgroundVertical\f[R] the same way and must also set
6396\f[C]parallaxBackgroundSize\f[R] to have your values take effect.
6398To set an image for a particular reveal.js slide, add
6399\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
6400slide-level heading on the slide (which may even be empty).
6402In reveal.js\[aq]s overview mode, the parallaxBackgroundImage will show
6403up only on the first slide.
6405Other reveal.js background settings also work on individual slides,
6406including \f[C]data-background-size\f[R],
6407\f[C]data-background-repeat\f[R], \f[C]data-background-color\f[R],
6408\f[C]data-transition\f[R], and \f[C]data-transition-speed\f[R].
6410To add a background image to the automatically generated title slide,
6411use the \f[C]title-slide-attributes\f[R] variable in the YAML metadata
6413It must contain a map of attribute names and values.
6415See the reveal.js documentation for more details.
6417For example in reveal.js:
6423parallaxBackgroundImage: /path/to/my/background_image.png
6424title-slide-attributes:
6425 data-background-image: /path/to/title_image.png
6426 data-background-size: contain
6431Slide 1 has background_image.png as its background.
6433## {data-background-image=\[dq]/path/to/special_image.jpg\[dq]}
6435Slide 2 has a special image for its background, even though the heading has no content.
6438.SH CREATING EPUBS WITH PANDOC
6441EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]
6442option, but if the source document is Markdown, it is better to use a
6453 text: An investigation of metadata
6461 text: doi:10.234234.234/33
6463rights: \[co] 2007 John Smith, CC BY-NC
6470The following fields are recognized:
6472\f[B]\f[CB]identifier\f[B]\f[R]
6473Either a string value or an object with fields \f[C]text\f[R] and
6475Valid values for \f[C]scheme\f[R] are \f[C]ISBN-10\f[R],
6476\f[C]GTIN-13\f[R], \f[C]UPC\f[R], \f[C]ISMN-10\f[R], \f[C]DOI\f[R],
6477\f[C]LCCN\f[R], \f[C]GTIN-14\f[R], \f[C]ISBN-13\f[R],
6478\f[C]Legal deposit number\f[R], \f[C]URN\f[R], \f[C]OCLC\f[R],
6479\f[C]ISMN-13\f[R], \f[C]ISBN-A\f[R], \f[C]JP\f[R], \f[C]OLCC\f[R].
6481\f[B]\f[CB]title\f[B]\f[R]
6482Either a string value, or an object with fields \f[C]file-as\f[R] and
6483\f[C]type\f[R], or a list of such objects.
6484Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],
6485\f[C]short\f[R], \f[C]collection\f[R], \f[C]edition\f[R],
6488\f[B]\f[CB]creator\f[B]\f[R]
6489Either a string value, or an object with fields \f[C]role\f[R],
6490\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.
6491Valid values for \f[C]role\f[R] are MARC relators, but pandoc will
6492attempt to translate the human-readable versions (like \[dq]author\[dq]
6493and \[dq]editor\[dq]) to the appropriate marc relators.
6495\f[B]\f[CB]contributor\f[B]\f[R]
6496Same format as \f[C]creator\f[R].
6498\f[B]\f[CB]date\f[B]\f[R]
6499A string value in \f[C]YYYY-MM-DD\f[R] format.
6500(Only the year is necessary.) Pandoc will attempt to convert other
6503\f[B]\f[CB]lang\f[B]\f[R] (or legacy: \f[B]\f[CB]language\f[B]\f[R])
6504A string value in BCP 47 format.
6505Pandoc will default to the local language if nothing is specified.
6507\f[B]\f[CB]subject\f[B]\f[R]
6508A string value or a list of such values.
6510\f[B]\f[CB]description\f[B]\f[R]
6513\f[B]\f[CB]type\f[B]\f[R]
6516\f[B]\f[CB]format\f[B]\f[R]
6519\f[B]\f[CB]relation\f[B]\f[R]
6522\f[B]\f[CB]coverage\f[B]\f[R]
6525\f[B]\f[CB]rights\f[B]\f[R]
6528\f[B]\f[CB]cover-image\f[B]\f[R]
6529A string value (path to cover image).
6531\f[B]\f[CB]css\f[B]\f[R] (or legacy: \f[B]\f[CB]stylesheet\f[B]\f[R])
6532A string value (path to CSS stylesheet).
6534\f[B]\f[CB]page-progression-direction\f[B]\f[R]
6535Either \f[C]ltr\f[R] or \f[C]rtl\f[R].
6536Specifies the \f[C]page-progression-direction\f[R] attribute for the
6537\f[C]spine\f[R] element.
6539\f[B]\f[CB]ibooks\f[B]\f[R]
6540iBooks-specific metadata, with the following fields:
6543\f[C]version\f[R]: (string)
6545\f[C]specified-fonts\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
6548\f[C]ipad-orientation-lock\f[R]:
6549\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
6551\f[C]iphone-orientation-lock\f[R]:
6552\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
6554\f[C]binding\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
6557\f[C]scroll-axis\f[R]:
6558\f[C]vertical\f[R]|\f[C]horizontal\f[R]|\f[C]default\f[R]
6560.SS The \f[C]epub:type\f[R] attribute
6562For \f[C]epub3\f[R] output, you can mark up the heading that corresponds
6563to an EPUB chapter using the \f[C]epub:type\f[R] attribute.
6564For example, to set the attribute to the value \f[C]prologue\f[R], use
6569# My chapter {epub:type=prologue}
6573Which will result in:
6577<body epub:type=\[dq]frontmatter\[dq]>
6578 <section epub:type=\[dq]prologue\[dq]>
6583Pandoc will output \f[C]<body epub:type=\[dq]bodymatter\[dq]>\f[R],
6584unless you use one of the following values, in which case either
6585\f[C]frontmatter\f[R] or \f[C]backmatter\f[R] will be output.
6591\f[C]epub:type\f[R] of first section
6593\f[C]epub:type\f[R] of body
6714By default, pandoc will download media referenced from any
6715\f[C]<img>\f[R], \f[C]<audio>\f[R], \f[C]<video>\f[R] or
6716\f[C]<source>\f[R] element present in the generated EPUB, and include it
6717in the EPUB container, yielding a completely self-contained EPUB.
6718If you want to link to external media resources instead, use raw HTML in
6719your source and add \f[C]data-external=\[dq]1\[dq]\f[R] to the tag with
6720the \f[C]src\f[R] attribute.
6725<audio controls=\[dq]1\[dq]>
6726 <source src=\[dq]http://example.com/music/toccata.mp3\[dq]
6727 data-external=\[dq]1\[dq] type=\[dq]audio/mpeg\[dq]>
6732.SH CREATING JUPYTER NOTEBOOKS WITH PANDOC
6734When creating a Jupyter notebook, pandoc will try to infer the notebook
6736Code blocks with the class \f[C]code\f[R] will be taken as code cells,
6737and intervening content will be taken as Markdown cells.
6738Attachments will automatically be created for images in Markdown cells.
6739Metadata will be taken from the \f[C]jupyter\f[R] metadata field.
6750 display_name: Python 2
6757 file_extension: \[dq].py\[dq]
6758 mimetype: \[dq]text/x-python\[dq]
6759 name: \[dq]python\[dq]
6760 nbconvert_exporter: \[dq]python\[dq]
6761 pygments_lexer: \[dq]ipython2\[dq]
6762 version: \[dq]2.7.15\[dq]
6767**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6768bibendum felis dictum sodales.
6771print(\[dq]hello\[dq])
6777from IPython.display import HTML
6780console.log(\[dq]hello\[dq]);
6788This image  will be
6789included as a cell attachment.
6793If you want to add cell attributes, group cells differently, or add
6794output to code cells, then you need to include divs to indicate the
6796You can use either fenced divs or native divs for this.
6801:::::: {.cell .markdown}
6804**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6805bibendum felis dictum sodales.
6808:::::: {.cell .code execution_count=1}
6809\[ga]\[ga]\[ga] {.python}
6810print(\[dq]hello\[dq])
6813::: {.output .stream .stdout}
6820:::::: {.cell .code execution_count=2}
6821\[ga]\[ga]\[ga] {.python}
6822from IPython.display import HTML
6825console.log(\[dq]hello\[dq]);
6831::: {.output .execute_result execution_count=2}
6832\[ga]\[ga]\[ga]{=html}
6834console.log(\[dq]hello\[dq]);
6844If you include raw HTML or TeX in an output cell, use the [raw
6845attribute][Extension: \f[C]fenced_attribute\f[R]], as shown in the last
6846cell of the example above.
6847Although pandoc can process \[dq]bare\[dq] raw HTML and TeX, the result
6848is often interspersed raw elements and normal textual elements, and in
6849an output cell pandoc expects a single, connected raw block.
6850To avoid using raw HTML or TeX except when marked explicitly using raw
6851attributes, we recommend specifying the extensions
6852\f[C]-raw_html-raw_tex+raw_attribute\f[R] when translating between
6853Markdown and ipynb notebooks.
6855Note that options and extensions that affect reading and writing of
6856Markdown will also affect Markdown cells in ipynb notebooks.
6857For example, \f[C]--wrap=preserve\f[R] will preserve soft line breaks in
6858Markdown cells; \f[C]--atx-headers\f[R] will cause ATX-style headings to
6859be used; and \f[C]--preserve-tabs\f[R] will prevent tabs from being
6861.SH SYNTAX HIGHLIGHTING
6863Pandoc will automatically highlight syntax in fenced code blocks that
6864are marked with a language name.
6865The Haskell library skylighting is used for highlighting.
6866Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and
6868To see a list of language names that pandoc will recognize, type
6869\f[C]pandoc --list-highlight-languages\f[R].
6871The color scheme can be selected using the \f[C]--highlight-style\f[R]
6873The default color scheme is \f[C]pygments\f[R], which imitates the
6874default color scheme used by the Python library pygments (though
6875pygments is not actually used to do the highlighting).
6876To see a list of highlight styles, type
6877\f[C]pandoc --list-highlight-styles\f[R].
6879If you are not satisfied with the predefined styles, you can use
6880\f[C]--print-highlight-style\f[R] to generate a JSON \f[C].theme\f[R]
6881file which can be modified and used as the argument to
6882\f[C]--highlight-style\f[R].
6883To get a JSON version of the \f[C]pygments\f[R] style, for example:
6887pandoc --print-highlight-style pygments > my.theme
6891Then edit \f[C]my.theme\f[R] and use it like this:
6895pandoc --highlight-style my.theme
6899If you are not satisfied with the built-in highlighting, or you want
6900highlight a language that isn\[aq]t supported, you can use the
6901\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax
6903Before writing your own, have a look at KDE\[aq]s repository of syntax
6906To disable highlighting, use the \f[C]--no-highlight\f[R] option.
6909Custom styles can be used in the docx and ICML formats.
6912By default, pandoc\[aq]s docx and ICML output applies a predefined set
6913of styles for blocks such as paragraphs and block quotes, and uses
6914largely default formatting (italics, bold) for inlines.
6915This will work for most purposes, especially alongside a
6916\f[C]reference.docx\f[R] file.
6917However, if you need to apply your own styles to blocks, or match a
6918preexisting set of styles, pandoc allows you to define custom styles for
6919blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.
6921If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute
6922\f[C]custom-style\f[R], pandoc will apply your specified style to the
6923contained elements (with the exception of elements whose function
6924depends on a style, like headings, code blocks, block quotes, or links).
6925So, for example, using the \f[C]bracketed_spans\f[R] syntax,
6929[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
6933would produce a docx file with \[dq]Get out\[dq] styled with character
6934style \f[C]Emphatically\f[R].
6935Similarly, using the \f[C]fenced_divs\f[R] syntax,
6939Dickinson starts the poem simply:
6941::: {custom-style=\[dq]Poetry\[dq]}
6942| A Bird came down the Walk---
6943| He did not know I saw---
6948would style the two contained lines with the \f[C]Poetry\f[R] paragraph
6951For docx output, styles will be defined in the output file as inheriting
6952from normal text, if the styles are not yet in your reference.docx.
6953If they are already defined, pandoc will not alter the definition.
6955This feature allows for greatest customization in conjunction with
6957If you want all paragraphs after block quotes to be indented, you can
6958write a filter to apply the styles necessary.
6959If you want all italics to be transformed to the \f[C]Emphasis\f[R]
6960character style (perhaps to change their color), you can write a filter
6961which will transform all italicized inlines to inlines within an
6962\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
6964For docx output, you don\[aq]t need to enable any extensions for custom
6968The docx reader, by default, only reads those styles that it can convert
6969into pandoc elements, either by direct conversion or interpreting the
6970derivation of the input document\[aq]s styles.
6972By enabling the \f[C]styles\f[R] extension in the docx reader
6973(\f[C]-f docx+styles\f[R]), you can produce output that maintains the
6974styles of the input document, using the \f[C]custom-style\f[R] class.
6975Paragraph styles are interpreted as divs, while character styles are
6976interpreted as spans.
6978For example, using the \f[C]custom-style-reference.docx\f[R] file in the
6979test directory, we have the following different outputs:
6981Without the \f[C]+styles\f[R] extension:
6985$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
6988This is text with an *emphasized* text style. And this is text with a
6989**strengthened** text style.
6991> Here is a styled paragraph that inherits from Block Text.
6995And with the extension:
6999$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
7001::: {custom-style=\[dq]First Paragraph\[dq]}
7005::: {custom-style=\[dq]Body Text\[dq]}
7006This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style.
7007And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]}
7011::: {custom-style=\[dq]My Block Style\[dq]}
7012> Here is a styled paragraph that inherits from Block Text.
7017With these custom styles, you can use your input document as a
7018reference-doc while creating docx output (see below), and maintain the
7019same styles in your input and output files.
7022Pandoc can be extended with custom writers written in lua.
7023(Pandoc includes a lua interpreter, so lua need not be installed
7026To use a custom writer, simply specify the path to the lua script in
7027place of the output format.
7032pandoc -t data/sample.lua
7036Creating a custom writer requires writing a lua function for each
7037possible element in a pandoc document.
7038To get a documented example which you can modify according to your
7043pandoc --print-default-data-file sample.lua
7047Note that custom writers have no default template.
7048If you want to use \f[C]--standalone\f[R] with a custom writer, you will
7049need to specify a template manually using \f[C]--template\f[R] or add a
7050new default template with the name
7051\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
7052subdirectory of your user data directory (see Templates).
7053.SH A NOTE ON SECURITY
7055If you use pandoc to convert user-contributed content in a web
7056application, here are some things to keep in mind:
7058Although pandoc itself will not create or modify any files other than
7059those you explicitly ask it create (with the exception of temporary
7060files used in producing PDFs), a filter or custom writer could in
7061principle do anything on your file system.
7062Please audit filters and custom writers very carefully before using
7065If your application uses pandoc as a Haskell library (rather than
7066shelling out to the executable), it is possible to use it in a mode that
7067fully isolates pandoc from your file system, by running the pandoc
7068operations in the \f[C]PandocPure\f[R] monad.
7069See the document Using the pandoc API for more details.
7071Pandoc\[aq]s parsers can exhibit pathological performance on some corner
7073It is wise to put any pandoc operations under a timeout, to avoid DOS
7074attacks that exploit these issues.
7075If you are using the pandoc executable, you can add the command line
7076options \f[C]+RTS -M512M -RTS\f[R] (for example) to limit the heap size
7079The HTML generated by pandoc is not guaranteed to be safe.
7080If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
7081inject arbitrary HTML.
7082Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
7083content in attributes for headings, spans, and code blocks.
7084To be safe, you should run all the generated HTML through an HTML
7088Copyright 2006--2019 John MacFarlane (jgm\[at]berkeley.edu).
7089Released under the GPL, version 2 or greater.
7090This software carries no warranty of any kind.
7091(See COPYRIGHT for full copyright and warranty notices.) For a full list
7092of contributors, see the file AUTHORS.md in the pandoc source code.
7094The Pandoc source code and all documentation may be downloaded
7095from <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