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, soul, 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 • typst (typst)
248 • vimwiki (Vimwiki)
250 • the path of a custom Lua reader, see Custom readers and writ‐
252 ers below
253 Extensions can be individually enabled or disabled by appending
255 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
256 low, for a list of extensions and their names. See --list-in‐
257 put-formats and --list-extensions, below.
258 -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
260 Specify output format. FORMAT can be:
261 • asciidoc (AsciiDoc) or asciidoctor (AsciiDoctor)
263 • beamer (LaTeX beamer slide show)
265 • bibtex (BibTeX bibliography)
267 • biblatex (BibLaTeX bibliography)
269 • chunkedhtml (zip archive of multiple linked HTML files)
271 • commonmark (CommonMark Markdown)
273 • commonmark_x (CommonMark Markdown with extensions)
275 • context (ConTeXt)
277 • csljson (CSL JSON bibliography)
279 • docbook or docbook4 (DocBook 4)
281 • docbook5 (DocBook 5)
283 • docx (Word docx)
285 • dokuwiki (DokuWiki markup)
287 • epub or epub3 (EPUB v3 book)
289 • epub2 (EPUB v2)
291 • fb2 (FictionBook2 e-book)
293 • gfm (GitHub-Flavored Markdown), or the deprecated and less ac‐
295 curate markdown_github; use markdown_github only if you need
296 extensions not supported in gfm.
297 • haddock (Haddock markup)
299 • html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
301 • html4 (XHTML 1.0 Transitional)
303 • icml (InDesign ICML)
305 • ipynb (Jupyter notebook)
307 • jats_archiving (JATS XML, Archiving and Interchange Tag Set)
309 • jats_articleauthoring (JATS XML, Article Authoring Tag Set)
311 • jats_publishing (JATS XML, Journal Publishing Tag Set)
313 • jats (alias for jats_archiving)
315 • jira (Jira/Confluence wiki markup)
317 • json (JSON version of native AST)
319 • latex (LaTeX)
321 • man (roff man)
323 • markdown (Pandoc’s Markdown)
325 • markdown_mmd (MultiMarkdown)
327 • markdown_phpextra (PHP Markdown Extra)
329 • markdown_strict (original unextended Markdown)
331 • markua (Markua)
333 • mediawiki (MediaWiki markup)
335 • ms (roff ms)
337 • muse (Muse)
339 • native (native Haskell)
341 • odt (OpenOffice text document)
343 • opml (OPML)
345 • opendocument (OpenDocument)
347 • org (Emacs Org mode)
349 • pdf (PDF)
351 • plain (plain text)
353 • pptx (PowerPoint slide show)
355 • rst (reStructuredText)
357 • rtf (Rich Text Format)
359 • texinfo (GNU Texinfo)
361 • textile (Textile)
363 • slideous (Slideous HTML and JavaScript slide show)
365 • slidy (Slidy HTML and JavaScript slide show)
367 • dzslides (DZSlides HTML5 + JavaScript slide show)
369 • revealjs (reveal.js HTML5 + JavaScript slide show)
371 • s5 (S5 HTML and JavaScript slide show)
373 • tei (TEI Simple)
375 • typst (typst)
377 • xwiki (XWiki markup)
379 • zimwiki (ZimWiki markup)
381 • the path of a custom Lua writer, see Custom readers and writ‐
383 ers below
384 Note that odt, docx, epub, and pdf output will not be directed
386 to stdout unless forced with -o -.
387 Extensions can be individually enabled or disabled by appending
389 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
390 low, for a list of extensions and their names. See --list-out‐
391 put-formats and --list-extensions, below.
392 -o FILE, --output=FILE
394 Write output to FILE instead of stdout. If FILE is -, output
395 will go to stdout, even if a non-textual format (docx, odt,
396 epub2, epub3) is specified. If the output format is chunkedhtml
397 and FILE has no extension, then instead of producing a .zip file
398 pandoc will create a directory FILE and unpack the zip archive
399 there (unless FILE already exists, in which case an error will
400 be raised).
401 --data-dir=DIRECTORY
403 Specify the user data directory to search for pandoc data files.
404 If this option is not specified, the default user data directory
405 will be used. On *nix and macOS systems this will be the pandoc
406 subdirectory of the XDG data directory (by default, $HOME/.lo‐
407 cal/share, overridable by setting the XDG_DATA_HOME environment
408 variable). If that directory does not exist and $HOME/.pandoc
409 exists, it will be used (for backwards compatibility). On Win‐
410 dows the default user data directory is %APPDATA%\pandoc. You
411 can find the default user data directory on your system by look‐
412 ing at the output of pandoc --version. Data files placed in
413 this directory (for example, reference.odt, reference.docx,
414 epub.css, templates) will override pandoc’s normal defaults.
415 (Note that the user data directory is not created by pandoc, so
416 you will need to create it yourself if you want to make use of
417 it.)
418 -d FILE, --defaults=FILE
420 Specify a set of default option settings. FILE is a YAML file
421 whose fields correspond to command-line option settings. All
422 options for document conversion, including input and output
423 files, can be set using a defaults file. The file will be
424 searched for first in the working directory, and then in the de‐
425 faults subdirectory of the user data directory (see --data-dir).
426 The .yaml extension may be omitted. See the section Defaults
427 files for more information on the file format. Settings from
428 the defaults file may be overridden or extended by subsequent
429 options on the command line.
430 --bash-completion
432 Generate a bash completion script. To enable bash completion
433 with pandoc, add this to your .bashrc:
434 eval "$(pandoc --bash-completion)"
436 --verbose
438 Give verbose debugging output.
439 --quiet
441 Suppress warning messages.
442 --fail-if-warnings
444 Exit with error status if there are any warnings.
445 --log=FILE
447 Write log messages in machine-readable JSON format to FILE. All
448 messages above DEBUG level will be written, regardless of ver‐
449 bosity settings (--verbose, --quiet).
450 --list-input-formats
452 List supported input formats, one per line.
453 --list-output-formats
455 List supported output formats, one per line.
456 --list-extensions[=FORMAT]
458 List supported extensions for FORMAT, one per line, preceded by
459 a + or - indicating whether it is enabled by default in FORMAT.
460 If FORMAT is not specified, defaults for pandoc’s Markdown are
461 given.
462 --list-highlight-languages
464 List supported languages for syntax highlighting, one per line.
465 --list-highlight-styles
467 List supported styles for syntax highlighting, one per line.
468 See --highlight-style.
469 -v, --version
471 Print version.
472 -h, --help
474 Show usage message.
475 Reader options
477 --shift-heading-level-by=NUMBER
478 Shift heading levels by a positive or negative integer. For ex‐
479 ample, with --shift-heading-level-by=-1, level 2 headings become
480 level 1 headings, and level 3 headings become level 2 headings.
481 Headings cannot have a level less than 1, so a heading that
482 would be shifted below level 1 becomes a regular paragraph. Ex‐
483 ception: with a shift of -N, a level-N heading at the beginning
484 of the document replaces the metadata title. --shift-heading-
485 level-by=-1 is a good choice when converting HTML or Markdown
486 documents that use an initial level-1 heading for the document
487 title and level-2+ headings for sections. --shift-heading-lev‐
488 el-by=1 may be a good choice for converting Markdown documents
489 that use level-1 headings for sections to HTML, since pandoc us‐
490 es a level-1 heading to render the document title.
491 --base-header-level=NUMBER
493 Deprecated. Use --shift-heading-level-by=X instead, where X =
494 NUMBER - 1. Specify the base level for headings (defaults to 1).
495 --indented-code-classes=CLASSES
497 Specify classes to use for indented code blocks–for example,
498 perl,numberLines or haskell. Multiple classes may be separated
499 by spaces or commas.
500 --default-image-extension=EXTENSION
502 Specify a default extension to use when image paths/URLs have no
503 extension. This allows you to use the same source for formats
504 that require different kinds of images. Currently this option
505 only affects the Markdown and LaTeX readers.
506 --file-scope
508 Parse each file individually before combining for multifile doc‐
509 uments. This will allow footnotes in different files with the
510 same identifiers to work as expected. If this option is set,
511 footnotes and links will not work across files. Reading binary
512 files (docx, odt, epub) implies --file-scope.
513 If two or more files are processed using --file-scope, prefixes
515 based on the filenames will be added to identifiers in order to
516 disambiguate them, and internal links will be adjusted accord‐
517 ingly. For example, a header with identifier foo in sub‐
518 dir/file1.txt will have its identifier changed to sub‐
519 dir__file1.txt__foo.
520 In addition, a Div with an identifier based on the filename will
522 be added around the file’s content, so that internal links to
523 the filename will point to this Div’s identifier.
524 -F PROGRAM, --filter=PROGRAM
526 Specify an executable to be used as a filter transforming the
527 pandoc AST after the input is parsed and before the output is
528 written. The executable should read JSON from stdin and write
529 JSON to stdout. The JSON must be formatted like pandoc’s own
530 JSON input and output. The name of the output format will be
531 passed to the filter as the first argument. Hence,
532 pandoc --filter ./caps.py -t latex
534 is equivalent to
536 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
538 The latter form may be useful for debugging filters.
540 Filters may be written in any language. Text.Pandoc.JSON ex‐
542 ports toJSONFilter to facilitate writing filters in Haskell.
543 Those who would prefer to write filters in python can use the
544 module pandocfilters, installable from PyPI. There are also
545 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
546 In order of preference, pandoc will look for filters in
548 1. a specified full or relative path (executable or non-exe‐
550 cutable),
551 2. $DATADIR/filters (executable or non-executable) where
553 $DATADIR is the user data directory (see --data-dir, above),
554 3. $PATH (executable only).
556 Filters, Lua-filters, and citeproc processing are applied in the
558 order specified on the command line.
559 -L SCRIPT, --lua-filter=SCRIPT
561 Transform the document in a similar fashion as JSON filters (see
562 --filter), but use pandoc’s built-in Lua filtering system. The
563 given Lua script is expected to return a list of Lua filters
564 which will be applied in order. Each Lua filter must contain
565 element-transforming functions indexed by the name of the AST
566 element on which the filter function should be applied.
567 The pandoc Lua module provides helper functions for element cre‐
569 ation. It is always loaded into the script’s Lua environment.
570 See the Lua filters documentation for further details.
572 In order of preference, pandoc will look for Lua filters in
574 1. a specified full or relative path,
576 2. $DATADIR/filters where $DATADIR is the user data directory
578 (see --data-dir, above).
579 Filters, Lua filters, and citeproc processing are applied in the
581 order specified on the command line.
582 -M KEY[=VAL], --metadata=KEY[:VAL]
584 Set the metadata field KEY to the value VAL. A value specified
585 on the command line overrides a value specified in the document
586 using YAML metadata blocks. Values will be parsed as YAML bool‐
587 ean or string values. If no value is specified, the value will
588 be treated as Boolean true. Like --variable, --metadata causes
589 template variables to be set. But unlike --variable, --metadata
590 affects the metadata of the underlying document (which is acces‐
591 sible from filters and may be printed in some output formats)
592 and metadata values will be escaped when inserted into the tem‐
593 plate.
594 --metadata-file=FILE
596 Read metadata from the supplied YAML (or JSON) file. This op‐
597 tion can be used with every input format, but string scalars in
598 the metadata file will always be parsed as Markdown. (If the
599 input format is Markdown or a Markdown variant, then the same
600 variant will be used to parse the metadata file; if it is a non-
601 Markdown format, pandoc’s default Markdown extensions will be
602 used.) This option can be used repeatedly to include multiple
603 metadata files; values in files specified later on the command
604 line will be preferred over those specified in earlier files.
605 Metadata values specified inside the document, or by using -M,
606 overwrite values specified with this option. The file will be
607 searched for first in the working directory, and then in the
608 metadata subdirectory of the user data directory (see --data-
609 dir).
610 -p, --preserve-tabs
612 Preserve tabs instead of converting them to spaces. (By de‐
613 fault, pandoc converts tabs to spaces before parsing its input.)
614 Note that this will only affect tabs in literal code spans and
615 code blocks. Tabs in regular text are always treated as spaces.
616 --tab-stop=NUMBER
618 Specify the number of spaces per tab (default is 4).
619 --track-changes=accept|reject|all
621 Specifies what to do with insertions, deletions, and comments
622 produced by the MS Word “Track Changes” feature. accept (the
623 default) processes all the insertions and deletions. reject ig‐
624 nores them. Both accept and reject ignore comments. all in‐
625 cludes all insertions, deletions, and comments, wrapped in spans
626 with insertion, deletion, comment-start, and comment-end class‐
627 es, respectively. The author and time of change is included.
628 all is useful for scripting: only accepting changes from a cer‐
629 tain reviewer, say, or before a certain date. If a paragraph is
630 inserted or deleted, track-changes=all produces a span with the
631 class paragraph-insertion/paragraph-deletion before the affected
632 paragraph break. This option only affects the docx reader.
633 --extract-media=DIR
635 Extract images and other media contained in or linked from the
636 source document to the path DIR, creating it if necessary, and
637 adjust the images references in the document so they point to
638 the extracted files. Media are downloaded, read from the file
639 system, or extracted from a binary container (e.g. docx), as
640 needed. The original file paths are used if they are relative
641 paths not containing ... Otherwise filenames are constructed
642 from the SHA1 hash of the contents.
643 --abbreviations=FILE
645 Specifies a custom abbreviations file, with abbreviations one to
646 a line. If this option is not specified, pandoc will read the
647 data file abbreviations from the user data directory or fall
648 back on a system default. To see the system default, use pandoc
649 --print-default-data-file=abbreviations. The only use pandoc
650 makes of this list is in the Markdown reader. Strings found in
651 this list will be followed by a nonbreaking space, and the peri‐
652 od will not produce sentence-ending space in formats like LaTeX.
653 The strings may not contain spaces.
654 --trace
656 Print diagnostic output tracing parser progress to stderr. This
657 option is intended for use by developers in diagnosing perfor‐
658 mance issues.
659 General writer options
661 -s, --standalone
662 Produce output with an appropriate header and footer (e.g. a
663 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
664 option is set automatically for pdf, epub, epub3, fb2, docx, and
665 odt output. For native output, this option causes metadata to
666 be included; otherwise, metadata is suppressed.
667 --template=FILE|URL
669 Use the specified file as a custom template for the generated
670 document. Implies --standalone. See Templates, below, for a
671 description of template syntax. If no extension is specified,
672 an extension corresponding to the writer will be added, so that
673 --template=special looks for special.html for HTML output. If
674 the template is not found, pandoc will search for it in the tem‐
675 plates subdirectory of the user data directory (see --data-dir).
676 If this option is not used, a default template appropriate for
677 the output format will be used (see -D/--print-default-tem‐
678 plate).
679 -V KEY[=VAL], --variable=KEY[:VAL]
681 Set the template variable KEY to the value VAL when rendering
682 the document in standalone mode. If no VAL is specified, the
683 key will be given the value true.
684 --sandbox
686 Run pandoc in a sandbox, limiting IO operations in readers and
687 writers to reading the files specified on the command line.
688 Note that this option does not limit IO operations by filters or
689 in the production of PDF documents. But it does offer security
690 against, for example, disclosure of files through the use of in‐
691 clude directives. Anyone using pandoc on untrusted user input
692 should use this option.
693 Note: some readers and writers (e.g., docx) need access to data
695 files. If these are stored on the file system, then pandoc will
696 not be able to find them when run in --sandbox mode and will
697 raise an error. For these applications, we recommend using a
698 pandoc binary compiled with the embed_data_files option, which
699 causes the data files to be baked into the binary instead of be‐
700 ing stored on the file system.
701 -D FORMAT, --print-default-template=FORMAT
703 Print the system default template for an output FORMAT. (See -t
704 for a list of possible FORMATs.) Templates in the user data di‐
705 rectory are ignored. This option may be used with -o/--output
706 to redirect output to a file, but -o/--output must come before
707 --print-default-template on the command line.
708 Note that some of the default templates use partials, for exam‐
710 ple styles.html. To print the partials, use --print-default-da‐
711 ta-file: for example, --print-default-data-file=tem‐
712 plates/styles.html.
713 --print-default-data-file=FILE
715 Print a system default data file. Files in the user data direc‐
716 tory are ignored. This option may be used with -o/--output to
717 redirect output to a file, but -o/--output must come before
718 --print-default-data-file on the command line.
719 --eol=crlf|lf|native
721 Manually specify line endings: crlf (Windows), lf (macOS/Lin‐
722 ux/UNIX), or native (line endings appropriate to the OS on which
723 pandoc is being run). The default is native.
724 --dpi=NUMBER
726 Specify the default dpi (dots per inch) value for conversion
727 from pixels to inch/centimeters and vice versa. (Technically,
728 the correct term would be ppi: pixels per inch.) The default is
729 96dpi. When images contain information about dpi internally,
730 the encoded value is used instead of the default specified by
731 this option.
732 --wrap=auto|none|preserve
734 Determine how text is wrapped in the output (the source code,
735 not the rendered version). With auto (the default), pandoc will
736 attempt to wrap lines to the column width specified by --columns
737 (default 72). With none, pandoc will not wrap lines at all.
738 With preserve, pandoc will attempt to preserve the wrapping from
739 the source document (that is, where there are nonsemantic new‐
740 lines in the source, there will be nonsemantic newlines in the
741 output as well). In ipynb output, this option affects wrapping
742 of the contents of markdown cells.
743 --columns=NUMBER
745 Specify length of lines in characters. This affects text wrap‐
746 ping in the generated source code (see --wrap). It also affects
747 calculation of column widths for plain text tables (see Tables
748 below).
749 --toc, --table-of-contents
751 Include an automatically generated table of contents (or, in the
752 case of latex, context, docx, odt, opendocument, rst, or ms, an
753 instruction to create one) in the output document. This option
754 has no effect unless -s/--standalone is used, and it has no ef‐
755 fect on man, docbook4, docbook5, or jats output.
756 Note that if you are producing a PDF via ms, the table of con‐
758 tents will appear at the beginning of the document, before the
759 title. If you would prefer it to be at the end of the document,
760 use the option --pdf-engine-opt=--no-toc-relocation.
761 --toc-depth=NUMBER
763 Specify the number of section levels to include in the table of
764 contents. The default is 3 (which means that level-1, 2, and 3
765 headings will be listed in the contents).
766 --strip-comments
768 Strip out HTML comments in the Markdown or Textile source,
769 rather than passing them on to Markdown, Textile or HTML output
770 as raw HTML. This does not apply to HTML comments inside raw
771 HTML blocks when the markdown_in_html_blocks extension is not
772 set.
773 --no-highlight
775 Disables syntax highlighting for code blocks and inlines, even
776 when a language attribute is given.
777 --highlight-style=STYLE|FILE
779 Specifies the coloring style to be used in highlighted source
780 code. Options are pygments (the default), kate, monochrome,
781 breezeDark, espresso, zenburn, haddock, and tango. For more in‐
782 formation on syntax highlighting in pandoc, see Syntax high‐
783 lighting, below. See also --list-highlight-styles.
784 Instead of a STYLE name, a JSON file with extension .theme may
786 be supplied. This will be parsed as a KDE syntax highlighting
787 theme and (if valid) used as the highlighting style.
788 To generate the JSON version of an existing style, use --print-
790 highlight-style.
791 --print-highlight-style=STYLE|FILE
793 Prints a JSON version of a highlighting style, which can be mod‐
794 ified, saved with a .theme extension, and used with --highlight-
795 style. This option may be used with -o/--output to redirect
796 output to a file, but -o/--output must come before --print-high‐
797 light-style on the command line.
798 --syntax-definition=FILE
800 Instructs pandoc to load a KDE XML syntax definition file, which
801 will be used for syntax highlighting of appropriately marked
802 code blocks. This can be used to add support for new languages
803 or to use altered syntax definitions for existing languages.
804 This option may be repeated to add multiple syntax definitions.
805 -H FILE, --include-in-header=FILE|URL
807 Include contents of FILE, verbatim, at the end of the header.
808 This can be used, for example, to include special CSS or Java‐
809 Script in HTML documents. This option can be used repeatedly to
810 include multiple files in the header. They will be included in
811 the order specified. Implies --standalone.
812 -B FILE, --include-before-body=FILE|URL
814 Include contents of FILE, verbatim, at the beginning of the doc‐
815 ument body (e.g. after the <body> tag in HTML, or the \be‐
816 gin{document} command in LaTeX). This can be used to include
817 navigation bars or banners in HTML documents. This option can
818 be used repeatedly to include multiple files. They will be in‐
819 cluded in the order specified. Implies --standalone.
820 -A FILE, --include-after-body=FILE|URL
822 Include contents of FILE, verbatim, at the end of the document
823 body (before the </body> tag in HTML, or the \end{document} com‐
824 mand in LaTeX). This option can be used repeatedly to include
825 multiple files. They will be included in the order specified.
826 Implies --standalone.
827 --resource-path=SEARCHPATH
829 List of paths to search for images and other resources. The
830 paths should be separated by : on Linux, UNIX, and macOS sys‐
831 tems, and by ; on Windows. If --resource-path is not specified,
832 the default resource path is the working directory. Note that,
833 if --resource-path is specified, the working directory must be
834 explicitly listed or it will not be searched. For example:
835 --resource-path=.:test will search the working directory and the
836 test subdirectory, in that order. This option can be used re‐
837 peatedly. Search path components that come later on the command
838 line will be searched before those that come earlier, so --re‐
839 source-path foo:bar --resource-path baz:bim is equivalent to
840 --resource-path baz:bim:foo:bar.
841 --request-header=NAME:VAL
843 Set the request header NAME to the value VAL when making HTTP
844 requests (for example, when a URL is given on the command line,
845 or when resources used in a document must be downloaded). If
846 you’re behind a proxy, you also need to set the environment
847 variable http_proxy to http://....
848 --no-check-certificate
850 Disable the certificate verification to allow access to unsecure
851 HTTP resources (for example when the certificate is no longer
852 valid or self signed).
853 Options affecting specific writers
855 --self-contained
856 Deprecated synonym for --embed-resources --standalone.
857 --embed-resources
859 Produce a standalone HTML file with no external dependencies,
860 using data: URIs to incorporate the contents of linked scripts,
861 stylesheets, images, and videos. The resulting file should be
862 “self-contained,” in the sense that it needs no external files
863 and no net access to be displayed properly by a browser. This
864 option works only with HTML output formats, including html4,
865 html5, html+lhs, html5+lhs, s5, slidy, slideous, dzslides, and
866 revealjs. Scripts, images, and stylesheets at absolute URLs
867 will be downloaded; those at relative URLs will be sought rela‐
868 tive to the working directory (if the first source file is lo‐
869 cal) or relative to the base URL (if the first source file is
870 remote). Elements with the attribute data-external="1" will be
871 left alone; the documents they link to will not be incorporated
872 in the document. Limitation: resources that are loaded dynami‐
873 cally through JavaScript cannot be incorporated; as a result,
874 fonts may be missing when --mathjax is used, and some advanced
875 features (e.g. zoom or speaker notes) may not work in an offline
876 “self-contained” reveal.js slide show.
877 --html-q-tags
879 Use <q> tags for quotes in HTML. (This option only has an ef‐
880 fect if the smart extension is enabled for the input format
881 used.)
882 --ascii
884 Use only ASCII characters in output. Currently supported for
885 XML and HTML formats (which use entities instead of UTF-8 when
886 this option is selected), CommonMark, gfm, and Markdown (which
887 use entities), roff man and ms (which use hexadecimal escapes),
888 and to a limited degree LaTeX (which uses standard commands for
889 accented characters when possible).
890 --reference-links
892 Use reference-style links, rather than inline links, in writing
893 Markdown or reStructuredText. By default inline links are used.
894 The placement of link references is affected by the --reference-
895 location option.
896 --reference-location=block|section|document
898 Specify whether footnotes (and references, if reference-links is
899 set) are placed at the end of the current (top-level) block, the
900 current section, or the document. The default is document.
901 Currently this option only affects the markdown, muse, html,
902 epub, slidy, s5, slideous, dzslides, and revealjs writers. In
903 slide formats, specifying --reference-location=section will
904 cause notes to be rendered at the bottom of a slide.
905 --markdown-headings=setext|atx
907 Specify whether to use ATX-style (#-prefixed) or Setext-style
908 (underlined) headings for level 1 and 2 headings in Markdown
909 output. (The default is atx.) ATX-style headings are always
910 used for levels 3+. This option also affects Markdown cells in
911 ipynb output.
912 --list-tables
914 Render tables as list tables in RST output.
915 --top-level-division=default|section|chapter|part
917 Treat top-level headings as the given division type in LaTeX,
918 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
919 chapter, then section; all headings are shifted such that the
920 top-level heading becomes the specified type. The default be‐
921 havior is to determine the best division type via heuristics:
922 unless other conditions apply, section is chosen. When the doc‐
923 umentclass variable is set to report, book, or memoir (unless
924 the article option is specified), chapter is implied as the set‐
925 ting for this option. If beamer is the output format, specify‐
926 ing either chapter or part will cause top-level headings to be‐
927 come \part{..}, while second-level headings remain as their de‐
928 fault type.
929 -N, --number-sections
931 Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or
932 EPUB output. By default, sections are not numbered. Sections
933 with class unnumbered will never be numbered, even if --number-
934 sections is specified.
935 --number-offset=NUMBER[,NUMBER,...]
937 Offset for section headings in HTML output (ignored in other
938 output formats). The first number is added to the section num‐
939 ber for top-level headings, the second for second-level head‐
940 ings, and so on. So, for example, if you want the first top-
941 level heading in your document to be numbered “6”, specify
942 --number-offset=5. If your document starts with a level-2 head‐
943 ing which you want to be numbered “1.5”, specify --number-off‐
944 set=1,4. Offsets are 0 by default. Implies --number-sections.
945 --listings
947 Use the listings package for LaTeX code blocks. The package
948 does not support multi-byte encoding for source code. To handle
949 UTF-8 you would need to use a custom template. This issue is
950 fully documented here: Encoding issue with the listings package.
951 -i, --incremental
953 Make list items in slide shows display incrementally (one by
954 one). The default is for lists to be displayed all at once.
955 --slide-level=NUMBER
957 Specifies that headings with the specified level create slides
958 (for beamer, s5, slidy, slideous, dzslides). Headings above
959 this level in the hierarchy are used to divide the slide show
960 into sections; headings below this level create subheads within
961 a slide. Valid values are 0-6. If a slide level of 0 is speci‐
962 fied, slides will not be split automatically on headings, and
963 horizontal rules must be used to indicate slide boundaries. If
964 a slide level is not specified explicitly, the slide level will
965 be set automatically based on the contents of the document; see
966 Structuring the slide show.
967 --section-divs
969 Wrap sections in <section> tags (or <div> tags for html4), and
970 attach identifiers to the enclosing <section> (or <div>) rather
971 than the heading itself. See Heading identifiers, below.
972 --email-obfuscation=none|javascript|references
974 Specify a method for obfuscating mailto: links in HTML docu‐
975 ments. none leaves mailto: links as they are. javascript ob‐
976 fuscates them using JavaScript. references obfuscates them by
977 printing their letters as decimal or hexadecimal character ref‐
978 erences. The default is none.
979 --id-prefix=STRING
981 Specify a prefix to be added to all identifiers and internal
982 links in HTML and DocBook output, and to footnote numbers in
983 Markdown and Haddock output. This is useful for preventing du‐
984 plicate identifiers when generating fragments to be included in
985 other pages.
986 -T STRING, --title-prefix=STRING
988 Specify STRING as a prefix at the beginning of the title that
989 appears in the HTML header (but not in the title as it appears
990 at the beginning of the HTML body). Implies --standalone.
991 -c URL, --css=URL
993 Link to a CSS style sheet. This option can be used repeatedly
994 to include multiple files. They will be included in the order
995 specified. This option only affects HTML (including HTML slide
996 shows) and EPUB output. It should be used together with
997 -s/--standalone, because the link to the stylesheet goes in the
998 document header.
999 A stylesheet is required for generating EPUB. If none is pro‐
1001 vided using this option (or the css or stylesheet metadata
1002 fields), pandoc will look for a file epub.css in the user data
1003 directory (see --data-dir). If it is not found there, sensible
1004 defaults will be used.
1005 --reference-doc=FILE|URL
1007 Use the specified file as a style reference in producing a docx
1008 or ODT file.
1009 Docx For best results, the reference docx should be a modified
1011 version of a docx file produced using pandoc. The con‐
1012 tents of the reference docx are ignored, but its
1013 stylesheets and document properties (including margins,
1014 page size, header, and footer) are used in the new docx.
1015 If no reference docx is specified on the command line,
1016 pandoc will look for a file reference.docx in the user
1017 data directory (see --data-dir). If this is not found
1018 either, sensible defaults will be used.
1019 To produce a custom reference.docx, first get a copy of
1021 the default reference.docx: pandoc -o custom-refer‐
1022 ence.docx --print-default-data-file reference.docx. Then
1023 open custom-reference.docx in Word, modify the styles as
1024 you wish, and save the file. For best results, do not
1025 make changes to this file other than modifying the styles
1026 used by pandoc:
1027 Paragraph styles:
1029 • Normal
1031 • Body Text
1033 • First Paragraph
1035 • Compact
1037 • Title
1039 • Subtitle
1041 • Author
1043 • Date
1045 • Abstract
1047 • AbstractTitle
1049 • Bibliography
1051 • Heading 1
1053 • Heading 2
1055 • Heading 3
1057 • Heading 4
1059 • Heading 5
1061 • Heading 6
1063 • Heading 7
1065 • Heading 8
1067 • Heading 9
1069 • Block Text
1071 • Source Code
1073 • Footnote Text
1075 • Definition Term
1077 • Definition
1079 • Caption
1081 • Table Caption
1083 • Image Caption
1085 • Figure
1087 • Captioned Figure
1089 • TOC Heading
1091 Character styles:
1093 • Default Paragraph Font
1095 • Body Text Char
1097 • Verbatim Char
1099 • Footnote Reference
1101 • Hyperlink
1103 • Section Number
1105 Table style:
1107 • Table
1109 ODT For best results, the reference ODT should be a modified
1111 version of an ODT produced using pandoc. The contents of
1112 the reference ODT are ignored, but its stylesheets are
1113 used in the new ODT. If no reference ODT is specified on
1114 the command line, pandoc will look for a file refer‐
1115 ence.odt in the user data directory (see --data-dir). If
1116 this is not found either, sensible defaults will be used.
1117 To produce a custom reference.odt, first get a copy of
1119 the default reference.odt: pandoc -o custom-reference.odt
1120 --print-default-data-file reference.odt. Then open cus‐
1121 tom-reference.odt in LibreOffice, modify the styles as
1122 you wish, and save the file.
1123 PowerPoint
1125 Templates included with Microsoft PowerPoint 2013 (either
1126 with .pptx or .potx extension) are known to work, as are
1127 most templates derived from these.
1128 The specific requirement is that the template should con‐
1130 tain layouts with the following names (as seen within
1131 PowerPoint):
1132 • Title Slide
1134 • Title and Content
1136 • Section Header
1138 • Two Content
1140 • Comparison
1142 • Content with Caption
1144 • Blank
1146 For each name, the first layout found with that name will
1148 be used. If no layout is found with one of the names,
1149 pandoc will output a warning and use the layout with that
1150 name from the default reference doc instead. (How these
1151 layouts are used is described in PowerPoint layout
1152 choice.)
1153 All templates included with a recent version of MS Power‐
1155 Point will fit these criteria. (You can click on Layout
1156 under the Home menu to check.)
1157 You can also modify the default reference.pptx: first run
1159 pandoc -o custom-reference.pptx --print-default-data-file
1160 reference.pptx, and then modify custom-reference.pptx in
1161 MS PowerPoint (pandoc will use the layouts with the names
1162 listed above).
1163 --split-level=NUMBER
1165 Specify the heading level at which to split an EPUB or chunked
1166 HTML document into separate files. The default is to split into
1167 chapters at level-1 headings. In the case of EPUB, this option
1168 only affects the internal composition of the EPUB, not the way
1169 chapters and sections are displayed to users. Some readers may
1170 be slow if the chapter files are too large, so for large docu‐
1171 ments with few level-1 headings, one might want to use a chapter
1172 level of 2 or 3. For chunked HTML, this option determines how
1173 much content goes in each “chunk.”
1174 --chunk-template=PATHTEMPLATE
1176 Specify a template for the filenames in a chunkedhtml document.
1177 In the template, %n will be replaced by the chunk number (padded
1178 with leading 0s to 3 digits), %s with the section number of the
1179 chunk, %h with the heading text (with formatting removed), %i
1180 with the section identifier. For example, %section-%s-%i.html
1181 might be resolved to section-1.1-introduction.html. The charac‐
1182 ters / and \ are not allowed in chunk templates and will be ig‐
1183 nored. The default is %s-%i.html.
1184 --epub-chapter-level=NUMBER
1186 Deprecated synonym for --split-level.
1187 --epub-cover-image=FILE
1189 Use the specified image as the EPUB cover. It is recommended
1190 that the image be less than 1000px in width and height. Note
1191 that in a Markdown source document you can also specify cover-
1192 image in a YAML metadata block (see EPUB Metadata, below).
1193 --epub-title-page=true|false
1195 Determines whether a the title page is included in the EPUB (de‐
1196 fault is true).
1197 --epub-metadata=FILE
1199 Look in the specified XML file for metadata for the EPUB. The
1200 file should contain a series of Dublin Core elements. For exam‐
1201 ple:
1202 <dc:rights>Creative Commons</dc:rights>
1204 <dc:language>es-AR</dc:language>
1205 By default, pandoc will include the following metadata elements:
1207 <dc:title> (from the document title), <dc:creator> (from the
1208 document authors), <dc:date> (from the document date, which
1209 should be in ISO 8601 format), <dc:language> (from the lang
1210 variable, or, if is not set, the locale), and <dc:identifier
1211 id="BookId"> (a randomly generated UUID). Any of these may be
1212 overridden by elements in the metadata file.
1213 Note: if the source document is Markdown, a YAML metadata block
1215 in the document can be used instead. See below under EPUB Meta‐
1216 data.
1217 --epub-embed-font=FILE
1219 Embed the specified font in the EPUB. This option can be re‐
1220 peated to embed multiple fonts. Wildcards can also be used: for
1221 example, DejaVuSans-*.ttf. However, if you use wildcards on the
1222 command line, be sure to escape them or put the whole filename
1223 in single quotes, to prevent them from being interpreted by the
1224 shell. To use the embedded fonts, you will need to add declara‐
1225 tions like the following to your CSS (see --css):
1226 @font-face {
1228 font-family: DejaVuSans;
1229 font-style: normal;
1230 font-weight: normal;
1231 src:url("../fonts/DejaVuSans-Regular.ttf");
1232 }
1233 @font-face {
1234 font-family: DejaVuSans;
1235 font-style: normal;
1236 font-weight: bold;
1237 src:url("../fonts/DejaVuSans-Bold.ttf");
1238 }
1239 @font-face {
1240 font-family: DejaVuSans;
1241 font-style: italic;
1242 font-weight: normal;
1243 src:url("../fonts/DejaVuSans-Oblique.ttf");
1244 }
1245 @font-face {
1246 font-family: DejaVuSans;
1247 font-style: italic;
1248 font-weight: bold;
1249 src:url("../fonts/DejaVuSans-BoldOblique.ttf");
1250 }
1251 body { font-family: "DejaVuSans"; }
1252 --epub-subdirectory=DIRNAME
1254 Specify the subdirectory in the OCF container that is to hold
1255 the EPUB-specific contents. The default is EPUB. To put the
1256 EPUB contents in the top level, use an empty string.
1257 --ipynb-output=all|none|best
1259 Determines how ipynb output cells are treated. all means that
1260 all of the data formats included in the original are preserved.
1261 none means that the contents of data cells are omitted. best
1262 causes pandoc to try to pick the richest data block in each out‐
1263 put cell that is compatible with the output format. The default
1264 is best.
1265 --pdf-engine=PROGRAM
1267 Use the specified engine when producing PDF output. Valid val‐
1268 ues are pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtml‐
1269 topdf, weasyprint, pagedjs-cli, prince, context, pdfroff, and
1270 typst. If the engine is not in your PATH, the full path of the
1271 engine may be specified here. If this option is not specified,
1272 pandoc uses the following defaults depending on the output for‐
1273 mat specified using -t/--to:
1274 • -t latex or none: pdflatex (other options: xelatex, lualatex,
1276 tectonic, latexmk)
1277 • -t context: context
1279 • -t html: wkhtmltopdf (other options: prince, weasyprint,
1281 pagedjs-cli; see print-css.rocks for a good introduction to
1282 PDF generation from HTML/CSS)
1283 • -t ms: pdfroff
1285 • -t typst: typst
1287 --pdf-engine-opt=STRING
1289 Use the given string as a command-line argument to the pdf-en‐
1290 gine. For example, to use a persistent directory foo for la‐
1291 texmk’s auxiliary files, use --pdf-engine-opt=-outdir=foo. Note
1292 that no check for duplicate options is done.
1293 Citation rendering
1295 -C, --citeproc
1296 Process the citations in the file, replacing them with rendered
1297 citations and adding a bibliography. Citation processing will
1298 not take place unless bibliographic data is supplied, either
1299 through an external file specified using the --bibliography op‐
1300 tion or the bibliography field in metadata, or via a references
1301 section in metadata containing a list of citations in CSL YAML
1302 format with Markdown formatting. The style is controlled by a
1303 CSL stylesheet specified using the --csl option or the csl field
1304 in metadata. (If no stylesheet is specified, the chicago-au‐
1305 thor-date style will be used by default.) The citation process‐
1306 ing transformation may be applied before or after filters or Lua
1307 filters (see --filter, --lua-filter): these transformations are
1308 applied in the order they appear on the command line. For more
1309 information, see the section on Citations.
1310 --bibliography=FILE
1312 Set the bibliography field in the document’s metadata to FILE,
1313 overriding any value set in the metadata. If you supply this
1314 argument multiple times, each FILE will be added to bibliogra‐
1315 phy. If FILE is a URL, it will be fetched via HTTP. If FILE is
1316 not found relative to the working directory, it will be sought
1317 in the resource path (see --resource-path).
1318 --csl=FILE
1320 Set the csl field in the document’s metadata to FILE, overriding
1321 any value set in the metadata. (This is equivalent to --metada‐
1322 ta csl=FILE.) If FILE is a URL, it will be fetched via HTTP.
1323 If FILE is not found relative to the working directory, it will
1324 be sought in the resource path (see --resource-path) and finally
1325 in the csl subdirectory of the pandoc user data directory.
1326 --citation-abbreviations=FILE
1328 Set the citation-abbreviations field in the document’s metadata
1329 to FILE, overriding any value set in the metadata. (This is
1330 equivalent to --metadata citation-abbreviations=FILE.) If FILE
1331 is a URL, it will be fetched via HTTP. If FILE is not found
1332 relative to the working directory, it will be sought in the re‐
1333 source path (see --resource-path) and finally in the csl subdi‐
1334 rectory of the pandoc user data directory.
1335 --natbib
1337 Use natbib for citations in LaTeX output. This option is not
1338 for use with the --citeproc option or with PDF output. It is
1339 intended for use in producing a LaTeX file that can be processed
1340 with bibtex.
1341 --biblatex
1343 Use biblatex for citations in LaTeX output. This option is not
1344 for use with the --citeproc option or with PDF output. It is
1345 intended for use in producing a LaTeX file that can be processed
1346 with bibtex or biber.
1347 Math rendering in HTML
1349 The default is to render TeX math as far as possible using Unicode
1350 characters. Formulas are put inside a span with class="math", so that
1351 they may be styled differently from the surrounding text if needed.
1352 However, this gives acceptable results only for basic math, usually you
1353 will want to use --mathjax or another of the following options.
1354 --mathjax[=URL]
1356 Use MathJax to display embedded TeX math in HTML output. TeX
1357 math will be put between \(...\) (for inline math) or \[...\]
1358 (for display math) and wrapped in <span> tags with class math.
1359 Then the MathJax JavaScript will render it. The URL should
1360 point to the MathJax.js load script. If a URL is not provided,
1361 a link to the Cloudflare CDN will be inserted.
1362 --mathml
1364 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
1365 html4 and html5). This is the default in odt output. MathML is
1366 supported natively by the main web browsers and select e-book
1367 readers.
1368 --webtex[=URL]
1370 Convert TeX formulas to <img> tags that link to an external
1371 script that converts formulas to images. The formula will be
1372 URL-encoded and concatenated with the URL provided. For SVG im‐
1373 ages you can for example use --webtex https://la‐
1374 tex.codecogs.com/svg.latex?. If no URL is specified, the
1375 CodeCogs URL generating PNGs will be used (https://la‐
1376 tex.codecogs.com/png.latex?). Note: the --webtex option will
1377 affect Markdown output as well as HTML, which is useful if
1378 you’re targeting a version of Markdown without native math sup‐
1379 port.
1380 --katex[=URL]
1382 Use KaTeX to display embedded TeX math in HTML output. The URL
1383 is the base URL for the KaTeX library. That directory should
1384 contain a katex.min.js and a katex.min.css file. If a URL is
1385 not provided, a link to the KaTeX CDN will be inserted.
1386 --gladtex
1388 Enclose TeX math in <eq> tags in HTML output. The resulting
1389 HTML can then be processed by GladTeX to produce SVG images of
1390 the typeset formulas and an HTML file with these images embed‐
1391 ded.
1392 pandoc -s --gladtex input.md -o myfile.htex
1394 gladtex -d image_dir myfile.htex
1395 # produces myfile.html and images in image_dir
1396 Options for wrapper scripts
1398 --dump-args
1399 Print information about command-line arguments to stdout, then
1400 exit. This option is intended primarily for use in wrapper
1401 scripts. The first line of output contains the name of the out‐
1402 put file specified with the -o option, or - (for stdout) if no
1403 output file was specified. The remaining lines contain the com‐
1404 mand-line arguments, one per line, in the order they appear.
1405 These do not include regular pandoc options and their arguments,
1406 but do include any options appearing after a -- separator at the
1407 end of the line.
1408 --ignore-args
1410 Ignore command-line arguments (for use in wrapper scripts).
1411 Regular pandoc options are not ignored. Thus, for example,
1412 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1414 is equivalent to
1416 pandoc -o foo.html -s
1418
1420 If pandoc completes successfully, it will return exit code 0. Nonzero
1421 exit codes have the following meanings:
1422 Code Error
1424 ------ -------------------------------------
1425 1 PandocIOError
1426 3 PandocFailOnWarningError
1427 4 PandocAppError
1428 5 PandocTemplateError
1429 6 PandocOptionError
1430 21 PandocUnknownReaderError
1431 22 PandocUnknownWriterError
1432 23 PandocUnsupportedExtensionError
1433 24 PandocCiteprocError
1434 25 PandocBibliographyError
1435 31 PandocEpubSubdirectoryError
1436 43 PandocPDFError
1437 44 PandocXMLError
1438 47 PandocPDFProgramNotFoundError
1439 61 PandocHttpError
1440 62 PandocShouldNeverHappenError
1441 63 PandocSomeError
1442 64 PandocParseError
1443 66 PandocMakePDFError
1444 67 PandocSyntaxMapError
1445 83 PandocFilterError
1446 84 PandocLuaError
1447 89 PandocNoScriptingEngine
1448 91 PandocMacroLoop
1449 92 PandocUTF8DecodingError
1450 93 PandocIpynbDecodingError
1451 94 PandocUnsupportedCharsetError
1452 97 PandocCouldNotFindDataFileError
1453 98 PandocCouldNotFindMetadataFileError
1454 99 PandocResourceNotFound
1455
1457 The --defaults option may be used to specify a package of options, in
1458 the form of a YAML file.
1459 Fields that are omitted will just have their regular default values.
1461 So a defaults file can be as simple as one line:
1462 verbosity: INFO
1464 In fields that expect a file path (or list of file paths), the follow‐
1466 ing syntax may be used to interpolate environment variables:
1467 csl: ${HOME}/mycsldir/special.csl
1469 ${USERDATA} may also be used; this will always resolve to the user data
1471 directory that is current when the defaults file is parsed, regardless
1472 of the setting of the environment variable USERDATA.
1473 ${.} will resolve to the directory containing the defaults file itself.
1475 This allows you to refer to resources contained in that directory:
1476 epub-cover-image: ${.}/cover.jpg
1478 epub-metadata: ${.}/meta.xml
1479 resource-path:
1480 - . # the working directory from which pandoc is run
1481 - ${.}/images # the images subdirectory of the directory
1482 # containing this defaults file
1483 This environment variable interpolation syntax only works in fields
1485 that expect file paths.
1486 Defaults files can be placed in the defaults subdirectory of the user
1488 data directory and used from any directory. For example, one could
1489 create a file specifying defaults for writing letters, save it as let‐
1490 ter.yaml in the defaults subdirectory of the user data directory, and
1491 then invoke these defaults from any directory using pandoc --defaults
1492 letter or pandoc -dletter.
1493 When multiple defaults are used, their contents will be combined.
1495 Note that, where command-line arguments may be repeated (--metadata-
1497 file, --css, --include-in-header, --include-before-body, --include-af‐
1498 ter-body, --variable, --metadata, --syntax-definition), the values
1499 specified on the command line will combine with values specified in the
1500 defaults file, rather than replacing them.
1501 The following tables show the mapping between the command line and de‐
1503 faults file entries.
1504 command line defaults file
1506 --------------------------------- ----------------------------------
1507 foo.md input-file: foo.md
1508 foo.md bar.md input-files:
1510 - foo.md
1511 - bar.md
1512 The value of input-files may be left empty to indicate input from
1515 stdin, and it can be an empty sequence [] for no input.
1516 General options
1518 command line defaults file
1519 --------------------------------- ----------------------------------
1520 --from markdown+emoji from: markdown+emoji
1521 reader: markdown+emoji
1523 to: markdown+hard_line_breaks
1525 --to markdown+hard_line_breaks
1526 writer: markdown+hard_line_breaks
1528 --output foo.pdf output-file: foo.pdf
1530 --output - output-file:
1532 --data-dir dir data-dir: dir
1534 --defaults file defaults:
1536 - file
1537 --verbose verbosity: INFO
1539 --quiet verbosity: ERROR
1541 --fail-if-warnings fail-if-warnings: true
1543 --sandbox sandbox: true
1545 --log=FILE log-file: FILE
1547 Options specified in a defaults file itself always have priority over
1550 those in another file included with a defaults: entry.
1551 verbosity can have the values ERROR, WARNING, or INFO.
1553 Reader options
1555 command line defaults file
1556 --------------------------------- ----------------------------------
1557 --shift-heading-level-by -1 shift-heading-level-by: -1
1558 indented-code-classes:
1560 --indented-code-classes python - python
1561 --default-image-extension ".jpg" default-image-extension: '.jpg'
1564 --file-scope file-scope: true
1566 --filter pandoc-citeproc \ filters:
1568 - pandoc-citeproc
1569 --lua-filter count-words.lua \ - count-words.lua
1570 --filter special.lua - type: json
1571 path: special.lua
1572 --metadata key=value \ metadata:
1574 --metadata key2 key: value
1575 key2: true
1576 --metadata-file meta.yaml metadata-files:
1578 - meta.yaml
1579 metadata-file: meta.yaml
1581 --preserve-tabs preserve-tabs: true
1583 --tab-stop 8 tab-stop: 8
1585 --track-changes accept track-changes: accept
1587 --extract-media dir extract-media: dir
1589 --abbreviations abbrevs.txt abbreviations: abbrevs.txt
1591 --trace trace: true
1593 Metadata values specified in a defaults file are parsed as literal
1596 string text, not Markdown.
1597 Filters will be assumed to be Lua filters if they have the .lua exten‐
1599 sion, and JSON filters otherwise. But the filter type can also be
1600 specified explicitly, as shown. Filters are run in the order speci‐
1601 fied. To include the built-in citeproc filter, use either citeproc or
1602 {type: citeproc}.
1603 General writer options
1605 command line defaults file
1606 --------------------------------- ----------------------------------
1607 --standalone standalone: true
1608 --template letter template: letter
1610 --variable key=val \ variables:
1612 --variable key2 key: val
1613 key2: true
1614 --eol nl eol: nl
1616 --dpi 300 dpi: 300
1618 --wrap 60 wrap: 60
1620 --columns 72 columns: 72
1622 --table-of-contents table-of-contents: true
1624 --toc toc: true
1626 --toc-depth 3 toc-depth: 3
1628 --strip-comments strip-comments: true
1630 --no-highlight highlight-style: null
1632 --highlight-style kate highlight-style: kate
1634 syntax-definitions:
1636 --syntax-definition mylang.xml - mylang.xml
1637 syntax-definition: mylang.xml
1639 --include-in-header inc.tex include-in-header:
1641 - inc.tex
1642 include-before-body:
1644--include-before-body inc.tex - inc.tex
1645 --include-after-body inc.tex include-after-body:
1647 - inc.tex
1648 --resource-path .:foo resource-path: ['.','foo']
1650 --request-header foo:bar request-headers:
1652 - ["User-Agent", "Mozilla/5.0"]
1654 --no-check-certificate no-check-certificate: true
1656 Options affecting specific writers
1659 command line defaults file
1660 --------------------------------- ----------------------------------
1661 --self-contained self-contained: true
1662 --html-q-tags html-q-tags: true
1664 --ascii ascii: true
1666 --reference-links reference-links: true
1668 --reference-location block reference-location: block
1670 --markdown-headings atx markdown-headings: atx
1672 --list-tables list-tables: true
1674 --top-level-division chapter top-level-division: chapter
1676 --number-sections number-sections: true
1678 --number-offset=1,4 number-offset: \[1,4\]
1680 --listings listings: true
1682 --incremental incremental: true
1684 --slide-level 2 slide-level: 2
1686 --section-divs section-divs: true
1688 email-obfuscation: references
1690 --email-obfuscation references
1691 --id-prefix ch1 identifier-prefix: ch1
1693 --title-prefix MySite title-prefix: MySite
1695 --css styles/screen.css \ css:
1697 --css styles/special.css - styles/screen.css
1698 - styles/special.css
1699 --reference-doc my.docx reference-doc: my.docx
1701 --epub-cover-image cover.jpg epub-cover-image: cover.jpg
1703 --epub-title-page=false epub-title-page: false
1705 --epub-metadata meta.xml epub-metadata: meta.xml
1707 epub-fonts:
1709 --epub-embed-font special.otf \ - special.otf
1710 - headline.otf
1711 --epub-embed-font headline.otf
1712 --split-level 2 split-level: 2
1714 --chunk-template="%i.html" chunk-template: "%i.html"
1716 --epub-subdirectory="" epub-subdirectory: ''
1718 --ipynb-output best ipynb-output: best
1720 --pdf-engine xelatex pdf-engine: xelatex
1722 pdf-engine-opts:
1724 --pdf-engine-opt=--shell-escape - '-shell-escape'
1725 pdf-engine-opt: '-shell-escape'
1728 Citation rendering
1731 command line defaults file
1732 --------------------------------- ----------------------------------
1733 --citeproc citeproc: true
1734 --bibliography logic.bib metadata:
1736 bibliography: logic.bib
1737 --csl ieee.csl metadata:
1739 csl: ieee.csl
1740 metadata:
1742 --citation-abbreviations ab.json
1743 citation-abbreviations: ab.json
1744 --natbib cite-method: natbib
1746 --biblatex cite-method: biblatex
1748 cite-method can be citeproc, natbib, or biblatex. This only affects
1751 LaTeX output. If you want to use citeproc to format citations, you
1752 should also set `citeproc: true'.
1753 If you need control over when the citeproc processing is done relative
1755 to other filters, you should instead use citeproc in the list of fil‐
1756 ters (see above).
1757 Math rendering in HTML
1759 command line defaults file
1760 --------------------------------- ----------------------------------
1761 --mathjax html-math-method:
1762 method: mathjax
1763 --mathml html-math-method:
1765 method: mathml
1766 --webtex html-math-method:
1768 method: webtex
1769 --katex html-math-method:
1771 method: katex
1772 --gladtex html-math-method:
1774 method: gladtex
1775 In addition to the values listed above, method can have the value
1778 plain.
1779 If the command line option accepts a URL argument, an url: field can be
1781 added to html-math-method:.
1782 Options for wrapper scripts
1784 command line defaults file
1785 --------------------------------- ----------------------------------
1786 --dump-args dump-args: true
1787 --ignore-args ignore-args: true
1789
1792 When the -s/--standalone option is used, pandoc uses a template to add
1793 header and footer material that is needed for a self-standing document.
1794 To see the default template that is used, just type
1795 pandoc -D *FORMAT*
1797 where FORMAT is the name of the output format. A custom template can
1799 be specified using the --template option. You can also override the
1800 system default templates for a given output format FORMAT by putting a
1801 file templates/default.*FORMAT* in the user data directory (see --data-
1802 dir, above). Exceptions:
1803 • For odt output, customize the default.opendocument template.
1805 • For pdf output, customize the default.latex template (or the de‐
1807 fault.context template, if you use -t context, or the default.ms tem‐
1808 plate, if you use -t ms, or the default.html template, if you use -t
1809 html).
1810 • docx and pptx have no template (however, you can use --reference-doc
1812 to customize the output).
1813 Templates contain variables, which allow for the inclusion of arbitrary
1815 information at any point in the file. They may be set at the command
1816 line using the -V/--variable option. If a variable is not set, pandoc
1817 will look for the key in the document’s metadata, which can be set us‐
1818 ing either YAML metadata blocks or with the -M/--metadata option. In
1819 addition, some variables are given default values by pandoc. See Vari‐
1820 ables below for a list of variables used in pandoc’s default templates.
1821 If you use custom templates, you may need to revise them as pandoc
1823 changes. We recommend tracking the changes in the default templates,
1824 and modifying your custom templates accordingly. An easy way to do
1825 this is to fork the pandoc-templates repository and merge in changes
1826 after each pandoc release.
1827 Template syntax
1829 Comments
1830 Anything between the sequence $-- and the end of the line will be
1831 treated as a comment and omitted from the output.
1832 Delimiters
1834 To mark variables and control structures in the template, either $...$
1835 or ${...} may be used as delimiters. The styles may also be mixed in
1836 the same template, but the opening and closing delimiter must match in
1837 each case. The opening delimiter may be followed by one or more spaces
1838 or tabs, which will be ignored. The closing delimiter may be preceded
1839 by one or more spaces or tabs, which will be ignored.
1840 To include a literal $ in the document, use $$.
1842 Interpolated variables
1844 A slot for an interpolated variable is a variable name surrounded by
1845 matched delimiters. Variable names must begin with a letter and can
1846 contain letters, numbers, _, -, and .. The keywords it, if, else, en‐
1847 dif, for, sep, and endfor may not be used as variable names. Examples:
1848 $foo$
1850 $foo.bar.baz$
1851 $foo_bar.baz-bim$
1852 $ foo $
1853 ${foo}
1854 ${foo.bar.baz}
1855 ${foo_bar.baz-bim}
1856 ${ foo }
1857 Variable names with periods are used to get at structured variable val‐
1859 ues. So, for example, employee.salary will return the value of the
1860 salary field of the object that is the value of the employee field.
1861 • If the value of the variable is a simple value, it will be rendered
1863 verbatim. (Note that no escaping is done; the assumption is that the
1864 calling program will escape the strings appropriately for the output
1865 format.)
1866 • If the value is a list, the values will be concatenated.
1868 • If the value is a map, the string true will be rendered.
1870 • Every other value will be rendered as the empty string.
1872 Conditionals
1874 A conditional begins with if(variable) (enclosed in matched delimiters)
1875 and ends with endif (enclosed in matched delimiters). It may optional‐
1876 ly contain an else (enclosed in matched delimiters). The if section is
1877 used if variable has a non-empty value, otherwise the else section is
1878 used (if present). Examples:
1879 $if(foo)$bar$endif$
1881 $if(foo)$
1883 $foo$
1884 $endif$
1885 $if(foo)$
1887 part one
1888 $else$
1889 part two
1890 $endif$
1891 ${if(foo)}bar${endif}
1893 ${if(foo)}
1895 ${foo}
1896 ${endif}
1897 ${if(foo)}
1899 ${ foo.bar }
1900 ${else}
1901 no foo!
1902 ${endif}
1903 The keyword elseif may be used to simplify complex nested conditionals:
1905 $if(foo)$
1907 XXX
1908 $elseif(bar)$
1909 YYY
1910 $else$
1911 ZZZ
1912 $endif$
1913 For loops
1915 A for loop begins with for(variable) (enclosed in matched delimiters)
1916 and ends with endfor (enclosed in matched delimiters).
1917 • If variable is an array, the material inside the loop will be evalu‐
1919 ated repeatedly, with variable being set to each value of the array
1920 in turn, and concatenated.
1921 • If variable is a map, the material inside will be set to the map.
1923 • If the value of the associated variable is not an array or a map, a
1925 single iteration will be performed on its value.
1926 Examples:
1928 $for(foo)$$foo$$sep$, $endfor$
1930 $for(foo)$
1932 - $foo.last$, $foo.first$
1933 $endfor$
1934 ${ for(foo.bar) }
1936 - ${ foo.bar.last }, ${ foo.bar.first }
1937 ${ endfor }
1938 $for(mymap)$
1940 $it.name$: $it.office$
1941 $endfor$
1942 You may optionally specify a separator between consecutive values using
1944 sep (enclosed in matched delimiters). The material between sep and the
1945 endfor is the separator.
1946 ${ for(foo) }${ foo }${ sep }, ${ endfor }
1948 Instead of using variable inside the loop, the special anaphoric key‐
1950 word it may be used.
1951 ${ for(foo.bar) }
1953 - ${ it.last }, ${ it.first }
1954 ${ endfor }
1955 Partials
1957 Partials (subtemplates stored in different files) may be included by
1958 using the name of the partial, followed by (), for example:
1959 ${ styles() }
1961 Partials will be sought in the directory containing the main template.
1963 The file name will be assumed to have the same extension as the main
1964 template if it lacks an extension. When calling the partial, the full
1965 name including file extension can also be used:
1966 ${ styles.html() }
1968 (If a partial is not found in the directory of the template and the
1970 template path is given as a relative path, it will also be sought in
1971 the templates subdirectory of the user data directory.)
1972 Partials may optionally be applied to variables using a colon:
1974 ${ date:fancy() }
1976 ${ articles:bibentry() }
1978 If articles is an array, this will iterate over its values, applying
1980 the partial bibentry() to each one. So the second example above is
1981 equivalent to
1982 ${ for(articles) }
1984 ${ it:bibentry() }
1985 ${ endfor }
1986 Note that the anaphoric keyword it must be used when iterating over
1988 partials. In the above examples, the bibentry partial should contain
1989 it.title (and so on) instead of articles.title.
1990 Final newlines are omitted from included partials.
1992 Partials may include other partials.
1994 A separator between values of an array may be specified in square
1996 brackets, immediately after the variable name or partial:
1997 ${months[, ]}$
1999 ${articles:bibentry()[; ]$
2001 The separator in this case is literal and (unlike with sep in an ex‐
2003 plicit for loop) cannot contain interpolated variables or other tem‐
2004 plate directives.
2005 Nesting
2007 To ensure that content is “nested,” that is, subsequent lines indented,
2008 use the ^ directive:
2009 $item.number$ $^$$item.description$ ($item.price$)
2011 In this example, if item.description has multiple lines, they will all
2013 be indented to line up with the first line:
2014 00123 A fine bottle of 18-year old
2016 Oban whiskey. ($148)
2017 To nest multiple lines to the same level, align them with the ^ direc‐
2019 tive in the template. For example:
2020 $item.number$ $^$$item.description$ ($item.price$)
2022 (Available til $item.sellby$.)
2023 will produce
2025 00123 A fine bottle of 18-year old
2027 Oban whiskey. ($148)
2028 (Available til March 30, 2020.)
2029 If a variable occurs by itself on a line, preceded by whitespace and
2031 not followed by further text or directives on the same line, and the
2032 variable’s value contains multiple lines, it will be nested automati‐
2033 cally.
2034 Breakable spaces
2036 Normally, spaces in the template itself (as opposed to values of the
2037 interpolated variables) are not breakable, but they can be made break‐
2038 able in part of the template by using the ~ keyword (ended with another
2039 ~).
2040 $~$This long line may break if the document is rendered
2042 with a short line length.$~$
2043 Pipes
2045 A pipe transforms the value of a variable or partial. Pipes are speci‐
2046 fied using a slash (/) between the variable name (or partial) and the
2047 pipe name. Example:
2048 $for(name)$
2050 $name/uppercase$
2051 $endfor$
2052 $for(metadata/pairs)$
2054 - $it.key$: $it.value$
2055 $endfor$
2056 $employee:name()/uppercase$
2058 Pipes may be chained:
2060 $for(employees/pairs)$
2062 $it.key/alpha/uppercase$. $it.name$
2063 $endfor$
2064 Some pipes take parameters:
2066 |----------------------|------------|
2068 $for(employee)$
2069 $it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
2070 $endfor$
2071 |----------------------|------------|
2072 Currently the following pipes are predefined:
2074 • pairs: Converts a map or array to an array of maps, each with key and
2076 value fields. If the original value was an array, the key will be
2077 the array index, starting with 1.
2078 • uppercase: Converts text to uppercase.
2080 • lowercase: Converts text to lowercase.
2082 • length: Returns the length of the value: number of characters for a
2084 textual value, number of elements for a map or array.
2085 • reverse: Reverses a textual value or array, and has no effect on oth‐
2087 er values.
2088 • first: Returns the first value of an array, if applied to a non-empty
2090 array; otherwise returns the original value.
2091 • last: Returns the last value of an array, if applied to a non-empty
2093 array; otherwise returns the original value.
2094 • rest: Returns all but the first value of an array, if applied to a
2096 non-empty array; otherwise returns the original value.
2097 • allbutlast: Returns all but the last value of an array, if applied to
2099 a non-empty array; otherwise returns the original value.
2100 • chomp: Removes trailing newlines (and breakable space).
2102 • nowrap: Disables line wrapping on breakable spaces.
2104 • alpha: Converts textual values that can be read as an integer into
2106 lowercase alphabetic characters a..z (mod 26). This can be used to
2107 get lettered enumeration from array indices. To get uppercase let‐
2108 ters, chain with uppercase.
2109 • roman: Converts textual values that can be read as an integer into
2111 lowercase roman numerals. This can be used to get lettered enumera‐
2112 tion from array indices. To get uppercase roman, chain with upper‐
2113 case.
2114 • left n "leftborder" "rightborder": Renders a textual value in a block
2116 of width n, aligned to the left, with an optional left and right bor‐
2117 der. Has no effect on other values. This can be used to align mate‐
2118 rial in tables. Widths are positive integers indicating the number
2119 of characters. Borders are strings inside double quotes; literal "
2120 and \ characters must be backslash-escaped.
2121 • right n "leftborder" "rightborder": Renders a textual value in a
2123 block of width n, aligned to the right, and has no effect on other
2124 values.
2125 • center n "leftborder" "rightborder": Renders a textual value in a
2127 block of width n, aligned to the center, and has no effect on other
2128 values.
2129 Variables
2131 Metadata variables
2132 title, author, date
2133 allow identification of basic aspects of the document. Included
2134 in PDF metadata through LaTeX and ConTeXt. These can be set
2135 through a pandoc title block, which allows for multiple authors,
2136 or through a YAML metadata block:
2137 ---
2139 author:
2140 - Aristotle
2141 - Peter Abelard
2142 ...
2143 Note that if you just want to set PDF or HTML metadata, without
2145 including a title block in the document itself, you can set the
2146 title-meta, author-meta, and date-meta variables. (By default
2147 these are set automatically, based on title, author, and date.)
2148 The page title in HTML is set by pagetitle, which is equal to
2149 title by default.
2150 subtitle
2152 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
2153 docx documents
2154 abstract
2156 document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc,
2157 and docx documents
2158 abstract-title
2160 title of abstract, currently used only in HTML and EPUB. This
2161 will be set automatically to a localized value, depending on
2162 lang, but can be manually overridden.
2163 keywords
2165 list of keywords to be included in HTML, PDF, ODT, pptx, docx
2166 and AsciiDoc metadata; repeat as for author, above
2167 subject
2169 document subject, included in ODT, PDF, docx, EPUB, and pptx
2170 metadata
2171 description
2173 document description, included in ODT, docx and pptx metadata.
2174 Some applications show this as Comments metadata.
2175 category
2177 document category, included in docx and pptx metadata
2178 Additionally, any root-level string metadata, not included in ODT, docx
2180 or pptx metadata is added as a custom property. The following YAML
2181 metadata block for instance:
2182 ---
2184 title: 'This is the title'
2185 subtitle: "This is the subtitle"
2186 author:
2187 - Author One
2188 - Author Two
2189 description: |
2190 This is a long
2191 description.
2192 It consists of two paragraphs
2194 ...
2195 will include title, author and description as standard document proper‐
2197 ties and subtitle as a custom property when converting to docx, ODT or
2198 pptx.
2199 Language variables
2201 lang identifies the main language of the document using IETF language
2202 tags (following the BCP 47 standard), such as en or en-GB. The
2203 Language subtag lookup tool can look up or verify these tags.
2204 This affects most formats, and controls hyphenation in PDF out‐
2205 put when using LaTeX (through babel and polyglossia) or ConTeXt.
2206 Use native pandoc Divs and Spans with the lang attribute to
2208 switch the language:
2209 ---
2211 lang: en-GB
2212 ...
2213 Text in the main document language (British English).
2215 ::: {lang=fr-CA}
2217 > Cette citation est écrite en français canadien.
2218 :::
2219 More text in English. ['Zitat auf Deutsch.']{lang=de}
2221 dir the base script direction, either rtl (right-to-left) or ltr
2223 (left-to-right).
2224 For bidirectional documents, native pandoc spans and divs with
2226 the dir attribute (value rtl or ltr) can be used to override the
2227 base direction in some output formats. This may not always be
2228 necessary if the final renderer (e.g. the browser, when generat‐
2229 ing HTML) supports the Unicode Bidirectional Algorithm.
2230 When using LaTeX for bidirectional documents, only the xelatex
2232 engine is fully supported (use --pdf-engine=xelatex).
2233 Variables for HTML
2235 document-css
2236 Enables inclusion of most of the CSS in the styles.html partial
2237 (have a look with pandoc --print-default-data-file=tem‐
2238 plates/styles.html). Unless you use --css, this variable is set
2239 to true by default. You can disable it with e.g. pandoc -M doc‐
2240 ument-css=false.
2241 mainfont
2243 sets the CSS font-family property on the html element.
2244 fontsize
2246 sets the base CSS font-size, which you’d usually set to
2247 e.g. 20px, but it also accepts pt (12pt = 16px in most
2248 browsers).
2249 fontcolor
2251 sets the CSS color property on the html element.
2252 linkcolor
2254 sets the CSS color property on all links.
2255 monofont
2257 sets the CSS font-family property on code elements.
2258 monobackgroundcolor
2260 sets the CSS background-color property on code elements and adds
2261 extra padding.
2262 linestretch
2264 sets the CSS line-height property on the html element, which is
2265 preferred to be unitless.
2266 maxwidth
2268 sets the CSS max-width property (default is 32em).
2269 backgroundcolor
2271 sets the CSS background-color property on the html element.
2272 margin-left, margin-right, margin-top, margin-bottom
2274 sets the corresponding CSS padding properties on the body ele‐
2275 ment.
2276 To override or extend some CSS for just one document, include for exam‐
2278 ple:
2279 ---
2281 header-includes: |
2282 <style>
2283 blockquote {
2284 font-style: italic;
2285 }
2286 tr.even {
2287 background-color: #f0f0f0;
2288 }
2289 td, th {
2290 padding: 0.5em 2em 0.5em 0.5em;
2291 }
2292 tbody {
2293 border-bottom: none;
2294 }
2295 </style>
2296 ---
2297 Variables for HTML math
2299 classoption
2300 when using KaTeX, you can render display math equations flush
2301 left using YAML metadata or with -M classoption=fleqn.
2302 Variables for HTML slides
2304 These affect HTML output when producing slide shows with pandoc.
2305 institute
2307 author affiliations: can be a list when there are multiple au‐
2308 thors
2309 revealjs-url
2311 base URL for reveal.js documents (defaults to
2312 https://unpkg.com/reveal.js@^4/)
2313 s5-url base URL for S5 documents (defaults to s5/default)
2315 slidy-url
2317 base URL for Slidy documents (defaults to
2318 https://www.w3.org/Talks/Tools/Slidy2)
2319 slideous-url
2321 base URL for Slideous documents (defaults to slideous)
2322 title-slide-attributes
2324 additional attributes for the title slide of reveal.js slide
2325 shows. See background in reveal.js, beamer, and pptx for an ex‐
2326 ample.
2327 All reveal.js configuration options are available as variables. To
2329 turn off boolean flags that default to true in reveal.js, use 0.
2330 Variables for Beamer slides
2332 These variables change the appearance of PDF slides using beamer.
2333 aspectratio
2335 slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for
2336 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)
2337 beameroption
2339 add extra beamer option with \setbeameroption{}
2340 institute
2342 author affiliations: can be a list when there are multiple au‐
2343 thors
2344 logo logo image for slides
2346 navigation
2348 controls navigation symbols (default is empty for no navigation
2349 symbols; other valid values are frame, vertical, and horizontal)
2350 section-titles
2352 enables “title pages” for new sections (default is true)
2353 theme, colortheme, fonttheme, innertheme, outertheme
2355 beamer themes
2356 themeoptions
2358 options for LaTeX beamer themes (a list).
2359 titlegraphic
2361 image for title slide
2362 Variables for PowerPoint
2364 These variables control the visual aspects of a slide show that are not
2365 easily controlled via templates.
2366 monofont
2368 font to use for code.
2369 Variables for LaTeX
2371 Pandoc uses these variables when creating a PDF with a LaTeX engine.
2372 Layout
2374 block-headings
2375 make \paragraph and \subparagraph (fourth- and fifth-level head‐
2376 ings, or fifth- and sixth-level with book classes) free-standing
2377 rather than run-in; requires further formatting to distinguish
2378 from \subsubsection (third- or fourth-level headings). Instead
2379 of using this option, KOMA-Script can adjust headings more ex‐
2380 tensively:
2381 ---
2383 documentclass: scrartcl
2384 header-includes: |
2385 \RedeclareSectionCommand[
2386 beforeskip=-10pt plus -2pt minus -1pt,
2387 afterskip=1sp plus -1sp minus 1sp,
2388 font=\normalfont\itshape]{paragraph}
2389 \RedeclareSectionCommand[
2390 beforeskip=-10pt plus -2pt minus -1pt,
2391 afterskip=1sp plus -1sp minus 1sp,
2392 font=\normalfont\scshape,
2393 indent=0pt]{subparagraph}
2394 ...
2395 classoption
2397 option for document class, e.g. oneside; repeat for multiple op‐
2398 tions:
2399 ---
2401 classoption:
2402 - twocolumn
2403 - landscape
2404 ...
2405 documentclass
2407 document class: usually one of the standard classes, article,
2408 book, and report; the KOMA-Script equivalents, scrartcl, scr‐
2409 book, and scrreprt, which default to smaller margins; or memoir
2410 geometry
2412 option for geometry package, e.g. margin=1in; repeat for multi‐
2413 ple options:
2414 ---
2416 geometry:
2417 - top=30mm
2418 - left=20mm
2419 - heightrounded
2420 ...
2421 hyperrefoptions
2423 option for hyperref package, e.g. linktoc=all; repeat for multi‐
2424 ple options:
2425 ---
2427 hyperrefoptions:
2428 - linktoc=all
2429 - pdfwindowui
2430 - pdfpagemode=FullScreen
2431 ...
2432 indent if true, pandoc will use document class settings for indentation
2434 (the default LaTeX template otherwise removes indentation and
2435 adds space between paragraphs)
2436 linestretch
2438 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
2439 margin-left, margin-right, margin-top, margin-bottom
2441 sets margins if geometry is not used (otherwise geometry over‐
2442 rides these)
2443 pagestyle
2445 control \pagestyle{}: the default article class supports plain
2446 (default), empty (no running heads or page numbers), and head‐
2447 ings (section titles in running heads)
2448 papersize
2450 paper size, e.g. letter, a4
2451 secnumdepth
2453 numbering depth for sections (with --number-sections option or
2454 numbersections variable)
2455 beamerarticle
2457 produce an article from Beamer slides
2458 Fonts
2460 fontenc
2461 allows font encoding to be specified through fontenc package
2462 (with pdflatex); default is T1 (see LaTeX font encodings guide)
2463 fontfamily
2465 font package for use with pdflatex: TeX Live includes many op‐
2466 tions, documented in the LaTeX Font Catalogue. The default is
2467 Latin Modern.
2468 fontfamilyoptions
2470 options for package used as fontfamily; repeat for multiple op‐
2471 tions. For example, to use the Libertine font with proportional
2472 lowercase (old-style) figures through the libertinus package:
2473 ---
2475 fontfamily: libertinus
2476 fontfamilyoptions:
2477 - osf
2478 - p
2479 ...
2480 fontsize
2482 font size for body text. The standard classes allow 10pt, 11pt,
2483 and 12pt. To use another size, set documentclass to one of the
2484 KOMA-Script classes, such as scrartcl or scrbook.
2485 mainfont, sansfont, monofont, mathfont, CJKmainfont, CJKsansfont, CJK‐
2487 monofont
2488 font families for use with xelatex or lualatex: take the name of
2489 any system font, using the fontspec package. CJKmainfont uses
2490 the xecjk package.
2491 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions,
2493 CJKoptions
2494 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
2495 mainfont in xelatex and lualatex. Allow for any choices avail‐
2496 able through fontspec; repeat for multiple options. For exam‐
2497 ple, to use the TeX Gyre version of Palatino with lowercase fig‐
2498 ures:
2499 ---
2501 mainfont: TeX Gyre Pagella
2502 mainfontoptions:
2503 - Numbers=Lowercase
2504 - Numbers=Proportional
2505 ...
2506 babelfonts
2508 a map of Babel language names (e.g. chinese) to the font to be
2509 used with the language:
2510 * * * * *
2512 babelfonts: chinese-hant: “Noto Serif CJK TC” russian: “Noto
2514 Serif” ...
2515 microtypeoptions
2517 options to pass to the microtype package
2518 Links
2520 colorlinks
2521 add color to link text; automatically enabled if any of linkcol‐
2522 or, filecolor, citecolor, urlcolor, or toccolor are set
2523 boxlinks
2525 add visible box around links (has no effect if colorlinks is
2526 set)
2527 linkcolor, filecolor, citecolor, urlcolor, toccolor
2529 color for internal links, external links, citation links, linked
2530 URLs, and links in table of contents, respectively: uses options
2531 allowed by xcolor, including the dvipsnames, svgnames, and
2532 x11names lists
2533 links-as-notes
2535 causes links to be printed as footnotes
2536 urlstyle
2538 style for URLs (e.g., tt, rm, sf, and, the default, same)
2539 Front matter
2541 lof, lot
2542 include list of figures, list of tables
2543 thanks contents of acknowledgments footnote after document title
2545 toc include table of contents (can also be set using --toc/--table-
2547 of-contents)
2548 toc-depth
2550 level of section to include in table of contents
2551 BibLaTeX Bibliographies
2553 These variables function when using BibLaTeX for citation rendering.
2554 biblatexoptions
2556 list of options for biblatex
2557 biblio-style
2559 bibliography style, when used with --natbib and --biblatex
2560 biblio-title
2562 bibliography title, when used with --natbib and --biblatex
2563 bibliography
2565 bibliography to use for resolving references
2566 natbiboptions
2568 list of options for natbib
2569 Variables for ConTeXt
2571 Pandoc uses these variables when creating a PDF with ConTeXt.
2572 fontsize
2574 font size for body text (e.g. 10pt, 12pt)
2575 headertext, footertext
2577 text to be placed in running header or footer (see ConTeXt Head‐
2578 ers and Footers); repeat up to four times for different place‐
2579 ment
2580 indenting
2582 controls indentation of paragraphs, e.g. yes,small,next (see
2583 ConTeXt Indentation); repeat for multiple options
2584 interlinespace
2586 adjusts line spacing, e.g. 4ex (using setupinterlinespace); re‐
2587 peat for multiple options
2588 layout options for page margins and text arrangement (see ConTeXt Lay‐
2590 out); repeat for multiple options
2591 linkcolor, contrastcolor
2593 color for links outside and inside a page, e.g. red, blue (see
2594 ConTeXt Color)
2595 linkstyle
2597 typeface style for links, e.g. normal, bold, slanted, boldslant‐
2598 ed, type, cap, small
2599 lof, lot
2601 include list of figures, list of tables
2602 mainfont, sansfont, monofont, mathfont
2604 font families: take the name of any system font (see ConTeXt
2605 Font Switching)
2606 margin-left, margin-right, margin-top, margin-bottom
2608 sets margins, if layout is not used (otherwise layout overrides
2609 these)
2610 pagenumbering
2612 page number style and location (using setuppagenumbering); re‐
2613 peat for multiple options
2614 papersize
2616 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
2617 up); repeat for multiple options
2618 pdfa adds to the preamble the setup necessary to generate PDF/A of
2620 the type specified, e.g. 1a:2005, 2a. If no type is specified
2621 (i.e. the value is set to True, by e.g. --metadata=pdfa or
2622 pdfa: true in a YAML metadata block), 1b:2005 will be used as
2623 default, for reasons of backwards compatibility. Using --vari‐
2624 able=pdfa without specified value is not supported. To success‐
2625 fully generate PDF/A the required ICC color profiles have to be
2626 available and the content and all included files (such as im‐
2627 ages) have to be standard-conforming. The ICC profiles and out‐
2628 put intent may be specified using the variables pdfaiccprofile
2629 and pdfaintent. See also ConTeXt PDFA for more details.
2630 pdfaiccprofile
2632 when used in conjunction with pdfa, specifies the ICC profile to
2633 use in the PDF, e.g. default.cmyk. If left unspecified,
2634 sRGB.icc is used as default. May be repeated to include multi‐
2635 ple profiles. Note that the profiles have to be available on
2636 the system. They can be obtained from ConTeXt ICC Profiles.
2637 pdfaintent
2639 when used in conjunction with pdfa, specifies the output intent
2640 for the colors, e.g. ISO coated v2 300\letterpercent\space (ECI)
2641 If left unspecified, sRGB IEC61966-2.1 is used as default.
2642 toc include table of contents (can also be set using --toc/--table-
2644 of-contents)
2645 urlstyle
2647 typeface style for links without link text, e.g. normal, bold,
2648 slanted, boldslanted, type, cap, small
2649 whitespace
2651 spacing between paragraphs, e.g. none, small (using setupwhites‐
2652 pace)
2653 includesource
2655 include all source documents as file attachments in the PDF file
2656 Variables for wkhtmltopdf
2658 Pandoc uses these variables when creating a PDF with wkhtmltopdf. The
2659 --css option also affects the output.
2660 footer-html, header-html
2662 add information to the header and footer
2663 margin-left, margin-right, margin-top, margin-bottom
2665 set the page margins
2666 papersize
2668 sets the PDF paper size
2669 Variables for man pages
2671 adjusting
2672 adjusts text to left (l), right (r), center (c), or both (b)
2673 margins
2674 footer footer in man pages
2676 header header in man pages
2678 hyphenate
2680 if true (the default), hyphenation will be used
2681 section
2683 section number in man pages
2684 Variables for Typst
2686 margin A dictionary with the fields defined in the Typst documentation:
2687 x, y, top, bottom, left, right.
2688 papersize
2690 Paper size: a4, us-letter, etc.
2691 mainfont
2693 Name of system font to use for the main font.
2694 fontsize
2696 Font size (e.g., 12pt).
2697 section-numbering
2699 Schema to use for numbering sections, e.g. 1.A.1.
2700 columns
2702 Number of columns for body text.
2703 Variables for ms
2705 fontfamily
2706 A (Avant Garde), B (Bookman), C (Helvetica), HN (Helvetica Nar‐
2707 row), P (Palatino), or T (Times New Roman). This setting does
2708 not affect source code, which is always displayed using mono‐
2709 space Courier. These built-in fonts are limited in their cover‐
2710 age of characters. Additional fonts may be installed using the
2711 script install-font.sh provided by Peter Schaffter and document‐
2712 ed in detail on his web site.
2713 indent paragraph indent (e.g. 2m)
2715 lineheight
2717 line height (e.g. 12p)
2718 pointsize
2720 point size (e.g. 10p)
2721 Variables set automatically
2723 Pandoc sets these variables automatically in response to options or
2724 document contents; users can also modify them. These vary depending on
2725 the output format, and include the following:
2726 body body of document
2728 date-meta
2730 the date variable converted to ISO 8601 YYYY-MM-DD, included in
2731 all HTML based formats (dzslides, epub, html, html4, html5, re‐
2732 vealjs, s5, slideous, slidy). The recognized formats for date
2733 are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy
2734 (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy
2735 (e.g. Apr. 02, 2018 or April 02,
2736 2018),yyyy[mm[dd]](e.g.20180402, 201804 or 2018).
2737 header-includes
2739 contents specified by -H/--include-in-header (may have multiple
2740 values)
2741 include-before
2743 contents specified by -B/--include-before-body (may have multi‐
2744 ple values)
2745 include-after
2747 contents specified by -A/--include-after-body (may have multiple
2748 values)
2749 meta-json
2751 JSON representation of all of the document’s metadata. Field
2752 values are transformed to the selected output format.
2753 numbersections
2755 non-null value if -N/--number-sections was specified
2756 sourcefile, outputfile
2758 source and destination filenames, as given on the command line.
2759 sourcefile can also be a list if input comes from multiple
2760 files, or empty if input is from stdin. You can use the follow‐
2761 ing snippet in your template to distinguish them:
2762 $if(sourcefile)$
2764 $for(sourcefile)$
2765 $sourcefile$
2766 $endfor$
2767 $else$
2768 (stdin)
2769 $endif$
2770 Similarly, outputfile can be - if output goes to the terminal.
2772 If you need absolute paths, use e.g. $curdir$/$sourcefile$.
2774 curdir working directory from which pandoc is run.
2776 pandoc-version
2778 pandoc version.
2779 toc non-null value if --toc/--table-of-contents was specified
2781 toc-title
2783 title of table of contents (works only with EPUB, HTML, re‐
2784 vealjs, opendocument, odt, docx, pptx, beamer, LaTeX)
2785
2787 The behavior of some of the readers and writers can be adjusted by en‐
2788 abling or disabling various extensions.
2789 An extension can be enabled by adding +EXTENSION to the format name and
2791 disabled by adding -EXTENSION. For example, --from mark‐
2792 down_strict+footnotes is strict Markdown with footnotes enabled, while
2793 --from markdown-footnotes-pipe_tables is pandoc’s Markdown without
2794 footnotes or pipe tables.
2795 The markdown reader and writer make by far the most use of extensions.
2797 Extensions only used by them are therefore covered in the section Pan‐
2798 doc’s Markdown below (see Markdown variants for commonmark and gfm).
2799 In the following, extensions that also work for other formats are cov‐
2800 ered.
2801 Note that markdown extensions added to the ipynb format affect Markdown
2803 cells in Jupyter notebooks (as do command-line options like --markdown-
2804 headings).
2805 Typography
2807 Extension: smart
2808 Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-
2809 dashes, and ... as ellipses. Nonbreaking spaces are inserted after
2810 certain abbreviations, such as “Mr.”
2811 This extension can be enabled/disabled for the following formats:
2813 input formats
2815 markdown, commonmark, latex, mediawiki, org, rst, twiki, html
2816 output formats
2818 markdown, latex, context, rst
2819 enabled by default in
2821 markdown, latex, context (both input and output)
2822 Note: If you are writing Markdown, then the smart extension has the re‐
2824 verse effect: what would have been curly quotes comes out straight.
2825 In LaTeX, smart means to use the standard TeX ligatures for quotation
2827 marks (`` and '' for double quotes, ` and ' for single quotes) and
2828 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
2829 then in reading LaTeX pandoc will parse these characters literally. In
2830 writing LaTeX, enabling smart tells pandoc to use the ligatures when
2831 possible; if smart is disabled pandoc will use unicode quotation mark
2832 and dash characters.
2833 Headings and sections
2835 Extension: auto_identifiers
2836 A heading without an explicitly specified identifier will be automati‐
2837 cally assigned a unique identifier based on the heading text.
2838 This extension can be enabled/disabled for the following formats:
2840 input formats
2842 markdown, latex, rst, mediawiki, textile
2843 output formats
2845 markdown, muse
2846 enabled by default in
2848 markdown, muse
2849 The default algorithm used to derive the identifier from the heading
2851 text is:
2852 • Remove all formatting, links, etc.
2854 • Remove all footnotes.
2856 • Remove all non-alphanumeric characters, except underscores, hyphens,
2858 and periods.
2859 • Replace all spaces and newlines with hyphens.
2861 • Convert all alphabetic characters to lowercase.
2863 • Remove everything up to the first letter (identifiers may not begin
2865 with a number or punctuation mark).
2866 • If nothing is left after this, use the identifier section.
2868 Thus, for example,
2870 Heading Identifier
2872 ----------------------------- -----------------------------
2873 Heading identifiers in HTML heading-identifiers-in-html
2874 Maître d'hôtel maître-dhôtel
2875 *Dogs*?--in *my* house? dogs--in-my-house
2876 [HTML], [S5], or [RTF]? html-s5-or-rtf
2877 3. Applications applications
2878 33 section
2879 These rules should, in most cases, allow one to determine the identifi‐
2881 er from the heading text. The exception is when several headings have
2882 the same text; in this case, the first will get an identifier as de‐
2883 scribed above; the second will get the same identifier with -1 append‐
2884 ed; the third with -2; and so on.
2885 (However, a different algorithm is used if gfm_auto_identifiers is en‐
2887 abled; see below.)
2888 These identifiers are used to provide link targets in the table of con‐
2890 tents generated by the --toc|--table-of-contents option. They also
2891 make it easy to provide links from one section of a document to anoth‐
2892 er. A link to this section, for example, might look like this:
2893 See the section on
2895 [heading identifiers](#heading-identifiers-in-html-latex-and-context).
2896 Note, however, that this method of providing links to sections works
2898 only in HTML, LaTeX, and ConTeXt formats.
2899 If the --section-divs option is specified, then each section will be
2901 wrapped in a section (or a div, if html4 was specified), and the iden‐
2902 tifier will be attached to the enclosing <section> (or <div>) tag
2903 rather than the heading itself. This allows entire sections to be ma‐
2904 nipulated using JavaScript or treated differently in CSS.
2905 Extension: ascii_identifiers
2907 Causes the identifiers produced by auto_identifiers to be pure ASCII.
2908 Accents are stripped off of accented Latin letters, and non-Latin let‐
2909 ters are omitted.
2910 Extension: gfm_auto_identifiers
2912 Changes the algorithm used by auto_identifiers to conform to GitHub’s
2913 method. Spaces are converted to dashes (-), uppercase characters to
2914 lowercase characters, and punctuation characters other than - and _ are
2915 removed. Emojis are replaced by their names.
2916 Math Input
2918 The extensions tex_math_dollars, tex_math_single_backslash, and
2919 tex_math_double_backslash are described in the section about Pandoc’s
2920 Markdown.
2921 However, they can also be used with HTML input. This is handy for
2923 reading web pages formatted using MathJax, for example.
2924 Raw HTML/TeX
2926 The following extensions are described in more detail in their respec‐
2927 tive sections of Pandoc’s Markdown:
2928 • raw_html allows HTML elements which are not representable in pandoc’s
2930 AST to be parsed as raw HTML. By default, this is disabled for HTML
2931 input.
2932 • raw_tex allows raw LaTeX, TeX, and ConTeXt to be included in a docu‐
2934 ment. This extension can be enabled/disabled for the following for‐
2935 mats (in addition to markdown):
2936 input formats
2938 latex, textile, html (environments, \ref, and \eqref only),
2939 ipynb
2940 output formats
2942 textile, commonmark
2943 Note: as applied to ipynb, raw_html and raw_tex affect not only raw
2945 TeX in markdown cells, but data with mime type text/html in output
2946 cells. Since the ipynb reader attempts to preserve the richest pos‐
2947 sible outputs when several options are given, you will get best re‐
2948 sults if you disable raw_html and raw_tex when converting to formats
2949 like docx which don’t allow raw html or tex.
2950 • native_divs causes HTML div elements to be parsed as native pandoc
2952 Div blocks. If you want them to be parsed as raw HTML, use -f html-
2953 native_divs+raw_html.
2954 • native_spans causes HTML span elements to be parsed as native pandoc
2956 Span inlines. If you want them to be parsed as raw HTML, use -f
2957 html-native_spans+raw_html. If you want to drop all divs and spans
2958 when converting HTML to Markdown, you can use pandoc -f html-na‐
2959 tive_divs-native_spans -t markdown.
2960 Literate Haskell support
2962 Extension: literate_haskell
2963 Treat the document as literate Haskell source.
2964 This extension can be enabled/disabled for the following formats:
2966 input formats
2968 markdown, rst, latex
2969 output formats
2971 markdown, rst, latex, html
2972 If you append +lhs (or +literate_haskell) to one of the formats above,
2974 pandoc will treat the document as literate Haskell source. This means
2975 that
2976 • In Markdown input, “bird track” sections will be parsed as Haskell
2978 code rather than block quotations. Text between \begin{code} and
2979 \end{code} will also be treated as Haskell code. For ATX-style head‐
2980 ings the character `=' will be used instead of `#'.
2981 • In Markdown output, code blocks with classes haskell and literate
2983 will be rendered using bird tracks, and block quotations will be in‐
2984 dented one space, so they will not be treated as Haskell code. In
2985 addition, headings will be rendered setext-style (with underlines)
2986 rather than ATX-style (with `#' characters). (This is because ghc
2987 treats `#' characters in column 1 as introducing line numbers.)
2988 • In restructured text input, “bird track” sections will be parsed as
2990 Haskell code.
2991 • In restructured text output, code blocks with class haskell will be
2993 rendered using bird tracks.
2994 • In LaTeX input, text in code environments will be parsed as Haskell
2996 code.
2997 • In LaTeX output, code blocks with class haskell will be rendered in‐
2999 side code environments.
3000 • In HTML output, code blocks with class haskell will be rendered with
3002 class literatehaskell and bird tracks.
3003 Examples:
3005 pandoc -f markdown+lhs -t html
3007 reads literate Haskell source formatted with Markdown conventions and
3009 writes ordinary HTML (without bird tracks).
3010 pandoc -f markdown+lhs -t html+lhs
3012 writes HTML with the Haskell code in bird tracks, so it can be copied
3014 and pasted as literate Haskell source.
3015 Note that GHC expects the bird tracks in the first column, so indented
3017 literate code blocks (e.g. inside an itemized environment) will not be
3018 picked up by the Haskell compiler.
3019 Other extensions
3021 Extension: empty_paragraphs
3022 Allows empty paragraphs. By default empty paragraphs are omitted.
3023 This extension can be enabled/disabled for the following formats:
3025 input formats
3027 docx, html
3028 output formats
3030 docx, odt, opendocument, html
3031 Extension: native_numbering
3033 Enables native numbering of figures and tables. Enumeration starts at
3034 1.
3035 This extension can be enabled/disabled for the following formats:
3037 output formats
3039 odt, opendocument, docx
3040 Extension: xrefs_name
3042 Links to headings, figures and tables inside the document are substi‐
3043 tuted with cross-references that will use the name or caption of the
3044 referenced item. The original link text is replaced once the generated
3045 document is refreshed. This extension can be combined with xrefs_num‐
3046 ber in which case numbers will appear before the name.
3047 Text in cross-references is only made consistent with the referenced
3049 item once the document has been refreshed.
3050 This extension can be enabled/disabled for the following formats:
3052 output formats
3054 odt, opendocument
3055 Extension: xrefs_number
3057 Links to headings, figures and tables inside the document are substi‐
3058 tuted with cross-references that will use the number of the referenced
3059 item. The original link text is discarded. This extension can be com‐
3060 bined with xrefs_name in which case the name or caption numbers will
3061 appear after the number.
3062 For the xrefs_number to be useful heading numbers must be enabled in
3064 the generated document, also table and figure captions must be enabled
3065 using for example the native_numbering extension.
3066 Numbers in cross-references are only visible in the final document once
3068 it has been refreshed.
3069 This extension can be enabled/disabled for the following formats:
3071 output formats
3073 odt, opendocument
3074 Extension: styles
3076 When converting from docx, read all docx styles as divs (for paragraph
3077 styles) and spans (for character styles) regardless of whether pandoc
3078 understands the meaning of these styles. This can be used with docx
3079 custom styles. Disabled by default.
3080 input formats
3082 docx
3083 Extension: amuse
3085 In the muse input format, this enables Text::Amuse extensions to Emacs
3086 Muse markup.
3087 Extension: raw_markdown
3089 In the ipynb input format, this causes Markdown cells to be included as
3090 raw Markdown blocks (allowing lossless round-tripping) rather than be‐
3091 ing parsed. Use this only when you are targeting ipynb or a markdown-
3092 based output format.
3093 Extension: citations
3095 When the citations extension is enabled in org, org-cite and org-ref
3096 style citations will be parsed as native pandoc citations.
3097 When citations is enabled in docx, citations inserted by Zotero or
3099 Mendeley or EndNote plugins will be parsed as native pandoc citations.
3100 (Otherwise, the formatted citations generated by the bibliographic
3101 software will be parsed as regular text.)
3102 Extension: fancy_lists
3104 Some aspects of Pandoc’s Markdown fancy lists are also accepted in org
3105 input, mimicking the option org-list-allow-alphabetical in Emacs. As
3106 in Org Mode, enabling this extension allows lowercase and uppercase al‐
3107 phabetical markers for ordered lists to be parsed in addition to arabic
3108 ones. Note that for Org, this does not include roman numerals or the #
3109 placeholder that are enabled by the extension in Pandoc’s Markdown.
3110 Extension: element_citations
3112 In the jats output formats, this causes reference items to be replaced
3113 with <element-citation> elements. These elements are not influenced by
3114 CSL styles, but all information on the item is included in tags.
3115 Extension: ntb
3117 In the context output format this enables the use of Natural Tables
3118 (TABLE) instead of the default Extreme Tables (xtables). Natural ta‐
3119 bles allow more fine-grained global customization but come at a perfor‐
3120 mance penalty compared to extreme tables.
3121 Extension: tagging
3123 Enabling this extension with context output will produce markup suit‐
3124 able for the production of tagged PDFs. This includes additional mark‐
3125 ers for paragraphs and alternative markup for emphasized text. The em‐
3126 phasis-command template variable is set if the extension is enabled.
3127
3129 Pandoc understands an extended and slightly revised version of John
3130 Gruber’s Markdown syntax. This document explains the syntax, noting
3131 differences from original Markdown. Except where noted, these differ‐
3132 ences can be suppressed by using the markdown_strict format instead of
3133 markdown. Extensions can be enabled or disabled to specify the behav‐
3134 ior more granularly. They are described in the following. See also
3135 Extensions above, for extensions that work also on other formats.
3136 Philosophy
3138 Markdown is designed to be easy to write, and, even more importantly,
3139 easy to read:
3140 A Markdown-formatted document should be publishable as-is, as
3142 plain text, without looking like it’s been marked up with tags
3143 or formatting instructions. – John Gruber
3144 This principle has guided pandoc’s decisions in finding syntax for ta‐
3146 bles, footnotes, and other extensions.
3147 There is, however, one respect in which pandoc’s aims are different
3149 from the original aims of Markdown. Whereas Markdown was originally
3150 designed with HTML generation in mind, pandoc is designed for multiple
3151 output formats. Thus, while pandoc allows the embedding of raw HTML,
3152 it discourages it, and provides other, non-HTMLish ways of representing
3153 important document elements like definition lists, tables, mathematics,
3154 and footnotes.
3155 Paragraphs
3157 A paragraph is one or more lines of text followed by one or more blank
3158 lines. Newlines are treated as spaces, so you can reflow your para‐
3159 graphs as you like. If you need a hard line break, put two or more
3160 spaces at the end of a line.
3161 Extension: escaped_line_breaks
3163 A backslash followed by a newline is also a hard line break. Note: in
3164 multiline and grid table cells, this is the only way to create a hard
3165 line break, since trailing spaces in the cells are ignored.
3166 Headings
3168 There are two kinds of headings: Setext and ATX.
3169 Setext-style headings
3171 A setext-style heading is a line of text “underlined” with a row of =
3172 signs (for a level-one heading) or - signs (for a level-two heading):
3173 A level-one heading
3175 ===================
3176 A level-two heading
3178 -------------------
3179 The heading text can contain inline formatting, such as emphasis (see
3181 Inline formatting, below).
3182 ATX-style headings
3184 An ATX-style heading consists of one to six # signs and a line of text,
3185 optionally followed by any number of # signs. The number of # signs at
3186 the beginning of the line is the heading level:
3187 ## A level-two heading
3189 ### A level-three heading ###
3191 As with setext-style headings, the heading text can contain formatting:
3193 # A level-one heading with a [link](/url) and *emphasis*
3195 Extension: blank_before_header
3197 Original Markdown syntax does not require a blank line before a head‐
3198 ing. Pandoc does require this (except, of course, at the beginning of
3199 the document). The reason for the requirement is that it is all too
3200 easy for a # to end up at the beginning of a line by accident (perhaps
3201 through line wrapping). Consider, for example:
3202 I like several of their flavors of ice cream:
3204 #22, for example, and #5.
3205 Extension: space_in_atx_header
3207 Many Markdown implementations do not require a space between the open‐
3208 ing #s of an ATX heading and the heading text, so that #5 bolt and
3209 #hashtag count as headings. With this extension, pandoc does require
3210 the space.
3211 Heading identifiers
3213 See also the auto_identifiers extension above.
3214 Extension: header_attributes
3216 Headings can be assigned attributes using this syntax at the end of the
3217 line containing the heading text:
3218 {#identifier .class .class key=value key=value}
3220 Thus, for example, the following headings will all be assigned the
3222 identifier foo:
3223 # My heading {#foo}
3225 ## My heading ## {#foo}
3227 My other heading {#foo}
3229 ---------------
3230 (This syntax is compatible with PHP Markdown Extra.)
3232 Note that although this syntax allows assignment of classes and
3234 key/value attributes, writers generally don’t use all of this informa‐
3235 tion. Identifiers, classes, and key/value attributes are used in HTML
3236 and HTML-based formats such as EPUB and slidy. Identifiers are used
3237 for labels and link anchors in the LaTeX, ConTeXt, Textile, Jira
3238 markup, and AsciiDoc writers.
3239 Headings with the class unnumbered will not be numbered, even if --num‐
3241 ber-sections is specified. A single hyphen (-) in an attribute context
3242 is equivalent to .unnumbered, and preferable in non-English documents.
3243 So,
3244 # My heading {-}
3246 is just the same as
3248 # My heading {.unnumbered}
3250 If the unlisted class is present in addition to unnumbered, the heading
3252 will not be included in a table of contents. (Currently this feature
3253 is only implemented for certain formats: those based on LaTeX and HTML,
3254 PowerPoint, and RTF.)
3255 Extension: implicit_header_references
3257 Pandoc behaves as if reference links have been defined for each head‐
3258 ing. So, to link to a heading
3259 # Heading identifiers in HTML
3261 you can simply write
3263 [Heading identifiers in HTML]
3265 or
3267 [Heading identifiers in HTML][]
3269 or
3271 [the section on heading identifiers][heading identifiers in
3273 HTML]
3274 instead of giving the identifier explicitly:
3276 [Heading identifiers in HTML](#heading-identifiers-in-html)
3278 If there are multiple headings with identical text, the corresponding
3280 reference will link to the first one only, and you will need to use ex‐
3281 plicit links to link to the others, as described above.
3282 Like regular reference links, these references are case-insensitive.
3284 Explicit link reference definitions always take priority over implicit
3286 heading references. So, in the following example, the link will point
3287 to bar, not to #foo:
3288 # Foo
3290 [foo]: bar
3292 See [foo]
3294 Block quotations
3296 Markdown uses email conventions for quoting blocks of text. A block
3297 quotation is one or more paragraphs or other block elements (such as
3298 lists or headings), with each line preceded by a > character and an op‐
3299 tional space. (The > need not start at the left margin, but it should
3300 not be indented more than three spaces.)
3301 > This is a block quote. This
3303 > paragraph has two lines.
3304 >
3305 > 1. This is a list inside a block quote.
3306 > 2. Second item.
3307 A “lazy” form, which requires the > character only on the first line of
3309 each block, is also allowed:
3310 > This is a block quote. This
3312 paragraph has two lines.
3313 > 1. This is a list inside a block quote.
3315 2. Second item.
3316 Among the block elements that can be contained in a block quote are
3318 other block quotes. That is, block quotes can be nested:
3319 > This is a block quote.
3321 >
3322 > > A block quote within a block quote.
3323 If the > character is followed by an optional space, that space will be
3325 considered part of the block quote marker and not part of the indenta‐
3326 tion of the contents. Thus, to put an indented code block in a block
3327 quote, you need five spaces after the >:
3328 > code
3330 Extension: blank_before_blockquote
3332 Original Markdown syntax does not require a blank line before a block
3333 quote. Pandoc does require this (except, of course, at the beginning
3334 of the document). The reason for the requirement is that it is all too
3335 easy for a > to end up at the beginning of a line by accident (perhaps
3336 through line wrapping). So, unless the markdown_strict format is used,
3337 the following does not produce a nested block quote in pandoc:
3338 > This is a block quote.
3340 >> Not nested, since `blank_before_blockquote` is enabled by default
3341 Verbatim (code) blocks
3343 Indented code blocks
3344 A block of text indented four spaces (or one tab) is treated as verba‐
3345 tim text: that is, special characters do not trigger special format‐
3346 ting, and all spaces and line breaks are preserved. For example,
3347 if (a > 3) {
3349 moveShip(5 * gravity, DOWN);
3350 }
3351 The initial (four space or one tab) indentation is not considered part
3353 of the verbatim text, and is removed in the output.
3354 Note: blank lines in the verbatim text need not begin with four spaces.
3356 Fenced code blocks
3358 Extension: fenced_code_blocks
3359 In addition to standard indented code blocks, pandoc supports fenced
3360 code blocks. These begin with a row of three or more tildes (~) and
3361 end with a row of tildes that must be at least as long as the starting
3362 row. Everything between these lines is treated as code. No indenta‐
3363 tion is necessary:
3364 ~~~~~~~
3366 if (a > 3) {
3367 moveShip(5 * gravity, DOWN);
3368 }
3369 ~~~~~~~
3370 Like regular code blocks, fenced code blocks must be separated from
3372 surrounding text by blank lines.
3373 If the code itself contains a row of tildes or backticks, just use a
3375 longer row of tildes or backticks at the start and end:
3376 ~~~~~~~~~~~~~~~~
3378 ~~~~~~~~~~
3379 code including tildes
3380 ~~~~~~~~~~
3381 ~~~~~~~~~~~~~~~~
3382 Extension: backtick_code_blocks
3384 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
3385 (~).
3386 Extension: fenced_code_attributes
3388 Optionally, you may attach attributes to fenced or backtick code block
3389 using this syntax:
3390 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
3392 qsort [] = []
3393 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3394 qsort (filter (>= x) xs)
3395 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3396 Here mycode is an identifier, haskell and numberLines are classes, and
3398 startFrom is an attribute with value 100. Some output formats can use
3399 this information to do syntax highlighting. Currently, the only output
3400 formats that use this information are HTML, LaTeX, Docx, Ms, and Power‐
3401 Point. If highlighting is supported for your output format and lan‐
3402 guage, then the code block above will appear highlighted, with numbered
3403 lines. (To see which languages are supported, type pandoc --list-high‐
3404 light-languages.) Otherwise, the code block above will appear as fol‐
3405 lows:
3406 <pre id="mycode" class="haskell numberLines" startFrom="100">
3408 <code>
3409 ...
3410 </code>
3411 </pre>
3412 The numberLines (or number-lines) class will cause the lines of the
3414 code block to be numbered, starting with 1 or the value of the start‐
3415 From attribute. The lineAnchors (or line-anchors) class will cause the
3416 lines to be clickable anchors in HTML output.
3417 A shortcut form can also be used for specifying the language of the
3419 code block:
3420 ```haskell
3422 qsort [] = []
3423 ```
3424 This is equivalent to:
3426 ``` {.haskell}
3428 qsort [] = []
3429 ```
3430 This shortcut form may be combined with attributes:
3432 ```haskell {.numberLines}
3434 qsort [] = []
3435 ```
3436 Which is equivalent to:
3438 ``` {.haskell .numberLines}
3440 qsort [] = []
3441 ```
3442 If the fenced_code_attributes extension is disabled, but input contains
3444 class attribute(s) for the code block, the first class attribute will
3445 be printed after the opening fence as a bare word.
3446 To prevent all highlighting, use the --no-highlight flag. To set the
3448 highlighting style, use --highlight-style. For more information on
3449 highlighting, see Syntax highlighting, below.
3450 Line blocks
3452 Extension: line_blocks
3453 A line block is a sequence of lines beginning with a vertical bar (|)
3454 followed by a space. The division into lines will be preserved in the
3455 output, as will any leading spaces; otherwise, the lines will be for‐
3456 matted as Markdown. This is useful for verse and addresses:
3457 | The limerick packs laughs anatomical
3459 | In space that is quite economical.
3460 | But the good ones I've seen
3461 | So seldom are clean
3462 | And the clean ones so seldom are comical
3463 | 200 Main St.
3465 | Berkeley, CA 94718
3466 The lines can be hard-wrapped if needed, but the continuation line must
3468 begin with a space.
3469 | The Right Honorable Most Venerable and Righteous Samuel L.
3471 Constable, Jr.
3472 | 200 Main St.
3473 | Berkeley, CA 94718
3474 Inline formatting (such as emphasis) is allowed in the content, but not
3476 block-level formatting (such as block quotes or lists).
3477 This syntax is borrowed from reStructuredText.
3479 Lists
3481 Bullet lists
3482 A bullet list is a list of bulleted list items. A bulleted list item
3483 begins with a bullet (*, +, or -). Here is a simple example:
3484 * one
3486 * two
3487 * three
3488 This will produce a “compact” list. If you want a “loose” list, in
3490 which each item is formatted as a paragraph, put spaces between the
3491 items:
3492 * one
3494 * two
3496 * three
3498 The bullets need not be flush with the left margin; they may be indent‐
3500 ed one, two, or three spaces. The bullet must be followed by white‐
3501 space.
3502 List items look best if subsequent lines are flush with the first line
3504 (after the bullet):
3505 * here is my first
3507 list item.
3508 * and my second.
3509 But Markdown also allows a “lazy” format:
3511 * here is my first
3513 list item.
3514 * and my second.
3515 Block content in list items
3517 A list item may contain multiple paragraphs and other block-level con‐
3518 tent. However, subsequent paragraphs must be preceded by a blank line
3519 and indented to line up with the first non-space content after the list
3520 marker.
3521 * First paragraph.
3523 Continued.
3525 * Second paragraph. With a code block, which must be indented
3527 eight spaces:
3528 { code }
3530 Exception: if the list marker is followed by an indented code block,
3532 which must begin 5 spaces after the list marker, then subsequent para‐
3533 graphs must begin two columns after the last character of the list
3534 marker:
3535 * code
3537 continuation paragraph
3539 List items may include other lists. In this case the preceding blank
3541 line is optional. The nested list must be indented to line up with the
3542 first non-space character after the list marker of the containing list
3543 item.
3544 * fruits
3546 + apples
3547 - macintosh
3548 - red delicious
3549 + pears
3550 + peaches
3551 * vegetables
3552 + broccoli
3553 + chard
3554 As noted above, Markdown allows you to write list items “lazily,” in‐
3556 stead of indenting continuation lines. However, if there are multiple
3557 paragraphs or other blocks in a list item, the first line of each must
3558 be indented.
3559 + A lazy, lazy, list
3561 item.
3562 + Another one; this looks
3564 bad but is legal.
3565 Second paragraph of second
3567 list item.
3568 Ordered lists
3570 Ordered lists work just like bulleted lists, except that the items be‐
3571 gin with enumerators rather than bullets.
3572 In original Markdown, enumerators are decimal numbers followed by a pe‐
3574 riod and a space. The numbers themselves are ignored, so there is no
3575 difference between this list:
3576 1. one
3578 2. two
3579 3. three
3580 and this one:
3582 5. one
3584 7. two
3585 1. three
3586 Extension: fancy_lists
3588 Unlike original Markdown, pandoc allows ordered list items to be marked
3589 with uppercase and lowercase letters and roman numerals, in addition to
3590 Arabic numerals. List markers may be enclosed in parentheses or fol‐
3591 lowed by a single right-parenthesis or period. They must be separated
3592 from the text that follows by at least one space, and, if the list
3593 marker is a capital letter with a period, by at least two spaces.
3594 The fancy_lists extension also allows `#' to be used as an ordered list
3596 marker in place of a numeral:
3597 #. one
3599 #. two
3600 Note: the `#' ordered list marker doesn’t work with commonmark.
3602 Extension: startnum
3604 Pandoc also pays attention to the type of list marker used, and to the
3605 starting number, and both of these are preserved where possible in the
3606 output format. Thus, the following yields a list with numbers followed
3607 by a single parenthesis, starting with 9, and a sublist with lowercase
3608 roman numerals:
3609 9) Ninth
3611 10) Tenth
3612 11) Eleventh
3613 i. subone
3614 ii. subtwo
3615 iii. subthree
3616 Pandoc will start a new list each time a different type of list marker
3618 is used. So, the following will create three lists:
3619 (2) Two
3621 (5) Three
3622 1. Four
3623 * Five
3624 If default list markers are desired, use #.:
3626 #. one
3628 #. two
3629 #. three
3630 Extension: task_lists
3632 Pandoc supports task lists, using the syntax of GitHub-Flavored Mark‐
3633 down.
3634 - [ ] an unchecked task list item
3636 - [x] checked item
3637 Definition lists
3639 Extension: definition_lists
3640 Pandoc supports definition lists, using the syntax of PHP Markdown Ex‐
3641 tra with some extensions.
3642 Term 1
3644 : Definition 1
3646 Term 2 with *inline markup*
3648 : Definition 2
3650 { some code, part of Definition 2 }
3652 Third paragraph of definition 2.
3654 Each term must fit on one line, which may optionally be followed by a
3656 blank line, and must be followed by one or more definitions. A defini‐
3657 tion begins with a colon or tilde, which may be indented one or two
3658 spaces.
3659 A term may have multiple definitions, and each definition may consist
3661 of one or more block elements (paragraph, code block, list, etc.), each
3662 indented four spaces or one tab stop. The body of the definition (not
3663 including the first line) should be indented four spaces. However, as
3664 with other Markdown lists, you can “lazily” omit indentation except at
3665 the beginning of a paragraph or other block element:
3666 Term 1
3668 : Definition
3670 with lazy continuation.
3671 Second paragraph of the definition.
3673 If you leave space before the definition (as in the example above), the
3675 text of the definition will be treated as a paragraph. In some output
3676 formats, this will mean greater spacing between term/definition pairs.
3677 For a more compact definition list, omit the space before the defini‐
3678 tion:
3679 Term 1
3681 ~ Definition 1
3682 Term 2
3684 ~ Definition 2a
3685 ~ Definition 2b
3686 Note that space between items in a definition list is required. (A
3688 variant that loosens this requirement, but disallows “lazy” hard wrap‐
3689 ping, can be activated with the compact_definition_lists extension.)
3690 Numbered example lists
3692 Extension: example_lists
3693 The special list marker @ can be used for sequentially numbered exam‐
3694 ples. The first list item with a @ marker will be numbered `1', the
3695 next `2', and so on, throughout the document. The numbered examples
3696 need not occur in a single list; each new list using @ will take up
3697 where the last stopped. So, for example:
3698 (@) My first example will be numbered (1).
3700 (@) My second example will be numbered (2).
3701 Explanation of examples.
3703 (@) My third example will be numbered (3).
3705 Numbered examples can be labeled and referred to elsewhere in the docu‐
3707 ment:
3708 (@good) This is a good example.
3710 As (@good) illustrates, ...
3712 The label can be any string of alphanumeric characters, underscores, or
3714 hyphens.
3715 Note: continuation paragraphs in example lists must always be indented
3717 four spaces, regardless of the length of the list marker. That is, ex‐
3718 ample lists always behave as if the four_space_rule extension is set.
3719 This is because example labels tend to be long, and indenting content
3720 to the first non-space character after the label would be awkward.
3721 Ending a list
3723 What if you want to put an indented code block after a list?
3724 - item one
3726 - item two
3727 { my code block }
3729 Trouble! Here pandoc (like other Markdown implementations) will treat
3731 { my code block } as the second paragraph of item two, and not as a
3732 code block.
3733 To “cut off” the list after item two, you can insert some non-indented
3735 content, like an HTML comment, which won’t produce visible output in
3736 any format:
3737 - item one
3739 - item two
3740 <!-- end of list -->
3742 { my code block }
3744 You can use the same trick if you want two consecutive lists instead of
3746 one big list:
3747 1. one
3749 2. two
3750 3. three
3751 <!-- -->
3753 1. uno
3755 2. dos
3756 3. tres
3757 Horizontal rules
3759 A line containing a row of three or more *, -, or _ characters (option‐
3760 ally separated by spaces) produces a horizontal rule:
3761 * * * *
3763 ---------------
3765 We strongly recommend that horizontal rules be separated from surround‐
3767 ing text by blank lines. If a horizontal rule is not followed by a
3768 blank line, pandoc may try to interpret the lines that follow as a YAML
3769 metadata block or a table.
3770 Tables
3772 Four kinds of tables may be used. The first three kinds presuppose the
3773 use of a fixed-width font, such as Courier. The fourth kind can be
3774 used with proportionally spaced fonts, as it does not require lining up
3775 columns.
3776 Extension: table_captions
3778 A caption may optionally be provided with all 4 kinds of tables (as il‐
3779 lustrated in the examples below). A caption is a paragraph beginning
3780 with the string Table: (or table: or just :), which will be stripped
3781 off. It may appear either before or after the table.
3782 Extension: simple_tables
3784 Simple tables look like this:
3785 Right Left Center Default
3787 ------- ------ ---------- -------
3788 12 12 12 12
3789 123 123 123 123
3790 1 1 1 1
3791 Table: Demonstration of simple table syntax.
3793 The header and table rows must each fit on one line. Column alignments
3795 are determined by the position of the header text relative to the
3796 dashed line below it:
3797 • If the dashed line is flush with the header text on the right side
3799 but extends beyond it on the left, the column is right-aligned.
3800 • If the dashed line is flush with the header text on the left side but
3802 extends beyond it on the right, the column is left-aligned.
3803 • If the dashed line extends beyond the header text on both sides, the
3805 column is centered.
3806 • If the dashed line is flush with the header text on both sides, the
3808 default alignment is used (in most cases, this will be left).
3809 The table must end with a blank line, or a line of dashes followed by a
3811 blank line.
3812 The column header row may be omitted, provided a dashed line is used to
3814 end the table. For example:
3815 ------- ------ ---------- -------
3817 12 12 12 12
3818 123 123 123 123
3819 1 1 1 1
3820 ------- ------ ---------- -------
3821 When the header row is omitted, column alignments are determined on the
3823 basis of the first line of the table body. So, in the tables above,
3824 the columns would be right, left, center, and right aligned, respec‐
3825 tively.
3826 Extension: multiline_tables
3828 Multiline tables allow header and table rows to span multiple lines of
3829 text (but cells that span multiple columns or rows of the table are not
3830 supported). Here is an example:
3831 -------------------------------------------------------------
3833 Centered Default Right Left
3834 Header Aligned Aligned Aligned
3835 ----------- ------- --------------- -------------------------
3836 First row 12.0 Example of a row that
3837 spans multiple lines.
3838 Second row 5.0 Here's another one. Note
3840 the blank line between
3841 rows.
3842 -------------------------------------------------------------
3843 Table: Here's the caption. It, too, may span
3845 multiple lines.
3846 These work like simple tables, but with the following differences:
3848 • They must begin with a row of dashes, before the header text (unless
3850 the header row is omitted).
3851 • They must end with a row of dashes, then a blank line.
3853 • The rows must be separated by blank lines.
3855 In multiline tables, the table parser pays attention to the widths of
3857 the columns, and the writers try to reproduce these relative widths in
3858 the output. So, if you find that one of the columns is too narrow in
3859 the output, try widening it in the Markdown source.
3860 The header may be omitted in multiline tables as well as simple tables:
3862 ----------- ------- --------------- -------------------------
3864 First row 12.0 Example of a row that
3865 spans multiple lines.
3866 Second row 5.0 Here's another one. Note
3868 the blank line between
3869 rows.
3870 ----------- ------- --------------- -------------------------
3871 : Here's a multiline table without a header.
3873 It is possible for a multiline table to have just one row, but the row
3875 should be followed by a blank line (and then the row of dashes that
3876 ends the table), or the table may be interpreted as a simple table.
3877 Extension: grid_tables
3879 Grid tables look like this:
3880 : Sample grid table.
3882 +---------------+---------------+--------------------+
3884 | Fruit | Price | Advantages |
3885 +===============+===============+====================+
3886 | Bananas | $1.34 | - built-in wrapper |
3887 | | | - bright color |
3888 +---------------+---------------+--------------------+
3889 | Oranges | $2.10 | - cures scurvy |
3890 | | | - tasty |
3891 +---------------+---------------+--------------------+
3892 The row of =s separates the header from the table body, and can be
3894 omitted for a headerless table. The cells of grid tables may contain
3895 arbitrary block elements (multiple paragraphs, code blocks, lists,
3896 etc.).
3897 Cells can span multiple columns or rows:
3899 +---------------------+----------+
3901 | Property | Earth |
3902 +=============+=======+==========+
3903 | | min | -89.2 °C |
3904 | Temperature +-------+----------+
3905 | 1961-1990 | mean | 14 °C |
3906 | +-------+----------+
3907 | | max | 56.7 °C |
3908 +-------------+-------+----------+
3909 A table header may contain more than one row:
3911 +---------------------+-----------------------+
3913 | Location | Temperature 1961-1990 |
3914 | | in degree Celsius |
3915 | +-------+-------+-------+
3916 | | min | mean | max |
3917 +=====================+=======+=======+=======+
3918 | Antarctica | -89.2 | N/A | 19.8 |
3919 +---------------------+-------+-------+-------+
3920 | Earth | -89.2 | 14 | 56.7 |
3921 +---------------------+-------+-------+-------+
3922 Alignments can be specified as with pipe tables, by putting colons at
3924 the boundaries of the separator line after the header:
3925 +---------------+---------------+--------------------+
3927 | Right | Left | Centered |
3928 +==============:+:==============+:==================:+
3929 | Bananas | $1.34 | built-in wrapper |
3930 +---------------+---------------+--------------------+
3931 For headerless tables, the colons go on the top line instead:
3933 +--------------:+:--------------+:------------------:+
3935 | Right | Left | Centered |
3936 +---------------+---------------+--------------------+
3937 A table foot can be defined by enclosing it with separator lines that
3939 use = instead of -:
3940 +---------------+---------------+
3942 | Fruit | Price |
3943 +===============+===============+
3944 | Bananas | $1.34 |
3945 +---------------+---------------+
3946 | Oranges | $2.10 |
3947 +===============+===============+
3948 | Sum | $3.44 |
3949 +===============+===============+
3950 The foot must always be placed at the very bottom of the table.
3952 Grid tables can be created easily using Emacs’ table-mode (M-x table-
3954 insert).
3955 Extension: pipe_tables
3957 Pipe tables look like this:
3958 | Right | Left | Default | Center |
3960 |------:|:-----|---------|:------:|
3961 | 12 | 12 | 12 | 12 |
3962 | 123 | 123 | 123 | 123 |
3963 | 1 | 1 | 1 | 1 |
3964 : Demonstration of pipe table syntax.
3966 The syntax is identical to PHP Markdown Extra tables. The beginning
3968 and ending pipe characters are optional, but pipes are required between
3969 all columns. The colons indicate column alignment as shown. The head‐
3970 er cannot be omitted. To simulate a headerless table, include a header
3971 with blank cells.
3972 Since the pipes indicate column boundaries, columns need not be verti‐
3974 cally aligned, as they are in the above example. So, this is a per‐
3975 fectly legal (though ugly) pipe table:
3976 fruit| price
3978 -----|-----:
3979 apple|2.05
3980 pear|1.37
3981 orange|3.09
3982 The cells of pipe tables cannot contain block elements like paragraphs
3984 and lists, and cannot span multiple lines. If any line of the markdown
3985 source is longer than the column width (see --columns), then the table
3986 will take up the full text width and the cell contents will wrap, with
3987 the relative cell widths determined by the number of dashes in the line
3988 separating the table header from the table body. (For example ---|-
3989 would make the first column 3/4 and the second column 1/4 of the full
3990 text width.) On the other hand, if no lines are wider than column
3991 width, then cell contents will not be wrapped, and the cells will be
3992 sized to their contents.
3993 Note: pandoc also recognizes pipe tables of the following form, as can
3995 be produced by Emacs’ orgtbl-mode:
3996 | One | Two |
3998 |-----+-------|
3999 | my | table |
4000 | is | nice |
4001 The difference is that + is used instead of |. Other orgtbl features
4003 are not supported. In particular, to get non-default column alignment,
4004 you’ll need to add colons as above.
4005 Metadata blocks
4007 Extension: pandoc_title_block
4008 If the file begins with a title block
4009 % title
4011 % author(s) (separated by semicolons)
4012 % date
4013 it will be parsed as bibliographic information, not regular text. (It
4015 will be used, for example, in the title of standalone LaTeX or HTML
4016 output.) The block may contain just a title, a title and an author, or
4017 all three elements. If you want to include an author but no title, or
4018 a title and a date but no author, you need a blank line:
4019 %
4021 % Author
4022 % My title
4024 %
4025 % June 15, 2006
4026 The title may occupy multiple lines, but continuation lines must begin
4028 with leading space, thus:
4029 % My title
4031 on multiple lines
4032 If a document has multiple authors, the authors may be put on separate
4034 lines with leading space, or separated by semicolons, or both. So, all
4035 of the following are equivalent:
4036 % Author One
4038 Author Two
4039 % Author One; Author Two
4041 % Author One;
4043 Author Two
4044 The date must fit on one line.
4046 All three metadata fields may contain standard inline formatting (ital‐
4048 ics, links, footnotes, etc.).
4049 Title blocks will always be parsed, but they will affect the output on‐
4051 ly when the --standalone (-s) option is chosen. In HTML output, titles
4052 will appear twice: once in the document head – this is the title that
4053 will appear at the top of the window in a browser – and once at the be‐
4054 ginning of the document body. The title in the document head can have
4055 an optional prefix attached (--title-prefix or -T option). The title
4056 in the body appears as an H1 element with class “title”, so it can be
4057 suppressed or reformatted with CSS. If a title prefix is specified
4058 with -T and no title block appears in the document, the title prefix
4059 will be used by itself as the HTML title.
4060 The man page writer extracts a title, man page section number, and oth‐
4062 er header and footer information from the title line. The title is as‐
4063 sumed to be the first word on the title line, which may optionally end
4064 with a (single-digit) section number in parentheses. (There should be
4065 no space between the title and the parentheses.) Anything after this
4066 is assumed to be additional footer and header text. A single pipe
4067 character (|) should be used to separate the footer text from the head‐
4068 er text. Thus,
4069 % PANDOC(1)
4071 will yield a man page with the title PANDOC and section 1.
4073 % PANDOC(1) Pandoc User Manuals
4075 will also have “Pandoc User Manuals” in the footer.
4077 % PANDOC(1) Pandoc User Manuals | Version 4.0
4079 will also have “Version 4.0” in the header.
4081 Extension: yaml_metadata_block
4083 A YAML metadata block is a valid YAML object, delimited by a line of
4084 three hyphens (---) at the top and a line of three hyphens (---) or
4085 three dots (...) at the bottom. The initial line --- must not be fol‐
4086 lowed by a blank line. A YAML metadata block may occur anywhere in the
4087 document, but if it is not at the beginning, it must be preceded by a
4088 blank line.
4089 Note that, because of the way pandoc concatenates input files when sev‐
4091 eral are provided, you may also keep the metadata in a separate YAML
4092 file and pass it to pandoc as an argument, along with your Markdown
4093 files:
4094 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
4096 Just be sure that the YAML file begins with --- and ends with --- or
4098 .... Alternatively, you can use the --metadata-file option. Using
4099 that approach however, you cannot reference content (like footnotes)
4100 from the main markdown input document.
4101 Metadata will be taken from the fields of the YAML object and added to
4103 any existing document metadata. Metadata can contain lists and objects
4104 (nested arbitrarily), but all string scalars will be interpreted as
4105 Markdown. Fields with names ending in an underscore will be ignored by
4106 pandoc. (They may be given a role by external processors.) Field
4107 names must not be interpretable as YAML numbers or boolean values (so,
4108 for example, yes, True, and 15 cannot be used as field names).
4109 A document may contain multiple metadata blocks. If two metadata
4111 blocks attempt to set the same field, the value from the second block
4112 will be taken.
4113 Each metadata block is handled internally as an independent YAML docu‐
4115 ment. This means, for example, that any YAML anchors defined in a
4116 block cannot be referenced in another block.
4117 When pandoc is used with -t markdown to create a Markdown document, a
4119 YAML metadata block will be produced only if the -s/--standalone option
4120 is used. All of the metadata will appear in a single block at the be‐
4121 ginning of the document.
4122 Note that YAML escaping rules must be followed. Thus, for example, if
4124 a title contains a colon, it must be quoted, and if it contains a back‐
4125 slash escape, then it must be ensured that it is not treated as a YAML
4126 escape sequence. The pipe character (|) can be used to begin an in‐
4127 dented block that will be interpreted literally, without need for es‐
4128 caping. This form is necessary when the field contains blank lines or
4129 block-level formatting:
4130 ---
4132 title: 'This is the title: it contains a colon'
4133 author:
4134 - Author One
4135 - Author Two
4136 keywords: [nothing, nothingness]
4137 abstract: |
4138 This is the abstract.
4139 It consists of two paragraphs.
4141 ...
4142 The literal block after the | must be indented relative to the line
4144 containing the |. If it is not, the YAML will be invalid and pandoc
4145 will not interpret it as metadata. For an overview of the complex
4146 rules governing YAML, see the Wikipedia entry on YAML syntax.
4147 Template variables will be set automatically from the metadata. Thus,
4149 for example, in writing HTML, the variable abstract will be set to the
4150 HTML equivalent of the Markdown in the abstract field:
4151 <p>This is the abstract.</p>
4153 <p>It consists of two paragraphs.</p>
4154 Variables can contain arbitrary YAML structures, but the template must
4156 match this structure. The author variable in the default templates ex‐
4157 pects a simple list or string, but can be changed to support more com‐
4158 plicated structures. The following combination, for example, would add
4159 an affiliation to the author if one is given:
4160 ---
4162 title: The document title
4163 author:
4164 - name: Author One
4165 affiliation: University of Somewhere
4166 - name: Author Two
4167 affiliation: University of Nowhere
4168 ...
4169 To use the structured authors in the example above, you would need a
4171 custom template:
4172 $for(author)$
4174 $if(author.name)$
4175 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
4176 $else$
4177 $author$
4178 $endif$
4179 $endfor$
4180 Raw content to include in the document’s header may be specified using
4182 header-includes; however, it is important to mark up this content as
4183 raw code for a particular output format, using the raw_attribute exten‐
4184 sion, or it will be interpreted as markdown. For example:
4185 header-includes:
4187 - |
4188 ```{=latex}
4189 \let\oldsection\section
4190 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
4191 ```
4192 Note: the yaml_metadata_block extension works with commonmark as well
4194 as markdown (and it is enabled by default in gfm and commonmark_x).
4195 However, in these formats the following restrictions apply:
4196 • The YAML metadata block must occur at the beginning of the document
4198 (and there can be only one). If multiple files are given as argu‐
4199 ments to pandoc, only the first can be a YAML metadata block.
4200 • The leaf nodes of the YAML structure are parsed in isolation from
4202 each other and from the rest of the document. So, for example, you
4203 can’t use a reference link in these contexts if the link definition
4204 is somewhere else in the document.
4205 Backslash escapes
4207 Extension: all_symbols_escapable
4208 Except inside a code block or inline code, any punctuation or space
4209 character preceded by a backslash will be treated literally, even if it
4210 would normally indicate formatting. Thus, for example, if one writes
4211 *\*hello\**
4213 one will get
4215 <em>*hello*</em>
4217 instead of
4219 <strong>hello</strong>
4221 This rule is easier to remember than original Markdown’s rule, which
4223 allows only the following characters to be backslash-escaped:
4224 \`*_{}[]()>#+-.!
4226 (However, if the markdown_strict format is used, the original Markdown
4228 rule will be used.)
4229 A backslash-escaped space is parsed as a nonbreaking space. In TeX
4231 output, it will appear as ~. In HTML and XML output, it will appear as
4232 a literal unicode nonbreaking space character (note that it will thus
4233 actually look “invisible” in the generated HTML source; you can still
4234 use the --ascii command-line option to make it appear as an explicit
4235 entity).
4236 A backslash-escaped newline (i.e. a backslash occurring at the end of a
4238 line) is parsed as a hard line break. It will appear in TeX output as
4239 \\ and in HTML as <br />. This is a nice alternative to Markdown’s
4240 “invisible” way of indicating hard line breaks using two trailing spa‐
4241 ces on a line.
4242 Backslash escapes do not work in verbatim contexts.
4244 Inline formatting
4246 Emphasis
4247 To emphasize some text, surround it with *s or _, like this:
4248 This text is _emphasized with underscores_, and this
4250 is *emphasized with asterisks*.
4251 Double * or _ produces strong emphasis:
4253 This is **strong emphasis** and __with underscores__.
4255 A * or _ character surrounded by spaces, or backslash-escaped, will not
4257 trigger emphasis:
4258 This is * not emphasized *, and \*neither is this\*.
4260 Extension: intraword_underscores
4262 Because _ is sometimes used inside words and identifiers, pandoc does
4263 not interpret a _ surrounded by alphanumeric characters as an emphasis
4264 marker. If you want to emphasize just part of a word, use *:
4265 feas*ible*, not feas*able*.
4267 Strikeout
4269 Extension: strikeout
4270 To strike out a section of text with a horizontal line, begin and end
4271 it with ~~. Thus, for example,
4272 This ~~is deleted text.~~
4274 Superscripts and subscripts
4276 Extension: superscript, subscript
4277 Superscripts may be written by surrounding the superscripted text by ^
4278 characters; subscripts may be written by surrounding the subscripted
4279 text by ~ characters. Thus, for example,
4280 H~2~O is a liquid. 2^10^ is 1024.
4282 The text between ^...^ or ~...~ may not contain spaces or newlines. If
4284 the superscripted or subscripted text contains spaces, these spaces
4285 must be escaped with backslashes. (This is to prevent accidental su‐
4286 perscripting and subscripting through the ordinary use of ~ and ^, and
4287 also bad interactions with footnotes.) Thus, if you want the letter P
4288 with `a cat' in subscripts, use P~a\ cat~, not P~a cat~.
4289 Verbatim
4291 To make a short span of text verbatim, put it inside backticks:
4292 What is the difference between `>>=` and `>>`?
4294 If the verbatim text includes a backtick, use double backticks:
4296 Here is a literal backtick `` ` ``.
4298 (The spaces after the opening backticks and before the closing back‐
4300 ticks will be ignored.)
4301 The general rule is that a verbatim span starts with a string of con‐
4303 secutive backticks (optionally followed by a space) and ends with a
4304 string of the same number of backticks (optionally preceded by a
4305 space).
4306 Note that backslash-escapes (and other Markdown constructs) do not work
4308 in verbatim contexts:
4309 This is a backslash followed by an asterisk: `\*`.
4311 Extension: inline_code_attributes
4313 Attributes can be attached to verbatim text, just as with fenced code
4314 blocks:
4315 `<$>`{.haskell}
4317 Underline
4319 To underline text, use the underline class:
4320 [Underline]{.underline}
4322 Or, without the bracketed_spans extension (but with native_spans):
4324 <span class="underline">Underline</span>
4326 This will work in all output formats that support underline.
4328 Small caps
4330 To write small caps, use the smallcaps class:
4331 [Small caps]{.smallcaps}
4333 Or, without the bracketed_spans extension:
4335 <span class="smallcaps">Small caps</span>
4337 For compatibility with other Markdown flavors, CSS is also supported:
4339 <span style="font-variant:small-caps;">Small caps</span>
4341 This will work in all output formats that support small caps.
4343 Highlighting
4345 To highlight text, use the mark class:
4346 [Mark]{.mark}
4348 Or, without the bracketed_spans extension (but with native_spans):
4350 <span class="mark">Mark</span>
4352 This will work in all output formats that support highlighting.
4354 Math
4356 Extension: tex_math_dollars
4357 Anything between two $ characters will be treated as TeX math. The
4358 opening $ must have a non-space character immediately to its right,
4359 while the closing $ must have a non-space character immediately to its
4360 left, and must not be followed immediately by a digit. Thus, $20,000
4361 and $30,000 won’t parse as math. If for some reason you need to en‐
4362 close text in literal $ characters, backslash-escape them and they
4363 won’t be treated as math delimiters.
4364 For display math, use $$ delimiters. (In this case, the delimiters may
4366 be separated from the formula by whitespace. However, there can be no
4367 blank lines between the opening and closing $$ delimiters.)
4368 TeX math will be printed in all output formats. How it is rendered de‐
4370 pends on the output format:
4371 LaTeX It will appear verbatim surrounded by \(...\) (for inline math)
4373 or \[...\] (for display math).
4374 Markdown, Emacs Org mode, ConTeXt, ZimWiki
4376 It will appear verbatim surrounded by $...$ (for inline math) or
4377 $$...$$ (for display math).
4378 XWiki It will appear verbatim surrounded by {{formula}}..{{/formula}}.
4380 reStructuredText
4382 It will be rendered using an interpreted text role :math:.
4383 AsciiDoc
4385 For AsciiDoc output format (-t asciidoc) it will appear verbatim
4386 surrounded by latexmath:[$...$] (for inline math) or [latex‐
4387 math]++++\[...\]+++ (for display math). For AsciiDoctor output
4388 format (-t asciidoctor) the LaTeX delimiters ($..$ and \[..\])
4389 are omitted.
4390 Texinfo
4392 It will be rendered inside a @math command.
4393 roff man, Jira markup
4395 It will be rendered verbatim without $’s.
4396 MediaWiki, DokuWiki
4398 It will be rendered inside <math> tags.
4399 Textile
4401 It will be rendered inside <span class="math"> tags.
4402 RTF, OpenDocument
4404 It will be rendered, if possible, using Unicode characters, and
4405 will otherwise appear verbatim.
4406 ODT It will be rendered, if possible, using MathML.
4408 DocBook
4410 If the --mathml flag is used, it will be rendered using MathML
4411 in an inlineequation or informalequation tag. Otherwise it will
4412 be rendered, if possible, using Unicode characters.
4413 Docx and PowerPoint
4415 It will be rendered using OMML math markup.
4416 FictionBook2
4418 If the --webtex option is used, formulas are rendered as images
4419 using CodeCogs or other compatible web service, downloaded and
4420 embedded in the e-book. Otherwise, they will appear verbatim.
4421 HTML, Slidy, DZSlides, S5, EPUB
4423 The way math is rendered in HTML will depend on the command-line
4424 options selected. Therefore see Math rendering in HTML above.
4425 Raw HTML
4427 Extension: raw_html
4428 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
4429 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
4430 erally). (Technically this is not an extension, since standard Mark‐
4431 down allows it, but it has been made an extension so that it can be
4432 disabled if desired.)
4433 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
4435 DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile out‐
4436 put, and suppressed in other formats.
4437 For a more explicit way of including raw HTML in a Markdown document,
4439 see the raw_attribute extension.
4440 In the CommonMark format, if raw_html is enabled, superscripts, sub‐
4442 scripts, strikeouts and small capitals will be represented as HTML.
4443 Otherwise, plain-text fallbacks will be used. Note that even if
4444 raw_html is disabled, tables will be rendered with HTML syntax if they
4445 cannot use pipe syntax.
4446 Extension: markdown_in_html_blocks
4448 Original Markdown allows you to include HTML “blocks”: blocks of HTML
4449 between balanced tags that are separated from the surrounding text with
4450 blank lines, and start and end at the left margin. Within these
4451 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
4452 ple), * does not signify emphasis.
4453 Pandoc behaves this way when the markdown_strict format is used; but by
4455 default, pandoc interprets material between HTML block tags as Mark‐
4456 down. Thus, for example, pandoc will turn
4457 <table>
4459 <tr>
4460 <td>*one*</td>
4461 <td>[a link](https://google.com)</td>
4462 </tr>
4463 </table>
4464 into
4466 <table>
4468 <tr>
4469 <td><em>one</em></td>
4470 <td><a href="https://google.com">a link</a></td>
4471 </tr>
4472 </table>
4473 whereas Markdown.pl will preserve it as is.
4475 There is one exception to this rule: text between <script>, <style>,
4477 and <textarea> tags is not interpreted as Markdown.
4478 This departure from original Markdown should make it easier to mix
4480 Markdown with HTML block elements. For example, one can surround a
4481 block of Markdown text with <div> tags without preventing it from being
4482 interpreted as Markdown.
4483 Extension: native_divs
4485 Use native pandoc Div blocks for content inside <div> tags. For the
4486 most part this should give the same output as markdown_in_html_blocks,
4487 but it makes it easier to write pandoc filters to manipulate groups of
4488 blocks.
4489 Extension: native_spans
4491 Use native pandoc Span blocks for content inside <span> tags. For the
4492 most part this should give the same output as raw_html, but it makes it
4493 easier to write pandoc filters to manipulate groups of inlines.
4494 Extension: raw_tex
4496 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
4497 be included in a document. Inline TeX commands will be preserved and
4498 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
4499 you can use LaTeX to include BibTeX citations:
4500 This result was proved in \cite{jones.1967}.
4502 Note that in LaTeX environments, like
4504 \begin{tabular}{|l|l|}\hline
4506 Age & Frequency \\ \hline
4507 18--25 & 15 \\
4508 26--35 & 33 \\
4509 36--45 & 22 \\ \hline
4510 \end{tabular}
4511 the material between the begin and end tags will be interpreted as raw
4513 LaTeX, not as Markdown.
4514 For a more explicit and flexible way of including raw TeX in a Markdown
4516 document, see the raw_attribute extension.
4517 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
4519 Emacs Org mode, and ConTeXt.
4520 Generic raw attribute
4522 Extension: raw_attribute
4523 Inline spans and fenced code blocks with a special kind of attribute
4524 will be parsed as raw content with the designated format. For example,
4525 the following produces a raw roff ms block:
4526 ```{=ms}
4528 .MYMACRO
4529 blah blah
4530 ```
4531 And the following produces a raw html inline element:
4533 This is `<a>html</a>`{=html}
4535 This can be useful to insert raw xml into docx documents, e.g. a page‐
4537 break:
4538 ```{=openxml}
4540 <w:p>
4541 <w:r>
4542 <w:br w:type="page"/>
4543 </w:r>
4544 </w:p>
4545 ```
4546 The format name should match the target format name (see -t/--to,
4548 above, for a list, or use pandoc --list-output-formats). Use openxml
4549 for docx output, opendocument for odt output, html5 for epub3 output,
4550 html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output
4551 (depending on what you use for --pdf-engine).
4552 This extension presupposes that the relevant kind of inline code or
4554 fenced code block is enabled. Thus, for example, to use a raw attri‐
4555 bute with a backtick code block, backtick_code_blocks must be enabled.
4556 The raw attribute cannot be combined with regular attributes.
4558 LaTeX macros
4560 Extension: latex_macros
4561 When this extension is enabled, pandoc will parse LaTeX macro defini‐
4562 tions and apply the resulting macros to all LaTeX math and raw LaTeX.
4563 So, for example, the following will work in all output formats, not
4564 just LaTeX:
4565 \newcommand{\tuple}[1]{\langle #1 \rangle}
4567 $\tuple{a, b, c}$
4569 Note that LaTeX macros will not be applied if they occur inside a raw
4571 span or block marked with the raw_attribute extension.
4572 When latex_macros is disabled, the raw LaTeX and math will not have
4574 macros applied. This is usually a better approach when you are target‐
4575 ing LaTeX or PDF.
4576 Macro definitions in LaTeX will be passed through as raw LaTeX only if
4578 latex_macros is not enabled. Macro definitions in Markdown source (or
4579 other formats allowing raw_tex) will be passed through regardless of
4580 whether latex_macros is enabled.
4581 Links
4583 Markdown allows links to be specified in several ways.
4584 Automatic links
4586 If you enclose a URL or email address in pointy brackets, it will be‐
4587 come a link:
4588 <https://google.com>
4590 <sam@green.eggs.ham>
4591 Inline links
4593 An inline link consists of the link text in square brackets, followed
4594 by the URL in parentheses. (Optionally, the URL can be followed by a
4595 link title, in quotes.)
4596 This is an [inline link](/url), and here's [one with
4598 a title](https://fsf.org "click here for a good time!").
4599 There can be no space between the bracketed part and the parenthesized
4601 part. The link text can contain formatting (such as emphasis), but the
4602 title cannot.
4603 Email addresses in inline links are not autodetected, so they have to
4605 be prefixed with mailto:
4606 [Write me!](mailto:sam@green.eggs.ham)
4608 Reference links
4610 An explicit reference link has two parts, the link itself and the link
4611 definition, which may occur elsewhere in the document (either before or
4612 after the link).
4613 The link consists of link text in square brackets, followed by a label
4615 in square brackets. (There cannot be space between the two unless the
4616 spaced_reference_links extension is enabled.) The link definition con‐
4617 sists of the bracketed label, followed by a colon and a space, followed
4618 by the URL, and optionally (after a space) a link title either in
4619 quotes or in parentheses. The label must not be parseable as a cita‐
4620 tion (assuming the citations extension is enabled): citations take
4621 precedence over link labels.
4622 Here are some examples:
4624 [my label 1]: /foo/bar.html "My title, optional"
4626 [my label 2]: /foo
4627 [my label 3]: https://fsf.org (The Free Software Foundation)
4628 [my label 4]: /bar#special 'A title in single quotes'
4629 The URL may optionally be surrounded by angle brackets:
4631 [my label 5]: <http://foo.bar.baz>
4633 The title may go on the next line:
4635 [my label 3]: https://fsf.org
4637 "The Free Software Foundation"
4638 Note that link labels are not case sensitive. So, this will work:
4640 Here is [my link][FOO]
4642 [Foo]: /bar/baz
4644 In an implicit reference link, the second pair of brackets is empty:
4646 See [my website][].
4648 [my website]: http://foo.bar.baz
4650 Note: In Markdown.pl and most other Markdown implementations, reference
4652 link definitions cannot occur in nested constructions such as list
4653 items or block quotes. Pandoc lifts this arbitrary-seeming restric‐
4654 tion. So the following is fine in pandoc, though not in most other im‐
4655 plementations:
4656 > My block [quote].
4658 >
4659 > [quote]: /foo
4660 Extension: shortcut_reference_links
4662 In a shortcut reference link, the second pair of brackets may be omit‐
4663 ted entirely:
4664 See [my website].
4666 [my website]: http://foo.bar.baz
4668 Internal links
4670 To link to another section of the same document, use the automatically
4671 generated identifier (see Heading identifiers). For example:
4672 See the [Introduction](#introduction).
4674 or
4676 See the [Introduction].
4678 [Introduction]: #introduction
4680 Internal links are currently supported for HTML formats (including HTML
4682 slide shows and EPUB), LaTeX, and ConTeXt.
4683 Images
4685 A link immediately preceded by a ! will be treated as an image. The
4686 link text will be used as the image’s alt text:
4687 
4689 ![movie reel]
4691 [movie reel]: movie.gif
4693 Extension: implicit_figures
4695 An image with nonempty alt text, occurring by itself in a paragraph,
4696 will be rendered as a figure with a caption. The image’s alt text will
4697 be used as the caption.
4698 
4700 How this is rendered depends on the output format. Some output formats
4702 (e.g. RTF) do not yet support figures. In those formats, you’ll just
4703 get an image in a paragraph by itself, with no caption.
4704 If you just want a regular inline image, just make sure it is not the
4706 only thing in the paragraph. One way to do this is to insert a non‐
4707 breaking space after the image:
4708 \
4710 Note that in reveal.js slide shows, an image in a paragraph by itself
4712 that has the r-stretch class will fill the screen, and the caption and
4713 figure tags will be omitted.
4714 Extension: link_attributes
4716 Attributes can be set on links and images:
4717 An inline {#id .class width=30 height=20px}
4719 and a reference ![image][ref] with attributes.
4720 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
4722 (This syntax is compatible with PHP Markdown Extra when only #id and
4724 .class are used.)
4725 For HTML and EPUB, all known HTML5 attributes except width and height
4727 (but including srcset and sizes) are passed through as is. Unknown at‐
4728 tributes are passed through as custom attributes, with data- prepended.
4729 The other writers ignore attributes that are not specifically supported
4730 by their output format.
4731 The width and height attributes on images are treated specially. When
4733 used without a unit, the unit is assumed to be pixels. However, any of
4734 the following unit identifiers can be used: px, cm, mm, in, inch and %.
4735 There must not be any spaces between the number and the unit. For ex‐
4736 ample:
4737 { width=50% }
4739 • Dimensions may be converted to a form that is compatible with the
4741 output format (for example, dimensions given in pixels will be con‐
4742 verted to inches when converting HTML to LaTeX). Conversion between
4743 pixels and physical measurements is affected by the --dpi option (by
4744 default, 96 dpi is assumed, unless the image itself contains dpi in‐
4745 formation).
4746 • The % unit is generally relative to some available space. For exam‐
4748 ple the above example will render to the following.
4749 • HTML: <img href="file.jpg" style="width: 50%;" />
4751 • LaTeX: \includegraphics[width=0.5\textwidth,height=\text‐
4753 height]{file.jpg} (If you’re using a custom template, you need to
4754 configure graphicx as in the default template.)
4755 • ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
4757 • Some output formats have a notion of a class (ConTeXt) or a unique
4759 identifier (LaTeX \caption), or both (HTML).
4760 • When no width or height attributes are specified, the fallback is to
4762 look at the image resolution and the dpi metadata embedded in the im‐
4763 age file.
4764 Divs and Spans
4766 Using the native_divs and native_spans extensions (see above), HTML
4767 syntax can be used as part of markdown to create native Div and Span
4768 elements in the pandoc AST (as opposed to raw HTML). However, there is
4769 also nicer syntax available:
4770 Extension: fenced_divs
4772 Allow special fenced syntax for native Div blocks. A Div starts with a
4773 fence containing at least three consecutive colons plus some at‐
4774 tributes. The attributes may optionally be followed by another string
4775 of consecutive colons.
4776 Note: the commonmark parser doesn’t permit colons after the attributes.
4778 The attribute syntax is exactly as in fenced code blocks (see Exten‐
4780 sion: fenced_code_attributes). As with fenced code blocks, one can use
4781 either attributes in curly braces or a single unbraced word, which will
4782 be treated as a class name. The Div ends with another line containing
4783 a string of at least three consecutive colons. The fenced Div should
4784 be separated by blank lines from preceding and following blocks.
4785 Example:
4787 ::::: {#special .sidebar}
4789 Here is a paragraph.
4790 And another.
4792 :::::
4793 Fenced divs can be nested. Opening fences are distinguished because
4795 they must have attributes:
4796 ::: Warning ::::::
4798 This is a warning.
4799 ::: Danger
4801 This is a warning within a warning.
4802 :::
4803 ::::::::::::::::::
4804 Fences without attributes are always closing fences. Unlike with
4806 fenced code blocks, the number of colons in the closing fence need not
4807 match the number in the opening fence. However, it can be helpful for
4808 visual clarity to use fences of different lengths to distinguish nested
4809 divs from their parents.
4810 Extension: bracketed_spans
4812 A bracketed sequence of inlines, as one would use to begin a link, will
4813 be treated as a Span with attributes if it is followed immediately by
4814 attributes:
4815 [This is *some text*]{.class key="val"}
4817 Footnotes
4819 Extension: footnotes
4820 Pandoc’s Markdown allows footnotes, using the following syntax:
4821 Here is a footnote reference,[^1] and another.[^longnote]
4823 [^1]: Here is the footnote.
4825 [^longnote]: Here's one with multiple blocks.
4827 Subsequent paragraphs are indented to show that they
4829 belong to the previous footnote.
4830 { some.code }
4832 The whole paragraph can be indented, or just the first
4834 line. In this way, multi-paragraph footnotes work like
4835 multi-paragraph list items.
4836 This paragraph won't be part of the note, because it
4838 isn't indented.
4839 The identifiers in footnote references may not contain spaces, tabs, or
4841 newlines. These identifiers are used only to correlate the footnote
4842 reference with the note itself; in the output, footnotes will be num‐
4843 bered sequentially.
4844 The footnotes themselves need not be placed at the end of the document.
4846 They may appear anywhere except inside other block elements (lists,
4847 block quotes, tables, etc.). Each footnote should be separated from
4848 surrounding content (including other footnotes) by blank lines.
4849 Extension: inline_notes
4851 Inline footnotes are also allowed (though, unlike regular notes, they
4852 cannot contain multiple paragraphs). The syntax is as follows:
4853 Here is an inline note.^[Inline notes are easier to write, since
4855 you don't have to pick an identifier and move down to type the
4856 note.]
4857 Inline and regular footnotes may be mixed freely.
4859 Citation syntax
4861 Extension: citations
4862 To cite a bibliographic item with an identifier foo, use the syntax
4863 @foo. Normal citations should be included in square brackets, with
4864 semicolons separating distinct items:
4865 Blah blah [@doe99; @smith2000; @smith2004].
4867 How this is rendered depends on the citation style. In an author-date
4869 style, it might render as
4870 Blah blah (Doe 1999, Smith 2000, 2004).
4872 In a footnote style, it might render as
4874 Blah blah.[^1]
4876 [^1]: John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
4878 Susan Smith, "Flies," *Journal of Insects* (2000);
4879 Susan Smith, "Bees," *Journal of Insects* (2004).
4880 See the CSL user documentation for more information about CSL styles
4882 and how they affect rendering.
4883 Unless a citation key starts with a letter, digit, or _, and contains
4885 only alphanumerics and single internal punctuation characters
4886 (:.#$%&-+?<>~/), it must be surrounded by curly braces, which are not
4887 considered part of the key. In @Foo_bar.baz., the key is Foo_bar.baz
4888 because the final period is not internal punctuation, so it is not in‐
4889 cluded in the key. In @{Foo_bar.baz.}, the key is Foo_bar.baz., in‐
4890 cluding the final period. In @Foo_bar--baz, the key is Foo_bar because
4891 the repeated internal punctuation characters terminate the key. The
4892 curly braces are recommended if you use URLs as keys: [@{https://exam‐
4893 ple.com/bib?name=foobar&date=2000}, p. 33].
4894 Citation items may optionally include a prefix, a locator, and a suf‐
4896 fix. In
4897 Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].
4899 the first item (doe99) has prefix see, locator pp. 33-35, and suffix
4901 and *passim*. The second item (smith04) has locator chap. 1 and no
4902 prefix or suffix.
4903 Pandoc uses some heuristics to separate the locator from the rest of
4905 the subject. It is sensitive to the locator terms defined in the CSL
4906 locale files. Either abbreviated or unabbreviated forms are accepted.
4907 In the en-US locale, locator terms can be written in either singular or
4908 plural forms, as book, bk./bks.; chapter, chap./chaps.; column,
4909 col./cols.; figure, fig./figs.; folio, fol./fols.; number, no./nos.;
4910 line, l./ll.; note, n./nn.; opus, op./opp.; page, p./pp.; paragraph,
4911 para./paras.; part, pt./pts.; section, sec./secs.; sub verbo,
4912 s.v./s.vv.; verse, v./vv.; volume, vol./vols.; ¶/¶¶; §/§§. If no loca‐
4913 tor term is used, “page” is assumed.
4914 In complex cases, you can force something to be treated as a locator by
4916 enclosing it in curly braces or prevent parsing the suffix as locator
4917 by prepending curly braces:
4918 [@smith{ii, A, D-Z}, with a suffix]
4920 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
4921 [@smith{}, 99 years later]
4922 A minus sign (-) before the @ will suppress mention of the author in
4924 the citation. This can be useful when the author is already mentioned
4925 in the text:
4926 Smith says blah [-@smith04].
4928 You can also write an author-in-text citation, by omitting the square
4930 brackets:
4931 @smith04 says blah.
4933 @smith04 [p. 33] says blah.
4935 This will cause the author’s name to be rendered, followed by the bib‐
4937 liographical details. Use this form when you want to make the citation
4938 the subject of a sentence.
4939 When you are using a note style, it is usually better to let citeproc
4941 create the footnotes from citations rather than writing an explicit
4942 note. If you do write an explicit note that contains a citation, note
4943 that normal citations will be put in parentheses, while author-in-text
4944 citations will not. For this reason, it is sometimes preferable to use
4945 the author-in-text style inside notes when using a note style.
4946 Non-default extensions
4948 The following Markdown syntax extensions are not enabled by default in
4949 pandoc, but may be enabled by adding +EXTENSION to the format name,
4950 where EXTENSION is the name of the extension. Thus, for example, mark‐
4951 down+hard_line_breaks is Markdown with hard line breaks.
4952 Extension: rebase_relative_paths
4954 Rewrite relative paths for Markdown links and images, depending on the
4955 path of the file containing the link or image link. For each link or
4956 image, pandoc will compute the directory of the containing file, rela‐
4957 tive to the working directory, and prepend the resulting path to the
4958 link or image path.
4959 The use of this extension is best understood by example. Suppose you
4961 have a subdirectory for each chapter of a book, chap1, chap2, chap3.
4962 Each contains a file text.md and a number of images used in the chap‐
4963 ter. You would like to have  in chap1/text.md re‐
4964 fer to chap1/spider.jpg and  in chap2/text.md refer
4965 to chap2/spider.jpg. To do this, use
4966 pandoc chap*/*.md -f markdown+rebase_relative_paths
4968 Without this extension, you would have to use  in chap1/text.md and  in
4971 chap2/text.md. Links with relative paths will be rewritten in the same
4972 way as images.
4973 Absolute paths and URLs are not changed. Neither are empty paths or
4975 paths consisting entirely of a fragment, e.g., #foo.
4976 Note that relative paths in reference links and images will be rewrit‐
4978 ten relative to the file containing the link reference definition, not
4979 the file containing the reference link or image itself, if these dif‐
4980 fer.
4981 Extension: mark
4983 To highlight out a section of text, begin and end it with with ==.
4984 Thus, for example,
4985 This ==is deleted text.==
4987 Extension: attributes
4989 Allows attributes to be attached to any inline or block-level element
4990 when parsing commonmark. The syntax for the attributes is the same as
4991 that used in header_attributes.
4992 • Attributes that occur immediately after an inline element affect that
4994 element. If they follow a space, then they belong to the space.
4995 (Hence, this option subsumes inline_code_attributes and link_at‐
4996 tributes.)
4997 • Attributes that occur immediately before a block element, on a line
4999 by themselves, affect that element.
5000 • Consecutive attribute specifiers may be used, either for blocks or
5002 for inlines. Their attributes will be combined.
5003 • Attributes that occur at the end of the text of a Setext or ATX head‐
5005 ing (separated by whitespace from the text) affect the heading ele‐
5006 ment. (Hence, this option subsumes header_attributes.)
5007 • Attributes that occur after the opening fence in a fenced code block
5009 affect the code block element. (Hence, this option subsumes
5010 fenced_code_attributes.)
5011 • Attributes that occur at the end of a reference link definition af‐
5013 fect links that refer to that definition.
5014 Note that pandoc’s AST does not currently allow attributes to be at‐
5016 tached to arbitrary elements. Hence a Span or Div container will be
5017 added if needed.
5018 Extension: old_dashes
5020 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - be‐
5021 fore a numeral is an en-dash, and -- is an em-dash. This option only
5022 has an effect if smart is enabled. It is selected automatically for
5023 textile input.
5024 Extension: angle_brackets_escapable
5026 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
5027 vored Markdown but not original Markdown. This is implied by pandoc’s
5028 default all_symbols_escapable.
5029 Extension: lists_without_preceding_blankline
5031 Allow a list to occur right after a paragraph, with no intervening
5032 blank space.
5033 Extension: four_space_rule
5035 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
5036 ces indent are needed for list item continuation paragraphs.
5037 Extension: spaced_reference_links
5039 Allow whitespace between the two components of a reference link, for
5040 example,
5041 [foo] [bar].
5043 Extension: hard_line_breaks
5045 Causes all newlines within a paragraph to be interpreted as hard line
5046 breaks instead of spaces.
5047 Extension: ignore_line_breaks
5049 Causes newlines within a paragraph to be ignored, rather than being
5050 treated as spaces or as hard line breaks. This option is intended for
5051 use with East Asian languages where spaces are not used between words,
5052 but text is divided into lines for readability.
5053 Extension: east_asian_line_breaks
5055 Causes newlines within a paragraph to be ignored, rather than being
5056 treated as spaces or as hard line breaks, when they occur between two
5057 East Asian wide characters. This is a better choice than ig‐
5058 nore_line_breaks for texts that include a mix of East Asian wide char‐
5059 acters and other characters.
5060 Extension: emoji
5062 Parses textual emojis like :smile: as Unicode emoticons.
5063 Extension: tex_math_single_backslash
5065 Causes anything between \( and \) to be interpreted as inline TeX math,
5066 and anything between \[ and \] to be interpreted as display TeX math.
5067 Note: a drawback of this extension is that it precludes escaping ( and
5068 [.
5069 Extension: tex_math_double_backslash
5071 Causes anything between \\( and \\) to be interpreted as inline TeX
5072 math, and anything between \\[ and \\] to be interpreted as display TeX
5073 math.
5074 Extension: markdown_attribute
5076 By default, pandoc interprets material inside block-level tags as Mark‐
5077 down. This extension changes the behavior so that Markdown is only
5078 parsed inside block-level tags if the tags have the attribute mark‐
5079 down=1.
5080 Extension: mmd_title_block
5082 Enables a MultiMarkdown style title block at the top of the document,
5083 for example:
5084 Title: My title
5086 Author: John Doe
5087 Date: September 1, 2008
5088 Comment: This is a sample mmd title block, with
5089 a field spanning multiple lines.
5090 See the MultiMarkdown documentation for details. If pandoc_title_block
5092 or yaml_metadata_block is enabled, it will take precedence over mmd_ti‐
5093 tle_block.
5094 Extension: abbreviations
5096 Parses PHP Markdown Extra abbreviation keys, like
5097 *[HTML]: Hypertext Markup Language
5099 Note that the pandoc document model does not support abbreviations, so
5101 if this extension is enabled, abbreviation keys are simply skipped (as
5102 opposed to being parsed as paragraphs).
5103 Extension: autolink_bare_uris
5105 Makes all absolute URIs into links, even when not surrounded by pointy
5106 braces <...>.
5107 Extension: mmd_link_attributes
5109 Parses multimarkdown style key-value attributes on link and image ref‐
5110 erences. This extension should not be confused with the link_at‐
5111 tributes extension.
5112 This is a reference ![image][ref] with multimarkdown attributes.
5114 [ref]: https://path.to/image "Image title" width=20px height=30px
5116 id=myId class="myClass1 myClass2"
5117 Extension: mmd_header_identifiers
5119 Parses multimarkdown style heading identifiers (in square brackets, af‐
5120 ter the heading but before any trailing #s in an ATX heading).
5121 Extension: compact_definition_lists
5123 Activates the definition list syntax of pandoc 1.12.x and earlier.
5124 This syntax differs from the one described above under Definition lists
5125 in several respects:
5126 • No blank line is required between consecutive items of the definition
5128 list.
5129 • To get a “tight” or “compact” list, omit space between consecutive
5131 items; the space between a term and its definition does not affect
5132 anything.
5133 • Lazy wrapping of paragraphs is not allowed: the entire definition
5135 must be indented four spaces.
5136 Extension: gutenberg
5138 Use Project Gutenberg conventions for plain output: all-caps for strong
5139 emphasis, surround by underscores for regular emphasis, add extra blank
5140 space around headings.
5141 Extension: sourcepos
5143 Include source position attributes when parsing commonmark. For ele‐
5144 ments that accept attributes, a data-pos attribute is added; other ele‐
5145 ments are placed in a surrounding Div or Span element with a data-pos
5146 attribute.
5147 Extension: short_subsuperscripts
5149 Parse multimarkdown style subscripts and superscripts, which start with
5150 a `~' or `^' character, respectively, and include the alphanumeric se‐
5151 quence that follows. For example:
5152 x^2 = 4
5154 or
5156 Oxygen is O~2.
5158 Extension: wikilinks_title_after_pipe
5160 Pandoc supports multiple markdown wikilink syntaxes, regardless of
5161 whether the title is before or after the pipe.
5162 Using --from=markdown+wikilinks_title_after_pipe results in
5164 [[URL|title]]
5166 while using --from=markdown+wikilinks_title_before_pipe results in
5168 [[title|URL]]
5170 Markdown variants
5172 In addition to pandoc’s extended Markdown, the following Markdown vari‐
5173 ants are supported:
5174 • markdown_phpextra (PHP Markdown Extra)
5176 • markdown_github (deprecated GitHub-Flavored Markdown)
5178 • markdown_mmd (MultiMarkdown)
5180 • markdown_strict (Markdown.pl)
5182 • commonmark (CommonMark)
5184 • gfm (Github-Flavored Markdown)
5186 • commonmark_x (CommonMark with many pandoc extensions)
5188 To see which extensions are supported for a given format, and which are
5190 enabled by default, you can use the command
5191 pandoc --list-extensions=FORMAT
5193 where FORMAT is replaced with the name of the format.
5195 Note that the list of extensions for commonmark, gfm, and commonmark_x
5197 are defined relative to default commonmark. So, for example, back‐
5198 tick_code_blocks does not appear as an extension, since it is enabled
5199 by default and cannot be disabled.
5200
5202 When the --citeproc option is used, pandoc can automatically generate
5203 citations and a bibliography in a number of styles. Basic usage is
5204 pandoc --citeproc myinput.txt
5206 To use this feature, you will need to have
5208 • a document containing citations (see Citation syntax);
5210 • a source of bibliographic data: either an external bibliography file
5212 or a list of references in the document’s YAML metadata;
5213 • optionally, a CSL citation style.
5215 Specifying bibliographic data
5217 You can specify an external bibliography using the bibliography metada‐
5218 ta field in a YAML metadata section or the --bibliography command line
5219 argument. If you want to use multiple bibliography files, you can sup‐
5220 ply multiple --bibliography arguments or set bibliography metadata
5221 field to YAML array. A bibliography may have any of these formats:
5222 Format File extension
5224 ---------- ----------------
5225 BibLaTeX .bib
5226 BibTeX .bibtex
5227 CSL JSON .json
5228 CSL YAML .yaml
5229 RIS .ris
5230 Note that .bib can be used with both BibTeX and BibLaTeX files; use the
5232 extension .bibtex to force interpretation as BibTeX.
5233 In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside
5235 fields such as title; in CSL YAML databases, pandoc Markdown; and in
5236 CSL JSON databases, an HTML-like markup:
5237 <i>...</i>
5239 italics
5240 <b>...</b>
5242 bold
5243 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
5245 small capitals
5246 <sub>...</sub>
5248 subscript
5249 <sup>...</sup>
5251 superscript
5252 <span class="nocase">...</span>
5254 prevent a phrase from being capitalized as title case
5255 As an alternative to specifying a bibliography file using --bibliogra‐
5257 phy or the YAML metadata field bibliography, you can include the cita‐
5258 tion data directly in the references field of the document’s YAML meta‐
5259 data. The field should contain an array of YAML-encoded references,
5260 for example:
5261 ---
5263 references:
5264 - type: article-journal
5265 id: WatsonCrick1953
5266 author:
5267 - family: Watson
5268 given: J. D.
5269 - family: Crick
5270 given: F. H. C.
5271 issued:
5272 date-parts:
5273 - - 1953
5274 - 4
5275 - 25
5276 title: 'Molecular structure of nucleic acids: a structure for
5277 deoxyribose nucleic acid'
5278 title-short: Molecular structure of nucleic acids
5279 container-title: Nature
5280 volume: 171
5281 issue: 4356
5282 page: 737-738
5283 DOI: 10.1038/171737a0
5284 URL: https://www.nature.com/articles/171737a0
5285 language: en-GB
5286 ...
5287 If both an external bibliography and inline (YAML metadata) references
5289 are provided, both will be used. In case of conflicting ids, the in‐
5290 line references will take precedence.
5291 Note that pandoc can be used to produce such a YAML metadata section
5293 from a BibTeX, BibLaTeX, or CSL JSON bibliography:
5294 pandoc chem.bib -s -f biblatex -t markdown
5296 pandoc chem.json -s -f csljson -t markdown
5297 Indeed, pandoc can convert between any of these citation formats:
5299 pandoc chem.bib -s -f biblatex -t csljson
5301 pandoc chem.yaml -s -f markdown -t biblatex
5302 Running pandoc on a bibliography file with the --citeproc option will
5304 create a formatted bibliography in the format of your choice:
5305 pandoc chem.bib -s --citeproc -o chem.html
5307 pandoc chem.bib -s --citeproc -o chem.pdf
5308 Capitalization in titles
5310 If you are using a bibtex or biblatex bibliography, then observe the
5311 following rules:
5312 • English titles should be in title case. Non-English titles should be
5314 in sentence case, and the langid field in biblatex should be set to
5315 the relevant language. (The following values are treated as English:
5316 american, british, canadian, english, australian, newzealand, USen‐
5317 glish, or UKenglish.)
5318 • As is standard with bibtex/biblatex, proper names should be protected
5320 with curly braces so that they won’t be lowercased in styles that
5321 call for sentence case. For example:
5322 title = {My Dinner with {Andre}}
5324 • In addition, words that should remain lowercase (or camelCase) should
5326 be protected:
5327 title = {Spin Wave Dispersion on the {nm} Scale}
5329 Though this is not necessary in bibtex/biblatex, it is necessary with
5331 citeproc, which stores titles internally in sentence case, and con‐
5332 verts to title case in styles that require it. Here we protect “nm”
5333 so that it doesn’t get converted to “Nm” at this stage.
5334 If you are using a CSL bibliography (either JSON or YAML), then observe
5336 the following rules:
5337 • All titles should be in sentence case.
5339 • Use the language field for non-English titles to prevent their con‐
5341 version to title case in styles that call for this. (Conversion hap‐
5342 pens only if language begins with en or is left empty.)
5343 • Protect words that should not be converted to title case using this
5345 syntax:
5346 Spin wave dispersion on the <span class="nocase">nm</span> scale
5348 Conference Papers, Published vs. Unpublished
5350 For a formally published conference paper, use the biblatex entry type
5351 inproceedings (which will be mapped to CSL paper-conference).
5352 For an unpublished manuscript, use the biblatex entry type unpublished
5354 without an eventtitle field (this entry type will be mapped to CSL man‐
5355 uscript).
5356 For a talk, an unpublished conference paper, or a poster presentation,
5358 use the biblatex entry type unpublished with an eventtitle field (this
5359 entry type will be mapped to CSL speech). Use the biblatex type field
5360 to indicate the type, e.g. “Paper”, or “Poster”. venue and eventdate
5361 may be useful too, though eventdate will not be rendered by most CSL
5362 styles. Note that venue is for the event’s venue, unlike location
5363 which describes the publisher’s location; do not use the latter for an
5364 unpublished conference paper.
5365 Specifying a citation style
5367 Citations and references can be formatted using any style supported by
5368 the Citation Style Language, listed in the Zotero Style Repository.
5369 These files are specified using the --csl option or the csl (or cita‐
5370 tion-style) metadata field. By default, pandoc will use the Chicago
5371 Manual of Style author-date format. (You can override this default by
5372 copying a CSL style of your choice to default.csl in your user data di‐
5373 rectory.) The CSL project provides further information on finding and
5374 editing styles.
5375 The --citation-abbreviations option (or the citation-abbreviations
5377 metadata field) may be used to specify a JSON file containing abbrevia‐
5378 tions of journals that should be used in formatted bibliographies when
5379 form="short" is specified. The format of the file can be illustrated
5380 with an example:
5381 { "default": {
5383 "container-title": {
5384 "Lloyd's Law Reports": "Lloyd's Rep",
5385 "Estates Gazette": "EG",
5386 "Scots Law Times": "SLT"
5387 }
5388 }
5389 }
5390 Citations in note styles
5392 Pandoc’s citation processing is designed to allow you to move between
5393 author-date, numerical, and note styles without modifying the markdown
5394 source. When you’re using a note style, avoid inserting footnotes man‐
5395 ually. Instead, insert citations just as you would in an author-date
5396 style—for example,
5397 Blah blah [@foo, p. 33].
5399 The footnote will be created automatically. Pandoc will take care of
5401 removing the space and moving the note before or after the period, de‐
5402 pending on the setting of notes-after-punctuation, as described below
5403 in Other relevant metadata fields.
5404 In some cases you may need to put a citation inside a regular footnote.
5406 Normal citations in footnotes (such as [@foo, p. 33]) will be rendered
5407 in parentheses. In-text citations (such as @foo [p. 33]) will be ren‐
5408 dered without parentheses. (A comma will be added if appropriate.)
5409 Thus:
5410 [^1]: Some studies [@foo; @bar, p. 33] show that
5412 frubulicious zoosnaps are quantical. For a survey
5413 of the literature, see @baz [chap. 1].
5414 Placement of the bibliography
5416 If the style calls for a list of works cited, it will be placed in a
5417 div with id refs, if one exists:
5418 ::: {#refs}
5420 :::
5421 Otherwise, it will be placed at the end of the document. Generation of
5423 the bibliography can be suppressed by setting suppress-bibliography:
5424 true in the YAML metadata.
5425 If you wish the bibliography to have a section heading, you can set
5427 reference-section-title in the metadata, or put the heading at the be‐
5428 ginning of the div with id refs (if you are using it) or at the end of
5429 your document:
5430 last paragraph...
5432 # References
5434 The bibliography will be inserted after this heading. Note that the
5436 unnumbered class will be added to this heading, so that the section
5437 will not be numbered.
5438 If you want to put the bibliography into a variable in your template,
5440 one way to do that is to put the div with id refs into a metadata
5441 field, e.g.
5442 ---
5444 refs: |
5445 ::: {#refs}
5446 :::
5447 ...
5448 You can then put the variable $refs$ into your template where you want
5450 the bibliography to be placed.
5451 Including uncited items in the bibliography
5453 If you want to include items in the bibliography without actually cit‐
5454 ing them in the body text, you can define a dummy nocite metadata field
5455 and put the citations there:
5456 ---
5458 nocite: |
5459 @item1, @item2
5460 ...
5461 @item3
5463 In this example, the document will contain a citation for item3 only,
5465 but the bibliography will contain entries for item1, item2, and item3.
5466 It is possible to create a bibliography with all the citations, whether
5468 or not they appear in the document, by using a wildcard:
5469 ---
5471 nocite: |
5472 @*
5473 ...
5474 For LaTeX output, you can also use natbib or biblatex to render the
5476 bibliography. In order to do so, specify bibliography files as out‐
5477 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
5478 tion. Bear in mind that bibliography files have to be in either BibTeX
5479 (for --natbib) or BibLaTeX (for --biblatex) format.
5480 Other relevant metadata fields
5482 A few other metadata fields affect bibliography formatting:
5483 link-citations
5485 If true, citations will be hyperlinked to the corresponding bib‐
5486 liography entries (for author-date and numerical styles only).
5487 Defaults to false.
5488 link-bibliography
5490 If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be
5491 rendered as hyperlinks. (If an entry contains a DOI, PMCID,
5492 PMID, or URL, but none of these fields are rendered by the
5493 style, then the title, or in the absence of a title the whole
5494 entry, will be hyperlinked.) Defaults to true.
5495 lang The lang field will affect how the style is localized, for exam‐
5497 ple in the translation of labels, the use of quotation marks,
5498 and the way items are sorted. (For backwards compatibility, lo‐
5499 cale may be used instead of lang, but this use is deprecated.)
5500 A BCP 47 language tag is expected: for example, en, de, en-US,
5502 fr-CA, ug-Cyrl. The unicode extension syntax (after -u-) may be
5503 used to specify options for collation (sorting) more precisely.
5504 Here are some examples:
5505 • zh-u-co-pinyin – Chinese with the Pinyin collation.
5507 • es-u-co-trad – Spanish with the traditional collation (with Ch
5509 sorting after C).
5510 • fr-u-kb – French with “backwards” accent sorting (with coté
5512 sorting after côte).
5513 • en-US-u-kf-upper – English with uppercase letters sorting be‐
5515 fore lower (default is lower before upper).
5516 notes-after-punctuation
5518 If true (the default for note styles), pandoc will put footnote
5519 references or superscripted numerical citations after following
5520 punctuation. For example, if the source contains blah blah
5521 [@jones99]., the result will look like blah blah.[^1], with the
5522 note moved after the period and the space collapsed. If false,
5523 the space will still be collapsed, but the footnote will not be
5524 moved after the punctuation. The option may also be used in nu‐
5525 merical styles that use superscripts for citation numbers (but
5526 for these styles the default is not to move the citation).
5527
5529 You can use pandoc to produce an HTML + JavaScript slide presentation
5530 that can be viewed via a web browser. There are five ways to do this,
5531 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
5532 duce a PDF slide show using LaTeX beamer, or slide shows in Microsoft
5533 PowerPoint format.
5534 Here’s the Markdown source for a simple slide show, habits.txt:
5536 % Habits
5538 % John Doe
5539 % March 22, 2005
5540 # In the morning
5542 ## Getting up
5544 - Turn off alarm
5546 - Get out of bed
5547 ## Breakfast
5549 - Eat eggs
5551 - Drink coffee
5552 # In the evening
5554 ## Dinner
5556 - Eat spaghetti
5558 - Drink wine
5559 ------------------
5561 
5563 ## Going to sleep
5565 - Get in bed
5567 - Count sheep
5568 To produce an HTML/JavaScript slide show, simply type
5570 pandoc -t FORMAT -s habits.txt -o habits.html
5572 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
5574 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
5576 with the -s/--standalone option embeds a link to JavaScript and CSS
5577 files, which are assumed to be available at the relative path s5/de‐
5578 fault (for S5), slideous (for Slideous), reveal.js (for reveal.js), or
5579 at the Slidy website at w3.org (for Slidy). (These paths can be
5580 changed by setting the slidy-url, slideous-url, revealjs-url, or s5-url
5581 variables; see Variables for HTML slides, above.) For DZSlides, the
5582 (relatively short) JavaScript and CSS are included in the file by de‐
5583 fault.
5584 With all HTML slide formats, the --self-contained option can be used to
5586 produce a single file that contains all of the data necessary to dis‐
5587 play the slide show, including linked scripts, stylesheets, images, and
5588 videos.
5589 To produce a PDF slide show using beamer, type
5591 pandoc -t beamer habits.txt -o habits.pdf
5593 Note that a reveal.js slide show can also be converted to a PDF by
5595 printing it to a file from the browser.
5596 To produce a PowerPoint slide show, type
5598 pandoc habits.txt -o habits.pptx
5600 Structuring the slide show
5602 By default, the slide level is the highest heading level in the hierar‐
5603 chy that is followed immediately by content, and not another heading,
5604 somewhere in the document. In the example above, level-1 headings are
5605 always followed by level-2 headings, which are followed by content, so
5606 the slide level is 2. This default can be overridden using the
5607 --slide-level option.
5608 The document is carved up into slides according to the following rules:
5610 • A horizontal rule always starts a new slide.
5612 • A heading at the slide level always starts a new slide.
5614 • Headings below the slide level in the hierarchy create headings with‐
5616 in a slide. (In beamer, a “block” will be created. If the heading
5617 has the class example, an exampleblock environment will be used; if
5618 it has the class alert, an alertblock will be used; otherwise a regu‐
5619 lar block will be used.)
5620 • Headings above the slide level in the hierarchy create “title
5622 slides,” which just contain the section title and help to break the
5623 slide show into sections. Non-slide content under these headings
5624 will be included on the title slide (for HTML slide shows) or in a
5625 subsequent slide with the same title (for beamer).
5626 • A title page is constructed automatically from the document’s title
5628 block, if present. (In the case of beamer, this can be disabled by
5629 commenting out some lines in the default template.)
5630 These rules are designed to support many different styles of slide
5632 show. If you don’t care about structuring your slides into sections
5633 and subsections, you can either just use level-1 headings for all
5634 slides (in that case, level 1 will be the slide level) or you can set
5635 --slide-level=0.
5636 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
5638 layout will be produced, with level-1 headings building horizontally
5639 and level-2 headings building vertically. It is not recommended that
5640 you use deeper nesting of section levels with reveal.js unless you set
5641 --slide-level=0 (which lets reveal.js produce a one-dimensional layout
5642 and only interprets horizontal rules as slide boundaries).
5643 PowerPoint layout choice
5645 When creating slides, the pptx writer chooses from a number of pre-de‐
5646 fined layouts, based on the content of the slide:
5647 Title Slide
5649 This layout is used for the initial slide, which is generated
5650 and filled from the metadata fields date, author, and title, if
5651 they are present.
5652 Section Header
5654 This layout is used for what pandoc calls “title slides”, i.e.
5655 slides which start with a header which is above the slide level
5656 in the hierarchy.
5657 Two Content
5659 This layout is used for two-column slides, i.e. slides contain‐
5660 ing a div with class columns which contains at least two divs
5661 with class column.
5662 Comparison
5664 This layout is used instead of “Two Content” for any two-column
5665 slides in which at least one column contains text followed by
5666 non-text (e.g. an image or a table).
5667 Content with Caption
5669 This layout is used for any non-two-column slides which contain
5670 text followed by non-text (e.g. an image or a table).
5671 Blank This layout is used for any slides which only contain blank con‐
5673 tent, e.g. a slide containing only speaker notes, or a slide
5674 containing only a non-breaking space.
5675 Title and Content
5677 This layout is used for all slides which do not match the crite‐
5678 ria for another layout.
5679 These layouts are chosen from the default pptx reference doc included
5681 with pandoc, unless an alternative reference doc is specified using
5682 --reference-doc.
5683 Incremental lists
5685 By default, these writers produce lists that display “all at once.” If
5686 you want your lists to display incrementally (one item at a time), use
5687 the -i option. If you want a particular list to depart from the de‐
5688 fault, put it in a div block with class incremental or nonincremental.
5689 So, for example, using the fenced div syntax, the following would be
5690 incremental regardless of the document default:
5691 ::: incremental
5693 - Eat spaghetti
5695 - Drink wine
5696 :::
5698 or
5700 ::: nonincremental
5702 - Eat spaghetti
5704 - Drink wine
5705 :::
5707 While using incremental and nonincremental divs is the recommended
5709 method of setting incremental lists on a per-case basis, an older meth‐
5710 od is also supported: putting lists inside a blockquote will depart
5711 from the document default (that is, it will display incrementally with‐
5712 out the -i option and all at once with the -i option):
5713 > - Eat spaghetti
5715 > - Drink wine
5716 Both methods allow incremental and nonincremental lists to be mixed in
5718 a single document.
5719 If you want to include a block-quoted list, you can work around this
5721 behavior by putting the list inside a fenced div, so that it is not the
5722 direct child of the block quote:
5723 > ::: wrapper
5725 > - a
5726 > - list in a quote
5727 > :::
5728 Inserting pauses
5730 You can add “pauses” within a slide by including a paragraph containing
5731 three dots, separated by spaces:
5732 # Slide with a pause
5734 content before the pause
5736 . . .
5738 content after the pause
5740 Note: this feature is not yet implemented for PowerPoint output.
5742 Styling the slides
5744 You can change the style of HTML slides by putting customized CSS files
5745 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
5746 $DATADIR/slideous (for Slideous), where $DATADIR is the user data di‐
5747 rectory (see --data-dir, above). The originals may be found in pan‐
5748 doc’s system data directory (generally $CABALDIR/pandoc-VERSION/s5/de‐
5749 fault). Pandoc will look there for any files it does not find in the
5750 user data directory.
5751 For dzslides, the CSS is included in the HTML file itself, and may be
5753 modified there.
5754 All reveal.js configuration options can be set through variables. For
5756 example, themes can be used by setting the theme variable:
5757 -V theme=moon
5759 Or you can specify a custom stylesheet using the --css option.
5761 To style beamer slides, you can specify a theme, colortheme, fonttheme,
5763 innertheme, and outertheme, using the -V option:
5764 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
5766 Note that heading attributes will turn into slide attributes (on a
5768 <div> or <section>) in HTML slide formats, allowing you to style indi‐
5769 vidual slides. In beamer, a number of heading classes and attributes
5770 are recognized as frame options and will be passed through as options
5771 to the frame: see Frame attributes in beamer, below.
5772 Speaker notes
5774 Speaker notes are supported in reveal.js, PowerPoint (pptx), and beamer
5775 output. You can add notes to your Markdown document thus:
5776 ::: notes
5778 This is my note.
5780 - It can contain Markdown
5782 - like this list
5783 :::
5785 To show the notes window in reveal.js, press s while viewing the pre‐
5787 sentation. Speaker notes in PowerPoint will be available, as usual, in
5788 handouts and presenter view.
5789 Notes are not yet supported for other slide formats, but the notes will
5791 not appear on the slides themselves.
5792 Columns
5794 To put material in side by side columns, you can use a native div con‐
5795 tainer with class columns, containing two or more div containers with
5796 class column and a width attribute:
5797 :::::::::::::: {.columns}
5799 ::: {.column width="40%"}
5800 contents...
5801 :::
5802 ::: {.column width="60%"}
5803 contents...
5804 :::
5805 ::::::::::::::
5806 Additional columns attributes in beamer
5808 The div containers with classes columns and column can optionally have
5809 an align attribute. The class columns can optionally have a totalwidth
5810 attribute or an onlytextwidth class.
5811 :::::::::::::: {.columns align=center totalwidth=8em}
5813 ::: {.column width="40%"}
5814 contents...
5815 :::
5816 ::: {.column width="60%" align=bottom}
5817 contents...
5818 :::
5819 ::::::::::::::
5820 The align attributes on columns and column can be used with the values
5822 top, top-baseline, center and bottom to vertically align the columns.
5823 It defaults to top in columns.
5824 The totalwidth attribute limits the width of the columns to the given
5826 value.
5827 :::::::::::::: {.columns align=top .onlytextwidth}
5829 ::: {.column width="40%" align=center}
5830 contents...
5831 :::
5832 ::: {.column width="60%"}
5833 contents...
5834 :::
5835 ::::::::::::::
5836 The class onlytextwidth sets the totalwidth to \textwidth.
5838 See Section 12.7 of the Beamer User’s Guide for more details.
5840 Frame attributes in beamer
5842 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
5843 in beamer (for example, when using the minted environment). This can
5844 be forced by adding the fragile class to the heading introducing the
5845 slide:
5846 # Fragile slide {.fragile}
5848 All of the other frame attributes described in Section 8.1 of the Beam‐
5850 er User’s Guide may also be used: allowdisplaybreaks, allowframebreaks,
5851 b, c, s, t, environment, label, plain, shrink, standout, noframenumber‐
5852 ing, squeeze. allowframebreaks is recommended especially for bibli‐
5853 ographies, as it allows multiple slides to be created if the content
5854 overfills the frame:
5855 # References {.allowframebreaks}
5857 In addition, the frameoptions attribute may be used to pass arbitrary
5859 frame options to a beamer slide:
5860 # Heading {frameoptions="squeeze,shrink,customoption=foobar"}
5862 Background in reveal.js, beamer, and pptx
5864 Background images can be added to self-contained reveal.js slide shows,
5865 beamer slide shows, and pptx slide shows.
5866 On all slides (beamer, reveal.js, pptx)
5868 With beamer and reveal.js, the configuration option background-image
5869 can be used either in the YAML metadata block or as a command-line
5870 variable to get the same image on every slide.
5871 Note that for reveal.js, the background-image will be used as a paral‐
5873 laxBackgroundImage (see below).
5874 For pptx, you can use a reference doc in which background images have
5876 been set on the relevant layouts.
5877 parallaxBackgroundImage (reveal.js)
5879 For reveal.js, there is also the reveal.js-native option parallaxBack‐
5880 groundImage, which produces a parallax scrolling background. You must
5881 also set parallaxBackgroundSize, and can optionally set parallaxBack‐
5882 groundHorizontal and parallaxBackgroundVertical to configure the
5883 scrolling behaviour. See the reveal.js documentation for more details
5884 about the meaning of these options.
5885 In reveal.js’s overview mode, the parallaxBackgroundImage will show up
5887 only on the first slide.
5888 On individual slides (reveal.js, pptx)
5890 To set an image for a particular reveal.js or pptx slide, add {back‐
5891 ground-image="/path/to/image"} to the first slide-level heading on the
5892 slide (which may even be empty).
5893 As the HTML writers pass unknown attributes through, other reveal.js
5895 background settings also work on individual slides, including back‐
5896 ground-size, background-repeat, background-color, transition, and tran‐
5897 sition-speed. (The data- prefix will automatically be added.)
5898 Note: data-background-image is also supported in pptx for consistency
5900 with reveal.js – if background-image isn’t found, data-background-image
5901 will be checked.
5902 On the title slide (reveal.js, pptx)
5904 To add a background image to the automatically generated title slide
5905 for reveal.js, use the title-slide-attributes variable in the YAML
5906 metadata block. It must contain a map of attribute names and values.
5907 (Note that the data- prefix is required here, as it isn’t added auto‐
5908 matically.)
5909 For pptx, pass a reference doc with the background image set on the
5911 “Title Slide” layout.
5912 Example (reveal.js)
5914 ---
5915 title: My Slide Show
5916 parallaxBackgroundImage: /path/to/my/background_image.png
5917 title-slide-attributes:
5918 data-background-image: /path/to/title_image.png
5919 data-background-size: contain
5920 ---
5921 ## Slide One
5923 Slide 1 has background_image.png as its background.
5925 ## {background-image="/path/to/special_image.jpg"}
5927 Slide 2 has a special image for its background, even though the heading has no content.
5929
5931 EPUB Metadata
5932 EPUB metadata may be specified using the --epub-metadata option, but if
5933 the source document is Markdown, it is better to use a YAML metadata
5934 block. Here is an example:
5935 ---
5937 title:
5938 - type: main
5939 text: My Book
5940 - type: subtitle
5941 text: An investigation of metadata
5942 creator:
5943 - role: author
5944 text: John Smith
5945 - role: editor
5946 text: Sarah Jones
5947 identifier:
5948 - scheme: DOI
5949 text: doi:10.234234.234/33
5950 publisher: My Press
5951 rights: © 2007 John Smith, CC BY-NC
5952 ibooks:
5953 version: 1.3.4
5954 ...
5955 The following fields are recognized:
5957 identifier
5959 Either a string value or an object with fields text and scheme.
5960 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
5961 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
5962 ISMN-13, ISBN-A, JP, OLCC.
5963 title Either a string value, or an object with fields file-as and
5965 type, or a list of such objects. Valid values for type are
5966 main, subtitle, short, collection, edition, extended.
5967 creator
5969 Either a string value, or an object with fields role, file-as,
5970 and text, or a list of such objects. Valid values for role are
5971 MARC relators, but pandoc will attempt to translate the human-
5972 readable versions (like “author” and “editor”) to the appropri‐
5973 ate marc relators.
5974 contributor
5976 Same format as creator.
5977 date A string value in YYYY-MM-DD format. (Only the year is neces‐
5979 sary.) Pandoc will attempt to convert other common date for‐
5980 mats.
5981 lang (or legacy: language)
5983 A string value in BCP 47 format. Pandoc will default to the lo‐
5984 cal language if nothing is specified.
5985 subject
5987 Either a string value, or an object with fields text, authority,
5988 and term, or a list of such objects. Valid values for authority
5989 are either a reserved authority value (currently AAT, BIC,
5990 BISAC, CLC, DDC, CLIL, EuroVoc, MEDTOP, LCSH, NDC, Thema, UDC,
5991 and WGS) or an absolute IRI identifying a custom scheme. Valid
5992 values for term are defined by the scheme.
5993 description
5995 A string value.
5996 type A string value.
5998 format A string value.
6000 relation
6002 A string value.
6003 coverage
6005 A string value.
6006 rights A string value.
6008 belongs-to-collection
6010 A string value. Identifies the name of a collection to which
6011 the EPUB Publication belongs.
6012 group-position
6014 The group-position field indicates the numeric position in which
6015 the EPUB Publication belongs relative to other works belonging
6016 to the same belongs-to-collection field.
6017 cover-image
6019 A string value (path to cover image).
6020 css (or legacy: stylesheet)
6022 A string value (path to CSS stylesheet).
6023 page-progression-direction
6025 Either ltr or rtl. Specifies the page-progression-direction at‐
6026 tribute for the spine element.
6027 ibooks iBooks-specific metadata, with the following fields:
6029 • version: (string)
6031 • specified-fonts: true|false (default false)
6033 • ipad-orientation-lock: portrait-only|landscape-only
6035 • iphone-orientation-lock: portrait-only|landscape-only
6037 • binding: true|false (default true)
6039 • scroll-axis: vertical|horizontal|default
6041 The epub:type attribute
6043 For epub3 output, you can mark up the heading that corresponds to an
6044 EPUB chapter using the epub:type attribute. For example, to set the
6045 attribute to the value prologue, use this markdown:
6046 # My chapter {epub:type=prologue}
6048 Which will result in:
6050 <body epub:type="frontmatter">
6052 <section epub:type="prologue">
6053 <h1>My chapter</h1>
6054 Pandoc will output <body epub:type="bodymatter">, unless you use one of
6056 the following values, in which case either frontmatter or backmatter
6057 will be output.
6058 epub:type of first section epub:type of body
6060 ---------------------------- -------------------
6061 prologue frontmatter
6062 abstract frontmatter
6063 acknowledgments frontmatter
6064 copyright-page frontmatter
6065 dedication frontmatter
6066 credits frontmatter
6067 keywords frontmatter
6068 imprint frontmatter
6069 contributors frontmatter
6070 other-credits frontmatter
6071 errata frontmatter
6072 revision-history frontmatter
6073 titlepage frontmatter
6074 halftitlepage frontmatter
6075 seriespage frontmatter
6076 foreword frontmatter
6077 preface frontmatter
6078 frontispiece frontmatter
6079 appendix backmatter
6080 colophon backmatter
6081 bibliography backmatter
6082 index backmatter
6083 Linked media
6085 By default, pandoc will download media referenced from any <img>, <au‐
6086 dio>, <video> or <source> element present in the generated EPUB, and
6087 include it in the EPUB container, yielding a completely self-contained
6088 EPUB. If you want to link to external media resources instead, use raw
6089 HTML in your source and add data-external="1" to the tag with the src
6090 attribute. For example:
6091 <audio controls="1">
6093 <source src="https://example.com/music/toccata.mp3"
6094 data-external="1" type="audio/mpeg">
6095 </source>
6096 </audio>
6097 If the input format already is HTML then data-external="1" will work as
6099 expected for <img> elements. Similarly, for Markdown, external images
6100 can be declared with {external=1}. Note that this only
6101 works for images; the other media elements have no native representa‐
6102 tion in pandoc’s AST and require the use of raw HTML.
6103 EPUB styling
6105 By default, pandoc will include some basic styling contained in its
6106 epub.css data file. (To see this, use pandoc --print-default-data-file
6107 epub.css.) To use a different CSS file, just use the --css command
6108 line option. A few inline styles are defined in addition; these are
6109 essential for correct formatting of pandoc’s HTML output.
6110 The document-css variable may be set if the more opinionated styling of
6112 pandoc’s default HTML templates is desired (and in that case the vari‐
6113 ables defined in Variables for HTML may be used to fine-tune the
6114 style).
6115
6117 pandoc -t chunkedhtml will produce a zip archive of linked HTML files,
6118 one for each section of the original document. Internal links will au‐
6119 tomatically be adjusted to point to the right place, images linked to
6120 under the working directory will be incorporated, and navigation links
6121 will be added. In addition, a JSON file sitemap.json will be included
6122 describing the hierarchical structure of the files.
6123 If an output file without an extension is specified, then it will be
6125 interpreted as a directory and the zip archive will be automatically
6126 unpacked into it (unless it already exists, in which case an error will
6127 be raised). Otherwise a .zip file will be produced.
6128 The navigation links can be customized by adjusting the template. By
6130 default, a table of contents is included only on the top page. To in‐
6131 clude it on every page, set the toc variable manually.
6132
6134 When creating a Jupyter notebook, pandoc will try to infer the notebook
6135 structure. Code blocks with the class code will be taken as code
6136 cells, and intervening content will be taken as Markdown cells. At‐
6137 tachments will automatically be created for images in Markdown cells.
6138 Metadata will be taken from the jupyter metadata field. For example:
6139 ---
6141 title: My notebook
6142 jupyter:
6143 nbformat: 4
6144 nbformat_minor: 5
6145 kernelspec:
6146 display_name: Python 2
6147 language: python
6148 name: python2
6149 language_info:
6150 codemirror_mode:
6151 name: ipython
6152 version: 2
6153 file_extension: ".py"
6154 mimetype: "text/x-python"
6155 name: "python"
6156 nbconvert_exporter: "python"
6157 pygments_lexer: "ipython2"
6158 version: "2.7.15"
6159 ---
6160 # Lorem ipsum
6162 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6164 bibendum felis dictum sodales.
6165 ``` code
6167 print("hello")
6168 ```
6169 ## Pyout
6171 ``` code
6173 from IPython.display import HTML
6174 HTML("""
6175 <script>
6176 console.log("hello");
6177 </script>
6178 <b>HTML</b>
6179 """)
6180 ```
6181 ## Image
6183 This image  will be
6185 included as a cell attachment.
6186 If you want to add cell attributes, group cells differently, or add
6188 output to code cells, then you need to include divs to indicate the
6189 structure. You can use either fenced divs or native divs for this.
6190 Here is an example:
6191 :::::: {.cell .markdown}
6193 # Lorem
6194 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6196 bibendum felis dictum sodales.
6197 ::::::
6198 :::::: {.cell .code execution_count=1}
6200 ``` {.python}
6201 print("hello")
6202 ```
6203 ::: {.output .stream .stdout}
6205 ```
6206 hello
6207 ```
6208 :::
6209 ::::::
6210 :::::: {.cell .code execution_count=2}
6212 ``` {.python}
6213 from IPython.display import HTML
6214 HTML("""
6215 <script>
6216 console.log("hello");
6217 </script>
6218 <b>HTML</b>
6219 """)
6220 ```
6221 ::: {.output .execute_result execution_count=2}
6223 ```{=html}
6224 <script>
6225 console.log("hello");
6226 </script>
6227 <b>HTML</b>
6228 hello
6229 ```
6230 :::
6231 ::::::
6232 If you include raw HTML or TeX in an output cell, use the raw attri‐
6234 bute, as shown in the last cell of the example above. Although pandoc
6235 can process “bare” raw HTML and TeX, the result is often interspersed
6236 raw elements and normal textual elements, and in an output cell pandoc
6237 expects a single, connected raw block. To avoid using raw HTML or TeX
6238 except when marked explicitly using raw attributes, we recommend speci‐
6239 fying the extensions -raw_html-raw_tex+raw_attribute when translating
6240 between Markdown and ipynb notebooks.
6241 Note that options and extensions that affect reading and writing of
6243 Markdown will also affect Markdown cells in ipynb notebooks. For exam‐
6244 ple, --wrap=preserve will preserve soft line breaks in Markdown cells;
6245 --markdown-headings=setext will cause Setext-style headings to be used;
6246 and --preserve-tabs will prevent tabs from being turned to spaces.
6247
6249 Pandoc will automatically highlight syntax in fenced code blocks that
6250 are marked with a language name. The Haskell library skylighting is
6251 used for highlighting. Currently highlighting is supported only for
6252 HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language
6253 names that pandoc will recognize, type pandoc --list-highlight-lan‐
6254 guages.
6255 The color scheme can be selected using the --highlight-style option.
6257 The default color scheme is pygments, which imitates the default color
6258 scheme used by the Python library pygments (though pygments is not ac‐
6259 tually used to do the highlighting). To see a list of highlight
6260 styles, type pandoc --list-highlight-styles.
6261 If you are not satisfied with the predefined styles, you can use
6263 --print-highlight-style to generate a JSON .theme file which can be
6264 modified and used as the argument to --highlight-style. To get a JSON
6265 version of the pygments style, for example:
6266 pandoc --print-highlight-style pygments > my.theme
6268 Then edit my.theme and use it like this:
6270 pandoc --highlight-style my.theme
6272 If you are not satisfied with the built-in highlighting, or you want to
6274 highlight a language that isn’t supported, you can use the --syntax-
6275 definition option to load a KDE-style XML syntax definition file. Be‐
6276 fore writing your own, have a look at KDE’s repository of syntax defi‐
6277 nitions.
6278 To disable highlighting, use the --no-highlight option.
6280
6282 Custom styles can be used in the docx and ICML formats.
6283 Output
6285 By default, pandoc’s docx and ICML output applies a predefined set of
6286 styles for blocks such as paragraphs and block quotes, and uses largely
6287 default formatting (italics, bold) for inlines. This will work for
6288 most purposes, especially alongside a reference.docx file. However, if
6289 you need to apply your own styles to blocks, or match a preexisting set
6290 of styles, pandoc allows you to define custom styles for blocks and
6291 text using divs and spans, respectively.
6292 If you define a div or span with the attribute custom-style, pandoc
6294 will apply your specified style to the contained elements (with the ex‐
6295 ception of elements whose function depends on a style, like headings,
6296 code blocks, block quotes, or links). So, for example, using the
6297 bracketed_spans syntax,
6298 [Get out]{custom-style="Emphatically"}, he said.
6300 would produce a docx file with “Get out” styled with character style
6302 Emphatically. Similarly, using the fenced_divs syntax,
6303 Dickinson starts the poem simply:
6305 ::: {custom-style="Poetry"}
6307 | A Bird came down the Walk---
6308 | He did not know I saw---
6309 :::
6310 would style the two contained lines with the Poetry paragraph style.
6312 For docx output, styles will be defined in the output file as inherit‐
6314 ing from normal text, if the styles are not yet in your reference.docx.
6315 If they are already defined, pandoc will not alter the definition.
6316 This feature allows for greatest customization in conjunction with pan‐
6318 doc filters. If you want all paragraphs after block quotes to be in‐
6319 dented, you can write a filter to apply the styles necessary. If you
6320 want all italics to be transformed to the Emphasis character style
6321 (perhaps to change their color), you can write a filter which will
6322 transform all italicized inlines to inlines within an Emphasis custom-
6323 style span.
6324 For docx output, you don’t need to enable any extensions for custom
6326 styles to work.
6327 Input
6329 The docx reader, by default, only reads those styles that it can con‐
6330 vert into pandoc elements, either by direct conversion or interpreting
6331 the derivation of the input document’s styles.
6332 By enabling the styles extension in the docx reader (-f docx+styles),
6334 you can produce output that maintains the styles of the input document,
6335 using the custom-style class. Paragraph styles are interpreted as di‐
6336 vs, while character styles are interpreted as spans.
6337 For example, using the custom-style-reference.docx file in the test di‐
6339 rectory, we have the following different outputs:
6340 Without the +styles extension:
6342 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
6344 This is some text.
6345 This is text with an *emphasized* text style. And this is text with a
6347 **strengthened** text style.
6348 > Here is a styled paragraph that inherits from Block Text.
6350 And with the extension:
6352 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
6354 ::: {custom-style="First Paragraph"}
6356 This is some text.
6357 :::
6358 ::: {custom-style="Body Text"}
6360 This is text with an [emphasized]{custom-style="Emphatic"} text style.
6361 And this is text with a [strengthened]{custom-style="Strengthened"}
6362 text style.
6363 :::
6364 ::: {custom-style="My Block Style"}
6366 > Here is a styled paragraph that inherits from Block Text.
6367 :::
6368 With these custom styles, you can use your input document as a refer‐
6370 ence-doc while creating docx output (see below), and maintain the same
6371 styles in your input and output files.
6372
6374 Pandoc can be extended with custom readers and writers written in Lua.
6375 (Pandoc includes a Lua interpreter, so Lua need not be installed sepa‐
6376 rately.)
6377 To use a custom reader or writer, simply specify the path to the Lua
6379 script in place of the input or output format. For example:
6380 pandoc -t data/sample.lua
6382 pandoc -f my_custom_markup_language.lua -t latex -s
6383 If the script is not found relative to the working directory, it will
6385 be sought in the custom subdirectory of the user data directory (see
6386 --data-dir).
6387 A custom reader is a Lua script that defines one function, Reader,
6389 which takes a string as input and returns a Pandoc AST. See the Lua
6390 filters documentation for documentation of the functions that are
6391 available for creating pandoc AST elements. For parsing, the lpeg
6392 parsing library is available by default. To see a sample custom read‐
6393 er:
6394 pandoc --print-default-data-file creole.lua
6396 If you want your custom reader to have access to reader options
6398 (e.g. the tab stop setting), you give your Reader function a second op‐
6399 tions parameter.
6400 A custom writer is a Lua script that defines a function that specifies
6402 how to render each element in a Pandoc AST. See the djot-writer.lua
6403 for a full-featured example.
6404 Note that custom writers have no default template. If you want to use
6406 --standalone with a custom writer, you will need to specify a template
6407 manually using --template or add a new default template with the name
6408 default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your
6409 user data directory (see Templates).
6410
6412 Some of the document formats pandoc targets (such as EPUB, docx, and
6413 ODT) include build timestamps in the generated document. That means
6414 that the files generated on successive builds will differ, even if the
6415 source does not. To avoid this, set the SOURCE_DATE_EPOCH environment
6416 variable, and the timestamp will be taken from it instead of the cur‐
6417 rent time. SOURCE_DATE_EPOCH should contain an integer unix timestamp
6418 (specifying the number of seconds since midnight UTC January 1, 1970).
6419 Some document formats also include a unique identifier. For EPUB, this
6421 can be set explicitly by setting the identifier metadata field (see
6422 EPUB Metadata, above).
6423
6425 PDF is a flexible format, and using PDF in certain contexts requires
6426 additional conventions. For example, PDFs are not accessible by de‐
6427 fault; they define how characters are placed on a page but do not con‐
6428 tain semantic information on the content. However, it is possible to
6429 generate accessible PDFs, which use tagging to add semantic information
6430 to the document.
6431 Pandoc defaults to LaTeX to generate PDF. Tagging support in LaTeX is
6433 in development and not readily available, so PDFs generated in this way
6434 will always be untagged and not accessible. This means that alterna‐
6435 tive engines must be used to generate accessible PDFs.
6436 The PDF standards PDF/A and PDF/UA define further restrictions intended
6438 to optimize PDFs for archiving and accessibility. Tagging is commonly
6439 used in combination with these standards to ensure best results.
6440 Note, however, that standard compliance depends on many things, includ‐
6442 ing the colorspace of embedded images. Pandoc cannot check this, and
6443 external programs must be used to ensure that generated PDFs are in
6444 compliance.
6445 ConTeXt
6447 ConTeXt always produces tagged PDFs, but the quality depends on the in‐
6448 put. The default ConTeXt markup generated by pandoc is optimized for
6449 readability and reuse, not tagging. Enable the tagging format exten‐
6450 sion to force markup that is optimized for tagging. This can be com‐
6451 bined with the pdfa variable to generate standard-compliant PDFs.
6452 E.g.:
6453 pandoc --to=context+tagging -V pdfa=3a
6455 A recent context version should be used, as older versions contained a
6457 bug that lead to invalid PDF metadata.
6458 WeasyPrint
6460 The HTML-based engine WeasyPrint includes experimental support for
6461 PDF/A and PDF/UA since version 57. Tagged PDFs can created with
6462 pandoc --pdf-engine=weasyprint \
6464 --pdf-engine-opt=--pdf-variant=pdf/ua-1 ...
6465 The feature is experimental and standard compliance should not be as‐
6467 sumed.
6468 Prince XML
6470 The non-free HTML-to-PDf converter prince has extensive support for
6471 various PDF standards as well as tagging. E.g.:
6472 pandoc --pdf-engine=prince \
6474 --pdf-engine-opt=--tagged-pdf ...
6475 See the prince documentation for more info.
6477 Word Processors
6479 Word processors like LibreOffice and MS Word can also be used to gener‐
6480 ate standardized and tagged PDF output. Pandoc does not support direct
6481 conversions via these tools. However, pandoc can convert a document to
6482 a docx or odt file, which can then be opened and converted to PDF with
6483 the respective word processor. See the documentation for Word and Li‐
6484 breOffice.
6485
6487 If you rename (or symlink) the pandoc executable to pandoc-server, or
6488 if you call pandoc with server as the first argument, it will start up
6489 a web server with a JSON API. This server exposes most of the conver‐
6490 sion functionality of pandoc. For full documentation, see the pandoc-
6491 server man page.
6492 If you rename (or symlink) the pandoc executable to pandoc-server.cgi,
6494 it will function as a CGI program exposing the same API as pandoc-serv‐
6495 er.
6496 pandoc-server is designed to be maximally secure; it uses Haskell’s
6498 type system to provide strong guarantees that no I/O will be performed
6499 on the server during pandoc conversions.
6500
6502 Calling the pandoc executable under the name pandoc-lua or with lua as
6503 the first argument will make it function as a standalone Lua inter‐
6504 preter. The behavior is mostly identical to that of the standalone lua
6505 executable, version 5.4. However, there is no REPL yet, and the -i op‐
6506 tion has no effect. For full documentation, see the pandoc-lua man
6507 page.
6508
6510 1. Although pandoc itself will not create or modify any files other
6511 than those you explicitly ask it create (with the exception of tem‐
6512 porary files used in producing PDFs), a filter or custom writer
6513 could in principle do anything on your file system. Please audit
6514 filters and custom writers very carefully before using them.
6515 2. Several input formats (including HTML, Org, and RST) support include
6517 directives that allow the contents of a file to be included in the
6518 output. An untrusted attacker could use these to view the contents
6519 of files on the file system. (Using the --sandbox option can pro‐
6520 tect against this threat.)
6521 3. Several output formats (including RTF, FB2, HTML with --self-con‐
6523 tained, EPUB, Docx, and ODT) will embed encoded or raw images into
6524 the output file. An untrusted attacker could exploit this to view
6525 the contents of non-image files on the file system. (Using the
6526 --sandbox option can protect against this threat, but will also pre‐
6527 vent including images in these formats.)
6528 4. If your application uses pandoc as a Haskell library (rather than
6530 shelling out to the executable), it is possible to use it in a mode
6531 that fully isolates pandoc from your file system, by running the
6532 pandoc operations in the PandocPure monad. See the document Using
6533 the pandoc API for more details. (This corresponds to the use of
6534 the --sandbox option on the command line.)
6535 5. Pandoc’s parsers can exhibit pathological performance on some corner
6537 cases. It is wise to put any pandoc operations under a timeout, to
6538 avoid DOS attacks that exploit these issues. If you are using the
6539 pandoc executable, you can add the command line options +RTS -M512M
6540 -RTS (for example) to limit the heap size to 512MB. Note that the
6541 commonmark parser (including commonmark_x and gfm) is much less vul‐
6542 nerable to pathological performance than the markdown parser, so it
6543 is a better choice when processing untrusted input.
6544 6. The HTML generated by pandoc is not guaranteed to be safe. If
6546 raw_html is enabled for the Markdown input, users can inject arbi‐
6547 trary HTML. Even if raw_html is disabled, users can include danger‐
6548 ous content in URLs and attributes. To be safe, you should run all
6549 HTML generated from untrusted user input through an HTML sanitizer.
6550
6552 Copyright 2006–2022 John MacFarlane (jgm@berkeley.edu). Released under
6553 the GPL, version 2 or greater. This software carries no warranty of
6554 any kind. (See COPYRIGHT for full copyright and warranty notices.)
6555 For a full list of contributors, see the file AUTHORS.md in the pandoc
6556 source code.
6557 The Pandoc source code may be downloaded from <https://hack‐
6559 age.haskell.org/package/pandoc> or <https://github.com/jgm/pandoc/re‐
6560 leases>. Further documentation is available at <https://pandoc.org>.
6561pandoc 3.1.3 June 6, 2023 Pandoc User’s Guide()