2.\" Automatically generated by Pandoc 2.12.1
4.TH "Pandoc User\[cq]s Guide" "" "March 20, 2021" "pandoc 2.13" ""
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\[cq]s enhanced version of Markdown includes syntax for tables,
24definition lists, metadata blocks, footnotes, citations, math, and much
26See below under Pandoc\[cq]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\[cq]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\[cq]s simple document model.
43While conversions from pandoc\[cq]s Markdown to all formats aspire to be
44perfect, conversions from formats more expressive than pandoc\[cq]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.\ a valid HTML file including
61\f[C]<head>\f[R] and \f[C]<body>\f[R]), use the \f[C]-s\f[R] or
62\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\[cq]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\[cq] 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]iftex\f[R], \f[C]listings\f[R] (if the \f[C]--listings\f[R] option
176is used), \f[C]fancyvrb\f[R], \f[C]longtable\f[R], \f[C]booktabs\f[R],
177\f[C]graphicx\f[R] (if the document contains images),
178\f[C]hyperref\f[R], \f[C]xcolor\f[R], \f[C]ulem\f[R], \f[C]geometry\f[R]
179(with the \f[C]geometry\f[R] variable set), \f[C]setspace\f[R] (with
180\f[C]linestretch\f[R]), and \f[C]babel\f[R] (with \f[C]lang\f[R]).
181The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
182requires \f[C]fontspec\f[R].
183\f[C]lualatex\f[R] uses \f[C]selnolig\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 https://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]bibtex\f[R] (BibTeX bibliography)
232\f[C]biblatex\f[R] (BibLaTeX bibliography)
234\f[C]commonmark\f[R] (CommonMark Markdown)
236\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
238\f[C]creole\f[R] (Creole 1.0)
240\f[C]csljson\f[R] (CSL JSON bibliography)
242\f[C]csv\f[R] (CSV table)
244\f[C]docbook\f[R] (DocBook)
246\f[C]docx\f[R] (Word docx)
248\f[C]dokuwiki\f[R] (DokuWiki markup)
252\f[C]fb2\f[R] (FictionBook2 e-book)
254\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
255accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
256if you need extensions not supported in \f[C]gfm\f[R].
258\f[C]haddock\f[R] (Haddock markup)
262\f[C]ipynb\f[R] (Jupyter notebook)
264\f[C]jats\f[R] (JATS XML)
266\f[C]jira\f[R] (Jira/Confluence wiki markup)
268\f[C]json\f[R] (JSON version of native AST)
270\f[C]latex\f[R] (LaTeX)
272\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)
274\f[C]markdown_mmd\f[R] (MultiMarkdown)
276\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
278\f[C]markdown_strict\f[R] (original unextended Markdown)
280\f[C]mediawiki\f[R] (MediaWiki markup)
282\f[C]man\f[R] (roff man)
286\f[C]native\f[R] (native Haskell)
292\f[C]org\f[R] (Emacs Org mode)
294\f[C]rst\f[R] (reStructuredText)
296\f[C]t2t\f[R] (txt2tags)
298\f[C]textile\f[R] (Textile)
300\f[C]tikiwiki\f[R] (TikiWiki markup)
302\f[C]twiki\f[R] (TWiki markup)
304\f[C]vimwiki\f[R] (Vimwiki)
306Extensions can be individually enabled or disabled by appending
307\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
308See Extensions below, for a list of extensions and their names.
309See \f[C]--list-input-formats\f[R] and \f[C]--list-extensions\f[R],
313\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]
314Specify output format.
315\f[I]FORMAT\f[R] can be:
318\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor)
320\f[C]beamer\f[R] (LaTeX beamer slide show)
322\f[C]bibtex\f[R] (BibTeX bibliography)
324\f[C]biblatex\f[R] (BibLaTeX bibliography)
326\f[C]commonmark\f[R] (CommonMark Markdown)
328\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
330\f[C]context\f[R] (ConTeXt)
332\f[C]csljson\f[R] (CSL JSON bibliography)
334\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)
336\f[C]docbook5\f[R] (DocBook 5)
338\f[C]docx\f[R] (Word docx)
340\f[C]dokuwiki\f[R] (DokuWiki markup)
342\f[C]epub\f[R] or \f[C]epub3\f[R] (EPUB v3 book)
344\f[C]epub2\f[R] (EPUB v2)
346\f[C]fb2\f[R] (FictionBook2 e-book)
348\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less
349accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only
350if you need extensions not supported in \f[C]gfm\f[R].
352\f[C]haddock\f[R] (Haddock markup)
354\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot
357\f[C]html4\f[R] (XHTML 1.0 Transitional)
359\f[C]icml\f[R] (InDesign ICML)
361\f[C]ipynb\f[R] (Jupyter notebook)
363\f[C]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set)
365\f[C]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set)
367\f[C]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set)
369\f[C]jats\f[R] (alias for \f[C]jats_archiving\f[R])
371\f[C]jira\f[R] (Jira/Confluence wiki markup)
373\f[C]json\f[R] (JSON version of native AST)
375\f[C]latex\f[R] (LaTeX)
377\f[C]man\f[R] (roff man)
379\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)
381\f[C]markdown_mmd\f[R] (MultiMarkdown)
383\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
385\f[C]markdown_strict\f[R] (original unextended Markdown)
387\f[C]mediawiki\f[R] (MediaWiki markup)
389\f[C]ms\f[R] (roff ms)
391\f[C]muse\f[R] (Muse),
393\f[C]native\f[R] (native Haskell),
395\f[C]odt\f[R] (OpenOffice text document)
399\f[C]opendocument\f[R] (OpenDocument)
401\f[C]org\f[R] (Emacs Org mode)
405\f[C]plain\f[R] (plain text),
407\f[C]pptx\f[R] (PowerPoint slide show)
409\f[C]rst\f[R] (reStructuredText)
411\f[C]rtf\f[R] (Rich Text Format)
413\f[C]texinfo\f[R] (GNU Texinfo)
415\f[C]textile\f[R] (Textile)
417\f[C]slideous\f[R] (Slideous HTML and JavaScript slide show)
419\f[C]slidy\f[R] (Slidy HTML and JavaScript slide show)
421\f[C]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show),
423\f[C]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)
425\f[C]s5\f[R] (S5 HTML and JavaScript slide show)
427\f[C]tei\f[R] (TEI Simple)
429\f[C]xwiki\f[R] (XWiki markup)
431\f[C]zimwiki\f[R] (ZimWiki markup)
433the path of a custom Lua writer, see Custom writers below
435Note that \f[C]odt\f[R], \f[C]docx\f[R], \f[C]epub\f[R], and
436\f[C]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless
437forced with \f[C]-o -\f[R].
439Extensions can be individually enabled or disabled by appending
440\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.
441See Extensions below, for a list of extensions and their names.
442See \f[C]--list-output-formats\f[R] and \f[C]--list-extensions\f[R],
446\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]
447Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].
448If \f[I]FILE\f[R] is \f[C]-\f[R], output will go to \f[I]stdout\f[R],
449even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],
450\f[C]epub2\f[R], \f[C]epub3\f[R]) is specified.
452\f[B]\f[CB]--data-dir=\f[B]\f[R]\f[I]DIRECTORY\f[R]
453Specify the user data directory to search for pandoc data files.
454If this option is not specified, the default user data directory will be
456On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
457of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
458overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
460If that directory does not exist and \f[C]$HOME/.pandoc\f[R] exists, it
461will be used (for backwards compatibility).
462On Windows the default user data directory is
463\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
464You can find the default user data directory on your system by looking
465at the output of \f[C]pandoc --version\f[R].
466Data files placed in this directory (for example,
467\f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
468\f[C]templates\f[R]) will override pandoc\[cq]s normal defaults.
470\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]
471Specify a set of default option settings.
472\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line
474All options for document conversion, including input and output files,
475can be set using a defaults file.
476The file will be searched for first in the working directory, and then
477in the \f[C]defaults\f[R] subdirectory of the user data directory (see
478\f[C]--data-dir\f[R]).
479The \f[C].yaml\f[R] extension may be omitted.
480See the section Default files for more information on the file format.
481Settings from the defaults file may be overridden or extended by
482subsequent options on the command line.
484\f[B]\f[CB]--bash-completion\f[B]\f[R]
485Generate a bash completion script.
486To enable bash completion with pandoc, add this to your
492eval \[dq]$(pandoc --bash-completion)\[dq]
497\f[B]\f[CB]--verbose\f[B]\f[R]
498Give verbose debugging output.
500\f[B]\f[CB]--quiet\f[B]\f[R]
501Suppress warning messages.
503\f[B]\f[CB]--fail-if-warnings\f[B]\f[R]
504Exit with error status if there are any warnings.
506\f[B]\f[CB]--log=\f[B]\f[R]\f[I]FILE\f[R]
507Write log messages in machine-readable JSON format to \f[I]FILE\f[R].
508All messages above DEBUG level will be written, regardless of verbosity
509settings (\f[C]--verbose\f[R], \f[C]--quiet\f[R]).
511\f[B]\f[CB]--list-input-formats\f[B]\f[R]
512List supported input formats, one per line.
514\f[B]\f[CB]--list-output-formats\f[B]\f[R]
515List supported output formats, one per line.
517\f[B]\f[CB]--list-extensions\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]FORMAT\f[R]]
518List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
519by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by
520default in \f[I]FORMAT\f[R].
521If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown
524\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]
525List supported languages for syntax highlighting, one per line.
527\f[B]\f[CB]--list-highlight-styles\f[B]\f[R]
528List supported styles for syntax highlighting, one per line.
529See \f[C]--highlight-style\f[R].
531\f[B]\f[CB]-v\f[B]\f[R], \f[B]\f[CB]--version\f[B]\f[R]
534\f[B]\f[CB]-h\f[B]\f[R], \f[B]\f[CB]--help\f[B]\f[R]
538\f[B]\f[CB]--shift-heading-level-by=\f[B]\f[R]\f[I]NUMBER\f[R]
539Shift heading levels by a positive or negative integer.
540For example, with \f[C]--shift-heading-level-by=-1\f[R], level 2
541headings become level 1 headings, and level 3 headings become level 2
543Headings cannot have a level less than 1, so a heading that would be
544shifted below level 1 becomes a regular paragraph.
545Exception: with a shift of -N, a level-N heading at the beginning of the
546document replaces the metadata title.
547\f[C]--shift-heading-level-by=-1\f[R] is a good choice when converting
548HTML or Markdown documents that use an initial level-1 heading for the
549document title and level-2+ headings for sections.
550\f[C]--shift-heading-level-by=1\f[R] may be a good choice for converting
551Markdown documents that use level-1 headings for sections to HTML, since
552pandoc uses a level-1 heading to render the document title.
554\f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R]
555\f[I]Deprecated. Use \f[CI]--shift-heading-level-by\f[I]=X instead,
556where X = NUMBER - 1.\f[R] Specify the base level for headings (defaults
559\f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R]
560\f[I]Deprecated. Use the \f[CI]+empty_paragraphs\f[I] extension
561instead.\f[R] Ignore paragraphs with no content.
562This option is useful for converting word processing documents where
563users have used empty paragraphs to create inter-paragraph space.
565\f[B]\f[CB]--indented-code-classes=\f[B]\f[R]\f[I]CLASSES\f[R]
566Specify classes to use for indented code blocks\[en]for example,
567\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].
568Multiple classes may be separated by spaces or commas.
570\f[B]\f[CB]--default-image-extension=\f[B]\f[R]\f[I]EXTENSION\f[R]
571Specify a default extension to use when image paths/URLs have no
573This allows you to use the same source for formats that require
574different kinds of images.
575Currently this option only affects the Markdown and LaTeX readers.
577\f[B]\f[CB]--file-scope\f[B]\f[R]
578Parse each file individually before combining for multifile documents.
579This will allow footnotes in different files with the same identifiers
581If this option is set, footnotes and links will not work across files.
582Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].
584\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]
585Specify an executable to be used as a filter transforming the pandoc AST
586after the input is parsed and before the output is written.
587The executable should read JSON from stdin and write JSON to stdout.
588The JSON must be formatted like pandoc\[cq]s own JSON input and output.
589The name of the output format will be passed to the filter as the first
596pandoc --filter ./caps.py -t latex
604pandoc -t json | ./caps.py latex | pandoc -f json -t latex
608The latter form may be useful for debugging filters.
610Filters may be written in any language.
611\f[C]Text.Pandoc.JSON\f[R] exports \f[C]toJSONFilter\f[R] to facilitate
612writing filters in Haskell.
613Those who would prefer to write filters in python can use the module
614\f[C]pandocfilters\f[R], installable from PyPI.
615There are also pandoc filter libraries in PHP, perl, and
618In order of preference, pandoc will look for filters in
620a specified full or relative path (executable or non-executable)
622\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
623\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
626\f[C]$PATH\f[R] (executable only)
628Filters, Lua-filters, and citeproc processing are applied in the order
629specified on the command line.
632\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]
633Transform the document in a similar fashion as JSON filters (see
634\f[C]--filter\f[R]), but use pandoc\[cq]s built-in Lua filtering system.
635The given Lua script is expected to return a list of Lua filters which
636will be applied in order.
637Each Lua filter must contain element-transforming functions indexed by
638the name of the AST element on which the filter function should be
642The \f[C]pandoc\f[R] Lua module provides helper functions for element
644It is always loaded into the script\[cq]s Lua environment.
646See the Lua filters documentation for further details.
648In order of preference, pandoc will look for Lua filters in
650a specified full or relative path
652\f[C]$DATADIR/filters\f[R] where \f[C]$DATADIR\f[R] is the user data
653directory (see \f[C]--data-dir\f[R], above).
655Filters, Lua filters, and citeproc processing are applied in the order
656specified on the command line.
659\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]]
660Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].
661A value specified on the command line overrides a value specified in the
662document using YAML metadata blocks.
663Values will be parsed as YAML boolean or string values.
664If no value is specified, the value will be treated as Boolean true.
665Like \f[C]--variable\f[R], \f[C]--metadata\f[R] causes template
667But unlike \f[C]--variable\f[R], \f[C]--metadata\f[R] affects the
668metadata of the underlying document (which is accessible from filters
669and may be printed in some output formats) and metadata values will be
670escaped when inserted into the template.
672\f[B]\f[CB]--metadata-file=\f[B]\f[R]\f[I]FILE\f[R]
673Read metadata from the supplied YAML (or JSON) file.
674This option can be used with every input format, but string scalars in
675the YAML file will always be parsed as Markdown.
676Generally, the input will be handled the same as in YAML metadata
678This option can be used repeatedly to include multiple metadata files;
679values in files specified later on the command line will be preferred
680over those specified in earlier files.
681Metadata values specified inside the document, or by using \f[C]-M\f[R],
682overwrite values specified with this option.
684\f[B]\f[CB]-p\f[B]\f[R], \f[B]\f[CB]--preserve-tabs\f[B]\f[R]
685Preserve tabs instead of converting them to spaces.
686(By default, pandoc converts tabs to spaces before parsing its input.)
687Note that this will only affect tabs in literal code spans and code
689Tabs in regular text are always treated as spaces.
691\f[B]\f[CB]--tab-stop=\f[B]\f[R]\f[I]NUMBER\f[R]
692Specify the number of spaces per tab (default is 4).
694\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]
695Specifies what to do with insertions, deletions, and comments produced
696by the MS Word \[lq]Track Changes\[rq] feature.
697\f[C]accept\f[R] (the default) processes all the insertions and
699\f[C]reject\f[R] ignores them.
700Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.
701\f[C]all\f[R] includes all insertions, deletions, and comments, wrapped
702in spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
703\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,
705The author and time of change is included.
706\f[C]all\f[R] is useful for scripting: only accepting changes from a
707certain reviewer, say, or before a certain date.
708If a paragraph is inserted or deleted, \f[C]track-changes=all\f[R]
709produces a span with the class
710\f[C]paragraph-insertion\f[R]/\f[C]paragraph-deletion\f[R] before the
711affected paragraph break.
712This option only affects the docx reader.
714\f[B]\f[CB]--extract-media=\f[B]\f[R]\f[I]DIR\f[R]
715Extract images and other media contained in or linked from the source
716document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
717the images references in the document so they point to the extracted
719If the source format is a binary container (docx, epub, or odt), the
720media is extracted from the container and the original filenames are
722Otherwise the media is read from the file system or downloaded, and new
723filenames are constructed based on SHA1 hashes of the contents.
725\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
726Specifies a custom abbreviations file, with abbreviations one to a line.
727If this option is not specified, pandoc will read the data file
728\f[C]abbreviations\f[R] from the user data directory or fall back on a
730To see the system default, use
731\f[C]pandoc --print-default-data-file=abbreviations\f[R].
732The only use pandoc makes of this list is in the Markdown reader.
733Strings found in this list will be followed by a nonbreaking space, and
734the period will not produce sentence-ending space in formats like LaTeX.
735The strings may not contain spaces.
736.SS General writer options
738\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]
739Produce output with an appropriate header and footer (e.g.\ a standalone
740HTML, LaTeX, TEI, or RTF file, not a fragment).
741This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],
742\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]
744For \f[C]native\f[R] output, this option causes metadata to be included;
745otherwise, metadata is suppressed.
747\f[B]\f[CB]--template=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
748Use the specified file as a custom template for the generated document.
749Implies \f[C]--standalone\f[R].
750See Templates, below, for a description of template syntax.
751If no extension is specified, an extension corresponding to the writer
752will be added, so that \f[C]--template=special\f[R] looks for
753\f[C]special.html\f[R] for HTML output.
754If the template is not found, pandoc will search for it in the
755\f[C]templates\f[R] subdirectory of the user data directory (see
756\f[C]--data-dir\f[R]).
757If this option is not used, a default template appropriate for the
758output format will be used (see \f[C]-D/--print-default-template\f[R]).
760\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]]
761Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when
762rendering the document in standalone mode.
763If no \f[I]VAL\f[R] is specified, the key will be given the value
766\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]
767Print the system default template for an output \f[I]FORMAT\f[R].
768(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) Templates
769in the user data directory are ignored.
770This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
771output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
772\f[C]--print-default-template\f[R] on the command line.
775Note that some of the default templates use partials, for example
776\f[C]styles.html\f[R].
777To print the partials, use \f[C]--print-default-data-file\f[R]: for
778example, \f[C]--print-default-data-file=templates/styles.html\f[R].
781\f[B]\f[CB]--print-default-data-file=\f[B]\f[R]\f[I]FILE\f[R]
782Print a system default data file.
783Files in the user data directory are ignored.
784This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
785output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
786\f[C]--print-default-data-file\f[R] on the command line.
788\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]
789Manually specify line endings: \f[C]crlf\f[R] (Windows), \f[C]lf\f[R]
790(macOS/Linux/UNIX), or \f[C]native\f[R] (line endings appropriate to the
791OS on which pandoc is being run).
792The default is \f[C]native\f[R].
794\f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R]
795Specify the default dpi (dots per inch) value for conversion from pixels
796to inch/centimeters and vice versa.
797(Technically, the correct term would be ppi: pixels per inch.) The
799When images contain information about dpi internally, the encoded value
800is used instead of the default specified by this option.
802\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]
803Determine how text is wrapped in the output (the source code, not the
805With \f[C]auto\f[R] (the default), pandoc will attempt to wrap lines to
806the column width specified by \f[C]--columns\f[R] (default 72).
807With \f[C]none\f[R], pandoc will not wrap lines at all.
808With \f[C]preserve\f[R], pandoc will attempt to preserve the wrapping
809from the source document (that is, where there are nonsemantic newlines
810in the source, there will be nonsemantic newlines in the output as
812Automatic wrapping does not currently work in HTML output.
813In \f[C]ipynb\f[R] output, this option affects wrapping of the contents
816\f[B]\f[CB]--columns=\f[B]\f[R]\f[I]NUMBER\f[R]
817Specify length of lines in characters.
818This affects text wrapping in the generated source code (see
820It also affects calculation of column widths for plain text tables (see
823\f[B]\f[CB]--toc\f[B]\f[R], \f[B]\f[CB]--table-of-contents\f[B]\f[R]
824Include an automatically generated table of contents (or, in the case of
825\f[C]latex\f[R], \f[C]context\f[R], \f[C]docx\f[R], \f[C]odt\f[R],
826\f[C]opendocument\f[R], \f[C]rst\f[R], or \f[C]ms\f[R], an instruction
827to create one) in the output document.
828This option has no effect unless \f[C]-s/--standalone\f[R] is used, and
829it has no effect on \f[C]man\f[R], \f[C]docbook4\f[R],
830\f[C]docbook5\f[R], or \f[C]jats\f[R] output.
833Note that if you are producing a PDF via \f[C]ms\f[R], the table of
834contents will appear at the beginning of the document, before the title.
835If you would prefer it to be at the end of the document, use the option
836\f[C]--pdf-engine-opt=--no-toc-relocation\f[R].
839\f[B]\f[CB]--toc-depth=\f[B]\f[R]\f[I]NUMBER\f[R]
840Specify the number of section levels to include in the table of
842The default is 3 (which means that level-1, 2, and 3 headings will be
843listed in the contents).
845\f[B]\f[CB]--strip-comments\f[B]\f[R]
846Strip out HTML comments in the Markdown or Textile source, rather than
847passing them on to Markdown, Textile or HTML output as raw HTML.
848This does not apply to HTML comments inside raw HTML blocks when the
849\f[C]markdown_in_html_blocks\f[R] extension is not set.
851\f[B]\f[CB]--no-highlight\f[B]\f[R]
852Disables syntax highlighting for code blocks and inlines, even when a
853language attribute is given.
855\f[B]\f[CB]--highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
856Specifies the coloring style to be used in highlighted source code.
857Options are \f[C]pygments\f[R] (the default), \f[C]kate\f[R],
858\f[C]monochrome\f[R], \f[C]breezeDark\f[R], \f[C]espresso\f[R],
859\f[C]zenburn\f[R], \f[C]haddock\f[R], and \f[C]tango\f[R].
860For more information on syntax highlighting in pandoc, see Syntax
862See also \f[C]--list-highlight-styles\f[R].
865Instead of a \f[I]STYLE\f[R] name, a JSON file with extension
866\f[C].theme\f[R] may be supplied.
867This will be parsed as a KDE syntax highlighting theme and (if valid)
868used as the highlighting style.
870To generate the JSON version of an existing style, use
871\f[C]--print-highlight-style\f[R].
874\f[B]\f[CB]--print-highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]
875Prints a JSON version of a highlighting style, which can be modified,
876saved with a \f[C].theme\f[R] extension, and used with
877\f[C]--highlight-style\f[R].
878This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect
879output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before
880\f[C]--print-highlight-style\f[R] on the command line.
882\f[B]\f[CB]--syntax-definition=\f[B]\f[R]\f[I]FILE\f[R]
883Instructs pandoc to load a KDE XML syntax definition file, which will be
884used for syntax highlighting of appropriately marked code blocks.
885This can be used to add support for new languages or to use altered
886syntax definitions for existing languages.
887This option may be repeated to add multiple syntax definitions.
889\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]
890Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.
891This can be used, for example, to include special CSS or JavaScript in
893This option can be used repeatedly to include multiple files in the
895They will be included in the order specified.
896Implies \f[C]--standalone\f[R].
898\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]
899Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the
900document body (e.g.\ after the \f[C]<body>\f[R] tag in HTML, or the
901\f[C]\[rs]begin{document}\f[R] command in LaTeX).
902This can be used to include navigation bars or banners in HTML
904This option can be used repeatedly to include multiple files.
905They will be included in the order specified.
906Implies \f[C]--standalone\f[R].
908\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]
909Include contents of \f[I]FILE\f[R], verbatim, at the end of the document
910body (before the \f[C]</body>\f[R] tag in HTML, or the
911\f[C]\[rs]end{document}\f[R] command in LaTeX).
912This option can be used repeatedly to include multiple files.
913They will be included in the order specified.
914Implies \f[C]--standalone\f[R].
916\f[B]\f[CB]--resource-path=\f[B]\f[R]\f[I]SEARCHPATH\f[R]
917List of paths to search for images and other resources.
918The paths should be separated by \f[C]:\f[R] on Linux, UNIX, and macOS
919systems, and by \f[C];\f[R] on Windows.
920If \f[C]--resource-path\f[R] is not specified, the default resource path
921is the working directory.
922Note that, if \f[C]--resource-path\f[R] is specified, the working
923directory must be explicitly listed or it will not be searched.
924For example: \f[C]--resource-path=.:test\f[R] will search the working
925directory and the \f[C]test\f[R] subdirectory, in that order.
926This option can be used repeatedly.
927Search path components that come later on the command line will be
928searched before those that come earlier, so
929\f[C]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent
930to \f[C]--resource-path baz:bim:foo:bar\f[R].
932\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]
933Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
934making HTTP requests (for example, when a URL is given on the command
935line, or when resources used in a document must be downloaded).
936If you\[cq]re behind a proxy, you also need to set the environment
937variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].
939\f[B]\f[CB]--no-check-certificate\f[B]\f[R]
940Disable the certificate verification to allow access to unsecure HTTP
941resources (for example when the certificate is no longer valid or self
943.SS Options affecting specific writers
945\f[B]\f[CB]--self-contained\f[B]\f[R]
946Produce a standalone HTML file with no external dependencies, using
947\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,
948stylesheets, images, and videos.
949Implies \f[C]--standalone\f[R].
950The resulting file should be \[lq]self-contained,\[rq] in the sense that
951it needs no external files and no net access to be displayed properly by
953This option works only with HTML output formats, including
954\f[C]html4\f[R], \f[C]html5\f[R], \f[C]html+lhs\f[R],
955\f[C]html5+lhs\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
956\f[C]dzslides\f[R], and \f[C]revealjs\f[R].
957Scripts, images, and stylesheets at absolute URLs will be downloaded;
958those at relative URLs will be sought relative to the working directory
959(if the first source file is local) or relative to the base URL (if the
960first source file is remote).
961Elements with the attribute \f[C]data-external=\[dq]1\[dq]\f[R] will be
962left alone; the documents they link to will not be incorporated in the
964Limitation: resources that are loaded dynamically through JavaScript
965cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not
966work with \f[C]--mathjax\f[R], and some advanced features (e.g.\ zoom or
967speaker notes) may not work in an offline \[lq]self-contained\[rq]
968\f[C]reveal.js\f[R] slide show.
970\f[B]\f[CB]--html-q-tags\f[B]\f[R]
971Use \f[C]<q>\f[R] tags for quotes in HTML.
972(This option only has an effect if the \f[C]smart\f[R] extension is
973enabled for the input format used.)
975\f[B]\f[CB]--ascii\f[B]\f[R]
976Use only ASCII characters in output.
977Currently supported for XML and HTML formats (which use entities instead
978of UTF-8 when this option is selected), CommonMark, gfm, and Markdown
979(which use entities), roff ms (which use hexadecimal escapes), and to a
980limited degree LaTeX (which uses standard commands for accented
981characters when possible).
982roff man output uses ASCII by default.
984\f[B]\f[CB]--reference-links\f[B]\f[R]
985Use reference-style links, rather than inline links, in writing Markdown
987By default inline links are used.
988The placement of link references is affected by the
989\f[C]--reference-location\f[R] option.
991\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]
992Specify whether footnotes (and references, if \f[C]reference-links\f[R]
993is set) are placed at the end of the current (top-level) block, the
994current section, or the document.
995The default is \f[C]document\f[R].
996Currently only affects the markdown writer.
998\f[B]\f[CB]--markdown-headings=setext\f[B]\f[R]|\f[B]\f[CB]atx\f[B]\f[R]
999Specify whether to use ATX-style (\f[C]#\f[R]-prefixed) or Setext-style
1000(underlined) headings for level 1 and 2 headings in Markdown output.
1001(The default is \f[C]atx\f[R].) ATX-style headings are always used for
1003This option also affects Markdown cells in \f[C]ipynb\f[R] output.
1005\f[B]\f[CB]--atx-headers\f[B]\f[R]
1006\f[I]Deprecated synonym for \f[CI]--markdown-headings=atx\f[I].\f[R]
1008\f[B]\f[CB]--top-level-division=default\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]chapter\f[B]\f[R]|\f[B]\f[CB]part\f[B]\f[R]
1009Treat top-level headings as the given division type in LaTeX, ConTeXt,
1010DocBook, and TEI output.
1011The hierarchy order is part, chapter, then section; all headings are
1012shifted such that the top-level heading becomes the specified type.
1013The default behavior is to determine the best division type via
1014heuristics: unless other conditions apply, \f[C]section\f[R] is chosen.
1015When the \f[C]documentclass\f[R] variable is set to \f[C]report\f[R],
1016\f[C]book\f[R], or \f[C]memoir\f[R] (unless the \f[C]article\f[R] option
1017is specified), \f[C]chapter\f[R] is implied as the setting for this
1019If \f[C]beamer\f[R] is the output format, specifying either
1020\f[C]chapter\f[R] or \f[C]part\f[R] will cause top-level headings to
1021become \f[C]\[rs]part{..}\f[R], while second-level headings remain as
1024\f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]
1025Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB
1027By default, sections are not numbered.
1028Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
1029\f[C]--number-sections\f[R] is specified.
1031\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]]
1032Offset for section headings in HTML output (ignored in other output
1034The first number is added to the section number for top-level headings,
1035the second for second-level headings, and so on.
1036So, for example, if you want the first top-level heading in your
1037document to be numbered \[lq]6\[rq], specify
1038\f[C]--number-offset=5\f[R].
1039If your document starts with a level-2 heading which you want to be
1040numbered \[lq]1.5\[rq], specify \f[C]--number-offset=1,4\f[R].
1041Offsets are 0 by default.
1042Implies \f[C]--number-sections\f[R].
1044\f[B]\f[CB]--listings\f[B]\f[R]
1045Use the \f[C]listings\f[R] package for LaTeX code blocks.
1046The package does not support multi-byte encoding for source code.
1047To handle UTF-8 you would need to use a custom template.
1048This issue is fully documented here: Encoding issue with the listings
1051\f[B]\f[CB]-i\f[B]\f[R], \f[B]\f[CB]--incremental\f[B]\f[R]
1052Make list items in slide shows display incrementally (one by one).
1053The default is for lists to be displayed all at once.
1055\f[B]\f[CB]--slide-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1056Specifies that headings with the specified level create slides (for
1057\f[C]beamer\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],
1059Headings above this level in the hierarchy are used to divide the slide
1060show into sections; headings below this level create subheads within a
1062Note that content that is not contained under slide-level headings will
1063not appear in the slide show.
1064The default is to set the slide level based on the contents of the
1065document; see Structuring the slide show.
1067\f[B]\f[CB]--section-divs\f[B]\f[R]
1068Wrap sections in \f[C]<section>\f[R] tags (or \f[C]<div>\f[R] tags for
1069\f[C]html4\f[R]), and attach identifiers to the enclosing
1070\f[C]<section>\f[R] (or \f[C]<div>\f[R]) rather than the heading itself.
1071See Heading identifiers, below.
1073\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]
1074Specify a method for obfuscating \f[C]mailto:\f[R] links in HTML
1076\f[C]none\f[R] leaves \f[C]mailto:\f[R] links as they are.
1077\f[C]javascript\f[R] obfuscates them using JavaScript.
1078\f[C]references\f[R] obfuscates them by printing their letters as
1079decimal or hexadecimal character references.
1080The default is \f[C]none\f[R].
1082\f[B]\f[CB]--id-prefix=\f[B]\f[R]\f[I]STRING\f[R]
1083Specify a prefix to be added to all identifiers and internal links in
1084HTML and DocBook output, and to footnote numbers in Markdown and Haddock
1086This is useful for preventing duplicate identifiers when generating
1087fragments to be included in other pages.
1089\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]
1090Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that
1091appears in the HTML header (but not in the title as it appears at the
1092beginning of the HTML body).
1093Implies \f[C]--standalone\f[R].
1095\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]
1096Link to a CSS style sheet.
1097This option can be used repeatedly to include multiple files.
1098They will be included in the order specified.
1101A stylesheet is required for generating EPUB.
1102If none is provided using this option (or the \f[C]css\f[R] or
1103\f[C]stylesheet\f[R] metadata fields), pandoc will look for a file
1104\f[C]epub.css\f[R] in the user data directory (see
1105\f[C]--data-dir\f[R]).
1106If it is not found there, sensible defaults will be used.
1109\f[B]\f[CB]--reference-doc=\f[B]\f[R]\f[I]FILE\f[R]
1110Use the specified file as a style reference in producing a docx or ODT
1115For best results, the reference docx should be a modified version of a
1116docx file produced using pandoc.
1117The contents of the reference docx are ignored, but its stylesheets and
1118document properties (including margins, page size, header, and footer)
1119are used in the new docx.
1120If no reference docx is specified on the command line, pandoc will look
1121for a file \f[C]reference.docx\f[R] in the user data directory (see
1122\f[C]--data-dir\f[R]).
1123If this is not found either, sensible defaults will be used.
1126To produce a custom \f[C]reference.docx\f[R], first get a copy of the
1127default \f[C]reference.docx\f[R]:
1128\f[C]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R].
1129Then open \f[C]custom-reference.docx\f[R] in Word, modify the styles as
1130you wish, and save the file.
1131For best results, do not make changes to this file other than modifying
1132the styles used by pandoc:
1196Default Paragraph Font
1214For best results, the reference ODT should be a modified version of an
1215ODT produced using pandoc.
1216The contents of the reference ODT are ignored, but its stylesheets are
1218If no reference ODT is specified on the command line, pandoc will look
1219for a file \f[C]reference.odt\f[R] in the user data directory (see
1220\f[C]--data-dir\f[R]).
1221If this is not found either, sensible defaults will be used.
1224To produce a custom \f[C]reference.odt\f[R], first get a copy of the
1225default \f[C]reference.odt\f[R]:
1226\f[C]pandoc -o custom-reference.odt --print-default-data-file reference.odt\f[R].
1227Then open \f[C]custom-reference.odt\f[R] in LibreOffice, modify the
1228styles as you wish, and save the file.
1232Templates included with Microsoft PowerPoint 2013 (either with
1233\f[C].pptx\f[R] or \f[C].potx\f[R] extension) are known to work, as are
1234most templates derived from these.
1237The specific requirement is that the template should begin with the
1238following first four layouts:
1248All templates included with a recent version of MS PowerPoint will fit
1250(You can click on \f[C]Layout\f[R] under the \f[C]Home\f[R] menu to
1253You can also modify the default \f[C]reference.pptx\f[R]: first run
1254\f[C]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R],
1255and then modify \f[C]custom-reference.pptx\f[R] in MS PowerPoint (pandoc
1256will use the first four layout slides, as mentioned above).
1260\f[B]\f[CB]--epub-cover-image=\f[B]\f[R]\f[I]FILE\f[R]
1261Use the specified image as the EPUB cover.
1262It is recommended that the image be less than 1000px in width and
1264Note that in a Markdown source document you can also specify
1265\f[C]cover-image\f[R] in a YAML metadata block (see EPUB Metadata,
1268\f[B]\f[CB]--epub-metadata=\f[B]\f[R]\f[I]FILE\f[R]
1269Look in the specified XML file for metadata for the EPUB.
1270The file should contain a series of Dublin Core elements.
1276 <dc:rights>Creative Commons</dc:rights>
1277 <dc:language>es-AR</dc:language>
1281By default, pandoc will include the following metadata elements:
1282\f[C]<dc:title>\f[R] (from the document title), \f[C]<dc:creator>\f[R]
1283(from the document authors), \f[C]<dc:date>\f[R] (from the document
1284date, which should be in ISO 8601 format), \f[C]<dc:language>\f[R] (from
1285the \f[C]lang\f[R] variable, or, if is not set, the locale), and
1286\f[C]<dc:identifier id=\[dq]BookId\[dq]>\f[R] (a randomly generated
1288Any of these may be overridden by elements in the metadata file.
1290Note: if the source document is Markdown, a YAML metadata block in the
1291document can be used instead.
1292See below under EPUB Metadata.
1295\f[B]\f[CB]--epub-embed-font=\f[B]\f[R]\f[I]FILE\f[R]
1296Embed the specified font in the EPUB.
1297This option can be repeated to embed multiple fonts.
1298Wildcards can also be used: for example, \f[C]DejaVuSans-*.ttf\f[R].
1299However, if you use wildcards on the command line, be sure to escape
1300them or put the whole filename in single quotes, to prevent them from
1301being interpreted by the shell.
1302To use the embedded fonts, you will need to add declarations like the
1303following to your CSS (see \f[C]--css\f[R]):
1309font-family: DejaVuSans;
1312src:url(\[dq]DejaVuSans-Regular.ttf\[dq]);
1315font-family: DejaVuSans;
1318src:url(\[dq]DejaVuSans-Bold.ttf\[dq]);
1321font-family: DejaVuSans;
1324src:url(\[dq]DejaVuSans-Oblique.ttf\[dq]);
1327font-family: DejaVuSans;
1330src:url(\[dq]DejaVuSans-BoldOblique.ttf\[dq]);
1332body { font-family: \[dq]DejaVuSans\[dq]; }
1337\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1338Specify the heading level at which to split the EPUB into separate
1339\[lq]chapter\[rq] files.
1340The default is to split into chapters at level-1 headings.
1341This option only affects the internal composition of the EPUB, not the
1342way chapters and sections are displayed to users.
1343Some readers may be slow if the chapter files are too large, so for
1344large documents with few level-1 headings, one might want to use a
1345chapter level of 2 or 3.
1347\f[B]\f[CB]--epub-subdirectory=\f[B]\f[R]\f[I]DIRNAME\f[R]
1348Specify the subdirectory in the OCF container that is to hold the
1349EPUB-specific contents.
1350The default is \f[C]EPUB\f[R].
1351To put the EPUB contents in the top level, use an empty string.
1353\f[B]\f[CB]--ipynb-output=all|none|best\f[B]\f[R]
1354Determines how ipynb output cells are treated.
1355\f[C]all\f[R] means that all of the data formats included in the
1356original are preserved.
1357\f[C]none\f[R] means that the contents of data cells are omitted.
1358\f[C]best\f[R] causes pandoc to try to pick the richest data block in
1359each output cell that is compatible with the output format.
1360The default is \f[C]best\f[R].
1362\f[B]\f[CB]--pdf-engine=\f[B]\f[R]\f[I]PROGRAM\f[R]
1363Use the specified engine when producing PDF output.
1364Valid values are \f[C]pdflatex\f[R], \f[C]lualatex\f[R],
1365\f[C]xelatex\f[R], \f[C]latexmk\f[R], \f[C]tectonic\f[R],
1366\f[C]wkhtmltopdf\f[R], \f[C]weasyprint\f[R], \f[C]prince\f[R],
1367\f[C]context\f[R], and \f[C]pdfroff\f[R].
1368If the engine is not in your PATH, the full path of the engine may be
1370If this option is not specified, pandoc uses the following defaults
1371depending on the output format specified using \f[C]-t/--to\f[R]:
1374\f[C]-t latex\f[R] or none: \f[C]pdflatex\f[R] (other options:
1375\f[C]xelatex\f[R], \f[C]lualatex\f[R], \f[C]tectonic\f[R],
1378\f[C]-t context\f[R]: \f[C]context\f[R]
1380\f[C]-t html\f[R]: \f[C]wkhtmltopdf\f[R] (other options:
1381\f[C]prince\f[R], \f[C]weasyprint\f[R]; see print-css.rocks for a good
1382introduction to PDF generation from HTML/CSS.)
1384\f[C]-t ms\f[R]: \f[C]pdfroff\f[R]
1387\f[B]\f[CB]--pdf-engine-opt=\f[B]\f[R]\f[I]STRING\f[R]
1388Use the given string as a command-line argument to the
1389\f[C]pdf-engine\f[R].
1390For example, to use a persistent directory \f[C]foo\f[R] for
1391\f[C]latexmk\f[R]\[cq]s auxiliary files, use
1392\f[C]--pdf-engine-opt=-outdir=foo\f[R].
1393Note that no check for duplicate options is done.
1394.SS Citation rendering
1396\f[B]\f[CB]-C\f[B]\f[R], \f[B]\f[CB]--citeproc\f[B]\f[R]
1397Process the citations in the file, replacing them with rendered
1398citations and adding a bibliography.
1399Citation processing will not take place unless bibliographic data is
1400supplied, either through an external file specified using the
1401\f[C]--bibliography\f[R] option or the \f[C]bibliography\f[R] field in
1402metadata, or via a \f[C]references\f[R] section in metadata containing a
1403list of citations in CSL YAML format with Markdown formatting.
1404The style is controlled by a CSL stylesheet specified using the
1405\f[C]--csl\f[R] option or the \f[C]csl\f[R] field in metadata.
1406(If no stylesheet is specified, the \f[C]chicago-author-date\f[R] style
1407will be used by default.) The citation processing transformation may be
1408applied before or after filters or Lua filters (see \f[C]--filter\f[R],
1409\f[C]--lua-filter\f[R]): these transformations are applied in the order
1410they appear on the command line.
1411For more information, see the section on Citations.
1413\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]
1414Set the \f[C]bibliography\f[R] field in the document\[cq]s metadata to
1415\f[I]FILE\f[R], overriding any value set in the metadata.
1416If you supply this argument multiple times, each \f[I]FILE\f[R] will be
1417added to bibliography.
1418If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.
1419If \f[I]FILE\f[R] is not found relative to the working directory, it
1420will be sought in the resource path (see \f[C]--resource-path\f[R]).
1422\f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R]
1423Set the \f[C]csl\f[R] field in the document\[cq]s metadata to
1424\f[I]FILE\f[R], overriding any value set in the metadata.
1425(This is equivalent to \f[C]--metadata csl=FILE\f[R].) If \f[I]FILE\f[R]
1426is a URL, it will be fetched via HTTP.
1427If \f[I]FILE\f[R] is not found relative to the working directory, it
1428will be sought in the resource path (see \f[C]--resource-path\f[R]) and
1429finally in the \f[C]csl\f[R] subdirectory of the pandoc user data
1432\f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
1433Set the \f[C]citation-abbreviations\f[R] field in the document\[cq]s
1434metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
1435(This is equivalent to
1436\f[C]--metadata citation-abbreviations=FILE\f[R].) If \f[I]FILE\f[R] is
1437a URL, it will be fetched via HTTP.
1438If \f[I]FILE\f[R] is not found relative to the working directory, it
1439will be sought in the resource path (see \f[C]--resource-path\f[R]) and
1440finally in the \f[C]csl\f[R] subdirectory of the pandoc user data
1443\f[B]\f[CB]--natbib\f[B]\f[R]
1444Use \f[C]natbib\f[R] for citations in LaTeX output.
1445This option is not for use with the \f[C]--citeproc\f[R] option or with
1447It is intended for use in producing a LaTeX file that can be processed
1448with \f[C]bibtex\f[R].
1450\f[B]\f[CB]--biblatex\f[B]\f[R]
1451Use \f[C]biblatex\f[R] for citations in LaTeX output.
1452This option is not for use with the \f[C]--citeproc\f[R] option or with
1454It is intended for use in producing a LaTeX file that can be processed
1455with \f[C]bibtex\f[R] or \f[C]biber\f[R].
1456.SS Math rendering in HTML
1458The default is to render TeX math as far as possible using Unicode
1460Formulas are put inside a \f[C]span\f[R] with
1461\f[C]class=\[dq]math\[dq]\f[R], so that they may be styled differently
1462from the surrounding text if needed.
1463However, this gives acceptable results only for basic math, usually you
1464will want to use \f[C]--mathjax\f[R] or another of the following
1467\f[B]\f[CB]--mathjax\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1468Use MathJax to display embedded TeX math in HTML output.
1469TeX math will be put between \f[C]\[rs](...\[rs])\f[R] (for inline math)
1470or \f[C]\[rs][...\[rs]]\f[R] (for display math) and wrapped in
1471\f[C]<span>\f[R] tags with class \f[C]math\f[R].
1472Then the MathJax JavaScript will render it.
1473The \f[I]URL\f[R] should point to the \f[C]MathJax.js\f[R] load script.
1474If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be
1477\f[B]\f[CB]--mathml\f[B]\f[R]
1478Convert TeX math to MathML (in \f[C]epub3\f[R], \f[C]docbook4\f[R],
1479\f[C]docbook5\f[R], \f[C]jats\f[R], \f[C]html4\f[R] and
1481This is the default in \f[C]odt\f[R] output.
1482Note that currently only Firefox and Safari (and select e-book readers)
1483natively support MathML.
1485\f[B]\f[CB]--webtex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1486Convert TeX formulas to \f[C]<img>\f[R] tags that link to an external
1487script that converts formulas to images.
1488The formula will be URL-encoded and concatenated with the URL provided.
1489For SVG images you can for example use
1490\f[C]--webtex https://latex.codecogs.com/svg.latex?\f[R].
1491If no URL is specified, the CodeCogs URL generating PNGs will be used
1492(\f[C]https://latex.codecogs.com/png.latex?\f[R]).
1493Note: the \f[C]--webtex\f[R] option will affect Markdown output as well
1494as HTML, which is useful if you\[cq]re targeting a version of Markdown
1495without native math support.
1497\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1498Use KaTeX to display embedded TeX math in HTML output.
1499The \f[I]URL\f[R] is the base URL for the KaTeX library.
1500That directory should contain a \f[C]katex.min.js\f[R] and a
1501\f[C]katex.min.css\f[R] file.
1502If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be
1505\f[B]\f[CB]--gladtex\f[B]\f[R]
1506Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.
1507The resulting HTML can then be processed by GladTeX to produce images of
1508the typeset formulas and an HTML file with links to these images.
1509So, the procedure is:
1514pandoc -s --gladtex input.md -o myfile.htex
1515gladtex -d myfile-images myfile.htex
1516# produces myfile.html and images in myfile-images
1520.SS Options for wrapper scripts
1522\f[B]\f[CB]--dump-args\f[B]\f[R]
1523Print information about command-line arguments to \f[I]stdout\f[R], then
1525This option is intended primarily for use in wrapper scripts.
1526The first line of output contains the name of the output file specified
1527with the \f[C]-o\f[R] option, or \f[C]-\f[R] (for \f[I]stdout\f[R]) if
1528no output file was specified.
1529The remaining lines contain the command-line arguments, one per line, in
1530the order they appear.
1531These do not include regular pandoc options and their arguments, but do
1532include any options appearing after a \f[C]--\f[R] separator at the end
1535\f[B]\f[CB]--ignore-args\f[B]\f[R]
1536Ignore command-line arguments (for use in wrapper scripts).
1537Regular pandoc options are not ignored.
1543pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1551pandoc -o foo.html -s
1557If pandoc completes successfully, it will return exit code 0.
1558Nonzero exit codes have the following meanings:
1572PandocFailOnWarningError
1592PandocUnknownReaderError
1597PandocUnknownWriterError
1602PandocUnsupportedExtensionError
1612PandocEpubSubdirectoryError
1627PandocPDFProgramNotFoundError
1637PandocShouldNeverHappenError
1677PandocUTF8DecodingError
1682PandocIpynbDecodingError
1687PandocUnsupportedCharsetError
1692PandocCouldNotFindDataFileError
1697PandocResourceNotFound
1702The \f[C]--defaults\f[R] option may be used to specify a package of
1704Here is a sample defaults file demonstrating all of the fields that may
1710# reader: may be used instead of from:
1712# writer: may be used instead of to:
1714# leave blank for output to stdout:
1716# leave blank for input from stdin, use [] for no input:
1720# or you may use input-file: with a single value
1722# Include options from the specified defaults files.
1723# The files will be searched for first in the working directory
1724# and then in the defaults subdirectory of the user data directory.
1725# The files are included in the same order in which they appear in
1726# the list. Options specified in this defaults file always have
1727# priority over the included ones.
1734self-contained: false
1736# note that structured variables may be specified:
1743# metadata values specified here are parsed as literal
1744# string text, not markdown:
1751# or you may use metadata-file: with a single value
1753# Note that these take files, not their contents:
1754include-before-body: []
1755include-after-body: []
1756include-in-header: []
1757resource-path: [\[dq].\[dq]]
1759# turn on built-in citation processing. Note that if you need
1760# control over when the citeproc processing is done relative
1761# to other filters, you should instead use \[ga]citeproc\[ga] in the
1762# list of \[ga]filters\[ga] (see below).
1768citation-abbreviations: abbrevs.json
1770# Filters will be assumed to be Lua filters if they have
1771# the .lua extension, and json filters otherwise. But
1772# the filter type can also be specified explicitly, as shown.
1773# Filters are run in the order specified.
1774# To include the built-in citeproc filter, use either \[ga]citeproc\[ga]
1775# or \[ga]{type: citeproc}\[ga].
1785# ERROR, WARNING, or INFO
1789# citeproc, natbib, or biblatex. This only affects LaTeX
1790# output. If you want to use citeproc to format citations,
1791# you should also set \[aq]citeproc: true\[aq] (see above).
1792cite-method: citeproc
1794# part, chapter, section, or default:
1795top-level-division: chapter
1800- \[dq]-shell-escape\[dq]
1801# you may also use pdf-engine-opt: with a single option
1802# pdf-engine-opt: \[dq]-shell-escape\[dq]
1804# auto, preserve, or none
1809extract-media: mediadir
1811table-of-contents: true
1813number-sections: false
1814# a list of offsets at each heading level
1815number-offset: [0,0,0,0,0,0]
1816# toc: may also be used instead of table-of-contents:
1817shift-heading-level-by: 1
1819identifier-prefix: foo
1820title-prefix: \[dq]\[dq]
1821strip-empty-paragraphs: true
1822# lf, crlf, or native
1824strip-comments: false
1825indented-code-classes: []
1827default-image-extension: \[dq].jpg\[dq]
1829# either a style name of a style definition file:
1830highlight-style: pygments
1833# or you may use syntax-definition: with a single value
1836reference-doc: myref.docx
1838# method is plain, webtex, gladtex, mathml, mathjax, katex
1839# you may specify a url with webtex, mathjax, katex
1842 url: \[dq]https://cdn.jsdelivr.net/npm/mathjax\[at]3/es5/tex-mml-chtml.js\[dq]
1843# none, references, or javascript
1844email-obfuscation: javascript
1852epub-subdirectory: EPUB
1853epub-metadata: meta.xml
1856epub-chapter-level: 1
1857epub-cover-image: cover.jpg
1859reference-links: true
1860# block, section, or document
1861reference-location: block
1862markdown-headings: setext
1864# accept, reject, or all
1865track-changes: accept
1874# A list of two-element lists
1876- [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]
1878fail-if-warnings: false
1885Fields that are omitted will just have their regular default values.
1886So a defaults file can be as simple as one line:
1894In fields that expect a file path (or list of file paths), the following
1895syntax may be used to interpolate environment variables:
1899csl: ${HOME}/mycsldir/special.csl
1903\f[C]${USERDATA}\f[R] may also be used; this will always resolve to the
1904user data directory that is current when the defaults file is parsed,
1905regardless of the setting of the environment variable
1908\f[C]${.}\f[R] will resolve to the directory containing the default file
1910This allows you to refer to resources contained in that directory:
1914epub-cover-image: ${.}/cover.jpg
1915epub-metadata: ${.}/meta.xml
1917- . # the working directory from which pandoc is run
1918- ${.}/images # the images subdirectory of the directory
1919 # containing this defaults file
1923This environment variable interpolation syntax \f[I]only\f[R] works in
1924fields that expect file paths.
1926Default files can be placed in the \f[C]defaults\f[R] subdirectory of
1927the user data directory and used from any directory.
1928For example, one could create a file specifying defaults for writing
1929letters, save it as \f[C]letter.yaml\f[R] in the \f[C]defaults\f[R]
1930subdirectory of the user data directory, and then invoke these defaults
1931from any directory using \f[C]pandoc --defaults letter\f[R] or
1932\f[C]pandoc -dletter\f[R].
1934When multiple defaults are used, their contents will be combined.
1936Note that, where command-line arguments may be repeated
1937(\f[C]--metadata-file\f[R], \f[C]--css\f[R],
1938\f[C]--include-in-header\f[R], \f[C]--include-before-body\f[R],
1939\f[C]--include-after-body\f[R], \f[C]--variable\f[R],
1940\f[C]--metadata\f[R], \f[C]--syntax-definition\f[R]), the values
1941specified on the command line will combine with values specified in the
1942defaults file, rather than replacing them.
1945When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a
1946template to add header and footer material that is needed for a
1947self-standing document.
1948To see the default template that is used, just type
1956where \f[I]FORMAT\f[R] is the name of the output format.
1957A custom template can be specified using the \f[C]--template\f[R]
1959You can also override the system default templates for a given output
1960format \f[I]FORMAT\f[R] by putting a file
1961\f[C]templates/default.*FORMAT*\f[R] in the user data directory (see
1962\f[C]--data-dir\f[R], above).
1963\f[I]Exceptions:\f[R]
1965For \f[C]odt\f[R] output, customize the \f[C]default.opendocument\f[R]
1968For \f[C]pdf\f[R] output, customize the \f[C]default.latex\f[R] template
1969(or the \f[C]default.context\f[R] template, if you use
1970\f[C]-t context\f[R], or the \f[C]default.ms\f[R] template, if you use
1971\f[C]-t ms\f[R], or the \f[C]default.html\f[R] template, if you use
1974\f[C]docx\f[R] and \f[C]pptx\f[R] have no template (however, you can use
1975\f[C]--reference-doc\f[R] to customize the output).
1977Templates contain \f[I]variables\f[R], which allow for the inclusion of
1978arbitrary information at any point in the file.
1979They may be set at the command line using the \f[C]-V/--variable\f[R]
1981If a variable is not set, pandoc will look for the key in the
1982document\[cq]s metadata, which can be set using either YAML metadata
1983blocks or with the \f[C]-M/--metadata\f[R] option.
1984In addition, some variables are given default values by pandoc.
1985See Variables below for a list of variables used in pandoc\[cq]s default
1988If you use custom templates, you may need to revise them as pandoc
1990We recommend tracking the changes in the default templates, and
1991modifying your custom templates accordingly.
1992An easy way to do this is to fork the pandoc-templates repository and
1993merge in changes after each pandoc release.
1997Anything between the sequence \f[C]$--\f[R] and the end of the line will
1998be treated as a comment and omitted from the output.
2001To mark variables and control structures in the template, either
2002\f[C]$\f[R]\&...\f[C]$\f[R] or \f[C]${\f[R]\&...\f[C]}\f[R] may be used
2004The styles may also be mixed in the same template, but the opening and
2005closing delimiter must match in each case.
2006The opening delimiter may be followed by one or more spaces or tabs,
2007which will be ignored.
2008The closing delimiter may be followed by one or more spaces or tabs,
2009which will be ignored.
2011To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].
2012.SS Interpolated variables
2014A slot for an interpolated variable is a variable name surrounded by
2016Variable names must begin with a letter and can contain letters,
2017numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].
2018The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],
2019\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may
2020not be used as variable names.
2036Variable names with periods are used to get at structured variable
2038So, for example, \f[C]employee.salary\f[R] will return the value of the
2039\f[C]salary\f[R] field of the object that is the value of the
2040\f[C]employee\f[R] field.
2042If the value of the variable is simple value, it will be rendered
2044(Note that no escaping is done; the assumption is that the calling
2045program will escape the strings appropriately for the output format.)
2047If the value is a list, the values will be concatenated.
2049If the value is a map, the string \f[C]true\f[R] will be rendered.
2051Every other value will be rendered as the empty string.
2054A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched
2055delimiters) and ends with \f[C]endif\f[R] (enclosed in matched
2057It may optionally contain an \f[C]else\f[R] (enclosed in matched
2059The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty
2060value, otherwise the \f[C]else\f[R] section is used (if present).
2077${if(foo)}bar${endif}
2091The keyword \f[C]elseif\f[R] may be used to simplify complex nested
2107A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched
2108delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched
2111If \f[C]variable\f[R] is an array, the material inside the loop will be
2112evaluated repeatedly, with \f[C]variable\f[R] being set to each value of
2113the array in turn, and concatenated.
2115If \f[C]variable\f[R] is a map, the material inside will be set to the
2118If the value of the associated variable is not an array or a map, a
2119single iteration will be performed on its value.
2125$for(foo)$$foo$$sep$, $endfor$
2128 - $foo.last$, $foo.first$
2132 - ${ foo.bar.last }, ${ foo.bar.first }
2136$it.name$: $it.office$
2141You may optionally specify a separator between consecutive values using
2142\f[C]sep\f[R] (enclosed in matched delimiters).
2143The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the
2148${ for(foo) }${ foo }${ sep }, ${ endfor }
2152Instead of using \f[C]variable\f[R] inside the loop, the special
2153anaphoric keyword \f[C]it\f[R] may be used.
2158 - ${ it.last }, ${ it.first }
2164Partials (subtemplates stored in different files) may be included by
2165using the name of the partial, followed by \f[C]()\f[R], for example:
2173Partials will be sought in the directory containing the main template.
2174The file name will be assumed to have the same extension as the main
2175template if it lacks an extension.
2176When calling the partial, the full name including file extension can
2185(If a partial is not found in the directory of the template and the
2186template path is given as a relative path, it will also be sought in the
2187\f[C]templates\f[R] subdirectory of the user data directory.)
2189Partials may optionally be applied to variables using a colon:
2195${ articles:bibentry() }
2199If \f[C]articles\f[R] is an array, this will iterate over its values,
2200applying the partial \f[C]bibentry()\f[R] to each one.
2201So the second example above is equivalent to
2211Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating
2213In the above examples, the \f[C]bibentry\f[R] partial should contain
2214\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].
2216Final newlines are omitted from included partials.
2218Partials may include other partials.
2220A separator between values of an array may be specified in square
2221brackets, immediately after the variable name or partial:
2227${articles:bibentry()[; ]$
2231The separator in this case is literal and (unlike with \f[C]sep\f[R] in
2232an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or
2233other template directives.
2236To ensure that content is \[lq]nested,\[rq] that is, subsequent lines
2237indented, use the \f[C]\[ha]\f[R] directive:
2241$item.number$ $\[ha]$$item.description$ ($item.price$)
2245In this example, if \f[C]item.description\f[R] has multiple lines, they
2246will all be indented to line up with the first line:
225000123 A fine bottle of 18-year old
2251 Oban whiskey. ($148)
2255To nest multiple lines to the same level, align them with the
2256\f[C]\[ha]\f[R] directive in the template.
2261$item.number$ $\[ha]$$item.description$ ($item.price$)
2262 (Available til $item.sellby$.)
227000123 A fine bottle of 18-year old
2271 Oban whiskey. ($148)
2272 (Available til March 30, 2020.)
2276If a variable occurs by itself on a line, preceded by whitespace and not
2277followed by further text or directives on the same line, and the
2278variable\[cq]s value contains multiple lines, it will be nested
2282Normally, spaces in the template itself (as opposed to values of the
2283interpolated variables) are not breakable, but they can be made
2284breakable in part of the template by using the \f[C]\[ti]\f[R] keyword
2285(ended with another \f[C]\[ti]\f[R]).
2289$\[ti]$This long line may break if the document is rendered
2290with a short line length.$\[ti]$
2295A pipe transforms the value of a variable or partial.
2296Pipes are specified using a slash (\f[C]/\f[R]) between the variable
2297name (or partial) and the pipe name.
2306$for(metadata/pairs)$
2307- $it.key$: $it.value$
2310$employee:name()/uppercase$
2314Pipes may be chained:
2318$for(employees/pairs)$
2319$it.key/alpha/uppercase$. $it.name$
2324Some pipes take parameters:
2328|----------------------|------------|
2330$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$
2332|----------------------|------------|
2336Currently the following pipes are predefined:
2338\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with
2339\f[C]key\f[R] and \f[C]value\f[R] fields.
2340If the original value was an array, the \f[C]key\f[R] will be the array
2341index, starting with 1.
2343\f[C]uppercase\f[R]: Converts text to uppercase.
2345\f[C]lowercase\f[R]: Converts text to lowercase.
2347\f[C]length\f[R]: Returns the length of the value: number of characters
2348for a textual value, number of elements for a map or array.
2350\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect
2353\f[C]first\f[R]: Returns the first value of an array, if applied to a
2354non-empty array; otherwise returns the original value.
2356\f[C]last\f[R]: Returns the last value of an array, if applied to a
2357non-empty array; otherwise returns the original value.
2359\f[C]rest\f[R]: Returns all but the first value of an array, if applied
2360to a non-empty array; otherwise returns the original value.
2362\f[C]allbutlast\f[R]: Returns all but the last value of an array, if
2363applied to a non-empty array; otherwise returns the original value.
2365\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).
2367\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.
2369\f[C]alpha\f[R]: Converts textual values that can be read as an integer
2370into lowercase alphabetic characters \f[C]a..z\f[R] (mod 26).
2371This can be used to get lettered enumeration from array indices.
2372To get uppercase letters, chain with \f[C]uppercase\f[R].
2374\f[C]roman\f[R]: Converts textual values that can be read as an integer
2375into lowercase roman numerials.
2376This can be used to get lettered enumeration from array indices.
2377To get uppercase roman, chain with \f[C]uppercase\f[R].
2379\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2380textual value in a block of width \f[C]n\f[R], aligned to the left, with
2381an optional left and right border.
2382Has no effect on other values.
2383This can be used to align material in tables.
2384Widths are positive integers indicating the number of characters.
2385Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and
2386\f[C]\[rs]\f[R] characters must be backslash-escaped.
2388\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2389textual value in a block of width \f[C]n\f[R], aligned to the right, and
2390has no effect on other values.
2392\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a
2393textual value in a block of width \f[C]n\f[R], aligned to the center,
2394and has no effect on other values.
2396.SS Metadata variables
2398\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]
2399allow identification of basic aspects of the document.
2400Included in PDF metadata through LaTeX and ConTeXt.
2401These can be set through a pandoc title block, which allows for multiple
2402authors, or through a YAML metadata block:
2415Note that if you just want to set PDF or HTML metadata, without
2416including a title block in the document itself, you can set the
2417\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]
2419(By default these are set automatically, based on \f[C]title\f[R],
2420\f[C]author\f[R], and \f[C]date\f[R].) The page title in HTML is set by
2421\f[C]pagetitle\f[R], which is equal to \f[C]title\f[R] by default.
2424\f[B]\f[CB]subtitle\f[B]\f[R]
2425document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx
2428\f[B]\f[CB]abstract\f[B]\f[R]
2429document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
2432\f[B]\f[CB]keywords\f[B]\f[R]
2433list of keywords to be included in HTML, PDF, ODT, pptx, docx and
2434AsciiDoc metadata; repeat as for \f[C]author\f[R], above
2436\f[B]\f[CB]subject\f[B]\f[R]
2437document subject, included in ODT, PDF, docx and pptx metadata
2439\f[B]\f[CB]description\f[B]\f[R]
2440document description, included in ODT, docx and pptx metadata.
2441Some applications show this as \f[C]Comments\f[R] metadata.
2443\f[B]\f[CB]category\f[B]\f[R]
2444document category, included in docx and pptx metadata
2446Additionally, any root-level string metadata, not included in ODT, docx
2447or pptx metadata is added as a \f[I]custom property\f[R].
2448The following YAML metadata block for instance:
2453title: \[aq]This is the title\[aq]
2454subtitle: \[dq]This is the subtitle\[dq]
2462 It consists of two paragraphs
2467will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]
2468as standard document properties and \f[C]subtitle\f[R] as a custom
2469property when converting to docx, ODT or pptx.
2470.SS Language variables
2472\f[B]\f[CB]lang\f[B]\f[R]
2473identifies the main language of the document using IETF language tags
2474(following the BCP 47 standard), such as \f[C]en\f[R] or
2476The Language subtag lookup tool can look up or verify these tags.
2477This affects most formats, and controls hyphenation in PDF output when
2478using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or
2482Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to
2491Text in the main document language (British English).
2494> Cette citation est \['e]crite en fran\[,c]ais canadien.
2497More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}
2502\f[B]\f[CB]dir\f[B]\f[R]
2503the base script direction, either \f[C]rtl\f[R] (right-to-left) or
2504\f[C]ltr\f[R] (left-to-right).
2507For bidirectional documents, native pandoc \f[C]span\f[R]s and
2508\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or
2509\f[C]ltr\f[R]) can be used to override the base direction in some output
2511This may not always be necessary if the final renderer (e.g.\ the
2512browser, when generating HTML) supports the Unicode Bidirectional
2515When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
2516engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
2518.SS Variables for HTML
2520\f[B]\f[CB]document-css\f[B]\f[R]
2521Enables inclusion of most of the CSS in the \f[C]styles.html\f[R]
2522partial (have a look with
2523\f[C]pandoc --print-default-data-file=templates/styles.html\f[R]).
2524Unless you use \f[C]--css\f[R], this variable is set to \f[C]true\f[R]
2526You can disable it with e.g.\ \f[C]pandoc -M document-css=false\f[R].
2528\f[B]\f[CB]mainfont\f[B]\f[R]
2529sets the CSS \f[C]font-family\f[R] property on the \f[C]html\f[R]
2532\f[B]\f[CB]fontsize\f[B]\f[R]
2533sets the base CSS \f[C]font-size\f[R], which you\[cq]d usually set to
2534e.g.\ \f[C]20px\f[R], but it also accepts \f[C]pt\f[R] (12pt = 16px in
2537\f[B]\f[CB]fontcolor\f[B]\f[R]
2538sets the CSS \f[C]color\f[R] property on the \f[C]html\f[R] element.
2540\f[B]\f[CB]linkcolor\f[B]\f[R]
2541sets the CSS \f[C]color\f[R] property on all links.
2543\f[B]\f[CB]monofont\f[B]\f[R]
2544sets the CSS \f[C]font-family\f[R] property on \f[C]code\f[R] elements.
2546\f[B]\f[CB]monobackgroundcolor\f[B]\f[R]
2547sets the CSS \f[C]background-color\f[R] property on \f[C]code\f[R]
2548elements and adds extra padding.
2550\f[B]\f[CB]linestretch\f[B]\f[R]
2551sets the CSS \f[C]line-height\f[R] property on the \f[C]html\f[R]
2552element, which is preferred to be unitless.
2554\f[B]\f[CB]backgroundcolor\f[B]\f[R]
2555sets the CSS \f[C]background-color\f[R] property on the \f[C]html\f[R]
2558\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]
2559sets the corresponding CSS \f[C]padding\f[R] properties on the
2560\f[C]body\f[R] element.
2562To override or extend some CSS for just one document, include for
2574 background-color: #f0f0f0;
2577 padding: 0.5em 2em 0.5em 0.5em;
2580 border-bottom: none;
2586.SS Variables for HTML math
2588\f[B]\f[CB]classoption\f[B]\f[R]
2589when using KaTeX, you can render display math equations flush left using
2590YAML metadata or with \f[C]-M classoption=fleqn\f[R].
2591.SS Variables for HTML slides
2593These affect HTML output when [producing slide shows with pandoc].
2595All reveal.js configuration options are available as variables.
2596To turn off boolean flags that default to true in reveal.js, use
2599\f[B]\f[CB]revealjs-url\f[B]\f[R]
2600base URL for reveal.js documents (defaults to
2601\f[C]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R])
2603\f[B]\f[CB]s5-url\f[B]\f[R]
2604base URL for S5 documents (defaults to \f[C]s5/default\f[R])
2606\f[B]\f[CB]slidy-url\f[B]\f[R]
2607base URL for Slidy documents (defaults to
2608\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])
2610\f[B]\f[CB]slideous-url\f[B]\f[R]
2611base URL for Slideous documents (defaults to \f[C]slideous\f[R])
2613\f[B]\f[CB]title-slide-attributes\f[B]\f[R]
2614additional attributes for the title slide of reveal.js slide shows.
2615See background in reveal.js and beamer for an example.
2616.SS Variables for Beamer slides
2618These variables change the appearance of PDF slides using
2621\f[B]\f[CB]aspectratio\f[B]\f[R]
2622slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for
262316:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]
2624for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)
2626\f[B]\f[CB]beamerarticle\f[B]\f[R]
2627produce an article from Beamer slides
2629\f[B]\f[CB]beameroption\f[B]\f[R]
2630add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]
2632\f[B]\f[CB]institute\f[B]\f[R]
2633author affiliations: can be a list when there are multiple authors
2635\f[B]\f[CB]logo\f[B]\f[R]
2636logo image for slides
2638\f[B]\f[CB]navigation\f[B]\f[R]
2639controls navigation symbols (default is \f[C]empty\f[R] for no
2640navigation symbols; other valid values are \f[C]frame\f[R],
2641\f[C]vertical\f[R], and \f[C]horizontal\f[R])
2643\f[B]\f[CB]section-titles\f[B]\f[R]
2644enables \[lq]title pages\[rq] for new sections (default is true)
2646\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]
2649\f[B]\f[CB]themeoptions\f[B]\f[R]
2650options for LaTeX beamer themes (a list).
2652\f[B]\f[CB]titlegraphic\f[B]\f[R]
2653image for title slide
2654.SS Variables for PowerPoint
2656These variables control the visual aspects of a slide show that are not
2657easily controlled via templates.
2659\f[B]\f[CB]monofont\f[B]\f[R]
2660font to use for code.
2661.SS Variables for LaTeX
2663Pandoc uses these variables when creating a PDF with a LaTeX engine.
2666\f[B]\f[CB]block-headings\f[B]\f[R]
2667make \f[C]\[rs]paragraph\f[R] and \f[C]\[rs]subparagraph\f[R] (fourth-
2668and fifth-level headings, or fifth- and sixth-level with book classes)
2669free-standing rather than run-in; requires further formatting to
2670distinguish from \f[C]\[rs]subsubsection\f[R] (third- or fourth-level
2672Instead of using this option, KOMA-Script can adjust headings more
2679documentclass: scrartcl
2681 \[rs]RedeclareSectionCommand[
2682 beforeskip=-10pt plus -2pt minus -1pt,
2683 afterskip=1sp plus -1sp minus 1sp,
2684 font=\[rs]normalfont\[rs]itshape]{paragraph}
2685 \[rs]RedeclareSectionCommand[
2686 beforeskip=-10pt plus -2pt minus -1pt,
2687 afterskip=1sp plus -1sp minus 1sp,
2688 font=\[rs]normalfont\[rs]scshape,
2689 indent=0pt]{subparagraph}
2695\f[B]\f[CB]classoption\f[B]\f[R]
2696option for document class, e.g.\ \f[C]oneside\f[R]; repeat for multiple
2711\f[B]\f[CB]documentclass\f[B]\f[R]
2712document class: usually one of the standard classes, \f[C]article\f[R],
2713\f[C]book\f[R], and \f[C]report\f[R]; the KOMA-Script equivalents,
2714\f[C]scrartcl\f[R], \f[C]scrbook\f[R], and \f[C]scrreprt\f[R], which
2715default to smaller margins; or \f[C]memoir\f[R]
2717\f[B]\f[CB]geometry\f[B]\f[R]
2718option for \f[C]geometry\f[R] package, e.g.\ \f[C]margin=1in\f[R];
2719repeat for multiple options:
2734\f[B]\f[CB]hyperrefoptions\f[B]\f[R]
2735option for \f[C]hyperref\f[R] package, e.g.\ \f[C]linktoc=all\f[R];
2736repeat for multiple options:
2745- pdfpagemode=FullScreen
2751\f[B]\f[CB]indent\f[B]\f[R]
2752if true, pandoc will use document class settings for indentation (the
2753default LaTeX template otherwise removes indentation and adds space
2756\f[B]\f[CB]linestretch\f[B]\f[R]
2757adjusts line spacing using the \f[C]setspace\f[R] package,
2758e.g.\ \f[C]1.25\f[R], \f[C]1.5\f[R]
2760\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]
2761sets margins if \f[C]geometry\f[R] is not used (otherwise
2762\f[C]geometry\f[R] overrides these)
2764\f[B]\f[CB]pagestyle\f[B]\f[R]
2765control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports
2766\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page
2767numbers), and \f[C]headings\f[R] (section titles in running heads)
2769\f[B]\f[CB]papersize\f[B]\f[R]
2770paper size, e.g.\ \f[C]letter\f[R], \f[C]a4\f[R]
2772\f[B]\f[CB]secnumdepth\f[B]\f[R]
2773numbering depth for sections (with \f[C]--number-sections\f[R] option or
2774\f[C]numbersections\f[R] variable)
2777\f[B]\f[CB]fontenc\f[B]\f[R]
2778allows font encoding to be specified through \f[C]fontenc\f[R] package
2779(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font
2782\f[B]\f[CB]fontfamily\f[B]\f[R]
2783font package for use with \f[C]pdflatex\f[R]: TeX Live includes many
2784options, documented in the LaTeX Font Catalogue.
2785The default is Latin Modern.
2787\f[B]\f[CB]fontfamilyoptions\f[B]\f[R]
2788options for package used as \f[C]fontfamily\f[R]; repeat for multiple
2790For example, to use the Libertine font with proportional lowercase
2791(old-style) figures through the \f[C]libertinus\f[R] package:
2797fontfamily: libertinus
2806\f[B]\f[CB]fontsize\f[B]\f[R]
2807font size for body text.
2808The standard classes allow 10pt, 11pt, and 12pt.
2809To use another size, set \f[C]documentclass\f[R] to one of the
2810KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].
2812\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]
2813font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take
2814the name of any system font, using the \f[C]fontspec\f[R] package.
2815\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.
2817\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]
2818options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],
2819\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in
2820\f[C]xelatex\f[R] and \f[C]lualatex\f[R].
2821Allow for any choices available through \f[C]fontspec\f[R]; repeat for
2823For example, to use the TeX Gyre version of Palatino with lowercase
2830mainfont: TeX Gyre Pagella
2833- Numbers=Proportional
2839\f[B]\f[CB]microtypeoptions\f[B]\f[R]
2840options to pass to the microtype package
2843\f[B]\f[CB]colorlinks\f[B]\f[R]
2844add color to link text; automatically enabled if any of
2845\f[C]linkcolor\f[R], \f[C]filecolor\f[R], \f[C]citecolor\f[R],
2846\f[C]urlcolor\f[R], or \f[C]toccolor\f[R] are set
2848\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]
2849color for internal links, external links, citation links, linked URLs,
2850and links in table of contents, respectively: uses options allowed by
2851\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],
2852\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists
2854\f[B]\f[CB]links-as-notes\f[B]\f[R]
2855causes links to be printed as footnotes
2858\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2859include list of figures, list of tables
2861\f[B]\f[CB]thanks\f[B]\f[R]
2862contents of acknowledgments footnote after document title
2864\f[B]\f[CB]toc\f[B]\f[R]
2865include table of contents (can also be set using
2866\f[C]--toc/--table-of-contents\f[R])
2868\f[B]\f[CB]toc-depth\f[B]\f[R]
2869level of section to include in table of contents
2870.SS BibLaTeX Bibliographies
2872These variables function when using BibLaTeX for citation rendering.
2874\f[B]\f[CB]biblatexoptions\f[B]\f[R]
2875list of options for biblatex
2877\f[B]\f[CB]biblio-style\f[B]\f[R]
2878bibliography style, when used with \f[C]--natbib\f[R] and
2879\f[C]--biblatex\f[R].
2881\f[B]\f[CB]biblio-title\f[B]\f[R]
2882bibliography title, when used with \f[C]--natbib\f[R] and
2883\f[C]--biblatex\f[R].
2885\f[B]\f[CB]bibliography\f[B]\f[R]
2886bibliography to use for resolving references
2888\f[B]\f[CB]natbiboptions\f[B]\f[R]
2889list of options for natbib
2890.SS Variables for ConTeXt
2892Pandoc uses these variables when creating a PDF with ConTeXt.
2894\f[B]\f[CB]fontsize\f[B]\f[R]
2895font size for body text (e.g.\ \f[C]10pt\f[R], \f[C]12pt\f[R])
2897\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]
2898text to be placed in running header or footer (see ConTeXt Headers and
2899Footers); repeat up to four times for different placement
2901\f[B]\f[CB]indenting\f[B]\f[R]
2902controls indentation of paragraphs, e.g.\ \f[C]yes,small,next\f[R] (see
2903ConTeXt Indentation); repeat for multiple options
2905\f[B]\f[CB]interlinespace\f[B]\f[R]
2906adjusts line spacing, e.g.\ \f[C]4ex\f[R] (using
2907\f[C]setupinterlinespace\f[R]); repeat for multiple options
2909\f[B]\f[CB]layout\f[B]\f[R]
2910options for page margins and text arrangement (see ConTeXt Layout);
2911repeat for multiple options
2913\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]
2914color for links outside and inside a page, e.g.\ \f[C]red\f[R],
2915\f[C]blue\f[R] (see ConTeXt Color)
2917\f[B]\f[CB]linkstyle\f[B]\f[R]
2918typeface style for links, e.g.\ \f[C]normal\f[R], \f[C]bold\f[R],
2919\f[C]slanted\f[R], \f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R],
2922\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2923include list of figures, list of tables
2925\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]
2926font families: take the name of any system font (see ConTeXt Font
2929\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]
2930sets margins, if \f[C]layout\f[R] is not used (otherwise
2931\f[C]layout\f[R] overrides these)
2933\f[B]\f[CB]pagenumbering\f[B]\f[R]
2934page number style and location (using \f[C]setuppagenumbering\f[R]);
2935repeat for multiple options
2937\f[B]\f[CB]papersize\f[B]\f[R]
2938paper size, e.g.\ \f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R]
2939(see ConTeXt Paper Setup); repeat for multiple options
2941\f[B]\f[CB]pdfa\f[B]\f[R]
2942adds to the preamble the setup necessary to generate PDF/A of the type
2943specified, e.g.\ \f[C]1a:2005\f[R], \f[C]2a\f[R].
2944If no type is specified (i.e.\ the value is set to True, by e.g.
2945\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata
2946block), \f[C]1b:2005\f[R] will be used as default, for reasons of
2947backwards compatibility.
2948Using \f[C]--variable=pdfa\f[R] without specified value is not
2950To successfully generate PDF/A the required ICC color profiles have to
2951be available and the content and all included files (such as images)
2952have to be standard conforming.
2953The ICC profiles and output intent may be specified using the variables
2954\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].
2955See also ConTeXt PDFA for more details.
2957\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]
2958when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile
2959to use in the PDF, e.g.\ \f[C]default.cmyk\f[R].
2960If left unspecified, \f[C]sRGB.icc\f[R] is used as default.
2961May be repeated to include multiple profiles.
2962Note that the profiles have to be available on the system.
2963They can be obtained from ConTeXt ICC Profiles.
2965\f[B]\f[CB]pdfaintent\f[B]\f[R]
2966when used in conjunction with \f[C]pdfa\f[R], specifies the output
2967intent for the colors,
2968e.g.\ \f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If
2969left unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
2971\f[B]\f[CB]toc\f[B]\f[R]
2972include table of contents (can also be set using
2973\f[C]--toc/--table-of-contents\f[R])
2975\f[B]\f[CB]whitespace\f[B]\f[R]
2976spacing between paragraphs, e.g.\ \f[C]none\f[R], \f[C]small\f[R] (using
2977\f[C]setupwhitespace\f[R])
2979\f[B]\f[CB]includesource\f[B]\f[R]
2980include all source documents as file attachments in the PDF file
2981.SS Variables for \f[C]wkhtmltopdf\f[R]
2983Pandoc uses these variables when creating a PDF with
2984\f[C]wkhtmltopdf\f[R].
2985The \f[C]--css\f[R] option also affects the output.
2987\f[B]\f[CB]footer-html\f[B]\f[R], \f[B]\f[CB]header-html\f[B]\f[R]
2988add information to the header and footer
2990\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]
2993\f[B]\f[CB]papersize\f[B]\f[R]
2994sets the PDF paper size
2995.SS Variables for man pages
2997\f[B]\f[CB]adjusting\f[B]\f[R]
2998adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center
2999(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins
3001\f[B]\f[CB]footer\f[B]\f[R]
3004\f[B]\f[CB]header\f[B]\f[R]
3007\f[B]\f[CB]hyphenate\f[B]\f[R]
3008if \f[C]true\f[R] (the default), hyphenation will be used
3010\f[B]\f[CB]section\f[B]\f[R]
3011section number in man pages
3014\f[B]\f[CB]fontfamily\f[B]\f[R]
3015font family (e.g.\ \f[C]T\f[R] or \f[C]P\f[R])
3017\f[B]\f[CB]indent\f[B]\f[R]
3018paragraph indent (e.g.\ \f[C]2m\f[R])
3020\f[B]\f[CB]lineheight\f[B]\f[R]
3021line height (e.g.\ \f[C]12p\f[R])
3023\f[B]\f[CB]pointsize\f[B]\f[R]
3024point size (e.g.\ \f[C]10p\f[R])
3025.SS Variables set automatically
3027Pandoc sets these variables automatically in response to options or
3028document contents; users can also modify them.
3029These vary depending on the output format, and include the following:
3031\f[B]\f[CB]body\f[B]\f[R]
3034\f[B]\f[CB]date-meta\f[B]\f[R]
3035the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included
3036in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,
3037s5, slideous, slidy).
3038The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],
3039\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),
3040\f[C]dd MM yyyy\f[R] (e.g.\ either \f[C]02 Apr 2018\f[R] or
3041\f[C]02 April 2018\f[R]), \f[C]MM dd, yyyy\f[R]
3042(e.g.\ \f[C]Apr. 02, 2018\f[R] or
3043\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,
3044\f[C]201804\f[R] or \f[C]2018\f[R]).
3046\f[B]\f[CB]header-includes\f[B]\f[R]
3047contents specified by \f[C]-H/--include-in-header\f[R] (may have
3050\f[B]\f[CB]include-before\f[B]\f[R]
3051contents specified by \f[C]-B/--include-before-body\f[R] (may have
3054\f[B]\f[CB]include-after\f[B]\f[R]
3055contents specified by \f[C]-A/--include-after-body\f[R] (may have
3058\f[B]\f[CB]meta-json\f[B]\f[R]
3059JSON representation of all of the document\[cq]s metadata.
3060Field values are transformed to the selected output format.
3062\f[B]\f[CB]numbersections\f[B]\f[R]
3063non-null value if \f[C]-N/--number-sections\f[R] was specified
3065\f[B]\f[CB]sourcefile\f[B]\f[R], \f[B]\f[CB]outputfile\f[B]\f[R]
3066source and destination filenames, as given on the command line.
3067\f[C]sourcefile\f[R] can also be a list if input comes from multiple
3068files, or empty if input is from stdin.
3069You can use the following snippet in your template to distinguish them:
3084Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the
3087If you need absolute paths, use e.g.\ \f[C]$curdir$/$sourcefile$\f[R].
3090\f[B]\f[CB]curdir\f[B]\f[R]
3091working directory from which pandoc is run.
3093\f[B]\f[CB]toc\f[B]\f[R]
3094non-null value if \f[C]--toc/--table-of-contents\f[R] was specified
3096\f[B]\f[CB]toc-title\f[B]\f[R]
3097title of table of contents (works only with EPUB, HTML, opendocument,
3098odt, docx, pptx, beamer, LaTeX)
3101The behavior of some of the readers and writers can be adjusted by
3102enabling or disabling various extensions.
3104An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format
3105name and disabled by adding \f[C]-EXTENSION\f[R].
3106For example, \f[C]--from markdown_strict+footnotes\f[R] is strict
3107Markdown with footnotes enabled, while
3108\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s Markdown
3109without footnotes or pipe tables.
3111The markdown reader and writer make by far the most use of extensions.
3112Extensions only used by them are therefore covered in the section
3113Pandoc\[cq]s Markdown below (See Markdown variants for
3114\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
3115that also work for other formats are covered.
3117Note that markdown extensions added to the \f[C]ipynb\f[R] format affect
3118Markdown cells in Jupyter notebooks (as do command-line options like
3119\f[C]--atx-headers\f[R]).
3121.SS Extension: \f[C]smart\f[R]
3123Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,
3124\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.
3125Nonbreaking spaces are inserted after certain abbreviations, such as
3128This extension can be enabled/disabled for the following formats:
3131\f[C]markdown\f[R], \f[C]commonmark\f[R], \f[C]latex\f[R],
3132\f[C]mediawiki\f[R], \f[C]org\f[R], \f[C]rst\f[R], \f[C]twiki\f[R]
3135\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R], \f[C]rst\f[R]
3137enabled by default in
3138\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R] (both input and
3141Note: If you are \f[I]writing\f[R] Markdown, then the \f[C]smart\f[R]
3142extension has the reverse effect: what would have been curly quotes
3145In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for
3146quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for
3147double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)
3148and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).
3149If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse
3150these characters literally.
3151In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the
3152ligatures when possible; if \f[C]smart\f[R] is disabled pandoc will use
3153unicode quotation mark and dash characters.
3154.SS Headings and sections
3155.SS Extension: \f[C]auto_identifiers\f[R]
3157A heading without an explicitly specified identifier will be
3158automatically assigned a unique identifier based on the heading text.
3160This extension can be enabled/disabled for the following formats:
3163\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]rst\f[R], \f[C]mediawiki\f[R],
3167\f[C]markdown\f[R], \f[C]muse\f[R]
3169enabled by default in
3170\f[C]markdown\f[R], \f[C]muse\f[R]
3172The default algorithm used to derive the identifier from the heading
3175Remove all formatting, links, etc.
3177Remove all footnotes.
3179Remove all non-alphanumeric characters, except underscores, hyphens, and
3182Replace all spaces and newlines with hyphens.
3184Convert all alphabetic characters to lowercase.
3186Remove everything up to the first letter (identifiers may not begin with
3187a number or punctuation mark).
3189If nothing is left after this, use the identifier \f[C]section\f[R].
3203\f[C]Heading identifiers in HTML\f[R]
3205\f[C]heading-identifiers-in-html\f[R]
3208\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]
3210\f[C]ma\[^i]tre-dh\[^o]tel\f[R]
3213\f[C]*Dogs*?--in *my* house?\f[R]
3215\f[C]dogs--in-my-house\f[R]
3218\f[C][HTML], [S5], or [RTF]?\f[R]
3220\f[C]html-s5-or-rtf\f[R]
3223\f[C]3. Applications\f[R]
3225\f[C]applications\f[R]
3234These rules should, in most cases, allow one to determine the identifier
3235from the heading text.
3236The exception is when several headings have the same text; in this case,
3237the first will get an identifier as described above; the second will get
3238the same identifier with \f[C]-1\f[R] appended; the third with
3239\f[C]-2\f[R]; and so on.
3241(However, a different algorithm is used if
3242\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)
3244These identifiers are used to provide link targets in the table of
3245contents generated by the \f[C]--toc|--table-of-contents\f[R] option.
3246They also make it easy to provide links from one section of a document
3248A link to this section, for example, might look like this:
3253[heading identifiers](#heading-identifiers-in-html-latex-and-context).
3257Note, however, that this method of providing links to sections works
3258only in HTML, LaTeX, and ConTeXt formats.
3260If the \f[C]--section-divs\f[R] option is specified, then each section
3261will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if
3262\f[C]html4\f[R] was specified), and the identifier will be attached to
3263the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than
3265This allows entire sections to be manipulated using JavaScript or
3266treated differently in CSS.
3267.SS Extension: \f[C]ascii_identifiers\f[R]
3269Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure
3271Accents are stripped off of accented Latin letters, and non-Latin
3273.SS Extension: \f[C]gfm_auto_identifiers\f[R]
3275Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
3277Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
3278lowercase characters, and punctuation characters other than \f[C]-\f[R]
3279and \f[C]_\f[R] are removed.
3280Emojis are replaced by their names.
3283The extensions \f[C]tex_math_dollars\f[R],
3284\f[C]tex_math_single_backslash\f[R], and
3285\f[C]tex_math_double_backslash\f[R] are described in the section about
3286Pandoc\[cq]s Markdown.
3288However, they can also be used with HTML input.
3289This is handy for reading web pages formatted using MathJax, for
3293The following extensions are described in more detail in their
3294respective sections of Pandoc\[cq]s Markdown:
3296\f[C]raw_html\f[R] allows HTML elements which are not representable in
3297pandoc\[cq]s AST to be parsed as raw HTML.
3298By default, this is disabled for HTML input.
3300\f[C]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a
3302This extension can be enabled/disabled for the following formats (in
3303addition to \f[C]markdown\f[R]):
3307\f[C]latex\f[R], \f[C]textile\f[R], \f[C]html\f[R] (environments,
3308\f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only), \f[C]ipynb\f[R]
3311\f[C]textile\f[R], \f[C]commonmark\f[R]
3313Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and
3314\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data
3315with mime type \f[C]text/html\f[R] in output cells.
3316Since the \f[C]ipynb\f[R] reader attempts to preserve the richest
3317possible outputs when several options are given, you will get best
3318results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when
3319converting to formats like \f[C]docx\f[R] which don\[cq]t allow raw
3320\f[C]html\f[R] or \f[C]tex\f[R].
3323\f[C]native_divs\f[R] causes HTML \f[C]div\f[R] elements to be parsed as
3324native pandoc Div blocks.
3325If you want them to be parsed as raw HTML, use
3326\f[C]-f html-native_divs+raw_html\f[R].
3328\f[C]native_spans\f[R] causes HTML \f[C]span\f[R] elements to be parsed
3329as native pandoc Span inlines.
3330If you want them to be parsed as raw HTML, use
3331\f[C]-f html-native_spans+raw_html\f[R].
3332If you want to drop all \f[C]div\f[R]s and \f[C]span\f[R]s when
3333converting HTML to Markdown, you can use
3334\f[C]pandoc -f html-native_divs-native_spans -t markdown\f[R].
3335.SS Literate Haskell support
3336.SS Extension: \f[C]literate_haskell\f[R]
3338Treat the document as literate Haskell source.
3340This extension can be enabled/disabled for the following formats:
3343\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R]
3346\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R], \f[C]html\f[R]
3348If you append \f[C]+lhs\f[R] (or \f[C]+literate_haskell\f[R]) to one of
3349the formats above, pandoc will treat the document as literate Haskell
3353In Markdown input, \[lq]bird track\[rq] sections will be parsed as
3354Haskell code rather than block quotations.
3355Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]
3356will also be treated as Haskell code.
3357For ATX-style headings the character `=' will be used instead of `#'.
3359In Markdown output, code blocks with classes \f[C]haskell\f[R] and
3360\f[C]literate\f[R] will be rendered using bird tracks, and block
3361quotations will be indented one space, so they will not be treated as
3363In addition, headings will be rendered setext-style (with underlines)
3364rather than ATX-style (with `#' characters).
3365(This is because ghc treats `#' characters in column 1 as introducing
3368In restructured text input, \[lq]bird track\[rq] sections will be parsed
3371In restructured text output, code blocks with class \f[C]haskell\f[R]
3372will be rendered using bird tracks.
3374In LaTeX input, text in \f[C]code\f[R] environments will be parsed as
3377In LaTeX output, code blocks with class \f[C]haskell\f[R] will be
3378rendered inside \f[C]code\f[R] environments.
3380In HTML output, code blocks with class \f[C]haskell\f[R] will be
3381rendered with class \f[C]literatehaskell\f[R] and bird tracks.
3387pandoc -f markdown+lhs -t html
3391reads literate Haskell source formatted with Markdown conventions and
3392writes ordinary HTML (without bird tracks).
3396pandoc -f markdown+lhs -t html+lhs
3400writes HTML with the Haskell code in bird tracks, so it can be copied
3401and pasted as literate Haskell source.
3403Note that GHC expects the bird tracks in the first column, so indented
3404literate code blocks (e.g.\ inside an itemized environment) will not be
3405picked up by the Haskell compiler.
3407.SS Extension: \f[C]empty_paragraphs\f[R]
3409Allows empty paragraphs.
3410By default empty paragraphs are omitted.
3412This extension can be enabled/disabled for the following formats:
3415\f[C]docx\f[R], \f[C]html\f[R]
3418\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]
3419.SS Extension: \f[C]native_numbering\f[R]
3421Enables native numbering of figures and tables.
3422Enumeration starts at 1.
3424This extension can be enabled/disabled for the following formats:
3427\f[C]odt\f[R], \f[C]opendocument\f[R]
3428.SS Extension: \f[C]xrefs_name\f[R]
3430Links to headings, figures and tables inside the document are
3431substituted with cross-references that will use the name or caption of
3433The original link text is replaced once the generated document is
3435This extension can be combined with \f[C]xrefs_number\f[R] in which case
3436numbers will appear before the name.
3438Text in cross-references is only made consistent with the referenced
3439item once the document has been refreshed.
3441This extension can be enabled/disabled for the following formats:
3444\f[C]odt\f[R], \f[C]opendocument\f[R]
3445.SS Extension: \f[C]xrefs_number\f[R]
3447Links to headings, figures and tables inside the document are
3448substituted with cross-references that will use the number of the
3450The original link text is discarded.
3451This extension can be combined with \f[C]xrefs_name\f[R] in which case
3452the name or caption numbers will appear after the number.
3454For the \f[C]xrefs_number\f[R] to be useful heading numbers must be
3455enabled in the generated document, also table and figure captions must
3456be enabled using for example the \f[C]native_numbering\f[R] extension.
3458Numbers in cross-references are only visible in the final document once
3459it has been refreshed.
3461This extension can be enabled/disabled for the following formats:
3464\f[C]odt\f[R], \f[C]opendocument\f[R]
3465.SS Extension: \f[C]styles\f[R]
3467When converting from docx, read all docx styles as divs (for paragraph
3468styles) and spans (for character styles) regardless of whether pandoc
3469understands the meaning of these styles.
3470This can be used with docx custom styles.
3475.SS Extension: \f[C]amuse\f[R]
3477In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions
3478to Emacs Muse markup.
3479.SS Extension: \f[C]raw_markdown\f[R]
3481In the \f[C]ipynb\f[R] input format, this causes Markdown cells to be
3482included as raw Markdown blocks (allowing lossless round-tripping)
3483rather than being parsed.
3484Use this only when you are targeting \f[C]ipynb\f[R] or a markdown-based
3486.SS Extension: \f[C]citations\f[R]
3488Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted
3489in \f[C]org\f[R] input.
3490.SS Extension: \f[C]element_citations\f[R]
3492In the \f[C]jats\f[R] output formats, this causes reference items to be
3493replaced with \f[C]<element-citation>\f[R] elements.
3494These elements are not influenced by CSL styles, but all information on
3495the item is included in tags.
3496.SS Extension: \f[C]ntb\f[R]
3498In the \f[C]context\f[R] output format this enables the use of Natural
3499Tables (TABLE) instead of the default Extreme Tables (xtables).
3500Natural tables allow more fine-grained global customization but come at
3501a performance penalty compared to extreme tables.
3502.SH PANDOC\[cq]S MARKDOWN
3504Pandoc understands an extended and slightly revised version of John
3505Gruber\[cq]s Markdown syntax.
3506This document explains the syntax, noting differences from standard
3508Except where noted, these differences can be suppressed by using the
3509\f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R].
3510Extensions can be enabled or disabled to specify the behavior more
3512They are described in the following.
3513See also Extensions above, for extensions that work also on other
3517Markdown is designed to be easy to write, and, even more importantly,
3521A Markdown-formatted document should be publishable as-is, as plain
3522text, without looking like it\[cq]s been marked up with tags or
3523formatting instructions.
3527This principle has guided pandoc\[cq]s decisions in finding syntax for
3528tables, footnotes, and other extensions.
3530There is, however, one respect in which pandoc\[cq]s aims are different
3531from the original aims of Markdown.
3532Whereas Markdown was originally designed with HTML generation in mind,
3533pandoc is designed for multiple output formats.
3534Thus, while pandoc allows the embedding of raw HTML, it discourages it,
3535and provides other, non-HTMLish ways of representing important document
3536elements like definition lists, tables, mathematics, and footnotes.
3539A paragraph is one or more lines of text followed by one or more blank
3541Newlines are treated as spaces, so you can reflow your paragraphs as you
3543If you need a hard line break, put two or more spaces at the end of a
3545.SS Extension: \f[C]escaped_line_breaks\f[R]
3547A backslash followed by a newline is also a hard line break.
3548Note: in multiline and grid table cells, this is the only way to create
3549a hard line break, since trailing spaces in the cells are ignored.
3552There are two kinds of headings: Setext and ATX.
3553.SS Setext-style headings
3555A setext-style heading is a line of text \[lq]underlined\[rq] with a row
3556of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for
3557a level-two heading):
3569The heading text can contain inline formatting, such as emphasis (see
3570Inline formatting, below).
3571.SS ATX-style headings
3573An ATX-style heading consists of one to six \f[C]#\f[R] signs and a line
3574of text, optionally followed by any number of \f[C]#\f[R] signs.
3575The number of \f[C]#\f[R] signs at the beginning of the line is the
3580## A level-two heading
3582### A level-three heading ###
3586As with setext-style headings, the heading text can contain formatting:
3590# A level-one heading with a [link](/url) and *emphasis*
3593.SS Extension: \f[C]blank_before_header\f[R]
3595Standard Markdown syntax does not require a blank line before a heading.
3596Pandoc does require this (except, of course, at the beginning of the
3598The reason for the requirement is that it is all too easy for a
3599\f[C]#\f[R] to end up at the beginning of a line by accident (perhaps
3600through line wrapping).
3601Consider, for example:
3605I like several of their flavors of ice cream:
3606#22, for example, and #5.
3609.SS Extension: \f[C]space_in_atx_header\f[R]
3611Many Markdown implementations do not require a space between the opening
3612\f[C]#\f[R]s of an ATX heading and the heading text, so that
3613\f[C]#5 bolt\f[R] and \f[C]#hashtag\f[R] count as headings.
3614With this extension, pandoc does require the space.
3615.SS Heading identifiers
3617See also the \f[C]auto_identifiers\f[R] extension above.
3618.SS Extension: \f[C]header_attributes\f[R]
3620Headings can be assigned attributes using this syntax at the end of the
3621line containing the heading text:
3625{#identifier .class .class key=value key=value}
3629Thus, for example, the following headings will all be assigned the
3630identifier \f[C]foo\f[R]:
3636## My heading ## {#foo}
3638My other heading {#foo}
3643(This syntax is compatible with PHP Markdown Extra.)
3645Note that although this syntax allows assignment of classes and
3646key/value attributes, writers generally don\[cq]t use all of this
3648Identifiers, classes, and key/value attributes are used in HTML and
3649HTML-based formats such as EPUB and slidy.
3650Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,
3651Textile, Jira markup, and AsciiDoc writers.
3653Headings with the class \f[C]unnumbered\f[R] will not be numbered, even
3654if \f[C]--number-sections\f[R] is specified.
3655A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to
3656\f[C].unnumbered\f[R], and preferable in non-English documents.
3669# My heading {.unnumbered}
3673If the \f[C]unlisted\f[R] class is present in addition to
3674\f[C]unnumbered\f[R], the heading will not be included in a table of
3676(Currently this feature is only implemented for certain formats: those
3677based on LaTeX and HTML, PowerPoint, and RTF.)
3678.SS Extension: \f[C]implicit_header_references\f[R]
3680Pandoc behaves as if reference links have been defined for each heading.
3681So, to link to a heading
3685# Heading identifiers in HTML
3693[Heading identifiers in HTML]
3701[Heading identifiers in HTML][]
3709[the section on heading identifiers][heading identifiers in
3714instead of giving the identifier explicitly:
3718[Heading identifiers in HTML](#heading-identifiers-in-html)
3722If there are multiple headings with identical text, the corresponding
3723reference will link to the first one only, and you will need to use
3724explicit links to link to the others, as described above.
3726Like regular reference links, these references are case-insensitive.
3728Explicit link reference definitions always take priority over implicit
3730So, in the following example, the link will point to \f[C]bar\f[R], not
3744Markdown uses email conventions for quoting blocks of text.
3745A block quotation is one or more paragraphs or other block elements
3746(such as lists or headings), with each line preceded by a \f[C]>\f[R]
3747character and an optional space.
3748(The \f[C]>\f[R] need not start at the left margin, but it should not be
3749indented more than three spaces.)
3753> This is a block quote. This
3754> paragraph has two lines.
3756> 1. This is a list inside a block quote.
3761A \[lq]lazy\[rq] form, which requires the \f[C]>\f[R] character only on
3762the first line of each block, is also allowed:
3766> This is a block quote. This
3767paragraph has two lines.
3769> 1. This is a list inside a block quote.
3774Among the block elements that can be contained in a block quote are
3776That is, block quotes can be nested:
3780> This is a block quote.
3782> > A block quote within a block quote.
3786If the \f[C]>\f[R] character is followed by an optional space, that
3787space will be considered part of the block quote marker and not part of
3788the indentation of the contents.
3789Thus, to put an indented code block in a block quote, you need five
3790spaces after the \f[C]>\f[R]:
3797.SS Extension: \f[C]blank_before_blockquote\f[R]
3799Standard Markdown syntax does not require a blank line before a block
3801Pandoc does require this (except, of course, at the beginning of the
3803The reason for the requirement is that it is all too easy for a
3804\f[C]>\f[R] to end up at the beginning of a line by accident (perhaps
3805through line wrapping).
3806So, unless the \f[C]markdown_strict\f[R] format is used, the following
3807does not produce a nested block quote in pandoc:
3811> This is a block quote.
3815.SS Verbatim (code) blocks
3816.SS Indented code blocks
3818A block of text indented four spaces (or one tab) is treated as verbatim
3819text: that is, special characters do not trigger special formatting, and
3820all spaces and line breaks are preserved.
3826 moveShip(5 * gravity, DOWN);
3831The initial (four space or one tab) indentation is not considered part
3832of the verbatim text, and is removed in the output.
3834Note: blank lines in the verbatim text need not begin with four spaces.
3835.SS Fenced code blocks
3836.SS Extension: \f[C]fenced_code_blocks\f[R]
3838In addition to standard indented code blocks, pandoc supports
3839\f[I]fenced\f[R] code blocks.
3840These begin with a row of three or more tildes (\f[C]\[ti]\f[R]) and end
3841with a row of tildes that must be at least as long as the starting row.
3842Everything between these lines is treated as code.
3843No indentation is necessary:
3847\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3849 moveShip(5 * gravity, DOWN);
3851\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3855Like regular code blocks, fenced code blocks must be separated from
3856surrounding text by blank lines.
3858If the code itself contains a row of tildes or backticks, just use a
3859longer row of tildes or backticks at the start and end:
3863\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3864\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3865code including tildes
3866\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3867\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]
3870.SS Extension: \f[C]backtick_code_blocks\f[R]
3872Same as \f[C]fenced_code_blocks\f[R], but uses backticks
3873(\f[C]\[ga]\f[R]) instead of tildes (\f[C]\[ti]\f[R]).
3874.SS Extension: \f[C]fenced_code_attributes\f[R]
3876Optionally, you may attach attributes to fenced or backtick code block
3881\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}
3883qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3884 qsort (filter (>= x) xs)
3885\[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]
3889Here \f[C]mycode\f[R] is an identifier, \f[C]haskell\f[R] and
3890\f[C]numberLines\f[R] are classes, and \f[C]startFrom\f[R] is an
3891attribute with value \f[C]100\f[R].
3892Some output formats can use this information to do syntax highlighting.
3893Currently, the only output formats that uses this information are HTML,
3894LaTeX, Docx, Ms, and PowerPoint.
3895If highlighting is supported for your output format and language, then
3896the code block above will appear highlighted, with numbered lines.
3897(To see which languages are supported, type
3898\f[C]pandoc --list-highlight-languages\f[R].) Otherwise, the code block
3899above will appear as follows:
3903<pre id=\[dq]mycode\[dq] class=\[dq]haskell numberLines\[dq] startFrom=\[dq]100\[dq]>
3911The \f[C]numberLines\f[R] (or \f[C]number-lines\f[R]) class will cause
3912the lines of the code block to be numbered, starting with \f[C]1\f[R] or
3913the value of the \f[C]startFrom\f[R] attribute.
3914The \f[C]lineAnchors\f[R] (or \f[C]line-anchors\f[R]) class will cause
3915the lines to be clickable anchors in HTML output.
3917A shortcut form can also be used for specifying the language of the code
3922\[ga]\[ga]\[ga]haskell
3928This is equivalent to:
3932\[ga]\[ga]\[ga] {.haskell}
3938If the \f[C]fenced_code_attributes\f[R] extension is disabled, but input
3939contains class attribute(s) for the code block, the first class
3940attribute will be printed after the opening fence as a bare word.
3942To prevent all highlighting, use the \f[C]--no-highlight\f[R] flag.
3943To set the highlighting style, use \f[C]--highlight-style\f[R].
3944For more information on highlighting, see Syntax highlighting, below.
3946.SS Extension: \f[C]line_blocks\f[R]
3948A line block is a sequence of lines beginning with a vertical bar
3949(\f[C]|\f[R]) followed by a space.
3950The division into lines will be preserved in the output, as will any
3951leading spaces; otherwise, the lines will be formatted as Markdown.
3952This is useful for verse and addresses:
3956| The limerick packs laughs anatomical
3957| In space that is quite economical.
3958| But the good ones I\[aq]ve seen
3959| So seldom are clean
3960| And the clean ones so seldom are comical
3967The lines can be hard-wrapped if needed, but the continuation line must
3972| The Right Honorable Most Venerable and Righteous Samuel L.
3979Inline formatting (such as emphasis) is allowed in the content, but not
3980block-level formatting (such as block quotes or lists).
3982This syntax is borrowed from reStructuredText.
3986A bullet list is a list of bulleted list items.
3987A bulleted list item begins with a bullet (\f[C]*\f[R], \f[C]+\f[R], or
3989Here is a simple example:
3999This will produce a \[lq]compact\[rq] list.
4000If you want a \[lq]loose\[rq] list, in which each item is formatted as a
4001paragraph, put spaces between the items:
4013The bullets need not be flush with the left margin; they may be indented
4014one, two, or three spaces.
4015The bullet must be followed by whitespace.
4017List items look best if subsequent lines are flush with the first line
4028But Markdown also allows a \[lq]lazy\[rq] format:
4037.SS Block content in list items
4039A list item may contain multiple paragraphs and other block-level
4041However, subsequent paragraphs must be preceded by a blank line and
4042indented to line up with the first non-space content after the list
4051 * Second paragraph. With a code block, which must be indented
4058Exception: if the list marker is followed by an indented code block,
4059which must begin 5 spaces after the list marker, then subsequent
4060paragraphs must begin two columns after the last character of the list
4067 continuation paragraph
4071List items may include other lists.
4072In this case the preceding blank line is optional.
4073The nested list must be indented to line up with the first non-space
4074character after the list marker of the containing list item.
4090As noted above, Markdown allows you to write list items
4091\[lq]lazily,\[rq] instead of indenting continuation lines.
4092However, if there are multiple paragraphs or other blocks in a list
4093item, the first line of each must be indented.
4100+ Another one; this looks
4103 Second paragraph of second
4109Ordered lists work just like bulleted lists, except that the items begin
4110with enumerators rather than bullets.
4112In standard Markdown, enumerators are decimal numbers followed by a
4114The numbers themselves are ignored, so there is no difference between
4134.SS Extension: \f[C]fancy_lists\f[R]
4136Unlike standard Markdown, pandoc allows ordered list items to be marked
4137with uppercase and lowercase letters and roman numerals, in addition to
4139List markers may be enclosed in parentheses or followed by a single
4140right-parentheses or period.
4141They must be separated from the text that follows by at least one space,
4142and, if the list marker is a capital letter with a period, by at least
4145The \f[C]fancy_lists\f[R] extension also allows `\f[C]#\f[R]' to be used
4146as an ordered list marker in place of a numeral:
4154.SS Extension: \f[C]startnum\f[R]
4156Pandoc also pays attention to the type of list marker used, and to the
4157starting number, and both of these are preserved where possible in the
4159Thus, the following yields a list with numbers followed by a single
4160parenthesis, starting with 9, and a sublist with lowercase roman
4174Pandoc will start a new list each time a different type of list marker
4176So, the following will create three lists:
4187If default list markers are desired, use \f[C]#.\f[R]:
4196.SS Extension: \f[C]task_lists\f[R]
4198Pandoc supports task lists, using the syntax of GitHub-Flavored
4203- [ ] an unchecked task list item
4208.SS Extension: \f[C]definition_lists\f[R]
4210Pandoc supports definition lists, using the syntax of PHP Markdown Extra
4211with some extensions.
4219Term 2 with *inline markup*
4223 { some code, part of Definition 2 }
4225 Third paragraph of definition 2.
4229Each term must fit on one line, which may optionally be followed by a
4230blank line, and must be followed by one or more definitions.
4231A definition begins with a colon or tilde, which may be indented one or
4234A term may have multiple definitions, and each definition may consist of
4235one or more block elements (paragraph, code block, list, etc.), each
4236indented four spaces or one tab stop.
4237The body of the definition (including the first line, aside from the
4238colon or tilde) should be indented four spaces.
4239However, as with other Markdown lists, you can \[lq]lazily\[rq] omit
4240indentation except at the beginning of a paragraph or other block
4248with lazy continuation.
4250 Second paragraph of the definition.
4254If you leave space before the definition (as in the example above), the
4255text of the definition will be treated as a paragraph.
4256In some output formats, this will mean greater spacing between
4257term/definition pairs.
4258For a more compact definition list, omit the space before the
4272Note that space between items in a definition list is required.
4273(A variant that loosens this requirement, but disallows \[lq]lazy\[rq]
4274hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
4275see Non-pandoc extensions, below.)
4276.SS Numbered example lists
4277.SS Extension: \f[C]example_lists\f[R]
4279The special list marker \f[C]\[at]\f[R] can be used for sequentially
4281The first list item with a \f[C]\[at]\f[R] marker will be numbered `1',
4282the next `2', and so on, throughout the document.
4283The numbered examples need not occur in a single list; each new list
4284using \f[C]\[at]\f[R] will take up where the last stopped.
4289(\[at]) My first example will be numbered (1).
4290(\[at]) My second example will be numbered (2).
4292Explanation of examples.
4294(\[at]) My third example will be numbered (3).
4298Numbered examples can be labeled and referred to elsewhere in the
4303(\[at]good) This is a good example.
4305As (\[at]good) illustrates, ...
4309The label can be any string of alphanumeric characters, underscores, or
4312Note: continuation paragraphs in example lists must always be indented
4313four spaces, regardless of the length of the list marker.
4314That is, example lists always behave as if the \f[C]four_space_rule\f[R]
4316This is because example labels tend to be long, and indenting content to
4317the first non-space character after the label would be awkward.
4320What if you want to put an indented code block after a list?
4331Trouble! Here pandoc (like other Markdown implementations) will treat
4332\f[C]{ my code block }\f[R] as the second paragraph of item two, and not
4335To \[lq]cut off\[rq] the list after item two, you can insert some
4336non-indented content, like an HTML comment, which won\[cq]t produce
4337visible output in any format:
4350You can use the same trick if you want two consecutive lists instead of
4368A line containing a row of three or more \f[C]*\f[R], \f[C]-\f[R], or
4369\f[C]_\f[R] characters (optionally separated by spaces) produces a
4381Four kinds of tables may be used.
4382The first three kinds presuppose the use of a fixed-width font, such as
4384The fourth kind can be used with proportionally spaced fonts, as it does
4385not require lining up columns.
4386.SS Extension: \f[C]table_captions\f[R]
4388A caption may optionally be provided with all 4 kinds of tables (as
4389illustrated in the examples below).
4390A caption is a paragraph beginning with the string \f[C]Table:\f[R] (or
4391just \f[C]:\f[R]), which will be stripped off.
4392It may appear either before or after the table.
4393.SS Extension: \f[C]simple_tables\f[R]
4395Simple tables look like this:
4399 Right Left Center Default
4400------- ------ ---------- -------
4405Table: Demonstration of simple table syntax.
4409The header and table rows must each fit on one line.
4410Column alignments are determined by the position of the header text
4411relative to the dashed line below it:
4413If the dashed line is flush with the header text on the right side but
4414extends beyond it on the left, the column is right-aligned.
4416If the dashed line is flush with the header text on the left side but
4417extends beyond it on the right, the column is left-aligned.
4419If the dashed line extends beyond the header text on both sides, the
4422If the dashed line is flush with the header text on both sides, the
4423default alignment is used (in most cases, this will be left).
4425The table must end with a blank line, or a line of dashes followed by a
4428The column header row may be omitted, provided a dashed line is used to
4434------- ------ ---------- -------
4438------- ------ ---------- -------
4442When the header row is omitted, column alignments are determined on the
4443basis of the first line of the table body.
4444So, in the tables above, the columns would be right, left, center, and
4445right aligned, respectively.
4446.SS Extension: \f[C]multiline_tables\f[R]
4448Multiline tables allow header and table rows to span multiple lines of
4449text (but cells that span multiple columns or rows of the table are not
4455-------------------------------------------------------------
4456 Centered Default Right Left
4457 Header Aligned Aligned Aligned
4458----------- ------- --------------- -------------------------
4459 First row 12.0 Example of a row that
4460 spans multiple lines.
4462 Second row 5.0 Here\[aq]s another one. Note
4463 the blank line between
4465-------------------------------------------------------------
4467Table: Here\[aq]s the caption. It, too, may span
4472These work like simple tables, but with the following differences:
4474They must begin with a row of dashes, before the header text (unless the
4475header row is omitted).
4477They must end with a row of dashes, then a blank line.
4479The rows must be separated by blank lines.
4481In multiline tables, the table parser pays attention to the widths of
4482the columns, and the writers try to reproduce these relative widths in
4484So, if you find that one of the columns is too narrow in the output, try
4485widening it in the Markdown source.
4487The header may be omitted in multiline tables as well as simple tables:
4491----------- ------- --------------- -------------------------
4492 First row 12.0 Example of a row that
4493 spans multiple lines.
4495 Second row 5.0 Here\[aq]s another one. Note
4496 the blank line between
4498----------- ------- --------------- -------------------------
4500: Here\[aq]s a multiline table without a header.
4504It is possible for a multiline table to have just one row, but the row
4505should be followed by a blank line (and then the row of dashes that ends
4506the table), or the table may be interpreted as a simple table.
4507.SS Extension: \f[C]grid_tables\f[R]
4509Grid tables look like this:
4515+---------------+---------------+--------------------+
4516| Fruit | Price | Advantages |
4517+===============+===============+====================+
4518| Bananas | $1.34 | - built-in wrapper |
4519| | | - bright color |
4520+---------------+---------------+--------------------+
4521| Oranges | $2.10 | - cures scurvy |
4523+---------------+---------------+--------------------+
4527The row of \f[C]=\f[R]s separates the header from the table body, and
4528can be omitted for a headerless table.
4529The cells of grid tables may contain arbitrary block elements (multiple
4530paragraphs, code blocks, lists, etc.).
4531Cells that span multiple columns or rows are not supported.
4532Grid tables can be created easily using Emacs\[cq] table-mode
4533(\f[C]M-x table-insert\f[R]).
4535Alignments can be specified as with pipe tables, by putting colons at
4536the boundaries of the separator line after the header:
4540+---------------+---------------+--------------------+
4541| Right | Left | Centered |
4542+==============:+:==============+:==================:+
4543| Bananas | $1.34 | built-in wrapper |
4544+---------------+---------------+--------------------+
4548For headerless tables, the colons go on the top line instead:
4552+--------------:+:--------------+:------------------:+
4553| Right | Left | Centered |
4554+---------------+---------------+--------------------+
4557.SS Grid Table Limitations
4559Pandoc does not support grid tables with row spans or column spans.
4560This means that neither variable numbers of columns across rows nor
4561variable numbers of rows across columns are supported by Pandoc.
4562All grid tables must have the same number of columns in each row, and
4563the same number of rows in each column.
4564For example, the Docutils sample grid tables will not render as expected
4566.SS Extension: \f[C]pipe_tables\f[R]
4568Pipe tables look like this:
4572| Right | Left | Default | Center |
4573|------:|:-----|---------|:------:|
4574| 12 | 12 | 12 | 12 |
4575| 123 | 123 | 123 | 123 |
4578 : Demonstration of pipe table syntax.
4582The syntax is identical to PHP Markdown Extra tables.
4583The beginning and ending pipe characters are optional, but pipes are
4584required between all columns.
4585The colons indicate column alignment as shown.
4586The header cannot be omitted.
4587To simulate a headerless table, include a header with blank cells.
4589Since the pipes indicate column boundaries, columns need not be
4590vertically aligned, as they are in the above example.
4591So, this is a perfectly legal (though ugly) pipe table:
4603The cells of pipe tables cannot contain block elements like paragraphs
4604and lists, and cannot span multiple lines.
4605If a pipe table contains a row whose Markdown content is wider than the
4606column width (see \f[C]--columns\f[R]), then the table will take up the
4607full text width and the cell contents will wrap, with the relative cell
4608widths determined by the number of dashes in the line separating the
4609table header from the table body.
4610(For example \f[C]---|-\f[R] would make the first column 3/4 and the
4611second column 1/4 of the full text width.) On the other hand, if no
4612lines are wider than column width, then cell contents will not be
4613wrapped, and the cells will be sized to their contents.
4615Note: pandoc also recognizes pipe tables of the following form, as can
4616be produced by Emacs\[cq] orgtbl-mode:
4627The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].
4628Other orgtbl features are not supported.
4629In particular, to get non-default column alignment, you\[cq]ll need to
4632.SS Extension: \f[C]pandoc_title_block\f[R]
4634If the file begins with a title block
4639% author(s) (separated by semicolons)
4644it will be parsed as bibliographic information, not regular text.
4645(It will be used, for example, in the title of standalone LaTeX or HTML
4646output.) The block may contain just a title, a title and an author, or
4648If you want to include an author but no title, or a title and a date but
4649no author, you need a blank line:
4666The title may occupy multiple lines, but continuation lines must begin
4667with leading space, thus:
4676If a document has multiple authors, the authors may be put on separate
4677lines with leading space, or separated by semicolons, or both.
4678So, all of the following are equivalent:
4689% Author One; Author Two
4700The date must fit on one line.
4702All three metadata fields may contain standard inline formatting
4703(italics, links, footnotes, etc.).
4705Title blocks will always be parsed, but they will affect the output only
4706when the \f[C]--standalone\f[R] (\f[C]-s\f[R]) option is chosen.
4707In HTML output, titles will appear twice: once in the document head
4708\[en] this is the title that will appear at the top of the window in a
4709browser \[en] and once at the beginning of the document body.
4710The title in the document head can have an optional prefix attached
4711(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).
4712The title in the body appears as an H1 element with class
4713\[lq]title\[rq], so it can be suppressed or reformatted with CSS.
4714If a title prefix is specified with \f[C]-T\f[R] and no title block
4715appears in the document, the title prefix will be used by itself as the
4718The man page writer extracts a title, man page section number, and other
4719header and footer information from the title line.
4720The title is assumed to be the first word on the title line, which may
4721optionally end with a (single-digit) section number in parentheses.
4722(There should be no space between the title and the parentheses.)
4723Anything after this is assumed to be additional footer and header text.
4724A single pipe character (\f[C]|\f[R]) should be used to separate the
4725footer text from the header text.
4734will yield a man page with the title \f[C]PANDOC\f[R] and section 1.
4738% PANDOC(1) Pandoc User Manuals
4742will also have \[lq]Pandoc User Manuals\[rq] in the footer.
4746% PANDOC(1) Pandoc User Manuals | Version 4.0
4750will also have \[lq]Version 4.0\[rq] in the header.
4751.SS Extension: \f[C]yaml_metadata_block\f[R]
4753A YAML metadata block is a valid YAML object, delimited by a line of
4754three hyphens (\f[C]---\f[R]) at the top and a line of three hyphens
4755(\f[C]---\f[R]) or three dots (\f[C]...\f[R]) at the bottom.
4756A YAML metadata block may occur anywhere in the document, but if it is
4757not at the beginning, it must be preceded by a blank line.
4758(Note that, because of the way pandoc concatenates input files when
4759several are provided, you may also keep the metadata in a separate YAML
4760file and pass it to pandoc as an argument, along with your Markdown
4765pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
4769Just be sure that the YAML file begins with \f[C]---\f[R] and ends with
4770\f[C]---\f[R] or \f[C]...\f[R].) Alternatively, you can use the
4771\f[C]--metadata-file\f[R] option.
4772Using that approach however, you cannot reference content (like
4773footnotes) from the main markdown input document.
4775Metadata will be taken from the fields of the YAML object and added to
4776any existing document metadata.
4777Metadata can contain lists and objects (nested arbitrarily), but all
4778string scalars will be interpreted as Markdown.
4779Fields with names ending in an underscore will be ignored by pandoc.
4780(They may be given a role by external processors.) Field names must not
4781be interpretable as YAML numbers or boolean values (so, for example,
4782\f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot be used as field
4785A document may contain multiple metadata blocks.
4786If two metadata blocks attempt to set the same field, the value from the
4787second block will be taken.
4789When pandoc is used with \f[C]-t markdown\f[R] to create a Markdown
4790document, a YAML metadata block will be produced only if the
4791\f[C]-s/--standalone\f[R] option is used.
4792All of the metadata will appear in a single block at the beginning of
4795Note that YAML escaping rules must be followed.
4796Thus, for example, if a title contains a colon, it must be quoted.
4797The pipe character (\f[C]|\f[R]) can be used to begin an indented block
4798that will be interpreted literally, without need for escaping.
4799This form is necessary when the field contains blank lines or
4800block-level formatting:
4805title: \[aq]This is the title: it contains a colon\[aq]
4809keywords: [nothing, nothingness]
4811 This is the abstract.
4813 It consists of two paragraphs.
4818Template variables will be set automatically from the metadata.
4819Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will
4820be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]
4825<p>This is the abstract.</p>
4826<p>It consists of two paragraphs.</p>
4830Variables can contain arbitrary YAML structures, but the template must
4831match this structure.
4832The \f[C]author\f[R] variable in the default templates expects a simple
4833list or string, but can be changed to support more complicated
4835The following combination, for example, would add an affiliation to the
4836author if one is given:
4841title: The document title
4844 affiliation: University of Somewhere
4846 affiliation: University of Nowhere
4851To use the structured authors in the example above, you would need a
4858$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
4866Raw content to include in the document\[cq]s header may be specified
4867using \f[C]header-includes\f[R]; however, it is important to mark up
4868this content as raw code for a particular output format, using the
4869\f[C]raw_attribute\f[R] extension), or it will be interpreted as
4877 \[ga]\[ga]\[ga]{=latex}
4878 \[rs]let\[rs]oldsection\[rs]section
4879 \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}}
4883.SS Backslash escapes
4884.SS Extension: \f[C]all_symbols_escapable\f[R]
4886Except inside a code block or inline code, any punctuation or space
4887character preceded by a backslash will be treated literally, even if it
4888would normally indicate formatting.
4889Thus, for example, if one writes
4909<strong>hello</strong>
4913This rule is easier to remember than standard Markdown\[cq]s rule, which
4914allows only the following characters to be backslash-escaped:
4918\[rs]\[ga]*_{}[]()>#+-.!
4922(However, if the \f[C]markdown_strict\f[R] format is used, the standard
4923Markdown rule will be used.)
4925A backslash-escaped space is parsed as a nonbreaking space.
4926In TeX output, it will appear as \f[C]\[ti]\f[R].
4927In HTML and XML output, it will appear as a literal unicode nonbreaking
4928space character (note that it will thus actually look
4929\[lq]invisible\[rq] in the generated HTML source; you can still use the
4930\f[C]--ascii\f[R] command-line option to make it appear as an explicit
4933A backslash-escaped newline (i.e.\ a backslash occurring at the end of a
4934line) is parsed as a hard line break.
4935It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as
4937This is a nice alternative to Markdown\[cq]s \[lq]invisible\[rq] way of
4938indicating hard line breaks using two trailing spaces on a line.
4940Backslash escapes do not work in verbatim contexts.
4941.SS Inline formatting
4944To \f[I]emphasize\f[R] some text, surround it with \f[C]*\f[R]s or
4945\f[C]_\f[R], like this:
4949This text is _emphasized with underscores_, and this
4950is *emphasized with asterisks*.
4954Double \f[C]*\f[R] or \f[C]_\f[R] produces \f[B]strong emphasis\f[R]:
4958This is **strong emphasis** and __with underscores__.
4962A \f[C]*\f[R] or \f[C]_\f[R] character surrounded by spaces, or
4963backslash-escaped, will not trigger emphasis:
4967This is * not emphasized *, and \[rs]*neither is this\[rs]*.
4970.SS Extension: \f[C]intraword_underscores\f[R]
4972Because \f[C]_\f[R] is sometimes used inside words and identifiers,
4973pandoc does not interpret a \f[C]_\f[R] surrounded by alphanumeric
4974characters as an emphasis marker.
4975If you want to emphasize just part of a word, use \f[C]*\f[R]:
4979feas*ible*, not feas*able*.
4983.SS Extension: \f[C]strikeout\f[R]
4985To strikeout a section of text with a horizontal line, begin and end it
4986with \f[C]\[ti]\[ti]\f[R].
4991This \[ti]\[ti]is deleted text.\[ti]\[ti]
4994.SS Superscripts and subscripts
4995.SS Extension: \f[C]superscript\f[R], \f[C]subscript\f[R]
4997Superscripts may be written by surrounding the superscripted text by
4998\f[C]\[ha]\f[R] characters; subscripts may be written by surrounding the
4999subscripted text by \f[C]\[ti]\f[R] characters.
5004H\[ti]2\[ti]O is a liquid. 2\[ha]10\[ha] is 1024.
5008The text between \f[C]\[ha]...\[ha]\f[R] or \f[C]\[ti]...\[ti]\f[R] may
5009not contain spaces or newlines.
5010If the superscripted or subscripted text contains spaces, these spaces
5011must be escaped with backslashes.
5012(This is to prevent accidental superscripting and subscripting through
5013the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad
5014interactions with footnotes.) Thus, if you want the letter P with `a
5015cat' in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
5016\f[C]P\[ti]a cat\[ti]\f[R].
5019To make a short span of text verbatim, put it inside backticks:
5023What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]?
5027If the verbatim text includes a backtick, use double backticks:
5031Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga].
5035(The spaces after the opening backticks and before the closing backticks
5038The general rule is that a verbatim span starts with a string of
5039consecutive backticks (optionally followed by a space) and ends with a
5040string of the same number of backticks (optionally preceded by a space).
5042Note that backslash-escapes (and other Markdown constructs) do not work
5043in verbatim contexts:
5047This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga].
5050.SS Extension: \f[C]inline_code_attributes\f[R]
5052Attributes can be attached to verbatim text, just as with fenced code
5057\[ga]<$>\[ga]{.haskell}
5062To write small caps, use the \f[C]smallcaps\f[R] class:
5066[Small caps]{.smallcaps}
5070Or, without the \f[C]bracketed_spans\f[R] extension:
5074<span class=\[dq]smallcaps\[dq]>Small caps</span>
5078For compatibility with other Markdown flavors, CSS is also supported:
5082<span style=\[dq]font-variant:small-caps;\[dq]>Small caps</span>
5086This will work in all output formats that support small caps.
5088.SS Extension: \f[C]tex_math_dollars\f[R]
5090Anything between two \f[C]$\f[R] characters will be treated as TeX math.
5091The opening \f[C]$\f[R] must have a non-space character immediately to
5092its right, while the closing \f[C]$\f[R] must have a non-space character
5093immediately to its left, and must not be followed immediately by a
5095Thus, \f[C]$20,000 and $30,000\f[R] won\[cq]t parse as math.
5096If for some reason you need to enclose text in literal \f[C]$\f[R]
5097characters, backslash-escape them and they won\[cq]t be treated as math
5100For display math, use \f[C]$$\f[R] delimiters.
5101(In this case, the delimiters may be separated from the formula by
5103However, there can be no blank lines betwen the opening and closing
5104\f[C]$$\f[R] delimiters.)
5106TeX math will be printed in all output formats.
5107How it is rendered depends on the output format:
5110It will appear verbatim surrounded by \f[C]\[rs](...\[rs])\f[R] (for
5111inline math) or \f[C]\[rs][...\[rs]]\f[R] (for display math).
5113Markdown, Emacs Org mode, ConTeXt, ZimWiki
5114It will appear verbatim surrounded by \f[C]$...$\f[R] (for inline math)
5115or \f[C]$$...$$\f[R] (for display math).
5118It will appear verbatim surrounded by
5119\f[C]{{formula}}..{{/formula}}\f[R].
5122It will be rendered using an interpreted text role \f[C]:math:\f[R].
5125For AsciiDoc output format (\f[C]-t asciidoc\f[R]) it will appear
5126verbatim surrounded by \f[C]latexmath:[$...$]\f[R] (for inline math) or
5127\f[C][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math).
5128For AsciiDoctor output format (\f[C]-t asciidoctor\f[R]) the LaTex
5129delimiters (\f[C]$..$\f[R] and \f[C]\[rs][..\[rs]]\f[R]) are omitted.
5132It will be rendered inside a \f[C]\[at]math\f[R] command.
5134roff man, Jira markup
5135It will be rendered verbatim without \f[C]$\f[R]\[cq]s.
5138It will be rendered inside \f[C]<math>\f[R] tags.
5141It will be rendered inside \f[C]<span class=\[dq]math\[dq]>\f[R] tags.
5144It will be rendered, if possible, using Unicode characters, and will
5145otherwise appear verbatim.
5148It will be rendered, if possible, using MathML.
5151If the \f[C]--mathml\f[R] flag is used, it will be rendered using MathML
5152in an \f[C]inlineequation\f[R] or \f[C]informalequation\f[R] tag.
5153Otherwise it will be rendered, if possible, using Unicode characters.
5156It will be rendered using OMML math markup.
5159If the \f[C]--webtex\f[R] option is used, formulas are rendered as
5160images using CodeCogs or other compatible web service, downloaded and
5161embedded in the e-book.
5162Otherwise, they will appear verbatim.
5164HTML, Slidy, DZSlides, S5, EPUB
5165The way math is rendered in HTML will depend on the command-line options
5167Therefore see Math rendering in HTML above.
5169.SS Extension: \f[C]raw_html\f[R]
5171Markdown allows you to insert raw HTML (or DocBook) anywhere in a
5172document (except verbatim contexts, where \f[C]<\f[R], \f[C]>\f[R], and
5173\f[C]&\f[R] are interpreted literally).
5174(Technically this is not an extension, since standard Markdown allows
5175it, but it has been made an extension so that it can be disabled if
5178The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
5179DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile
5180output, and suppressed in other formats.
5182For a more explicit way of including raw HTML in a Markdown document,
5183see the \f[C]raw_attribute\f[R] extension.
5185In the CommonMark format, if \f[C]raw_html\f[R] is enabled,
5186superscripts, subscripts, strikeouts and small capitals will be
5188Otherwise, plain-text fallbacks will be used.
5189Note that even if \f[C]raw_html\f[R] is disabled, tables will be
5190rendered with HTML syntax if they cannot use pipe syntax.
5191.SS Extension: \f[C]markdown_in_html_blocks\f[R]
5193Standard Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of
5194HTML between balanced tags that are separated from the surrounding text
5195with blank lines, and start and end at the left margin.
5196Within these blocks, everything is interpreted as HTML, not Markdown; so
5197(for example), \f[C]*\f[R] does not signify emphasis.
5199Pandoc behaves this way when the \f[C]markdown_strict\f[R] format is
5200used; but by default, pandoc interprets material between HTML block tags
5202Thus, for example, pandoc will turn
5209<td>[a link](https://google.com)</td>
5221<td><em>one</em></td>
5222<td><a href=\[dq]https://google.com\[dq]>a link</a></td>
5228whereas \f[C]Markdown.pl\f[R] will preserve it as is.
5230There is one exception to this rule: text between \f[C]<script>\f[R],
5231\f[C]<style>\f[R], and \f[C]<textarea>\f[R] tags is not interpreted as
5234This departure from standard Markdown should make it easier to mix
5235Markdown with HTML block elements.
5236For example, one can surround a block of Markdown text with
5237\f[C]<div>\f[R] tags without preventing it from being interpreted as
5239.SS Extension: \f[C]native_divs\f[R]
5241Use native pandoc \f[C]Div\f[R] blocks for content inside
5242\f[C]<div>\f[R] tags.
5243For the most part this should give the same output as
5244\f[C]markdown_in_html_blocks\f[R], but it makes it easier to write
5245pandoc filters to manipulate groups of blocks.
5246.SS Extension: \f[C]native_spans\f[R]
5248Use native pandoc \f[C]Span\f[R] blocks for content inside
5249\f[C]<span>\f[R] tags.
5250For the most part this should give the same output as
5251\f[C]raw_html\f[R], but it makes it easier to write pandoc filters to
5252manipulate groups of inlines.
5253.SS Extension: \f[C]raw_tex\f[R]
5255In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
5256included in a document.
5257Inline TeX commands will be preserved and passed unchanged to the LaTeX
5259Thus, for example, you can use LaTeX to include BibTeX citations:
5263This result was proved in \[rs]cite{jones.1967}.
5267Note that in LaTeX environments, like
5271\[rs]begin{tabular}{|l|l|}\[rs]hline
5272Age & Frequency \[rs]\[rs] \[rs]hline
527318--25 & 15 \[rs]\[rs]
527426--35 & 33 \[rs]\[rs]
527536--45 & 22 \[rs]\[rs] \[rs]hline
5280the material between the begin and end tags will be interpreted as raw
5281LaTeX, not as Markdown.
5283For a more explicit and flexible way of including raw TeX in a Markdown
5284document, see the \f[C]raw_attribute\f[R] extension.
5286Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
5287Emacs Org mode, and ConTeXt.
5288.SS Generic raw attribute
5289.SS Extension: \f[C]raw_attribute\f[R]
5291Inline spans and fenced code blocks with a special kind of attribute
5292will be parsed as raw content with the designated format.
5293For example, the following produces a raw roff \f[C]ms\f[R] block:
5304And the following produces a raw \f[C]html\f[R] inline element:
5308This is \[ga]<a>html</a>\[ga]{=html}
5312This can be useful to insert raw xml into \f[C]docx\f[R] documents, e.g.
5317\[ga]\[ga]\[ga]{=openxml}
5320 <w:br w:type=\[dq]page\[dq]/>
5327The format name should match the target format name (see
5328\f[C]-t/--to\f[R], above, for a list, or use
5329\f[C]pandoc --list-output-formats\f[R]).
5330Use \f[C]openxml\f[R] for \f[C]docx\f[R] output, \f[C]opendocument\f[R]
5331for \f[C]odt\f[R] output, \f[C]html5\f[R] for \f[C]epub3\f[R] output,
5332\f[C]html4\f[R] for \f[C]epub2\f[R] output, and \f[C]latex\f[R],
5333\f[C]beamer\f[R], \f[C]ms\f[R], or \f[C]html5\f[R] for \f[C]pdf\f[R]
5334output (depending on what you use for \f[C]--pdf-engine\f[R]).
5336This extension presupposes that the relevant kind of inline code or
5337fenced code block is enabled.
5338Thus, for example, to use a raw attribute with a backtick code block,
5339\f[C]backtick_code_blocks\f[R] must be enabled.
5341The raw attribute cannot be combined with regular attributes.
5343.SS Extension: \f[C]latex_macros\f[R]
5345When this extension is enabled, pandoc will parse LaTeX macro
5346definitions and apply the resulting macros to all LaTeX math and raw
5348So, for example, the following will work in all output formats, not just
5353\[rs]newcommand{\[rs]tuple}[1]{\[rs]langle #1 \[rs]rangle}
5355$\[rs]tuple{a, b, c}$
5359Note that LaTeX macros will not be applied if they occur inside a raw
5360span or block marked with the \f[C]raw_attribute\f[R] extension.
5362When \f[C]latex_macros\f[R] is disabled, the raw LaTeX and math will not
5364This is usually a better approach when you are targeting LaTeX or PDF.
5366Macro definitions in LaTeX will be passed through as raw LaTeX only if
5367\f[C]latex_macros\f[R] is not enabled.
5368Macro definitions in Markdown source (or other formats allowing
5369\f[C]raw_tex\f[R]) will be passed through regardless of whether
5370\f[C]latex_macros\f[R] is enabled.
5373Markdown allows links to be specified in several ways.
5376If you enclose a URL or email address in pointy brackets, it will become
5382<sam\[at]green.eggs.ham>
5387An inline link consists of the link text in square brackets, followed by
5388the URL in parentheses.
5389(Optionally, the URL can be followed by a link title, in quotes.)
5393This is an [inline link](/url), and here\[aq]s [one with
5394a title](https://fsf.org \[dq]click here for a good time!\[dq]).
5398There can be no space between the bracketed part and the parenthesized
5400The link text can contain formatting (such as emphasis), but the title
5403Email addresses in inline links are not autodetected, so they have to be
5404prefixed with \f[C]mailto\f[R]:
5408[Write me!](mailto:sam\[at]green.eggs.ham)
5413An \f[I]explicit\f[R] reference link has two parts, the link itself and
5414the link definition, which may occur elsewhere in the document (either
5415before or after the link).
5417The link consists of link text in square brackets, followed by a label
5419(There cannot be space between the two unless the
5420\f[C]spaced_reference_links\f[R] extension is enabled.) The link
5421definition consists of the bracketed label, followed by a colon and a
5422space, followed by the URL, and optionally (after a space) a link title
5423either in quotes or in parentheses.
5424The label must not be parseable as a citation (assuming the
5425\f[C]citations\f[R] extension is enabled): citations take precedence
5428Here are some examples:
5432[my label 1]: /foo/bar.html \[dq]My title, optional\[dq]
5434[my label 3]: https://fsf.org (The free software foundation)
5435[my label 4]: /bar#special \[aq]A title in single quotes\[aq]
5439The URL may optionally be surrounded by angle brackets:
5443[my label 5]: <http://foo.bar.baz>
5447The title may go on the next line:
5451[my label 3]: https://fsf.org
5452 \[dq]The free software foundation\[dq]
5456Note that link labels are not case sensitive.
5461Here is [my link][FOO]
5467In an \f[I]implicit\f[R] reference link, the second pair of brackets is
5474[my website]: http://foo.bar.baz
5478Note: In \f[C]Markdown.pl\f[R] and most other Markdown implementations,
5479reference link definitions cannot occur in nested constructions such as
5480list items or block quotes.
5481Pandoc lifts this arbitrary seeming restriction.
5482So the following is fine in pandoc, though not in most other
5492.SS Extension: \f[C]shortcut_reference_links\f[R]
5494In a \f[I]shortcut\f[R] reference link, the second pair of brackets may
5501[my website]: http://foo.bar.baz
5506To link to another section of the same document, use the automatically
5507generated identifier (see Heading identifiers).
5512See the [Introduction](#introduction).
5520See the [Introduction].
5522[Introduction]: #introduction
5526Internal links are currently supported for HTML formats (including HTML
5527slide shows and EPUB), LaTeX, and ConTeXt.
5530A link immediately preceded by a \f[C]!\f[R] will be treated as an
5532The link text will be used as the image\[cq]s alt text:
5536
5540[movie reel]: movie.gif
5543.SS Extension: \f[C]implicit_figures\f[R]
5545An image with nonempty alt text, occurring by itself in a paragraph,
5546will be rendered as a figure with a caption.
5547The image\[cq]s alt text will be used as the caption.
5551
5555How this is rendered depends on the output format.
5556Some output formats (e.g.\ RTF) do not yet support figures.
5557In those formats, you\[cq]ll just get an image in a paragraph by itself,
5560If you just want a regular inline image, just make sure it is not the
5561only thing in the paragraph.
5562One way to do this is to insert a nonbreaking space after the image:
5566![This image won\[aq]t be a figure](/url/of/image.png)\[rs]
5570Note that in reveal.js slide shows, an image in a paragraph by itself
5571that has the \f[C]stretch\f[R] class will fill the screen, and the
5572caption and figure tags will be omitted.
5573.SS Extension: \f[C]link_attributes\f[R]
5575Attributes can be set on links and images:
5579An inline {#id .class width=30 height=20px}
5580and a reference ![image][ref] with attributes.
5582[ref]: foo.jpg \[dq]optional title\[dq] {#id .class key=val key2=\[dq]val 2\[dq]}
5586(This syntax is compatible with PHP Markdown Extra when only
5587\f[C]#id\f[R] and \f[C].class\f[R] are used.)
5589For HTML and EPUB, all known HTML5 attributes except \f[C]width\f[R] and
5590\f[C]height\f[R] (but including \f[C]srcset\f[R] and \f[C]sizes\f[R])
5591are passed through as is.
5592Unknown attributes are passed through as custom attributes, with
5593\f[C]data-\f[R] prepended.
5594The other writers ignore attributes that are not specifically supported
5595by their output format.
5597The \f[C]width\f[R] and \f[C]height\f[R] attributes on images are
5599When used without a unit, the unit is assumed to be pixels.
5600However, any of the following unit identifiers can be used:
5601\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]
5603There must not be any spaces between the number and the unit.
5608{ width=50% }
5612Dimensions may be converted to a form that is compatible with the output
5613format (for example, dimensions given in pixels will be converted to
5614inches when converting HTML to LaTeX).
5615Conversion between pixels and physical measurements is affected by the
5616\f[C]--dpi\f[R] option (by default, 96 dpi is assumed, unless the image
5617itself contains dpi information).
5619The \f[C]%\f[R] unit is generally relative to some available space.
5620For example the above example will render to the following.
5624\f[C]<img href=\[dq]file.jpg\[dq] style=\[dq]width: 50%;\[dq] />\f[R]
5627\f[C]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]
5628(If you\[cq]re using a custom template, you need to configure
5629\f[C]graphicx\f[R] as in the default template.)
5632\f[C]\[rs]externalfigure[file.jpg][width=0.5\[rs]textwidth]\f[R]
5635Some output formats have a notion of a class (ConTeXt) or a unique
5636identifier (LaTeX \f[C]\[rs]caption\f[R]), or both (HTML).
5638When no \f[C]width\f[R] or \f[C]height\f[R] attributes are specified,
5639the fallback is to look at the image resolution and the dpi metadata
5640embedded in the image file.
5643Using the \f[C]native_divs\f[R] and \f[C]native_spans\f[R] extensions
5644(see above), HTML syntax can be used as part of markdown to create
5645native \f[C]Div\f[R] and \f[C]Span\f[R] elements in the pandoc AST (as
5646opposed to raw HTML).
5647However, there is also nicer syntax available:
5648.SS Extension: \f[C]fenced_divs\f[R]
5650Allow special fenced syntax for native \f[C]Div\f[R] blocks.
5651A Div starts with a fence containing at least three consecutive colons
5652plus some attributes.
5653The attributes may optionally be followed by another string of
5655The attribute syntax is exactly as in fenced code blocks (see Extension:
5656\f[C]fenced_code_attributes\f[R]).
5657As with fenced code blocks, one can use either attributes in curly
5658braces or a single unbraced word, which will be treated as a class name.
5659The Div ends with another line containing a string of at least three
5661The fenced Div should be separated by blank lines from preceding and
5668::::: {#special .sidebar}
5676Fenced divs can be nested.
5677Opening fences are distinguished because they \f[I]must\f[R] have
5686This is a warning within a warning.
5692Fences without attributes are always closing fences.
5693Unlike with fenced code blocks, the number of colons in the closing
5694fence need not match the number in the opening fence.
5695However, it can be helpful for visual clarity to use fences of different
5696lengths to distinguish nested divs from their parents.
5697.SS Extension: \f[C]bracketed_spans\f[R]
5699A bracketed sequence of inlines, as one would use to begin a link, will
5700be treated as a \f[C]Span\f[R] with attributes if it is followed
5701immediately by attributes:
5705[This is *some text*]{.class key=\[dq]val\[dq]}
5709.SS Extension: \f[C]footnotes\f[R]
5711Pandoc\[cq]s Markdown allows footnotes, using the following syntax:
5715Here is a footnote reference,[\[ha]1] and another.[\[ha]longnote]
5717[\[ha]1]: Here is the footnote.
5719[\[ha]longnote]: Here\[aq]s one with multiple blocks.
5721 Subsequent paragraphs are indented to show that they
5722belong to the previous footnote.
5726 The whole paragraph can be indented, or just the first
5727 line. In this way, multi-paragraph footnotes work like
5728 multi-paragraph list items.
5730This paragraph won\[aq]t be part of the note, because it
5735The identifiers in footnote references may not contain spaces, tabs, or
5737These identifiers are used only to correlate the footnote reference with
5738the note itself; in the output, footnotes will be numbered sequentially.
5740The footnotes themselves need not be placed at the end of the document.
5741They may appear anywhere except inside other block elements (lists,
5742block quotes, tables, etc.).
5743Each footnote should be separated from surrounding content (including
5744other footnotes) by blank lines.
5745.SS Extension: \f[C]inline_notes\f[R]
5747Inline footnotes are also allowed (though, unlike regular notes, they
5748cannot contain multiple paragraphs).
5749The syntax is as follows:
5753Here is an inline note.\[ha][Inlines notes are easier to write, since
5754you don\[aq]t have to pick an identifier and move down to type the
5759Inline and regular footnotes may be mixed freely.
5761.SS Extension: \f[C]citations\f[R]
5763Markdown citations go inside square brackets and are separated by
5765Each citation must have a key, composed of `\[at]' + the citation
5766identifier from the database, and may optionally have a prefix, a
5767locator, and a suffix.
5768The citation key must begin with a letter, digit, or \f[C]_\f[R], and
5769may contain alphanumerics, \f[C]_\f[R], and internal punctuation
5770characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]).
5771Here are some examples:
5775Blah blah [see \[at]doe99, pp. 33-35; also \[at]smith04, chap. 1].
5777Blah blah [\[at]doe99, pp. 33-35, 38-39 and *passim*].
5779Blah blah [\[at]smith04; \[at]doe99].
5783\f[C]pandoc\f[R] detects locator terms in the CSL locale files.
5784Either abbreviated or unabbreviated forms are accepted.
5785In the \f[C]en-US\f[R] locale, locator terms can be written in either
5786singular or plural forms, as \f[C]book\f[R],
5787\f[C]bk.\f[R]/\f[C]bks.\f[R]; \f[C]chapter\f[R],
5788\f[C]chap.\f[R]/\f[C]chaps.\f[R]; \f[C]column\f[R],
5789\f[C]col.\f[R]/\f[C]cols.\f[R]; \f[C]figure\f[R],
5790\f[C]fig.\f[R]/\f[C]figs.\f[R]; \f[C]folio\f[R],
5791\f[C]fol.\f[R]/\f[C]fols.\f[R]; \f[C]number\f[R],
5792\f[C]no.\f[R]/\f[C]nos.\f[R]; \f[C]line\f[R],
5793\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];
5794\f[C]opus\f[R], \f[C]op.\f[R]/\f[C]opp.\f[R]; \f[C]page\f[R],
5795\f[C]p.\f[R]/\f[C]pp.\f[R]; \f[C]paragraph\f[R],
5796\f[C]para.\f[R]/\f[C]paras.\f[R]; \f[C]part\f[R],
5797\f[C]pt.\f[R]/\f[C]pts.\f[R]; \f[C]section\f[R],
5798\f[C]sec.\f[R]/\f[C]secs.\f[R]; \f[C]sub verbo\f[R],
5799\f[C]s.v.\f[R]/\f[C]s.vv.\f[R]; \f[C]verse\f[R],
5800\f[C]v.\f[R]/\f[C]vv.\f[R]; \f[C]volume\f[R],
5801\f[C]vol.\f[R]/\f[C]vols.\f[R]; \f[C]\[ps]\f[R]/\f[C]\[ps]\[ps]\f[R];
5802\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
5803If no locator term is used, \[lq]page\[rq] is assumed.
5805\f[C]pandoc\f[R] will use heuristics to distinguish the locator from the
5807In complex cases, the locator can be enclosed in curly braces:
5811[\[at]smith{ii, A, D-Z}, with a suffix]
5812[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
5816A minus sign (\f[C]-\f[R]) before the \f[C]\[at]\f[R] will suppress
5817mention of the author in the citation.
5818This can be useful when the author is already mentioned in the text:
5822Smith says blah [-\[at]smith04].
5826You can also write an in-text citation, as follows:
5830\[at]smith04 says blah.
5832\[at]smith04 [p. 33] says blah.
5835.SS Non-pandoc extensions
5837The following Markdown syntax extensions are not enabled by default in
5838pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
5839name, where \f[C]EXTENSION\f[R] is the name of the extension.
5840Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with
5842.SS Extension: \f[C]attributes\f[R]
5844Allows attributes to be attached to any inline or block-level element.
5845The syntax for the attributes is the same as that used in
5846\f[C]header_attributes\f[R].
5848Attributes that occur immediately after an inline element affect that
5850If they follow a space, then they belong to the space.
5851(Hence, this option subsumes \f[C]inline_code_attributes\f[R] and
5852\f[C]link_attributes\f[R].)
5854Attributes that occur immediately before a block element, on a line by
5855themselves, affect that element.
5857Consecutive attribute specifiers may be used, either for blocks or for
5859Their attributes will be combined.
5861Attributes that occur at the end of the text of a Setext or ATX heading
5862(separated by whitespace from the text) affect the heading element.
5863(Hence, this option subsumes \f[C]header_attributes\f[R].)
5865Attributes that occur after the opening fence in a fenced code block
5866affect the code block element.
5867(Hence, this option subsumes \f[C]fenced_code_attributes\f[R].)
5869Attributes that occur at the end of a reference link definition affect
5870links that refer to that definition.
5872Note that pandoc\[cq]s AST does not currently allow attributes to be
5873attached to arbitrary elements.
5874Hence a Span or Div container will be added if needed.
5875.SS Extension: \f[C]old_dashes\f[R]
5877Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
5878\f[C]-\f[R] before a numeral is an en-dash, and \f[C]--\f[R] is an
5880This option only has an effect if \f[C]smart\f[R] is enabled.
5881It is selected automatically for \f[C]textile\f[R] input.
5882.SS Extension: \f[C]angle_brackets_escapable\f[R]
5884Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can
5885be in GitHub flavored Markdown but not original Markdown.
5886This is implied by pandoc\[cq]s default \f[C]all_symbols_escapable\f[R].
5887.SS Extension: \f[C]lists_without_preceding_blankline\f[R]
5889Allow a list to occur right after a paragraph, with no intervening blank
5891.SS Extension: \f[C]four_space_rule\f[R]
5893Selects the pandoc <= 2.0 behavior for parsing lists, so that four
5894spaces indent are needed for list item continuation paragraphs.
5895.SS Extension: \f[C]spaced_reference_links\f[R]
5897Allow whitespace between the two components of a reference link, for
5905.SS Extension: \f[C]hard_line_breaks\f[R]
5907Causes all newlines within a paragraph to be interpreted as hard line
5908breaks instead of spaces.
5909.SS Extension: \f[C]ignore_line_breaks\f[R]
5911Causes newlines within a paragraph to be ignored, rather than being
5912treated as spaces or as hard line breaks.
5913This option is intended for use with East Asian languages where spaces
5914are not used between words, but text is divided into lines for
5916.SS Extension: \f[C]east_asian_line_breaks\f[R]
5918Causes newlines within a paragraph to be ignored, rather than being
5919treated as spaces or as hard line breaks, when they occur between two
5920East Asian wide characters.
5921This is a better choice than \f[C]ignore_line_breaks\f[R] for texts that
5922include a mix of East Asian wide characters and other characters.
5923.SS Extension: \f[C]emoji\f[R]
5925Parses textual emojis like \f[C]:smile:\f[R] as Unicode emoticons.
5926.SS Extension: \f[C]tex_math_single_backslash\f[R]
5928Causes anything between \f[C]\[rs](\f[R] and \f[C]\[rs])\f[R] to be
5929interpreted as inline TeX math, and anything between \f[C]\[rs][\f[R]
5930and \f[C]\[rs]]\f[R] to be interpreted as display TeX math.
5931Note: a drawback of this extension is that it precludes escaping
5932\f[C](\f[R] and \f[C][\f[R].
5933.SS Extension: \f[C]tex_math_double_backslash\f[R]
5935Causes anything between \f[C]\[rs]\[rs](\f[R] and \f[C]\[rs]\[rs])\f[R]
5936to be interpreted as inline TeX math, and anything between
5937\f[C]\[rs]\[rs][\f[R] and \f[C]\[rs]\[rs]]\f[R] to be interpreted as
5939.SS Extension: \f[C]markdown_attribute\f[R]
5941By default, pandoc interprets material inside block-level tags as
5943This extension changes the behavior so that Markdown is only parsed
5944inside block-level tags if the tags have the attribute
5945\f[C]markdown=1\f[R].
5946.SS Extension: \f[C]mmd_title_block\f[R]
5948Enables a MultiMarkdown style title block at the top of the document,
5955Date: September 1, 2008
5956Comment: This is a sample mmd title block, with
5957 a field spanning multiple lines.
5961See the MultiMarkdown documentation for details.
5962If \f[C]pandoc_title_block\f[R] or \f[C]yaml_metadata_block\f[R] is
5963enabled, it will take precedence over \f[C]mmd_title_block\f[R].
5964.SS Extension: \f[C]abbreviations\f[R]
5966Parses PHP Markdown Extra abbreviation keys, like
5970*[HTML]: Hypertext Markup Language
5974Note that the pandoc document model does not support abbreviations, so
5975if this extension is enabled, abbreviation keys are simply skipped (as
5976opposed to being parsed as paragraphs).
5977.SS Extension: \f[C]autolink_bare_uris\f[R]
5979Makes all absolute URIs into links, even when not surrounded by pointy
5980braces \f[C]<...>\f[R].
5981.SS Extension: \f[C]mmd_link_attributes\f[R]
5983Parses multimarkdown style key-value attributes on link and image
5985This extension should not be confused with the \f[C]link_attributes\f[R]
5990This is a reference ![image][ref] with multimarkdown attributes.
5992[ref]: https://path.to/image \[dq]Image title\[dq] width=20px height=30px
5993 id=myId class=\[dq]myClass1 myClass2\[dq]
5996.SS Extension: \f[C]mmd_header_identifiers\f[R]
5998Parses multimarkdown style heading identifiers (in square brackets,
5999after the heading but before any trailing \f[C]#\f[R]s in an ATX
6001.SS Extension: \f[C]compact_definition_lists\f[R]
6003Activates the definition list syntax of pandoc 1.12.x and earlier.
6004This syntax differs from the one described above under Definition lists
6007No blank line is required between consecutive items of the definition
6010To get a \[lq]tight\[rq] or \[lq]compact\[rq] list, omit space between
6011consecutive items; the space between a term and its definition does not
6014Lazy wrapping of paragraphs is not allowed: the entire definition must
6015be indented four spaces.
6016.SS Extension: \f[C]gutenberg\f[R]
6018Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
6019for strong emphasis, surround by underscores for regular emphasis, add
6020extra blank space around headings.
6021.SS Extension: \f[C]sourcepos\f[R]
6023Include source position attributes when parsing \f[C]commonmark\f[R].
6024For elements that accept attributes, a \f[C]data-pos\f[R] attribute is
6025added; other elements are placed in a surrounding Div or Span elemnet
6026with a \f[C]data-pos\f[R] attribute.
6027.SS Markdown variants
6029In addition to pandoc\[cq]s extended Markdown, the following Markdown
6030variants are supported:
6032\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
6034\f[C]markdown_github\f[R] (deprecated GitHub-Flavored Markdown)
6036\f[C]markdown_mmd\f[R] (MultiMarkdown)
6038\f[C]markdown_strict\f[R] (Markdown.pl)
6040\f[C]commonmark\f[R] (CommonMark)
6042\f[C]gfm\f[R] (Github-Flavored Markdown)
6044\f[C]commonmark_x\f[R] (CommonMark with many pandoc extensions)
6046To see which extensions are supported for a given format, and which are
6047enabled by default, you can use the command
6051pandoc --list-extensions=FORMAT
6055where \f[C]FORMAT\f[R] is replaced with the name of the format.
6057Note that the list of extensions for \f[C]commonmark\f[R],
6058\f[C]gfm\f[R], and \f[C]commonmark_x\f[R] are defined relative to
6060So, for example, \f[C]backtick_code_blocks\f[R] does not appear as an
6061extension, since it is enabled by default and cannot be disabled.
6064When the \f[C]--citeproc\f[R] option is used, pandoc can automatically
6065generate citations and a bibliography in a number of styles.
6070pandoc --citeproc myinput.txt
6074To use this feature, you will need to have
6076a document containing citations (see Extension: \f[C]citations\f[R]);
6078a source of bibliographic data: either an external bibliography file or
6079a list of \f[C]references\f[R] in the document\[cq]s YAML metadata
6081optionally, a CSL citation style.
6082.SS Specifying bibliographic data
6084You can specify an external bibliography using the
6085\f[C]bibliography\f[R] metadata field in a YAML metadata section or the
6086\f[C]--bibliography\f[R] command line argument.
6087If you want to use multiple bibliography files, you can supply multiple
6088\f[C]--bibliography\f[R] arguments or set \f[C]bibliography\f[R]
6089metadata field to YAML array.
6090A bibliography may have any of these formats:
6123Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX
6124files; use the extension \f[C].bibtex\f[R] to force interpretation as
6127In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside
6128fields such as \f[C]title\f[R]; in CSL YAML databases, pandoc Markdown;
6129and in CSL JSON databases, an HTML-like markup:
6131\f[B]\f[CB]<i>...</i>\f[B]\f[R]
6134\f[B]\f[CB]<b>...</b>\f[B]\f[R]
6137\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]
6140\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]
6143\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]
6146\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]
6147prevent a phrase from being capitalized as title case
6149As an alternative to specifying a bibliography file using
6150\f[C]--bibliography\f[R] or the YAML metadata field
6151\f[C]bibliography\f[R], you can include the citation data directly in
6152the \f[C]references\f[R] field of the document\[cq]s YAML metadata.
6153The field should contain an array of YAML-encoded references, for
6160- type: article-journal
6172 title: \[aq]Molecular structure of nucleic acids: a structure for
6173 deoxyribose nucleic acid\[aq]
6174 title-short: Molecular structure of nucleic acids
6175 container-title: Nature
6179 DOI: 10.1038/171737a0
6180 URL: https://www.nature.com/articles/171737a0
6186If both an external bibliography and inline (YAML metadata) references
6187are provided, both will be used.
6188In case of conflicting \f[C]id\f[R]s, the inline references will take
6191Note that \f[C]pandoc\f[R] can be used to produce such a YAML metadata
6192section from a BibTeX, BibLaTeX, or CSL JSON bibliography:
6196pandoc chem.bib -s -f biblatex -t markdown
6197pandoc chem.json -s -f csljson -t markdown
6201Indeed, \f[C]pandoc\f[R] can convert between any of these citation
6206pandoc chem.bib -s -f biblatex -t csljson
6207pandoc chem.yaml -s -f markdown -t biblatex
6211Running pandoc on a bibliography file with the \f[C]--citeproc\f[R]
6212option will create a formatted bibliography in the format of your
6217pandoc chem.bib -s --citeproc -o chem.html
6218pandoc chem.bib -s --citeproc -o chem.pdf
6221.SS Capitalization in titles
6223If you are using a bibtex or biblatex bibliography, then observe the
6226English titles should be in title case.
6227Non-English titles should be in sentence case, and the \f[C]langid\f[R]
6228field in biblatex should be set to the relevant language.
6229(The following values are treated as English: \f[C]american\f[R],
6230\f[C]british\f[R], \f[C]canadian\f[R], \f[C]english\f[R],
6231\f[C]australian\f[R], \f[C]newzealand\f[R], \f[C]USenglish\f[R], or
6232\f[C]UKenglish\f[R].)
6234As is standard with bibtex/biblatex, proper names should be protected
6235with curly braces so that they won\[cq]t be lowercased in styles that
6236call for sentence case.
6242title = {My Dinner with {Andre}}
6247In addition, words that should remain lowercase (or camelCase) should be
6253title = {Spin Wave Dispersion on the {nm} Scale}
6257Though this is not necessary in bibtex/biblatex, it is necessary with
6258citeproc, which stores titles internally in sentence case, and converts
6259to title case in styles that require it.
6260Here we protect \[lq]nm\[rq] so that it doesn\[cq]t get converted to
6261\[lq]Nm\[rq] at this stage.
6264If you are using a CSL bibliography (either JSON or YAML), then observe
6267All titles should be in sentence case.
6269Use the \f[C]language\f[R] field for non-English titles to prevent their
6270conversion to title case in styles that call for this.
6271(Conversion happens only if \f[C]language\f[R] begins with \f[C]en\f[R]
6274Protect words that should not be converted to title case using this
6280Spin wave dispersion on the <span class=\[dq]nocase\[dq]>nm</span> scale
6284.SS Conference Papers, Published vs.\ Unpublished
6286For a formally published conference paper, use the biblatex entry type
6287\f[C]inproceedings\f[R] (which will be mapped to CSL
6288\f[C]paper-conference\f[R]).
6290For an unpublished manuscript, use the biblatex entry type
6291\f[C]unpublished\f[R] without an \f[C]eventtitle\f[R] field (this entry
6292type will be mapped to CSL \f[C]manuscript\f[R]).
6294For a talk, an unpublished conference paper, or a poster presentation,
6295use the biblatex entry type \f[C]unpublished\f[R] with an
6296\f[C]eventtitle\f[R] field (this entry type will be mapped to CSL
6298Use the biblatex \f[C]type\f[R] field to indicate the type,
6299e.g.\ \[lq]Paper\[rq], or \[lq]Poster\[rq].
6300\f[C]venue\f[R] and \f[C]eventdate\f[R] may be useful too, though
6301\f[C]eventdate\f[R] will not be rendered by most CSL styles.
6302Note that \f[C]venue\f[R] is for the event\[cq]s venue, unlike
6303\f[C]location\f[R] which describes the publisher\[cq]s location; do not
6304use the latter for an unpublished conference paper.
6305.SS Specifying a citation style
6307Citations and references can be formatted using any style supported by
6308the Citation Style Language, listed in the Zotero Style Repository.
6309These files are specified using the \f[C]--csl\f[R] option or the
6310\f[C]csl\f[R] (or \f[C]citation-style\f[R]) metadata field.
6311By default, pandoc will use the Chicago Manual of Style author-date
6313(You can override this default by copying a CSL style of your choice to
6314\f[C]default.csl\f[R] in your user data directory.) The CSL project
6315provides further information on finding and editing styles.
6317The \f[C]--citation-abbreviations\f[R] option (or the
6318\f[C]citation-abbreviations\f[R] metadata field) may be used to specify
6319a JSON file containing abbreviations of journals that should be used in
6320formatted bibliographies when \f[C]form=\[dq]short\[dq]\f[R] is
6322The format of the file can be illustrated with an example:
6326{ \[dq]default\[dq]: {
6327 \[dq]container-title\[dq]: {
6328 \[dq]Lloyd\[aq]s Law Reports\[dq]: \[dq]Lloyd\[aq]s Rep\[dq],
6329 \[dq]Estates Gazette\[dq]: \[dq]EG\[dq],
6330 \[dq]Scots Law Times\[dq]: \[dq]SLT\[dq]
6336.SS Citations in note styles
6338Pandoc\[cq]s citation processing is designed to allow you to move
6339between author-date, numerical, and note styles without modifying the
6341When you\[cq]re using a note style, avoid inserting footnotes manually.
6342Instead, insert citations just as you would in an author-date
6343style\[em]for example,
6347Blah blah [\[at]foo, p. 33].
6351The footnote will be created automatically.
6352Pandoc will take care of removing the space and moving the note before
6353or after the period, depending on the setting of
6354\f[C]notes-after-punctuation\f[R], as described below in Other relevant
6357In some cases you may need to put a citation inside a regular footnote.
6358Normal citations in footnotes (such as \f[C][\[at]foo, p. 33]\f[R]) will
6359be rendered in parentheses.
6360In-text citations (such as \f[C]\[at]foo [p. 33]\f[R]) will be rendered
6362(A comma will be added if appropriate.) Thus:
6366[\[ha]1]: Some studies [\[at]foo; \[at]bar, p. 33] show that
6367frubulicious zoosnaps are quantical. For a survey
6368of the literature, see \[at]baz [chap. 1].
6371.SS Raw content in a style
6373To include raw content in a prefix, suffix, delimiter, or term, surround
6374it with these tags indicating the format:
6378{{jats}}<ref>{{/jats}}
6382Without the tags, the string will be interpreted as a string and escaped
6383in the output, rather than being passed through raw.
6385This feature allows stylesheets to be customized to give different
6386output for different output formats.
6387However, stylesheets customized in this way will not be usable by other
6389.SS Placement of the bibliography
6391If the style calls for a list of works cited, it will be placed in a div
6392with id \f[C]refs\f[R], if one exists:
6401Otherwise, it will be placed at the end of the document.
6402Generation of the bibliography can be suppressed by setting
6403\f[C]suppress-bibliography: true\f[R] in the YAML metadata.
6405If you wish the bibliography to have a section heading, you can set
6406\f[C]reference-section-title\f[R] in the metadata, or put the heading at
6407the beginning of the div with id \f[C]refs\f[R] (if you are using it) or
6408at the end of your document:
6418The bibliography will be inserted after this heading.
6419Note that the \f[C]unnumbered\f[R] class will be added to this heading,
6420so that the section will not be numbered.
6421.SS Including uncited items in the bibliography
6423If you want to include items in the bibliography without actually citing
6424them in the body text, you can define a dummy \f[C]nocite\f[R] metadata
6425field and put the citations there:
6431 \[at]item1, \[at]item2
6438In this example, the document will contain a citation for
6439\f[C]item3\f[R] only, but the bibliography will contain entries for
6440\f[C]item1\f[R], \f[C]item2\f[R], and \f[C]item3\f[R].
6442It is possible to create a bibliography with all the citations, whether
6443or not they appear in the document, by using a wildcard:
6454For LaTeX output, you can also use \f[C]natbib\f[R] or
6455\f[C]biblatex\f[R] to render the bibliography.
6456In order to do so, specify bibliography files as outlined above, and add
6457\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]
6459Bear in mind that bibliography files have to be in either BibTeX (for
6460\f[C]--natbib\f[R]) or BibLaTeX (for \f[C]--biblatex\f[R]) format.
6461.SS Other relevant metadata fields
6463A few other metadata fields affect bibliography formatting:
6465\f[B]\f[CB]link-citations\f[B]\f[R]
6466If true, citations will be hyperlinked to the corresponding bibliography
6467entries (for author-date and numerical styles only).
6469\f[B]\f[CB]lang\f[B]\f[R]
6470The \f[C]lang\f[R] field will affect how the style is localized, for
6471example in the translation of labels and the use of quotation marks.
6472(For backwards compatibility, \f[C]locale\f[R] may be used instead of
6473\f[C]lang\f[R], but this use is deprecated.)
6475\f[B]\f[CB]notes-after-punctuation\f[B]\f[R]
6476If true (the default), pandoc will put footnote citations after
6477following punctuation.
6478For example, if the source contains \f[C]blah blah [\[at]jones99].\f[R],
6479the result will look like \f[C]blah blah.[\[ha]1]\f[R], with the note
6480moved after the period and the space collapsed.
6481If false, the space will still be collapsed, but the footnote will not
6482be moved after the punctuation.
6485You can use pandoc to produce an HTML + JavaScript slide presentation
6486that can be viewed via a web browser.
6487There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or
6489You can also produce a PDF slide show using LaTeX \f[C]beamer\f[R], or
6490slides shows in Microsoft PowerPoint format.
6492Here\[cq]s the Markdown source for a simple slide show,
6493\f[C]habits.txt\f[R]:
6522
6531To produce an HTML/JavaScript slide show, simply type
6535pandoc -t FORMAT -s habits.txt -o habits.html
6539where \f[C]FORMAT\f[R] is either \f[C]s5\f[R], \f[C]slidy\f[R],
6540\f[C]slideous\f[R], \f[C]dzslides\f[R], or \f[C]revealjs\f[R].
6542For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with
6543the \f[C]-s/--standalone\f[R] option embeds a link to JavaScript and CSS
6544files, which are assumed to be available at the relative path
6545\f[C]s5/default\f[R] (for S5), \f[C]slideous\f[R] (for Slideous),
6546\f[C]reveal.js\f[R] (for reveal.js), or at the Slidy website at
6547\f[C]w3.org\f[R] (for Slidy).
6548(These paths can be changed by setting the \f[C]slidy-url\f[R],
6549\f[C]slideous-url\f[R], \f[C]revealjs-url\f[R], or \f[C]s5-url\f[R]
6550variables; see Variables for HTML slides, above.) For DZSlides, the
6551(relatively short) JavaScript and CSS are included in the file by
6554With all HTML slide formats, the \f[C]--self-contained\f[R] option can
6555be used to produce a single file that contains all of the data necessary
6556to display the slide show, including linked scripts, stylesheets,
6559To produce a PDF slide show using beamer, type
6563pandoc -t beamer habits.txt -o habits.pdf
6567Note that a reveal.js slide show can also be converted to a PDF by
6568printing it to a file from the browser.
6570To produce a Powerpoint slide show, type
6574pandoc habits.txt -o habits.pptx
6577.SS Structuring the slide show
6579By default, the \f[I]slide level\f[R] is the highest heading level in
6580the hierarchy that is followed immediately by content, and not another
6581heading, somewhere in the document.
6582In the example above, level-1 headings are always followed by level-2
6583headings, which are followed by content, so the slide level is 2.
6584This default can be overridden using the \f[C]--slide-level\f[R] option.
6586The document is carved up into slides according to the following rules:
6588A horizontal rule always starts a new slide.
6590A heading at the slide level always starts a new slide.
6592Headings \f[I]below\f[R] the slide level in the hierarchy create
6593headings \f[I]within\f[R] a slide.
6595Headings \f[I]above\f[R] the slide level in the hierarchy create
6596\[lq]title slides,\[rq] which just contain the section title and help to
6597break the slide show into sections.
6598Non-slide content under these headings will be included on the title
6599slide (for HTML slide shows) or in a subsequent slide with the same
6602A title page is constructed automatically from the document\[cq]s title
6604(In the case of beamer, this can be disabled by commenting out some
6605lines in the default template.)
6607These rules are designed to support many different styles of slide show.
6608If you don\[cq]t care about structuring your slides into sections and
6609subsections, you can just use level-1 headings for all each slide.
6610(In that case, level-1 will be the slide level.) But you can also
6611structure the slide show into sections, as in the example above.
6613Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
6614layout will be produced, with level-1 headings building horizontally and
6615level-2 headings building vertically.
6616It is not recommended that you use deeper nesting of section levels with
6618.SS Incremental lists
6620By default, these writers produce lists that display \[lq]all at
6621once.\[rq] If you want your lists to display incrementally (one item at
6622a time), use the \f[C]-i\f[R] option.
6623If you want a particular list to depart from the default, put it in a
6624\f[C]div\f[R] block with class \f[C]incremental\f[R] or
6625\f[C]nonincremental\f[R].
6626So, for example, using the \f[C]fenced div\f[R] syntax, the following
6627would be incremental regardless of the document default:
6653While using \f[C]incremental\f[R] and \f[C]nonincremental\f[R] divs are
6654the recommended method of setting incremental lists on a per-case basis,
6655an older method is also supported: putting lists inside a blockquote
6656will depart from the document default (that is, it will display
6657incrementally without the \f[C]-i\f[R] option and all at once with the
6658\f[C]-i\f[R] option):
6667Both methods allow incremental and nonincremental lists to be mixed in a
6670Note: Neither the \f[C]-i/--incremental\f[R] option nor any of the
6671methods described here currently works for PowerPoint output.
6674You can add \[lq]pauses\[rq] within a slide by including a paragraph
6675containing three dots, separated by spaces:
6681content before the pause
6685content after the pause
6689Note: this feature is not yet implemented for PowerPoint output.
6690.SS Styling the slides
6692You can change the style of HTML slides by putting customized CSS files
6693in \f[C]$DATADIR/s5/default\f[R] (for S5), \f[C]$DATADIR/slidy\f[R] (for
6694Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where
6695\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
6697The originals may be found in pandoc\[cq]s system data directory
6698(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).
6699Pandoc will look there for any files it does not find in the user data
6702For dzslides, the CSS is included in the HTML file itself, and may be
6705All reveal.js configuration options can be set through variables.
6706For example, themes can be used by setting the \f[C]theme\f[R] variable:
6714Or you can specify a custom stylesheet using the \f[C]--css\f[R] option.
6716To style beamer slides, you can specify a \f[C]theme\f[R],
6717\f[C]colortheme\f[R], \f[C]fonttheme\f[R], \f[C]innertheme\f[R], and
6718\f[C]outertheme\f[R], using the \f[C]-V\f[R] option:
6722pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
6726Note that heading attributes will turn into slide attributes (on a
6727\f[C]<div>\f[R] or \f[C]<section>\f[R]) in HTML slide formats, allowing
6728you to style individual slides.
6729In beamer, the only heading attribute that affects slides is the
6730\f[C]allowframebreaks\f[R] class, which sets the
6731\f[C]allowframebreaks\f[R] option, causing multiple slides to be created
6732if the content overfills the frame.
6733This is recommended especially for bibliographies:
6737# References {.allowframebreaks}
6742Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
6743You can add notes to your Markdown document thus:
6751- It can contain Markdown
6758To show the notes window in reveal.js, press \f[C]s\f[R] while viewing
6760Speaker notes in PowerPoint will be available, as usual, in handouts and
6763Notes are not yet supported for other slide formats, but the notes will
6764not appear on the slides themselves.
6767To put material in side by side columns, you can use a native div
6768container with class \f[C]columns\f[R], containing two or more div
6769containers with class \f[C]column\f[R] and a \f[C]width\f[R] attribute:
6773:::::::::::::: {.columns}
6774::: {.column width=\[dq]40%\[dq]}
6777::: {.column width=\[dq]60%\[dq]}
6783.SS Additional columns attributes in beamer
6785The div containers with classes \f[C]columns\f[R] and \f[C]column\f[R]
6786can optionally have an \f[C]align\f[R] attribute.
6787The class \f[C]columns\f[R] can optionally have a \f[C]totalwidth\f[R]
6788attribute or an \f[C]onlytextwidth\f[R] class.
6792:::::::::::::: {.columns align=center totalwidth=8em}
6793::: {.column width=\[dq]40%\[dq]}
6796::: {.column width=\[dq]60%\[dq] align=bottom}
6803The \f[C]align\f[R] attributes on \f[C]columns\f[R] and \f[C]column\f[R]
6804can be used with the values \f[C]top\f[R], \f[C]top-baseline\f[R],
6805\f[C]center\f[R] and \f[C]bottom\f[R] to vertically align the columns.
6806It defaults to \f[C]top\f[R] in \f[C]columns\f[R].
6808The \f[C]totalwidth\f[R] attribute limits the width of the columns to
6813:::::::::::::: {.columns align=top .onlytextwidth}
6814::: {.column width=\[dq]40%\[dq] align=center}
6817::: {.column width=\[dq]60%\[dq]}
6824The class \f[C]onlytextwidth\f[R] sets the \f[C]totalwidth\f[R] to
6825\f[C]\[rs]textwidth\f[R].
6827See Section 12.7 of the Beamer User\[cq]s Guide for more details.
6828.SS Frame attributes in beamer
6830Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[R] option to
6831a frame in beamer (for example, when using the \f[C]minted\f[R]
6833This can be forced by adding the \f[C]fragile\f[R] class to the heading
6834introducing the slide:
6838# Fragile slide {.fragile}
6842All of the other frame attributes described in Section 8.1 of the Beamer
6843User\[cq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
6844\f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],
6845\f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],
6846\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
6847.SS Background in reveal.js and beamer
6849Background images can be added to self-contained reveal.js slideshows
6850and to beamer slideshows.
6852For the same image on every slide, use the configuration option
6853\f[C]background-image\f[R] either in the YAML metadata block or as a
6854command-line variable.
6855(There are no other options in beamer and the rest of this section
6856concerns reveal.js slideshows.)
6858For reveal.js, you can instead use the reveal.js-native option
6859\f[C]parallaxBackgroundImage\f[R].
6860You can also set \f[C]parallaxBackgroundHorizontal\f[R] and
6861\f[C]parallaxBackgroundVertical\f[R] the same way and must also set
6862\f[C]parallaxBackgroundSize\f[R] to have your values take effect.
6864To set an image for a particular reveal.js slide, add
6865\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
6866slide-level heading on the slide (which may even be empty).
6868In reveal.js\[cq]s overview mode, the parallaxBackgroundImage will show
6869up only on the first slide.
6871Other reveal.js background settings also work on individual slides,
6872including \f[C]data-background-size\f[R],
6873\f[C]data-background-repeat\f[R], \f[C]data-background-color\f[R],
6874\f[C]data-transition\f[R], and \f[C]data-transition-speed\f[R].
6876To add a background image to the automatically generated title slide,
6877use the \f[C]title-slide-attributes\f[R] variable in the YAML metadata
6879It must contain a map of attribute names and values.
6881See the reveal.js documentation for more details.
6883For example in reveal.js:
6889parallaxBackgroundImage: /path/to/my/background_image.png
6890title-slide-attributes:
6891 data-background-image: /path/to/title_image.png
6892 data-background-size: contain
6897Slide 1 has background_image.png as its background.
6899## {data-background-image=\[dq]/path/to/special_image.jpg\[dq]}
6901Slide 2 has a special image for its background, even though the heading has no content.
6907EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]
6908option, but if the source document is Markdown, it is better to use a
6919 text: An investigation of metadata
6927 text: doi:10.234234.234/33
6929rights: \[co] 2007 John Smith, CC BY-NC
6936The following fields are recognized:
6938\f[B]\f[CB]identifier\f[B]\f[R]
6939Either a string value or an object with fields \f[C]text\f[R] and
6941Valid values for \f[C]scheme\f[R] are \f[C]ISBN-10\f[R],
6942\f[C]GTIN-13\f[R], \f[C]UPC\f[R], \f[C]ISMN-10\f[R], \f[C]DOI\f[R],
6943\f[C]LCCN\f[R], \f[C]GTIN-14\f[R], \f[C]ISBN-13\f[R],
6944\f[C]Legal deposit number\f[R], \f[C]URN\f[R], \f[C]OCLC\f[R],
6945\f[C]ISMN-13\f[R], \f[C]ISBN-A\f[R], \f[C]JP\f[R], \f[C]OLCC\f[R].
6947\f[B]\f[CB]title\f[B]\f[R]
6948Either a string value, or an object with fields \f[C]file-as\f[R] and
6949\f[C]type\f[R], or a list of such objects.
6950Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],
6951\f[C]short\f[R], \f[C]collection\f[R], \f[C]edition\f[R],
6954\f[B]\f[CB]creator\f[B]\f[R]
6955Either a string value, or an object with fields \f[C]role\f[R],
6956\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.
6957Valid values for \f[C]role\f[R] are MARC relators, but pandoc will
6958attempt to translate the human-readable versions (like \[lq]author\[rq]
6959and \[lq]editor\[rq]) to the appropriate marc relators.
6961\f[B]\f[CB]contributor\f[B]\f[R]
6962Same format as \f[C]creator\f[R].
6964\f[B]\f[CB]date\f[B]\f[R]
6965A string value in \f[C]YYYY-MM-DD\f[R] format.
6966(Only the year is necessary.) Pandoc will attempt to convert other
6969\f[B]\f[CB]lang\f[B]\f[R] (or legacy: \f[B]\f[CB]language\f[B]\f[R])
6970A string value in BCP 47 format.
6971Pandoc will default to the local language if nothing is specified.
6973\f[B]\f[CB]subject\f[B]\f[R]
6974A string value or a list of such values.
6976\f[B]\f[CB]description\f[B]\f[R]
6979\f[B]\f[CB]type\f[B]\f[R]
6982\f[B]\f[CB]format\f[B]\f[R]
6985\f[B]\f[CB]relation\f[B]\f[R]
6988\f[B]\f[CB]coverage\f[B]\f[R]
6991\f[B]\f[CB]rights\f[B]\f[R]
6994\f[B]\f[CB]belongs-to-collection\f[B]\f[R]
6996identifies the name of a collection to which the EPUB Publication
6999\f[B]\f[CB]group-position\f[B]\f[R]
7000The \f[C]group-position\f[R] field indicates the numeric position in
7001which the EPUB Publication belongs relative to other works belonging to
7002the same \f[C]belongs-to-collection\f[R] field.
7004\f[B]\f[CB]cover-image\f[B]\f[R]
7005A string value (path to cover image).
7007\f[B]\f[CB]css\f[B]\f[R] (or legacy: \f[B]\f[CB]stylesheet\f[B]\f[R])
7008A string value (path to CSS stylesheet).
7010\f[B]\f[CB]page-progression-direction\f[B]\f[R]
7011Either \f[C]ltr\f[R] or \f[C]rtl\f[R].
7012Specifies the \f[C]page-progression-direction\f[R] attribute for the
7013\f[C]spine\f[R] element.
7015\f[B]\f[CB]ibooks\f[B]\f[R]
7016iBooks-specific metadata, with the following fields:
7019\f[C]version\f[R]: (string)
7021\f[C]specified-fonts\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
7024\f[C]ipad-orientation-lock\f[R]:
7025\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
7027\f[C]iphone-orientation-lock\f[R]:
7028\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]
7030\f[C]binding\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default
7033\f[C]scroll-axis\f[R]:
7034\f[C]vertical\f[R]|\f[C]horizontal\f[R]|\f[C]default\f[R]
7036.SS The \f[C]epub:type\f[R] attribute
7038For \f[C]epub3\f[R] output, you can mark up the heading that corresponds
7039to an EPUB chapter using the \f[C]epub:type\f[R] attribute.
7040For example, to set the attribute to the value \f[C]prologue\f[R], use
7045# My chapter {epub:type=prologue}
7049Which will result in:
7053<body epub:type=\[dq]frontmatter\[dq]>
7054 <section epub:type=\[dq]prologue\[dq]>
7059Pandoc will output \f[C]<body epub:type=\[dq]bodymatter\[dq]>\f[R],
7060unless you use one of the following values, in which case either
7061\f[C]frontmatter\f[R] or \f[C]backmatter\f[R] will be output.
7067\f[C]epub:type\f[R] of first section
7069\f[C]epub:type\f[R] of body
7180By default, pandoc will download media referenced from any
7181\f[C]<img>\f[R], \f[C]<audio>\f[R], \f[C]<video>\f[R] or
7182\f[C]<source>\f[R] element present in the generated EPUB, and include it
7183in the EPUB container, yielding a completely self-contained EPUB.
7184If you want to link to external media resources instead, use raw HTML in
7185your source and add \f[C]data-external=\[dq]1\[dq]\f[R] to the tag with
7186the \f[C]src\f[R] attribute.
7191<audio controls=\[dq]1\[dq]>
7192 <source src=\[dq]https://example.com/music/toccata.mp3\[dq]
7193 data-external=\[dq]1\[dq] type=\[dq]audio/mpeg\[dq]>
7198.SH JUPYTER NOTEBOOKS
7200When creating a Jupyter notebook, pandoc will try to infer the notebook
7202Code blocks with the class \f[C]code\f[R] will be taken as code cells,
7203and intervening content will be taken as Markdown cells.
7204Attachments will automatically be created for images in Markdown cells.
7205Metadata will be taken from the \f[C]jupyter\f[R] metadata field.
7216 display_name: Python 2
7223 file_extension: \[dq].py\[dq]
7224 mimetype: \[dq]text/x-python\[dq]
7225 name: \[dq]python\[dq]
7226 nbconvert_exporter: \[dq]python\[dq]
7227 pygments_lexer: \[dq]ipython2\[dq]
7228 version: \[dq]2.7.15\[dq]
7233**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
7234bibendum felis dictum sodales.
7237print(\[dq]hello\[dq])
7243from IPython.display import HTML
7246console.log(\[dq]hello\[dq]);
7254This image  will be
7255included as a cell attachment.
7259If you want to add cell attributes, group cells differently, or add
7260output to code cells, then you need to include divs to indicate the
7262You can use either fenced divs or native divs for this.
7267:::::: {.cell .markdown}
7270**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
7271bibendum felis dictum sodales.
7274:::::: {.cell .code execution_count=1}
7275\[ga]\[ga]\[ga] {.python}
7276print(\[dq]hello\[dq])
7279::: {.output .stream .stdout}
7286:::::: {.cell .code execution_count=2}
7287\[ga]\[ga]\[ga] {.python}
7288from IPython.display import HTML
7291console.log(\[dq]hello\[dq]);
7297::: {.output .execute_result execution_count=2}
7298\[ga]\[ga]\[ga]{=html}
7300console.log(\[dq]hello\[dq]);
7310If you include raw HTML or TeX in an output cell, use the [raw
7311attribute][Extension: \f[C]fenced_attribute\f[R]], as shown in the last
7312cell of the example above.
7313Although pandoc can process \[lq]bare\[rq] raw HTML and TeX, the result
7314is often interspersed raw elements and normal textual elements, and in
7315an output cell pandoc expects a single, connected raw block.
7316To avoid using raw HTML or TeX except when marked explicitly using raw
7317attributes, we recommend specifying the extensions
7318\f[C]-raw_html-raw_tex+raw_attribute\f[R] when translating between
7319Markdown and ipynb notebooks.
7321Note that options and extensions that affect reading and writing of
7322Markdown will also affect Markdown cells in ipynb notebooks.
7323For example, \f[C]--wrap=preserve\f[R] will preserve soft line breaks in
7324Markdown cells; \f[C]--atx-headers\f[R] will cause ATX-style headings to
7325be used; and \f[C]--preserve-tabs\f[R] will prevent tabs from being
7327.SH SYNTAX HIGHLIGHTING
7329Pandoc will automatically highlight syntax in fenced code blocks that
7330are marked with a language name.
7331The Haskell library skylighting is used for highlighting.
7332Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and
7334To see a list of language names that pandoc will recognize, type
7335\f[C]pandoc --list-highlight-languages\f[R].
7337The color scheme can be selected using the \f[C]--highlight-style\f[R]
7339The default color scheme is \f[C]pygments\f[R], which imitates the
7340default color scheme used by the Python library pygments (though
7341pygments is not actually used to do the highlighting).
7342To see a list of highlight styles, type
7343\f[C]pandoc --list-highlight-styles\f[R].
7345If you are not satisfied with the predefined styles, you can use
7346\f[C]--print-highlight-style\f[R] to generate a JSON \f[C].theme\f[R]
7347file which can be modified and used as the argument to
7348\f[C]--highlight-style\f[R].
7349To get a JSON version of the \f[C]pygments\f[R] style, for example:
7353pandoc --print-highlight-style pygments > my.theme
7357Then edit \f[C]my.theme\f[R] and use it like this:
7361pandoc --highlight-style my.theme
7365If you are not satisfied with the built-in highlighting, or you want
7366highlight a language that isn\[cq]t supported, you can use the
7367\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax
7369Before writing your own, have a look at KDE\[cq]s repository of syntax
7372To disable highlighting, use the \f[C]--no-highlight\f[R] option.
7375Custom styles can be used in the docx and ICML formats.
7378By default, pandoc\[cq]s docx and ICML output applies a predefined set
7379of styles for blocks such as paragraphs and block quotes, and uses
7380largely default formatting (italics, bold) for inlines.
7381This will work for most purposes, especially alongside a
7382\f[C]reference.docx\f[R] file.
7383However, if you need to apply your own styles to blocks, or match a
7384preexisting set of styles, pandoc allows you to define custom styles for
7385blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.
7387If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute
7388\f[C]custom-style\f[R], pandoc will apply your specified style to the
7389contained elements (with the exception of elements whose function
7390depends on a style, like headings, code blocks, block quotes, or links).
7391So, for example, using the \f[C]bracketed_spans\f[R] syntax,
7395[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.
7399would produce a docx file with \[lq]Get out\[rq] styled with character
7400style \f[C]Emphatically\f[R].
7401Similarly, using the \f[C]fenced_divs\f[R] syntax,
7405Dickinson starts the poem simply:
7407::: {custom-style=\[dq]Poetry\[dq]}
7408| A Bird came down the Walk---
7409| He did not know I saw---
7414would style the two contained lines with the \f[C]Poetry\f[R] paragraph
7417For docx output, styles will be defined in the output file as inheriting
7418from normal text, if the styles are not yet in your reference.docx.
7419If they are already defined, pandoc will not alter the definition.
7421This feature allows for greatest customization in conjunction with
7423If you want all paragraphs after block quotes to be indented, you can
7424write a filter to apply the styles necessary.
7425If you want all italics to be transformed to the \f[C]Emphasis\f[R]
7426character style (perhaps to change their color), you can write a filter
7427which will transform all italicized inlines to inlines within an
7428\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
7430For docx output, you don\[cq]t need to enable any extensions for custom
7434The docx reader, by default, only reads those styles that it can convert
7435into pandoc elements, either by direct conversion or interpreting the
7436derivation of the input document\[cq]s styles.
7438By enabling the \f[C]styles\f[R] extension in the docx reader
7439(\f[C]-f docx+styles\f[R]), you can produce output that maintains the
7440styles of the input document, using the \f[C]custom-style\f[R] class.
7441Paragraph styles are interpreted as divs, while character styles are
7442interpreted as spans.
7444For example, using the \f[C]custom-style-reference.docx\f[R] file in the
7445test directory, we have the following different outputs:
7447Without the \f[C]+styles\f[R] extension:
7451$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
7454This is text with an *emphasized* text style. And this is text with a
7455**strengthened** text style.
7457> Here is a styled paragraph that inherits from Block Text.
7461And with the extension:
7465$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
7467::: {custom-style=\[dq]First Paragraph\[dq]}
7471::: {custom-style=\[dq]Body Text\[dq]}
7472This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style.
7473And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]}
7477::: {custom-style=\[dq]My Block Style\[dq]}
7478> Here is a styled paragraph that inherits from Block Text.
7483With these custom styles, you can use your input document as a
7484reference-doc while creating docx output (see below), and maintain the
7485same styles in your input and output files.
7488Pandoc can be extended with custom writers written in Lua.
7489(Pandoc includes a Lua interpreter, so Lua need not be installed
7492To use a custom writer, simply specify the path to the Lua script in
7493place of the output format.
7498pandoc -t data/sample.lua
7502Creating a custom writer requires writing a Lua function for each
7503possible element in a pandoc document.
7504To get a documented example which you can modify according to your
7509pandoc --print-default-data-file sample.lua
7513Note that custom writers have no default template.
7514If you want to use \f[C]--standalone\f[R] with a custom writer, you will
7515need to specify a template manually using \f[C]--template\f[R] or add a
7516new default template with the name
7517\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
7518subdirectory of your user data directory (see Templates).
7519.SH REPRODUCIBLE BUILDS
7521Some of the document formats pandoc targets (such as EPUB, docx, and
7522ODT) include build timestamps in the generated document.
7523That means that the files generated on successive builds will differ,
7524even if the source does not.
7525To avoid this, set the \f[C]SOURCE_DATE_EPOCH\f[R] environment variable,
7526and the timestamp will be taken from it instead of the current time.
7527\f[C]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp
7528(specifying the number of second since midnight UTC January 1, 1970).
7530Some document formats also include a unique identifier.
7531For EPUB, this can be set explicitly by setting the \f[C]identifier\f[R]
7532metadata field (see EPUB Metadata, above).
7533.SH A NOTE ON SECURITY
7535If you use pandoc to convert user-contributed content in a web
7536application, here are some things to keep in mind:
7538Although pandoc itself will not create or modify any files other than
7539those you explicitly ask it create (with the exception of temporary
7540files used in producing PDFs), a filter or custom writer could in
7541principle do anything on your file system.
7542Please audit filters and custom writers very carefully before using
7545If your application uses pandoc as a Haskell library (rather than
7546shelling out to the executable), it is possible to use it in a mode that
7547fully isolates pandoc from your file system, by running the pandoc
7548operations in the \f[C]PandocPure\f[R] monad.
7549See the document Using the pandoc API for more details.
7551Pandoc\[cq]s parsers can exhibit pathological performance on some corner
7553It is wise to put any pandoc operations under a timeout, to avoid DOS
7554attacks that exploit these issues.
7555If you are using the pandoc executable, you can add the command line
7556options \f[C]+RTS -M512M -RTS\f[R] (for example) to limit the heap size
7559The HTML generated by pandoc is not guaranteed to be safe.
7560If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
7561inject arbitrary HTML.
7562Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
7563content in attributes for headings, spans, and code blocks.
7564To be safe, you should run all the generated HTML through an HTML
7568Copyright 2006\[en]2021 John MacFarlane (jgm\[at]berkeley.edu).
7569Released under the GPL, version 2 or greater.
7570This software carries no warranty of any kind.
7571(See COPYRIGHT for full copyright and warranty notices.) For a full list
7572of contributors, see the file AUTHORS.md in the pandoc source code.
7574The Pandoc source code and all documentation may be downloaded
7575from <https://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