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, ifxetex, ifluatex, listings (if the --listings option is
130 used), fancyvrb, longtable, booktabs, graphicx (if the document con‐
131 tains images), hyperref, xcolor, ulem, geometry (with the geometry
132 variable set), setspace (with linestretch), and babel (with lang). The
133 use of xelatex or lualatex as the PDF engine requires fontspec. xela‐
134 tex uses polyglossia (with lang), xecjk, and bidi (with the dir vari‐
135 able set). If the mathspec variable is set, xelatex will use mathspec
136 instead of unicode-math. The upquote and microtype packages are used
137 if available, and csquotes will be used for typography if the csquotes
138 variable or metadata field is set to a true value. The natbib, bibla‐
139 tex, bibtex, and biber packages can optionally be used for citation
140 rendering. The following packages will be used to improve output qual‐
141 ity if present, but pandoc does not require them to be present: upquote
142 (for straight quotes in verbatim environments), microtype (for better
143 spacing adjustments), parskip (for better inter-paragraph spaces), xurl
144 (for better line breaks in URLs), bookmark (for better PDF bookmarks),
145 and footnotehyper or footnote (to allow footnotes in tables).
146 Reading from the Web
148 Instead of an input file, an absolute URI may be given. In this case
149 pandoc will fetch the content using HTTP:
150 pandoc -f html -t markdown https://www.fsf.org
152 It is possible to supply a custom User-Agent string or other header
154 when requesting a document from a URL:
155 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
157 https://www.fsf.org
158
160 General options
161 -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
162 Specify input format. FORMAT can be:
163 · commonmark (CommonMark Markdown)
165 · creole (Creole 1.0)
167 · csv (CSV table)
169 · docbook (DocBook)
171 · docx (Word docx)
173 · dokuwiki (DokuWiki markup)
175 · epub (EPUB)
177 · fb2 (FictionBook2 e-book)
179 · gfm (GitHub-Flavored Markdown), or the deprecated and less ac‐
181 curate markdown_github; use markdown_github only if you need
182 extensions not supported in gfm.
183 · haddock (Haddock markup)
185 · html (HTML)
187 · ipynb (Jupyter notebook)
189 · jats (JATS XML)
191 · jira (Jira wiki markup)
193 · json (JSON version of native AST)
195 · latex (LaTeX)
197 · markdown (Pandoc's Markdown)
199 · markdown_mmd (MultiMarkdown)
201 · markdown_phpextra (PHP Markdown Extra)
203 · markdown_strict (original unextended Markdown)
205 · mediawiki (MediaWiki markup)
207 · man (roff man)
209 · muse (Muse)
211 · native (native Haskell)
213 · odt (ODT)
215 · opml (OPML)
217 · org (Emacs Org mode)
219 · rst (reStructuredText)
221 · t2t (txt2tags)
223 · textile (Textile)
225 · tikiwiki (TikiWiki markup)
227 · twiki (TWiki markup)
229 · vimwiki (Vimwiki)
231 Extensions can be individually enabled or disabled by appending
233 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
234 low, for a list of extensions and their names. See --list-in‐
235 put-formats and --list-extensions, below.
236 -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
238 Specify output format. FORMAT can be:
239 · asciidoc (AsciiDoc) or asciidoctor (AsciiDoctor)
241 · beamer (LaTeX beamer slide show)
243 · commonmark (CommonMark Markdown)
245 · context (ConTeXt)
247 · docbook or docbook4 (DocBook 4)
249 · docbook5 (DocBook 5)
251 · docx (Word docx)
253 · dokuwiki (DokuWiki markup)
255 · epub or epub3 (EPUB v3 book)
257 · epub2 (EPUB v2)
259 · fb2 (FictionBook2 e-book)
261 · gfm (GitHub-Flavored Markdown), or the deprecated and less ac‐
263 curate markdown_github; use markdown_github only if you need
264 extensions not supported in gfm.
265 · haddock (Haddock markup)
267 · html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
269 · html4 (XHTML 1.0 Transitional)
271 · icml (InDesign ICML)
273 · ipynb (Jupyter notebook)
275 · jats_archiving (JATS XML, Archiving and Interchange Tag Set)
277 · jats_articleauthoring (JATS XML, Article Authoring Tag Set)
279 · jats_publishing (JATS XML, Journal Publishing Tag Set)
281 · jats (alias for jats_archiving)
283 · jira (Jira wiki markup)
285 · json (JSON version of native AST)
287 · latex (LaTeX)
289 · man (roff man)
291 · markdown (Pandoc's Markdown)
293 · markdown_mmd (MultiMarkdown)
295 · markdown_phpextra (PHP Markdown Extra)
297 · markdown_strict (original unextended Markdown)
299 · mediawiki (MediaWiki markup)
301 · ms (roff ms)
303 · muse (Muse),
305 · native (native Haskell),
307 · odt (OpenOffice text document)
309 · opml (OPML)
311 · opendocument (OpenDocument)
313 · org (Emacs Org mode)
315 · pdf (PDF)
317 · plain (plain text),
319 · pptx (PowerPoint slide show)
321 · rst (reStructuredText)
323 · rtf (Rich Text Format)
325 · texinfo (GNU Texinfo)
327 · textile (Textile)
329 · slideous (Slideous HTML and JavaScript slide show)
331 · slidy (Slidy HTML and JavaScript slide show)
333 · dzslides (DZSlides HTML5 + JavaScript slide show),
335 · revealjs (reveal.js HTML5 + JavaScript slide show)
337 · s5 (S5 HTML and JavaScript slide show)
339 · tei (TEI Simple)
341 · xwiki (XWiki markup)
343 · zimwiki (ZimWiki markup)
345 · the path of a custom Lua writer, see Custom writers below
347 Note that odt, docx, epub, and pdf output will not be directed
349 to stdout unless forced with -o -.
350 Extensions can be individually enabled or disabled by appending
352 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
353 low, for a list of extensions and their names. See --list-out‐
354 put-formats and --list-extensions, below.
355 -o FILE, --output=FILE
357 Write output to FILE instead of stdout. If FILE is -, output
358 will go to stdout, even if a non-textual format (docx, odt,
359 epub2, epub3) is specified.
360 --data-dir=DIRECTORY
362 Specify the user data directory to search for pandoc data files.
363 If this option is not specified, the default user data directory
364 will be used. On *nix and macOS systems this will be the pandoc
365 subdirectory of the XDG data directory (by default, $HOME/.lo‐
366 cal/share, overridable by setting the XDG_DATA_HOME environment
367 variable). If that directory does not exist, $HOME/.pandoc will
368 be used (for backwards compatibility). In Windows the default
369 user data directory is C:\Users\USERNAME\AppData\Roaming\pandoc.
370 You can find the default user data directory on your system by
371 looking at the output of pandoc --version. A reference.odt,
372 reference.docx, epub.css, templates, slidy, slideous, or s5 di‐
373 rectory placed in this directory will override pandoc's normal
374 defaults.
375 -d FILE, --defaults=FILE
377 Specify a set of default option settings. FILE is a YAML file
378 whose fields correspond to command-line option settings. All
379 options for document conversion, including input and output
380 files, can be set using a defaults file. The file will be
381 searched for first in the working directory, and then in the de‐
382 faults subdirectory of the user data directory (see --data-dir).
383 The .yaml extension may be omitted. See the section Default
384 files for more information on the file format. Settings from
385 the defaults file may be overridden or extended by subsequent
386 options on the command line.
387 --bash-completion
389 Generate a bash completion script. To enable bash completion
390 with pandoc, add this to your .bashrc:
391 eval "$(pandoc --bash-completion)"
393 --verbose
395 Give verbose debugging output. Currently this only has an ef‐
396 fect with PDF output.
397 --quiet
399 Suppress warning messages.
400 --fail-if-warnings
402 Exit with error status if there are any warnings.
403 --log=FILE
405 Write log messages in machine-readable JSON format to FILE. All
406 messages above DEBUG level will be written, regardless of ver‐
407 bosity settings (--verbose, --quiet).
408 --list-input-formats
410 List supported input formats, one per line.
411 --list-output-formats
413 List supported output formats, one per line.
414 --list-extensions[=FORMAT]
416 List supported extensions for FORMAT, one per line, preceded by
417 a + or - indicating whether it is enabled by default in FORMAT.
418 If FORMAT is not specified, defaults for pandoc's Markdown are
419 given.
420 --list-highlight-languages
422 List supported languages for syntax highlighting, one per line.
423 --list-highlight-styles
425 List supported styles for syntax highlighting, one per line.
426 See --highlight-style.
427 -v, --version
429 Print version.
430 -h, --help
432 Show usage message.
433 Reader options
435 --shift-heading-level-by=NUMBER
436 Shift heading levels by a positive or negative integer. For ex‐
437 ample, with --shift-heading-level-by=-1, level 2 headings become
438 level 1 headings, and level 3 headings become level 2 headings.
439 Headings cannot have a level less than 1, so a heading that
440 would be shifted below level 1 becomes a regular paragraph. Ex‐
441 ception: with a shift of -N, a level-N heading at the beginning
442 of the document replaces the metadata title. --shift-heading-
443 level-by=-1 is a good choice when converting HTML or Markdown
444 documents that use an initial level-1 heading for the document
445 title and level-2+ headings for sections. --shift-heading-lev‐
446 el-by=1 may be a good choice for converting Markdown documents
447 that use level-1 headings for sections to HTML, since pandoc us‐
448 es a level-1 heading to render the document title.
449 --base-header-level=NUMBER
451 Deprecated. Use --shift-heading-level-by=X instead, where X =
452 NUMBER - 1. Specify the base level for headings (defaults to 1).
453 --strip-empty-paragraphs
455 Deprecated. Use the +empty_paragraphs extension instead. Ignore
456 paragraphs with no content. This option is useful for convert‐
457 ing word processing documents where users have used empty para‐
458 graphs to create inter-paragraph space.
459 --indented-code-classes=CLASSES
461 Specify classes to use for indented code blocks--for example,
462 perl,numberLines or haskell. Multiple classes may be separated
463 by spaces or commas.
464 --default-image-extension=EXTENSION
466 Specify a default extension to use when image paths/URLs have no
467 extension. This allows you to use the same source for formats
468 that require different kinds of images. Currently this option
469 only affects the Markdown and LaTeX readers.
470 --file-scope
472 Parse each file individually before combining for multifile doc‐
473 uments. This will allow footnotes in different files with the
474 same identifiers to work as expected. If this option is set,
475 footnotes and links will not work across files. Reading binary
476 files (docx, odt, epub) implies --file-scope.
477 -F PROGRAM, --filter=PROGRAM
479 Specify an executable to be used as a filter transforming the
480 pandoc AST after the input is parsed and before the output is
481 written. The executable should read JSON from stdin and write
482 JSON to stdout. The JSON must be formatted like pandoc's own
483 JSON input and output. The name of the output format will be
484 passed to the filter as the first argument. Hence,
485 pandoc --filter ./caps.py -t latex
487 is equivalent to
489 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
491 The latter form may be useful for debugging filters.
493 Filters may be written in any language. Text.Pandoc.JSON ex‐
495 ports toJSONFilter to facilitate writing filters in Haskell.
496 Those who would prefer to write filters in python can use the
497 module pandocfilters, installable from PyPI. There are also
498 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
499 In order of preference, pandoc will look for filters in
501 1. a specified full or relative path (executable or non-exe‐
503 cutable)
504 2. $DATADIR/filters (executable or non-executable) where
506 $DATADIR is the user data directory (see --data-dir, above).
507 3. $PATH (executable only)
509 Filters and Lua-filters are applied in the order specified on
511 the command line.
512 -L SCRIPT, --lua-filter=SCRIPT
514 Transform the document in a similar fashion as JSON filters (see
515 --filter), but use pandoc's build-in Lua filtering system. The
516 given Lua script is expected to return a list of Lua filters
517 which will be applied in order. Each Lua filter must contain
518 element-transforming functions indexed by the name of the AST
519 element on which the filter function should be applied.
520 The pandoc Lua module provides helper functions for element cre‐
522 ation. It is always loaded into the script's Lua environment.
523 The following is an example Lua script for macro-expansion:
525 function expand_hello_world(inline)
527 if inline.c == '{{helloworld}}' then
528 return pandoc.Emph{ pandoc.Str "Hello, World" }
529 else
530 return inline
531 end
532 end
533 return {{Str = expand_hello_world}}
535 In order of preference, pandoc will look for Lua filters in
537 1. a specified full or relative path (executable or non-exe‐
539 cutable)
540 2. $DATADIR/filters (executable or non-executable) where
542 $DATADIR is the user data directory (see --data-dir, above).
543 -M KEY[=VAL], --metadata=KEY[:VAL]
545 Set the metadata field KEY to the value VAL. A value specified
546 on the command line overrides a value specified in the document
547 using YAML metadata blocks. Values will be parsed as YAML bool‐
548 ean or string values. If no value is specified, the value will
549 be treated as Boolean true. Like --variable, --metadata causes
550 template variables to be set. But unlike --variable, --metadata
551 affects the metadata of the underlying document (which is acces‐
552 sible from filters and may be printed in some output formats)
553 and metadata values will be escaped when inserted into the tem‐
554 plate.
555 --metadata-file=FILE
557 Read metadata from the supplied YAML (or JSON) file. This op‐
558 tion can be used with every input format, but string scalars in
559 the YAML file will always be parsed as Markdown. Generally, the
560 input will be handled the same as in YAML metadata blocks. This
561 option can be used repeatedly to include multiple metadata
562 files; values in files specified later on the command line will
563 be preferred over those specified in earlier files. Metadata
564 values specified inside the document, or by using -M, overwrite
565 values specified with this option.
566 -p, --preserve-tabs
568 Preserve tabs instead of converting them to spaces. (By de‐
569 fault, pandoc converts tabs to spaces before parsing its input.)
570 Note that this will only affect tabs in literal code spans and
571 code blocks. Tabs in regular text are always treated as spaces.
572 --tab-stop=NUMBER
574 Specify the number of spaces per tab (default is 4).
575 --track-changes=accept|reject|all
577 Specifies what to do with insertions, deletions, and comments
578 produced by the MS Word "Track Changes" feature. accept (the
579 default), inserts all insertions, and ignores all deletions.
580 reject inserts all deletions and ignores insertions. Both ac‐
581 cept and reject ignore comments. all puts in insertions, dele‐
582 tions, and comments, wrapped in spans with insertion, deletion,
583 comment-start, and comment-end classes, respectively. The au‐
584 thor and time of change is included. all is useful for script‐
585 ing: only accepting changes from a certain reviewer, say, or be‐
586 fore a certain date. If a paragraph is inserted or deleted,
587 track-changes=all produces a span with the class paragraph-in‐
588 sertion/paragraph-deletion before the affected paragraph break.
589 This option only affects the docx reader.
590 --extract-media=DIR
592 Extract images and other media contained in or linked from the
593 source document to the path DIR, creating it if necessary, and
594 adjust the images references in the document so they point to
595 the extracted files. If the source format is a binary container
596 (docx, epub, or odt), the media is extracted from the container
597 and the original filenames are used. Otherwise the media is
598 read from the file system or downloaded, and new filenames are
599 constructed based on SHA1 hashes of the contents.
600 --abbreviations=FILE
602 Specifies a custom abbreviations file, with abbreviations one to
603 a line. If this option is not specified, pandoc will read the
604 data file abbreviations from the user data directory or fall
605 back on a system default. To see the system default, use pandoc
606 --print-default-data-file=abbreviations. The only use pandoc
607 makes of this list is in the Markdown reader. Strings ending in
608 a period that are found in this list will be followed by a non‐
609 breaking space, so that the period will not produce sentence-
610 ending space in formats like LaTeX.
611 General writer options
613 -s, --standalone
614 Produce output with an appropriate header and footer (e.g. a
615 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
616 option is set automatically for pdf, epub, epub3, fb2, docx, and
617 odt output. For native output, this option causes metadata to
618 be included; otherwise, metadata is suppressed.
619 --template=FILE|URL
621 Use the specified file as a custom template for the generated
622 document. Implies --standalone. See Templates, below, for a
623 description of template syntax. If no extension is specified,
624 an extension corresponding to the writer will be added, so that
625 --template=special looks for special.html for HTML output. If
626 the template is not found, pandoc will search for it in the tem‐
627 plates subdirectory of the user data directory (see --data-dir).
628 If this option is not used, a default template appropriate for
629 the output format will be used (see -D/--print-default-tem‐
630 plate).
631 -V KEY[=VAL], --variable=KEY[:VAL]
633 Set the template variable KEY to the value VAL when rendering
634 the document in standalone mode. If no VAL is specified, the
635 key will be given the value true.
636 -D FORMAT, --print-default-template=FORMAT
638 Print the system default template for an output FORMAT. (See -t
639 for a list of possible FORMATs.) Templates in the user data di‐
640 rectory are ignored. This option may be used with -o/--output
641 to redirect output to a file, but -o/--output must come before
642 --print-default-template on the command line.
643 Note that some of the default templates use partials, for exam‐
645 ple styles.html. To print the partials, use --print-default-da‐
646 ta-file: for example, --print-default-data-file=tem‐
647 plates/styles.html.
648 --print-default-data-file=FILE
650 Print a system default data file. Files in the user data direc‐
651 tory are ignored. This option may be used with -o/--output to
652 redirect output to a file, but -o/--output must come before
653 --print-default-data-file on the command line.
654 --eol=crlf|lf|native
656 Manually specify line endings: crlf (Windows), lf (macOS/Lin‐
657 ux/UNIX), or native (line endings appropriate to the OS on which
658 pandoc is being run). The default is native.
659 --dpi=NUMBER
661 Specify the default dpi (dots per inch) value for conversion
662 from pixels to inch/centimeters and vice versa. (Technically,
663 the correct term would be ppi: pixels per inch.) The default is
664 96dpi. When images contain information about dpi internally,
665 the encoded value is used instead of the default specified by
666 this option.
667 --wrap=auto|none|preserve
669 Determine how text is wrapped in the output (the source code,
670 not the rendered version). With auto (the default), pandoc will
671 attempt to wrap lines to the column width specified by --columns
672 (default 72). With none, pandoc will not wrap lines at all.
673 With preserve, pandoc will attempt to preserve the wrapping from
674 the source document (that is, where there are nonsemantic new‐
675 lines in the source, there will be nonsemantic newlines in the
676 output as well). Automatic wrapping does not currently work in
677 HTML output. In ipynb output, this option affects wrapping of
678 the contents of markdown cells.
679 --columns=NUMBER
681 Specify length of lines in characters. This affects text wrap‐
682 ping in the generated source code (see --wrap). It also affects
683 calculation of column widths for plain text tables (see Tables
684 below).
685 --toc, --table-of-contents
687 Include an automatically generated table of contents (or, in the
688 case of latex, context, docx, odt, opendocument, rst, or ms, an
689 instruction to create one) in the output document. This option
690 has no effect unless -s/--standalone is used, and it has no ef‐
691 fect on man, docbook4, docbook5, or jats output.
692 Note that if you are producing a PDF via ms, the table of con‐
694 tents will appear at the beginning of the document, before the
695 title. If you would prefer it to be at the end of the document,
696 use the option --pdf-engine-opt=--no-toc-relocation.
697 --toc-depth=NUMBER
699 Specify the number of section levels to include in the table of
700 contents. The default is 3 (which means that level-1, 2, and 3
701 headings will be listed in the contents).
702 --strip-comments
704 Strip out HTML comments in the Markdown or Textile source,
705 rather than passing them on to Markdown, Textile or HTML output
706 as raw HTML. This does not apply to HTML comments inside raw
707 HTML blocks when the markdown_in_html_blocks extension is not
708 set.
709 --no-highlight
711 Disables syntax highlighting for code blocks and inlines, even
712 when a language attribute is given.
713 --highlight-style=STYLE|FILE
715 Specifies the coloring style to be used in highlighted source
716 code. Options are pygments (the default), kate, monochrome,
717 breezeDark, espresso, zenburn, haddock, and tango. For more in‐
718 formation on syntax highlighting in pandoc, see Syntax high‐
719 lighting, below. See also --list-highlight-styles.
720 Instead of a STYLE name, a JSON file with extension .theme may
722 be supplied. This will be parsed as a KDE syntax highlighting
723 theme and (if valid) used as the highlighting style.
724 To generate the JSON version of an existing style, use --print-
726 highlight-style.
727 --print-highlight-style=STYLE|FILE
729 Prints a JSON version of a highlighting style, which can be mod‐
730 ified, saved with a .theme extension, and used with --highlight-
731 style. This option may be used with -o/--output to redirect
732 output to a file, but -o/--output must come before --print-high‐
733 light-style on the command line.
734 --syntax-definition=FILE
736 Instructs pandoc to load a KDE XML syntax definition file, which
737 will be used for syntax highlighting of appropriately marked
738 code blocks. This can be used to add support for new languages
739 or to use altered syntax definitions for existing languages.
740 This option may be repeated to add multiple syntax definitions.
741 -H FILE, --include-in-header=FILE|URL
743 Include contents of FILE, verbatim, at the end of the header.
744 This can be used, for example, to include special CSS or
745 JavaScript in HTML documents. This option can be used repeated‐
746 ly to include multiple files in the header. They will be in‐
747 cluded in the order specified. Implies --standalone.
748 -B FILE, --include-before-body=FILE|URL
750 Include contents of FILE, verbatim, at the beginning of the doc‐
751 ument body (e.g. after the <body> tag in HTML, or the \be‐
752 gin{document} command in LaTeX). This can be used to include
753 navigation bars or banners in HTML documents. This option can
754 be used repeatedly to include multiple files. They will be in‐
755 cluded in the order specified. Implies --standalone.
756 -A FILE, --include-after-body=FILE|URL
758 Include contents of FILE, verbatim, at the end of the document
759 body (before the </body> tag in HTML, or the \end{document} com‐
760 mand in LaTeX). This option can be used repeatedly to include
761 multiple files. They will be included in the order specified.
762 Implies --standalone.
763 --resource-path=SEARCHPATH
765 List of paths to search for images and other resources. The
766 paths should be separated by : on Linux, UNIX, and macOS sys‐
767 tems, and by ; on Windows. If --resource-path is not specified,
768 the default resource path is the working directory. Note that,
769 if --resource-path is specified, the working directory must be
770 explicitly listed or it will not be searched. For example:
771 --resource-path=.:test will search the working directory and the
772 test subdirectory, in that order.
773 --resource-path only has an effect if (a) the output format em‐
775 beds images (for example, docx, pdf, or html with --self-con‐
776 tained) or (b) it is used together with --extract-media.
777 --request-header=NAME:VAL
779 Set the request header NAME to the value VAL when making HTTP
780 requests (for example, when a URL is given on the command line,
781 or when resources used in a document must be downloaded). If
782 you're behind a proxy, you also need to set the environment
783 variable http_proxy to http://....
784 Options affecting specific writers
786 --self-contained
787 Produce a standalone HTML file with no external dependencies,
788 using data: URIs to incorporate the contents of linked scripts,
789 stylesheets, images, and videos. Implies --standalone. The re‐
790 sulting file should be "self-contained," in the sense that it
791 needs no external files and no net access to be displayed prop‐
792 erly by a browser. This option works only with HTML output for‐
793 mats, including html4, html5, html+lhs, html5+lhs, s5, slidy,
794 slideous, dzslides, and revealjs. Scripts, images, and
795 stylesheets at absolute URLs will be downloaded; those at rela‐
796 tive URLs will be sought relative to the working directory (if
797 the first source file is local) or relative to the base URL (if
798 the first source file is remote). Elements with the attribute
799 data-external="1" will be left alone; the documents they link to
800 will not be incorporated in the document. Limitation: resources
801 that are loaded dynamically through JavaScript cannot be incor‐
802 porated; as a result, --self-contained does not work with
803 --mathjax, and some advanced features (e.g. zoom or speaker
804 notes) may not work in an offline "self-contained" reveal.js
805 slide show.
806 --html-q-tags
808 Use <q> tags for quotes in HTML.
809 --ascii
811 Use only ASCII characters in output. Currently supported for
812 XML and HTML formats (which use entities instead of UTF-8 when
813 this option is selected), CommonMark, gfm, and Markdown (which
814 use entities), roff ms (which use hexadecimal escapes), and to a
815 limited degree LaTeX (which uses standard commands for accented
816 characters when possible). roff man output uses ASCII by de‐
817 fault.
818 --reference-links
820 Use reference-style links, rather than inline links, in writing
821 Markdown or reStructuredText. By default inline links are used.
822 The placement of link references is affected by the --reference-
823 location option.
824 --reference-location = block|section|document
826 Specify whether footnotes (and references, if reference-links is
827 set) are placed at the end of the current (top-level) block, the
828 current section, or the document. The default is document.
829 Currently only affects the markdown writer.
830 --atx-headers
832 Use ATX-style headings in Markdown output. The default is to
833 use setext-style headings for levels 1 to 2, and then ATX head‐
834 ings. (Note: for gfm output, ATX headings are always used.)
835 This option also affects markdown cells in ipynb output.
836 --top-level-division=[default|section|chapter|part]
838 Treat top-level headings as the given division type in LaTeX,
839 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
840 chapter, then section; all headings are shifted such that the
841 top-level heading becomes the specified type. The default be‐
842 havior is to determine the best division type via heuristics:
843 unless other conditions apply, section is chosen. When the doc‐
844 umentclass variable is set to report, book, or memoir (unless
845 the article option is specified), chapter is implied as the set‐
846 ting for this option. If beamer is the output format, specify‐
847 ing either chapter or part will cause top-level headings to be‐
848 come \part{..}, while second-level headings remain as their de‐
849 fault type.
850 -N, --number-sections
852 Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
853 By default, sections are not numbered. Sections with class un‐
854 numbered will never be numbered, even if --number-sections is
855 specified.
856 --number-offset=NUMBER[,NUMBER,...]
858 Offset for section headings in HTML output (ignored in other
859 output formats). The first number is added to the section num‐
860 ber for top-level headings, the second for second-level head‐
861 ings, and so on. So, for example, if you want the first top-
862 level heading in your document to be numbered "6", specify
863 --number-offset=5. If your document starts with a level-2 head‐
864 ing which you want to be numbered "1.5", specify --number-off‐
865 set=1,4. Offsets are 0 by default. Implies --number-sections.
866 --listings
868 Use the listings package for LaTeX code blocks. The package
869 does not support multi-byte encoding for source code. To handle
870 UTF-8 you would need to use a custom template. This issue is
871 fully documented here: Encoding issue with the listings package.
872 -i, --incremental
874 Make list items in slide shows display incrementally (one by
875 one). The default is for lists to be displayed all at once.
876 --slide-level=NUMBER
878 Specifies that headings with the specified level create slides
879 (for beamer, s5, slidy, slideous, dzslides). Headings above
880 this level in the hierarchy are used to divide the slide show
881 into sections; headings below this level create subheads within
882 a slide. Note that content that is not contained under slide-
883 level headings will not appear in the slide show. The default
884 is to set the slide level based on the contents of the document;
885 see Structuring the slide show.
886 --section-divs
888 Wrap sections in <section> tags (or <div> tags for html4), and
889 attach identifiers to the enclosing <section> (or <div>) rather
890 than the heading itself. See Heading identifiers, below.
891 --email-obfuscation=none|javascript|references
893 Specify a method for obfuscating mailto: links in HTML docu‐
894 ments. none leaves mailto: links as they are. javascript ob‐
895 fuscates them using JavaScript. references obfuscates them by
896 printing their letters as decimal or hexadecimal character ref‐
897 erences. The default is none.
898 --id-prefix=STRING
900 Specify a prefix to be added to all identifiers and internal
901 links in HTML and DocBook output, and to footnote numbers in
902 Markdown and Haddock output. This is useful for preventing du‐
903 plicate identifiers when generating fragments to be included in
904 other pages.
905 -T STRING, --title-prefix=STRING
907 Specify STRING as a prefix at the beginning of the title that
908 appears in the HTML header (but not in the title as it appears
909 at the beginning of the HTML body). Implies --standalone.
910 -c URL, --css=URL
912 Link to a CSS style sheet. This option can be used repeatedly
913 to include multiple files. They will be included in the order
914 specified.
915 A stylesheet is required for generating EPUB. If none is pro‐
917 vided using this option (or the css or stylesheet metadata
918 fields), pandoc will look for a file epub.css in the user data
919 directory (see --data-dir). If it is not found there, sensible
920 defaults will be used.
921 --reference-doc=FILE
923 Use the specified file as a style reference in producing a docx
924 or ODT file.
925 Docx For best results, the reference docx should be a modified
927 version of a docx file produced using pandoc. The con‐
928 tents of the reference docx are ignored, but its
929 stylesheets and document properties (including margins,
930 page size, header, and footer) are used in the new docx.
931 If no reference docx is specified on the command line,
932 pandoc will look for a file reference.docx in the user
933 data directory (see --data-dir). If this is not found
934 either, sensible defaults will be used.
935 To produce a custom reference.docx, first get a copy of
937 the default reference.docx: pandoc -o custom-refer‐
938 ence.docx --print-default-data-file reference.docx. Then
939 open custom-reference.docx in Word, modify the styles as
940 you wish, and save the file. For best results, do not
941 make changes to this file other than modifying the styles
942 used by pandoc:
943 Paragraph styles:
945 · Normal
947 · Body Text
949 · First Paragraph
951 · Compact
953 · Title
955 · Subtitle
957 · Author
959 · Date
961 · Abstract
963 · Bibliography
965 · Heading 1
967 · Heading 2
969 · Heading 3
971 · Heading 4
973 · Heading 5
975 · Heading 6
977 · Heading 7
979 · Heading 8
981 · Heading 9
983 · Block Text
985 · Footnote Text
987 · Definition Term
989 · Definition
991 · Caption
993 · Table Caption
995 · Image Caption
997 · Figure
999 · Captioned Figure
1001 · TOC Heading
1003 Character styles:
1005 · Default Paragraph Font
1007 · Body Text Char
1009 · Verbatim Char
1011 · Footnote Reference
1013 · Hyperlink
1015 Table style:
1017 · Table
1019 ODT For best results, the reference ODT should be a modified
1021 version of an ODT produced using pandoc. The contents of
1022 the reference ODT are ignored, but its stylesheets are
1023 used in the new ODT. If no reference ODT is specified on
1024 the command line, pandoc will look for a file refer‐
1025 ence.odt in the user data directory (see --data-dir). If
1026 this is not found either, sensible defaults will be used.
1027 To produce a custom reference.odt, first get a copy of
1029 the default reference.odt: pandoc -o custom-reference.odt
1030 --print-default-data-file reference.odt. Then open cus‐
1031 tom-reference.odt in LibreOffice, modify the styles as
1032 you wish, and save the file.
1033 PowerPoint
1035 Templates included with Microsoft PowerPoint 2013 (either
1036 with .pptx or .potx extension) are known to work, as are
1037 most templates derived from these.
1038 The specific requirement is that the template should be‐
1040 gin with the following first four layouts:
1041 1. Title Slide
1043 2. Title and Content
1045 3. Section Header
1047 4. Two Content
1049 All templates included with a recent version of MS Power‐
1051 Point will fit these criteria. (You can click on Layout
1052 under the Home menu to check.)
1053 You can also modify the default reference.pptx: first run
1055 pandoc -o custom-reference.pptx --print-default-data-file
1056 reference.pptx, and then modify custom-reference.pptx in
1057 MS PowerPoint (pandoc will use the first four layout
1058 slides, as mentioned above).
1059 --epub-cover-image=FILE
1061 Use the specified image as the EPUB cover. It is recommended
1062 that the image be less than 1000px in width and height. Note
1063 that in a Markdown source document you can also specify cover-
1064 image in a YAML metadata block (see EPUB Metadata, below).
1065 --epub-metadata=FILE
1067 Look in the specified XML file for metadata for the EPUB. The
1068 file should contain a series of Dublin Core elements. For exam‐
1069 ple:
1070 <dc:rights>Creative Commons</dc:rights>
1072 <dc:language>es-AR</dc:language>
1073 By default, pandoc will include the following metadata elements:
1075 <dc:title> (from the document title), <dc:creator> (from the
1076 document authors), <dc:date> (from the document date, which
1077 should be in ISO 8601 format), <dc:language> (from the lang
1078 variable, or, if is not set, the locale), and <dc:identifier
1079 id="BookId"> (a randomly generated UUID). Any of these may be
1080 overridden by elements in the metadata file.
1081 Note: if the source document is Markdown, a YAML metadata block
1083 in the document can be used instead. See below under EPUB Meta‐
1084 data.
1085 --epub-embed-font=FILE
1087 Embed the specified font in the EPUB. This option can be re‐
1088 peated to embed multiple fonts. Wildcards can also be used: for
1089 example, DejaVuSans-*.ttf. However, if you use wildcards on the
1090 command line, be sure to escape them or put the whole filename
1091 in single quotes, to prevent them from being interpreted by the
1092 shell. To use the embedded fonts, you will need to add declara‐
1093 tions like the following to your CSS (see --css):
1094 @font-face {
1096 font-family: DejaVuSans;
1097 font-style: normal;
1098 font-weight: normal;
1099 src:url("DejaVuSans-Regular.ttf");
1100 }
1101 @font-face {
1102 font-family: DejaVuSans;
1103 font-style: normal;
1104 font-weight: bold;
1105 src:url("DejaVuSans-Bold.ttf");
1106 }
1107 @font-face {
1108 font-family: DejaVuSans;
1109 font-style: italic;
1110 font-weight: normal;
1111 src:url("DejaVuSans-Oblique.ttf");
1112 }
1113 @font-face {
1114 font-family: DejaVuSans;
1115 font-style: italic;
1116 font-weight: bold;
1117 src:url("DejaVuSans-BoldOblique.ttf");
1118 }
1119 body { font-family: "DejaVuSans"; }
1120 --epub-chapter-level=NUMBER
1122 Specify the heading level at which to split the EPUB into sepa‐
1123 rate "chapter" files. The default is to split into chapters at
1124 level-1 headings. This option only affects the internal compo‐
1125 sition of the EPUB, not the way chapters and sections are dis‐
1126 played to users. Some readers may be slow if the chapter files
1127 are too large, so for large documents with few level-1 headings,
1128 one might want to use a chapter level of 2 or 3.
1129 --epub-subdirectory=DIRNAME
1131 Specify the subdirectory in the OCF container that is to hold
1132 the EPUB-specific contents. The default is EPUB. To put the
1133 EPUB contents in the top level, use an empty string.
1134 --ipynb-output=all|none|best
1136 Determines how ipynb output cells are treated. all means that
1137 all of the data formats included in the original are preserved.
1138 none means that the contents of data cells are omitted. best
1139 causes pandoc to try to pick the richest data block in each out‐
1140 put cell that is compatible with the output format. The default
1141 is best.
1142 --pdf-engine=PROGRAM
1144 Use the specified engine when producing PDF output. Valid val‐
1145 ues are pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtml‐
1146 topdf, weasyprint, prince, context, and pdfroff. If the engine
1147 is not in your PATH, the full path of the engine may be speci‐
1148 fied here. If this option is not specified, pandoc uses the
1149 following defaults depending on the output format specified us‐
1150 ing -t/--to:
1151 · -t latex or none: pdflatex (other options: xelatex, lualatex,
1153 tectonic, latexmk)
1154 · -t context: context
1156 · -t html: wkhtmltopdf (other options: prince, weasyprint)
1158 · -t ms: pdfroff
1160 --pdf-engine-opt=STRING
1162 Use the given string as a command-line argument to the pdf-en‐
1163 gine. For example, to use a persistent directory foo for la‐
1164 texmk's auxiliary files, use --pdf-engine-opt=-outdir=foo. Note
1165 that no check for duplicate options is done.
1166 Citation rendering
1168 --bibliography=FILE
1169 Set the bibliography field in the document's metadata to FILE,
1170 overriding any value set in the metadata, and process citations
1171 using pandoc-citeproc. (This is equivalent to --metadata bibli‐
1172 ography=FILE --filter pandoc-citeproc.) If --natbib or --bibla‐
1173 tex is also supplied, pandoc-citeproc is not used, making this
1174 equivalent to --metadata bibliography=FILE. If you supply this
1175 argument multiple times, each FILE will be added to bibliogra‐
1176 phy.
1177 --csl=FILE
1179 Set the csl field in the document's metadata to FILE, overriding
1180 any value set in the metadata. (This is equivalent to --metada‐
1181 ta csl=FILE.) This option is only relevant with pandoc-citeproc.
1182 --citation-abbreviations=FILE
1184 Set the citation-abbreviations field in the document's metadata
1185 to FILE, overriding any value set in the metadata. (This is
1186 equivalent to --metadata citation-abbreviations=FILE.) This op‐
1187 tion is only relevant with pandoc-citeproc.
1188 --natbib
1190 Use natbib for citations in LaTeX output. This option is not
1191 for use with the pandoc-citeproc filter or with PDF output. It
1192 is intended for use in producing a LaTeX file that can be pro‐
1193 cessed with bibtex.
1194 --biblatex
1196 Use biblatex for citations in LaTeX output. This option is not
1197 for use with the pandoc-citeproc filter or with PDF output. It
1198 is intended for use in producing a LaTeX file that can be pro‐
1199 cessed with bibtex or biber.
1200 Math rendering in HTML
1202 The default is to render TeX math as far as possible using Unicode
1203 characters. Formulas are put inside a span with class="math", so that
1204 they may be styled differently from the surrounding text if needed.
1205 However, this gives acceptable results only for basic math, usually you
1206 will want to use --mathjax or another of the following options.
1207 --mathjax[=URL]
1209 Use MathJax to display embedded TeX math in HTML output. TeX
1210 math will be put between \(...\) (for inline math) or \[...\]
1211 (for display math) and wrapped in <span> tags with class math.
1212 Then the MathJax JavaScript will render it. The URL should
1213 point to the MathJax.js load script. If a URL is not provided,
1214 a link to the Cloudflare CDN will be inserted.
1215 --mathml
1217 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
1218 html4 and html5). This is the default in odt output. Note that
1219 currently only Firefox and Safari (and select e-book readers)
1220 natively support MathML.
1221 --webtex[=URL]
1223 Convert TeX formulas to <img> tags that link to an external
1224 script that converts formulas to images. The formula will be
1225 URL-encoded and concatenated with the URL provided. For SVG im‐
1226 ages you can for example use --webtex https://la‐
1227 tex.codecogs.com/svg.latex?. If no URL is specified, the
1228 CodeCogs URL generating PNGs will be used (https://la‐
1229 tex.codecogs.com/png.latex?). Note: the --webtex option will
1230 affect Markdown output as well as HTML, which is useful if
1231 you're targeting a version of Markdown without native math sup‐
1232 port.
1233 --katex[=URL]
1235 Use KaTeX to display embedded TeX math in HTML output. The URL
1236 is the base URL for the KaTeX library. That directory should
1237 contain a katex.min.js and a katex.min.css file. If a URL is
1238 not provided, a link to the KaTeX CDN will be inserted.
1239 --gladtex
1241 Enclose TeX math in <eq> tags in HTML output. The resulting
1242 HTML can then be processed by GladTeX to produce images of the
1243 typeset formulas and an HTML file with links to these images.
1244 So, the procedure is:
1245 pandoc -s --gladtex input.md -o myfile.htex
1247 gladtex -d myfile-images myfile.htex
1248 # produces myfile.html and images in myfile-images
1249 Options for wrapper scripts
1251 --dump-args
1252 Print information about command-line arguments to stdout, then
1253 exit. This option is intended primarily for use in wrapper
1254 scripts. The first line of output contains the name of the out‐
1255 put file specified with the -o option, or - (for stdout) if no
1256 output file was specified. The remaining lines contain the com‐
1257 mand-line arguments, one per line, in the order they appear.
1258 These do not include regular pandoc options and their arguments,
1259 but do include any options appearing after a -- separator at the
1260 end of the line.
1261 --ignore-args
1263 Ignore command-line arguments (for use in wrapper scripts).
1264 Regular pandoc options are not ignored. Thus, for example,
1265 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1267 is equivalent to
1269 pandoc -o foo.html -s
1271
1273 If pandoc completes successfully, it will return exit code 0. Nonzero
1274 exit codes have the following meanings:
1275 Code Error
1277 ─────────────────────────────────
1278 3 PandocFailOnWarningError
1279 4 PandocAppError
1280 5 PandocTemplateError
1281 6 PandocOptionError
1282 21 PandocUnknownReaderError
1283 22 PandocUnknownWriterError
1284 23 PandocUnsupportedExten‐
1285 sionError
1286 31 PandocEpubSubdirectoryEr‐
1289 ror
1290 43 PandocPDFError
1291 47 PandocPDFProgramNot‐
1292 FoundError
1293 61 PandocHttpError
1294 62 PandocShouldNeverHappen‐
1295 Error
1296 63 PandocSomeError
1297 64 PandocParseError
1298 65 PandocParsecError
1299 66 PandocMakePDFError
1300 67 PandocSyntaxMapError
1301 83 PandocFilterError
1302 91 PandocMacroLoop
1303 92 PandocUTF8DecodingError
1304 93 PandocIpynbDecodingError
1305 97 PandocCouldNotFind‐
1306 DataFileError
1307 99 PandocResourceNotFound
1308
1310 The --defaults option may be used to specify a package of options.
1311 Here is a sample defaults file demonstrating all of the fields that may
1312 be used:
1313 from: markdown+emoji
1315 # reader: may be used instead of from:
1316 to: html5
1317 # writer: may be used instead of to:
1318 # leave blank for output to stdout:
1320 output-file:
1321 # leave blank for input from stdin, use [] for no input:
1322 input-files:
1323 - preface.md
1324 - content.md
1325 # or you may use input-file: with a single value
1326 template: letter
1328 standalone: true
1329 self-contained: false
1330 # note that structured variables may be specified:
1332 variables:
1333 documentclass: book
1334 classoption:
1335 - twosides
1336 - draft
1337 # metadata values specified here are parsed as literal
1339 # string text, not markdown:
1340 metadata:
1341 author:
1342 - Sam Smith
1343 - Julie Liu
1344 metadata-files:
1345 - boilerplate.yaml
1346 # or you may use metadata-file: with a single value
1347 # Note that these take files, not their contents:
1349 include-before-body: []
1350 include-after-body: []
1351 include-in-header: []
1352 resource-path: ["."]
1353 # filters will be assumed to be Lua filters if they have
1355 # the .lua extension, and json filters otherwise. But
1356 # the filter type can also be specified explicitly, as shown:
1357 filters:
1358 - pandoc-citeproc
1359 - wordcount.lua
1360 - type: json
1361 path: foo.lua
1362 file-scope: false
1364 data-dir:
1366 # ERROR, WARNING, or INFO
1368 verbosity: INFO
1369 log-file: log.json
1370 # citeproc, natbib, or biblatex
1372 cite-method: citeproc
1373 # part, chapter, section, or default:
1374 top-level-division: chapter
1375 abbreviations:
1376 pdf-engine: pdflatex
1378 pdf-engine-opts:
1379 - "-shell-escape"
1380 # you may also use pdf-engine-opt: with a single option
1381 # pdf-engine-opt: "-shell-escape"
1382 # auto, preserve, or none
1384 wrap: auto
1385 columns: 78
1386 dpi: 72
1387 extract-media: mediadir
1389 table-of-contents: true
1391 toc-depth: 2
1392 number-sections: false
1393 # a list of offsets at each heading level
1394 number-offset: [0,0,0,0,0,0]
1395 # toc: may also be used instead of table-of-contents:
1396 shift-heading-level-by: 1
1397 section-divs: true
1398 identifier-prefix: foo
1399 title-prefix: ""
1400 strip-empty-paragraphs: true
1401 # lf, crlf, or native
1402 eol: lf
1403 strip-comments: false
1404 indented-code-classes: []
1405 ascii: true
1406 default-image-extension: ".jpg"
1407 # either a style name of a style definition file:
1409 highlight-style: pygments
1410 syntax-definitions:
1411 - c.xml
1412 # or you may use syntax-definition: with a single value
1413 listings: false
1414 reference-doc: myref.docx
1416 # method is plain, webtex, gladtex, mathml, mathjax, katex
1418 # you may specify a url with webtex, mathjax, katex
1419 html-math-method:
1420 method: mathjax
1421 url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
1422 # none, references, or javascript
1423 email-obfuscation: javascript
1424 tab-stop: 8
1426 preserve-tabs: true
1427 incremental: false
1429 slide-level: 2
1430 epub-subdirectory: EPUB
1432 epub-metadata: meta.xml
1433 epub-fonts:
1434 - foobar.otf
1435 epub-chapter-level: 1
1436 epub-cover-image: cover.jpg
1437 reference-links: true
1439 # block, section, or document
1440 reference-location: block
1441 atx-headers: false
1442 # accept, reject, or all
1444 track-changes: accept
1445 html-q-tags: false
1447 css:
1448 - site.css
1449 # none, all, or best
1451 ipynb-output: best
1452 # A list of two-element lists
1454 request-headers:
1455 - ["User-Agent", "Mozilla/5.0"]
1456 fail-if-warnings: false
1458 dump-args: false
1459 ignore-args: false
1460 trace: false
1461 Fields that are omitted will just have their regular default values.
1463 So a defaults file can be as simple as one line:
1464 verbosity: INFO
1466 Default files can be placed in the defaults subdirectory of the user
1468 data directory and used from any directory. For example, one could
1469 create a file specifying defaults for writing letters, save it as let‐
1470 ter.yaml in the defaults subdirectory of the user data directory, and
1471 then invoke these defaults from any directory using pandoc --defaults
1472 letter or pandoc -dletter.
1473 When multiple defaults are used, their contents will be combined.
1475 Note that, where command-line arguments may be repeated (--metadata-
1477 file, --css, --include-in-header, --include-before-body, --include-af‐
1478 ter-body, --variable, --metadata, --syntax-definition), the values
1479 specified on the command line will combine with values specified in the
1480 defaults file, rather than replacing them.
1481
1483 When the -s/--standalone option is used, pandoc uses a template to add
1484 header and footer material that is needed for a self-standing document.
1485 To see the default template that is used, just type
1486 pandoc -D *FORMAT*
1488 where FORMAT is the name of the output format. A custom template can
1490 be specified using the --template option. You can also override the
1491 system default templates for a given output format FORMAT by putting a
1492 file templates/default.*FORMAT* in the user data directory (see --data-
1493 dir, above). Exceptions:
1494 · For odt output, customize the default.opendocument template.
1496 · For pdf output, customize the default.latex template (or the de‐
1498 fault.context template, if you use -t context, or the default.ms tem‐
1499 plate, if you use -t ms, or the default.html template, if you use -t
1500 html).
1501 · docx and pptx have no template (however, you can use --reference-doc
1503 to customize the output).
1504 Templates contain variables, which allow for the inclusion of arbitrary
1506 information at any point in the file. They may be set at the command
1507 line using the -V/--variable option. If a variable is not set, pandoc
1508 will look for the key in the document's metadata, which can be set us‐
1509 ing either YAML metadata blocks or with the -M/--metadata option. In
1510 addition, some variables are given default values by pandoc. See Vari‐
1511 ables below for a list of variables used in pandoc's default templates.
1512 If you use custom templates, you may need to revise them as pandoc
1514 changes. We recommend tracking the changes in the default templates,
1515 and modifying your custom templates accordingly. An easy way to do
1516 this is to fork the pandoc-templates repository and merge in changes
1517 after each pandoc release.
1518 Template syntax
1520 Comments
1521 Anything between the sequence $-- and the end of the line will be
1522 treated as a comment and omitted from the output.
1523 Delimiters
1525 To mark variables and control structures in the template, either $...$
1526 or ${...} may be used as delimiters. The styles may also be mixed in
1527 the same template, but the opening and closing delimiter must match in
1528 each case. The opening delimiter may be followed by one or more spaces
1529 or tabs, which will be ignored. The closing delimiter may be followed
1530 by one or more spaces or tabs, which will be ignored.
1531 To include a literal $ in the document, use $$.
1533 Interpolated variables
1535 A slot for an interpolated variable is a variable name surrounded by
1536 matched delimiters. Variable names must begin with a letter and can
1537 contain letters, numbers, _, -, and .. The keywords it, if, else, en‐
1538 dif, for, sep, and endfor may not be used as variable names. Examples:
1539 $foo$
1541 $foo.bar.baz$
1542 $foo_bar.baz-bim$
1543 $ foo $
1544 ${foo}
1545 ${foo.bar.baz}
1546 ${foo_bar.baz-bim}
1547 ${ foo }
1548 Variable names with periods are used to get at structured variable val‐
1550 ues. So, for example, employee.salary will return the value of the
1551 salary field of the object that is the value of the employee field.
1552 · If the value of the variable is simple value, it will be rendered
1554 verbatim. (Note that no escaping is done; the assumption is that the
1555 calling program will escape the strings appropriately for the output
1556 format.)
1557 · If the value is a list, the values will be concatenated.
1559 · If the value is a map, the string true will be rendered.
1561 · Every other value will be rendered as the empty string.
1563 Conditionals
1565 A conditional begins with if(variable) (enclosed in matched delimiters)
1566 and ends with endif (enclosed in matched delimiters). It may optional‐
1567 ly contain an else (enclosed in matched delimiters). The if section is
1568 used if variable has a non-empty value, otherwise the else section is
1569 used (if present). Examples:
1570 $if(foo)$bar$endif$
1572 $if(foo)$
1574 $foo$
1575 $endif$
1576 $if(foo)$
1578 part one
1579 $else$
1580 part two
1581 $endif$
1582 ${if(foo)}bar${endif}
1584 ${if(foo)}
1586 ${foo}
1587 ${endif}
1588 ${if(foo)}
1590 ${ foo.bar }
1591 ${else}
1592 no foo!
1593 ${endif}
1594 The keyword elseif may be used to simplify complex nested conditionals:
1596 $if(foo)$
1598 XXX
1599 $elseif(bar)$
1600 YYY
1601 $else$
1602 ZZZ
1603 $endif$
1604 For loops
1606 A for loop begins with for(variable) (enclosed in matched delimiters)
1607 and ends with endfor (enclosed in matched delimiters.
1608 · If variable is an array, the material inside the loop will be evalu‐
1610 ated repeatedly, with variable being set to each value of the array
1611 in turn, and concatenated.
1612 · If variable is a map, the material inside will be set to the map.
1614 · If the value of the associated variable is not an array or a map, a
1616 single iteration will be performed on its value.
1617 Examples:
1619 $for(foo)$$foo$$sep$, $endfor$
1621 $for(foo)$
1623 - $foo.last$, $foo.first$
1624 $endfor$
1625 ${ for(foo.bar) }
1627 - ${ foo.bar.last }, ${ foo.bar.first }
1628 ${ endfor }
1629 $for(mymap)$
1631 $it.name$: $it.office$
1632 $endfor$
1633 You may optionally specify a separator between consecutive values using
1635 sep (enclosed in matched delimiters). The material between sep and the
1636 endfor is the separator.
1637 ${ for(foo) }${ foo }${ sep }, ${ endfor }
1639 Instead of using variable inside the loop, the special anaphoric key‐
1641 word it may be used.
1642 ${ for(foo.bar) }
1644 - ${ it.last }, ${ it.first }
1645 ${ endfor }
1646 Partials
1648 Partials (subtemplates stored in different files) may be included using
1649 the syntax
1650 ${ boilerplate() }
1652 Partials will be sought in the directory containing the main template,
1654 and will be assumed to have the same extension as the main template if
1655 they lack an explicit extension. (If the partials are not found here,
1656 they will also be sought in the templates subdirectory of the user data
1657 directory.)
1658 Partials may optionally be applied to variables using a colon:
1660 ${ date:fancy() }
1662 ${ articles:bibentry() }
1664 If articles is an array, this will iterate over its values, applying
1666 the partial bibentry() to each one. So the second example above is
1667 equivalent to
1668 ${ for(articles) }
1670 ${ it:bibentry() }
1671 ${ endfor }
1672 Note that the anaphoric keyword it must be used when iterating over
1674 partials. In the above examples, the bibentry partial should contain
1675 it.title (and so on) instead of articles.title.
1676 Final newlines are omitted from included partials.
1678 Partials may include other partials.
1680 A separator between values of an array may be specified in square
1682 brackets, immediately after the variable name or partial:
1683 ${months[, ]}$
1685 ${articles:bibentry()[; ]$
1687 The separator in this case is literal and (unlike with sep in an ex‐
1689 plicit for loop) cannot contain interpolated variables or other tem‐
1690 plate directives.
1691 Nesting
1693 To ensure that content is "nested," that is, subsequent lines indented,
1694 use the ^ directive:
1695 $item.number$ $^$$item.description$ ($item.price$)
1697 In this example, if item.description has multiple lines, they will all
1699 be indented to line up with the first line:
1700 00123 A fine bottle of 18-year old
1702 Oban whiskey. ($148)
1703 To nest multiple lines to the same level, align them with the ^ direc‐
1705 tive in the template. For example:
1706 $item.number$ $^$$item.description$ ($item.price$)
1708 (Available til $item.sellby$.)
1709 will produce
1711 00123 A fine bottle of 18-year old
1713 Oban whiskey. ($148)
1714 (Available til March 30, 2020.)
1715 If a variable occurs by itself on a line, preceded by whitespace and
1717 not followed by further text or directives on the same line, and the
1718 variable's value contains multiple lines, it will be nested automati‐
1719 cally.
1720 Breakable spaces
1722 Normally, spaces in the template itself (as opposed to values of the
1723 interpolated variables) are not breakable, but they can be made break‐
1724 able in part of the template by using the ~ keyword (ended with another
1725 ~).
1726 $~$This long line may break if the document is rendered
1728 with a short line length.$~$
1729 Pipes
1731 A pipe transforms the value of a variable or partial. Pipes are speci‐
1732 fied using a slash (/) between the variable name (or partial) and the
1733 pipe name. Example:
1734 $for(name)$
1736 $name/uppercase$
1737 $endfor$
1738 $for(metadata/pairs)$
1740 - $it.key$: $it.value$
1741 $endfor$
1742 $employee:name()/uppercase$
1744 Pipes may be chained:
1746 $for(employees/pairs)$
1748 $it.key/alpha/uppercase$. $it.name$
1749 $endfor$
1750 Some pipes take parameters:
1752 |----------------------|------------|
1754 $for(employee)$
1755 $it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
1756 $endfor$
1757 |----------------------|------------|
1758 Currently the following pipes are predefined:
1760 · pairs: Converts a map or array to an array of maps, each with key and
1762 value fields. If the original value was an array, the key will be
1763 the array index, starting with 1.
1764 · uppercase: Converts text to uppercase.
1766 · lowercase: Converts text to lowercase.
1768 · length: Returns the length of the value: number of characters for a
1770 textual value, number of elements for a map or array.
1771 · reverse: Reverses a textual value or array, and has no effect on oth‐
1773 er values.
1774 · chomp: Removes trailing newlines (and breakable space).
1776 · nowrap: Disables line wrapping on breakable spaces.
1778 · alpha: Converts textual values that can be read as an integer into
1780 lowercase alphabetic characters a..z (mod 26). This can be used to
1781 get lettered enumeration from array indices. To get uppercase let‐
1782 ters, chain with uppercase.
1783 · roman: Converts textual values that can be read as an integer into
1785 lowercase roman numerials. This can be used to get lettered enumera‐
1786 tion from array indices. To get uppercase roman, chain with upper‐
1787 case.
1788 · left n "leftborder" "rightborder": Renders a textual value in a block
1790 of width n, aligned to the left, with an optional left and right bor‐
1791 der. Has no effect on other values. This can be used to align mate‐
1792 rial in tables. Widths are positive integers indicating the number
1793 of characters. Borders are strings inside double quotes; literal "
1794 and \ characters must be backslash-escaped.
1795 · right n "leftborder" "rightborder": Renders a textual value in a
1797 block of width n, aligned to the right, and has no effect on other
1798 values.
1799 · center n "leftborder" "rightborder": Renders a textual value in a
1801 block of width n, aligned to the center, and has no effect on other
1802 values.
1803 Variables
1805 Metadata variables
1806 title, author, date
1807 allow identification of basic aspects of the document. Included
1808 in PDF metadata through LaTeX and ConTeXt. These can be set
1809 through a pandoc title block, which allows for multiple authors,
1810 or through a YAML metadata block:
1811 ---
1813 author:
1814 - Aristotle
1815 - Peter Abelard
1816 ...
1817 Note that if you just want to set PDF or HTML metadata, without
1819 including a title block in the document itself, you can set the
1820 title-meta, author-meta, and date-meta variables. (By default
1821 these are set automatically, based on title, author, and date.)
1822 subtitle
1824 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
1825 docx documents
1826 abstract
1828 document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
1829 documents
1830 keywords
1832 list of keywords to be included in HTML, PDF, ODT, pptx, docx
1833 and AsciiDoc metadata; repeat as for author, above
1834 subject
1836 document subject, included in ODT, PDF, docx and pptx metadata
1837 description
1839 document description, included in ODT, docx and pptx metadata.
1840 Some applications show this as Comments metadata.
1841 category
1843 document category, included in docx and pptx metadata
1844 Additionally, any root-level string metadata, not included in ODT, docx
1846 or pptx metadata is added as a custom property. The following YAML
1847 metadata block for instance:
1848 ---
1850 title: 'This is the title'
1851 subtitle: "This is the subtitle"
1852 author:
1853 - Author One
1854 - Author Two
1855 description: |
1856 This is a long
1857 description.
1858 It consists of two paragraphs
1860 ...
1861 will include title, author and description as standard document proper‐
1863 ties and subtitle as a custom property when converting to docx, ODT or
1864 pptx.
1865 Language variables
1867 lang identifies the main language of the document using IETF language
1868 tags (following the BCP 47 standard), such as en or en-GB. The
1869 Language subtag lookup tool can look up or verify these tags.
1870 This affects most formats, and controls hyphenation in PDF out‐
1871 put when using LaTeX (through babel and polyglossia) or ConTeXt.
1872 Use native pandoc Divs and Spans with the lang attribute to
1874 switch the language:
1875 ---
1877 lang: en-GB
1878 ...
1879 Text in the main document language (British English).
1881 ::: {lang=fr-CA}
1883 > Cette citation est écrite en français canadien.
1884 :::
1885 More text in English. ['Zitat auf Deutsch.']{lang=de}
1887 dir the base script direction, either rtl (right-to-left) or ltr
1889 (left-to-right).
1890 For bidirectional documents, native pandoc spans and divs with
1892 the dir attribute (value rtl or ltr) can be used to override the
1893 base direction in some output formats. This may not always be
1894 necessary if the final renderer (e.g. the browser, when gener‐
1895 ating HTML) supports the Unicode Bidirectional Algorithm.
1896 When using LaTeX for bidirectional documents, only the xelatex
1898 engine is fully supported (use --pdf-engine=xelatex).
1899 Variables for HTML math
1901 classoption
1902 when using KaTeX, you can render display math equations flush
1903 left using YAML metadata or with -M classoption=fleqn.
1904 Variables for HTML slides
1906 These affect HTML output when producing slide shows with pandoc.
1907 All reveal.js configuration options are available as variables. To
1909 turn off boolean flags that default to true in reveal.js, use 0.
1910 revealjs-url
1912 base URL for reveal.js documents (defaults to reveal.js)
1913 s5-url base URL for S5 documents (defaults to s5/default)
1915 slidy-url
1917 base URL for Slidy documents (defaults to
1918 https://www.w3.org/Talks/Tools/Slidy2)
1919 slideous-url
1921 base URL for Slideous documents (defaults to slideous)
1922 title-slide-attributes
1924 additional attributes for the title slide of reveal.js slide
1925 shows. See background in reveal.js and beamer for an example.
1926 Variables for Beamer slides
1928 These variables change the appearance of PDF slides using beamer.
1929 aspectratio
1931 slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for
1932 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)
1933 beamerarticle
1935 produce an article from Beamer slides
1936 beameroption
1938 add extra beamer option with \setbeameroption{}
1939 institute
1941 author affiliations: can be a list when there are multiple au‐
1942 thors
1943 logo logo image for slides
1945 navigation
1947 controls navigation symbols (default is empty for no navigation
1948 symbols; other valid values are frame, vertical, and horizontal)
1949 section-titles
1951 enables "title pages" for new sections (default is true)
1952 theme, colortheme, fonttheme, innertheme, outertheme
1954 beamer themes
1955 themeoptions
1957 options for LaTeX beamer themes (a list).
1958 titlegraphic
1960 image for title slide
1961 Variables for PowerPoint
1963 These variables control the visual aspects of a slide show that are not
1964 easily controlled via templates.
1965 monofont
1967 font to use for code.
1968 Variables for LaTeX
1970 Pandoc uses these variables when creating a PDF with a LaTeX engine.
1971 Layout
1973 block-headings
1974 make \paragraph and \subparagraph (fourth- and fifth-level head‐
1975 ings, or fifth- and sixth-level with book classes) free-standing
1976 rather than run-in; requires further formatting to distinguish
1977 from \subsubsection (third- or fourth-level headings). Instead
1978 of using this option, KOMA-Script can adjust headings more ex‐
1979 tensively:
1980 ---
1982 documentclass: scrartcl
1983 header-includes: |
1984 \RedeclareSectionCommand[
1985 beforeskip=-10pt plus -2pt minus -1pt,
1986 afterskip=1sp plus -1sp minus 1sp,
1987 font=\normalfont\itshape]{paragraph}
1988 \RedeclareSectionCommand[
1989 beforeskip=-10pt plus -2pt minus -1pt,
1990 afterskip=1sp plus -1sp minus 1sp,
1991 font=\normalfont\scshape,
1992 indent=0pt]{subparagraph}
1993 ...
1994 classoption
1996 option for document class, e.g. oneside; repeat for multiple
1997 options:
1998 ---
2000 classoption:
2001 - twocolumn
2002 - landscape
2003 ...
2004 documentclass
2006 document class: usually one of the standard classes, article,
2007 book, and report; the KOMA-Script equivalents, scrartcl, scr‐
2008 book, and scrreprt, which default to smaller margins; or memoir
2009 geometry
2011 option for geometry package, e.g. margin=1in; repeat for multi‐
2012 ple options:
2013 ---
2015 geometry:
2016 - top=30mm
2017 - left=20mm
2018 - heightrounded
2019 ...
2020 hyperrefoptions
2022 option for hyperref package, e.g. linktoc=all; repeat for mul‐
2023 tiple options:
2024 ---
2026 hyperrefoptions:
2027 - linktoc=all
2028 - pdfwindowui
2029 - pdfpagemode=FullScreen
2030 ...
2031 indent uses document class settings for indentation (the default LaTeX
2033 template otherwise removes indentation and adds space between
2034 paragraphs)
2035 linestretch
2037 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
2038 margin-left, margin-right, margin-top, margin-bottom
2040 sets margins if geometry is not used (otherwise geometry over‐
2041 rides these)
2042 pagestyle
2044 control \pagestyle{}: the default article class supports plain
2045 (default), empty (no running heads or page numbers), and head‐
2046 ings (section titles in running heads)
2047 papersize
2049 paper size, e.g. letter, a4
2050 secnumdepth
2052 numbering depth for sections (with --number-sections option or
2053 numbersections variable)
2054 Fonts
2056 fontenc
2057 allows font encoding to be specified through fontenc package
2058 (with pdflatex); default is T1 (see LaTeX font encodings guide)
2059 fontfamily
2061 font package for use with pdflatex: TeX Live includes many op‐
2062 tions, documented in the LaTeX Font Catalogue. The default is
2063 Latin Modern.
2064 fontfamilyoptions
2066 options for package used as fontfamily; repeat for multiple op‐
2067 tions. For example, to use the Libertine font with proportional
2068 lowercase (old-style) figures through the libertinus package:
2069 ---
2071 fontfamily: libertinus
2072 fontfamilyoptions:
2073 - osf
2074 - p
2075 ...
2076 fontsize
2078 font size for body text. The standard classes allow 10pt, 11pt,
2079 and 12pt. To use another size, set documentclass to one of the
2080 KOMA-Script classes, such as scrartcl or scrbook.
2081 mainfont, sansfont, monofont, mathfont, CJKmainfont
2083 font families for use with xelatex or lualatex: take the name of
2084 any system font, using the fontspec package. CJKmainfont uses
2085 the xecjk package.
2086 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions,
2088 CJKoptions
2089 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
2090 mainfont in xelatex and lualatex. Allow for any choices avail‐
2091 able through fontspec; repeat for multiple options. For exam‐
2092 ple, to use the TeX Gyre version of Palatino with lowercase fig‐
2093 ures:
2094 ---
2096 mainfont: TeX Gyre Pagella
2097 mainfontoptions:
2098 - Numbers=Lowercase
2099 - Numbers=Proportional
2100 ...
2101 microtypeoptions
2103 options to pass to the microtype package
2104 Links
2106 colorlinks
2107 add color to link text; automatically enabled if any of linkcol‐
2108 or, filecolor, citecolor, urlcolor, or toccolor are set
2109 linkcolor, filecolor, citecolor, urlcolor, toccolor
2111 color for internal links, external links, citation links, linked
2112 URLs, and links in table of contents, respectively: uses options
2113 allowed by xcolor, including the dvipsnames, svgnames, and
2114 x11names lists
2115 links-as-notes
2117 causes links to be printed as footnotes
2118 Front matter
2120 lof, lot
2121 include list of figures, list of tables
2122 thanks contents of acknowledgments footnote after document title
2124 toc include table of contents (can also be set using --toc/--table-
2126 of-contents)
2127 toc-depth
2129 level of section to include in table of contents
2130 BibLaTeX Bibliographies
2132 These variables function when using BibLaTeX for citation rendering.
2133 biblatexoptions
2135 list of options for biblatex
2136 biblio-style
2138 bibliography style, when used with --natbib and --biblatex.
2139 biblio-title
2141 bibliography title, when used with --natbib and --biblatex.
2142 bibliography
2144 bibliography to use for resolving references
2145 natbiboptions
2147 list of options for natbib
2148 Variables for ConTeXt
2150 Pandoc uses these variables when creating a PDF with ConTeXt.
2151 fontsize
2153 font size for body text (e.g. 10pt, 12pt)
2154 headertext, footertext
2156 text to be placed in running header or footer (see ConTeXt Head‐
2157 ers and Footers); repeat up to four times for different place‐
2158 ment
2159 indenting
2161 controls indentation of paragraphs, e.g. yes,small,next (see
2162 ConTeXt Indentation); repeat for multiple options
2163 interlinespace
2165 adjusts line spacing, e.g. 4ex (using setupinterlinespace); re‐
2166 peat for multiple options
2167 layout options for page margins and text arrangement (see ConTeXt Lay‐
2169 out); repeat for multiple options
2170 linkcolor, contrastcolor
2172 color for links outside and inside a page, e.g. red, blue (see
2173 ConTeXt Color)
2174 linkstyle
2176 typeface style for links, e.g. normal, bold, slanted, bold‐
2177 slanted, type, cap, small
2178 lof, lot
2180 include list of figures, list of tables
2181 mainfont, sansfont, monofont, mathfont
2183 font families: take the name of any system font (see ConTeXt
2184 Font Switching)
2185 margin-left, margin-right, margin-top, margin-bottom
2187 sets margins, if layout is not used (otherwise layout overrides
2188 these)
2189 pagenumbering
2191 page number style and location (using setuppagenumbering); re‐
2192 peat for multiple options
2193 papersize
2195 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
2196 up); repeat for multiple options
2197 pdfa adds to the preamble the setup necessary to generate PDF/A of
2199 the type specified, e.g. 1a:2005, 2a. If no type is specified
2200 (i.e. the value is set to True, by e.g. --metadata=pdfa or
2201 pdfa: true in a YAML metadata block), 1b:2005 will be used as
2202 default, for reasons of backwards compatibility. Using --vari‐
2203 able=pdfa without specified value is not supported. To success‐
2204 fully generate PDF/A the required ICC color profiles have to be
2205 available and the content and all included files (such as im‐
2206 ages) have to be standard conforming. The ICC profiles and out‐
2207 put intent may be specified using the variables pdfaiccprofile
2208 and pdfaintent. See also ConTeXt PDFA for more details.
2209 pdfaiccprofile
2211 when used in conjunction with pdfa, specifies the ICC profile to
2212 use in the PDF, e.g. default.cmyk. If left unspecified,
2213 sRGB.icc is used as default. May be repeated to include multi‐
2214 ple profiles. Note that the profiles have to be available on
2215 the system. They can be obtained from ConTeXt ICC Profiles.
2216 pdfaintent
2218 when used in conjunction with pdfa, specifies the output intent
2219 for the colors, e.g. ISO coated v2 300\letterpercent\space
2220 (ECI) If left unspecified, sRGB IEC61966-2.1 is used as default.
2221 toc include table of contents (can also be set using --toc/--table-
2223 of-contents)
2224 whitespace
2226 spacing between paragraphs, e.g. none, small (using setup‐
2227 whitespace)
2228 includesource
2230 include all source documents as file attachments in the PDF file
2231 Variables for wkhtmltopdf
2233 Pandoc uses these variables when creating a PDF with wkhtmltopdf. The
2234 --css option also affects the output.
2235 footer-html, header-html
2237 add information to the header and footer
2238 margin-left, margin-right, margin-top, margin-bottom
2240 set the page margins
2241 papersize
2243 sets the PDF paper size
2244 Variables for man pages
2246 adjusting
2247 adjusts text to left (l), right (r), center (c), or both (b)
2248 margins
2249 footer footer in man pages
2251 header header in man pages
2253 hyphenate
2255 if true (the default), hyphenation will be used
2256 section
2258 section number in man pages
2259 Variables for ms
2261 fontfamily
2262 font family (e.g. T or P)
2263 indent paragraph indent (e.g. 2m)
2265 lineheight
2267 line height (e.g. 12p)
2268 pointsize
2270 point size (e.g. 10p)
2271 Variables set automatically
2273 Pandoc sets these variables automatically in response to options or
2274 document contents; users can also modify them. These vary depending on
2275 the output format, and include the following:
2276 body body of document
2278 date-meta
2280 the date variable converted to ISO 8601 YYYY-MM-DD, included in
2281 all HTML based formats (dzslides, epub, html, html4, html5, re‐
2282 vealjs, s5, slideous, slidy). The recognized formats for date
2283 are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy
2284 (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy (e.g.
2285 Apr. 02, 2018 or April 02, 2018),yyyy[mm[dd]]](e.g.20180402,
2286 201804 or 2018).
2287 header-includes
2289 contents specified by -H/--include-in-header (may have multiple
2290 values)
2291 include-before
2293 contents specified by -B/--include-before-body (may have multi‐
2294 ple values)
2295 include-after
2297 contents specified by -A/--include-after-body (may have multiple
2298 values)
2299 meta-json
2301 JSON representation of all of the document's metadata. Field
2302 values are transformed to the selected output format.
2303 numbersections
2305 non-null value if -N/--number-sections was specified
2306 sourcefile, outputfile
2308 source and destination filenames, as given on the command line.
2309 sourcefile can also be a list if input comes from multiple
2310 files, or empty if input is from stdin. You can use the follow‐
2311 ing snippet in your template to distinguish them:
2312 $if(sourcefile)$
2314 $for(sourcefile)$
2315 $sourcefile$
2316 $endfor$
2317 $else$
2318 (stdin)
2319 $endif$
2320 Similarly, outputfile can be - if output goes to the terminal.
2322 If you need absolute paths, use e.g. $curdir$/$sourcefile$.
2324 curdir working directory from which pandoc is run.
2326 toc non-null value if --toc/--table-of-contents was specified
2328 toc-title
2330 title of table of contents (works only with EPUB, HTML, opendoc‐
2331 ument, odt, docx, pptx, beamer, LaTeX)
2332
2334 The behavior of some of the readers and writers can be adjusted by en‐
2335 abling or disabling various extensions.
2336 An extension can be enabled by adding +EXTENSION to the format name and
2338 disabled by adding -EXTENSION. For example, --from mark‐
2339 down_strict+footnotes is strict Markdown with footnotes enabled, while
2340 --from markdown-footnotes-pipe_tables is pandoc's Markdown without
2341 footnotes or pipe tables.
2342 The markdown reader and writer make by far the most use of extensions.
2344 Extensions only used by them are therefore covered in the section Pan‐
2345 doc's Markdown below (See Markdown variants for commonmark and gfm.) In
2346 the following, extensions that also work for other formats are covered.
2347 Note that markdown extensions added to the ipynb format affect Markdown
2349 cells in Jupyter notebooks (as do command-line options like --atx-head‐
2350 ers).
2351 Typography
2353 Extension: smart
2354 Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-
2355 dashes, and ... as ellipses. Nonbreaking spaces are inserted after
2356 certain abbreviations, such as "Mr."
2357 This extension can be enabled/disabled for the following formats:
2359 input formats
2361 markdown, commonmark, latex, mediawiki, org, rst, twiki
2362 output formats
2364 markdown, latex, context, rst
2365 enabled by default in
2367 markdown, latex, context (both input and output)
2368 Note: If you are writing Markdown, then the smart extension has the re‐
2370 verse effect: what would have been curly quotes comes out straight.
2371 In LaTeX, smart means to use the standard TeX ligatures for quotation
2373 marks (`` and '' for double quotes, ` and ' for single quotes) and
2374 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
2375 then in reading LaTeX pandoc will parse these characters literally. In
2376 writing LaTeX, enabling smart tells pandoc to use the ligatures when
2377 possible; if smart is disabled pandoc will use unicode quotation mark
2378 and dash characters.
2379 Headings and sections
2381 Extension: auto_identifiers
2382 A heading without an explicitly specified identifier will be automati‐
2383 cally assigned a unique identifier based on the heading text.
2384 This extension can be enabled/disabled for the following formats:
2386 input formats
2388 markdown, latex, rst, mediawiki, textile
2389 output formats
2391 markdown, muse
2392 enabled by default in
2394 markdown, muse
2395 The default algorithm used to derive the identifier from the heading
2397 text is:
2398 · Remove all formatting, links, etc.
2400 · Remove all footnotes.
2402 · Remove all non-alphanumeric characters, except underscores, hyphens,
2404 and periods.
2405 · Replace all spaces and newlines with hyphens.
2407 · Convert all alphabetic characters to lowercase.
2409 · Remove everything up to the first letter (identifiers may not begin
2411 with a number or punctuation mark).
2412 · If nothing is left after this, use the identifier section.
2414 Thus, for example,
2416 Heading Identifier
2418 ─────────────────────────────────────────────────────
2419 Heading identifiers in heading-identifiers-in-
2420 HTML html
2421 Maître d'hôtel maître-dhôtel
2422 *Dogs*?--in *my* house? dogs--in-my-house
2423 [HTML], [S5], or [RTF]? html-s5-or-rtf
2424 3. Applications applications
2425 33 section
2426 These rules should, in most cases, allow one to determine the identifi‐
2428 er from the heading text. The exception is when several headings have
2429 the same text; in this case, the first will get an identifier as de‐
2430 scribed above; the second will get the same identifier with -1 append‐
2431 ed; the third with -2; and so on.
2432 (However, a different algorithm is used if gfm_auto_identifiers is en‐
2434 abled; see below.)
2435 These identifiers are used to provide link targets in the table of con‐
2437 tents generated by the --toc|--table-of-contents option. They also
2438 make it easy to provide links from one section of a document to anoth‐
2439 er. A link to this section, for example, might look like this:
2440 See the section on
2442 [heading identifiers](#heading-identifiers-in-html-latex-and-context).
2443 Note, however, that this method of providing links to sections works
2445 only in HTML, LaTeX, and ConTeXt formats.
2446 If the --section-divs option is specified, then each section will be
2448 wrapped in a section (or a div, if html4 was specified), and the iden‐
2449 tifier will be attached to the enclosing <section> (or <div>) tag
2450 rather than the heading itself. This allows entire sections to be ma‐
2451 nipulated using JavaScript or treated differently in CSS.
2452 Extension: ascii_identifiers
2454 Causes the identifiers produced by auto_identifiers to be pure ASCII.
2455 Accents are stripped off of accented Latin letters, and non-Latin let‐
2456 ters are omitted.
2457 Extension: gfm_auto_identifiers
2459 Changes the algorithm used by auto_identifiers to conform to GitHub's
2460 method. Spaces are converted to dashes (-), uppercase characters to
2461 lowercase characters, and punctuation characters other than - and _ are
2462 removed. Emojis are replaced by their names.
2463 Math Input
2465 The extensions tex_math_dollars, tex_math_single_backslash, and
2466 tex_math_double_backslash are described in the section about Pandoc's
2467 Markdown.
2468 However, they can also be used with HTML input. This is handy for
2470 reading web pages formatted using MathJax, for example.
2471 Raw HTML/TeX
2473 The following extensions (especially how they affect Markdown in‐
2474 put/output) are also described in more detail in their respective sec‐
2475 tions of Pandoc's Markdown.
2476 Extension: raw_html
2478 When converting from HTML, parse elements to raw HTML which are not
2479 representable in pandoc's AST. By default, this is disabled for HTML
2480 input.
2481 Extension: raw_tex
2483 Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
2484 This extension can be enabled/disabled for the following formats (in
2486 addition to markdown):
2487 input formats
2489 latex, org, textile, html (environments, \ref, and \eqref only),
2490 ipynb
2491 output formats
2493 textile, commonmark
2494 Note: as applied to ipynb, raw_html and raw_tex affect not only raw TeX
2496 in markdown cells, but data with mime type text/html in output cells.
2497 Since the ipynb reader attempts to preserve the richest possible out‐
2498 puts when several options are given, you will get best results if you
2499 disable raw_html and raw_tex when converting to formats like docx which
2500 don't allow raw html or tex.
2501 Extension: native_divs
2503 This extension is enabled by default for HTML input. This means that
2504 divs are parsed to pandoc native elements. (Alternatively, you can
2505 parse them to raw HTML using -f html-native_divs+raw_html.)
2506 When converting HTML to Markdown, for example, you may want to drop all
2508 divs and spans:
2509 pandoc -f html-native_divs-native_spans -t markdown
2511 Extension: native_spans
2513 Analogous to native_divs above.
2514 Literate Haskell support
2516 Extension: literate_haskell
2517 Treat the document as literate Haskell source.
2518 This extension can be enabled/disabled for the following formats:
2520 input formats
2522 markdown, rst, latex
2523 output formats
2525 markdown, rst, latex, html
2526 If you append +lhs (or +literate_haskell) to one of the formats above,
2528 pandoc will treat the document as literate Haskell source. This means
2529 that
2530 · In Markdown input, "bird track" sections will be parsed as Haskell
2532 code rather than block quotations. Text between \begin{code} and
2533 \end{code} will also be treated as Haskell code. For ATX-style head‐
2534 ings the character '=' will be used instead of '#'.
2535 · In Markdown output, code blocks with classes haskell and literate
2537 will be rendered using bird tracks, and block quotations will be in‐
2538 dented one space, so they will not be treated as Haskell code. In
2539 addition, headings will be rendered setext-style (with underlines)
2540 rather than ATX-style (with '#' characters). (This is because ghc
2541 treats '#' characters in column 1 as introducing line numbers.)
2542 · In restructured text input, "bird track" sections will be parsed as
2544 Haskell code.
2545 · In restructured text output, code blocks with class haskell will be
2547 rendered using bird tracks.
2548 · In LaTeX input, text in code environments will be parsed as Haskell
2550 code.
2551 · In LaTeX output, code blocks with class haskell will be rendered in‐
2553 side code environments.
2554 · In HTML output, code blocks with class haskell will be rendered with
2556 class literatehaskell and bird tracks.
2557 Examples:
2559 pandoc -f markdown+lhs -t html
2561 reads literate Haskell source formatted with Markdown conventions and
2563 writes ordinary HTML (without bird tracks).
2564 pandoc -f markdown+lhs -t html+lhs
2566 writes HTML with the Haskell code in bird tracks, so it can be copied
2568 and pasted as literate Haskell source.
2569 Note that GHC expects the bird tracks in the first column, so indented
2571 literate code blocks (e.g. inside an itemized environment) will not be
2572 picked up by the Haskell compiler.
2573 Other extensions
2575 Extension: empty_paragraphs
2576 Allows empty paragraphs. By default empty paragraphs are omitted.
2577 This extension can be enabled/disabled for the following formats:
2579 input formats
2581 docx, html
2582 output formats
2584 docx, odt, opendocument, html
2585 Extension: native_numbering
2587 Enables native numbering of figures and tables. Enumeration starts at
2588 1.
2589 This extension can be enabled/disabled for the following formats:
2591 output formats
2593 odt, opendocument
2594 Extension: styles
2596 When converting from docx, read all docx styles as divs (for paragraph
2597 styles) and spans (for character styles) regardless of whether pandoc
2598 understands the meaning of these styles. This can be used with docx
2599 custom styles. Disabled by default.
2600 input formats
2602 docx
2603 Extension: amuse
2605 In the muse input format, this enables Text::Amuse extensions to Emacs
2606 Muse markup.
2607 Extension: citations
2609 Some aspects of Pandoc's Markdown citation syntax are also accepted in
2610 org input.
2611 Extension: ntb
2613 In the context output format this enables the use of Natural Tables
2614 (TABLE) instead of the default Extreme Tables (xtables). Natural ta‐
2615 bles allow more fine-grained global customization but come at a perfor‐
2616 mance penalty compared to extreme tables.
2617
2619 Pandoc understands an extended and slightly revised version of John
2620 Gruber's Markdown syntax. This document explains the syntax, noting
2621 differences from standard Markdown. Except where noted, these differ‐
2622 ences can be suppressed by using the markdown_strict format instead of
2623 markdown. Extensions can be enabled or disabled to specify the behav‐
2624 ior more granularly. They are described in the following. See also
2625 Extensions above, for extensions that work also on other formats.
2626 Philosophy
2628 Markdown is designed to be easy to write, and, even more importantly,
2629 easy to read:
2630 A Markdown-formatted document should be publishable as-is, as
2632 plain text, without looking like it's been marked up with tags
2633 or formatting instructions. -- John Gruber
2634 This principle has guided pandoc's decisions in finding syntax for ta‐
2636 bles, footnotes, and other extensions.
2637 There is, however, one respect in which pandoc's aims are different
2639 from the original aims of Markdown. Whereas Markdown was originally
2640 designed with HTML generation in mind, pandoc is designed for multiple
2641 output formats. Thus, while pandoc allows the embedding of raw HTML,
2642 it discourages it, and provides other, non-HTMLish ways of representing
2643 important document elements like definition lists, tables, mathematics,
2644 and footnotes.
2645 Paragraphs
2647 A paragraph is one or more lines of text followed by one or more blank
2648 lines. Newlines are treated as spaces, so you can reflow your para‐
2649 graphs as you like. If you need a hard line break, put two or more
2650 spaces at the end of a line.
2651 Extension: escaped_line_breaks
2653 A backslash followed by a newline is also a hard line break. Note: in
2654 multiline and grid table cells, this is the only way to create a hard
2655 line break, since trailing spaces in the cells are ignored.
2656 Headings
2658 There are two kinds of headings: Setext and ATX.
2659 Setext-style headings
2661 A setext-style heading is a line of text "underlined" with a row of =
2662 signs (for a level-one heading) or - signs (for a level-two heading):
2663 A level-one heading
2665 ===================
2666 A level-two heading
2668 -------------------
2669 The heading text can contain inline formatting, such as emphasis (see
2671 Inline formatting, below).
2672 ATX-style headings
2674 An ATX-style heading consists of one to six # signs and a line of text,
2675 optionally followed by any number of # signs. The number of # signs at
2676 the beginning of the line is the heading level:
2677 ## A level-two heading
2679 ### A level-three heading ###
2681 As with setext-style headings, the heading text can contain formatting:
2683 # A level-one heading with a [link](/url) and *emphasis*
2685 Extension: blank_before_header
2687 Standard Markdown syntax does not require a blank line before a head‐
2688 ing. Pandoc does require this (except, of course, at the beginning of
2689 the document). The reason for the requirement is that it is all too
2690 easy for a # to end up at the beginning of a line by accident (perhaps
2691 through line wrapping). Consider, for example:
2692 I like several of their flavors of ice cream:
2694 #22, for example, and #5.
2695 Extension: space_in_atx_header
2697 Many Markdown implementations do not require a space between the open‐
2698 ing #s of an ATX heading and the heading text, so that #5 bolt and
2699 #hashtag count as headings. With this extension, pandoc does require
2700 the space.
2701 Heading identifiers
2703 See also the auto_identifiers extension above.
2704 Extension: header_attributes
2706 Headings can be assigned attributes using this syntax at the end of the
2707 line containing the heading text:
2708 {#identifier .class .class key=value key=value}
2710 Thus, for example, the following headings will all be assigned the
2712 identifier foo:
2713 # My heading {#foo}
2715 ## My heading ## {#foo}
2717 My other heading {#foo}
2719 ---------------
2720 (This syntax is compatible with PHP Markdown Extra.)
2722 Note that although this syntax allows assignment of classes and
2724 key/value attributes, writers generally don't use all of this informa‐
2725 tion. Identifiers, classes, and key/value attributes are used in HTML
2726 and HTML-based formats such as EPUB and slidy. Identifiers are used
2727 for labels and link anchors in the LaTeX, ConTeXt, Textile, Jira
2728 markup, and AsciiDoc writers.
2729 Headings with the class unnumbered will not be numbered, even if --num‐
2731 ber-sections is specified. A single hyphen (-) in an attribute context
2732 is equivalent to .unnumbered, and preferable in non-English documents.
2733 So,
2734 # My heading {-}
2736 is just the same as
2738 # My heading {.unnumbered}
2740 If the unlisted class is present in addition to unnumbered, the heading
2742 will not be included in a table of contents. (Currently this feature
2743 is only implemented for certain formats: those based on LaTeX and HTML,
2744 PowerPoint, and RTF.)
2745 Extension: implicit_header_references
2747 Pandoc behaves as if reference links have been defined for each head‐
2748 ing. So, to link to a heading
2749 # Heading identifiers in HTML
2751 you can simply write
2753 [Heading identifiers in HTML]
2755 or
2757 [Heading identifiers in HTML][]
2759 or
2761 [the section on heading identifiers][heading identifiers in
2763 HTML]
2764 instead of giving the identifier explicitly:
2766 [Heading identifiers in HTML](#heading-identifiers-in-html)
2768 If there are multiple headings with identical text, the corresponding
2770 reference will link to the first one only, and you will need to use ex‐
2771 plicit links to link to the others, as described above.
2772 Like regular reference links, these references are case-insensitive.
2774 Explicit link reference definitions always take priority over implicit
2776 heading references. So, in the following example, the link will point
2777 to bar, not to #foo:
2778 # Foo
2780 [foo]: bar
2782 See [foo]
2784 Block quotations
2786 Markdown uses email conventions for quoting blocks of text. A block
2787 quotation is one or more paragraphs or other block elements (such as
2788 lists or headings), with each line preceded by a > character and an op‐
2789 tional space. (The > need not start at the left margin, but it should
2790 not be indented more than three spaces.)
2791 > This is a block quote. This
2793 > paragraph has two lines.
2794 >
2795 > 1. This is a list inside a block quote.
2796 > 2. Second item.
2797 A "lazy" form, which requires the > character only on the first line of
2799 each block, is also allowed:
2800 > This is a block quote. This
2802 paragraph has two lines.
2803 > 1. This is a list inside a block quote.
2805 2. Second item.
2806 Among the block elements that can be contained in a block quote are
2808 other block quotes. That is, block quotes can be nested:
2809 > This is a block quote.
2811 >
2812 > > A block quote within a block quote.
2813 If the > character is followed by an optional space, that space will be
2815 considered part of the block quote marker and not part of the indenta‐
2816 tion of the contents. Thus, to put an indented code block in a block
2817 quote, you need five spaces after the >:
2818 > code
2820 Extension: blank_before_blockquote
2822 Standard Markdown syntax does not require a blank line before a block
2823 quote. Pandoc does require this (except, of course, at the beginning
2824 of the document). The reason for the requirement is that it is all too
2825 easy for a > to end up at the beginning of a line by accident (perhaps
2826 through line wrapping). So, unless the markdown_strict format is used,
2827 the following does not produce a nested block quote in pandoc:
2828 > This is a block quote.
2830 >> Nested.
2831 Verbatim (code) blocks
2833 Indented code blocks
2834 A block of text indented four spaces (or one tab) is treated as verba‐
2835 tim text: that is, special characters do not trigger special format‐
2836 ting, and all spaces and line breaks are preserved. For example,
2837 if (a > 3) {
2839 moveShip(5 * gravity, DOWN);
2840 }
2841 The initial (four space or one tab) indentation is not considered part
2843 of the verbatim text, and is removed in the output.
2844 Note: blank lines in the verbatim text need not begin with four spaces.
2846 Fenced code blocks
2848 Extension: fenced_code_blocks
2849 In addition to standard indented code blocks, pandoc supports fenced
2850 code blocks. These begin with a row of three or more tildes (~) and
2851 end with a row of tildes that must be at least as long as the starting
2852 row. Everything between these lines is treated as code. No indenta‐
2853 tion is necessary:
2854 ~~~~~~~
2856 if (a > 3) {
2857 moveShip(5 * gravity, DOWN);
2858 }
2859 ~~~~~~~
2860 Like regular code blocks, fenced code blocks must be separated from
2862 surrounding text by blank lines.
2863 If the code itself contains a row of tildes or backticks, just use a
2865 longer row of tildes or backticks at the start and end:
2866 ~~~~~~~~~~~~~~~~
2868 ~~~~~~~~~~
2869 code including tildes
2870 ~~~~~~~~~~
2871 ~~~~~~~~~~~~~~~~
2872 Extension: backtick_code_blocks
2874 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
2875 (~).
2876 Extension: fenced_code_attributes
2878 Optionally, you may attach attributes to fenced or backtick code block
2879 using this syntax:
2880 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
2882 qsort [] = []
2883 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
2884 qsort (filter (>= x) xs)
2885 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2886 Here mycode is an identifier, haskell and numberLines are classes, and
2888 startFrom is an attribute with value 100. Some output formats can use
2889 this information to do syntax highlighting. Currently, the only output
2890 formats that uses this information are HTML, LaTeX, Docx, Ms, and Pow‐
2891 erPoint. If highlighting is supported for your output format and lan‐
2892 guage, then the code block above will appear highlighted, with numbered
2893 lines. (To see which languages are supported, type pandoc --list-high‐
2894 light-languages.) Otherwise, the code block above will appear as fol‐
2895 lows:
2896 <pre id="mycode" class="haskell numberLines" startFrom="100">
2898 <code>
2899 ...
2900 </code>
2901 </pre>
2902 The numberLines (or number-lines) class will cause the lines of the
2904 code block to be numbered, starting with 1 or the value of the start‐
2905 From attribute. The lineAnchors (or line-anchors) class will cause the
2906 lines to be clickable anchors in HTML output.
2907 A shortcut form can also be used for specifying the language of the
2909 code block:
2910 ```haskell
2912 qsort [] = []
2913 ```
2914 This is equivalent to:
2916 ``` {.haskell}
2918 qsort [] = []
2919 ```
2920 If the fenced_code_attributes extension is disabled, but input contains
2922 class attribute(s) for the code block, the first class attribute will
2923 be printed after the opening fence as a bare word.
2924 To prevent all highlighting, use the --no-highlight flag. To set the
2926 highlighting style, use --highlight-style. For more information on
2927 highlighting, see Syntax highlighting, below.
2928 Line blocks
2930 Extension: line_blocks
2931 A line block is a sequence of lines beginning with a vertical bar (|)
2932 followed by a space. The division into lines will be preserved in the
2933 output, as will any leading spaces; otherwise, the lines will be for‐
2934 matted as Markdown. This is useful for verse and addresses:
2935 | The limerick packs laughs anatomical
2937 | In space that is quite economical.
2938 | But the good ones I've seen
2939 | So seldom are clean
2940 | And the clean ones so seldom are comical
2941 | 200 Main St.
2943 | Berkeley, CA 94718
2944 The lines can be hard-wrapped if needed, but the continuation line must
2946 begin with a space.
2947 | The Right Honorable Most Venerable and Righteous Samuel L.
2949 Constable, Jr.
2950 | 200 Main St.
2951 | Berkeley, CA 94718
2952 This syntax is borrowed from reStructuredText.
2954 Lists
2956 Bullet lists
2957 A bullet list is a list of bulleted list items. A bulleted list item
2958 begins with a bullet (*, +, or -). Here is a simple example:
2959 * one
2961 * two
2962 * three
2963 This will produce a "compact" list. If you want a "loose" list, in
2965 which each item is formatted as a paragraph, put spaces between the
2966 items:
2967 * one
2969 * two
2971 * three
2973 The bullets need not be flush with the left margin; they may be indent‐
2975 ed one, two, or three spaces. The bullet must be followed by white‐
2976 space.
2977 List items look best if subsequent lines are flush with the first line
2979 (after the bullet):
2980 * here is my first
2982 list item.
2983 * and my second.
2984 But Markdown also allows a "lazy" format:
2986 * here is my first
2988 list item.
2989 * and my second.
2990 Block content in list items
2992 A list item may contain multiple paragraphs and other block-level con‐
2993 tent. However, subsequent paragraphs must be preceded by a blank line
2994 and indented to line up with the first non-space content after the list
2995 marker.
2996 * First paragraph.
2998 Continued.
3000 * Second paragraph. With a code block, which must be indented
3002 eight spaces:
3003 { code }
3005 Exception: if the list marker is followed by an indented code block,
3007 which must begin 5 spaces after the list marker, then subsequent para‐
3008 graphs must begin two columns after the last character of the list
3009 marker:
3010 * code
3012 continuation paragraph
3014 List items may include other lists. In this case the preceding blank
3016 line is optional. The nested list must be indented to line up with the
3017 first non-space character after the list marker of the containing list
3018 item.
3019 * fruits
3021 + apples
3022 - macintosh
3023 - red delicious
3024 + pears
3025 + peaches
3026 * vegetables
3027 + broccoli
3028 + chard
3029 As noted above, Markdown allows you to write list items "lazily," in‐
3031 stead of indenting continuation lines. However, if there are multiple
3032 paragraphs or other blocks in a list item, the first line of each must
3033 be indented.
3034 + A lazy, lazy, list
3036 item.
3037 + Another one; this looks
3039 bad but is legal.
3040 Second paragraph of second
3042 list item.
3043 Ordered lists
3045 Ordered lists work just like bulleted lists, except that the items be‐
3046 gin with enumerators rather than bullets.
3047 In standard Markdown, enumerators are decimal numbers followed by a pe‐
3049 riod and a space. The numbers themselves are ignored, so there is no
3050 difference between this list:
3051 1. one
3053 2. two
3054 3. three
3055 and this one:
3057 5. one
3059 7. two
3060 1. three
3061 Extension: fancy_lists
3063 Unlike standard Markdown, pandoc allows ordered list items to be marked
3064 with uppercase and lowercase letters and roman numerals, in addition to
3065 Arabic numerals. List markers may be enclosed in parentheses or fol‐
3066 lowed by a single right-parentheses or period. They must be separated
3067 from the text that follows by at least one space, and, if the list
3068 marker is a capital letter with a period, by at least two spaces.
3069 The fancy_lists extension also allows '#' to be used as an ordered list
3071 marker in place of a numeral:
3072 #. one
3074 #. two
3075 Extension: startnum
3077 Pandoc also pays attention to the type of list marker used, and to the
3078 starting number, and both of these are preserved where possible in the
3079 output format. Thus, the following yields a list with numbers followed
3080 by a single parenthesis, starting with 9, and a sublist with lowercase
3081 roman numerals:
3082 9) Ninth
3084 10) Tenth
3085 11) Eleventh
3086 i. subone
3087 ii. subtwo
3088 iii. subthree
3089 Pandoc will start a new list each time a different type of list marker
3091 is used. So, the following will create three lists:
3092 (2) Two
3094 (5) Three
3095 1. Four
3096 * Five
3097 If default list markers are desired, use #.:
3099 #. one
3101 #. two
3102 #. three
3103 Extension: task_lists
3105 Pandoc supports task lists, using the syntax of GitHub-Flavored Mark‐
3106 down.
3107 - [ ] an unchecked task list item
3109 - [x] checked item
3110 Definition lists
3112 Extension: definition_lists
3113 Pandoc supports definition lists, using the syntax of PHP Markdown Ex‐
3114 tra with some extensions.
3115 Term 1
3117 : Definition 1
3119 Term 2 with *inline markup*
3121 : Definition 2
3123 { some code, part of Definition 2 }
3125 Third paragraph of definition 2.
3127 Each term must fit on one line, which may optionally be followed by a
3129 blank line, and must be followed by one or more definitions. A defini‐
3130 tion begins with a colon or tilde, which may be indented one or two
3131 spaces.
3132 A term may have multiple definitions, and each definition may consist
3134 of one or more block elements (paragraph, code block, list, etc.), each
3135 indented four spaces or one tab stop. The body of the definition (in‐
3136 cluding the first line, aside from the colon or tilde) should be in‐
3137 dented four spaces. However, as with other Markdown lists, you can
3138 "lazily" omit indentation except at the beginning of a paragraph or
3139 other block element:
3140 Term 1
3142 : Definition
3144 with lazy continuation.
3145 Second paragraph of the definition.
3147 If you leave space before the definition (as in the example above), the
3149 text of the definition will be treated as a paragraph. In some output
3150 formats, this will mean greater spacing between term/definition pairs.
3151 For a more compact definition list, omit the space before the defini‐
3152 tion:
3153 Term 1
3155 ~ Definition 1
3156 Term 2
3158 ~ Definition 2a
3159 ~ Definition 2b
3160 Note that space between items in a definition list is required. (A
3162 variant that loosens this requirement, but disallows "lazy" hard wrap‐
3163 ping, can be activated with compact_definition_lists: see Non-pandoc
3164 extensions, below.)
3165 Numbered example lists
3167 Extension: example_lists
3168 The special list marker @ can be used for sequentially numbered exam‐
3169 ples. The first list item with a @ marker will be numbered '1', the
3170 next '2', and so on, throughout the document. The numbered examples
3171 need not occur in a single list; each new list using @ will take up
3172 where the last stopped. So, for example:
3173 (@) My first example will be numbered (1).
3175 (@) My second example will be numbered (2).
3176 Explanation of examples.
3178 (@) My third example will be numbered (3).
3180 Numbered examples can be labeled and referred to elsewhere in the docu‐
3182 ment:
3183 (@good) This is a good example.
3185 As (@good) illustrates, ...
3187 The label can be any string of alphanumeric characters, underscores, or
3189 hyphens.
3190 Note: continuation paragraphs in example lists must always be indented
3192 four spaces, regardless of the length of the list marker. That is, ex‐
3193 ample lists always behave as if the four_space_rule extension is set.
3194 This is because example labels tend to be long, and indenting content
3195 to the first non-space character after the label would be awkward.
3196 Compact and loose lists
3198 Pandoc behaves differently from Markdown.pl on some "edge cases" in‐
3199 volving lists. Consider this source:
3200 + First
3202 + Second:
3203 - Fee
3204 - Fie
3205 - Foe
3206 + Third
3208 Pandoc transforms this into a "compact list" (with no <p> tags around
3210 "First", "Second", or "Third"), while Markdown puts <p> tags around
3211 "Second" and "Third" (but not "First"), because of the blank space
3212 around "Third". Pandoc follows a simple rule: if the text is followed
3213 by a blank line, it is treated as a paragraph. Since "Second" is fol‐
3214 lowed by a list, and not a blank line, it isn't treated as a paragraph.
3215 The fact that the list is followed by a blank line is irrelevant.
3216 (Note: Pandoc works this way even when the markdown_strict format is
3217 specified. This behavior is consistent with the official Markdown syn‐
3218 tax description, even though it is different from that of Markdown.pl.)
3219 Ending a list
3221 What if you want to put an indented code block after a list?
3222 - item one
3224 - item two
3225 { my code block }
3227 Trouble! Here pandoc (like other Markdown implementations) will treat {
3229 my code block } as the second paragraph of item two, and not as a code
3230 block.
3231 To "cut off" the list after item two, you can insert some non-indented
3233 content, like an HTML comment, which won't produce visible output in
3234 any format:
3235 - item one
3237 - item two
3238 <!-- end of list -->
3240 { my code block }
3242 You can use the same trick if you want two consecutive lists instead of
3244 one big list:
3245 1. one
3247 2. two
3248 3. three
3249 <!-- -->
3251 1. uno
3253 2. dos
3254 3. tres
3255 Horizontal rules
3257 A line containing a row of three or more *, -, or _ characters (option‐
3258 ally separated by spaces) produces a horizontal rule:
3259 * * * *
3261 ---------------
3263 Tables
3265 Four kinds of tables may be used. The first three kinds presuppose the
3266 use of a fixed-width font, such as Courier. The fourth kind can be
3267 used with proportionally spaced fonts, as it does not require lining up
3268 columns.
3269 Extension: table_captions
3271 A caption may optionally be provided with all 4 kinds of tables (as il‐
3272 lustrated in the examples below). A caption is a paragraph beginning
3273 with the string Table: (or just :), which will be stripped off. It may
3274 appear either before or after the table.
3275 Extension: simple_tables
3277 Simple tables look like this:
3278 Right Left Center Default
3280 ------- ------ ---------- -------
3281 12 12 12 12
3282 123 123 123 123
3283 1 1 1 1
3284 Table: Demonstration of simple table syntax.
3286 The header and table rows must each fit on one line. Column alignments
3288 are determined by the position of the header text relative to the
3289 dashed line below it:
3290 · If the dashed line is flush with the header text on the right side
3292 but extends beyond it on the left, the column is right-aligned.
3293 · If the dashed line is flush with the header text on the left side but
3295 extends beyond it on the right, the column is left-aligned.
3296 · If the dashed line extends beyond the header text on both sides, the
3298 column is centered.
3299 · If the dashed line is flush with the header text on both sides, the
3301 default alignment is used (in most cases, this will be left).
3302 The table must end with a blank line, or a line of dashes followed by a
3304 blank line.
3305 The column header row may be omitted, provided a dashed line is used to
3307 end the table. For example:
3308 ------- ------ ---------- -------
3310 12 12 12 12
3311 123 123 123 123
3312 1 1 1 1
3313 ------- ------ ---------- -------
3314 When the header row is omitted, column alignments are determined on the
3316 basis of the first line of the table body. So, in the tables above,
3317 the columns would be right, left, center, and right aligned, respec‐
3318 tively.
3319 Extension: multiline_tables
3321 Multiline tables allow header and table rows to span multiple lines of
3322 text (but cells that span multiple columns or rows of the table are not
3323 supported). Here is an example:
3324 -------------------------------------------------------------
3326 Centered Default Right Left
3327 Header Aligned Aligned Aligned
3328 ----------- ------- --------------- -------------------------
3329 First row 12.0 Example of a row that
3330 spans multiple lines.
3331 Second row 5.0 Here's another one. Note
3333 the blank line between
3334 rows.
3335 -------------------------------------------------------------
3336 Table: Here's the caption. It, too, may span
3338 multiple lines.
3339 These work like simple tables, but with the following differences:
3341 · They must begin with a row of dashes, before the header text (unless
3343 the header row is omitted).
3344 · They must end with a row of dashes, then a blank line.
3346 · The rows must be separated by blank lines.
3348 In multiline tables, the table parser pays attention to the widths of
3350 the columns, and the writers try to reproduce these relative widths in
3351 the output. So, if you find that one of the columns is too narrow in
3352 the output, try widening it in the Markdown source.
3353 The header may be omitted in multiline tables as well as simple tables:
3355 ----------- ------- --------------- -------------------------
3357 First row 12.0 Example of a row that
3358 spans multiple lines.
3359 Second row 5.0 Here's another one. Note
3361 the blank line between
3362 rows.
3363 ----------- ------- --------------- -------------------------
3364 : Here's a multiline table without a header.
3366 It is possible for a multiline table to have just one row, but the row
3368 should be followed by a blank line (and then the row of dashes that
3369 ends the table), or the table may be interpreted as a simple table.
3370 Extension: grid_tables
3372 Grid tables look like this:
3373 : Sample grid table.
3375 +---------------+---------------+--------------------+
3377 | Fruit | Price | Advantages |
3378 +===============+===============+====================+
3379 | Bananas | $1.34 | - built-in wrapper |
3380 | | | - bright color |
3381 +---------------+---------------+--------------------+
3382 | Oranges | $2.10 | - cures scurvy |
3383 | | | - tasty |
3384 +---------------+---------------+--------------------+
3385 The row of =s separates the header from the table body, and can be
3387 omitted for a headerless table. The cells of grid tables may contain
3388 arbitrary block elements (multiple paragraphs, code blocks, lists,
3389 etc.). Cells that span multiple columns or rows are not supported.
3390 Grid tables can be created easily using Emacs' table-mode (M-x table-
3391 insert).
3392 Alignments can be specified as with pipe tables, by putting colons at
3394 the boundaries of the separator line after the header:
3395 +---------------+---------------+--------------------+
3397 | Right | Left | Centered |
3398 +==============:+:==============+:==================:+
3399 | Bananas | $1.34 | built-in wrapper |
3400 +---------------+---------------+--------------------+
3401 For headerless tables, the colons go on the top line instead:
3403 +--------------:+:--------------+:------------------:+
3405 | Right | Left | Centered |
3406 +---------------+---------------+--------------------+
3407 Grid Table Limitations
3409 Pandoc does not support grid tables with row spans or column spans.
3410 This means that neither variable numbers of columns across rows nor
3411 variable numbers of rows across columns are supported by Pandoc. All
3412 grid tables must have the same number of columns in each row, and the
3413 same number of rows in each column. For example, the Docutils sample
3414 grid tables will not render as expected with Pandoc.
3415 Extension: pipe_tables
3417 Pipe tables look like this:
3418 | Right | Left | Default | Center |
3420 |------:|:-----|---------|:------:|
3421 | 12 | 12 | 12 | 12 |
3422 | 123 | 123 | 123 | 123 |
3423 | 1 | 1 | 1 | 1 |
3424 : Demonstration of pipe table syntax.
3426 The syntax is identical to PHP Markdown Extra tables. The beginning
3428 and ending pipe characters are optional, but pipes are required between
3429 all columns. The colons indicate column alignment as shown. The head‐
3430 er cannot be omitted. To simulate a headerless table, include a header
3431 with blank cells.
3432 Since the pipes indicate column boundaries, columns need not be verti‐
3434 cally aligned, as they are in the above example. So, this is a per‐
3435 fectly legal (though ugly) pipe table:
3436 fruit| price
3438 -----|-----:
3439 apple|2.05
3440 pear|1.37
3441 orange|3.09
3442 The cells of pipe tables cannot contain block elements like paragraphs
3444 and lists, and cannot span multiple lines. If a pipe table contains a
3445 row whose printable content is wider than the column width (see --col‐
3446 umns), then the table will take up the full text width and the cell
3447 contents will wrap, with the relative cell widths determined by the
3448 number of dashes in the line separating the table header from the table
3449 body. (For example ---|- would make the first column 3/4 and the sec‐
3450 ond column 1/4 of the full text width.) On the other hand, if no lines
3451 are wider than column width, then cell contents will not be wrapped,
3452 and the cells will be sized to their contents.
3453 Note: pandoc also recognizes pipe tables of the following form, as can
3455 be produced by Emacs' orgtbl-mode:
3456 | One | Two |
3458 |-----+-------|
3459 | my | table |
3460 | is | nice |
3461 The difference is that + is used instead of |. Other orgtbl features
3463 are not supported. In particular, to get non-default column alignment,
3464 you'll need to add colons as above.
3465 Metadata blocks
3467 Extension: pandoc_title_block
3468 If the file begins with a title block
3469 % title
3471 % author(s) (separated by semicolons)
3472 % date
3473 it will be parsed as bibliographic information, not regular text. (It
3475 will be used, for example, in the title of standalone LaTeX or HTML
3476 output.) The block may contain just a title, a title and an author, or
3477 all three elements. If you want to include an author but no title, or
3478 a title and a date but no author, you need a blank line:
3479 %
3481 % Author
3482 % My title
3484 %
3485 % June 15, 2006
3486 The title may occupy multiple lines, but continuation lines must begin
3488 with leading space, thus:
3489 % My title
3491 on multiple lines
3492 If a document has multiple authors, the authors may be put on separate
3494 lines with leading space, or separated by semicolons, or both. So, all
3495 of the following are equivalent:
3496 % Author One
3498 Author Two
3499 % Author One; Author Two
3501 % Author One;
3503 Author Two
3504 The date must fit on one line.
3506 All three metadata fields may contain standard inline formatting (ital‐
3508 ics, links, footnotes, etc.).
3509 Title blocks will always be parsed, but they will affect the output on‐
3511 ly when the --standalone (-s) option is chosen. In HTML output, titles
3512 will appear twice: once in the document head -- this is the title that
3513 will appear at the top of the window in a browser -- and once at the
3514 beginning of the document body. The title in the document head can
3515 have an optional prefix attached (--title-prefix or -T option). The
3516 title in the body appears as an H1 element with class "title", so it
3517 can be suppressed or reformatted with CSS. If a title prefix is speci‐
3518 fied with -T and no title block appears in the document, the title pre‐
3519 fix will be used by itself as the HTML title.
3520 The man page writer extracts a title, man page section number, and oth‐
3522 er header and footer information from the title line. The title is as‐
3523 sumed to be the first word on the title line, which may optionally end
3524 with a (single-digit) section number in parentheses. (There should be
3525 no space between the title and the parentheses.) Anything after this
3526 is assumed to be additional footer and header text. A single pipe
3527 character (|) should be used to separate the footer text from the head‐
3528 er text. Thus,
3529 % PANDOC(1)
3531 will yield a man page with the title PANDOC and section 1.
3533 % PANDOC(1) Pandoc User Manuals
3535 will also have "Pandoc User Manuals" in the footer.
3537 % PANDOC(1) Pandoc User Manuals | Version 4.0
3539 will also have "Version 4.0" in the header.
3541 Extension: yaml_metadata_block
3543 A YAML metadata block is a valid YAML object, delimited by a line of
3544 three hyphens (---) at the top and a line of three hyphens (---) or
3545 three dots (...) at the bottom. A YAML metadata block may occur any‐
3546 where in the document, but if it is not at the beginning, it must be
3547 preceded by a blank line. (Note that, because of the way pandoc con‐
3548 catenates input files when several are provided, you may also keep the
3549 metadata in a separate YAML file and pass it to pandoc as an argument,
3550 along with your Markdown files:
3551 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
3553 Just be sure that the YAML file begins with --- and ends with --- or
3555 ....) Alternatively, you can use the --metadata-file option. Using
3556 that approach however, you cannot reference content (like footnotes)
3557 from the main markdown input document.
3558 Metadata will be taken from the fields of the YAML object and added to
3560 any existing document metadata. Metadata can contain lists and objects
3561 (nested arbitrarily), but all string scalars will be interpreted as
3562 Markdown. Fields with names ending in an underscore will be ignored by
3563 pandoc. (They may be given a role by external processors.) Field names
3564 must not be interpretable as YAML numbers or boolean values (so, for
3565 example, yes, True, and 15 cannot be used as field names).
3566 A document may contain multiple metadata blocks. If two metadata
3568 blocks attempt to set the same field, the value from the second block
3569 will be taken.
3570 When pandoc is used with -t markdown to create a Markdown document, a
3572 YAML metadata block will be produced only if the -s/--standalone option
3573 is used. All of the metadata will appear in a single block at the be‐
3574 ginning of the document.
3575 Note that YAML escaping rules must be followed. Thus, for example, if
3577 a title contains a colon, it must be quoted. The pipe character (|)
3578 can be used to begin an indented block that will be interpreted liter‐
3579 ally, without need for escaping. This form is necessary when the field
3580 contains blank lines or block-level formatting:
3581 ---
3583 title: 'This is the title: it contains a colon'
3584 author:
3585 - Author One
3586 - Author Two
3587 keywords: [nothing, nothingness]
3588 abstract: |
3589 This is the abstract.
3590 It consists of two paragraphs.
3592 ...
3593 Template variables will be set automatically from the metadata. Thus,
3595 for example, in writing HTML, the variable abstract will be set to the
3596 HTML equivalent of the Markdown in the abstract field:
3597 <p>This is the abstract.</p>
3599 <p>It consists of two paragraphs.</p>
3600 Variables can contain arbitrary YAML structures, but the template must
3602 match this structure. The author variable in the default templates ex‐
3603 pects a simple list or string, but can be changed to support more com‐
3604 plicated structures. The following combination, for example, would add
3605 an affiliation to the author if one is given:
3606 ---
3608 title: The document title
3609 author:
3610 - name: Author One
3611 affiliation: University of Somewhere
3612 - name: Author Two
3613 affiliation: University of Nowhere
3614 ...
3615 To use the structured authors in the example above, you would need a
3617 custom template:
3618 $for(author)$
3620 $if(author.name)$
3621 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
3622 $else$
3623 $author$
3624 $endif$
3625 $endfor$
3626 Raw content to include in the document's header may be specified using
3628 header-includes; however, it is important to mark up this content as
3629 raw code for a particular output format, using the raw_attribute exten‐
3630 sion), or it will be interpreted as markdown. For example:
3631 header-includes:
3633 - |
3634 ```{=latex}
3635 \let\oldsection\section
3636 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
3637 ```
3638 Backslash escapes
3640 Extension: all_symbols_escapable
3641 Except inside a code block or inline code, any punctuation or space
3642 character preceded by a backslash will be treated literally, even if it
3643 would normally indicate formatting. Thus, for example, if one writes
3644 *\*hello\**
3646 one will get
3648 <em>*hello*</em>
3650 instead of
3652 <strong>hello</strong>
3654 This rule is easier to remember than standard Markdown's rule, which
3656 allows only the following characters to be backslash-escaped:
3657 \`*_{}[]()>#+-.!
3659 (However, if the markdown_strict format is used, the standard Markdown
3661 rule will be used.)
3662 A backslash-escaped space is parsed as a nonbreaking space. In TeX
3664 output, it will appear as ~. In HTML and XML output, it will appear as
3665 a literal unicode nonbreaking space character (note that it will thus
3666 actually look "invisible" in the generated HTML source; you can still
3667 use the --ascii command-line option to make it appear as an explicit
3668 entity).
3669 A backslash-escaped newline (i.e. a backslash occurring at the end of
3671 a line) is parsed as a hard line break. It will appear in TeX output
3672 as \\ and in HTML as <br />. This is a nice alternative to Markdown's
3673 "invisible" way of indicating hard line breaks using two trailing spa‐
3674 ces on a line.
3675 Backslash escapes do not work in verbatim contexts.
3677 Inline formatting
3679 Emphasis
3680 To emphasize some text, surround it with *s or _, like this:
3681 This text is _emphasized with underscores_, and this
3683 is *emphasized with asterisks*.
3684 Double * or _ produces strong emphasis:
3686 This is **strong emphasis** and __with underscores__.
3688 A * or _ character surrounded by spaces, or backslash-escaped, will not
3690 trigger emphasis:
3691 This is * not emphasized *, and \*neither is this\*.
3693 Extension: intraword_underscores
3695 Because _ is sometimes used inside words and identifiers, pandoc does
3696 not interpret a _ surrounded by alphanumeric characters as an emphasis
3697 marker. If you want to emphasize just part of a word, use *:
3698 feas*ible*, not feas*able*.
3700 Strikeout
3702 Extension: strikeout
3703 To strikeout a section of text with a horizontal line, begin and end it
3704 with ~~. Thus, for example,
3705 This ~~is deleted text.~~
3707 Superscripts and subscripts
3709 Extension: superscript, subscript
3710 Superscripts may be written by surrounding the superscripted text by ^
3711 characters; subscripts may be written by surrounding the subscripted
3712 text by ~ characters. Thus, for example,
3713 H~2~O is a liquid. 2^10^ is 1024.
3715 The text between ^...^ or ~...~ may not contain spaces or newlines. If
3717 the superscripted or subscripted text contains spaces, these spaces
3718 must be escaped with backslashes. (This is to prevent accidental su‐
3719 perscripting and subscripting through the ordinary use of ~ and ^, and
3720 also bad interactions with footnotes.) Thus, if you want the letter P
3721 with 'a cat' in subscripts, use P~a\ cat~, not P~a cat~.
3722 Verbatim
3724 To make a short span of text verbatim, put it inside backticks:
3725 What is the difference between `>>=` and `>>`?
3727 If the verbatim text includes a backtick, use double backticks:
3729 Here is a literal backtick `` ` ``.
3731 (The spaces after the opening backticks and before the closing back‐
3733 ticks will be ignored.)
3734 The general rule is that a verbatim span starts with a string of con‐
3736 secutive backticks (optionally followed by a space) and ends with a
3737 string of the same number of backticks (optionally preceded by a
3738 space).
3739 Note that backslash-escapes (and other Markdown constructs) do not work
3741 in verbatim contexts:
3742 This is a backslash followed by an asterisk: `\*`.
3744 Extension: inline_code_attributes
3746 Attributes can be attached to verbatim text, just as with fenced code
3747 blocks:
3748 `<$>`{.haskell}
3750 Small caps
3752 To write small caps, use the smallcaps class:
3753 [Small caps]{.smallcaps}
3755 Or, without the bracketed_spans extension:
3757 <span class="smallcaps">Small caps</span>
3759 For compatibility with other Markdown flavors, CSS is also supported:
3761 <span style="font-variant:small-caps;">Small caps</span>
3763 This will work in all output formats that support small caps.
3765 Math
3767 Extension: tex_math_dollars
3768 Anything between two $ characters will be treated as TeX math. The
3769 opening $ must have a non-space character immediately to its right,
3770 while the closing $ must have a non-space character immediately to its
3771 left, and must not be followed immediately by a digit. Thus, $20,000
3772 and $30,000 won't parse as math. If for some reason you need to en‐
3773 close text in literal $ characters, backslash-escape them and they
3774 won't be treated as math delimiters.
3775 For display math, use $$ delimiters. (In this case, the delimiters may
3777 be separated from the formula by whitespace.)
3778 TeX math will be printed in all output formats. How it is rendered de‐
3780 pends on the output format:
3781 LaTeX It will appear verbatim surrounded by \(...\) (for inline math)
3783 or \[...\] (for display math).
3784 Markdown, Emacs Org mode, ConTeXt, ZimWiki
3786 It will appear verbatim surrounded by $...$ (for inline math) or
3787 $$...$$ (for display math).
3788 XWiki It will appear verbatim surrounded by {{formula}}..{{/formula}}.
3790 reStructuredText
3792 It will be rendered using an interpreted text role :math:.
3793 AsciiDoc
3795 For AsciiDoc output format (-t asciidoc) it will appear verbatim
3796 surrounded by latexmath:[$...$] (for inline math) or [latex‐
3797 math]++++\[...\]+++ (for display math). For AsciiDoctor output
3798 format (-t asciidoctor) the LaTex delimiters ($..$ and \[..\])
3799 are omitted.
3800 Texinfo
3802 It will be rendered inside a @math command.
3803 roff man, Jira markup
3805 It will be rendered verbatim without $'s.
3806 MediaWiki, DokuWiki
3808 It will be rendered inside <math> tags.
3809 Textile
3811 It will be rendered inside <span class="math"> tags.
3812 RTF, OpenDocument
3814 It will be rendered, if possible, using Unicode characters, and
3815 will otherwise appear verbatim.
3816 ODT It will be rendered, if possible, using MathML.
3818 DocBook
3820 If the --mathml flag is used, it will be rendered using MathML
3821 in an inlineequation or informalequation tag. Otherwise it will
3822 be rendered, if possible, using Unicode characters.
3823 Docx It will be rendered using OMML math markup.
3825 FictionBook2
3827 If the --webtex option is used, formulas are rendered as images
3828 using CodeCogs or other compatible web service, downloaded and
3829 embedded in the e-book. Otherwise, they will appear verbatim.
3830 HTML, Slidy, DZSlides, S5, EPUB
3832 The way math is rendered in HTML will depend on the command-line
3833 options selected. Therefore see Math rendering in HTML above.
3834 Raw HTML
3836 Extension: raw_html
3837 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
3838 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
3839 erally). (Technically this is not an extension, since standard Mark‐
3840 down allows it, but it has been made an extension so that it can be
3841 disabled if desired.)
3842 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
3844 DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile out‐
3845 put, and suppressed in other formats.
3846 For a more explicit way of including raw HTML in a Markdown document,
3848 see the raw_attribute extension.
3849 In the CommonMark format, if raw_html is enabled, superscripts, sub‐
3851 scripts, strikeouts and small capitals will be represented as HTML.
3852 Otherwise, plain-text fallbacks will be used. Note that even if
3853 raw_html is disabled, tables will be rendered with HTML syntax if they
3854 cannot use pipe syntax.
3855 Extension: markdown_in_html_blocks
3857 Standard Markdown allows you to include HTML "blocks": blocks of HTML
3858 between balanced tags that are separated from the surrounding text with
3859 blank lines, and start and end at the left margin. Within these
3860 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
3861 ple), * does not signify emphasis.
3862 Pandoc behaves this way when the markdown_strict format is used; but by
3864 default, pandoc interprets material between HTML block tags as Mark‐
3865 down. Thus, for example, pandoc will turn
3866 <table>
3868 <tr>
3869 <td>*one*</td>
3870 <td>[a link](https://google.com)</td>
3871 </tr>
3872 </table>
3873 into
3875 <table>
3877 <tr>
3878 <td><em>one</em></td>
3879 <td><a href="https://google.com">a link</a></td>
3880 </tr>
3881 </table>
3882 whereas Markdown.pl will preserve it as is.
3884 There is one exception to this rule: text between <script> and <style>
3886 tags is not interpreted as Markdown.
3887 This departure from standard Markdown should make it easier to mix
3889 Markdown with HTML block elements. For example, one can surround a
3890 block of Markdown text with <div> tags without preventing it from being
3891 interpreted as Markdown.
3892 Extension: native_divs
3894 Use native pandoc Div blocks for content inside <div> tags. For the
3895 most part this should give the same output as markdown_in_html_blocks,
3896 but it makes it easier to write pandoc filters to manipulate groups of
3897 blocks.
3898 Extension: native_spans
3900 Use native pandoc Span blocks for content inside <span> tags. For the
3901 most part this should give the same output as raw_html, but it makes it
3902 easier to write pandoc filters to manipulate groups of inlines.
3903 Extension: raw_tex
3905 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
3906 be included in a document. Inline TeX commands will be preserved and
3907 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
3908 you can use LaTeX to include BibTeX citations:
3909 This result was proved in \cite{jones.1967}.
3911 Note that in LaTeX environments, like
3913 \begin{tabular}{|l|l|}\hline
3915 Age & Frequency \\ \hline
3916 18--25 & 15 \\
3917 26--35 & 33 \\
3918 36--45 & 22 \\ \hline
3919 \end{tabular}
3920 the material between the begin and end tags will be interpreted as raw
3922 LaTeX, not as Markdown.
3923 For a more explicit and flexible way of including raw TeX in a Markdown
3925 document, see the raw_attribute extension.
3926 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
3928 Emacs Org mode, and ConTeXt.
3929 Generic raw attribute
3931 Extension: raw_attribute
3932 Inline spans and fenced code blocks with a special kind of attribute
3933 will be parsed as raw content with the designated format. For example,
3934 the following produces a raw roff ms block:
3935 ```{=ms}
3937 .MYMACRO
3938 blah blah
3939 ```
3940 And the following produces a raw html inline element:
3942 This is `<a>html</a>`{=html}
3944 This can be useful to insert raw xml into docx documents, e.g. a page‐
3946 break:
3947 ```{=openxml}
3949 <w:p>
3950 <w:r>
3951 <w:br w:type="page"/>
3952 </w:r>
3953 </w:p>
3954 ```
3955 The format name should match the target format name (see -t/--to,
3957 above, for a list, or use pandoc --list-output-formats). Use openxml
3958 for docx output, opendocument for odt output, html5 for epub3 output,
3959 html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output
3960 (depending on what you use for --pdf-engine).
3961 This extension presupposes that the relevant kind of inline code or
3963 fenced code block is enabled. Thus, for example, to use a raw at‐
3964 tribute with a backtick code block, backtick_code_blocks must be en‐
3965 abled.
3966 The raw attribute cannot be combined with regular attributes.
3968 LaTeX macros
3970 Extension: latex_macros
3971 When this extension is enabled, pandoc will parse LaTeX macro defini‐
3972 tions and apply the resulting macros to all LaTeX math and raw LaTeX.
3973 So, for example, the following will work in all output formats, not
3974 just LaTeX:
3975 \newcommand{\tuple}[1]{\langle #1 \rangle}
3977 $\tuple{a, b, c}$
3979 Note that LaTeX macros will not be applied if they occur inside a raw
3981 span or block marked with the raw_attribute extension.
3982 When latex_macros is disabled, the raw LaTeX and math will not have
3984 macros applied. This is usually a better approach when you are target‐
3985 ing LaTeX or PDF.
3986 Macro definitions in LaTeX will be passed through as raw LaTeX only if
3988 latex_macros is not enabled. Macro definitions in Markdown source (or
3989 other formats allowing raw_tex) will be passed through regardless of
3990 whether latex_macros is enabled.
3991 Links
3993 Markdown allows links to be specified in several ways.
3994 Automatic links
3996 If you enclose a URL or email address in pointy brackets, it will be‐
3997 come a link:
3998 <https://google.com>
4000 <sam@green.eggs.ham>
4001 Inline links
4003 An inline link consists of the link text in square brackets, followed
4004 by the URL in parentheses. (Optionally, the URL can be followed by a
4005 link title, in quotes.)
4006 This is an [inline link](/url), and here's [one with
4008 a title](https://fsf.org "click here for a good time!").
4009 There can be no space between the bracketed part and the parenthesized
4011 part. The link text can contain formatting (such as emphasis), but the
4012 title cannot.
4013 Email addresses in inline links are not autodetected, so they have to
4015 be prefixed with mailto:
4016 [Write me!](mailto:sam@green.eggs.ham)
4018 Reference links
4020 An explicit reference link has two parts, the link itself and the link
4021 definition, which may occur elsewhere in the document (either before or
4022 after the link).
4023 The link consists of link text in square brackets, followed by a label
4025 in square brackets. (There cannot be space between the two unless the
4026 spaced_reference_links extension is enabled.) The link definition con‐
4027 sists of the bracketed label, followed by a colon and a space, followed
4028 by the URL, and optionally (after a space) a link title either in
4029 quotes or in parentheses. The label must not be parseable as a cita‐
4030 tion (assuming the citations extension is enabled): citations take
4031 precedence over link labels.
4032 Here are some examples:
4034 [my label 1]: /foo/bar.html "My title, optional"
4036 [my label 2]: /foo
4037 [my label 3]: https://fsf.org (The free software foundation)
4038 [my label 4]: /bar#special 'A title in single quotes'
4039 The URL may optionally be surrounded by angle brackets:
4041 [my label 5]: <http://foo.bar.baz>
4043 The title may go on the next line:
4045 [my label 3]: https://fsf.org
4047 "The free software foundation"
4048 Note that link labels are not case sensitive. So, this will work:
4050 Here is [my link][FOO]
4052 [Foo]: /bar/baz
4054 In an implicit reference link, the second pair of brackets is empty:
4056 See [my website][].
4058 [my website]: http://foo.bar.baz
4060 Note: In Markdown.pl and most other Markdown implementations, reference
4062 link definitions cannot occur in nested constructions such as list
4063 items or block quotes. Pandoc lifts this arbitrary seeming restric‐
4064 tion. So the following is fine in pandoc, though not in most other im‐
4065 plementations:
4066 > My block [quote].
4068 >
4069 > [quote]: /foo
4070 Extension: shortcut_reference_links
4072 In a shortcut reference link, the second pair of brackets may be omit‐
4073 ted entirely:
4074 See [my website].
4076 [my website]: http://foo.bar.baz
4078 Internal links
4080 To link to another section of the same document, use the automatically
4081 generated identifier (see Heading identifiers). For example:
4082 See the [Introduction](#introduction).
4084 or
4086 See the [Introduction].
4088 [Introduction]: #introduction
4090 Internal links are currently supported for HTML formats (including HTML
4092 slide shows and EPUB), LaTeX, and ConTeXt.
4093 Images
4095 A link immediately preceded by a ! will be treated as an image. The
4096 link text will be used as the image's alt text:
4097 
4099 ![movie reel]
4101 [movie reel]: movie.gif
4103 Extension: implicit_figures
4105 An image with nonempty alt text, occurring by itself in a paragraph,
4106 will be rendered as a figure with a caption. The image's alt text will
4107 be used as the caption.
4108 
4110 How this is rendered depends on the output format. Some output formats
4112 (e.g. RTF) do not yet support figures. In those formats, you'll just
4113 get an image in a paragraph by itself, with no caption.
4114 If you just want a regular inline image, just make sure it is not the
4116 only thing in the paragraph. One way to do this is to insert a non‐
4117 breaking space after the image:
4118 \
4120 Note that in reveal.js slide shows, an image in a paragraph by itself
4122 that has the stretch class will fill the screen, and the caption and
4123 figure tags will be omitted.
4124 Extension: link_attributes
4126 Attributes can be set on links and images:
4127 An inline {#id .class width=30 height=20px}
4129 and a reference ![image][ref] with attributes.
4130 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
4132 (This syntax is compatible with PHP Markdown Extra when only #id and
4134 .class are used.)
4135 For HTML and EPUB, all known HTML5 attributes except width and height
4137 (but including srcset and sizes) are passed through as is. Unknown at‐
4138 tributes are passed through as custom attributes, with data- prepended.
4139 The other writers ignore attributes that are not specifically supported
4140 by their output format.
4141 The width and height attributes on images are treated specially. When
4143 used without a unit, the unit is assumed to be pixels. However, any of
4144 the following unit identifiers can be used: px, cm, mm, in, inch and %.
4145 There must not be any spaces between the number and the unit. For ex‐
4146 ample:
4147 { width=50% }
4149 · Dimensions are converted to inches for output in page-based formats
4151 like LaTeX. Dimensions are converted to pixels for output in HTML-
4152 like formats. Use the --dpi option to specify the number of pixels
4153 per inch. The default is 96dpi.
4154 · The % unit is generally relative to some available space. For exam‐
4156 ple the above example will render to the following.
4157 · HTML: <img href="file.jpg" style="width: 50%;" />
4159 · LaTeX: \includegraphics[width=0.5\textwidth,height=\tex‐
4161 theight]{file.jpg} (If you're using a custom template, you need to
4162 configure graphicx as in the default template.)
4163 · ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
4165 · Some output formats have a notion of a class (ConTeXt) or a unique
4167 identifier (LaTeX \caption), or both (HTML).
4168 · When no width or height attributes are specified, the fallback is to
4170 look at the image resolution and the dpi metadata embedded in the im‐
4171 age file.
4172 Divs and Spans
4174 Using the native_divs and native_spans extensions (see above), HTML
4175 syntax can be used as part of markdown to create native Div and Span
4176 elements in the pandoc AST (as opposed to raw HTML). However, there is
4177 also nicer syntax available:
4178 Extension: fenced_divs
4180 Allow special fenced syntax for native Div blocks. A Div starts with a
4181 fence containing at least three consecutive colons plus some at‐
4182 tributes. The attributes may optionally be followed by another string
4183 of consecutive colons. The attribute syntax is exactly as in fenced
4184 code blocks (see Extension: fenced_code_attributes). As with fenced
4185 code blocks, one can use either attributes in curly braces or a single
4186 unbraced word, which will be treated as a class name. The Div ends
4187 with another line containing a string of at least three consecutive
4188 colons. The fenced Div should be separated by blank lines from preced‐
4189 ing and following blocks.
4190 Example:
4192 ::::: {#special .sidebar}
4194 Here is a paragraph.
4195 And another.
4197 :::::
4198 Fenced divs can be nested. Opening fences are distinguished because
4200 they must have attributes:
4201 ::: Warning ::::::
4203 This is a warning.
4204 ::: Danger
4206 This is a warning within a warning.
4207 :::
4208 ::::::::::::::::::
4209 Fences without attributes are always closing fences. Unlike with
4211 fenced code blocks, the number of colons in the closing fence need not
4212 match the number in the opening fence. However, it can be helpful for
4213 visual clarity to use fences of different lengths to distinguish nested
4214 divs from their parents.
4215 Extension: bracketed_spans
4217 A bracketed sequence of inlines, as one would use to begin a link, will
4218 be treated as a Span with attributes if it is followed immediately by
4219 attributes:
4220 [This is *some text*]{.class key="val"}
4222 Footnotes
4224 Extension: footnotes
4225 Pandoc's Markdown allows footnotes, using the following syntax:
4226 Here is a footnote reference,[^1] and another.[^longnote]
4228 [^1]: Here is the footnote.
4230 [^longnote]: Here's one with multiple blocks.
4232 Subsequent paragraphs are indented to show that they
4234 belong to the previous footnote.
4235 { some.code }
4237 The whole paragraph can be indented, or just the first
4239 line. In this way, multi-paragraph footnotes work like
4240 multi-paragraph list items.
4241 This paragraph won't be part of the note, because it
4243 isn't indented.
4244 The identifiers in footnote references may not contain spaces, tabs, or
4246 newlines. These identifiers are used only to correlate the footnote
4247 reference with the note itself; in the output, footnotes will be num‐
4248 bered sequentially.
4249 The footnotes themselves need not be placed at the end of the document.
4251 They may appear anywhere except inside other block elements (lists,
4252 block quotes, tables, etc.). Each footnote should be separated from
4253 surrounding content (including other footnotes) by blank lines.
4254 Extension: inline_notes
4256 Inline footnotes are also allowed (though, unlike regular notes, they
4257 cannot contain multiple paragraphs). The syntax is as follows:
4258 Here is an inline note.^[Inlines notes are easier to write, since
4260 you don't have to pick an identifier and move down to type the
4261 note.]
4262 Inline and regular footnotes may be mixed freely.
4264 Citations
4266 Extension: citations
4267 Using an external filter, pandoc-citeproc, pandoc can automatically
4268 generate citations and a bibliography in a number of styles. Basic us‐
4269 age is
4270 pandoc --filter pandoc-citeproc myinput.txt
4272 In order to use this feature, you will need to specify a bibliography
4274 file using the bibliography metadata field in a YAML metadata section,
4275 or --bibliography command line argument. You can supply multiple
4276 --bibliography arguments or set bibliography metadata field to YAML ar‐
4277 ray, if you want to use multiple bibliography files. The bibliography
4278 may have any of these formats:
4279 Format File extension
4281 ─────────────────────────────
4282 BibLaTeX .bib
4283 BibTeX .bibtex
4284 Copac .copac
4285 CSL JSON .json
4286 CSL YAML .yaml
4287 EndNote .enl
4288 EndNote XML .xml
4289 ISI .wos
4290 MEDLINE .medline
4291 MODS .mods
4292 RIS .ris
4293 Note that .bib can be used with both BibTeX and BibLaTeX files; use
4295 .bibtex to force BibTeX.
4296 Note that pandoc-citeproc --bib2json and pandoc-citeproc --bib2yaml can
4298 produce .json and .yaml files from any of the supported formats.
4299 In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
4301 parses a subset of LaTeX markup; in CSL YAML databases, pandoc Mark‐
4302 down; and in CSL JSON databases, an HTML-like markup:
4303 <i>...</i>
4305 italics
4306 <b>...</b>
4308 bold
4309 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
4311 small capitals
4312 <sub>...</sub>
4314 subscript
4315 <sup>...</sup>
4317 superscript
4318 <span class="nocase">...</span>
4320 prevent a phrase from being capitalized as title case
4321 pandoc-citeproc -j and -y interconvert the CSL JSON and CSL YAML for‐
4323 mats as far as possible.
4324 As an alternative to specifying a bibliography file using --bibliogra‐
4326 phy or the YAML metadata field bibliography, you can include the cita‐
4327 tion data directly in the references field of the document's YAML meta‐
4328 data. The field should contain an array of YAML-encoded references,
4329 for example:
4330 ---
4332 references:
4333 - type: article-journal
4334 id: WatsonCrick1953
4335 author:
4336 - family: Watson
4337 given: J. D.
4338 - family: Crick
4339 given: F. H. C.
4340 issued:
4341 date-parts:
4342 - - 1953
4343 - 4
4344 - 25
4345 title: 'Molecular structure of nucleic acids: a structure for deoxyribose
4346 nucleic acid'
4347 title-short: Molecular structure of nucleic acids
4348 container-title: Nature
4349 volume: 171
4350 issue: 4356
4351 page: 737-738
4352 DOI: 10.1038/171737a0
4353 URL: https://www.nature.com/articles/171737a0
4354 language: en-GB
4355 ...
4356 (pandoc-citeproc --bib2yaml can produce these from a bibliography file
4358 in one of the supported formats.)
4359 Citations and references can be formatted using any style supported by
4361 the Citation Style Language, listed in the Zotero Style Repository.
4362 These files are specified using the --csl option or the csl metadata
4363 field. By default, pandoc-citeproc will use the Chicago Manual of
4364 Style author-date format. The CSL project provides further information
4365 on finding and editing styles.
4366 To make your citations hyperlinks to the corresponding bibliography en‐
4368 tries, add link-citations: true to your YAML metadata.
4369 Citations go inside square brackets and are separated by semicolons.
4371 Each citation must have a key, composed of '@' + the citation identifi‐
4372 er from the database, and may optionally have a prefix, a locator, and
4373 a suffix. The citation key must begin with a letter, digit, or _, and
4374 may contain alphanumerics, _, and internal punctuation characters
4375 (:.#$%&-+?<>~/). Here are some examples:
4376 Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
4378 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
4380 Blah blah [@smith04; @doe99].
4382 pandoc-citeproc detects locator terms in the CSL locale files. Either
4384 abbreviated or unabbreviated forms are accepted. In the en-US locale,
4385 locator terms can be written in either singular or plural forms, as
4386 book, bk./bks.; chapter, chap./chaps.; column, col./cols.; figure,
4387 fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note,
4388 n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part,
4389 pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.;
4390 volume, vol./vols.; ¶/¶¶; §/§§. If no locator term is used, "page" is
4391 assumed.
4392 pandoc-citeproc will use heuristics to distinguish the locator from the
4394 suffix. In complex cases, the locator can be enclosed in curly braces
4395 (using pandoc-citeproc 0.15 and higher only):
4396 [@smith{ii, A, D-Z}, with a suffix]
4398 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
4399 A minus sign (-) before the @ will suppress mention of the author in
4401 the citation. This can be useful when the author is already mentioned
4402 in the text:
4403 Smith says blah [-@smith04].
4405 You can also write an in-text citation, as follows:
4407 @smith04 says blah.
4409 @smith04 [p. 33] says blah.
4411 If the style calls for a list of works cited, it will be placed in a
4413 div with id refs, if one exists:
4414 ::: {#refs}
4416 :::
4417 Otherwise, it will be placed at the end of the document. Generation of
4419 the bibliography can be suppressed by setting suppress-bibliography:
4420 true in the YAML metadata.
4421 If you wish the bibliography to have a section heading, you can set
4423 reference-section-title in the metadata, or put the heading at the be‐
4424 ginning of the div with id refs (if you are using it) or at the end of
4425 your document:
4426 last paragraph...
4428 # References
4430 The bibliography will be inserted after this heading. Note that the
4432 unnumbered class will be added to this heading, so that the section
4433 will not be numbered.
4434 If you want to include items in the bibliography without actually cit‐
4436 ing them in the body text, you can define a dummy nocite metadata field
4437 and put the citations there:
4438 ---
4440 nocite: |
4441 @item1, @item2
4442 ...
4443 @item3
4445 In this example, the document will contain a citation for item3 only,
4447 but the bibliography will contain entries for item1, item2, and item3.
4448 It is possible to create a bibliography with all the citations, whether
4450 or not they appear in the document, by using a wildcard:
4451 ---
4453 nocite: |
4454 @*
4455 ...
4456 For LaTeX output, you can also use natbib or biblatex to render the
4458 bibliography. In order to do so, specify bibliography files as out‐
4459 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
4460 tion. Bear in mind that bibliography files have to be in respective
4461 format (either BibTeX or BibLaTeX).
4462 For more information, see the pandoc-citeproc man page.
4464 Non-pandoc extensions
4466 The following Markdown syntax extensions are not enabled by default in
4467 pandoc, but may be enabled by adding +EXTENSION to the format name,
4468 where EXTENSION is the name of the extension. Thus, for example, mark‐
4469 down+hard_line_breaks is Markdown with hard line breaks.
4470 Extension: old_dashes
4472 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - be‐
4473 fore a numeral is an en-dash, and -- is an em-dash. This option only
4474 has an effect if smart is enabled. It is selected automatically for
4475 textile input.
4476 Extension: angle_brackets_escapable
4478 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
4479 vored Markdown but not original Markdown. This is implied by pandoc's
4480 default all_symbols_escapable.
4481 Extension: lists_without_preceding_blankline
4483 Allow a list to occur right after a paragraph, with no intervening
4484 blank space.
4485 Extension: four_space_rule
4487 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
4488 ces indent are needed for list item continuation paragraphs.
4489 Extension: spaced_reference_links
4491 Allow whitespace between the two components of a reference link, for
4492 example,
4493 [foo] [bar].
4495 Extension: hard_line_breaks
4497 Causes all newlines within a paragraph to be interpreted as hard line
4498 breaks instead of spaces.
4499 Extension: ignore_line_breaks
4501 Causes newlines within a paragraph to be ignored, rather than being
4502 treated as spaces or as hard line breaks. This option is intended for
4503 use with East Asian languages where spaces are not used between words,
4504 but text is divided into lines for readability.
4505 Extension: east_asian_line_breaks
4507 Causes newlines within a paragraph to be ignored, rather than being
4508 treated as spaces or as hard line breaks, when they occur between two
4509 East Asian wide characters. This is a better choice than ig‐
4510 nore_line_breaks for texts that include a mix of East Asian wide char‐
4511 acters and other characters.
4512 Extension: emoji
4514 Parses textual emojis like :smile: as Unicode emoticons.
4515 Extension: tex_math_single_backslash
4517 Causes anything between \( and \) to be interpreted as inline TeX math,
4518 and anything between \[ and \] to be interpreted as display TeX math.
4519 Note: a drawback of this extension is that it precludes escaping ( and
4520 [.
4521 Extension: tex_math_double_backslash
4523 Causes anything between \\( and \\) to be interpreted as inline TeX
4524 math, and anything between \\[ and \\] to be interpreted as display TeX
4525 math.
4526 Extension: markdown_attribute
4528 By default, pandoc interprets material inside block-level tags as Mark‐
4529 down. This extension changes the behavior so that Markdown is only
4530 parsed inside block-level tags if the tags have the attribute mark‐
4531 down=1.
4532 Extension: mmd_title_block
4534 Enables a MultiMarkdown style title block at the top of the document,
4535 for example:
4536 Title: My title
4538 Author: John Doe
4539 Date: September 1, 2008
4540 Comment: This is a sample mmd title block, with
4541 a field spanning multiple lines.
4542 See the MultiMarkdown documentation for details. If pandoc_title_block
4544 or yaml_metadata_block is enabled, it will take precedence over mmd_ti‐
4545 tle_block.
4546 Extension: abbreviations
4548 Parses PHP Markdown Extra abbreviation keys, like
4549 *[HTML]: Hypertext Markup Language
4551 Note that the pandoc document model does not support abbreviations, so
4553 if this extension is enabled, abbreviation keys are simply skipped (as
4554 opposed to being parsed as paragraphs).
4555 Extension: autolink_bare_uris
4557 Makes all absolute URIs into links, even when not surrounded by pointy
4558 braces <...>.
4559 Extension: mmd_link_attributes
4561 Parses multimarkdown style key-value attributes on link and image ref‐
4562 erences. This extension should not be confused with the link_at‐
4563 tributes extension.
4564 This is a reference ![image][ref] with multimarkdown attributes.
4566 [ref]: https://path.to/image "Image title" width=20px height=30px
4568 id=myId class="myClass1 myClass2"
4569 Extension: mmd_header_identifiers
4571 Parses multimarkdown style heading identifiers (in square brackets, af‐
4572 ter the heading but before any trailing #s in an ATX heading).
4573 Extension: compact_definition_lists
4575 Activates the definition list syntax of pandoc 1.12.x and earlier.
4576 This syntax differs from the one described above under Definition lists
4577 in several respects:
4578 · No blank line is required between consecutive items of the definition
4580 list.
4581 · To get a "tight" or "compact" list, omit space between consecutive
4583 items; the space between a term and its definition does not affect
4584 anything.
4585 · Lazy wrapping of paragraphs is not allowed: the entire definition
4587 must be indented four spaces.
4588 Extension: gutenberg
4590 Use Project Gutenberg conventions for plain output: all-caps for strong
4591 emphasis, surround by underscores for regular emphasis, add extra blank
4592 space around headings.
4593 Markdown variants
4595 In addition to pandoc's extended Markdown, the following Markdown vari‐
4596 ants are supported:
4597 markdown_phpextra (PHP Markdown Extra)
4599 footnotes, pipe_tables, raw_html, markdown_attribute,
4600 fenced_code_blocks, definition_lists, intraword_underscores,
4601 header_attributes, link_attributes, abbreviations, shortcut_ref‐
4602 erence_links, spaced_reference_links.
4603 markdown_github (deprecated GitHub-Flavored Markdown)
4605 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
4606 gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris,
4607 space_in_atx_header, intraword_underscores, strikeout,
4608 task_lists, emoji, shortcut_reference_links, angle_brackets_es‐
4609 capable, lists_without_preceding_blankline.
4610 markdown_mmd (MultiMarkdown)
4612 pipe_tables, raw_html, markdown_attribute, mmd_link_attributes,
4613 tex_math_double_backslash, intraword_underscores, mmd_ti‐
4614 tle_block, footnotes, definition_lists, all_symbols_escapable,
4615 implicit_header_references, auto_identifiers, mmd_header_identi‐
4616 fiers, shortcut_reference_links, implicit_figures, superscript,
4617 subscript, backtick_code_blocks, spaced_reference_links, raw_at‐
4618 tribute.
4619 markdown_strict (Markdown.pl)
4621 raw_html, shortcut_reference_links, spaced_reference_links.
4622 We also support commonmark and gfm (GitHub-Flavored Markdown, which is
4624 implemented as a set of extensions on commonmark).
4625 Note, however, that commonmark and gfm have limited support for exten‐
4627 sions. Only those listed below (and smart, raw_tex, and
4628 hard_line_breaks) will work. The extensions can, however, all be indi‐
4629 vidually disabled. Also, raw_tex only affects gfm output, not input.
4630 gfm (GitHub-Flavored Markdown)
4632 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
4633 gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris,
4634 space_in_atx_header, intraword_underscores, strikeout,
4635 task_lists, emoji, shortcut_reference_links, angle_brackets_es‐
4636 capable, lists_without_preceding_blankline.
4637
4639 You can use pandoc to produce an HTML + JavaScript slide presentation
4640 that can be viewed via a web browser. There are five ways to do this,
4641 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
4642 duce a PDF slide show using LaTeX beamer, or slides shows in Microsoft
4643 PowerPoint format.
4644 Here's the Markdown source for a simple slide show, habits.txt:
4646 % Habits
4648 % John Doe
4649 % March 22, 2005
4650 # In the morning
4652 ## Getting up
4654 - Turn off alarm
4656 - Get out of bed
4657 ## Breakfast
4659 - Eat eggs
4661 - Drink coffee
4662 # In the evening
4664 ## Dinner
4666 - Eat spaghetti
4668 - Drink wine
4669 ------------------
4671 
4673 ## Going to sleep
4675 - Get in bed
4677 - Count sheep
4678 To produce an HTML/JavaScript slide show, simply type
4680 pandoc -t FORMAT -s habits.txt -o habits.html
4682 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
4684 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
4686 with the -s/--standalone option embeds a link to JavaScript and CSS
4687 files, which are assumed to be available at the relative path s5/de‐
4688 fault (for S5), slideous (for Slideous), reveal.js (for reveal.js), or
4689 at the Slidy website at w3.org (for Slidy). (These paths can be
4690 changed by setting the slidy-url, slideous-url, revealjs-url, or s5-url
4691 variables; see Variables for HTML slides, above.) For DZSlides, the
4692 (relatively short) JavaScript and CSS are included in the file by de‐
4693 fault.
4694 With all HTML slide formats, the --self-contained option can be used to
4696 produce a single file that contains all of the data necessary to dis‐
4697 play the slide show, including linked scripts, stylesheets, images, and
4698 videos.
4699 To produce a PDF slide show using beamer, type
4701 pandoc -t beamer habits.txt -o habits.pdf
4703 Note that a reveal.js slide show can also be converted to a PDF by
4705 printing it to a file from the browser.
4706 To produce a Powerpoint slide show, type
4708 pandoc habits.txt -o habits.pptx
4710 Structuring the slide show
4712 By default, the slide level is the highest heading level in the hierar‐
4713 chy that is followed immediately by content, and not another heading,
4714 somewhere in the document. In the example above, level-1 headings are
4715 always followed by level-2 headings, which are followed by content, so
4716 the slide level is 2. This default can be overridden using the
4717 --slide-level option.
4718 The document is carved up into slides according to the following rules:
4720 · A horizontal rule always starts a new slide.
4722 · A heading at the slide level always starts a new slide.
4724 · Headings below the slide level in the hierarchy create headings with‐
4726 in a slide.
4727 · Headings above the slide level in the hierarchy create "title
4729 slides," which just contain the section title and help to break the
4730 slide show into sections. Non-slide content under these headings
4731 will be included on the title slide (for HTML slide shows) or in a
4732 subsequent slide with the same title (for beamer).
4733 · A title page is constructed automatically from the document's title
4735 block, if present. (In the case of beamer, this can be disabled by
4736 commenting out some lines in the default template.)
4737 These rules are designed to support many different styles of slide
4739 show. If you don't care about structuring your slides into sections
4740 and subsections, you can just use level-1 headings for all each slide.
4741 (In that case, level-1 will be the slide level.) But you can also
4742 structure the slide show into sections, as in the example above.
4743 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
4745 layout will be produced, with level-1 headings building horizontally
4746 and level-2 headings building vertically. It is not recommended that
4747 you use deeper nesting of section levels with reveal.js.
4748 Incremental lists
4750 By default, these writers produce lists that display "all at once." If
4751 you want your lists to display incrementally (one item at a time), use
4752 the -i option. If you want a particular list to depart from the de‐
4753 fault, put it in a div block with class incremental or nonincremental.
4754 So, for example, using the fenced div syntax, the following would be
4755 incremental regardless of the document default:
4756 ::: incremental
4758 - Eat spaghetti
4760 - Drink wine
4761 :::
4763 or
4765 ::: nonincremental
4767 - Eat spaghetti
4769 - Drink wine
4770 :::
4772 While using incremental and nonincremental divs are the recommended
4774 method of setting incremental lists on a per-case basis, an older
4775 method is also supported: putting lists inside a blockquote will depart
4776 from the document default (that is, it will display incrementally with‐
4777 out the -i option and all at once with the -i option):
4778 > - Eat spaghetti
4780 > - Drink wine
4781 Both methods allow incremental and nonincremental lists to be mixed in
4783 a single document.
4784 Note: Neither the -i/--incremental option nor any of the methods de‐
4786 scribed here currently works for PowerPoint output.
4787 Inserting pauses
4789 You can add "pauses" within a slide by including a paragraph containing
4790 three dots, separated by spaces:
4791 # Slide with a pause
4793 content before the pause
4795 . . .
4797 content after the pause
4799 Note: this feature is not yet implemented for PowerPoint output.
4801 Styling the slides
4803 You can change the style of HTML slides by putting customized CSS files
4804 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
4805 $DATADIR/slideous (for Slideous), where $DATADIR is the user data di‐
4806 rectory (see --data-dir, above). The originals may be found in pan‐
4807 doc's system data directory (generally $CABALDIR/pandoc-VERSION/s5/de‐
4808 fault). Pandoc will look there for any files it does not find in the
4809 user data directory.
4810 For dzslides, the CSS is included in the HTML file itself, and may be
4812 modified there.
4813 All reveal.js configuration options can be set through variables. For
4815 example, themes can be used by setting the theme variable:
4816 -V theme=moon
4818 Or you can specify a custom stylesheet using the --css option.
4820 To style beamer slides, you can specify a theme, colortheme, fonttheme,
4822 innertheme, and outertheme, using the -V option:
4823 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
4825 Note that heading attributes will turn into slide attributes (on a
4827 <div> or <section>) in HTML slide formats, allowing you to style indi‐
4828 vidual slides. In beamer, the only heading attribute that affects
4829 slides is the allowframebreaks class, which sets the allowframebreaks
4830 option, causing multiple slides to be created if the content overfills
4831 the frame. This is recommended especially for bibliographies:
4832 # References {.allowframebreaks}
4834 Speaker notes
4836 Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
4837 You can add notes to your Markdown document thus:
4838 ::: notes
4840 This is my note.
4842 - It can contain Markdown
4844 - like this list
4845 :::
4847 To show the notes window in reveal.js, press s while viewing the pre‐
4849 sentation. Speaker notes in PowerPoint will be available, as usual, in
4850 handouts and presenter view.
4851 Notes are not yet supported for other slide formats, but the notes will
4853 not appear on the slides themselves.
4854 Columns
4856 To put material in side by side columns, you can use a native div con‐
4857 tainer with class columns, containing two or more div containers with
4858 class column and a width attribute:
4859 :::::::::::::: {.columns}
4861 ::: {.column width="40%"}
4862 contents...
4863 :::
4864 ::: {.column width="60%"}
4865 contents...
4866 :::
4867 ::::::::::::::
4868 Frame attributes in beamer
4870 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
4871 in beamer (for example, when using the minted environment). This can
4872 be forced by adding the fragile class to the heading introducing the
4873 slide:
4874 # Fragile slide {.fragile}
4876 All of the other frame attributes described in Section 8.1 of the Beam‐
4878 er User's Guide may also be used: allowdisplaybreaks, allowframebreaks,
4879 b, c, t, environment, label, plain, shrink, standout, noframenumbering.
4880 Background in reveal.js and beamer
4882 Background images can be added to self-contained reveal.js slideshows
4883 and to beamer slideshows.
4884 For the same image on every slide, use the configuration option back‐
4886 ground-image either in the YAML metadata block or as a command-line
4887 variable. (There are no other options in beamer and the rest of this
4888 section concerns reveal.js slideshows.)
4889 For reveal.js, you can instead use the reveal.js-native option paral‐
4891 laxBackgroundImage. You can also set parallaxBackgroundHorizontal and
4892 parallaxBackgroundVertical the same way and must also set parallaxBack‐
4893 groundSize to have your values take effect.
4894 To set an image for a particular reveal.js slide, add {data-background-
4896 image="/path/to/image"} to the first slide-level heading on the slide
4897 (which may even be empty).
4898 In reveal.js's overview mode, the parallaxBackgroundImage will show up
4900 only on the first slide.
4901 Other reveal.js background settings also work on individual slides, in‐
4903 cluding data-background-size, data-background-repeat, data-background-
4904 color, data-transition, and data-transition-speed.
4905 To add a background image to the automatically generated title slide,
4907 use the title-slide-attributes variable in the YAML metadata block. It
4908 must contain a map of attribute names and values.
4909 See the reveal.js documentation for more details.
4911 For example in reveal.js:
4913 ---
4915 title: My Slideshow
4916 parallaxBackgroundImage: /path/to/my/background_image.png
4917 title-slide-attributes:
4918 data-background-image: /path/to/title_image.png
4919 data-background-size: contain
4920 ---
4921 ## Slide One
4923 Slide 1 has background_image.png as its background.
4925 ## {data-background-image="/path/to/special_image.jpg"}
4927 Slide 2 has a special image for its background, even though the heading has no content.
4929
4931 EPUB Metadata
4932 EPUB metadata may be specified using the --epub-metadata option, but if
4933 the source document is Markdown, it is better to use a YAML metadata
4934 block. Here is an example:
4935 ---
4937 title:
4938 - type: main
4939 text: My Book
4940 - type: subtitle
4941 text: An investigation of metadata
4942 creator:
4943 - role: author
4944 text: John Smith
4945 - role: editor
4946 text: Sarah Jones
4947 identifier:
4948 - scheme: DOI
4949 text: doi:10.234234.234/33
4950 publisher: My Press
4951 rights: © 2007 John Smith, CC BY-NC
4952 ibooks:
4953 version: 1.3.4
4954 ...
4955 The following fields are recognized:
4957 identifier
4959 Either a string value or an object with fields text and scheme.
4960 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
4961 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
4962 ISMN-13, ISBN-A, JP, OLCC.
4963 title Either a string value, or an object with fields file-as and
4965 type, or a list of such objects. Valid values for type are
4966 main, subtitle, short, collection, edition, extended.
4967 creator
4969 Either a string value, or an object with fields role, file-as,
4970 and text, or a list of such objects. Valid values for role are
4971 MARC relators, but pandoc will attempt to translate the human-
4972 readable versions (like "author" and "editor") to the appropri‐
4973 ate marc relators.
4974 contributor
4976 Same format as creator.
4977 date A string value in YYYY-MM-DD format. (Only the year is neces‐
4979 sary.) Pandoc will attempt to convert other common date formats.
4980 lang (or legacy: language)
4982 A string value in BCP 47 format. Pandoc will default to the lo‐
4983 cal language if nothing is specified.
4984 subject
4986 A string value or a list of such values.
4987 description
4989 A string value.
4990 type A string value.
4992 format A string value.
4994 relation
4996 A string value.
4997 coverage
4999 A string value.
5000 rights A string value.
5002 cover-image
5004 A string value (path to cover image).
5005 css (or legacy: stylesheet)
5007 A string value (path to CSS stylesheet).
5008 page-progression-direction
5010 Either ltr or rtl. Specifies the page-progression-direction at‐
5011 tribute for the spine element.
5012 ibooks iBooks-specific metadata, with the following fields:
5014 · version: (string)
5016 · specified-fonts: true|false (default false)
5018 · ipad-orientation-lock: portrait-only|landscape-only
5020 · iphone-orientation-lock: portrait-only|landscape-only
5022 · binding: true|false (default true)
5024 · scroll-axis: vertical|horizontal|default
5026 The epub:type attribute
5028 For epub3 output, you can mark up the heading that corresponds to an
5029 EPUB chapter using the epub:type attribute. For example, to set the
5030 attribute to the value prologue, use this markdown:
5031 # My chapter {epub:type=prologue}
5033 Which will result in:
5035 <body epub:type="frontmatter">
5037 <section epub:type="prologue">
5038 <h1>My chapter</h1>
5039 Pandoc will output <body epub:type="bodymatter">, unless you use one of
5041 the following values, in which case either frontmatter or backmatter
5042 will be output.
5043 epub:type of first section epub:type of body
5045 ───────────────────────────────────────────────
5046 prologue frontmatter
5047 abstract frontmatter
5048 acknowledgments frontmatter
5049 copyright-page frontmatter
5050 dedication frontmatter
5051 credits frontmatter
5052 keywords frontmatter
5053 imprint frontmatter
5054 contributors frontmatter
5055 other-credits frontmatter
5056 errata frontmatter
5057 revision-history frontmatter
5058 titlepage frontmatter
5059 halftitlepage frontmatter
5060 seriespage frontmatter
5061 foreword frontmatter
5062 preface frontmatter
5063 seriespage frontmatter
5064 titlepage frontmatter
5065 appendix backmatter
5066 colophon backmatter
5067 bibliography backmatter
5068 index backmatter
5069 Linked media
5071 By default, pandoc will download media referenced from any <img>, <au‐
5072 dio>, <video> or <source> element present in the generated EPUB, and
5073 include it in the EPUB container, yielding a completely self-contained
5074 EPUB. If you want to link to external media resources instead, use raw
5075 HTML in your source and add data-external="1" to the tag with the src
5076 attribute. For example:
5077 <audio controls="1">
5079 <source src="https://example.com/music/toccata.mp3"
5080 data-external="1" type="audio/mpeg">
5081 </source>
5082 </audio>
5083
5085 When creating a Jupyter notebook, pandoc will try to infer the notebook
5086 structure. Code blocks with the class code will be taken as code
5087 cells, and intervening content will be taken as Markdown cells. At‐
5088 tachments will automatically be created for images in Markdown cells.
5089 Metadata will be taken from the jupyter metadata field. For example:
5090 ---
5092 title: My notebook
5093 jupyter:
5094 nbformat: 4
5095 nbformat_minor: 5
5096 kernelspec:
5097 display_name: Python 2
5098 language: python
5099 name: python2
5100 language_info:
5101 codemirror_mode:
5102 name: ipython
5103 version: 2
5104 file_extension: ".py"
5105 mimetype: "text/x-python"
5106 name: "python"
5107 nbconvert_exporter: "python"
5108 pygments_lexer: "ipython2"
5109 version: "2.7.15"
5110 ---
5111 # Lorem ipsum
5113 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5115 bibendum felis dictum sodales.
5116 ``` code
5118 print("hello")
5119 ```
5120 ## Pyout
5122 ``` code
5124 from IPython.display import HTML
5125 HTML("""
5126 <script>
5127 console.log("hello");
5128 </script>
5129 <b>HTML</b>
5130 """)
5131 ```
5132 ## Image
5134 This image  will be
5136 included as a cell attachment.
5137 If you want to add cell attributes, group cells differently, or add
5139 output to code cells, then you need to include divs to indicate the
5140 structure. You can use either fenced divs or native divs for this.
5141 Here is an example:
5142 :::::: {.cell .markdown}
5144 # Lorem
5145 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5147 bibendum felis dictum sodales.
5148 ::::::
5149 :::::: {.cell .code execution_count=1}
5151 ``` {.python}
5152 print("hello")
5153 ```
5154 ::: {.output .stream .stdout}
5156 ```
5157 hello
5158 ```
5159 :::
5160 ::::::
5161 :::::: {.cell .code execution_count=2}
5163 ``` {.python}
5164 from IPython.display import HTML
5165 HTML("""
5166 <script>
5167 console.log("hello");
5168 </script>
5169 <b>HTML</b>
5170 """)
5171 ```
5172 ::: {.output .execute_result execution_count=2}
5174 ```{=html}
5175 <script>
5176 console.log("hello");
5177 </script>
5178 <b>HTML</b>
5179 hello
5180 ```
5181 :::
5182 ::::::
5183 If you include raw HTML or TeX in an output cell, use the [raw at‐
5185 tribute][Extension: fenced_attribute], as shown in the last cell of the
5186 example above. Although pandoc can process "bare" raw HTML and TeX,
5187 the result is often interspersed raw elements and normal textual ele‐
5188 ments, and in an output cell pandoc expects a single, connected raw
5189 block. To avoid using raw HTML or TeX except when marked explicitly
5190 using raw attributes, we recommend specifying the extensions -raw_html-
5191 raw_tex+raw_attribute when translating between Markdown and ipynb note‐
5192 books.
5193 Note that options and extensions that affect reading and writing of
5195 Markdown will also affect Markdown cells in ipynb notebooks. For exam‐
5196 ple, --wrap=preserve will preserve soft line breaks in Markdown cells;
5197 --atx-headers will cause ATX-style headings to be used; and --preserve-
5198 tabs will prevent tabs from being turned to spaces.
5199
5201 Pandoc will automatically highlight syntax in fenced code blocks that
5202 are marked with a language name. The Haskell library skylighting is
5203 used for highlighting. Currently highlighting is supported only for
5204 HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language
5205 names that pandoc will recognize, type pandoc --list-highlight-lan‐
5206 guages.
5207 The color scheme can be selected using the --highlight-style option.
5209 The default color scheme is pygments, which imitates the default color
5210 scheme used by the Python library pygments (though pygments is not ac‐
5211 tually used to do the highlighting). To see a list of highlight
5212 styles, type pandoc --list-highlight-styles.
5213 If you are not satisfied with the predefined styles, you can use
5215 --print-highlight-style to generate a JSON .theme file which can be
5216 modified and used as the argument to --highlight-style. To get a JSON
5217 version of the pygments style, for example:
5218 pandoc --print-highlight-style pygments > my.theme
5220 Then edit my.theme and use it like this:
5222 pandoc --highlight-style my.theme
5224 If you are not satisfied with the built-in highlighting, or you want
5226 highlight a language that isn't supported, you can use the --syntax-
5227 definition option to load a KDE-style XML syntax definition file. Be‐
5228 fore writing your own, have a look at KDE's repository of syntax defi‐
5229 nitions.
5230 To disable highlighting, use the --no-highlight option.
5232
5234 Custom styles can be used in the docx and ICML formats.
5235 Output
5237 By default, pandoc's docx and ICML output applies a predefined set of
5238 styles for blocks such as paragraphs and block quotes, and uses largely
5239 default formatting (italics, bold) for inlines. This will work for
5240 most purposes, especially alongside a reference.docx file. However, if
5241 you need to apply your own styles to blocks, or match a preexisting set
5242 of styles, pandoc allows you to define custom styles for blocks and
5243 text using divs and spans, respectively.
5244 If you define a div or span with the attribute custom-style, pandoc
5246 will apply your specified style to the contained elements (with the ex‐
5247 ception of elements whose function depends on a style, like headings,
5248 code blocks, block quotes, or links). So, for example, using the
5249 bracketed_spans syntax,
5250 [Get out]{custom-style="Emphatically"}, he said.
5252 would produce a docx file with "Get out" styled with character style
5254 Emphatically. Similarly, using the fenced_divs syntax,
5255 Dickinson starts the poem simply:
5257 ::: {custom-style="Poetry"}
5259 | A Bird came down the Walk---
5260 | He did not know I saw---
5261 :::
5262 would style the two contained lines with the Poetry paragraph style.
5264 For docx output, styles will be defined in the output file as inherit‐
5266 ing from normal text, if the styles are not yet in your reference.docx.
5267 If they are already defined, pandoc will not alter the definition.
5268 This feature allows for greatest customization in conjunction with pan‐
5270 doc filters. If you want all paragraphs after block quotes to be in‐
5271 dented, you can write a filter to apply the styles necessary. If you
5272 want all italics to be transformed to the Emphasis character style
5273 (perhaps to change their color), you can write a filter which will
5274 transform all italicized inlines to inlines within an Emphasis custom-
5275 style span.
5276 For docx output, you don't need to enable any extensions for custom
5278 styles to work.
5279 Input
5281 The docx reader, by default, only reads those styles that it can con‐
5282 vert into pandoc elements, either by direct conversion or interpreting
5283 the derivation of the input document's styles.
5284 By enabling the styles extension in the docx reader (-f docx+styles),
5286 you can produce output that maintains the styles of the input document,
5287 using the custom-style class. Paragraph styles are interpreted as di‐
5288 vs, while character styles are interpreted as spans.
5289 For example, using the custom-style-reference.docx file in the test di‐
5291 rectory, we have the following different outputs:
5292 Without the +styles extension:
5294 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
5296 This is some text.
5297 This is text with an *emphasized* text style. And this is text with a
5299 **strengthened** text style.
5300 > Here is a styled paragraph that inherits from Block Text.
5302 And with the extension:
5304 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
5306 ::: {custom-style="First Paragraph"}
5308 This is some text.
5309 :::
5310 ::: {custom-style="Body Text"}
5312 This is text with an [emphasized]{custom-style="Emphatic"} text style.
5313 And this is text with a [strengthened]{custom-style="Strengthened"}
5314 text style.
5315 :::
5316 ::: {custom-style="My Block Style"}
5318 > Here is a styled paragraph that inherits from Block Text.
5319 :::
5320 With these custom styles, you can use your input document as a refer‐
5322 ence-doc while creating docx output (see below), and maintain the same
5323 styles in your input and output files.
5324
5326 Pandoc can be extended with custom writers written in Lua. (Pandoc in‐
5327 cludes a Lua interpreter, so Lua need not be installed separately.)
5328 To use a custom writer, simply specify the path to the Lua script in
5330 place of the output format. For example:
5331 pandoc -t data/sample.lua
5333 Creating a custom writer requires writing a Lua function for each pos‐
5335 sible element in a pandoc document. To get a documented example which
5336 you can modify according to your needs, do
5337 pandoc --print-default-data-file sample.lua
5339 Note that custom writers have no default template. If you want to use
5341 --standalone with a custom writer, you will need to specify a template
5342 manually using --template or add a new default template with the name
5343 default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your
5344 user data directory (see Templates).
5345
5347 If you use pandoc to convert user-contributed content in a web applica‐
5348 tion, here are some things to keep in mind:
5349 1. Although pandoc itself will not create or modify any files other
5351 than those you explicitly ask it create (with the exception of tem‐
5352 porary files used in producing PDFs), a filter or custom writer
5353 could in principle do anything on your file system. Please audit
5354 filters and custom writers very carefully before using them.
5355 2. If your application uses pandoc as a Haskell library (rather than
5357 shelling out to the executable), it is possible to use it in a mode
5358 that fully isolates pandoc from your file system, by running the
5359 pandoc operations in the PandocPure monad. See the document Using
5360 the pandoc API for more details.
5361 3. Pandoc's parsers can exhibit pathological performance on some corner
5363 cases. It is wise to put any pandoc operations under a timeout, to
5364 avoid DOS attacks that exploit these issues. If you are using the
5365 pandoc executable, you can add the command line options +RTS -M512M
5366 -RTS (for example) to limit the heap size to 512MB.
5367 4. The HTML generated by pandoc is not guaranteed to be safe. If
5369 raw_html is enabled for the Markdown input, users can inject arbi‐
5370 trary HTML. Even if raw_html is disabled, users can include danger‐
5371 ous content in attributes for headings, spans, and code blocks. To
5372 be safe, you should run all the generated HTML through an HTML sani‐
5373 tizer.
5374
5376 Copyright 2006--2020 John MacFarlane (jgm@berkeley.edu). Released un‐
5377 der the GPL, version 2 or greater. This software carries no warranty
5378 of any kind. (See COPYRIGHT for full copyright and warranty notices.)
5379 For a full list of contributors, see the file AUTHORS.md in the pandoc
5380 source code.
5381 The Pandoc source code and all documentation may be downloaded from
5383 <http://pandoc.org>.
5384pandoc 2.9.2.1 March 23, 2020 Pandoc User's Guide()