1Pandoc User’s Guide() Pandoc User’s Guide()
2
6 pandoc - general markup converter
7
9 pandoc [options] [input-file]...
10
12 Pandoc is a Haskell library for converting from one markup format to
13 another, and a command-line tool that uses this library.
14 Pandoc can convert between numerous markup and word processing formats,
16 including, but not limited to, various flavors of Markdown, HTML, LaTeX
17 and Word docx. For the full lists of input and output formats, see the
18 --from and --to options below. Pandoc can also produce PDF output: see
19 creating a PDF, below.
20 Pandoc’s enhanced version of Markdown includes syntax for tables, defi‐
22 nition lists, metadata blocks, footnotes, citations, math, and much
23 more. See below under Pandoc’s Markdown.
24 Pandoc has a modular design: it consists of a set of readers, which
26 parse text in a given format and produce a native representation of the
27 document (an abstract syntax tree or AST), and a set of writers, which
28 convert this native representation into a target format. Thus, adding
29 an input or output format requires only adding a reader or writer.
30 Users can also run custom pandoc filters to modify the intermediate
31 AST.
32 Because pandoc’s intermediate representation of a document is less ex‐
34 pressive than many of the formats it converts between, one should not
35 expect perfect conversions between every format and every other. Pan‐
36 doc attempts to preserve the structural elements of a document, but not
37 formatting details such as margin size. And some document elements,
38 such as complex tables, may not fit into pandoc’s simple document mod‐
39 el. While conversions from pandoc’s Markdown to all formats aspire to
40 be perfect, conversions from formats more expressive than pandoc’s
41 Markdown can be expected to be lossy.
42 Using pandoc
44 If no input-files are specified, input is read from stdin. Output goes
45 to stdout by default. For output to a file, use the -o option:
46 pandoc -o output.html input.txt
48 By default, pandoc produces a document fragment. To produce a stand‐
50 alone document (e.g. a valid HTML file including <head> and <body>),
51 use the -s or --standalone flag:
52 pandoc -s -o output.html input.txt
54 For more information on how standalone documents are produced, see Tem‐
56 plates below.
57 If multiple input files are given, pandoc will concatenate them all
59 (with blank lines between them) before parsing. (Use --file-scope to
60 parse files individually.)
61 Specifying formats
63 The format of the input and output can be specified explicitly using
64 command-line options. The input format can be specified using the
65 -f/--from option, the output format using the -t/--to option. Thus, to
66 convert hello.txt from Markdown to LaTeX, you could type:
67 pandoc -f markdown -t latex hello.txt
69 To convert hello.html from HTML to Markdown:
71 pandoc -f html -t markdown hello.html
73 Supported input and output formats are listed below under Options (see
75 -f for input formats and -t for output formats). You can also use pan‐
76 doc --list-input-formats and pandoc --list-output-formats to print
77 lists of supported formats.
78 If the input or output format is not specified explicitly, pandoc will
80 attempt to guess it from the extensions of the filenames. Thus, for
81 example,
82 pandoc -o hello.tex hello.txt
84 will convert hello.txt from Markdown to LaTeX. If no output file is
86 specified (so that output goes to stdout), or if the output file’s ex‐
87 tension is unknown, the output format will default to HTML. If no in‐
88 put file is specified (so that input comes from stdin), or if the input
89 files’ extensions are unknown, the input format will be assumed to be
90 Markdown.
91 Character encoding
93 Pandoc uses the UTF-8 character encoding for both input and output. If
94 your local character encoding is not UTF-8, you should pipe input and
95 output through iconv:
96 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
98 Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
100 OPML, DocBook, and Texinfo), information about the character encoding
101 is included in the document header, which will only be included if you
102 use the -s/--standalone option.
103 Creating a PDF
105 To produce a PDF, specify an output file with a .pdf extension:
106 pandoc test.txt -o test.pdf
108 By default, pandoc will use LaTeX to create the PDF, which requires
110 that a LaTeX engine be installed (see --pdf-engine below). Alterna‐
111 tively, pandoc can use ConTeXt, roff ms, or HTML as an intermediate
112 format. To do this, specify an output file with a .pdf extension, as
113 before, but add the --pdf-engine option or -t context, -t html, or -t
114 ms to the command line. The tool used to generate the PDF from the in‐
115 termediate format may be specified using --pdf-engine.
116 You can control the PDF style using variables, depending on the inter‐
118 mediate format used: see variables for LaTeX, variables for ConTeXt,
119 variables for wkhtmltopdf, variables for ms. When HTML is used as an
120 intermediate format, the output can be styled using --css.
121 To debug the PDF creation, it can be useful to look at the intermediate
123 representation: instead of -o test.pdf, use for example -s -o test.tex
124 to output the generated LaTeX. You can then test it with pdflatex
125 test.tex.
126 When using LaTeX, the following packages need to be available (they are
128 included with all recent versions of TeX Live): amsfonts, amsmath, lm,
129 unicode-math, iftex, listings (if the --listings option is used), fan‐
130 cyvrb, longtable, booktabs, graphicx (if the document contains images),
131 hyperref, xcolor, ulem, geometry (with the geometry variable set),
132 setspace (with linestretch), and babel (with lang). If CJKmainfont is
133 set, xeCJK is needed. The use of xelatex or lualatex as the PDF engine
134 requires fontspec. lualatex uses selnolig. xelatex uses bidi (with
135 the dir variable set). If the mathspec variable is set, xelatex will
136 use mathspec instead of unicode-math. The upquote and microtype pack‐
137 ages are used if available, and csquotes will be used for typography if
138 the csquotes variable or metadata field is set to a true value. The
139 natbib, biblatex, bibtex, and biber packages can optionally be used for
140 citation rendering. The following packages will be used to improve
141 output quality if present, but pandoc does not require them to be
142 present: upquote (for straight quotes in verbatim environments), mi‐
143 crotype (for better spacing adjustments), parskip (for better inter-
144 paragraph spaces), xurl (for better line breaks in URLs), bookmark (for
145 better PDF bookmarks), and footnotehyper or footnote (to allow foot‐
146 notes in tables).
147 Reading from the Web
149 Instead of an input file, an absolute URI may be given. In this case
150 pandoc will fetch the content using HTTP:
151 pandoc -f html -t markdown https://www.fsf.org
153 It is possible to supply a custom User-Agent string or other header
155 when requesting a document from a URL:
156 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
158 https://www.fsf.org
159
161 General options
162 -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
163 Specify input format. FORMAT can be:
164 • bibtex (BibTeX bibliography)
166 • biblatex (BibLaTeX bibliography)
168 • commonmark (CommonMark Markdown)
170 • commonmark_x (CommonMark Markdown with extensions)
172 • creole (Creole 1.0)
174 • csljson (CSL JSON bibliography)
176 • csv (CSV table)
178 • tsv (TSV table)
180 • docbook (DocBook)
182 • docx (Word docx)
184 • dokuwiki (DokuWiki markup)
186 • endnotexml (EndNote XML bibliography)
188 • epub (EPUB)
190 • fb2 (FictionBook2 e-book)
192 • gfm (GitHub-Flavored Markdown), or the deprecated and less ac‐
194 curate markdown_github; use markdown_github only if you need
195 extensions not supported in gfm.
196 • haddock (Haddock markup)
198 • html (HTML)
200 • ipynb (Jupyter notebook)
202 • jats (JATS XML)
204 • jira (Jira/Confluence wiki markup)
206 • json (JSON version of native AST)
208 • latex (LaTeX)
210 • markdown (Pandoc’s Markdown)
212 • markdown_mmd (MultiMarkdown)
214 • markdown_phpextra (PHP Markdown Extra)
216 • markdown_strict (original unextended Markdown)
218 • mediawiki (MediaWiki markup)
220 • man (roff man)
222 • muse (Muse)
224 • native (native Haskell)
226 • odt (ODT)
228 • opml (OPML)
230 • org (Emacs Org mode)
232 • ris (RIS bibliography)
234 • rtf (Rich Text Format)
236 • rst (reStructuredText)
238 • t2t (txt2tags)
240 • textile (Textile)
242 • tikiwiki (TikiWiki markup)
244 • twiki (TWiki markup)
246 • vimwiki (Vimwiki)
248 • the path of a custom Lua reader, see Custom readers and writ‐
250 ers below
251 Extensions can be individually enabled or disabled by appending
253 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
254 low, for a list of extensions and their names. See --list-in‐
255 put-formats and --list-extensions, below.
256 -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
258 Specify output format. FORMAT can be:
259 • asciidoc (AsciiDoc) or asciidoctor (AsciiDoctor)
261 • beamer (LaTeX beamer slide show)
263 • bibtex (BibTeX bibliography)
265 • biblatex (BibLaTeX bibliography)
267 • commonmark (CommonMark Markdown)
269 • commonmark_x (CommonMark Markdown with extensions)
271 • context (ConTeXt)
273 • csljson (CSL JSON bibliography)
275 • docbook or docbook4 (DocBook 4)
277 • docbook5 (DocBook 5)
279 • docx (Word docx)
281 • dokuwiki (DokuWiki markup)
283 • epub or epub3 (EPUB v3 book)
285 • epub2 (EPUB v2)
287 • fb2 (FictionBook2 e-book)
289 • gfm (GitHub-Flavored Markdown), or the deprecated and less ac‐
291 curate markdown_github; use markdown_github only if you need
292 extensions not supported in gfm.
293 • haddock (Haddock markup)
295 • html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
297 • html4 (XHTML 1.0 Transitional)
299 • icml (InDesign ICML)
301 • ipynb (Jupyter notebook)
303 • jats_archiving (JATS XML, Archiving and Interchange Tag Set)
305 • jats_articleauthoring (JATS XML, Article Authoring Tag Set)
307 • jats_publishing (JATS XML, Journal Publishing Tag Set)
309 • jats (alias for jats_archiving)
311 • jira (Jira/Confluence wiki markup)
313 • json (JSON version of native AST)
315 • latex (LaTeX)
317 • man (roff man)
319 • markdown (Pandoc’s Markdown)
321 • markdown_mmd (MultiMarkdown)
323 • markdown_phpextra (PHP Markdown Extra)
325 • markdown_strict (original unextended Markdown)
327 • markua (Markua)
329 • mediawiki (MediaWiki markup)
331 • ms (roff ms)
333 • muse (Muse)
335 • native (native Haskell)
337 • odt (OpenOffice text document)
339 • opml (OPML)
341 • opendocument (OpenDocument)
343 • org (Emacs Org mode)
345 • pdf (PDF)
347 • plain (plain text)
349 • pptx (PowerPoint slide show)
351 • rst (reStructuredText)
353 • rtf (Rich Text Format)
355 • texinfo (GNU Texinfo)
357 • textile (Textile)
359 • slideous (Slideous HTML and JavaScript slide show)
361 • slidy (Slidy HTML and JavaScript slide show)
363 • dzslides (DZSlides HTML5 + JavaScript slide show)
365 • revealjs (reveal.js HTML5 + JavaScript slide show)
367 • s5 (S5 HTML and JavaScript slide show)
369 • tei (TEI Simple)
371 • xwiki (XWiki markup)
373 • zimwiki (ZimWiki markup)
375 • the path of a custom Lua writer, see Custom readers and writ‐
377 ers below
378 Note that odt, docx, epub, and pdf output will not be directed
380 to stdout unless forced with -o -.
381 Extensions can be individually enabled or disabled by appending
383 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
384 low, for a list of extensions and their names. See --list-out‐
385 put-formats and --list-extensions, below.
386 -o FILE, --output=FILE
388 Write output to FILE instead of stdout. If FILE is -, output
389 will go to stdout, even if a non-textual format (docx, odt,
390 epub2, epub3) is specified.
391 --data-dir=DIRECTORY
393 Specify the user data directory to search for pandoc data files.
394 If this option is not specified, the default user data directory
395 will be used. On *nix and macOS systems this will be the pandoc
396 subdirectory of the XDG data directory (by default, $HOME/.lo‐
397 cal/share, overridable by setting the XDG_DATA_HOME environment
398 variable). If that directory does not exist and $HOME/.pandoc
399 exists, it will be used (for backwards compatibility). On Win‐
400 dows the default user data directory is C:\Users\USERNAME\AppDa‐
401 ta\Roaming\pandoc. You can find the default user data directory
402 on your system by looking at the output of pandoc --version.
403 Data files placed in this directory (for example, reference.odt,
404 reference.docx, epub.css, templates) will override pandoc’s nor‐
405 mal defaults.
406 -d FILE, --defaults=FILE
408 Specify a set of default option settings. FILE is a YAML file
409 whose fields correspond to command-line option settings. All
410 options for document conversion, including input and output
411 files, can be set using a defaults file. The file will be
412 searched for first in the working directory, and then in the de‐
413 faults subdirectory of the user data directory (see --data-dir).
414 The .yaml extension may be omitted. See the section Defaults
415 files for more information on the file format. Settings from
416 the defaults file may be overridden or extended by subsequent
417 options on the command line.
418 --bash-completion
420 Generate a bash completion script. To enable bash completion
421 with pandoc, add this to your .bashrc:
422 eval "$(pandoc --bash-completion)"
424 --verbose
426 Give verbose debugging output.
427 --quiet
429 Suppress warning messages.
430 --fail-if-warnings
432 Exit with error status if there are any warnings.
433 --log=FILE
435 Write log messages in machine-readable JSON format to FILE. All
436 messages above DEBUG level will be written, regardless of ver‐
437 bosity settings (--verbose, --quiet).
438 --list-input-formats
440 List supported input formats, one per line.
441 --list-output-formats
443 List supported output formats, one per line.
444 --list-extensions[=FORMAT]
446 List supported extensions for FORMAT, one per line, preceded by
447 a + or - indicating whether it is enabled by default in FORMAT.
448 If FORMAT is not specified, defaults for pandoc’s Markdown are
449 given.
450 --list-highlight-languages
452 List supported languages for syntax highlighting, one per line.
453 --list-highlight-styles
455 List supported styles for syntax highlighting, one per line.
456 See --highlight-style.
457 -v, --version
459 Print version.
460 -h, --help
462 Show usage message.
463 Reader options
465 --shift-heading-level-by=NUMBER
466 Shift heading levels by a positive or negative integer. For ex‐
467 ample, with --shift-heading-level-by=-1, level 2 headings become
468 level 1 headings, and level 3 headings become level 2 headings.
469 Headings cannot have a level less than 1, so a heading that
470 would be shifted below level 1 becomes a regular paragraph. Ex‐
471 ception: with a shift of -N, a level-N heading at the beginning
472 of the document replaces the metadata title. --shift-heading-
473 level-by=-1 is a good choice when converting HTML or Markdown
474 documents that use an initial level-1 heading for the document
475 title and level-2+ headings for sections. --shift-heading-lev‐
476 el-by=1 may be a good choice for converting Markdown documents
477 that use level-1 headings for sections to HTML, since pandoc us‐
478 es a level-1 heading to render the document title.
479 --base-header-level=NUMBER
481 Deprecated. Use --shift-heading-level-by=X instead, where X =
482 NUMBER - 1. Specify the base level for headings (defaults to 1).
483 --strip-empty-paragraphs
485 Deprecated. Use the +empty_paragraphs extension instead. Ignore
486 paragraphs with no content. This option is useful for convert‐
487 ing word processing documents where users have used empty para‐
488 graphs to create inter-paragraph space.
489 --indented-code-classes=CLASSES
491 Specify classes to use for indented code blocks–for example,
492 perl,numberLines or haskell. Multiple classes may be separated
493 by spaces or commas.
494 --default-image-extension=EXTENSION
496 Specify a default extension to use when image paths/URLs have no
497 extension. This allows you to use the same source for formats
498 that require different kinds of images. Currently this option
499 only affects the Markdown and LaTeX readers.
500 --file-scope
502 Parse each file individually before combining for multifile doc‐
503 uments. This will allow footnotes in different files with the
504 same identifiers to work as expected. If this option is set,
505 footnotes and links will not work across files. Reading binary
506 files (docx, odt, epub) implies --file-scope.
507 -F PROGRAM, --filter=PROGRAM
509 Specify an executable to be used as a filter transforming the
510 pandoc AST after the input is parsed and before the output is
511 written. The executable should read JSON from stdin and write
512 JSON to stdout. The JSON must be formatted like pandoc’s own
513 JSON input and output. The name of the output format will be
514 passed to the filter as the first argument. Hence,
515 pandoc --filter ./caps.py -t latex
517 is equivalent to
519 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
521 The latter form may be useful for debugging filters.
523 Filters may be written in any language. Text.Pandoc.JSON ex‐
525 ports toJSONFilter to facilitate writing filters in Haskell.
526 Those who would prefer to write filters in python can use the
527 module pandocfilters, installable from PyPI. There are also
528 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
529 In order of preference, pandoc will look for filters in
531 1. a specified full or relative path (executable or non-exe‐
533 cutable),
534 2. $DATADIR/filters (executable or non-executable) where
536 $DATADIR is the user data directory (see --data-dir, above),
537 3. $PATH (executable only).
539 Filters, Lua-filters, and citeproc processing are applied in the
541 order specified on the command line.
542 -L SCRIPT, --lua-filter=SCRIPT
544 Transform the document in a similar fashion as JSON filters (see
545 --filter), but use pandoc’s built-in Lua filtering system. The
546 given Lua script is expected to return a list of Lua filters
547 which will be applied in order. Each Lua filter must contain
548 element-transforming functions indexed by the name of the AST
549 element on which the filter function should be applied.
550 The pandoc Lua module provides helper functions for element cre‐
552 ation. It is always loaded into the script’s Lua environment.
553 See the Lua filters documentation for further details.
555 In order of preference, pandoc will look for Lua filters in
557 1. a specified full or relative path,
559 2. $DATADIR/filters where $DATADIR is the user data directory
561 (see --data-dir, above).
562 Filters, Lua filters, and citeproc processing are applied in the
564 order specified on the command line.
565 -M KEY[=VAL], --metadata=KEY[:VAL]
567 Set the metadata field KEY to the value VAL. A value specified
568 on the command line overrides a value specified in the document
569 using YAML metadata blocks. Values will be parsed as YAML bool‐
570 ean or string values. If no value is specified, the value will
571 be treated as Boolean true. Like --variable, --metadata causes
572 template variables to be set. But unlike --variable, --metadata
573 affects the metadata of the underlying document (which is acces‐
574 sible from filters and may be printed in some output formats)
575 and metadata values will be escaped when inserted into the tem‐
576 plate.
577 --metadata-file=FILE
579 Read metadata from the supplied YAML (or JSON) file. This op‐
580 tion can be used with every input format, but string scalars in
581 the YAML file will always be parsed as Markdown. (If the input
582 format is Markdown or a Markdown variant, then the same variant
583 will be used to parse the metadata file; if it is a non-Markdown
584 format, pandoc’s default Markdown extensions will be used.)
585 This option can be used repeatedly to include multiple metadata
586 files; values in files specified later on the command line will
587 be preferred over those specified in earlier files. Metadata
588 values specified inside the document, or by using -M, overwrite
589 values specified with this option. The file will be searched
590 for first in the working directory, and then in the metadata
591 subdirectory of the user data directory (see --data-dir).
592 -p, --preserve-tabs
594 Preserve tabs instead of converting them to spaces. (By de‐
595 fault, pandoc converts tabs to spaces before parsing its input.)
596 Note that this will only affect tabs in literal code spans and
597 code blocks. Tabs in regular text are always treated as spaces.
598 --tab-stop=NUMBER
600 Specify the number of spaces per tab (default is 4).
601 --track-changes=accept|reject|all
603 Specifies what to do with insertions, deletions, and comments
604 produced by the MS Word “Track Changes” feature. accept (the
605 default) processes all the insertions and deletions. reject ig‐
606 nores them. Both accept and reject ignore comments. all in‐
607 cludes all insertions, deletions, and comments, wrapped in spans
608 with insertion, deletion, comment-start, and comment-end class‐
609 es, respectively. The author and time of change is included.
610 all is useful for scripting: only accepting changes from a cer‐
611 tain reviewer, say, or before a certain date. If a paragraph is
612 inserted or deleted, track-changes=all produces a span with the
613 class paragraph-insertion/paragraph-deletion before the affected
614 paragraph break. This option only affects the docx reader.
615 --extract-media=DIR
617 Extract images and other media contained in or linked from the
618 source document to the path DIR, creating it if necessary, and
619 adjust the images references in the document so they point to
620 the extracted files. Media are downloaded, read from the file
621 system, or extracted from a binary container (e.g. docx), as
622 needed. The original file paths are used if they are relative
623 paths not containing ... Otherwise filenames are constructed
624 from the SHA1 hash of the contents.
625 --abbreviations=FILE
627 Specifies a custom abbreviations file, with abbreviations one to
628 a line. If this option is not specified, pandoc will read the
629 data file abbreviations from the user data directory or fall
630 back on a system default. To see the system default, use pandoc
631 --print-default-data-file=abbreviations. The only use pandoc
632 makes of this list is in the Markdown reader. Strings found in
633 this list will be followed by a nonbreaking space, and the peri‐
634 od will not produce sentence-ending space in formats like LaTeX.
635 The strings may not contain spaces.
636 --trace
638 Print diagnostic output tracing parser progress to stderr. This
639 option is intended for use by developers in diagnosing perfor‐
640 mance issues.
641 General writer options
643 -s, --standalone
644 Produce output with an appropriate header and footer (e.g. a
645 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
646 option is set automatically for pdf, epub, epub3, fb2, docx, and
647 odt output. For native output, this option causes metadata to
648 be included; otherwise, metadata is suppressed.
649 --template=FILE|URL
651 Use the specified file as a custom template for the generated
652 document. Implies --standalone. See Templates, below, for a
653 description of template syntax. If no extension is specified,
654 an extension corresponding to the writer will be added, so that
655 --template=special looks for special.html for HTML output. If
656 the template is not found, pandoc will search for it in the tem‐
657 plates subdirectory of the user data directory (see --data-dir).
658 If this option is not used, a default template appropriate for
659 the output format will be used (see -D/--print-default-tem‐
660 plate).
661 -V KEY[=VAL], --variable=KEY[:VAL]
663 Set the template variable KEY to the value VAL when rendering
664 the document in standalone mode. If no VAL is specified, the
665 key will be given the value true.
666 --sandbox
668 Run pandoc in a sandbox, limiting IO operations in readers and
669 writers to reading the files specified on the command line.
670 Note that this option does not limit IO operations by filters or
671 in the production of PDF documents. But it does offer security
672 against, for example, disclosure of files through the use of in‐
673 clude directives. Anyone using pandoc on untrusted user input
674 should use this option.
675 Note: some readers and writers (e.g., docx) need access to data
677 files. If these are stored on the file system, then pandoc will
678 not be able to find them when run in --sandbox mode and will
679 raise an error. For these applications, we recommend using a
680 pandoc binary compiled with the embed_data_files option, which
681 causes the data files to be baked into the binary instead of be‐
682 ing stored on the file system.
683 -D FORMAT, --print-default-template=FORMAT
685 Print the system default template for an output FORMAT. (See -t
686 for a list of possible FORMATs.) Templates in the user data di‐
687 rectory are ignored. This option may be used with -o/--output
688 to redirect output to a file, but -o/--output must come before
689 --print-default-template on the command line.
690 Note that some of the default templates use partials, for exam‐
692 ple styles.html. To print the partials, use --print-default-da‐
693 ta-file: for example, --print-default-data-file=tem‐
694 plates/styles.html.
695 --print-default-data-file=FILE
697 Print a system default data file. Files in the user data direc‐
698 tory are ignored. This option may be used with -o/--output to
699 redirect output to a file, but -o/--output must come before
700 --print-default-data-file on the command line.
701 --eol=crlf|lf|native
703 Manually specify line endings: crlf (Windows), lf (macOS/Lin‐
704 ux/UNIX), or native (line endings appropriate to the OS on which
705 pandoc is being run). The default is native.
706 --dpi=NUMBER
708 Specify the default dpi (dots per inch) value for conversion
709 from pixels to inch/centimeters and vice versa. (Technically,
710 the correct term would be ppi: pixels per inch.) The default is
711 96dpi. When images contain information about dpi internally,
712 the encoded value is used instead of the default specified by
713 this option.
714 --wrap=auto|none|preserve
716 Determine how text is wrapped in the output (the source code,
717 not the rendered version). With auto (the default), pandoc will
718 attempt to wrap lines to the column width specified by --columns
719 (default 72). With none, pandoc will not wrap lines at all.
720 With preserve, pandoc will attempt to preserve the wrapping from
721 the source document (that is, where there are nonsemantic new‐
722 lines in the source, there will be nonsemantic newlines in the
723 output as well). In ipynb output, this option affects wrapping
724 of the contents of markdown cells.
725 --columns=NUMBER
727 Specify length of lines in characters. This affects text wrap‐
728 ping in the generated source code (see --wrap). It also affects
729 calculation of column widths for plain text tables (see Tables
730 below).
731 --toc, --table-of-contents
733 Include an automatically generated table of contents (or, in the
734 case of latex, context, docx, odt, opendocument, rst, or ms, an
735 instruction to create one) in the output document. This option
736 has no effect unless -s/--standalone is used, and it has no ef‐
737 fect on man, docbook4, docbook5, or jats output.
738 Note that if you are producing a PDF via ms, the table of con‐
740 tents will appear at the beginning of the document, before the
741 title. If you would prefer it to be at the end of the document,
742 use the option --pdf-engine-opt=--no-toc-relocation.
743 --toc-depth=NUMBER
745 Specify the number of section levels to include in the table of
746 contents. The default is 3 (which means that level-1, 2, and 3
747 headings will be listed in the contents).
748 --strip-comments
750 Strip out HTML comments in the Markdown or Textile source,
751 rather than passing them on to Markdown, Textile or HTML output
752 as raw HTML. This does not apply to HTML comments inside raw
753 HTML blocks when the markdown_in_html_blocks extension is not
754 set.
755 --no-highlight
757 Disables syntax highlighting for code blocks and inlines, even
758 when a language attribute is given.
759 --highlight-style=STYLE|FILE
761 Specifies the coloring style to be used in highlighted source
762 code. Options are pygments (the default), kate, monochrome,
763 breezeDark, espresso, zenburn, haddock, and tango. For more in‐
764 formation on syntax highlighting in pandoc, see Syntax high‐
765 lighting, below. See also --list-highlight-styles.
766 Instead of a STYLE name, a JSON file with extension .theme may
768 be supplied. This will be parsed as a KDE syntax highlighting
769 theme and (if valid) used as the highlighting style.
770 To generate the JSON version of an existing style, use --print-
772 highlight-style.
773 --print-highlight-style=STYLE|FILE
775 Prints a JSON version of a highlighting style, which can be mod‐
776 ified, saved with a .theme extension, and used with --highlight-
777 style. This option may be used with -o/--output to redirect
778 output to a file, but -o/--output must come before --print-high‐
779 light-style on the command line.
780 --syntax-definition=FILE
782 Instructs pandoc to load a KDE XML syntax definition file, which
783 will be used for syntax highlighting of appropriately marked
784 code blocks. This can be used to add support for new languages
785 or to use altered syntax definitions for existing languages.
786 This option may be repeated to add multiple syntax definitions.
787 -H FILE, --include-in-header=FILE|URL
789 Include contents of FILE, verbatim, at the end of the header.
790 This can be used, for example, to include special CSS or Java‐
791 Script in HTML documents. This option can be used repeatedly to
792 include multiple files in the header. They will be included in
793 the order specified. Implies --standalone.
794 -B FILE, --include-before-body=FILE|URL
796 Include contents of FILE, verbatim, at the beginning of the doc‐
797 ument body (e.g. after the <body> tag in HTML, or the \be‐
798 gin{document} command in LaTeX). This can be used to include
799 navigation bars or banners in HTML documents. This option can
800 be used repeatedly to include multiple files. They will be in‐
801 cluded in the order specified. Implies --standalone.
802 -A FILE, --include-after-body=FILE|URL
804 Include contents of FILE, verbatim, at the end of the document
805 body (before the </body> tag in HTML, or the \end{document} com‐
806 mand in LaTeX). This option can be used repeatedly to include
807 multiple files. They will be included in the order specified.
808 Implies --standalone.
809 --resource-path=SEARCHPATH
811 List of paths to search for images and other resources. The
812 paths should be separated by : on Linux, UNIX, and macOS sys‐
813 tems, and by ; on Windows. If --resource-path is not specified,
814 the default resource path is the working directory. Note that,
815 if --resource-path is specified, the working directory must be
816 explicitly listed or it will not be searched. For example:
817 --resource-path=.:test will search the working directory and the
818 test subdirectory, in that order. This option can be used re‐
819 peatedly. Search path components that come later on the command
820 line will be searched before those that come earlier, so --re‐
821 source-path foo:bar --resource-path baz:bim is equivalent to
822 --resource-path baz:bim:foo:bar.
823 --request-header=NAME:VAL
825 Set the request header NAME to the value VAL when making HTTP
826 requests (for example, when a URL is given on the command line,
827 or when resources used in a document must be downloaded). If
828 you’re behind a proxy, you also need to set the environment
829 variable http_proxy to http://....
830 --no-check-certificate
832 Disable the certificate verification to allow access to unsecure
833 HTTP resources (for example when the certificate is no longer
834 valid or self signed).
835 Options affecting specific writers
837 --self-contained
838 Deprecated synonym for --embed-resources --standalone.
839 --embed-resources
841 Produce a standalone HTML file with no external dependencies,
842 using data: URIs to incorporate the contents of linked scripts,
843 stylesheets, images, and videos. The resulting file should be
844 “self-contained,” in the sense that it needs no external files
845 and no net access to be displayed properly by a browser. This
846 option works only with HTML output formats, including html4,
847 html5, html+lhs, html5+lhs, s5, slidy, slideous, dzslides, and
848 revealjs. Scripts, images, and stylesheets at absolute URLs
849 will be downloaded; those at relative URLs will be sought rela‐
850 tive to the working directory (if the first source file is lo‐
851 cal) or relative to the base URL (if the first source file is
852 remote). Elements with the attribute data-external="1" will be
853 left alone; the documents they link to will not be incorporated
854 in the document. Limitation: resources that are loaded dynami‐
855 cally through JavaScript cannot be incorporated; as a result,
856 some advanced features (e.g. zoom or speaker notes) may not work
857 in an offline “self-contained” reveal.js slide show.
858 --html-q-tags
860 Use <q> tags for quotes in HTML. (This option only has an ef‐
861 fect if the smart extension is enabled for the input format
862 used.)
863 --ascii
865 Use only ASCII characters in output. Currently supported for
866 XML and HTML formats (which use entities instead of UTF-8 when
867 this option is selected), CommonMark, gfm, and Markdown (which
868 use entities), roff ms (which use hexadecimal escapes), and to a
869 limited degree LaTeX (which uses standard commands for accented
870 characters when possible). roff man output uses ASCII by de‐
871 fault.
872 --reference-links
874 Use reference-style links, rather than inline links, in writing
875 Markdown or reStructuredText. By default inline links are used.
876 The placement of link references is affected by the --reference-
877 location option.
878 --reference-location=block|section|document
880 Specify whether footnotes (and references, if reference-links is
881 set) are placed at the end of the current (top-level) block, the
882 current section, or the document. The default is document.
883 Currently this option only affects the markdown, muse, html,
884 epub, slidy, s5, slideous, dzslides, and revealjs writers.
885 --markdown-headings=setext|atx
887 Specify whether to use ATX-style (#-prefixed) or Setext-style
888 (underlined) headings for level 1 and 2 headings in Markdown
889 output. (The default is atx.) ATX-style headings are always
890 used for levels 3+. This option also affects Markdown cells in
891 ipynb output.
892 --atx-headers
894 Deprecated synonym for --markdown-headings=atx.
895 --top-level-division=default|section|chapter|part
897 Treat top-level headings as the given division type in LaTeX,
898 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
899 chapter, then section; all headings are shifted such that the
900 top-level heading becomes the specified type. The default be‐
901 havior is to determine the best division type via heuristics:
902 unless other conditions apply, section is chosen. When the doc‐
903 umentclass variable is set to report, book, or memoir (unless
904 the article option is specified), chapter is implied as the set‐
905 ting for this option. If beamer is the output format, specify‐
906 ing either chapter or part will cause top-level headings to be‐
907 come \part{..}, while second-level headings remain as their de‐
908 fault type.
909 -N, --number-sections
911 Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or
912 EPUB output. By default, sections are not numbered. Sections
913 with class unnumbered will never be numbered, even if --number-
914 sections is specified.
915 --number-offset=NUMBER[,NUMBER,...]
917 Offset for section headings in HTML output (ignored in other
918 output formats). The first number is added to the section num‐
919 ber for top-level headings, the second for second-level head‐
920 ings, and so on. So, for example, if you want the first top-
921 level heading in your document to be numbered “6”, specify
922 --number-offset=5. If your document starts with a level-2 head‐
923 ing which you want to be numbered “1.5”, specify --number-off‐
924 set=1,4. Offsets are 0 by default. Implies --number-sections.
925 --listings
927 Use the listings package for LaTeX code blocks. The package
928 does not support multi-byte encoding for source code. To handle
929 UTF-8 you would need to use a custom template. This issue is
930 fully documented here: Encoding issue with the listings package.
931 -i, --incremental
933 Make list items in slide shows display incrementally (one by
934 one). The default is for lists to be displayed all at once.
935 --slide-level=NUMBER
937 Specifies that headings with the specified level create slides
938 (for beamer, s5, slidy, slideous, dzslides). Headings above
939 this level in the hierarchy are used to divide the slide show
940 into sections; headings below this level create subheads within
941 a slide. Valid values are 0-6. If a slide level of 0 is speci‐
942 fied, slides will not be split automatically on headings, and
943 horizontal rules must be used to indicate slide boundaries. If
944 a slide level is not specified explicitly, the slide level will
945 be set automatically based on the contents of the document; see
946 Structuring the slide show.
947 --section-divs
949 Wrap sections in <section> tags (or <div> tags for html4), and
950 attach identifiers to the enclosing <section> (or <div>) rather
951 than the heading itself. See Heading identifiers, below.
952 --email-obfuscation=none|javascript|references
954 Specify a method for obfuscating mailto: links in HTML docu‐
955 ments. none leaves mailto: links as they are. javascript ob‐
956 fuscates them using JavaScript. references obfuscates them by
957 printing their letters as decimal or hexadecimal character ref‐
958 erences. The default is none.
959 --id-prefix=STRING
961 Specify a prefix to be added to all identifiers and internal
962 links in HTML and DocBook output, and to footnote numbers in
963 Markdown and Haddock output. This is useful for preventing du‐
964 plicate identifiers when generating fragments to be included in
965 other pages.
966 -T STRING, --title-prefix=STRING
968 Specify STRING as a prefix at the beginning of the title that
969 appears in the HTML header (but not in the title as it appears
970 at the beginning of the HTML body). Implies --standalone.
971 -c URL, --css=URL
973 Link to a CSS style sheet. This option can be used repeatedly
974 to include multiple files. They will be included in the order
975 specified.
976 A stylesheet is required for generating EPUB. If none is pro‐
978 vided using this option (or the css or stylesheet metadata
979 fields), pandoc will look for a file epub.css in the user data
980 directory (see --data-dir). If it is not found there, sensible
981 defaults will be used.
982 --reference-doc=FILE
984 Use the specified file as a style reference in producing a docx
985 or ODT file.
986 Docx For best results, the reference docx should be a modified
988 version of a docx file produced using pandoc. The con‐
989 tents of the reference docx are ignored, but its
990 stylesheets and document properties (including margins,
991 page size, header, and footer) are used in the new docx.
992 If no reference docx is specified on the command line,
993 pandoc will look for a file reference.docx in the user
994 data directory (see --data-dir). If this is not found
995 either, sensible defaults will be used.
996 To produce a custom reference.docx, first get a copy of
998 the default reference.docx: pandoc -o custom-refer‐
999 ence.docx --print-default-data-file reference.docx. Then
1000 open custom-reference.docx in Word, modify the styles as
1001 you wish, and save the file. For best results, do not
1002 make changes to this file other than modifying the styles
1003 used by pandoc:
1004 Paragraph styles:
1006 • Normal
1008 • Body Text
1010 • First Paragraph
1012 • Compact
1014 • Title
1016 • Subtitle
1018 • Author
1020 • Date
1022 • Abstract
1024 • Bibliography
1026 • Heading 1
1028 • Heading 2
1030 • Heading 3
1032 • Heading 4
1034 • Heading 5
1036 • Heading 6
1038 • Heading 7
1040 • Heading 8
1042 • Heading 9
1044 • Block Text
1046 • Source Code
1048 • Footnote Text
1050 • Definition Term
1052 • Definition
1054 • Caption
1056 • Table Caption
1058 • Image Caption
1060 • Figure
1062 • Captioned Figure
1064 • TOC Heading
1066 Character styles:
1068 • Default Paragraph Font
1070 • Body Text Char
1072 • Verbatim Char
1074 • Footnote Reference
1076 • Hyperlink
1078 • Section Number
1080 Table style:
1082 • Table
1084 ODT For best results, the reference ODT should be a modified
1086 version of an ODT produced using pandoc. The contents of
1087 the reference ODT are ignored, but its stylesheets are
1088 used in the new ODT. If no reference ODT is specified on
1089 the command line, pandoc will look for a file refer‐
1090 ence.odt in the user data directory (see --data-dir). If
1091 this is not found either, sensible defaults will be used.
1092 To produce a custom reference.odt, first get a copy of
1094 the default reference.odt: pandoc -o custom-reference.odt
1095 --print-default-data-file reference.odt. Then open cus‐
1096 tom-reference.odt in LibreOffice, modify the styles as
1097 you wish, and save the file.
1098 PowerPoint
1100 Templates included with Microsoft PowerPoint 2013 (either
1101 with .pptx or .potx extension) are known to work, as are
1102 most templates derived from these.
1103 The specific requirement is that the template should con‐
1105 tain layouts with the following names (as seen within
1106 PowerPoint):
1107 • Title Slide
1109 • Title and Content
1111 • Section Header
1113 • Two Content
1115 • Comparison
1117 • Content with Caption
1119 • Blank
1121 For each name, the first layout found with that name will
1123 be used. If no layout is found with one of the names,
1124 pandoc will output a warning and use the layout with that
1125 name from the default reference doc instead. (How these
1126 layouts are used is described in PowerPoint layout
1127 choice.)
1128 All templates included with a recent version of MS Power‐
1130 Point will fit these criteria. (You can click on Layout
1131 under the Home menu to check.)
1132 You can also modify the default reference.pptx: first run
1134 pandoc -o custom-reference.pptx --print-default-data-file
1135 reference.pptx, and then modify custom-reference.pptx in
1136 MS PowerPoint (pandoc will use the layouts with the names
1137 listed above).
1138 --epub-cover-image=FILE
1140 Use the specified image as the EPUB cover. It is recommended
1141 that the image be less than 1000px in width and height. Note
1142 that in a Markdown source document you can also specify cover-
1143 image in a YAML metadata block (see EPUB Metadata, below).
1144 --epub-metadata=FILE
1146 Look in the specified XML file for metadata for the EPUB. The
1147 file should contain a series of Dublin Core elements. For exam‐
1148 ple:
1149 <dc:rights>Creative Commons</dc:rights>
1151 <dc:language>es-AR</dc:language>
1152 By default, pandoc will include the following metadata elements:
1154 <dc:title> (from the document title), <dc:creator> (from the
1155 document authors), <dc:date> (from the document date, which
1156 should be in ISO 8601 format), <dc:language> (from the lang
1157 variable, or, if is not set, the locale), and <dc:identifier
1158 id="BookId"> (a randomly generated UUID). Any of these may be
1159 overridden by elements in the metadata file.
1160 Note: if the source document is Markdown, a YAML metadata block
1162 in the document can be used instead. See below under EPUB Meta‐
1163 data.
1164 --epub-embed-font=FILE
1166 Embed the specified font in the EPUB. This option can be re‐
1167 peated to embed multiple fonts. Wildcards can also be used: for
1168 example, DejaVuSans-*.ttf. However, if you use wildcards on the
1169 command line, be sure to escape them or put the whole filename
1170 in single quotes, to prevent them from being interpreted by the
1171 shell. To use the embedded fonts, you will need to add declara‐
1172 tions like the following to your CSS (see --css):
1173 @font-face {
1175 font-family: DejaVuSans;
1176 font-style: normal;
1177 font-weight: normal;
1178 src:url("DejaVuSans-Regular.ttf");
1179 }
1180 @font-face {
1181 font-family: DejaVuSans;
1182 font-style: normal;
1183 font-weight: bold;
1184 src:url("DejaVuSans-Bold.ttf");
1185 }
1186 @font-face {
1187 font-family: DejaVuSans;
1188 font-style: italic;
1189 font-weight: normal;
1190 src:url("DejaVuSans-Oblique.ttf");
1191 }
1192 @font-face {
1193 font-family: DejaVuSans;
1194 font-style: italic;
1195 font-weight: bold;
1196 src:url("DejaVuSans-BoldOblique.ttf");
1197 }
1198 body { font-family: "DejaVuSans"; }
1199 --epub-chapter-level=NUMBER
1201 Specify the heading level at which to split the EPUB into sepa‐
1202 rate “chapter” files. The default is to split into chapters at
1203 level-1 headings. This option only affects the internal compo‐
1204 sition of the EPUB, not the way chapters and sections are dis‐
1205 played to users. Some readers may be slow if the chapter files
1206 are too large, so for large documents with few level-1 headings,
1207 one might want to use a chapter level of 2 or 3.
1208 --epub-subdirectory=DIRNAME
1210 Specify the subdirectory in the OCF container that is to hold
1211 the EPUB-specific contents. The default is EPUB. To put the
1212 EPUB contents in the top level, use an empty string.
1213 --ipynb-output=all|none|best
1215 Determines how ipynb output cells are treated. all means that
1216 all of the data formats included in the original are preserved.
1217 none means that the contents of data cells are omitted. best
1218 causes pandoc to try to pick the richest data block in each out‐
1219 put cell that is compatible with the output format. The default
1220 is best.
1221 --pdf-engine=PROGRAM
1223 Use the specified engine when producing PDF output. Valid val‐
1224 ues are pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtml‐
1225 topdf, weasyprint, pagedjs-cli, prince, context, and pdfroff.
1226 If the engine is not in your PATH, the full path of the engine
1227 may be specified here. If this option is not specified, pandoc
1228 uses the following defaults depending on the output format spec‐
1229 ified using -t/--to:
1230 • -t latex or none: pdflatex (other options: xelatex, lualatex,
1232 tectonic, latexmk)
1233 • -t context: context
1235 • -t html: wkhtmltopdf (other options: prince, weasyprint,
1237 pagedjs-cli; see print-css.rocks for a good introduction to
1238 PDF generation from HTML/CSS)
1239 • -t ms: pdfroff
1241 --pdf-engine-opt=STRING
1243 Use the given string as a command-line argument to the pdf-en‐
1244 gine. For example, to use a persistent directory foo for la‐
1245 texmk’s auxiliary files, use --pdf-engine-opt=-outdir=foo. Note
1246 that no check for duplicate options is done.
1247 Citation rendering
1249 -C, --citeproc
1250 Process the citations in the file, replacing them with rendered
1251 citations and adding a bibliography. Citation processing will
1252 not take place unless bibliographic data is supplied, either
1253 through an external file specified using the --bibliography op‐
1254 tion or the bibliography field in metadata, or via a references
1255 section in metadata containing a list of citations in CSL YAML
1256 format with Markdown formatting. The style is controlled by a
1257 CSL stylesheet specified using the --csl option or the csl field
1258 in metadata. (If no stylesheet is specified, the chicago-au‐
1259 thor-date style will be used by default.) The citation process‐
1260 ing transformation may be applied before or after filters or Lua
1261 filters (see --filter, --lua-filter): these transformations are
1262 applied in the order they appear on the command line. For more
1263 information, see the section on Citations.
1264 --bibliography=FILE
1266 Set the bibliography field in the document’s metadata to FILE,
1267 overriding any value set in the metadata. If you supply this
1268 argument multiple times, each FILE will be added to bibliogra‐
1269 phy. If FILE is a URL, it will be fetched via HTTP. If FILE is
1270 not found relative to the working directory, it will be sought
1271 in the resource path (see --resource-path).
1272 --csl=FILE
1274 Set the csl field in the document’s metadata to FILE, overriding
1275 any value set in the metadata. (This is equivalent to --metada‐
1276 ta csl=FILE.) If FILE is a URL, it will be fetched via HTTP.
1277 If FILE is not found relative to the working directory, it will
1278 be sought in the resource path (see --resource-path) and finally
1279 in the csl subdirectory of the pandoc user data directory.
1280 --citation-abbreviations=FILE
1282 Set the citation-abbreviations field in the document’s metadata
1283 to FILE, overriding any value set in the metadata. (This is
1284 equivalent to --metadata citation-abbreviations=FILE.) If FILE
1285 is a URL, it will be fetched via HTTP. If FILE is not found
1286 relative to the working directory, it will be sought in the re‐
1287 source path (see --resource-path) and finally in the csl subdi‐
1288 rectory of the pandoc user data directory.
1289 --natbib
1291 Use natbib for citations in LaTeX output. This option is not
1292 for use with the --citeproc option or with PDF output. It is
1293 intended for use in producing a LaTeX file that can be processed
1294 with bibtex.
1295 --biblatex
1297 Use biblatex for citations in LaTeX output. This option is not
1298 for use with the --citeproc option or with PDF output. It is
1299 intended for use in producing a LaTeX file that can be processed
1300 with bibtex or biber.
1301 Math rendering in HTML
1303 The default is to render TeX math as far as possible using Unicode
1304 characters. Formulas are put inside a span with class="math", so that
1305 they may be styled differently from the surrounding text if needed.
1306 However, this gives acceptable results only for basic math, usually you
1307 will want to use --mathjax or another of the following options.
1308 --mathjax[=URL]
1310 Use MathJax to display embedded TeX math in HTML output. TeX
1311 math will be put between \(...\) (for inline math) or \[...\]
1312 (for display math) and wrapped in <span> tags with class math.
1313 Then the MathJax JavaScript will render it. The URL should
1314 point to the MathJax.js load script. If a URL is not provided,
1315 a link to the Cloudflare CDN will be inserted.
1316 --mathml
1318 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
1319 html4 and html5). This is the default in odt output. Note that
1320 currently only Firefox and Safari (and select e-book readers)
1321 natively support MathML.
1322 --webtex[=URL]
1324 Convert TeX formulas to <img> tags that link to an external
1325 script that converts formulas to images. The formula will be
1326 URL-encoded and concatenated with the URL provided. For SVG im‐
1327 ages you can for example use --webtex https://la‐
1328 tex.codecogs.com/svg.latex?. If no URL is specified, the
1329 CodeCogs URL generating PNGs will be used (https://la‐
1330 tex.codecogs.com/png.latex?). Note: the --webtex option will
1331 affect Markdown output as well as HTML, which is useful if
1332 you’re targeting a version of Markdown without native math sup‐
1333 port.
1334 --katex[=URL]
1336 Use KaTeX to display embedded TeX math in HTML output. The URL
1337 is the base URL for the KaTeX library. That directory should
1338 contain a katex.min.js and a katex.min.css file. If a URL is
1339 not provided, a link to the KaTeX CDN will be inserted.
1340 --gladtex
1342 Enclose TeX math in <eq> tags in HTML output. The resulting
1343 HTML can then be processed by GladTeX to produce SVG images of
1344 the typeset formulas and an HTML file with these images embed‐
1345 ded.
1346 pandoc -s --gladtex input.md -o myfile.htex
1348 gladtex -d image_dir myfile.htex
1349 # produces myfile.html and images in image_dir
1350 Options for wrapper scripts
1352 --dump-args
1353 Print information about command-line arguments to stdout, then
1354 exit. This option is intended primarily for use in wrapper
1355 scripts. The first line of output contains the name of the out‐
1356 put file specified with the -o option, or - (for stdout) if no
1357 output file was specified. The remaining lines contain the com‐
1358 mand-line arguments, one per line, in the order they appear.
1359 These do not include regular pandoc options and their arguments,
1360 but do include any options appearing after a -- separator at the
1361 end of the line.
1362 --ignore-args
1364 Ignore command-line arguments (for use in wrapper scripts).
1365 Regular pandoc options are not ignored. Thus, for example,
1366 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1368 is equivalent to
1370 pandoc -o foo.html -s
1372
1374 If pandoc completes successfully, it will return exit code 0. Nonzero
1375 exit codes have the following meanings:
1376 Code Error
1378 ------ -------------------------------------
1379 1 PandocIOError
1380 3 PandocFailOnWarningError
1381 4 PandocAppError
1382 5 PandocTemplateError
1383 6 PandocOptionError
1384 21 PandocUnknownReaderError
1385 22 PandocUnknownWriterError
1386 23 PandocUnsupportedExtensionError
1387 24 PandocCiteprocError
1388 25 PandocBibliographyError
1389 31 PandocEpubSubdirectoryError
1390 43 PandocPDFError
1391 44 PandocXMLError
1392 47 PandocPDFProgramNotFoundError
1393 61 PandocHttpError
1394 62 PandocShouldNeverHappenError
1395 63 PandocSomeError
1396 64 PandocParseError
1397 65 PandocParsecError
1398 66 PandocMakePDFError
1399 67 PandocSyntaxMapError
1400 83 PandocFilterError
1401 84 PandocLuaError
1402 91 PandocMacroLoop
1403 92 PandocUTF8DecodingError
1404 93 PandocIpynbDecodingError
1405 94 PandocUnsupportedCharsetError
1406 97 PandocCouldNotFindDataFileError
1407 98 PandocCouldNotFindMetadataFileError
1408 99 PandocResourceNotFound
1409
1411 The --defaults option may be used to specify a package of options, in
1412 the form of a YAML file.
1413 Fields that are omitted will just have their regular default values.
1415 So a defaults file can be as simple as one line:
1416 verbosity: INFO
1418 In fields that expect a file path (or list of file paths), the follow‐
1420 ing syntax may be used to interpolate environment variables:
1421 csl: ${HOME}/mycsldir/special.csl
1423 ${USERDATA} may also be used; this will always resolve to the user data
1425 directory that is current when the defaults file is parsed, regardless
1426 of the setting of the environment variable USERDATA.
1427 ${.} will resolve to the directory containing the defaults file itself.
1429 This allows you to refer to resources contained in that directory:
1430 epub-cover-image: ${.}/cover.jpg
1432 epub-metadata: ${.}/meta.xml
1433 resource-path:
1434 - . # the working directory from which pandoc is run
1435 - ${.}/images # the images subdirectory of the directory
1436 # containing this defaults file
1437 This environment variable interpolation syntax only works in fields
1439 that expect file paths.
1440 Defaults files can be placed in the defaults subdirectory of the user
1442 data directory and used from any directory. For example, one could
1443 create a file specifying defaults for writing letters, save it as let‐
1444 ter.yaml in the defaults subdirectory of the user data directory, and
1445 then invoke these defaults from any directory using pandoc --defaults
1446 letter or pandoc -dletter.
1447 When multiple defaults are used, their contents will be combined.
1449 Note that, where command-line arguments may be repeated (--metadata-
1451 file, --css, --include-in-header, --include-before-body, --include-af‐
1452 ter-body, --variable, --metadata, --syntax-definition), the values
1453 specified on the command line will combine with values specified in the
1454 defaults file, rather than replacing them.
1455 The following tables show the mapping between the command line and de‐
1457 faults file entries.
1458 command line defaults file
1460 --------------------------------- ----------------------------------
1461 foo.md input-file: foo.md
1462 foo.md bar.md input-files:
1464 - foo.md
1465 - bar.md
1466 The value of input-files may be left empty to indicate input from
1469 stdin, and it can be an empty sequence [] for no input.
1470 General options
1472 command line defaults file
1473 --------------------------------- ----------------------------------
1474 --from markdown+emoji from: markdown+emoji
1475 reader: markdown+emoji
1477 to: markdown+hard_line_breaks
1479 --to markdown+hard_line_breaks
1480 writer: markdown+hard_line_breaks
1482 --output foo.pdf output-file: foo.pdf
1484 --output - output-file:
1486 --data-dir dir data-dir: dir
1488 --defaults file defaults:
1490 - file
1491 --verbose verbosity: INFO
1493 --quiet verbosity: ERROR
1495 --fail-if-warnings fail-if-warnings: true
1497 --sandbox sandbox: true
1499 --log=FILE log-file: FILE
1501 Options specified in a defaults file itself always have priority over
1504 those in another file included with a defaults: entry.
1505 verbosity can have the values ERROR, WARNING, or INFO.
1507 Reader options
1509 command line defaults file
1510 --------------------------------- ----------------------------------
1511 --shift-heading-level-by -1 shift-heading-level-by: -1
1512 indented-code-classes:
1514 --indented-code-classes python - python
1515 --default-image-extension ".jpg" default-image-extension: '.jpg'
1518 --file-scope file-scope: true
1520 --filter pandoc-citeproc \ filters:
1522 - pandoc-citeproc
1523 --lua-filter count-words.lua \ - count-words.lua
1524 --filter special.lua - type: json
1525 path: special.lua
1526 --metadata key=value \ metadata:
1528 --metadata key2 key: value
1529 key2: true
1530 --metadata-file meta.yaml metadata-files:
1532 - meta.yaml
1533 metadata-file: meta.yaml
1535 --preserve-tabs preserve-tabs: true
1537 --tab-stop 8 tab-stop: 8
1539 --track-changes accept track-changes: accept
1541 --extract-media dir extract-media: dir
1543 --abbreviations abbrevs.txt abbreviations: abbrevs.txt
1545 --trace trace: true
1547 Metadata values specified in a defaults file are parsed as literal
1550 string text, not Markdown.
1551 Filters will be assumed to be Lua filters if they have the .lua exten‐
1553 sion, and JSON filters otherwise. But the filter type can also be
1554 specified explicitly, as shown. Filters are run in the order speci‐
1555 fied. To include the built-in citeproc filter, use either citeproc or
1556 {type: citeproc}.
1557 General writer options
1559 command line defaults file
1560 --------------------------------- ----------------------------------
1561 --standalone standalone: true
1562 --template letter template: letter
1564 --variable key=val \ variables:
1566 --variable key2 key: val
1567 key2: true
1568 --eol nl eol: nl
1570 --dpi 300 dpi: 300
1572 --wrap 60 wrap: 60
1574 --columns 72 columns: 72
1576 --table-of-contents table-of-contents: true
1578 --toc toc: true
1580 --toc-depth 3 toc-depth: 3
1582 --strip-comments strip-comments: true
1584 --no-highlight highlight-style: null
1586 --highlight-style kate highlight-style: kate
1588 syntax-definitions:
1590 --syntax-definition mylang.xml - mylang.xml
1591 syntax-definition: mylang.xml
1593 --include-in-header inc.tex include-in-header:
1595 - inc.tex
1596 include-before-body:
1598--include-before-body inc.tex - inc.tex
1599 --include-after-body inc.tex include-after-body:
1601 - inc.tex
1602 --resource-path .:foo resource-path: ['.','foo']
1604 --request-header foo:bar request-headers:
1606 - ["User-Agent", "Mozilla/5.0"]
1608 --no-check-certificate no-check-certificate: true
1610 Options affecting specific writers
1613 command line defaults file
1614 --------------------------------- ----------------------------------
1615 --self-contained self-contained: true
1616 --html-q-tags html-q-tags: true
1618 --ascii ascii: true
1620 --reference-links reference-links: true
1622 --reference-location block reference-location: block
1624 --markdown-headings atx markdown-headings: atx
1626 --top-level-division chapter top-level-division: chapter
1628 --number-sections number-sections: true
1630 --number-offset=1,4 number-offset: \[1,4\]
1632 --listings listings: true
1634 --incremental incremental: true
1636 --slide-level 2 slide-level: 2
1638 --section-divs section-divs: true
1640 email-obfuscation: references
1642 --email-obfuscation references
1643 --id-prefix ch1 identifier-prefix: ch1
1645 --title-prefix MySite title-prefix: MySite
1647 --css styles/screen.css \ css:
1649 --css styles/special.css - styles/screen.css
1650 - styles/special.css
1651 --reference-doc my.docx reference-doc: my.docx
1653 --epub-cover-image cover.jpg epub-cover-image: cover.jpg
1655 --epub-metadata meta.xml epub-metadata: meta.xml
1657 epub-fonts:
1659 --epub-embed-font special.otf \ - special.otf
1660 - headline.otf
1661 --epub-embed-font headline.otf
1662 --epub-chapter-level 2 epub-chapter-level: 2
1664 --epub-subdirectory="" epub-subdirectory: ''
1666 --ipynb-output best ipynb-output: best
1668 --pdf-engine xelatex pdf-engine: xelatex
1670 pdf-engine-opts:
1672 --pdf-engine-opt=--shell-escape - '-shell-escape'
1673 pdf-engine-opt: '-shell-escape'
1676 Citation rendering
1679 command line defaults file
1680 --------------------------------- ----------------------------------
1681 --citeproc citeproc: true
1682 --bibliography logic.bib metadata:
1684 bibliography: logic.bib
1685 --csl ieee.csl metadata:
1687 csl: ieee.csl
1688 metadata:
1690 --citation-abbreviations ab.json
1691 citation-abbreviations: ab.json
1692 --natbib cite-method: natbib
1694 --biblatex cite-method: biblatex
1696 cite-method can be citeproc, natbib, or biblatex. This only affects
1699 LaTeX output. If you want to use citeproc to format citations, you
1700 should also set `citeproc: true'.
1701 If you need control over when the citeproc processing is done relative
1703 to other filters, you should instead use citeproc in the list of fil‐
1704 ters (see above).
1705 Math rendering in HTML
1707 command line defaults file
1708 --------------------------------- ----------------------------------
1709 --mathjax html-math-method:
1710 method: mathjax
1711 --mathml html-math-method:
1713 method: mathml
1714 --webtex html-math-method:
1716 method: webtex
1717 --katex html-math-method:
1719 method: katex
1720 --gladtex html-math-method:
1722 method: gladtex
1723 In addition to the values listed above, method can have the value
1726 plain.
1727 If the command line option accepts a URL argument, an url: field can be
1729 added to html-math-method:.
1730 Options for wrapper scripts
1732 command line defaults file
1733 --------------------------------- ----------------------------------
1734 --dump-args dump-args: true
1735 --ignore-args ignore-args: true
1737
1740 When the -s/--standalone option is used, pandoc uses a template to add
1741 header and footer material that is needed for a self-standing document.
1742 To see the default template that is used, just type
1743 pandoc -D *FORMAT*
1745 where FORMAT is the name of the output format. A custom template can
1747 be specified using the --template option. You can also override the
1748 system default templates for a given output format FORMAT by putting a
1749 file templates/default.*FORMAT* in the user data directory (see --data-
1750 dir, above). Exceptions:
1751 • For odt output, customize the default.opendocument template.
1753 • For pdf output, customize the default.latex template (or the de‐
1755 fault.context template, if you use -t context, or the default.ms tem‐
1756 plate, if you use -t ms, or the default.html template, if you use -t
1757 html).
1758 • docx and pptx have no template (however, you can use --reference-doc
1760 to customize the output).
1761 Templates contain variables, which allow for the inclusion of arbitrary
1763 information at any point in the file. They may be set at the command
1764 line using the -V/--variable option. If a variable is not set, pandoc
1765 will look for the key in the document’s metadata, which can be set us‐
1766 ing either YAML metadata blocks or with the -M/--metadata option. In
1767 addition, some variables are given default values by pandoc. See Vari‐
1768 ables below for a list of variables used in pandoc’s default templates.
1769 If you use custom templates, you may need to revise them as pandoc
1771 changes. We recommend tracking the changes in the default templates,
1772 and modifying your custom templates accordingly. An easy way to do
1773 this is to fork the pandoc-templates repository and merge in changes
1774 after each pandoc release.
1775 Template syntax
1777 Comments
1778 Anything between the sequence $-- and the end of the line will be
1779 treated as a comment and omitted from the output.
1780 Delimiters
1782 To mark variables and control structures in the template, either $...$
1783 or ${...} may be used as delimiters. The styles may also be mixed in
1784 the same template, but the opening and closing delimiter must match in
1785 each case. The opening delimiter may be followed by one or more spaces
1786 or tabs, which will be ignored. The closing delimiter may be followed
1787 by one or more spaces or tabs, which will be ignored.
1788 To include a literal $ in the document, use $$.
1790 Interpolated variables
1792 A slot for an interpolated variable is a variable name surrounded by
1793 matched delimiters. Variable names must begin with a letter and can
1794 contain letters, numbers, _, -, and .. The keywords it, if, else, en‐
1795 dif, for, sep, and endfor may not be used as variable names. Examples:
1796 $foo$
1798 $foo.bar.baz$
1799 $foo_bar.baz-bim$
1800 $ foo $
1801 ${foo}
1802 ${foo.bar.baz}
1803 ${foo_bar.baz-bim}
1804 ${ foo }
1805 Variable names with periods are used to get at structured variable val‐
1807 ues. So, for example, employee.salary will return the value of the
1808 salary field of the object that is the value of the employee field.
1809 • If the value of the variable is a simple value, it will be rendered
1811 verbatim. (Note that no escaping is done; the assumption is that the
1812 calling program will escape the strings appropriately for the output
1813 format.)
1814 • If the value is a list, the values will be concatenated.
1816 • If the value is a map, the string true will be rendered.
1818 • Every other value will be rendered as the empty string.
1820 Conditionals
1822 A conditional begins with if(variable) (enclosed in matched delimiters)
1823 and ends with endif (enclosed in matched delimiters). It may optional‐
1824 ly contain an else (enclosed in matched delimiters). The if section is
1825 used if variable has a non-empty value, otherwise the else section is
1826 used (if present). Examples:
1827 $if(foo)$bar$endif$
1829 $if(foo)$
1831 $foo$
1832 $endif$
1833 $if(foo)$
1835 part one
1836 $else$
1837 part two
1838 $endif$
1839 ${if(foo)}bar${endif}
1841 ${if(foo)}
1843 ${foo}
1844 ${endif}
1845 ${if(foo)}
1847 ${ foo.bar }
1848 ${else}
1849 no foo!
1850 ${endif}
1851 The keyword elseif may be used to simplify complex nested conditionals:
1853 $if(foo)$
1855 XXX
1856 $elseif(bar)$
1857 YYY
1858 $else$
1859 ZZZ
1860 $endif$
1861 For loops
1863 A for loop begins with for(variable) (enclosed in matched delimiters)
1864 and ends with endfor (enclosed in matched delimiters).
1865 • If variable is an array, the material inside the loop will be evalu‐
1867 ated repeatedly, with variable being set to each value of the array
1868 in turn, and concatenated.
1869 • If variable is a map, the material inside will be set to the map.
1871 • If the value of the associated variable is not an array or a map, a
1873 single iteration will be performed on its value.
1874 Examples:
1876 $for(foo)$$foo$$sep$, $endfor$
1878 $for(foo)$
1880 - $foo.last$, $foo.first$
1881 $endfor$
1882 ${ for(foo.bar) }
1884 - ${ foo.bar.last }, ${ foo.bar.first }
1885 ${ endfor }
1886 $for(mymap)$
1888 $it.name$: $it.office$
1889 $endfor$
1890 You may optionally specify a separator between consecutive values using
1892 sep (enclosed in matched delimiters). The material between sep and the
1893 endfor is the separator.
1894 ${ for(foo) }${ foo }${ sep }, ${ endfor }
1896 Instead of using variable inside the loop, the special anaphoric key‐
1898 word it may be used.
1899 ${ for(foo.bar) }
1901 - ${ it.last }, ${ it.first }
1902 ${ endfor }
1903 Partials
1905 Partials (subtemplates stored in different files) may be included by
1906 using the name of the partial, followed by (), for example:
1907 ${ styles() }
1909 Partials will be sought in the directory containing the main template.
1911 The file name will be assumed to have the same extension as the main
1912 template if it lacks an extension. When calling the partial, the full
1913 name including file extension can also be used:
1914 ${ styles.html() }
1916 (If a partial is not found in the directory of the template and the
1918 template path is given as a relative path, it will also be sought in
1919 the templates subdirectory of the user data directory.)
1920 Partials may optionally be applied to variables using a colon:
1922 ${ date:fancy() }
1924 ${ articles:bibentry() }
1926 If articles is an array, this will iterate over its values, applying
1928 the partial bibentry() to each one. So the second example above is
1929 equivalent to
1930 ${ for(articles) }
1932 ${ it:bibentry() }
1933 ${ endfor }
1934 Note that the anaphoric keyword it must be used when iterating over
1936 partials. In the above examples, the bibentry partial should contain
1937 it.title (and so on) instead of articles.title.
1938 Final newlines are omitted from included partials.
1940 Partials may include other partials.
1942 A separator between values of an array may be specified in square
1944 brackets, immediately after the variable name or partial:
1945 ${months[, ]}$
1947 ${articles:bibentry()[; ]$
1949 The separator in this case is literal and (unlike with sep in an ex‐
1951 plicit for loop) cannot contain interpolated variables or other tem‐
1952 plate directives.
1953 Nesting
1955 To ensure that content is “nested,” that is, subsequent lines indented,
1956 use the ^ directive:
1957 $item.number$ $^$$item.description$ ($item.price$)
1959 In this example, if item.description has multiple lines, they will all
1961 be indented to line up with the first line:
1962 00123 A fine bottle of 18-year old
1964 Oban whiskey. ($148)
1965 To nest multiple lines to the same level, align them with the ^ direc‐
1967 tive in the template. For example:
1968 $item.number$ $^$$item.description$ ($item.price$)
1970 (Available til $item.sellby$.)
1971 will produce
1973 00123 A fine bottle of 18-year old
1975 Oban whiskey. ($148)
1976 (Available til March 30, 2020.)
1977 If a variable occurs by itself on a line, preceded by whitespace and
1979 not followed by further text or directives on the same line, and the
1980 variable’s value contains multiple lines, it will be nested automati‐
1981 cally.
1982 Breakable spaces
1984 Normally, spaces in the template itself (as opposed to values of the
1985 interpolated variables) are not breakable, but they can be made break‐
1986 able in part of the template by using the ~ keyword (ended with another
1987 ~).
1988 $~$This long line may break if the document is rendered
1990 with a short line length.$~$
1991 Pipes
1993 A pipe transforms the value of a variable or partial. Pipes are speci‐
1994 fied using a slash (/) between the variable name (or partial) and the
1995 pipe name. Example:
1996 $for(name)$
1998 $name/uppercase$
1999 $endfor$
2000 $for(metadata/pairs)$
2002 - $it.key$: $it.value$
2003 $endfor$
2004 $employee:name()/uppercase$
2006 Pipes may be chained:
2008 $for(employees/pairs)$
2010 $it.key/alpha/uppercase$. $it.name$
2011 $endfor$
2012 Some pipes take parameters:
2014 |----------------------|------------|
2016 $for(employee)$
2017 $it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
2018 $endfor$
2019 |----------------------|------------|
2020 Currently the following pipes are predefined:
2022 • pairs: Converts a map or array to an array of maps, each with key and
2024 value fields. If the original value was an array, the key will be
2025 the array index, starting with 1.
2026 • uppercase: Converts text to uppercase.
2028 • lowercase: Converts text to lowercase.
2030 • length: Returns the length of the value: number of characters for a
2032 textual value, number of elements for a map or array.
2033 • reverse: Reverses a textual value or array, and has no effect on oth‐
2035 er values.
2036 • first: Returns the first value of an array, if applied to a non-empty
2038 array; otherwise returns the original value.
2039 • last: Returns the last value of an array, if applied to a non-empty
2041 array; otherwise returns the original value.
2042 • rest: Returns all but the first value of an array, if applied to a
2044 non-empty array; otherwise returns the original value.
2045 • allbutlast: Returns all but the last value of an array, if applied to
2047 a non-empty array; otherwise returns the original value.
2048 • chomp: Removes trailing newlines (and breakable space).
2050 • nowrap: Disables line wrapping on breakable spaces.
2052 • alpha: Converts textual values that can be read as an integer into
2054 lowercase alphabetic characters a..z (mod 26). This can be used to
2055 get lettered enumeration from array indices. To get uppercase let‐
2056 ters, chain with uppercase.
2057 • roman: Converts textual values that can be read as an integer into
2059 lowercase roman numerals. This can be used to get lettered enumera‐
2060 tion from array indices. To get uppercase roman, chain with upper‐
2061 case.
2062 • left n "leftborder" "rightborder": Renders a textual value in a block
2064 of width n, aligned to the left, with an optional left and right bor‐
2065 der. Has no effect on other values. This can be used to align mate‐
2066 rial in tables. Widths are positive integers indicating the number
2067 of characters. Borders are strings inside double quotes; literal "
2068 and \ characters must be backslash-escaped.
2069 • right n "leftborder" "rightborder": Renders a textual value in a
2071 block of width n, aligned to the right, and has no effect on other
2072 values.
2073 • center n "leftborder" "rightborder": Renders a textual value in a
2075 block of width n, aligned to the center, and has no effect on other
2076 values.
2077 Variables
2079 Metadata variables
2080 title, author, date
2081 allow identification of basic aspects of the document. Included
2082 in PDF metadata through LaTeX and ConTeXt. These can be set
2083 through a pandoc title block, which allows for multiple authors,
2084 or through a YAML metadata block:
2085 ---
2087 author:
2088 - Aristotle
2089 - Peter Abelard
2090 ...
2091 Note that if you just want to set PDF or HTML metadata, without
2093 including a title block in the document itself, you can set the
2094 title-meta, author-meta, and date-meta variables. (By default
2095 these are set automatically, based on title, author, and date.)
2096 The page title in HTML is set by pagetitle, which is equal to
2097 title by default.
2098 subtitle
2100 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
2101 docx documents
2102 abstract
2104 document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc,
2105 and docx documents
2106 abstract-title
2108 title of abstract, currently used only in HTML and EPUB. This
2109 will be set automatically to a localized value, depending on
2110 lang, but can be manually overridden.
2111 keywords
2113 list of keywords to be included in HTML, PDF, ODT, pptx, docx
2114 and AsciiDoc metadata; repeat as for author, above
2115 subject
2117 document subject, included in ODT, PDF, docx, EPUB, and pptx
2118 metadata
2119 description
2121 document description, included in ODT, docx and pptx metadata.
2122 Some applications show this as Comments metadata.
2123 category
2125 document category, included in docx and pptx metadata
2126 Additionally, any root-level string metadata, not included in ODT, docx
2128 or pptx metadata is added as a custom property. The following YAML
2129 metadata block for instance:
2130 ---
2132 title: 'This is the title'
2133 subtitle: "This is the subtitle"
2134 author:
2135 - Author One
2136 - Author Two
2137 description: |
2138 This is a long
2139 description.
2140 It consists of two paragraphs
2142 ...
2143 will include title, author and description as standard document proper‐
2145 ties and subtitle as a custom property when converting to docx, ODT or
2146 pptx.
2147 Language variables
2149 lang identifies the main language of the document using IETF language
2150 tags (following the BCP 47 standard), such as en or en-GB. The
2151 Language subtag lookup tool can look up or verify these tags.
2152 This affects most formats, and controls hyphenation in PDF out‐
2153 put when using LaTeX (through babel and polyglossia) or ConTeXt.
2154 Use native pandoc Divs and Spans with the lang attribute to
2156 switch the language:
2157 ---
2159 lang: en-GB
2160 ...
2161 Text in the main document language (British English).
2163 ::: {lang=fr-CA}
2165 > Cette citation est écrite en français canadien.
2166 :::
2167 More text in English. ['Zitat auf Deutsch.']{lang=de}
2169 dir the base script direction, either rtl (right-to-left) or ltr
2171 (left-to-right).
2172 For bidirectional documents, native pandoc spans and divs with
2174 the dir attribute (value rtl or ltr) can be used to override the
2175 base direction in some output formats. This may not always be
2176 necessary if the final renderer (e.g. the browser, when generat‐
2177 ing HTML) supports the Unicode Bidirectional Algorithm.
2178 When using LaTeX for bidirectional documents, only the xelatex
2180 engine is fully supported (use --pdf-engine=xelatex).
2181 Variables for HTML
2183 document-css
2184 Enables inclusion of most of the CSS in the styles.html partial
2185 (have a look with pandoc --print-default-data-file=tem‐
2186 plates/styles.html). Unless you use --css, this variable is set
2187 to true by default. You can disable it with e.g. pandoc -M doc‐
2188 ument-css=false.
2189 mainfont
2191 sets the CSS font-family property on the html element.
2192 fontsize
2194 sets the base CSS font-size, which you’d usually set to
2195 e.g. 20px, but it also accepts pt (12pt = 16px in most
2196 browsers).
2197 fontcolor
2199 sets the CSS color property on the html element.
2200 linkcolor
2202 sets the CSS color property on all links.
2203 monofont
2205 sets the CSS font-family property on code elements.
2206 monobackgroundcolor
2208 sets the CSS background-color property on code elements and adds
2209 extra padding.
2210 linestretch
2212 sets the CSS line-height property on the html element, which is
2213 preferred to be unitless.
2214 backgroundcolor
2216 sets the CSS background-color property on the html element.
2217 margin-left, margin-right, margin-top, margin-bottom
2219 sets the corresponding CSS padding properties on the body ele‐
2220 ment.
2221 To override or extend some CSS for just one document, include for exam‐
2223 ple:
2224 ---
2226 header-includes: |
2227 <style>
2228 blockquote {
2229 font-style: italic;
2230 }
2231 tr.even {
2232 background-color: #f0f0f0;
2233 }
2234 td, th {
2235 padding: 0.5em 2em 0.5em 0.5em;
2236 }
2237 tbody {
2238 border-bottom: none;
2239 }
2240 </style>
2241 ---
2242 Variables for HTML math
2244 classoption
2245 when using KaTeX, you can render display math equations flush
2246 left using YAML metadata or with -M classoption=fleqn.
2247 Variables for HTML slides
2249 These affect HTML output when producing slide shows with pandoc.
2250 institute
2252 author affiliations: can be a list when there are multiple au‐
2253 thors
2254 revealjs-url
2256 base URL for reveal.js documents (defaults to
2257 https://unpkg.com/reveal.js@^4/)
2258 s5-url base URL for S5 documents (defaults to s5/default)
2260 slidy-url
2262 base URL for Slidy documents (defaults to
2263 https://www.w3.org/Talks/Tools/Slidy2)
2264 slideous-url
2266 base URL for Slideous documents (defaults to slideous)
2267 title-slide-attributes
2269 additional attributes for the title slide of reveal.js slide
2270 shows. See background in reveal.js, beamer, and pptx for an ex‐
2271 ample.
2272 All reveal.js configuration options are available as variables. To
2274 turn off boolean flags that default to true in reveal.js, use 0.
2275 Variables for Beamer slides
2277 These variables change the appearance of PDF slides using beamer.
2278 aspectratio
2280 slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for
2281 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)
2282 beameroption
2284 add extra beamer option with \setbeameroption{}
2285 institute
2287 author affiliations: can be a list when there are multiple au‐
2288 thors
2289 logo logo image for slides
2291 navigation
2293 controls navigation symbols (default is empty for no navigation
2294 symbols; other valid values are frame, vertical, and horizontal)
2295 section-titles
2297 enables “title pages” for new sections (default is true)
2298 theme, colortheme, fonttheme, innertheme, outertheme
2300 beamer themes
2301 themeoptions
2303 options for LaTeX beamer themes (a list).
2304 titlegraphic
2306 image for title slide
2307 Variables for PowerPoint
2309 These variables control the visual aspects of a slide show that are not
2310 easily controlled via templates.
2311 monofont
2313 font to use for code.
2314 Variables for LaTeX
2316 Pandoc uses these variables when creating a PDF with a LaTeX engine.
2317 Layout
2319 block-headings
2320 make \paragraph and \subparagraph (fourth- and fifth-level head‐
2321 ings, or fifth- and sixth-level with book classes) free-standing
2322 rather than run-in; requires further formatting to distinguish
2323 from \subsubsection (third- or fourth-level headings). Instead
2324 of using this option, KOMA-Script can adjust headings more ex‐
2325 tensively:
2326 ---
2328 documentclass: scrartcl
2329 header-includes: |
2330 \RedeclareSectionCommand[
2331 beforeskip=-10pt plus -2pt minus -1pt,
2332 afterskip=1sp plus -1sp minus 1sp,
2333 font=\normalfont\itshape]{paragraph}
2334 \RedeclareSectionCommand[
2335 beforeskip=-10pt plus -2pt minus -1pt,
2336 afterskip=1sp plus -1sp minus 1sp,
2337 font=\normalfont\scshape,
2338 indent=0pt]{subparagraph}
2339 ...
2340 classoption
2342 option for document class, e.g. oneside; repeat for multiple op‐
2343 tions:
2344 ---
2346 classoption:
2347 - twocolumn
2348 - landscape
2349 ...
2350 documentclass
2352 document class: usually one of the standard classes, article,
2353 book, and report; the KOMA-Script equivalents, scrartcl, scr‐
2354 book, and scrreprt, which default to smaller margins; or memoir
2355 geometry
2357 option for geometry package, e.g. margin=1in; repeat for multi‐
2358 ple options:
2359 ---
2361 geometry:
2362 - top=30mm
2363 - left=20mm
2364 - heightrounded
2365 ...
2366 hyperrefoptions
2368 option for hyperref package, e.g. linktoc=all; repeat for multi‐
2369 ple options:
2370 ---
2372 hyperrefoptions:
2373 - linktoc=all
2374 - pdfwindowui
2375 - pdfpagemode=FullScreen
2376 ...
2377 indent if true, pandoc will use document class settings for indentation
2379 (the default LaTeX template otherwise removes indentation and
2380 adds space between paragraphs)
2381 linestretch
2383 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
2384 margin-left, margin-right, margin-top, margin-bottom
2386 sets margins if geometry is not used (otherwise geometry over‐
2387 rides these)
2388 pagestyle
2390 control \pagestyle{}: the default article class supports plain
2391 (default), empty (no running heads or page numbers), and head‐
2392 ings (section titles in running heads)
2393 papersize
2395 paper size, e.g. letter, a4
2396 secnumdepth
2398 numbering depth for sections (with --number-sections option or
2399 numbersections variable)
2400 beamerarticle
2402 produce an article from Beamer slides
2403 Fonts
2405 fontenc
2406 allows font encoding to be specified through fontenc package
2407 (with pdflatex); default is T1 (see LaTeX font encodings guide)
2408 fontfamily
2410 font package for use with pdflatex: TeX Live includes many op‐
2411 tions, documented in the LaTeX Font Catalogue. The default is
2412 Latin Modern.
2413 fontfamilyoptions
2415 options for package used as fontfamily; repeat for multiple op‐
2416 tions. For example, to use the Libertine font with proportional
2417 lowercase (old-style) figures through the libertinus package:
2418 ---
2420 fontfamily: libertinus
2421 fontfamilyoptions:
2422 - osf
2423 - p
2424 ...
2425 fontsize
2427 font size for body text. The standard classes allow 10pt, 11pt,
2428 and 12pt. To use another size, set documentclass to one of the
2429 KOMA-Script classes, such as scrartcl or scrbook.
2430 mainfont, sansfont, monofont, mathfont, CJKmainfont
2432 font families for use with xelatex or lualatex: take the name of
2433 any system font, using the fontspec package. CJKmainfont uses
2434 the xecjk package.
2435 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions,
2437 CJKoptions
2438 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
2439 mainfont in xelatex and lualatex. Allow for any choices avail‐
2440 able through fontspec; repeat for multiple options. For exam‐
2441 ple, to use the TeX Gyre version of Palatino with lowercase fig‐
2442 ures:
2443 ---
2445 mainfont: TeX Gyre Pagella
2446 mainfontoptions:
2447 - Numbers=Lowercase
2448 - Numbers=Proportional
2449 ...
2450 microtypeoptions
2452 options to pass to the microtype package
2453 Links
2455 colorlinks
2456 add color to link text; automatically enabled if any of linkcol‐
2457 or, filecolor, citecolor, urlcolor, or toccolor are set
2458 boxlinks
2460 add visible box around links (has no effect if colorlinks is
2461 set)
2462 linkcolor, filecolor, citecolor, urlcolor, toccolor
2464 color for internal links, external links, citation links, linked
2465 URLs, and links in table of contents, respectively: uses options
2466 allowed by xcolor, including the dvipsnames, svgnames, and
2467 x11names lists
2468 links-as-notes
2470 causes links to be printed as footnotes
2471 Front matter
2473 lof, lot
2474 include list of figures, list of tables
2475 thanks contents of acknowledgments footnote after document title
2477 toc include table of contents (can also be set using --toc/--table-
2479 of-contents)
2480 toc-depth
2482 level of section to include in table of contents
2483 BibLaTeX Bibliographies
2485 These variables function when using BibLaTeX for citation rendering.
2486 biblatexoptions
2488 list of options for biblatex
2489 biblio-style
2491 bibliography style, when used with --natbib and --biblatex
2492 biblio-title
2494 bibliography title, when used with --natbib and --biblatex
2495 bibliography
2497 bibliography to use for resolving references
2498 natbiboptions
2500 list of options for natbib
2501 Variables for ConTeXt
2503 Pandoc uses these variables when creating a PDF with ConTeXt.
2504 fontsize
2506 font size for body text (e.g. 10pt, 12pt)
2507 headertext, footertext
2509 text to be placed in running header or footer (see ConTeXt Head‐
2510 ers and Footers); repeat up to four times for different place‐
2511 ment
2512 indenting
2514 controls indentation of paragraphs, e.g. yes,small,next (see
2515 ConTeXt Indentation); repeat for multiple options
2516 interlinespace
2518 adjusts line spacing, e.g. 4ex (using setupinterlinespace); re‐
2519 peat for multiple options
2520 layout options for page margins and text arrangement (see ConTeXt Lay‐
2522 out); repeat for multiple options
2523 linkcolor, contrastcolor
2525 color for links outside and inside a page, e.g. red, blue (see
2526 ConTeXt Color)
2527 linkstyle
2529 typeface style for links, e.g. normal, bold, slanted, boldslant‐
2530 ed, type, cap, small
2531 lof, lot
2533 include list of figures, list of tables
2534 mainfont, sansfont, monofont, mathfont
2536 font families: take the name of any system font (see ConTeXt
2537 Font Switching)
2538 margin-left, margin-right, margin-top, margin-bottom
2540 sets margins, if layout is not used (otherwise layout overrides
2541 these)
2542 pagenumbering
2544 page number style and location (using setuppagenumbering); re‐
2545 peat for multiple options
2546 papersize
2548 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
2549 up); repeat for multiple options
2550 pdfa adds to the preamble the setup necessary to generate PDF/A of
2552 the type specified, e.g. 1a:2005, 2a. If no type is specified
2553 (i.e. the value is set to True, by e.g. --metadata=pdfa or
2554 pdfa: true in a YAML metadata block), 1b:2005 will be used as
2555 default, for reasons of backwards compatibility. Using --vari‐
2556 able=pdfa without specified value is not supported. To success‐
2557 fully generate PDF/A the required ICC color profiles have to be
2558 available and the content and all included files (such as im‐
2559 ages) have to be standard-conforming. The ICC profiles and out‐
2560 put intent may be specified using the variables pdfaiccprofile
2561 and pdfaintent. See also ConTeXt PDFA for more details.
2562 pdfaiccprofile
2564 when used in conjunction with pdfa, specifies the ICC profile to
2565 use in the PDF, e.g. default.cmyk. If left unspecified,
2566 sRGB.icc is used as default. May be repeated to include multi‐
2567 ple profiles. Note that the profiles have to be available on
2568 the system. They can be obtained from ConTeXt ICC Profiles.
2569 pdfaintent
2571 when used in conjunction with pdfa, specifies the output intent
2572 for the colors, e.g. ISO coated v2 300\letterpercent\space (ECI)
2573 If left unspecified, sRGB IEC61966-2.1 is used as default.
2574 toc include table of contents (can also be set using --toc/--table-
2576 of-contents)
2577 whitespace
2579 spacing between paragraphs, e.g. none, small (using setupwhites‐
2580 pace)
2581 includesource
2583 include all source documents as file attachments in the PDF file
2584 Variables for wkhtmltopdf
2586 Pandoc uses these variables when creating a PDF with wkhtmltopdf. The
2587 --css option also affects the output.
2588 footer-html, header-html
2590 add information to the header and footer
2591 margin-left, margin-right, margin-top, margin-bottom
2593 set the page margins
2594 papersize
2596 sets the PDF paper size
2597 Variables for man pages
2599 adjusting
2600 adjusts text to left (l), right (r), center (c), or both (b)
2601 margins
2602 footer footer in man pages
2604 header header in man pages
2606 hyphenate
2608 if true (the default), hyphenation will be used
2609 section
2611 section number in man pages
2612 Variables for ms
2614 fontfamily
2615 font family (e.g. T or P)
2616 indent paragraph indent (e.g. 2m)
2618 lineheight
2620 line height (e.g. 12p)
2621 pointsize
2623 point size (e.g. 10p)
2624 Variables set automatically
2626 Pandoc sets these variables automatically in response to options or
2627 document contents; users can also modify them. These vary depending on
2628 the output format, and include the following:
2629 body body of document
2631 date-meta
2633 the date variable converted to ISO 8601 YYYY-MM-DD, included in
2634 all HTML based formats (dzslides, epub, html, html4, html5, re‐
2635 vealjs, s5, slideous, slidy). The recognized formats for date
2636 are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy
2637 (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy
2638 (e.g. Apr. 02, 2018 or April 02,
2639 2018),yyyy[mm[dd]](e.g.20180402, 201804 or 2018).
2640 header-includes
2642 contents specified by -H/--include-in-header (may have multiple
2643 values)
2644 include-before
2646 contents specified by -B/--include-before-body (may have multi‐
2647 ple values)
2648 include-after
2650 contents specified by -A/--include-after-body (may have multiple
2651 values)
2652 meta-json
2654 JSON representation of all of the document’s metadata. Field
2655 values are transformed to the selected output format.
2656 numbersections
2658 non-null value if -N/--number-sections was specified
2659 sourcefile, outputfile
2661 source and destination filenames, as given on the command line.
2662 sourcefile can also be a list if input comes from multiple
2663 files, or empty if input is from stdin. You can use the follow‐
2664 ing snippet in your template to distinguish them:
2665 $if(sourcefile)$
2667 $for(sourcefile)$
2668 $sourcefile$
2669 $endfor$
2670 $else$
2671 (stdin)
2672 $endif$
2673 Similarly, outputfile can be - if output goes to the terminal.
2675 If you need absolute paths, use e.g. $curdir$/$sourcefile$.
2677 curdir working directory from which pandoc is run.
2679 toc non-null value if --toc/--table-of-contents was specified
2681 toc-title
2683 title of table of contents (works only with EPUB, HTML, re‐
2684 vealjs, opendocument, odt, docx, pptx, beamer, LaTeX)
2685
2687 The behavior of some of the readers and writers can be adjusted by en‐
2688 abling or disabling various extensions.
2689 An extension can be enabled by adding +EXTENSION to the format name and
2691 disabled by adding -EXTENSION. For example, --from mark‐
2692 down_strict+footnotes is strict Markdown with footnotes enabled, while
2693 --from markdown-footnotes-pipe_tables is pandoc’s Markdown without
2694 footnotes or pipe tables.
2695 The markdown reader and writer make by far the most use of extensions.
2697 Extensions only used by them are therefore covered in the section Pan‐
2698 doc’s Markdown below (see Markdown variants for commonmark and gfm).
2699 In the following, extensions that also work for other formats are cov‐
2700 ered.
2701 Note that markdown extensions added to the ipynb format affect Markdown
2703 cells in Jupyter notebooks (as do command-line options like --atx-head‐
2704 ers).
2705 Typography
2707 Extension: smart
2708 Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-
2709 dashes, and ... as ellipses. Nonbreaking spaces are inserted after
2710 certain abbreviations, such as “Mr.”
2711 This extension can be enabled/disabled for the following formats:
2713 input formats
2715 markdown, commonmark, latex, mediawiki, org, rst, twiki, html
2716 output formats
2718 markdown, latex, context, rst
2719 enabled by default in
2721 markdown, latex, context (both input and output)
2722 Note: If you are writing Markdown, then the smart extension has the re‐
2724 verse effect: what would have been curly quotes comes out straight.
2725 In LaTeX, smart means to use the standard TeX ligatures for quotation
2727 marks (`` and '' for double quotes, ` and ' for single quotes) and
2728 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
2729 then in reading LaTeX pandoc will parse these characters literally. In
2730 writing LaTeX, enabling smart tells pandoc to use the ligatures when
2731 possible; if smart is disabled pandoc will use unicode quotation mark
2732 and dash characters.
2733 Headings and sections
2735 Extension: auto_identifiers
2736 A heading without an explicitly specified identifier will be automati‐
2737 cally assigned a unique identifier based on the heading text.
2738 This extension can be enabled/disabled for the following formats:
2740 input formats
2742 markdown, latex, rst, mediawiki, textile
2743 output formats
2745 markdown, muse
2746 enabled by default in
2748 markdown, muse
2749 The default algorithm used to derive the identifier from the heading
2751 text is:
2752 • Remove all formatting, links, etc.
2754 • Remove all footnotes.
2756 • Remove all non-alphanumeric characters, except underscores, hyphens,
2758 and periods.
2759 • Replace all spaces and newlines with hyphens.
2761 • Convert all alphabetic characters to lowercase.
2763 • Remove everything up to the first letter (identifiers may not begin
2765 with a number or punctuation mark).
2766 • If nothing is left after this, use the identifier section.
2768 Thus, for example,
2770 Heading Identifier
2772 ----------------------------- -----------------------------
2773 Heading identifiers in HTML heading-identifiers-in-html
2774 Maître d'hôtel maître-dhôtel
2775 *Dogs*?--in *my* house? dogs--in-my-house
2776 [HTML], [S5], or [RTF]? html-s5-or-rtf
2777 3. Applications applications
2778 33 section
2779 These rules should, in most cases, allow one to determine the identifi‐
2781 er from the heading text. The exception is when several headings have
2782 the same text; in this case, the first will get an identifier as de‐
2783 scribed above; the second will get the same identifier with -1 append‐
2784 ed; the third with -2; and so on.
2785 (However, a different algorithm is used if gfm_auto_identifiers is en‐
2787 abled; see below.)
2788 These identifiers are used to provide link targets in the table of con‐
2790 tents generated by the --toc|--table-of-contents option. They also
2791 make it easy to provide links from one section of a document to anoth‐
2792 er. A link to this section, for example, might look like this:
2793 See the section on
2795 [heading identifiers](#heading-identifiers-in-html-latex-and-context).
2796 Note, however, that this method of providing links to sections works
2798 only in HTML, LaTeX, and ConTeXt formats.
2799 If the --section-divs option is specified, then each section will be
2801 wrapped in a section (or a div, if html4 was specified), and the iden‐
2802 tifier will be attached to the enclosing <section> (or <div>) tag
2803 rather than the heading itself. This allows entire sections to be ma‐
2804 nipulated using JavaScript or treated differently in CSS.
2805 Extension: ascii_identifiers
2807 Causes the identifiers produced by auto_identifiers to be pure ASCII.
2808 Accents are stripped off of accented Latin letters, and non-Latin let‐
2809 ters are omitted.
2810 Extension: gfm_auto_identifiers
2812 Changes the algorithm used by auto_identifiers to conform to GitHub’s
2813 method. Spaces are converted to dashes (-), uppercase characters to
2814 lowercase characters, and punctuation characters other than - and _ are
2815 removed. Emojis are replaced by their names.
2816 Math Input
2818 The extensions tex_math_dollars, tex_math_single_backslash, and
2819 tex_math_double_backslash are described in the section about Pandoc’s
2820 Markdown.
2821 However, they can also be used with HTML input. This is handy for
2823 reading web pages formatted using MathJax, for example.
2824 Raw HTML/TeX
2826 The following extensions are described in more detail in their respec‐
2827 tive sections of Pandoc’s Markdown:
2828 • raw_html allows HTML elements which are not representable in pandoc’s
2830 AST to be parsed as raw HTML. By default, this is disabled for HTML
2831 input.
2832 • raw_tex allows raw LaTeX, TeX, and ConTeXt to be included in a docu‐
2834 ment. This extension can be enabled/disabled for the following for‐
2835 mats (in addition to markdown):
2836 input formats
2838 latex, textile, html (environments, \ref, and \eqref only),
2839 ipynb
2840 output formats
2842 textile, commonmark
2843 Note: as applied to ipynb, raw_html and raw_tex affect not only raw
2845 TeX in markdown cells, but data with mime type text/html in output
2846 cells. Since the ipynb reader attempts to preserve the richest pos‐
2847 sible outputs when several options are given, you will get best re‐
2848 sults if you disable raw_html and raw_tex when converting to formats
2849 like docx which don’t allow raw html or tex.
2850 • native_divs causes HTML div elements to be parsed as native pandoc
2852 Div blocks. If you want them to be parsed as raw HTML, use -f html-
2853 native_divs+raw_html.
2854 • native_spans causes HTML span elements to be parsed as native pandoc
2856 Span inlines. If you want them to be parsed as raw HTML, use -f
2857 html-native_spans+raw_html. If you want to drop all divs and spans
2858 when converting HTML to Markdown, you can use pandoc -f html-na‐
2859 tive_divs-native_spans -t markdown.
2860 Literate Haskell support
2862 Extension: literate_haskell
2863 Treat the document as literate Haskell source.
2864 This extension can be enabled/disabled for the following formats:
2866 input formats
2868 markdown, rst, latex
2869 output formats
2871 markdown, rst, latex, html
2872 If you append +lhs (or +literate_haskell) to one of the formats above,
2874 pandoc will treat the document as literate Haskell source. This means
2875 that
2876 • In Markdown input, “bird track” sections will be parsed as Haskell
2878 code rather than block quotations. Text between \begin{code} and
2879 \end{code} will also be treated as Haskell code. For ATX-style head‐
2880 ings the character `=' will be used instead of `#'.
2881 • In Markdown output, code blocks with classes haskell and literate
2883 will be rendered using bird tracks, and block quotations will be in‐
2884 dented one space, so they will not be treated as Haskell code. In
2885 addition, headings will be rendered setext-style (with underlines)
2886 rather than ATX-style (with `#' characters). (This is because ghc
2887 treats `#' characters in column 1 as introducing line numbers.)
2888 • In restructured text input, “bird track” sections will be parsed as
2890 Haskell code.
2891 • In restructured text output, code blocks with class haskell will be
2893 rendered using bird tracks.
2894 • In LaTeX input, text in code environments will be parsed as Haskell
2896 code.
2897 • In LaTeX output, code blocks with class haskell will be rendered in‐
2899 side code environments.
2900 • In HTML output, code blocks with class haskell will be rendered with
2902 class literatehaskell and bird tracks.
2903 Examples:
2905 pandoc -f markdown+lhs -t html
2907 reads literate Haskell source formatted with Markdown conventions and
2909 writes ordinary HTML (without bird tracks).
2910 pandoc -f markdown+lhs -t html+lhs
2912 writes HTML with the Haskell code in bird tracks, so it can be copied
2914 and pasted as literate Haskell source.
2915 Note that GHC expects the bird tracks in the first column, so indented
2917 literate code blocks (e.g. inside an itemized environment) will not be
2918 picked up by the Haskell compiler.
2919 Other extensions
2921 Extension: empty_paragraphs
2922 Allows empty paragraphs. By default empty paragraphs are omitted.
2923 This extension can be enabled/disabled for the following formats:
2925 input formats
2927 docx, html
2928 output formats
2930 docx, odt, opendocument, html
2931 Extension: native_numbering
2933 Enables native numbering of figures and tables. Enumeration starts at
2934 1.
2935 This extension can be enabled/disabled for the following formats:
2937 output formats
2939 odt, opendocument, docx
2940 Extension: xrefs_name
2942 Links to headings, figures and tables inside the document are substi‐
2943 tuted with cross-references that will use the name or caption of the
2944 referenced item. The original link text is replaced once the generated
2945 document is refreshed. This extension can be combined with xrefs_num‐
2946 ber in which case numbers will appear before the name.
2947 Text in cross-references is only made consistent with the referenced
2949 item once the document has been refreshed.
2950 This extension can be enabled/disabled for the following formats:
2952 output formats
2954 odt, opendocument
2955 Extension: xrefs_number
2957 Links to headings, figures and tables inside the document are substi‐
2958 tuted with cross-references that will use the number of the referenced
2959 item. The original link text is discarded. This extension can be com‐
2960 bined with xrefs_name in which case the name or caption numbers will
2961 appear after the number.
2962 For the xrefs_number to be useful heading numbers must be enabled in
2964 the generated document, also table and figure captions must be enabled
2965 using for example the native_numbering extension.
2966 Numbers in cross-references are only visible in the final document once
2968 it has been refreshed.
2969 This extension can be enabled/disabled for the following formats:
2971 output formats
2973 odt, opendocument
2974 Extension: styles
2976 When converting from docx, read all docx styles as divs (for paragraph
2977 styles) and spans (for character styles) regardless of whether pandoc
2978 understands the meaning of these styles. This can be used with docx
2979 custom styles. Disabled by default.
2980 input formats
2982 docx
2983 Extension: amuse
2985 In the muse input format, this enables Text::Amuse extensions to Emacs
2986 Muse markup.
2987 Extension: raw_markdown
2989 In the ipynb input format, this causes Markdown cells to be included as
2990 raw Markdown blocks (allowing lossless round-tripping) rather than be‐
2991 ing parsed. Use this only when you are targeting ipynb or a markdown-
2992 based output format.
2993 Extension: citations
2995 When the citations extension is enabled in org, org-cite and org-ref
2996 style citations will be parsed as native pandoc citations.
2997 When citations is enabled in docx, citations inserted by Zotero or
2999 Mendeley or EndNote plugins will be parsed as native pandoc citations.
3000 (Otherwise, the formatted citations generated by the bibliographic
3001 software will be parsed as regular text.)
3002 Extension: fancy_lists
3004 Some aspects of Pandoc’s Markdown fancy lists are also accepted in org
3005 input, mimicking the option org-list-allow-alphabetical in Emacs. As
3006 in Org Mode, enabling this extension allows lowercase and uppercase al‐
3007 phabetical markers for ordered lists to be parsed in addition to arabic
3008 ones. Note that for Org, this does not include roman numerals or the #
3009 placeholder that are enabled by the extension in Pandoc’s Markdown.
3010 Extension: element_citations
3012 In the jats output formats, this causes reference items to be replaced
3013 with <element-citation> elements. These elements are not influenced by
3014 CSL styles, but all information on the item is included in tags.
3015 Extension: ntb
3017 In the context output format this enables the use of Natural Tables
3018 (TABLE) instead of the default Extreme Tables (xtables). Natural ta‐
3019 bles allow more fine-grained global customization but come at a perfor‐
3020 mance penalty compared to extreme tables.
3021
3023 Pandoc understands an extended and slightly revised version of John
3024 Gruber’s Markdown syntax. This document explains the syntax, noting
3025 differences from original Markdown. Except where noted, these differ‐
3026 ences can be suppressed by using the markdown_strict format instead of
3027 markdown. Extensions can be enabled or disabled to specify the behav‐
3028 ior more granularly. They are described in the following. See also
3029 Extensions above, for extensions that work also on other formats.
3030 Philosophy
3032 Markdown is designed to be easy to write, and, even more importantly,
3033 easy to read:
3034 A Markdown-formatted document should be publishable as-is, as
3036 plain text, without looking like it’s been marked up with tags
3037 or formatting instructions. – John Gruber
3038 This principle has guided pandoc’s decisions in finding syntax for ta‐
3040 bles, footnotes, and other extensions.
3041 There is, however, one respect in which pandoc’s aims are different
3043 from the original aims of Markdown. Whereas Markdown was originally
3044 designed with HTML generation in mind, pandoc is designed for multiple
3045 output formats. Thus, while pandoc allows the embedding of raw HTML,
3046 it discourages it, and provides other, non-HTMLish ways of representing
3047 important document elements like definition lists, tables, mathematics,
3048 and footnotes.
3049 Paragraphs
3051 A paragraph is one or more lines of text followed by one or more blank
3052 lines. Newlines are treated as spaces, so you can reflow your para‐
3053 graphs as you like. If you need a hard line break, put two or more
3054 spaces at the end of a line.
3055 Extension: escaped_line_breaks
3057 A backslash followed by a newline is also a hard line break. Note: in
3058 multiline and grid table cells, this is the only way to create a hard
3059 line break, since trailing spaces in the cells are ignored.
3060 Headings
3062 There are two kinds of headings: Setext and ATX.
3063 Setext-style headings
3065 A setext-style heading is a line of text “underlined” with a row of =
3066 signs (for a level-one heading) or - signs (for a level-two heading):
3067 A level-one heading
3069 ===================
3070 A level-two heading
3072 -------------------
3073 The heading text can contain inline formatting, such as emphasis (see
3075 Inline formatting, below).
3076 ATX-style headings
3078 An ATX-style heading consists of one to six # signs and a line of text,
3079 optionally followed by any number of # signs. The number of # signs at
3080 the beginning of the line is the heading level:
3081 ## A level-two heading
3083 ### A level-three heading ###
3085 As with setext-style headings, the heading text can contain formatting:
3087 # A level-one heading with a [link](/url) and *emphasis*
3089 Extension: blank_before_header
3091 Original Markdown syntax does not require a blank line before a head‐
3092 ing. Pandoc does require this (except, of course, at the beginning of
3093 the document). The reason for the requirement is that it is all too
3094 easy for a # to end up at the beginning of a line by accident (perhaps
3095 through line wrapping). Consider, for example:
3096 I like several of their flavors of ice cream:
3098 #22, for example, and #5.
3099 Extension: space_in_atx_header
3101 Many Markdown implementations do not require a space between the open‐
3102 ing #s of an ATX heading and the heading text, so that #5 bolt and
3103 #hashtag count as headings. With this extension, pandoc does require
3104 the space.
3105 Heading identifiers
3107 See also the auto_identifiers extension above.
3108 Extension: header_attributes
3110 Headings can be assigned attributes using this syntax at the end of the
3111 line containing the heading text:
3112 {#identifier .class .class key=value key=value}
3114 Thus, for example, the following headings will all be assigned the
3116 identifier foo:
3117 # My heading {#foo}
3119 ## My heading ## {#foo}
3121 My other heading {#foo}
3123 ---------------
3124 (This syntax is compatible with PHP Markdown Extra.)
3126 Note that although this syntax allows assignment of classes and
3128 key/value attributes, writers generally don’t use all of this informa‐
3129 tion. Identifiers, classes, and key/value attributes are used in HTML
3130 and HTML-based formats such as EPUB and slidy. Identifiers are used
3131 for labels and link anchors in the LaTeX, ConTeXt, Textile, Jira
3132 markup, and AsciiDoc writers.
3133 Headings with the class unnumbered will not be numbered, even if --num‐
3135 ber-sections is specified. A single hyphen (-) in an attribute context
3136 is equivalent to .unnumbered, and preferable in non-English documents.
3137 So,
3138 # My heading {-}
3140 is just the same as
3142 # My heading {.unnumbered}
3144 If the unlisted class is present in addition to unnumbered, the heading
3146 will not be included in a table of contents. (Currently this feature
3147 is only implemented for certain formats: those based on LaTeX and HTML,
3148 PowerPoint, and RTF.)
3149 Extension: implicit_header_references
3151 Pandoc behaves as if reference links have been defined for each head‐
3152 ing. So, to link to a heading
3153 # Heading identifiers in HTML
3155 you can simply write
3157 [Heading identifiers in HTML]
3159 or
3161 [Heading identifiers in HTML][]
3163 or
3165 [the section on heading identifiers][heading identifiers in
3167 HTML]
3168 instead of giving the identifier explicitly:
3170 [Heading identifiers in HTML](#heading-identifiers-in-html)
3172 If there are multiple headings with identical text, the corresponding
3174 reference will link to the first one only, and you will need to use ex‐
3175 plicit links to link to the others, as described above.
3176 Like regular reference links, these references are case-insensitive.
3178 Explicit link reference definitions always take priority over implicit
3180 heading references. So, in the following example, the link will point
3181 to bar, not to #foo:
3182 # Foo
3184 [foo]: bar
3186 See [foo]
3188 Block quotations
3190 Markdown uses email conventions for quoting blocks of text. A block
3191 quotation is one or more paragraphs or other block elements (such as
3192 lists or headings), with each line preceded by a > character and an op‐
3193 tional space. (The > need not start at the left margin, but it should
3194 not be indented more than three spaces.)
3195 > This is a block quote. This
3197 > paragraph has two lines.
3198 >
3199 > 1. This is a list inside a block quote.
3200 > 2. Second item.
3201 A “lazy” form, which requires the > character only on the first line of
3203 each block, is also allowed:
3204 > This is a block quote. This
3206 paragraph has two lines.
3207 > 1. This is a list inside a block quote.
3209 2. Second item.
3210 Among the block elements that can be contained in a block quote are
3212 other block quotes. That is, block quotes can be nested:
3213 > This is a block quote.
3215 >
3216 > > A block quote within a block quote.
3217 If the > character is followed by an optional space, that space will be
3219 considered part of the block quote marker and not part of the indenta‐
3220 tion of the contents. Thus, to put an indented code block in a block
3221 quote, you need five spaces after the >:
3222 > code
3224 Extension: blank_before_blockquote
3226 Original Markdown syntax does not require a blank line before a block
3227 quote. Pandoc does require this (except, of course, at the beginning
3228 of the document). The reason for the requirement is that it is all too
3229 easy for a > to end up at the beginning of a line by accident (perhaps
3230 through line wrapping). So, unless the markdown_strict format is used,
3231 the following does not produce a nested block quote in pandoc:
3232 > This is a block quote.
3234 >> Nested.
3235 Verbatim (code) blocks
3237 Indented code blocks
3238 A block of text indented four spaces (or one tab) is treated as verba‐
3239 tim text: that is, special characters do not trigger special format‐
3240 ting, and all spaces and line breaks are preserved. For example,
3241 if (a > 3) {
3243 moveShip(5 * gravity, DOWN);
3244 }
3245 The initial (four space or one tab) indentation is not considered part
3247 of the verbatim text, and is removed in the output.
3248 Note: blank lines in the verbatim text need not begin with four spaces.
3250 Fenced code blocks
3252 Extension: fenced_code_blocks
3253 In addition to standard indented code blocks, pandoc supports fenced
3254 code blocks. These begin with a row of three or more tildes (~) and
3255 end with a row of tildes that must be at least as long as the starting
3256 row. Everything between these lines is treated as code. No indenta‐
3257 tion is necessary:
3258 ~~~~~~~
3260 if (a > 3) {
3261 moveShip(5 * gravity, DOWN);
3262 }
3263 ~~~~~~~
3264 Like regular code blocks, fenced code blocks must be separated from
3266 surrounding text by blank lines.
3267 If the code itself contains a row of tildes or backticks, just use a
3269 longer row of tildes or backticks at the start and end:
3270 ~~~~~~~~~~~~~~~~
3272 ~~~~~~~~~~
3273 code including tildes
3274 ~~~~~~~~~~
3275 ~~~~~~~~~~~~~~~~
3276 Extension: backtick_code_blocks
3278 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
3279 (~).
3280 Extension: fenced_code_attributes
3282 Optionally, you may attach attributes to fenced or backtick code block
3283 using this syntax:
3284 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
3286 qsort [] = []
3287 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3288 qsort (filter (>= x) xs)
3289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3290 Here mycode is an identifier, haskell and numberLines are classes, and
3292 startFrom is an attribute with value 100. Some output formats can use
3293 this information to do syntax highlighting. Currently, the only output
3294 formats that use this information are HTML, LaTeX, Docx, Ms, and Power‐
3295 Point. If highlighting is supported for your output format and lan‐
3296 guage, then the code block above will appear highlighted, with numbered
3297 lines. (To see which languages are supported, type pandoc --list-high‐
3298 light-languages.) Otherwise, the code block above will appear as fol‐
3299 lows:
3300 <pre id="mycode" class="haskell numberLines" startFrom="100">
3302 <code>
3303 ...
3304 </code>
3305 </pre>
3306 The numberLines (or number-lines) class will cause the lines of the
3308 code block to be numbered, starting with 1 or the value of the start‐
3309 From attribute. The lineAnchors (or line-anchors) class will cause the
3310 lines to be clickable anchors in HTML output.
3311 A shortcut form can also be used for specifying the language of the
3313 code block:
3314 ```haskell
3316 qsort [] = []
3317 ```
3318 This is equivalent to:
3320 ``` {.haskell}
3322 qsort [] = []
3323 ```
3324 If the fenced_code_attributes extension is disabled, but input contains
3326 class attribute(s) for the code block, the first class attribute will
3327 be printed after the opening fence as a bare word.
3328 To prevent all highlighting, use the --no-highlight flag. To set the
3330 highlighting style, use --highlight-style. For more information on
3331 highlighting, see Syntax highlighting, below.
3332 Line blocks
3334 Extension: line_blocks
3335 A line block is a sequence of lines beginning with a vertical bar (|)
3336 followed by a space. The division into lines will be preserved in the
3337 output, as will any leading spaces; otherwise, the lines will be for‐
3338 matted as Markdown. This is useful for verse and addresses:
3339 | The limerick packs laughs anatomical
3341 | In space that is quite economical.
3342 | But the good ones I've seen
3343 | So seldom are clean
3344 | And the clean ones so seldom are comical
3345 | 200 Main St.
3347 | Berkeley, CA 94718
3348 The lines can be hard-wrapped if needed, but the continuation line must
3350 begin with a space.
3351 | The Right Honorable Most Venerable and Righteous Samuel L.
3353 Constable, Jr.
3354 | 200 Main St.
3355 | Berkeley, CA 94718
3356 Inline formatting (such as emphasis) is allowed in the content, but not
3358 block-level formatting (such as block quotes or lists).
3359 This syntax is borrowed from reStructuredText.
3361 Lists
3363 Bullet lists
3364 A bullet list is a list of bulleted list items. A bulleted list item
3365 begins with a bullet (*, +, or -). Here is a simple example:
3366 * one
3368 * two
3369 * three
3370 This will produce a “compact” list. If you want a “loose” list, in
3372 which each item is formatted as a paragraph, put spaces between the
3373 items:
3374 * one
3376 * two
3378 * three
3380 The bullets need not be flush with the left margin; they may be indent‐
3382 ed one, two, or three spaces. The bullet must be followed by white‐
3383 space.
3384 List items look best if subsequent lines are flush with the first line
3386 (after the bullet):
3387 * here is my first
3389 list item.
3390 * and my second.
3391 But Markdown also allows a “lazy” format:
3393 * here is my first
3395 list item.
3396 * and my second.
3397 Block content in list items
3399 A list item may contain multiple paragraphs and other block-level con‐
3400 tent. However, subsequent paragraphs must be preceded by a blank line
3401 and indented to line up with the first non-space content after the list
3402 marker.
3403 * First paragraph.
3405 Continued.
3407 * Second paragraph. With a code block, which must be indented
3409 eight spaces:
3410 { code }
3412 Exception: if the list marker is followed by an indented code block,
3414 which must begin 5 spaces after the list marker, then subsequent para‐
3415 graphs must begin two columns after the last character of the list
3416 marker:
3417 * code
3419 continuation paragraph
3421 List items may include other lists. In this case the preceding blank
3423 line is optional. The nested list must be indented to line up with the
3424 first non-space character after the list marker of the containing list
3425 item.
3426 * fruits
3428 + apples
3429 - macintosh
3430 - red delicious
3431 + pears
3432 + peaches
3433 * vegetables
3434 + broccoli
3435 + chard
3436 As noted above, Markdown allows you to write list items “lazily,” in‐
3438 stead of indenting continuation lines. However, if there are multiple
3439 paragraphs or other blocks in a list item, the first line of each must
3440 be indented.
3441 + A lazy, lazy, list
3443 item.
3444 + Another one; this looks
3446 bad but is legal.
3447 Second paragraph of second
3449 list item.
3450 Ordered lists
3452 Ordered lists work just like bulleted lists, except that the items be‐
3453 gin with enumerators rather than bullets.
3454 In original Markdown, enumerators are decimal numbers followed by a pe‐
3456 riod and a space. The numbers themselves are ignored, so there is no
3457 difference between this list:
3458 1. one
3460 2. two
3461 3. three
3462 and this one:
3464 5. one
3466 7. two
3467 1. three
3468 Extension: fancy_lists
3470 Unlike original Markdown, pandoc allows ordered list items to be marked
3471 with uppercase and lowercase letters and roman numerals, in addition to
3472 Arabic numerals. List markers may be enclosed in parentheses or fol‐
3473 lowed by a single right-parenthesis or period. They must be separated
3474 from the text that follows by at least one space, and, if the list
3475 marker is a capital letter with a period, by at least two spaces.
3476 The fancy_lists extension also allows `#' to be used as an ordered list
3478 marker in place of a numeral:
3479 #. one
3481 #. two
3482 Extension: startnum
3484 Pandoc also pays attention to the type of list marker used, and to the
3485 starting number, and both of these are preserved where possible in the
3486 output format. Thus, the following yields a list with numbers followed
3487 by a single parenthesis, starting with 9, and a sublist with lowercase
3488 roman numerals:
3489 9) Ninth
3491 10) Tenth
3492 11) Eleventh
3493 i. subone
3494 ii. subtwo
3495 iii. subthree
3496 Pandoc will start a new list each time a different type of list marker
3498 is used. So, the following will create three lists:
3499 (2) Two
3501 (5) Three
3502 1. Four
3503 * Five
3504 If default list markers are desired, use #.:
3506 #. one
3508 #. two
3509 #. three
3510 Extension: task_lists
3512 Pandoc supports task lists, using the syntax of GitHub-Flavored Mark‐
3513 down.
3514 - [ ] an unchecked task list item
3516 - [x] checked item
3517 Definition lists
3519 Extension: definition_lists
3520 Pandoc supports definition lists, using the syntax of PHP Markdown Ex‐
3521 tra with some extensions.
3522 Term 1
3524 : Definition 1
3526 Term 2 with *inline markup*
3528 : Definition 2
3530 { some code, part of Definition 2 }
3532 Third paragraph of definition 2.
3534 Each term must fit on one line, which may optionally be followed by a
3536 blank line, and must be followed by one or more definitions. A defini‐
3537 tion begins with a colon or tilde, which may be indented one or two
3538 spaces.
3539 A term may have multiple definitions, and each definition may consist
3541 of one or more block elements (paragraph, code block, list, etc.), each
3542 indented four spaces or one tab stop. The body of the definition (not
3543 including the first line) should be indented four spaces. However, as
3544 with other Markdown lists, you can “lazily” omit indentation except at
3545 the beginning of a paragraph or other block element:
3546 Term 1
3548 : Definition
3550 with lazy continuation.
3551 Second paragraph of the definition.
3553 If you leave space before the definition (as in the example above), the
3555 text of the definition will be treated as a paragraph. In some output
3556 formats, this will mean greater spacing between term/definition pairs.
3557 For a more compact definition list, omit the space before the defini‐
3558 tion:
3559 Term 1
3561 ~ Definition 1
3562 Term 2
3564 ~ Definition 2a
3565 ~ Definition 2b
3566 Note that space between items in a definition list is required. (A
3568 variant that loosens this requirement, but disallows “lazy” hard wrap‐
3569 ping, can be activated with compact_definition_lists: see Non-default
3570 extensions, below.)
3571 Numbered example lists
3573 Extension: example_lists
3574 The special list marker @ can be used for sequentially numbered exam‐
3575 ples. The first list item with a @ marker will be numbered `1', the
3576 next `2', and so on, throughout the document. The numbered examples
3577 need not occur in a single list; each new list using @ will take up
3578 where the last stopped. So, for example:
3579 (@) My first example will be numbered (1).
3581 (@) My second example will be numbered (2).
3582 Explanation of examples.
3584 (@) My third example will be numbered (3).
3586 Numbered examples can be labeled and referred to elsewhere in the docu‐
3588 ment:
3589 (@good) This is a good example.
3591 As (@good) illustrates, ...
3593 The label can be any string of alphanumeric characters, underscores, or
3595 hyphens.
3596 Note: continuation paragraphs in example lists must always be indented
3598 four spaces, regardless of the length of the list marker. That is, ex‐
3599 ample lists always behave as if the four_space_rule extension is set.
3600 This is because example labels tend to be long, and indenting content
3601 to the first non-space character after the label would be awkward.
3602 Ending a list
3604 What if you want to put an indented code block after a list?
3605 - item one
3607 - item two
3608 { my code block }
3610 Trouble! Here pandoc (like other Markdown implementations) will treat
3612 { my code block } as the second paragraph of item two, and not as a
3613 code block.
3614 To “cut off” the list after item two, you can insert some non-indented
3616 content, like an HTML comment, which won’t produce visible output in
3617 any format:
3618 - item one
3620 - item two
3621 <!-- end of list -->
3623 { my code block }
3625 You can use the same trick if you want two consecutive lists instead of
3627 one big list:
3628 1. one
3630 2. two
3631 3. three
3632 <!-- -->
3634 1. uno
3636 2. dos
3637 3. tres
3638 Horizontal rules
3640 A line containing a row of three or more *, -, or _ characters (option‐
3641 ally separated by spaces) produces a horizontal rule:
3642 * * * *
3644 ---------------
3646 We strongly recommend that horizontal rules be separated from surround‐
3648 ing text by blank lines. If a horizontal rule is not followed by a
3649 blank line, pandoc may try to interpret the lines that follow as a YAML
3650 metadata block or a table.
3651 Tables
3653 Four kinds of tables may be used. The first three kinds presuppose the
3654 use of a fixed-width font, such as Courier. The fourth kind can be
3655 used with proportionally spaced fonts, as it does not require lining up
3656 columns.
3657 Extension: table_captions
3659 A caption may optionally be provided with all 4 kinds of tables (as il‐
3660 lustrated in the examples below). A caption is a paragraph beginning
3661 with the string Table: (or just :), which will be stripped off. It may
3662 appear either before or after the table.
3663 Extension: simple_tables
3665 Simple tables look like this:
3666 Right Left Center Default
3668 ------- ------ ---------- -------
3669 12 12 12 12
3670 123 123 123 123
3671 1 1 1 1
3672 Table: Demonstration of simple table syntax.
3674 The header and table rows must each fit on one line. Column alignments
3676 are determined by the position of the header text relative to the
3677 dashed line below it:
3678 • If the dashed line is flush with the header text on the right side
3680 but extends beyond it on the left, the column is right-aligned.
3681 • If the dashed line is flush with the header text on the left side but
3683 extends beyond it on the right, the column is left-aligned.
3684 • If the dashed line extends beyond the header text on both sides, the
3686 column is centered.
3687 • If the dashed line is flush with the header text on both sides, the
3689 default alignment is used (in most cases, this will be left).
3690 The table must end with a blank line, or a line of dashes followed by a
3692 blank line.
3693 The column header row may be omitted, provided a dashed line is used to
3695 end the table. For example:
3696 ------- ------ ---------- -------
3698 12 12 12 12
3699 123 123 123 123
3700 1 1 1 1
3701 ------- ------ ---------- -------
3702 When the header row is omitted, column alignments are determined on the
3704 basis of the first line of the table body. So, in the tables above,
3705 the columns would be right, left, center, and right aligned, respec‐
3706 tively.
3707 Extension: multiline_tables
3709 Multiline tables allow header and table rows to span multiple lines of
3710 text (but cells that span multiple columns or rows of the table are not
3711 supported). Here is an example:
3712 -------------------------------------------------------------
3714 Centered Default Right Left
3715 Header Aligned Aligned Aligned
3716 ----------- ------- --------------- -------------------------
3717 First row 12.0 Example of a row that
3718 spans multiple lines.
3719 Second row 5.0 Here's another one. Note
3721 the blank line between
3722 rows.
3723 -------------------------------------------------------------
3724 Table: Here's the caption. It, too, may span
3726 multiple lines.
3727 These work like simple tables, but with the following differences:
3729 • They must begin with a row of dashes, before the header text (unless
3731 the header row is omitted).
3732 • They must end with a row of dashes, then a blank line.
3734 • The rows must be separated by blank lines.
3736 In multiline tables, the table parser pays attention to the widths of
3738 the columns, and the writers try to reproduce these relative widths in
3739 the output. So, if you find that one of the columns is too narrow in
3740 the output, try widening it in the Markdown source.
3741 The header may be omitted in multiline tables as well as simple tables:
3743 ----------- ------- --------------- -------------------------
3745 First row 12.0 Example of a row that
3746 spans multiple lines.
3747 Second row 5.0 Here's another one. Note
3749 the blank line between
3750 rows.
3751 ----------- ------- --------------- -------------------------
3752 : Here's a multiline table without a header.
3754 It is possible for a multiline table to have just one row, but the row
3756 should be followed by a blank line (and then the row of dashes that
3757 ends the table), or the table may be interpreted as a simple table.
3758 Extension: grid_tables
3760 Grid tables look like this:
3761 : Sample grid table.
3763 +---------------+---------------+--------------------+
3765 | Fruit | Price | Advantages |
3766 +===============+===============+====================+
3767 | Bananas | $1.34 | - built-in wrapper |
3768 | | | - bright color |
3769 +---------------+---------------+--------------------+
3770 | Oranges | $2.10 | - cures scurvy |
3771 | | | - tasty |
3772 +---------------+---------------+--------------------+
3773 The row of =s separates the header from the table body, and can be
3775 omitted for a headerless table. The cells of grid tables may contain
3776 arbitrary block elements (multiple paragraphs, code blocks, lists,
3777 etc.). Cells that span multiple columns or rows are not supported.
3778 Grid tables can be created easily using Emacs’ table-mode (M-x table-
3779 insert).
3780 Alignments can be specified as with pipe tables, by putting colons at
3782 the boundaries of the separator line after the header:
3783 +---------------+---------------+--------------------+
3785 | Right | Left | Centered |
3786 +==============:+:==============+:==================:+
3787 | Bananas | $1.34 | built-in wrapper |
3788 +---------------+---------------+--------------------+
3789 For headerless tables, the colons go on the top line instead:
3791 +--------------:+:--------------+:------------------:+
3793 | Right | Left | Centered |
3794 +---------------+---------------+--------------------+
3795 Grid Table Limitations
3797 Pandoc does not support grid tables with row spans or column spans.
3798 This means that neither variable numbers of columns across rows nor
3799 variable numbers of rows across columns are supported by Pandoc. All
3800 grid tables must have the same number of columns in each row, and the
3801 same number of rows in each column. For example, the Docutils sample
3802 grid tables will not render as expected with Pandoc.
3803 Extension: pipe_tables
3805 Pipe tables look like this:
3806 | Right | Left | Default | Center |
3808 |------:|:-----|---------|:------:|
3809 | 12 | 12 | 12 | 12 |
3810 | 123 | 123 | 123 | 123 |
3811 | 1 | 1 | 1 | 1 |
3812 : Demonstration of pipe table syntax.
3814 The syntax is identical to PHP Markdown Extra tables. The beginning
3816 and ending pipe characters are optional, but pipes are required between
3817 all columns. The colons indicate column alignment as shown. The head‐
3818 er cannot be omitted. To simulate a headerless table, include a header
3819 with blank cells.
3820 Since the pipes indicate column boundaries, columns need not be verti‐
3822 cally aligned, as they are in the above example. So, this is a per‐
3823 fectly legal (though ugly) pipe table:
3824 fruit| price
3826 -----|-----:
3827 apple|2.05
3828 pear|1.37
3829 orange|3.09
3830 The cells of pipe tables cannot contain block elements like paragraphs
3832 and lists, and cannot span multiple lines. If any line of the markdown
3833 source is longer than the column width (see --columns), then the table
3834 will take up the full text width and the cell contents will wrap, with
3835 the relative cell widths determined by the number of dashes in the line
3836 separating the table header from the table body. (For example ---|-
3837 would make the first column 3/4 and the second column 1/4 of the full
3838 text width.) On the other hand, if no lines are wider than column
3839 width, then cell contents will not be wrapped, and the cells will be
3840 sized to their contents.
3841 Note: pandoc also recognizes pipe tables of the following form, as can
3843 be produced by Emacs’ orgtbl-mode:
3844 | One | Two |
3846 |-----+-------|
3847 | my | table |
3848 | is | nice |
3849 The difference is that + is used instead of |. Other orgtbl features
3851 are not supported. In particular, to get non-default column alignment,
3852 you’ll need to add colons as above.
3853 Metadata blocks
3855 Extension: pandoc_title_block
3856 If the file begins with a title block
3857 % title
3859 % author(s) (separated by semicolons)
3860 % date
3861 it will be parsed as bibliographic information, not regular text. (It
3863 will be used, for example, in the title of standalone LaTeX or HTML
3864 output.) The block may contain just a title, a title and an author, or
3865 all three elements. If you want to include an author but no title, or
3866 a title and a date but no author, you need a blank line:
3867 %
3869 % Author
3870 % My title
3872 %
3873 % June 15, 2006
3874 The title may occupy multiple lines, but continuation lines must begin
3876 with leading space, thus:
3877 % My title
3879 on multiple lines
3880 If a document has multiple authors, the authors may be put on separate
3882 lines with leading space, or separated by semicolons, or both. So, all
3883 of the following are equivalent:
3884 % Author One
3886 Author Two
3887 % Author One; Author Two
3889 % Author One;
3891 Author Two
3892 The date must fit on one line.
3894 All three metadata fields may contain standard inline formatting (ital‐
3896 ics, links, footnotes, etc.).
3897 Title blocks will always be parsed, but they will affect the output on‐
3899 ly when the --standalone (-s) option is chosen. In HTML output, titles
3900 will appear twice: once in the document head – this is the title that
3901 will appear at the top of the window in a browser – and once at the be‐
3902 ginning of the document body. The title in the document head can have
3903 an optional prefix attached (--title-prefix or -T option). The title
3904 in the body appears as an H1 element with class “title”, so it can be
3905 suppressed or reformatted with CSS. If a title prefix is specified
3906 with -T and no title block appears in the document, the title prefix
3907 will be used by itself as the HTML title.
3908 The man page writer extracts a title, man page section number, and oth‐
3910 er header and footer information from the title line. The title is as‐
3911 sumed to be the first word on the title line, which may optionally end
3912 with a (single-digit) section number in parentheses. (There should be
3913 no space between the title and the parentheses.) Anything after this
3914 is assumed to be additional footer and header text. A single pipe
3915 character (|) should be used to separate the footer text from the head‐
3916 er text. Thus,
3917 % PANDOC(1)
3919 will yield a man page with the title PANDOC and section 1.
3921 % PANDOC(1) Pandoc User Manuals
3923 will also have “Pandoc User Manuals” in the footer.
3925 % PANDOC(1) Pandoc User Manuals | Version 4.0
3927 will also have “Version 4.0” in the header.
3929 Extension: yaml_metadata_block
3931 A YAML metadata block is a valid YAML object, delimited by a line of
3932 three hyphens (---) at the top and a line of three hyphens (---) or
3933 three dots (...) at the bottom. The initial line --- must not be fol‐
3934 lowed by a blank line. A YAML metadata block may occur anywhere in the
3935 document, but if it is not at the beginning, it must be preceded by a
3936 blank line.
3937 Note that, because of the way pandoc concatenates input files when sev‐
3939 eral are provided, you may also keep the metadata in a separate YAML
3940 file and pass it to pandoc as an argument, along with your Markdown
3941 files:
3942 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
3944 Just be sure that the YAML file begins with --- and ends with --- or
3946 .... Alternatively, you can use the --metadata-file option. Using
3947 that approach however, you cannot reference content (like footnotes)
3948 from the main markdown input document.
3949 Metadata will be taken from the fields of the YAML object and added to
3951 any existing document metadata. Metadata can contain lists and objects
3952 (nested arbitrarily), but all string scalars will be interpreted as
3953 Markdown. Fields with names ending in an underscore will be ignored by
3954 pandoc. (They may be given a role by external processors.) Field
3955 names must not be interpretable as YAML numbers or boolean values (so,
3956 for example, yes, True, and 15 cannot be used as field names).
3957 A document may contain multiple metadata blocks. If two metadata
3959 blocks attempt to set the same field, the value from the second block
3960 will be taken.
3961 Each metadata block is handled internally as an independent YAML docu‐
3963 ment. This means, for example, that any YAML anchors defined in a
3964 block cannot be referenced in another block.
3965 When pandoc is used with -t markdown to create a Markdown document, a
3967 YAML metadata block will be produced only if the -s/--standalone option
3968 is used. All of the metadata will appear in a single block at the be‐
3969 ginning of the document.
3970 Note that YAML escaping rules must be followed. Thus, for example, if
3972 a title contains a colon, it must be quoted, and if it contains a back‐
3973 slash escape, then it must be ensured that it is not treated as a YAML
3974 escape sequence. The pipe character (|) can be used to begin an in‐
3975 dented block that will be interpreted literally, without need for es‐
3976 caping. This form is necessary when the field contains blank lines or
3977 block-level formatting:
3978 ---
3980 title: 'This is the title: it contains a colon'
3981 author:
3982 - Author One
3983 - Author Two
3984 keywords: [nothing, nothingness]
3985 abstract: |
3986 This is the abstract.
3987 It consists of two paragraphs.
3989 ...
3990 The literal block after the | must be indented relative to the line
3992 containing the |. If it is not, the YAML will be invalid and pandoc
3993 will not interpret it as metadata. For an overview of the complex
3994 rules governing YAML, see the Wikipedia entry on YAML syntax.
3995 Template variables will be set automatically from the metadata. Thus,
3997 for example, in writing HTML, the variable abstract will be set to the
3998 HTML equivalent of the Markdown in the abstract field:
3999 <p>This is the abstract.</p>
4001 <p>It consists of two paragraphs.</p>
4002 Variables can contain arbitrary YAML structures, but the template must
4004 match this structure. The author variable in the default templates ex‐
4005 pects a simple list or string, but can be changed to support more com‐
4006 plicated structures. The following combination, for example, would add
4007 an affiliation to the author if one is given:
4008 ---
4010 title: The document title
4011 author:
4012 - name: Author One
4013 affiliation: University of Somewhere
4014 - name: Author Two
4015 affiliation: University of Nowhere
4016 ...
4017 To use the structured authors in the example above, you would need a
4019 custom template:
4020 $for(author)$
4022 $if(author.name)$
4023 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
4024 $else$
4025 $author$
4026 $endif$
4027 $endfor$
4028 Raw content to include in the document’s header may be specified using
4030 header-includes; however, it is important to mark up this content as
4031 raw code for a particular output format, using the raw_attribute exten‐
4032 sion, or it will be interpreted as markdown. For example:
4033 header-includes:
4035 - |
4036 ```{=latex}
4037 \let\oldsection\section
4038 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
4039 ```
4040 Note: the yaml_metadata_block extension works with commonmark as well
4042 as markdown (and it is enabled by default in gfm and commonmark_x).
4043 However, in these formats the following restrictions apply:
4044 • The YAML metadata block must occur at the beginning of the document
4046 (and there can be only one). If multiple files are given as argu‐
4047 ments to pandoc, only the first can be a YAML metadata block.
4048 • The leaf nodes of the YAML structure are parsed in isolation from
4050 each other and from the rest of the document. So, for example, you
4051 can’t use a reference link in these contexts if the link definition
4052 is somewhere else in the document.
4053 Backslash escapes
4055 Extension: all_symbols_escapable
4056 Except inside a code block or inline code, any punctuation or space
4057 character preceded by a backslash will be treated literally, even if it
4058 would normally indicate formatting. Thus, for example, if one writes
4059 *\*hello\**
4061 one will get
4063 <em>*hello*</em>
4065 instead of
4067 <strong>hello</strong>
4069 This rule is easier to remember than original Markdown’s rule, which
4071 allows only the following characters to be backslash-escaped:
4072 \`*_{}[]()>#+-.!
4074 (However, if the markdown_strict format is used, the original Markdown
4076 rule will be used.)
4077 A backslash-escaped space is parsed as a nonbreaking space. In TeX
4079 output, it will appear as ~. In HTML and XML output, it will appear as
4080 a literal unicode nonbreaking space character (note that it will thus
4081 actually look “invisible” in the generated HTML source; you can still
4082 use the --ascii command-line option to make it appear as an explicit
4083 entity).
4084 A backslash-escaped newline (i.e. a backslash occurring at the end of a
4086 line) is parsed as a hard line break. It will appear in TeX output as
4087 \\ and in HTML as <br />. This is a nice alternative to Markdown’s
4088 “invisible” way of indicating hard line breaks using two trailing spa‐
4089 ces on a line.
4090 Backslash escapes do not work in verbatim contexts.
4092 Inline formatting
4094 Emphasis
4095 To emphasize some text, surround it with *s or _, like this:
4096 This text is _emphasized with underscores_, and this
4098 is *emphasized with asterisks*.
4099 Double * or _ produces strong emphasis:
4101 This is **strong emphasis** and __with underscores__.
4103 A * or _ character surrounded by spaces, or backslash-escaped, will not
4105 trigger emphasis:
4106 This is * not emphasized *, and \*neither is this\*.
4108 Extension: intraword_underscores
4110 Because _ is sometimes used inside words and identifiers, pandoc does
4111 not interpret a _ surrounded by alphanumeric characters as an emphasis
4112 marker. If you want to emphasize just part of a word, use *:
4113 feas*ible*, not feas*able*.
4115 Highlighting
4117 To highlight text, use the mark class:
4118 [Mark]{.mark}
4120 Or, without the bracketed_spans extension (but with native_spans):
4122 <span class="mark">Mark</span>
4124 This will work in html output.
4126 Strikeout
4128 Extension: strikeout
4129 To strike out a section of text with a horizontal line, begin and end
4130 it with ~~. Thus, for example,
4131 This ~~is deleted text.~~
4133 Superscripts and subscripts
4135 Extension: superscript, subscript
4136 Superscripts may be written by surrounding the superscripted text by ^
4137 characters; subscripts may be written by surrounding the subscripted
4138 text by ~ characters. Thus, for example,
4139 H~2~O is a liquid. 2^10^ is 1024.
4141 The text between ^...^ or ~...~ may not contain spaces or newlines. If
4143 the superscripted or subscripted text contains spaces, these spaces
4144 must be escaped with backslashes. (This is to prevent accidental su‐
4145 perscripting and subscripting through the ordinary use of ~ and ^, and
4146 also bad interactions with footnotes.) Thus, if you want the letter P
4147 with `a cat' in subscripts, use P~a\ cat~, not P~a cat~.
4148 Verbatim
4150 To make a short span of text verbatim, put it inside backticks:
4151 What is the difference between `>>=` and `>>`?
4153 If the verbatim text includes a backtick, use double backticks:
4155 Here is a literal backtick `` ` ``.
4157 (The spaces after the opening backticks and before the closing back‐
4159 ticks will be ignored.)
4160 The general rule is that a verbatim span starts with a string of con‐
4162 secutive backticks (optionally followed by a space) and ends with a
4163 string of the same number of backticks (optionally preceded by a
4164 space).
4165 Note that backslash-escapes (and other Markdown constructs) do not work
4167 in verbatim contexts:
4168 This is a backslash followed by an asterisk: `\*`.
4170 Extension: inline_code_attributes
4172 Attributes can be attached to verbatim text, just as with fenced code
4173 blocks:
4174 `<$>`{.haskell}
4176 Underline
4178 To underline text, use the underline class:
4179 [Underline]{.underline}
4181 Or, without the bracketed_spans extension (but with native_spans):
4183 <span class="underline">Underline</span>
4185 This will work in all output formats that support underline.
4187 Small caps
4189 To write small caps, use the smallcaps class:
4190 [Small caps]{.smallcaps}
4192 Or, without the bracketed_spans extension:
4194 <span class="smallcaps">Small caps</span>
4196 For compatibility with other Markdown flavors, CSS is also supported:
4198 <span style="font-variant:small-caps;">Small caps</span>
4200 This will work in all output formats that support small caps.
4202 Math
4204 Extension: tex_math_dollars
4205 Anything between two $ characters will be treated as TeX math. The
4206 opening $ must have a non-space character immediately to its right,
4207 while the closing $ must have a non-space character immediately to its
4208 left, and must not be followed immediately by a digit. Thus, $20,000
4209 and $30,000 won’t parse as math. If for some reason you need to en‐
4210 close text in literal $ characters, backslash-escape them and they
4211 won’t be treated as math delimiters.
4212 For display math, use $$ delimiters. (In this case, the delimiters may
4214 be separated from the formula by whitespace. However, there can be no
4215 blank lines between the opening and closing $$ delimiters.)
4216 TeX math will be printed in all output formats. How it is rendered de‐
4218 pends on the output format:
4219 LaTeX It will appear verbatim surrounded by \(...\) (for inline math)
4221 or \[...\] (for display math).
4222 Markdown, Emacs Org mode, ConTeXt, ZimWiki
4224 It will appear verbatim surrounded by $...$ (for inline math) or
4225 $$...$$ (for display math).
4226 XWiki It will appear verbatim surrounded by {{formula}}..{{/formula}}.
4228 reStructuredText
4230 It will be rendered using an interpreted text role :math:.
4231 AsciiDoc
4233 For AsciiDoc output format (-t asciidoc) it will appear verbatim
4234 surrounded by latexmath:[$...$] (for inline math) or [latex‐
4235 math]++++\[...\]+++ (for display math). For AsciiDoctor output
4236 format (-t asciidoctor) the LaTeX delimiters ($..$ and \[..\])
4237 are omitted.
4238 Texinfo
4240 It will be rendered inside a @math command.
4241 roff man, Jira markup
4243 It will be rendered verbatim without $’s.
4244 MediaWiki, DokuWiki
4246 It will be rendered inside <math> tags.
4247 Textile
4249 It will be rendered inside <span class="math"> tags.
4250 RTF, OpenDocument
4252 It will be rendered, if possible, using Unicode characters, and
4253 will otherwise appear verbatim.
4254 ODT It will be rendered, if possible, using MathML.
4256 DocBook
4258 If the --mathml flag is used, it will be rendered using MathML
4259 in an inlineequation or informalequation tag. Otherwise it will
4260 be rendered, if possible, using Unicode characters.
4261 Docx and PowerPoint
4263 It will be rendered using OMML math markup.
4264 FictionBook2
4266 If the --webtex option is used, formulas are rendered as images
4267 using CodeCogs or other compatible web service, downloaded and
4268 embedded in the e-book. Otherwise, they will appear verbatim.
4269 HTML, Slidy, DZSlides, S5, EPUB
4271 The way math is rendered in HTML will depend on the command-line
4272 options selected. Therefore see Math rendering in HTML above.
4273 Raw HTML
4275 Extension: raw_html
4276 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
4277 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
4278 erally). (Technically this is not an extension, since standard Mark‐
4279 down allows it, but it has been made an extension so that it can be
4280 disabled if desired.)
4281 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
4283 DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile out‐
4284 put, and suppressed in other formats.
4285 For a more explicit way of including raw HTML in a Markdown document,
4287 see the raw_attribute extension.
4288 In the CommonMark format, if raw_html is enabled, superscripts, sub‐
4290 scripts, strikeouts and small capitals will be represented as HTML.
4291 Otherwise, plain-text fallbacks will be used. Note that even if
4292 raw_html is disabled, tables will be rendered with HTML syntax if they
4293 cannot use pipe syntax.
4294 Extension: markdown_in_html_blocks
4296 Original Markdown allows you to include HTML “blocks”: blocks of HTML
4297 between balanced tags that are separated from the surrounding text with
4298 blank lines, and start and end at the left margin. Within these
4299 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
4300 ple), * does not signify emphasis.
4301 Pandoc behaves this way when the markdown_strict format is used; but by
4303 default, pandoc interprets material between HTML block tags as Mark‐
4304 down. Thus, for example, pandoc will turn
4305 <table>
4307 <tr>
4308 <td>*one*</td>
4309 <td>[a link](https://google.com)</td>
4310 </tr>
4311 </table>
4312 into
4314 <table>
4316 <tr>
4317 <td><em>one</em></td>
4318 <td><a href="https://google.com">a link</a></td>
4319 </tr>
4320 </table>
4321 whereas Markdown.pl will preserve it as is.
4323 There is one exception to this rule: text between <script>, <style>,
4325 and <textarea> tags is not interpreted as Markdown.
4326 This departure from original Markdown should make it easier to mix
4328 Markdown with HTML block elements. For example, one can surround a
4329 block of Markdown text with <div> tags without preventing it from being
4330 interpreted as Markdown.
4331 Extension: native_divs
4333 Use native pandoc Div blocks for content inside <div> tags. For the
4334 most part this should give the same output as markdown_in_html_blocks,
4335 but it makes it easier to write pandoc filters to manipulate groups of
4336 blocks.
4337 Extension: native_spans
4339 Use native pandoc Span blocks for content inside <span> tags. For the
4340 most part this should give the same output as raw_html, but it makes it
4341 easier to write pandoc filters to manipulate groups of inlines.
4342 Extension: raw_tex
4344 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
4345 be included in a document. Inline TeX commands will be preserved and
4346 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
4347 you can use LaTeX to include BibTeX citations:
4348 This result was proved in \cite{jones.1967}.
4350 Note that in LaTeX environments, like
4352 \begin{tabular}{|l|l|}\hline
4354 Age & Frequency \\ \hline
4355 18--25 & 15 \\
4356 26--35 & 33 \\
4357 36--45 & 22 \\ \hline
4358 \end{tabular}
4359 the material between the begin and end tags will be interpreted as raw
4361 LaTeX, not as Markdown.
4362 For a more explicit and flexible way of including raw TeX in a Markdown
4364 document, see the raw_attribute extension.
4365 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
4367 Emacs Org mode, and ConTeXt.
4368 Generic raw attribute
4370 Extension: raw_attribute
4371 Inline spans and fenced code blocks with a special kind of attribute
4372 will be parsed as raw content with the designated format. For example,
4373 the following produces a raw roff ms block:
4374 ```{=ms}
4376 .MYMACRO
4377 blah blah
4378 ```
4379 And the following produces a raw html inline element:
4381 This is `<a>html</a>`{=html}
4383 This can be useful to insert raw xml into docx documents, e.g. a page‐
4385 break:
4386 ```{=openxml}
4388 <w:p>
4389 <w:r>
4390 <w:br w:type="page"/>
4391 </w:r>
4392 </w:p>
4393 ```
4394 The format name should match the target format name (see -t/--to,
4396 above, for a list, or use pandoc --list-output-formats). Use openxml
4397 for docx output, opendocument for odt output, html5 for epub3 output,
4398 html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output
4399 (depending on what you use for --pdf-engine).
4400 This extension presupposes that the relevant kind of inline code or
4402 fenced code block is enabled. Thus, for example, to use a raw attri‐
4403 bute with a backtick code block, backtick_code_blocks must be enabled.
4404 The raw attribute cannot be combined with regular attributes.
4406 LaTeX macros
4408 Extension: latex_macros
4409 When this extension is enabled, pandoc will parse LaTeX macro defini‐
4410 tions and apply the resulting macros to all LaTeX math and raw LaTeX.
4411 So, for example, the following will work in all output formats, not
4412 just LaTeX:
4413 \newcommand{\tuple}[1]{\langle #1 \rangle}
4415 $\tuple{a, b, c}$
4417 Note that LaTeX macros will not be applied if they occur inside a raw
4419 span or block marked with the raw_attribute extension.
4420 When latex_macros is disabled, the raw LaTeX and math will not have
4422 macros applied. This is usually a better approach when you are target‐
4423 ing LaTeX or PDF.
4424 Macro definitions in LaTeX will be passed through as raw LaTeX only if
4426 latex_macros is not enabled. Macro definitions in Markdown source (or
4427 other formats allowing raw_tex) will be passed through regardless of
4428 whether latex_macros is enabled.
4429 Links
4431 Markdown allows links to be specified in several ways.
4432 Automatic links
4434 If you enclose a URL or email address in pointy brackets, it will be‐
4435 come a link:
4436 <https://google.com>
4438 <sam@green.eggs.ham>
4439 Inline links
4441 An inline link consists of the link text in square brackets, followed
4442 by the URL in parentheses. (Optionally, the URL can be followed by a
4443 link title, in quotes.)
4444 This is an [inline link](/url), and here's [one with
4446 a title](https://fsf.org "click here for a good time!").
4447 There can be no space between the bracketed part and the parenthesized
4449 part. The link text can contain formatting (such as emphasis), but the
4450 title cannot.
4451 Email addresses in inline links are not autodetected, so they have to
4453 be prefixed with mailto:
4454 [Write me!](mailto:sam@green.eggs.ham)
4456 Reference links
4458 An explicit reference link has two parts, the link itself and the link
4459 definition, which may occur elsewhere in the document (either before or
4460 after the link).
4461 The link consists of link text in square brackets, followed by a label
4463 in square brackets. (There cannot be space between the two unless the
4464 spaced_reference_links extension is enabled.) The link definition con‐
4465 sists of the bracketed label, followed by a colon and a space, followed
4466 by the URL, and optionally (after a space) a link title either in
4467 quotes or in parentheses. The label must not be parseable as a cita‐
4468 tion (assuming the citations extension is enabled): citations take
4469 precedence over link labels.
4470 Here are some examples:
4472 [my label 1]: /foo/bar.html "My title, optional"
4474 [my label 2]: /foo
4475 [my label 3]: https://fsf.org (The Free Software Foundation)
4476 [my label 4]: /bar#special 'A title in single quotes'
4477 The URL may optionally be surrounded by angle brackets:
4479 [my label 5]: <http://foo.bar.baz>
4481 The title may go on the next line:
4483 [my label 3]: https://fsf.org
4485 "The Free Software Foundation"
4486 Note that link labels are not case sensitive. So, this will work:
4488 Here is [my link][FOO]
4490 [Foo]: /bar/baz
4492 In an implicit reference link, the second pair of brackets is empty:
4494 See [my website][].
4496 [my website]: http://foo.bar.baz
4498 Note: In Markdown.pl and most other Markdown implementations, reference
4500 link definitions cannot occur in nested constructions such as list
4501 items or block quotes. Pandoc lifts this arbitrary-seeming restric‐
4502 tion. So the following is fine in pandoc, though not in most other im‐
4503 plementations:
4504 > My block [quote].
4506 >
4507 > [quote]: /foo
4508 Extension: shortcut_reference_links
4510 In a shortcut reference link, the second pair of brackets may be omit‐
4511 ted entirely:
4512 See [my website].
4514 [my website]: http://foo.bar.baz
4516 Internal links
4518 To link to another section of the same document, use the automatically
4519 generated identifier (see Heading identifiers). For example:
4520 See the [Introduction](#introduction).
4522 or
4524 See the [Introduction].
4526 [Introduction]: #introduction
4528 Internal links are currently supported for HTML formats (including HTML
4530 slide shows and EPUB), LaTeX, and ConTeXt.
4531 Images
4533 A link immediately preceded by a ! will be treated as an image. The
4534 link text will be used as the image’s alt text:
4535 
4537 ![movie reel]
4539 [movie reel]: movie.gif
4541 Extension: implicit_figures
4543 An image with nonempty alt text, occurring by itself in a paragraph,
4544 will be rendered as a figure with a caption. The image’s alt text will
4545 be used as the caption.
4546 
4548 How this is rendered depends on the output format. Some output formats
4550 (e.g. RTF) do not yet support figures. In those formats, you’ll just
4551 get an image in a paragraph by itself, with no caption.
4552 If you just want a regular inline image, just make sure it is not the
4554 only thing in the paragraph. One way to do this is to insert a non‐
4555 breaking space after the image:
4556 \
4558 Note that in reveal.js slide shows, an image in a paragraph by itself
4560 that has the r-stretch class will fill the screen, and the caption and
4561 figure tags will be omitted.
4562 Extension: link_attributes
4564 Attributes can be set on links and images:
4565 An inline {#id .class width=30 height=20px}
4567 and a reference ![image][ref] with attributes.
4568 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
4570 (This syntax is compatible with PHP Markdown Extra when only #id and
4572 .class are used.)
4573 For HTML and EPUB, all known HTML5 attributes except width and height
4575 (but including srcset and sizes) are passed through as is. Unknown at‐
4576 tributes are passed through as custom attributes, with data- prepended.
4577 The other writers ignore attributes that are not specifically supported
4578 by their output format.
4579 The width and height attributes on images are treated specially. When
4581 used without a unit, the unit is assumed to be pixels. However, any of
4582 the following unit identifiers can be used: px, cm, mm, in, inch and %.
4583 There must not be any spaces between the number and the unit. For ex‐
4584 ample:
4585 { width=50% }
4587 • Dimensions may be converted to a form that is compatible with the
4589 output format (for example, dimensions given in pixels will be con‐
4590 verted to inches when converting HTML to LaTeX). Conversion between
4591 pixels and physical measurements is affected by the --dpi option (by
4592 default, 96 dpi is assumed, unless the image itself contains dpi in‐
4593 formation).
4594 • The % unit is generally relative to some available space. For exam‐
4596 ple the above example will render to the following.
4597 • HTML: <img href="file.jpg" style="width: 50%;" />
4599 • LaTeX: \includegraphics[width=0.5\textwidth,height=\text‐
4601 height]{file.jpg} (If you’re using a custom template, you need to
4602 configure graphicx as in the default template.)
4603 • ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
4605 • Some output formats have a notion of a class (ConTeXt) or a unique
4607 identifier (LaTeX \caption), or both (HTML).
4608 • When no width or height attributes are specified, the fallback is to
4610 look at the image resolution and the dpi metadata embedded in the im‐
4611 age file.
4612 Divs and Spans
4614 Using the native_divs and native_spans extensions (see above), HTML
4615 syntax can be used as part of markdown to create native Div and Span
4616 elements in the pandoc AST (as opposed to raw HTML). However, there is
4617 also nicer syntax available:
4618 Extension: fenced_divs
4620 Allow special fenced syntax for native Div blocks. A Div starts with a
4621 fence containing at least three consecutive colons plus some at‐
4622 tributes. The attributes may optionally be followed by another string
4623 of consecutive colons. The attribute syntax is exactly as in fenced
4624 code blocks (see Extension: fenced_code_attributes). As with fenced
4625 code blocks, one can use either attributes in curly braces or a single
4626 unbraced word, which will be treated as a class name. The Div ends
4627 with another line containing a string of at least three consecutive
4628 colons. The fenced Div should be separated by blank lines from preced‐
4629 ing and following blocks.
4630 Example:
4632 ::::: {#special .sidebar}
4634 Here is a paragraph.
4635 And another.
4637 :::::
4638 Fenced divs can be nested. Opening fences are distinguished because
4640 they must have attributes:
4641 ::: Warning ::::::
4643 This is a warning.
4644 ::: Danger
4646 This is a warning within a warning.
4647 :::
4648 ::::::::::::::::::
4649 Fences without attributes are always closing fences. Unlike with
4651 fenced code blocks, the number of colons in the closing fence need not
4652 match the number in the opening fence. However, it can be helpful for
4653 visual clarity to use fences of different lengths to distinguish nested
4654 divs from their parents.
4655 Extension: bracketed_spans
4657 A bracketed sequence of inlines, as one would use to begin a link, will
4658 be treated as a Span with attributes if it is followed immediately by
4659 attributes:
4660 [This is *some text*]{.class key="val"}
4662 Footnotes
4664 Extension: footnotes
4665 Pandoc’s Markdown allows footnotes, using the following syntax:
4666 Here is a footnote reference,[^1] and another.[^longnote]
4668 [^1]: Here is the footnote.
4670 [^longnote]: Here's one with multiple blocks.
4672 Subsequent paragraphs are indented to show that they
4674 belong to the previous footnote.
4675 { some.code }
4677 The whole paragraph can be indented, or just the first
4679 line. In this way, multi-paragraph footnotes work like
4680 multi-paragraph list items.
4681 This paragraph won't be part of the note, because it
4683 isn't indented.
4684 The identifiers in footnote references may not contain spaces, tabs, or
4686 newlines. These identifiers are used only to correlate the footnote
4687 reference with the note itself; in the output, footnotes will be num‐
4688 bered sequentially.
4689 The footnotes themselves need not be placed at the end of the document.
4691 They may appear anywhere except inside other block elements (lists,
4692 block quotes, tables, etc.). Each footnote should be separated from
4693 surrounding content (including other footnotes) by blank lines.
4694 Extension: inline_notes
4696 Inline footnotes are also allowed (though, unlike regular notes, they
4697 cannot contain multiple paragraphs). The syntax is as follows:
4698 Here is an inline note.^[Inline notes are easier to write, since
4700 you don't have to pick an identifier and move down to type the
4701 note.]
4702 Inline and regular footnotes may be mixed freely.
4704 Citation syntax
4706 Extension: citations
4707 To cite a bibliographic item with an identifier foo, use the syntax
4708 @foo. Normal citations should be included in square brackets, with
4709 semicolons separating distinct items:
4710 Blah blah [@doe99; @smith2000; @smith2004].
4712 How this is rendered depends on the citation style. In an author-date
4714 style, it might render as
4715 Blah blah (Doe 1999, Smith 2000, 2004).
4717 In a footnote style, it might render as
4719 Blah blah.[^1]
4721 [^1]: John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
4723 Susan Smith, "Flies," *Journal of Insects* (2000);
4724 Susan Smith, "Bees," *Journal of Insects* (2004).
4725 See the CSL user documentation for more information about CSL styles
4727 and how they affect rendering.
4728 Unless a citation key starts with a letter, digit, or _, and contains
4730 only alphanumerics and single internal punctuation characters
4731 (:.#$%&-+?<>~/), it must be surrounded by curly braces, which are not
4732 considered part of the key. In @Foo_bar.baz., the key is Foo_bar.baz
4733 because the final period is not internal punctuation, so it is not in‐
4734 cluded in the key. In @{Foo_bar.baz.}, the key is Foo_bar.baz., in‐
4735 cluding the final period. In @Foo_bar--baz, the key is Foo_bar because
4736 the repeated internal punctuation characters terminate the key. The
4737 curly braces are recommended if you use URLs as keys: [@{https://exam‐
4738 ple.com/bib?name=foobar&date=2000}, p. 33].
4739 Citation items may optionally include a prefix, a locator, and a suf‐
4741 fix. In
4742 Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].
4744 the first item (doe99) has prefix see, locator pp. 33-35, and suffix
4746 and *passim*. The second item (smith04) has locator chap. 1 and no
4747 prefix or suffix.
4748 Pandoc uses some heuristics to separate the locator from the rest of
4750 the subject. It is sensitive to the locator terms defined in the CSL
4751 locale files. Either abbreviated or unabbreviated forms are accepted.
4752 In the en-US locale, locator terms can be written in either singular or
4753 plural forms, as book, bk./bks.; chapter, chap./chaps.; column,
4754 col./cols.; figure, fig./figs.; folio, fol./fols.; number, no./nos.;
4755 line, l./ll.; note, n./nn.; opus, op./opp.; page, p./pp.; paragraph,
4756 para./paras.; part, pt./pts.; section, sec./secs.; sub verbo,
4757 s.v./s.vv.; verse, v./vv.; volume, vol./vols.; ¶/¶¶; §/§§. If no loca‐
4758 tor term is used, “page” is assumed.
4759 In complex cases, you can force something to be treated as a locator by
4761 enclosing it in curly braces or prevent parsing the suffix as locator
4762 by prepending curly braces:
4763 [@smith{ii, A, D-Z}, with a suffix]
4765 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
4766 [@smith{}, 99 years later]
4767 A minus sign (-) before the @ will suppress mention of the author in
4769 the citation. This can be useful when the author is already mentioned
4770 in the text:
4771 Smith says blah [-@smith04].
4773 You can also write an author-in-text citation, by omitting the square
4775 brackets:
4776 @smith04 says blah.
4778 @smith04 [p. 33] says blah.
4780 This will cause the author’s name to be rendered, followed by the bib‐
4782 liographical details. Use this form when you want to make the citation
4783 the subject of a sentence.
4784 When you are using a note style, it is usually better to let citeproc
4786 create the footnotes from citations rather than writing an explicit
4787 note. If you do write an explicit note that contains a citation, note
4788 that normal citations will be put in parentheses, while author-in-text
4789 citations will not. For this reason, it is sometimes preferable to use
4790 the author-in-text style inside notes when using a note style.
4791 Non-default extensions
4793 The following Markdown syntax extensions are not enabled by default in
4794 pandoc, but may be enabled by adding +EXTENSION to the format name,
4795 where EXTENSION is the name of the extension. Thus, for example, mark‐
4796 down+hard_line_breaks is Markdown with hard line breaks.
4797 Extension: rebase_relative_paths
4799 Rewrite relative paths for Markdown links and images, depending on the
4800 path of the file containing the link or image link. For each link or
4801 image, pandoc will compute the directory of the containing file, rela‐
4802 tive to the working directory, and prepend the resulting path to the
4803 link or image path.
4804 The use of this extension is best understood by example. Suppose you
4806 have a subdirectory for each chapter of a book, chap1, chap2, chap3.
4807 Each contains a file text.md and a number of images used in the chap‐
4808 ter. You would like to have  in chap1/text.md re‐
4809 fer to chap1/spider.jpg and  in chap2/text.md refer
4810 to chap2/spider.jpg. To do this, use
4811 pandoc chap*/*.md -f markdown+rebase_relative_paths
4813 Without this extension, you would have to use  in chap1/text.md and  in
4816 chap2/text.md. Links with relative paths will be rewritten in the same
4817 way as images.
4818 Absolute paths and URLs are not changed. Neither are empty paths or
4820 paths consisting entirely of a fragment, e.g., #foo.
4821 Note that relative paths in reference links and images will be rewrit‐
4823 ten relative to the file containing the link reference definition, not
4824 the file containing the reference link or image itself, if these dif‐
4825 fer.
4826 Extension: attributes
4828 Allows attributes to be attached to any inline or block-level element
4829 when parsing commonmark. The syntax for the attributes is the same as
4830 that used in header_attributes.
4831 • Attributes that occur immediately after an inline element affect that
4833 element. If they follow a space, then they belong to the space.
4834 (Hence, this option subsumes inline_code_attributes and link_at‐
4835 tributes.)
4836 • Attributes that occur immediately before a block element, on a line
4838 by themselves, affect that element.
4839 • Consecutive attribute specifiers may be used, either for blocks or
4841 for inlines. Their attributes will be combined.
4842 • Attributes that occur at the end of the text of a Setext or ATX head‐
4844 ing (separated by whitespace from the text) affect the heading ele‐
4845 ment. (Hence, this option subsumes header_attributes.)
4846 • Attributes that occur after the opening fence in a fenced code block
4848 affect the code block element. (Hence, this option subsumes
4849 fenced_code_attributes.)
4850 • Attributes that occur at the end of a reference link definition af‐
4852 fect links that refer to that definition.
4853 Note that pandoc’s AST does not currently allow attributes to be at‐
4855 tached to arbitrary elements. Hence a Span or Div container will be
4856 added if needed.
4857 Extension: old_dashes
4859 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - be‐
4860 fore a numeral is an en-dash, and -- is an em-dash. This option only
4861 has an effect if smart is enabled. It is selected automatically for
4862 textile input.
4863 Extension: angle_brackets_escapable
4865 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
4866 vored Markdown but not original Markdown. This is implied by pandoc’s
4867 default all_symbols_escapable.
4868 Extension: lists_without_preceding_blankline
4870 Allow a list to occur right after a paragraph, with no intervening
4871 blank space.
4872 Extension: four_space_rule
4874 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
4875 ces indent are needed for list item continuation paragraphs.
4876 Extension: spaced_reference_links
4878 Allow whitespace between the two components of a reference link, for
4879 example,
4880 [foo] [bar].
4882 Extension: hard_line_breaks
4884 Causes all newlines within a paragraph to be interpreted as hard line
4885 breaks instead of spaces.
4886 Extension: ignore_line_breaks
4888 Causes newlines within a paragraph to be ignored, rather than being
4889 treated as spaces or as hard line breaks. This option is intended for
4890 use with East Asian languages where spaces are not used between words,
4891 but text is divided into lines for readability.
4892 Extension: east_asian_line_breaks
4894 Causes newlines within a paragraph to be ignored, rather than being
4895 treated as spaces or as hard line breaks, when they occur between two
4896 East Asian wide characters. This is a better choice than ig‐
4897 nore_line_breaks for texts that include a mix of East Asian wide char‐
4898 acters and other characters.
4899 Extension: emoji
4901 Parses textual emojis like :smile: as Unicode emoticons.
4902 Extension: tex_math_single_backslash
4904 Causes anything between \( and \) to be interpreted as inline TeX math,
4905 and anything between \[ and \] to be interpreted as display TeX math.
4906 Note: a drawback of this extension is that it precludes escaping ( and
4907 [.
4908 Extension: tex_math_double_backslash
4910 Causes anything between \\( and \\) to be interpreted as inline TeX
4911 math, and anything between \\[ and \\] to be interpreted as display TeX
4912 math.
4913 Extension: markdown_attribute
4915 By default, pandoc interprets material inside block-level tags as Mark‐
4916 down. This extension changes the behavior so that Markdown is only
4917 parsed inside block-level tags if the tags have the attribute mark‐
4918 down=1.
4919 Extension: mmd_title_block
4921 Enables a MultiMarkdown style title block at the top of the document,
4922 for example:
4923 Title: My title
4925 Author: John Doe
4926 Date: September 1, 2008
4927 Comment: This is a sample mmd title block, with
4928 a field spanning multiple lines.
4929 See the MultiMarkdown documentation for details. If pandoc_title_block
4931 or yaml_metadata_block is enabled, it will take precedence over mmd_ti‐
4932 tle_block.
4933 Extension: abbreviations
4935 Parses PHP Markdown Extra abbreviation keys, like
4936 *[HTML]: Hypertext Markup Language
4938 Note that the pandoc document model does not support abbreviations, so
4940 if this extension is enabled, abbreviation keys are simply skipped (as
4941 opposed to being parsed as paragraphs).
4942 Extension: autolink_bare_uris
4944 Makes all absolute URIs into links, even when not surrounded by pointy
4945 braces <...>.
4946 Extension: mmd_link_attributes
4948 Parses multimarkdown style key-value attributes on link and image ref‐
4949 erences. This extension should not be confused with the link_at‐
4950 tributes extension.
4951 This is a reference ![image][ref] with multimarkdown attributes.
4953 [ref]: https://path.to/image "Image title" width=20px height=30px
4955 id=myId class="myClass1 myClass2"
4956 Extension: mmd_header_identifiers
4958 Parses multimarkdown style heading identifiers (in square brackets, af‐
4959 ter the heading but before any trailing #s in an ATX heading).
4960 Extension: compact_definition_lists
4962 Activates the definition list syntax of pandoc 1.12.x and earlier.
4963 This syntax differs from the one described above under Definition lists
4964 in several respects:
4965 • No blank line is required between consecutive items of the definition
4967 list.
4968 • To get a “tight” or “compact” list, omit space between consecutive
4970 items; the space between a term and its definition does not affect
4971 anything.
4972 • Lazy wrapping of paragraphs is not allowed: the entire definition
4974 must be indented four spaces.
4975 Extension: gutenberg
4977 Use Project Gutenberg conventions for plain output: all-caps for strong
4978 emphasis, surround by underscores for regular emphasis, add extra blank
4979 space around headings.
4980 Extension: sourcepos
4982 Include source position attributes when parsing commonmark. For ele‐
4983 ments that accept attributes, a data-pos attribute is added; other ele‐
4984 ments are placed in a surrounding Div or Span element with a data-pos
4985 attribute.
4986 Extension: short_subsuperscripts
4988 Parse multimarkdown style subscripts and superscripts, which start with
4989 a `~' or `^' character, respectively, and include the alphanumeric se‐
4990 quence that follows. For example:
4991 x^2 = 4
4993 or
4995 Oxygen is O~2.
4997 Markdown variants
4999 In addition to pandoc’s extended Markdown, the following Markdown vari‐
5000 ants are supported:
5001 • markdown_phpextra (PHP Markdown Extra)
5003 • markdown_github (deprecated GitHub-Flavored Markdown)
5005 • markdown_mmd (MultiMarkdown)
5007 • markdown_strict (Markdown.pl)
5009 • commonmark (CommonMark)
5011 • gfm (Github-Flavored Markdown)
5013 • commonmark_x (CommonMark with many pandoc extensions)
5015 To see which extensions are supported for a given format, and which are
5017 enabled by default, you can use the command
5018 pandoc --list-extensions=FORMAT
5020 where FORMAT is replaced with the name of the format.
5022 Note that the list of extensions for commonmark, gfm, and commonmark_x
5024 are defined relative to default commonmark. So, for example, back‐
5025 tick_code_blocks does not appear as an extension, since it is enabled
5026 by default and cannot be disabled.
5027
5029 When the --citeproc option is used, pandoc can automatically generate
5030 citations and a bibliography in a number of styles. Basic usage is
5031 pandoc --citeproc myinput.txt
5033 To use this feature, you will need to have
5035 • a document containing citations (see Extension: citations);
5037 • a source of bibliographic data: either an external bibliography file
5039 or a list of references in the document’s YAML metadata;
5040 • optionally, a CSL citation style.
5042 Specifying bibliographic data
5044 You can specify an external bibliography using the bibliography metada‐
5045 ta field in a YAML metadata section or the --bibliography command line
5046 argument. If you want to use multiple bibliography files, you can sup‐
5047 ply multiple --bibliography arguments or set bibliography metadata
5048 field to YAML array. A bibliography may have any of these formats:
5049 Format File extension
5051 ---------- ----------------
5052 BibLaTeX .bib
5053 BibTeX .bibtex
5054 CSL JSON .json
5055 CSL YAML .yaml
5056 RIS .ris
5057 Note that .bib can be used with both BibTeX and BibLaTeX files; use the
5059 extension .bibtex to force interpretation as BibTeX.
5060 In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside
5062 fields such as title; in CSL YAML databases, pandoc Markdown; and in
5063 CSL JSON databases, an HTML-like markup:
5064 <i>...</i>
5066 italics
5067 <b>...</b>
5069 bold
5070 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
5072 small capitals
5073 <sub>...</sub>
5075 subscript
5076 <sup>...</sup>
5078 superscript
5079 <span class="nocase">...</span>
5081 prevent a phrase from being capitalized as title case
5082 As an alternative to specifying a bibliography file using --bibliogra‐
5084 phy or the YAML metadata field bibliography, you can include the cita‐
5085 tion data directly in the references field of the document’s YAML meta‐
5086 data. The field should contain an array of YAML-encoded references,
5087 for example:
5088 ---
5090 references:
5091 - type: article-journal
5092 id: WatsonCrick1953
5093 author:
5094 - family: Watson
5095 given: J. D.
5096 - family: Crick
5097 given: F. H. C.
5098 issued:
5099 date-parts:
5100 - - 1953
5101 - 4
5102 - 25
5103 title: 'Molecular structure of nucleic acids: a structure for
5104 deoxyribose nucleic acid'
5105 title-short: Molecular structure of nucleic acids
5106 container-title: Nature
5107 volume: 171
5108 issue: 4356
5109 page: 737-738
5110 DOI: 10.1038/171737a0
5111 URL: https://www.nature.com/articles/171737a0
5112 language: en-GB
5113 ...
5114 If both an external bibliography and inline (YAML metadata) references
5116 are provided, both will be used. In case of conflicting ids, the in‐
5117 line references will take precedence.
5118 Note that pandoc can be used to produce such a YAML metadata section
5120 from a BibTeX, BibLaTeX, or CSL JSON bibliography:
5121 pandoc chem.bib -s -f biblatex -t markdown
5123 pandoc chem.json -s -f csljson -t markdown
5124 Indeed, pandoc can convert between any of these citation formats:
5126 pandoc chem.bib -s -f biblatex -t csljson
5128 pandoc chem.yaml -s -f markdown -t biblatex
5129 Running pandoc on a bibliography file with the --citeproc option will
5131 create a formatted bibliography in the format of your choice:
5132 pandoc chem.bib -s --citeproc -o chem.html
5134 pandoc chem.bib -s --citeproc -o chem.pdf
5135 Capitalization in titles
5137 If you are using a bibtex or biblatex bibliography, then observe the
5138 following rules:
5139 • English titles should be in title case. Non-English titles should be
5141 in sentence case, and the langid field in biblatex should be set to
5142 the relevant language. (The following values are treated as English:
5143 american, british, canadian, english, australian, newzealand, USen‐
5144 glish, or UKenglish.)
5145 • As is standard with bibtex/biblatex, proper names should be protected
5147 with curly braces so that they won’t be lowercased in styles that
5148 call for sentence case. For example:
5149 title = {My Dinner with {Andre}}
5151 • In addition, words that should remain lowercase (or camelCase) should
5153 be protected:
5154 title = {Spin Wave Dispersion on the {nm} Scale}
5156 Though this is not necessary in bibtex/biblatex, it is necessary with
5158 citeproc, which stores titles internally in sentence case, and con‐
5159 verts to title case in styles that require it. Here we protect “nm”
5160 so that it doesn’t get converted to “Nm” at this stage.
5161 If you are using a CSL bibliography (either JSON or YAML), then observe
5163 the following rules:
5164 • All titles should be in sentence case.
5166 • Use the language field for non-English titles to prevent their con‐
5168 version to title case in styles that call for this. (Conversion hap‐
5169 pens only if language begins with en or is left empty.)
5170 • Protect words that should not be converted to title case using this
5172 syntax:
5173 Spin wave dispersion on the <span class="nocase">nm</span> scale
5175 Conference Papers, Published vs. Unpublished
5177 For a formally published conference paper, use the biblatex entry type
5178 inproceedings (which will be mapped to CSL paper-conference).
5179 For an unpublished manuscript, use the biblatex entry type unpublished
5181 without an eventtitle field (this entry type will be mapped to CSL man‐
5182 uscript).
5183 For a talk, an unpublished conference paper, or a poster presentation,
5185 use the biblatex entry type unpublished with an eventtitle field (this
5186 entry type will be mapped to CSL speech). Use the biblatex type field
5187 to indicate the type, e.g. “Paper”, or “Poster”. venue and eventdate
5188 may be useful too, though eventdate will not be rendered by most CSL
5189 styles. Note that venue is for the event’s venue, unlike location
5190 which describes the publisher’s location; do not use the latter for an
5191 unpublished conference paper.
5192 Specifying a citation style
5194 Citations and references can be formatted using any style supported by
5195 the Citation Style Language, listed in the Zotero Style Repository.
5196 These files are specified using the --csl option or the csl (or cita‐
5197 tion-style) metadata field. By default, pandoc will use the Chicago
5198 Manual of Style author-date format. (You can override this default by
5199 copying a CSL style of your choice to default.csl in your user data di‐
5200 rectory.) The CSL project provides further information on finding and
5201 editing styles.
5202 The --citation-abbreviations option (or the citation-abbreviations
5204 metadata field) may be used to specify a JSON file containing abbrevia‐
5205 tions of journals that should be used in formatted bibliographies when
5206 form="short" is specified. The format of the file can be illustrated
5207 with an example:
5208 { "default": {
5210 "container-title": {
5211 "Lloyd's Law Reports": "Lloyd's Rep",
5212 "Estates Gazette": "EG",
5213 "Scots Law Times": "SLT"
5214 }
5215 }
5216 }
5217 Citations in note styles
5219 Pandoc’s citation processing is designed to allow you to move between
5220 author-date, numerical, and note styles without modifying the markdown
5221 source. When you’re using a note style, avoid inserting footnotes man‐
5222 ually. Instead, insert citations just as you would in an author-date
5223 style—for example,
5224 Blah blah [@foo, p. 33].
5226 The footnote will be created automatically. Pandoc will take care of
5228 removing the space and moving the note before or after the period, de‐
5229 pending on the setting of notes-after-punctuation, as described below
5230 in Other relevant metadata fields.
5231 In some cases you may need to put a citation inside a regular footnote.
5233 Normal citations in footnotes (such as [@foo, p. 33]) will be rendered
5234 in parentheses. In-text citations (such as @foo [p. 33]) will be ren‐
5235 dered without parentheses. (A comma will be added if appropriate.)
5236 Thus:
5237 [^1]: Some studies [@foo; @bar, p. 33] show that
5239 frubulicious zoosnaps are quantical. For a survey
5240 of the literature, see @baz [chap. 1].
5241 Raw content in a style
5243 To include raw content in a prefix, suffix, delimiter, or term, sur‐
5244 round it with these tags indicating the format:
5245 {{jats}}<ref>{{/jats}}
5247 Without the tags, the string will be interpreted as a string and es‐
5249 caped in the output, rather than being passed through raw.
5250 This feature allows stylesheets to be customized to give different out‐
5252 put for different output formats. However, stylesheets customized in
5253 this way will not be usable by other CSL implementations.
5254 Placement of the bibliography
5256 If the style calls for a list of works cited, it will be placed in a
5257 div with id refs, if one exists:
5258 ::: {#refs}
5260 :::
5261 Otherwise, it will be placed at the end of the document. Generation of
5263 the bibliography can be suppressed by setting suppress-bibliography:
5264 true in the YAML metadata.
5265 If you wish the bibliography to have a section heading, you can set
5267 reference-section-title in the metadata, or put the heading at the be‐
5268 ginning of the div with id refs (if you are using it) or at the end of
5269 your document:
5270 last paragraph...
5272 # References
5274 The bibliography will be inserted after this heading. Note that the
5276 unnumbered class will be added to this heading, so that the section
5277 will not be numbered.
5278 If you want to put the bibliography into a variable in your template,
5280 one way to do that is to put the div with id refs into a metadata
5281 field, e.g.
5282 ---
5284 refs: |
5285 ::: {#refs}
5286 :::
5287 ...
5288 You can then put the variable $refs$ into your template where you want
5290 the bibliography to be placed.
5291 Including uncited items in the bibliography
5293 If you want to include items in the bibliography without actually cit‐
5294 ing them in the body text, you can define a dummy nocite metadata field
5295 and put the citations there:
5296 ---
5298 nocite: |
5299 @item1, @item2
5300 ...
5301 @item3
5303 In this example, the document will contain a citation for item3 only,
5305 but the bibliography will contain entries for item1, item2, and item3.
5306 It is possible to create a bibliography with all the citations, whether
5308 or not they appear in the document, by using a wildcard:
5309 ---
5311 nocite: |
5312 @*
5313 ...
5314 For LaTeX output, you can also use natbib or biblatex to render the
5316 bibliography. In order to do so, specify bibliography files as out‐
5317 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
5318 tion. Bear in mind that bibliography files have to be in either BibTeX
5319 (for --natbib) or BibLaTeX (for --biblatex) format.
5320 Other relevant metadata fields
5322 A few other metadata fields affect bibliography formatting:
5323 link-citations
5325 If true, citations will be hyperlinked to the corresponding bib‐
5326 liography entries (for author-date and numerical styles only).
5327 Defaults to false.
5328 link-bibliography
5330 If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be
5331 rendered as hyperlinks. (If an entry contains a DOI, PMCID,
5332 PMID, or URL, but none of these fields are rendered by the
5333 style, then the title, or in the absence of a title the whole
5334 entry, will be hyperlinked.) Defaults to true.
5335 lang The lang field will affect how the style is localized, for exam‐
5337 ple in the translation of labels, the use of quotation marks,
5338 and the way items are sorted. (For backwards compatibility, lo‐
5339 cale may be used instead of lang, but this use is deprecated.)
5340 A BCP 47 language tag is expected: for example, en, de, en-US,
5342 fr-CA, ug-Cyrl. The unicode extension syntax (after -u-) may be
5343 used to specify options for collation (sorting) more precisely.
5344 Here are some examples:
5345 • zh-u-co-pinyin – Chinese with the Pinyin collation.
5347 • es-u-co-trad – Spanish with the traditional collation (with Ch
5349 sorting after C).
5350 • fr-u-kb – French with “backwards” accent sorting (with coté
5352 sorting after côte).
5353 • en-US-u-kf-upper – English with uppercase letters sorting be‐
5355 fore lower (default is lower before upper).
5356 notes-after-punctuation
5358 If true (the default for note styles), pandoc will put footnote
5359 references or superscripted numerical citations after following
5360 punctuation. For example, if the source contains blah blah
5361 [@jones99]., the result will look like blah blah.[^1], with the
5362 note moved after the period and the space collapsed. If false,
5363 the space will still be collapsed, but the footnote will not be
5364 moved after the punctuation. The option may also be used in nu‐
5365 merical styles that use superscripts for citation numbers (but
5366 for these styles the default is not to move the citation).
5367
5369 You can use pandoc to produce an HTML + JavaScript slide presentation
5370 that can be viewed via a web browser. There are five ways to do this,
5371 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
5372 duce a PDF slide show using LaTeX beamer, or slide shows in Microsoft
5373 PowerPoint format.
5374 Here’s the Markdown source for a simple slide show, habits.txt:
5376 % Habits
5378 % John Doe
5379 % March 22, 2005
5380 # In the morning
5382 ## Getting up
5384 - Turn off alarm
5386 - Get out of bed
5387 ## Breakfast
5389 - Eat eggs
5391 - Drink coffee
5392 # In the evening
5394 ## Dinner
5396 - Eat spaghetti
5398 - Drink wine
5399 ------------------
5401 
5403 ## Going to sleep
5405 - Get in bed
5407 - Count sheep
5408 To produce an HTML/JavaScript slide show, simply type
5410 pandoc -t FORMAT -s habits.txt -o habits.html
5412 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
5414 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
5416 with the -s/--standalone option embeds a link to JavaScript and CSS
5417 files, which are assumed to be available at the relative path s5/de‐
5418 fault (for S5), slideous (for Slideous), reveal.js (for reveal.js), or
5419 at the Slidy website at w3.org (for Slidy). (These paths can be
5420 changed by setting the slidy-url, slideous-url, revealjs-url, or s5-url
5421 variables; see Variables for HTML slides, above.) For DZSlides, the
5422 (relatively short) JavaScript and CSS are included in the file by de‐
5423 fault.
5424 With all HTML slide formats, the --self-contained option can be used to
5426 produce a single file that contains all of the data necessary to dis‐
5427 play the slide show, including linked scripts, stylesheets, images, and
5428 videos.
5429 To produce a PDF slide show using beamer, type
5431 pandoc -t beamer habits.txt -o habits.pdf
5433 Note that a reveal.js slide show can also be converted to a PDF by
5435 printing it to a file from the browser.
5436 To produce a PowerPoint slide show, type
5438 pandoc habits.txt -o habits.pptx
5440 Structuring the slide show
5442 By default, the slide level is the highest heading level in the hierar‐
5443 chy that is followed immediately by content, and not another heading,
5444 somewhere in the document. In the example above, level-1 headings are
5445 always followed by level-2 headings, which are followed by content, so
5446 the slide level is 2. This default can be overridden using the
5447 --slide-level option.
5448 The document is carved up into slides according to the following rules:
5450 • A horizontal rule always starts a new slide.
5452 • A heading at the slide level always starts a new slide.
5454 • Headings below the slide level in the hierarchy create headings with‐
5456 in a slide. (In beamer, a “block” will be created. If the heading
5457 has the class example, an exampleblock environment will be used; if
5458 it has the class alert, an alertblock will be used; otherwise a regu‐
5459 lar block will be used.)
5460 • Headings above the slide level in the hierarchy create “title
5462 slides,” which just contain the section title and help to break the
5463 slide show into sections. Non-slide content under these headings
5464 will be included on the title slide (for HTML slide shows) or in a
5465 subsequent slide with the same title (for beamer).
5466 • A title page is constructed automatically from the document’s title
5468 block, if present. (In the case of beamer, this can be disabled by
5469 commenting out some lines in the default template.)
5470 These rules are designed to support many different styles of slide
5472 show. If you don’t care about structuring your slides into sections
5473 and subsections, you can either just use level-1 headings for all
5474 slides (in that case, level 1 will be the slide level) or you can set
5475 --slide-level=0.
5476 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
5478 layout will be produced, with level-1 headings building horizontally
5479 and level-2 headings building vertically. It is not recommended that
5480 you use deeper nesting of section levels with reveal.js unless you set
5481 --slide-level=0 (which lets reveal.js produce a one-dimensional layout
5482 and only interprets horizontal rules as slide boundaries).
5483 PowerPoint layout choice
5485 When creating slides, the pptx writer chooses from a number of pre-de‐
5486 fined layouts, based on the content of the slide:
5487 Title Slide
5489 This layout is used for the initial slide, which is generated
5490 and filled from the metadata fields date, author, and title, if
5491 they are present.
5492 Section Header
5494 This layout is used for what pandoc calls “title slides”, i.e.
5495 slides which start with a header which is above the slide level
5496 in the hierarchy.
5497 Two Content
5499 This layout is used for two-column slides, i.e. slides contain‐
5500 ing a div with class columns which contains at least two divs
5501 with class column.
5502 Comparison
5504 This layout is used instead of “Two Content” for any two-column
5505 slides in which at least one column contains text followed by
5506 non-text (e.g. an image or a table).
5507 Content with Caption
5509 This layout is used for any non-two-column slides which contain
5510 text followed by non-text (e.g. an image or a table).
5511 Blank This layout is used for any slides which only contain blank con‐
5513 tent, e.g. a slide containing only speaker notes, or a slide
5514 containing only a non-breaking space.
5515 Title and Content
5517 This layout is used for all slides which do not match the crite‐
5518 ria for another layout.
5519 These layouts are chosen from the default pptx reference doc included
5521 with pandoc, unless an alternative reference doc is specified using
5522 --reference-doc.
5523 Incremental lists
5525 By default, these writers produce lists that display “all at once.” If
5526 you want your lists to display incrementally (one item at a time), use
5527 the -i option. If you want a particular list to depart from the de‐
5528 fault, put it in a div block with class incremental or nonincremental.
5529 So, for example, using the fenced div syntax, the following would be
5530 incremental regardless of the document default:
5531 ::: incremental
5533 - Eat spaghetti
5535 - Drink wine
5536 :::
5538 or
5540 ::: nonincremental
5542 - Eat spaghetti
5544 - Drink wine
5545 :::
5547 While using incremental and nonincremental divs is the recommended
5549 method of setting incremental lists on a per-case basis, an older meth‐
5550 od is also supported: putting lists inside a blockquote will depart
5551 from the document default (that is, it will display incrementally with‐
5552 out the -i option and all at once with the -i option):
5553 > - Eat spaghetti
5555 > - Drink wine
5556 Both methods allow incremental and nonincremental lists to be mixed in
5558 a single document.
5559 If you want to include a block-quoted list, you can work around this
5561 behavior by putting the list inside a fenced div, so that it is not the
5562 direct child of the block quote:
5563 > ::: wrapper
5565 > - a
5566 > - list in a quote
5567 > :::
5568 Inserting pauses
5570 You can add “pauses” within a slide by including a paragraph containing
5571 three dots, separated by spaces:
5572 # Slide with a pause
5574 content before the pause
5576 . . .
5578 content after the pause
5580 Note: this feature is not yet implemented for PowerPoint output.
5582 Styling the slides
5584 You can change the style of HTML slides by putting customized CSS files
5585 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
5586 $DATADIR/slideous (for Slideous), where $DATADIR is the user data di‐
5587 rectory (see --data-dir, above). The originals may be found in pan‐
5588 doc’s system data directory (generally $CABALDIR/pandoc-VERSION/s5/de‐
5589 fault). Pandoc will look there for any files it does not find in the
5590 user data directory.
5591 For dzslides, the CSS is included in the HTML file itself, and may be
5593 modified there.
5594 All reveal.js configuration options can be set through variables. For
5596 example, themes can be used by setting the theme variable:
5597 -V theme=moon
5599 Or you can specify a custom stylesheet using the --css option.
5601 To style beamer slides, you can specify a theme, colortheme, fonttheme,
5603 innertheme, and outertheme, using the -V option:
5604 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
5606 Note that heading attributes will turn into slide attributes (on a
5608 <div> or <section>) in HTML slide formats, allowing you to style indi‐
5609 vidual slides. In beamer, a number of heading classes and attributes
5610 are recognized as frame options and will be passed through as options
5611 to the frame: see Frame attributes in beamer, below.
5612 Speaker notes
5614 Speaker notes are supported in reveal.js, PowerPoint (pptx), and beamer
5615 output. You can add notes to your Markdown document thus:
5616 ::: notes
5618 This is my note.
5620 - It can contain Markdown
5622 - like this list
5623 :::
5625 To show the notes window in reveal.js, press s while viewing the pre‐
5627 sentation. Speaker notes in PowerPoint will be available, as usual, in
5628 handouts and presenter view.
5629 Notes are not yet supported for other slide formats, but the notes will
5631 not appear on the slides themselves.
5632 Columns
5634 To put material in side by side columns, you can use a native div con‐
5635 tainer with class columns, containing two or more div containers with
5636 class column and a width attribute:
5637 :::::::::::::: {.columns}
5639 ::: {.column width="40%"}
5640 contents...
5641 :::
5642 ::: {.column width="60%"}
5643 contents...
5644 :::
5645 ::::::::::::::
5646 Additional columns attributes in beamer
5648 The div containers with classes columns and column can optionally have
5649 an align attribute. The class columns can optionally have a totalwidth
5650 attribute or an onlytextwidth class.
5651 :::::::::::::: {.columns align=center totalwidth=8em}
5653 ::: {.column width="40%"}
5654 contents...
5655 :::
5656 ::: {.column width="60%" align=bottom}
5657 contents...
5658 :::
5659 ::::::::::::::
5660 The align attributes on columns and column can be used with the values
5662 top, top-baseline, center and bottom to vertically align the columns.
5663 It defaults to top in columns.
5664 The totalwidth attribute limits the width of the columns to the given
5666 value.
5667 :::::::::::::: {.columns align=top .onlytextwidth}
5669 ::: {.column width="40%" align=center}
5670 contents...
5671 :::
5672 ::: {.column width="60%"}
5673 contents...
5674 :::
5675 ::::::::::::::
5676 The class onlytextwidth sets the totalwidth to \textwidth.
5678 See Section 12.7 of the Beamer User’s Guide for more details.
5680 Frame attributes in beamer
5682 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
5683 in beamer (for example, when using the minted environment). This can
5684 be forced by adding the fragile class to the heading introducing the
5685 slide:
5686 # Fragile slide {.fragile}
5688 All of the other frame attributes described in Section 8.1 of the Beam‐
5690 er User’s Guide may also be used: allowdisplaybreaks, allowframebreaks,
5691 b, c, s, t, environment, label, plain, shrink, standout, noframenumber‐
5692 ing, squeeze. allowframebreaks is recommended especially for bibli‐
5693 ographies, as it allows multiple slides to be created if the content
5694 overfills the frame:
5695 # References {.allowframebreaks}
5697 In addition, the frameoptions attribute may be used to pass arbitrary
5699 frame options to a beamer slide:
5700 # Heading {frameoptions="squeeze,shrink,customoption=foobar"}
5702 Background in reveal.js, beamer, and pptx
5704 Background images can be added to self-contained reveal.js slide shows,
5705 beamer slide shows, and pptx slide shows.
5706 On all slides (beamer, reveal.js, pptx)
5708 With beamer and reveal.js, the configuration option background-image
5709 can be used either in the YAML metadata block or as a command-line
5710 variable to get the same image on every slide.
5711 For pptx, you can use a reference doc in which background images have
5713 been set on the relevant layouts.
5714 parallaxBackgroundImage (reveal.js)
5716 For reveal.js, there is also the reveal.js-native option parallaxBack‐
5717 groundImage, which can be used instead of background-image to produce a
5718 parallax scrolling background. You must also set parallaxBackground‐
5719 Size, and can optionally set parallaxBackgroundHorizontal and paral‐
5720 laxBackgroundVertical to configure the scrolling behaviour. See the
5721 reveal.js documentation for more details about the meaning of these op‐
5722 tions.
5723 In reveal.js’s overview mode, the parallaxBackgroundImage will show up
5725 only on the first slide.
5726 On individual slides (reveal.js, pptx)
5728 To set an image for a particular reveal.js or pptx slide, add {back‐
5729 ground-image="/path/to/image"} to the first slide-level heading on the
5730 slide (which may even be empty).
5731 As the HTML writers pass unknown attributes through, other reveal.js
5733 background settings also work on individual slides, including back‐
5734 ground-size, background-repeat, background-color, transition, and tran‐
5735 sition-speed. (The data- prefix will automatically be added.)
5736 Note: data-background-image is also supported in pptx for consistency
5738 with reveal.js – if background-image isn’t found, data-background-image
5739 will be checked.
5740 On the title slide (reveal.js, pptx)
5742 To add a background image to the automatically generated title slide
5743 for reveal.js, use the title-slide-attributes variable in the YAML
5744 metadata block. It must contain a map of attribute names and values.
5745 (Note that the data- prefix is required here, as it isn’t added auto‐
5746 matically.)
5747 For pptx, pass a reference doc with the background image set on the
5749 “Title Slide” layout.
5750 Example (reveal.js)
5752 ---
5753 title: My Slide Show
5754 parallaxBackgroundImage: /path/to/my/background_image.png
5755 title-slide-attributes:
5756 data-background-image: /path/to/title_image.png
5757 data-background-size: contain
5758 ---
5759 ## Slide One
5761 Slide 1 has background_image.png as its background.
5763 ## {background-image="/path/to/special_image.jpg"}
5765 Slide 2 has a special image for its background, even though the heading has no content.
5767
5769 EPUB Metadata
5770 EPUB metadata may be specified using the --epub-metadata option, but if
5771 the source document is Markdown, it is better to use a YAML metadata
5772 block. Here is an example:
5773 ---
5775 title:
5776 - type: main
5777 text: My Book
5778 - type: subtitle
5779 text: An investigation of metadata
5780 creator:
5781 - role: author
5782 text: John Smith
5783 - role: editor
5784 text: Sarah Jones
5785 identifier:
5786 - scheme: DOI
5787 text: doi:10.234234.234/33
5788 publisher: My Press
5789 rights: © 2007 John Smith, CC BY-NC
5790 ibooks:
5791 version: 1.3.4
5792 ...
5793 The following fields are recognized:
5795 identifier
5797 Either a string value or an object with fields text and scheme.
5798 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
5799 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
5800 ISMN-13, ISBN-A, JP, OLCC.
5801 title Either a string value, or an object with fields file-as and
5803 type, or a list of such objects. Valid values for type are
5804 main, subtitle, short, collection, edition, extended.
5805 creator
5807 Either a string value, or an object with fields role, file-as,
5808 and text, or a list of such objects. Valid values for role are
5809 MARC relators, but pandoc will attempt to translate the human-
5810 readable versions (like “author” and “editor”) to the appropri‐
5811 ate marc relators.
5812 contributor
5814 Same format as creator.
5815 date A string value in YYYY-MM-DD format. (Only the year is neces‐
5817 sary.) Pandoc will attempt to convert other common date for‐
5818 mats.
5819 lang (or legacy: language)
5821 A string value in BCP 47 format. Pandoc will default to the lo‐
5822 cal language if nothing is specified.
5823 subject
5825 Either a string value, or an object with fields text, authority,
5826 and term, or a list of such objects. Valid values for authority
5827 are either a reserved authority value (currently AAT, BIC,
5828 BISAC, CLC, DDC, CLIL, EuroVoc, MEDTOP, LCSH, NDC, Thema, UDC,
5829 and WGS) or an absolute IRI identifying a custom scheme. Valid
5830 values for term are defined by the scheme.
5831 description
5833 A string value.
5834 type A string value.
5836 format A string value.
5838 relation
5840 A string value.
5841 coverage
5843 A string value.
5844 rights A string value.
5846 belongs-to-collection
5848 A string value. Identifies the name of a collection to which
5849 the EPUB Publication belongs.
5850 group-position
5852 The group-position field indicates the numeric position in which
5853 the EPUB Publication belongs relative to other works belonging
5854 to the same belongs-to-collection field.
5855 cover-image
5857 A string value (path to cover image).
5858 css (or legacy: stylesheet)
5860 A string value (path to CSS stylesheet).
5861 page-progression-direction
5863 Either ltr or rtl. Specifies the page-progression-direction at‐
5864 tribute for the spine element.
5865 ibooks iBooks-specific metadata, with the following fields:
5867 • version: (string)
5869 • specified-fonts: true|false (default false)
5871 • ipad-orientation-lock: portrait-only|landscape-only
5873 • iphone-orientation-lock: portrait-only|landscape-only
5875 • binding: true|false (default true)
5877 • scroll-axis: vertical|horizontal|default
5879 The epub:type attribute
5881 For epub3 output, you can mark up the heading that corresponds to an
5882 EPUB chapter using the epub:type attribute. For example, to set the
5883 attribute to the value prologue, use this markdown:
5884 # My chapter {epub:type=prologue}
5886 Which will result in:
5888 <body epub:type="frontmatter">
5890 <section epub:type="prologue">
5891 <h1>My chapter</h1>
5892 Pandoc will output <body epub:type="bodymatter">, unless you use one of
5894 the following values, in which case either frontmatter or backmatter
5895 will be output.
5896 epub:type of first section epub:type of body
5898 ---------------------------- -------------------
5899 prologue frontmatter
5900 abstract frontmatter
5901 acknowledgments frontmatter
5902 copyright-page frontmatter
5903 dedication frontmatter
5904 credits frontmatter
5905 keywords frontmatter
5906 imprint frontmatter
5907 contributors frontmatter
5908 other-credits frontmatter
5909 errata frontmatter
5910 revision-history frontmatter
5911 titlepage frontmatter
5912 halftitlepage frontmatter
5913 seriespage frontmatter
5914 foreword frontmatter
5915 preface frontmatter
5916 frontispiece frontmatter
5917 appendix backmatter
5918 colophon backmatter
5919 bibliography backmatter
5920 index backmatter
5921 Linked media
5923 By default, pandoc will download media referenced from any <img>, <au‐
5924 dio>, <video> or <source> element present in the generated EPUB, and
5925 include it in the EPUB container, yielding a completely self-contained
5926 EPUB. If you want to link to external media resources instead, use raw
5927 HTML in your source and add data-external="1" to the tag with the src
5928 attribute. For example:
5929 <audio controls="1">
5931 <source src="https://example.com/music/toccata.mp3"
5932 data-external="1" type="audio/mpeg">
5933 </source>
5934 </audio>
5935 If the input format already is HTML then data-external="1" will work as
5937 expected for <img> elements. Similarly, for Markdown, external images
5938 can be declared with {external=1}. Note that this only
5939 works for images; the other media elements have no native representa‐
5940 tion in pandoc’s AST and require the use of raw HTML.
5941 EPUB styling
5943 By default, pandoc will include some basic styling contained in its
5944 epub.css data file. (To see this, use pandoc --print-default-data-file
5945 epub.css.) To use a different CSS file, just use the --css command
5946 line option. A few inline styles are defined in addition; these are
5947 essential for correct formatting of pandoc’s HTML output.
5948 The document-css variable may be set if the more opinionated styling of
5950 pandoc’s default HTML templates is desired (and in that case the vari‐
5951 ables defined in Variables for HTML may be used to fine-tune the
5952 style).
5953
5955 When creating a Jupyter notebook, pandoc will try to infer the notebook
5956 structure. Code blocks with the class code will be taken as code
5957 cells, and intervening content will be taken as Markdown cells. At‐
5958 tachments will automatically be created for images in Markdown cells.
5959 Metadata will be taken from the jupyter metadata field. For example:
5960 ---
5962 title: My notebook
5963 jupyter:
5964 nbformat: 4
5965 nbformat_minor: 5
5966 kernelspec:
5967 display_name: Python 2
5968 language: python
5969 name: python2
5970 language_info:
5971 codemirror_mode:
5972 name: ipython
5973 version: 2
5974 file_extension: ".py"
5975 mimetype: "text/x-python"
5976 name: "python"
5977 nbconvert_exporter: "python"
5978 pygments_lexer: "ipython2"
5979 version: "2.7.15"
5980 ---
5981 # Lorem ipsum
5983 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5985 bibendum felis dictum sodales.
5986 ``` code
5988 print("hello")
5989 ```
5990 ## Pyout
5992 ``` code
5994 from IPython.display import HTML
5995 HTML("""
5996 <script>
5997 console.log("hello");
5998 </script>
5999 <b>HTML</b>
6000 """)
6001 ```
6002 ## Image
6004 This image  will be
6006 included as a cell attachment.
6007 If you want to add cell attributes, group cells differently, or add
6009 output to code cells, then you need to include divs to indicate the
6010 structure. You can use either fenced divs or native divs for this.
6011 Here is an example:
6012 :::::: {.cell .markdown}
6014 # Lorem
6015 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6017 bibendum felis dictum sodales.
6018 ::::::
6019 :::::: {.cell .code execution_count=1}
6021 ``` {.python}
6022 print("hello")
6023 ```
6024 ::: {.output .stream .stdout}
6026 ```
6027 hello
6028 ```
6029 :::
6030 ::::::
6031 :::::: {.cell .code execution_count=2}
6033 ``` {.python}
6034 from IPython.display import HTML
6035 HTML("""
6036 <script>
6037 console.log("hello");
6038 </script>
6039 <b>HTML</b>
6040 """)
6041 ```
6042 ::: {.output .execute_result execution_count=2}
6044 ```{=html}
6045 <script>
6046 console.log("hello");
6047 </script>
6048 <b>HTML</b>
6049 hello
6050 ```
6051 :::
6052 ::::::
6053 If you include raw HTML or TeX in an output cell, use the [raw attri‐
6055 bute][Extension: fenced_attribute], as shown in the last cell of the
6056 example above. Although pandoc can process “bare” raw HTML and TeX,
6057 the result is often interspersed raw elements and normal textual ele‐
6058 ments, and in an output cell pandoc expects a single, connected raw
6059 block. To avoid using raw HTML or TeX except when marked explicitly
6060 using raw attributes, we recommend specifying the extensions -raw_html-
6061 raw_tex+raw_attribute when translating between Markdown and ipynb note‐
6062 books.
6063 Note that options and extensions that affect reading and writing of
6065 Markdown will also affect Markdown cells in ipynb notebooks. For exam‐
6066 ple, --wrap=preserve will preserve soft line breaks in Markdown cells;
6067 --atx-headers will cause ATX-style headings to be used; and --preserve-
6068 tabs will prevent tabs from being turned to spaces.
6069
6071 Pandoc will automatically highlight syntax in fenced code blocks that
6072 are marked with a language name. The Haskell library skylighting is
6073 used for highlighting. Currently highlighting is supported only for
6074 HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language
6075 names that pandoc will recognize, type pandoc --list-highlight-lan‐
6076 guages.
6077 The color scheme can be selected using the --highlight-style option.
6079 The default color scheme is pygments, which imitates the default color
6080 scheme used by the Python library pygments (though pygments is not ac‐
6081 tually used to do the highlighting). To see a list of highlight
6082 styles, type pandoc --list-highlight-styles.
6083 If you are not satisfied with the predefined styles, you can use
6085 --print-highlight-style to generate a JSON .theme file which can be
6086 modified and used as the argument to --highlight-style. To get a JSON
6087 version of the pygments style, for example:
6088 pandoc --print-highlight-style pygments > my.theme
6090 Then edit my.theme and use it like this:
6092 pandoc --highlight-style my.theme
6094 If you are not satisfied with the built-in highlighting, or you want to
6096 highlight a language that isn’t supported, you can use the --syntax-
6097 definition option to load a KDE-style XML syntax definition file. Be‐
6098 fore writing your own, have a look at KDE’s repository of syntax defi‐
6099 nitions.
6100 To disable highlighting, use the --no-highlight option.
6102
6104 Custom styles can be used in the docx and ICML formats.
6105 Output
6107 By default, pandoc’s docx and ICML output applies a predefined set of
6108 styles for blocks such as paragraphs and block quotes, and uses largely
6109 default formatting (italics, bold) for inlines. This will work for
6110 most purposes, especially alongside a reference.docx file. However, if
6111 you need to apply your own styles to blocks, or match a preexisting set
6112 of styles, pandoc allows you to define custom styles for blocks and
6113 text using divs and spans, respectively.
6114 If you define a div or span with the attribute custom-style, pandoc
6116 will apply your specified style to the contained elements (with the ex‐
6117 ception of elements whose function depends on a style, like headings,
6118 code blocks, block quotes, or links). So, for example, using the
6119 bracketed_spans syntax,
6120 [Get out]{custom-style="Emphatically"}, he said.
6122 would produce a docx file with “Get out” styled with character style
6124 Emphatically. Similarly, using the fenced_divs syntax,
6125 Dickinson starts the poem simply:
6127 ::: {custom-style="Poetry"}
6129 | A Bird came down the Walk---
6130 | He did not know I saw---
6131 :::
6132 would style the two contained lines with the Poetry paragraph style.
6134 For docx output, styles will be defined in the output file as inherit‐
6136 ing from normal text, if the styles are not yet in your reference.docx.
6137 If they are already defined, pandoc will not alter the definition.
6138 This feature allows for greatest customization in conjunction with pan‐
6140 doc filters. If you want all paragraphs after block quotes to be in‐
6141 dented, you can write a filter to apply the styles necessary. If you
6142 want all italics to be transformed to the Emphasis character style
6143 (perhaps to change their color), you can write a filter which will
6144 transform all italicized inlines to inlines within an Emphasis custom-
6145 style span.
6146 For docx output, you don’t need to enable any extensions for custom
6148 styles to work.
6149 Input
6151 The docx reader, by default, only reads those styles that it can con‐
6152 vert into pandoc elements, either by direct conversion or interpreting
6153 the derivation of the input document’s styles.
6154 By enabling the styles extension in the docx reader (-f docx+styles),
6156 you can produce output that maintains the styles of the input document,
6157 using the custom-style class. Paragraph styles are interpreted as di‐
6158 vs, while character styles are interpreted as spans.
6159 For example, using the custom-style-reference.docx file in the test di‐
6161 rectory, we have the following different outputs:
6162 Without the +styles extension:
6164 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
6166 This is some text.
6167 This is text with an *emphasized* text style. And this is text with a
6169 **strengthened** text style.
6170 > Here is a styled paragraph that inherits from Block Text.
6172 And with the extension:
6174 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
6176 ::: {custom-style="First Paragraph"}
6178 This is some text.
6179 :::
6180 ::: {custom-style="Body Text"}
6182 This is text with an [emphasized]{custom-style="Emphatic"} text style.
6183 And this is text with a [strengthened]{custom-style="Strengthened"}
6184 text style.
6185 :::
6186 ::: {custom-style="My Block Style"}
6188 > Here is a styled paragraph that inherits from Block Text.
6189 :::
6190 With these custom styles, you can use your input document as a refer‐
6192 ence-doc while creating docx output (see below), and maintain the same
6193 styles in your input and output files.
6194
6196 Pandoc can be extended with custom readers and writers written in Lua.
6197 (Pandoc includes a Lua interpreter, so Lua need not be installed sepa‐
6198 rately.)
6199 To use a custom reader or writer, simply specify the path to the Lua
6201 script in place of the input or output format. For example:
6202 pandoc -t data/sample.lua
6204 pandoc -f my_custom_markup_language.lua -t latex -s
6205 If the script is not found relative to the working directory, it will
6207 be sought in the readers or writers subdirectory of the user data di‐
6208 rectory (see --data-dir).
6209 A custom reader is a Lua script that defines one function, Reader,
6211 which takes a string as input and returns a Pandoc AST. See the Lua
6212 filters documentation for documentation of the functions that are
6213 available for creating pandoc AST elements. For parsing, the lpeg
6214 parsing library is available by default. To see a sample custom read‐
6215 er:
6216 pandoc --print-default-data-file creole.lua
6218 If you want your custom reader to have access to reader options
6220 (e.g. the tab stop setting), you give your Reader function a second op‐
6221 tions parameter.
6222 A custom writer is a Lua script that defines a function that specifies
6224 how to render each element in a Pandoc AST. To see a documented exam‐
6225 ple which you can modify according to your needs:
6226 pandoc --print-default-data-file sample.lua
6228 Note that custom writers have no default template. If you want to use
6230 --standalone with a custom writer, you will need to specify a template
6231 manually using --template or add a new default template with the name
6232 default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your
6233 user data directory (see Templates).
6234
6236 Some of the document formats pandoc targets (such as EPUB, docx, and
6237 ODT) include build timestamps in the generated document. That means
6238 that the files generated on successive builds will differ, even if the
6239 source does not. To avoid this, set the SOURCE_DATE_EPOCH environment
6240 variable, and the timestamp will be taken from it instead of the cur‐
6241 rent time. SOURCE_DATE_EPOCH should contain an integer unix timestamp
6242 (specifying the number of seconds since midnight UTC January 1, 1970).
6243 Some document formats also include a unique identifier. For EPUB, this
6245 can be set explicitly by setting the identifier metadata field (see
6246 EPUB Metadata, above).
6247
6249 If you rename (or symlink) the pandoc executable to pandoc-server, it
6250 will start up a web server with a JSON API. This server exposes most
6251 of the conversion functionality of pandoc. For full documentation, see
6252 the pandoc-server man page.
6253 If you rename (or symlink) the pandoc executable to pandoc-server.cgi,
6255 it will function as a CGI program exposing the same API as pandoc-serv‐
6256 er.
6257 pandoc-server is designed to be maximally secure; it uses Haskell’s
6259 type system to provide strong guarantees that no I/O will be performed
6260 on the server during pandoc conversions.
6261
6263 1. Although pandoc itself will not create or modify any files other
6264 than those you explicitly ask it create (with the exception of tem‐
6265 porary files used in producing PDFs), a filter or custom writer
6266 could in principle do anything on your file system. Please audit
6267 filters and custom writers very carefully before using them.
6268 2. Several input formats (including HTML, Org, and RST) support include
6270 directives that allow the contents of a file to be included in the
6271 output. An untrusted attacker could use these to view the contents
6272 of files on the file system. (Using the --sandbox option can pro‐
6273 tect against this threat.)
6274 3. Several output formats (including RTF, FB2, HTML with --self-con‐
6276 tained, EPUB, Docx, and ODT) will embed encoded or raw images into
6277 the output file. An untrusted attacker could exploit this to view
6278 the contents of non-image files on the file system. (Using the
6279 --sandbox option can protect against this threat, but will also pre‐
6280 vent including images in these formats.)
6281 4. If your application uses pandoc as a Haskell library (rather than
6283 shelling out to the executable), it is possible to use it in a mode
6284 that fully isolates pandoc from your file system, by running the
6285 pandoc operations in the PandocPure monad. See the document Using
6286 the pandoc API for more details. (This corresponds to the use of
6287 the --sandbox option on the command line.)
6288 5. Pandoc’s parsers can exhibit pathological performance on some corner
6290 cases. It is wise to put any pandoc operations under a timeout, to
6291 avoid DOS attacks that exploit these issues. If you are using the
6292 pandoc executable, you can add the command line options +RTS -M512M
6293 -RTS (for example) to limit the heap size to 512MB. Note that the
6294 commonmark parser (including commonmark_x and gfm) is much less vul‐
6295 nerable to pathological performance than the markdown parser, so it
6296 is a better choice when processing untrusted input.
6297 6. The HTML generated by pandoc is not guaranteed to be safe. If
6299 raw_html is enabled for the Markdown input, users can inject arbi‐
6300 trary HTML. Even if raw_html is disabled, users can include danger‐
6301 ous content in URLs and attributes. To be safe, you should run all
6302 HTML generated from untrusted user input through an HTML sanitizer.
6303
6305 Copyright 2006–2022 John MacFarlane (jgm@berkeley.edu). Released under
6306 the GPL, version 2 or greater. This software carries no warranty of
6307 any kind. (See COPYRIGHT for full copyright and warranty notices.)
6308 For a full list of contributors, see the file AUTHORS.md in the pandoc
6309 source code.
6310 The Pandoc source code may be downloaded from <https://hack‐
6312 age.haskell.org/package/pandoc> or <https://github.com/jgm/pandoc/re‐
6313 leases>. Further documentation is available at <https://pandoc.org>.
6314pandoc 2.19.2 August 22, 2022 Pandoc User’s Guide()