1PANDOC(1) General Commands Manual PANDOC(1)
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
34 expressive 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
39 model. While conversions from pandoc's Markdown to all formats aspire
40 to 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
87 extension is unknown, the output format will default to HTML. If no
88 input file is specified (so that input comes from stdin), or if the
89 input files' extensions are unknown, the input format will be assumed
90 to be 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).
111 Alternatively, pandoc can use ConTeXt, pdfroff, or any of the following
113 HTML/CSS-to-PDF-engines, to create a PDF: wkhtmltopdf, weasyprint or
114 prince. To do this, specify an output file with a .pdf extension, as
115 before, but add the --pdf-engine option or -t context, -t html, or -t
116 ms to the command line (-t html defaults to --pdf-engine=wkhtmltopdf).
117 PDF output can be controlled using variables for LaTeX (if LaTeX is
119 used) and variables for ConTeXt (if ConTeXt is used). When using an
120 HTML/CSS-to-PDF-engine, --css affects the output. If wkhtmltopdf is
121 used, then the variables margin-left, margin-right, margin-top, mar‐
122 gin-bottom, footer-html, header-html and papersize will affect the out‐
123 put.
124 To debug the PDF creation, it can be useful to look at the intermediate
126 representation: instead of -o test.pdf, use for example -s -o test.tex
127 to output the generated LaTeX. You can then test it with pdflatex
128 test.tex.
129 When using LaTeX, the following packages need to be available (they are
131 included with all recent versions of TeX Live): amsfonts, amsmath, lm,
132 unicode-math, ifxetex, ifluatex, listings (if the --listings option is
133 used), fancyvrb, longtable, booktabs, graphicx and grffile (if the doc‐
134 ument contains images), hyperref, xcolor (with colorlinks), ulem, geom‐
135 etry (with the geometry variable set), setspace (with linestretch), and
136 babel (with lang). The use of xelatex or lualatex as the LaTeX engine
137 requires fontspec. xelatex uses polyglossia (with lang), xecjk, and
138 bidi (with the dir variable set). If the mathspec variable is set,
139 xelatex will use mathspec instead of unicode-math. The upquote and
140 microtype packages are used if available, and csquotes will be used for
141 typography if \usepackage{csquotes} is present in the template or
142 included via /H/--include-in-header. The natbib, biblatex, bibtex, and
143 biber packages can optionally be used for citation rendering.
144 Reading from the Web
146 Instead of an input file, an absolute URI may be given. In this case
147 pandoc will fetch the content using HTTP:
148 pandoc -f html -t markdown http://www.fsf.org
150 It is possible to supply a custom User-Agent string or other header
152 when requesting a document from a URL:
153 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
155 http://www.fsf.org
156
158 General options
159 -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
160 Specify input format. FORMAT can be:
161 · commonmark (CommonMark Markdown)
163 · creole (Creole 1.0)
165 · docbook (DocBook)
167 · docx (Word docx)
169 · epub (EPUB)
171 · fb2 (FictionBook2 e-book)
173 · gfm (GitHub-Flavored Markdown), or the deprecated and less
175 accurate markdown_github; use markdown_github only if you need
176 extensions not supported in gfm.
177 · haddock (Haddock markup)
179 · html (HTML)
181 · jats (JATS XML)
183 · json (JSON version of native AST)
185 · latex (LaTeX)
187 · markdown (Pandoc's Markdown)
189 · markdown_mmd (MultiMarkdown)
191 · markdown_phpextra (PHP Markdown Extra)
193 · markdown_strict (original unextended Markdown)
195 · mediawiki (MediaWiki markup)
197 · man (roff man)
199 · muse (Muse)
201 · native (native Haskell)
203 · odt (ODT)
205 · opml (OPML)
207 · org (Emacs Org mode)
209 · rst (reStructuredText)
211 · t2t (txt2tags)
213 · textile (Textile)
215 · tikiwiki (TikiWiki markup)
217 · twiki (TWiki markup)
219 · vimwiki (Vimwiki)
221 Extensions can be individually enabled or disabled by appending
223 +EXTENSION or -EXTENSION to the format name. See Extensions
224 below, for a list of extensions and their names. See
225 --list-input-formats and --list-extensions, below.
226 -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
228 Specify output format. FORMAT can be:
229 · asciidoc (AsciiDoc)
231 · beamer (LaTeX beamer slide show)
233 · commonmark (CommonMark Markdown)
235 · context (ConTeXt)
237 · docbook or docbook4 (DocBook 4)
239 · docbook5 (DocBook 5)
241 · docx (Word docx)
243 · dokuwiki (DokuWiki markup)
245 · epub or epub3 (EPUB v3 book)
247 · epub2 (EPUB v2)
249 · fb2 (FictionBook2 e-book)
251 · gfm (GitHub-Flavored Markdown), or the deprecated and less
253 accurate markdown_github; use markdown_github only if you need
254 extensions not supported in gfm.
255 · haddock (Haddock markup)
257 · html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
259 · html4 (XHTML 1.0 Transitional)
261 · icml (InDesign ICML)
263 · jats (JATS XML)
265 · json (JSON version of native AST)
267 · latex (LaTeX)
269 · man (roff man)
271 · markdown (Pandoc's Markdown)
273 · markdown_mmd (MultiMarkdown)
275 · markdown_phpextra (PHP Markdown Extra)
277 · markdown_strict (original unextended Markdown)
279 · mediawiki (MediaWiki markup)
281 · ms (roff ms)
283 · muse (Muse),
285 · native (native Haskell),
287 · odt (OpenOffice text document)
289 · opml (OPML)
291 · opendocument (OpenDocument)
293 · org (Emacs Org mode)
295 · plain (plain text),
297 · pptx (PowerPoint slide show)
299 · rst (reStructuredText)
301 · rtf (Rich Text Format)
303 · texinfo (GNU Texinfo)
305 · textile (Textile)
307 · slideous (Slideous HTML and JavaScript slide show)
309 · slidy (Slidy HTML and JavaScript slide show)
311 · dzslides (DZSlides HTML5 + JavaScript slide show),
313 · revealjs (reveal.js HTML5 + JavaScript slide show)
315 · s5 (S5 HTML and JavaScript slide show)
317 · tei (TEI Simple)
319 · zimwiki (ZimWiki markup)
321 · the path of a custom lua writer, see Custom writers below
323 Note that odt, docx, and epub output will not be directed to
325 stdout unless forced with -o -.
326 Extensions can be individually enabled or disabled by appending
328 +EXTENSION or -EXTENSION to the format name. See Extensions
329 below, for a list of extensions and their names. See
330 --list-output-formats and --list-extensions, below.
331 -o FILE, --output=FILE
333 Write output to FILE instead of stdout. If FILE is -, output
334 will go to stdout, even if a non-textual format (docx, odt,
335 epub2, epub3) is specified.
336 --data-dir=DIRECTORY
338 Specify the user data directory to search for pandoc data files.
339 If this option is not specified, the default user data directory
340 will be used. This is, in UNIX:
341 $HOME/.pandoc
343 in Windows XP:
345 C:\Documents And Settings\USERNAME\Application Data\pandoc
347 and in Windows Vista or later:
349 C:\Users\USERNAME\AppData\Roaming\pandoc
351 You can find the default user data directory on your system by
353 looking at the output of pandoc --version. A reference.odt,
354 reference.docx, epub.css, templates, slidy, slideous, or s5
355 directory placed in this directory will override pandoc's normal
356 defaults.
357 --bash-completion
359 Generate a bash completion script. To enable bash completion
360 with pandoc, add this to your .bashrc:
361 eval "$(pandoc --bash-completion)"
363 --verbose
365 Give verbose debugging output. Currently this only has an
366 effect with PDF output.
367 --quiet
369 Suppress warning messages.
370 --fail-if-warnings
372 Exit with error status if there are any warnings.
373 --log=FILE
375 Write log messages in machine-readable JSON format to FILE. All
376 messages above DEBUG level will be written, regardless of ver‐
377 bosity settings (--verbose, --quiet).
378 --list-input-formats
380 List supported input formats, one per line.
381 --list-output-formats
383 List supported output formats, one per line.
384 --list-extensions[=FORMAT]
386 List supported extensions, one per line, preceded by a + or -
387 indicating whether it is enabled by default in FORMAT. If FOR‐
388 MAT is not specified, defaults for pandoc's Markdown are given.
389 --list-highlight-languages
391 List supported languages for syntax highlighting, one per line.
392 --list-highlight-styles
394 List supported styles for syntax highlighting, one per line.
395 See --highlight-style.
396 -v, --version
398 Print version.
399 -h, --help
401 Show usage message.
402 Reader options
404 --base-header-level=NUMBER
405 Specify the base level for headers (defaults to 1).
406 --strip-empty-paragraphs
408 Deprecated. Use the +empty_paragraphs extension instead. Ignore
409 paragraphs with no content. This option is useful for convert‐
410 ing word processing documents where users have used empty para‐
411 graphs to create inter-paragraph space.
412 --indented-code-classes=CLASSES
414 Specify classes to use for indented code blocks--for example,
415 perl,numberLines or haskell. Multiple classes may be separated
416 by spaces or commas.
417 --default-image-extension=EXTENSION
419 Specify a default extension to use when image paths/URLs have no
420 extension. This allows you to use the same source for formats
421 that require different kinds of images. Currently this option
422 only affects the Markdown and LaTeX readers.
423 --file-scope
425 Parse each file individually before combining for multifile doc‐
426 uments. This will allow footnotes in different files with the
427 same identifiers to work as expected. If this option is set,
428 footnotes and links will not work across files. Reading binary
429 files (docx, odt, epub) implies --file-scope.
430 -F PROGRAM, --filter=PROGRAM
432 Specify an executable to be used as a filter transforming the
433 pandoc AST after the input is parsed and before the output is
434 written. The executable should read JSON from stdin and write
435 JSON to stdout. The JSON must be formatted like pandoc's own
436 JSON input and output. The name of the output format will be
437 passed to the filter as the first argument. Hence,
438 pandoc --filter ./caps.py -t latex
440 is equivalent to
442 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
444 The latter form may be useful for debugging filters.
446 Filters may be written in any language. Text.Pandoc.JSON
448 exports toJSONFilter to facilitate writing filters in Haskell.
449 Those who would prefer to write filters in python can use the
450 module pandocfilters, installable from PyPI. There are also
451 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
452 In order of preference, pandoc will look for filters in
454 1. a specified full or relative path (executable or non-exe‐
456 cutable)
457 2. $DATADIR/filters (executable or non-executable) where
459 $DATADIR is the user data directory (see --data-dir, above).
460 3. $PATH (executable only)
462 Filters and lua-filters are applied in the order specified on
464 the command line.
465 --lua-filter=SCRIPT
467 Transform the document in a similar fashion as JSON filters (see
468 --filter), but use pandoc's build-in lua filtering system. The
469 given lua script is expected to return a list of lua filters
470 which will be applied in order. Each lua filter must contain
471 element-transforming functions indexed by the name of the AST
472 element on which the filter function should be applied.
473 The pandoc lua module provides helper functions for element cre‐
475 ation. It is always loaded into the script's lua environment.
476 The following is an example lua script for macro-expansion:
478 function expand_hello_world(inline)
480 if inline.c == '{{helloworld}}' then
481 return pandoc.Emph{ pandoc.Str "Hello, World" }
482 else
483 return inline
484 end
485 end
486 return {{Str = expand_hello_world}}
488 In order of preference, pandoc will look for lua filters in
490 1. a specified full or relative path (executable or non-exe‐
492 cutable)
493 2. $DATADIR/filters (executable or non-executable) where
495 $DATADIR is the user data directory (see --data-dir, above).
496 -M KEY[=VAL], --metadata=KEY[:VAL]
498 Set the metadata field KEY to the value VAL. A value specified
499 on the command line overrides a value specified in the document
500 using YAML metadata blocks. Values will be parsed as YAML bool‐
501 ean or string values. If no value is specified, the value will
502 be treated as Boolean true. Like --variable, --metadata causes
503 template variables to be set. But unlike --variable, --metadata
504 affects the metadata of the underlying document (which is acces‐
505 sible from filters and may be printed in some output formats)
506 and metadata values will be escaped when inserted into the tem‐
507 plate.
508 --metadata-file=FILE
510 Read metadata from the supplied YAML (or JSON) file. This
511 option can be used with every input format, but string scalars
512 in the YAML file will always be parsed as Markdown. Generally,
513 the input will be handled the same as in YAML metadata blocks.
514 Metadata values specified inside the document, or by using -M,
515 overwrite values specified with this option.
516 -p, --preserve-tabs
518 Preserve tabs instead of converting them to spaces (the
519 default). Note that this will only affect tabs in literal code
520 spans and code blocks; tabs in regular text will be treated as
521 spaces.
522 --tab-stop=NUMBER
524 Specify the number of spaces per tab (default is 4).
525 --track-changes=accept|reject|all
527 Specifies what to do with insertions, deletions, and comments
528 produced by the MS Word "Track Changes" feature. accept (the
529 default), inserts all insertions, and ignores all deletions.
530 reject inserts all deletions and ignores insertions. Both
531 accept and reject ignore comments. all puts in insertions,
532 deletions, and comments, wrapped in spans with insertion, dele‐
533 tion, comment-start, and comment-end classes, respectively. The
534 author and time of change is included. all is useful for
535 scripting: only accepting changes from a certain reviewer, say,
536 or before a certain date. If a paragraph is inserted or
537 deleted, track-changes=all produces a span with the class para‐
538 graph-insertion/paragraph-deletion before the affected paragraph
539 break. This option only affects the docx reader.
540 --extract-media=DIR
542 Extract images and other media contained in or linked from the
543 source document to the path DIR, creating it if necessary, and
544 adjust the images references in the document so they point to
545 the extracted files. If the source format is a binary container
546 (docx, epub, or odt), the media is extracted from the container
547 and the original filenames are used. Otherwise the media is
548 read from the file system or downloaded, and new filenames are
549 constructed based on SHA1 hashes of the contents.
550 --abbreviations=FILE
552 Specifies a custom abbreviations file, with abbreviations one to
553 a line. If this option is not specified, pandoc will read the
554 data file abbreviations from the user data directory or fall
555 back on a system default. To see the system default, use pandoc
556 --print-default-data-file=abbreviations. The only use pandoc
557 makes of this list is in the Markdown reader. Strings ending in
558 a period that are found in this list will be followed by a non‐
559 breaking space, so that the period will not produce sen‐
560 tence-ending space in formats like LaTeX.
561 General writer options
563 -s, --standalone
564 Produce output with an appropriate header and footer (e.g. a
565 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
566 option is set automatically for pdf, epub, epub3, fb2, docx, and
567 odt output. For native output, this option causes metadata to
568 be included; otherwise, metadata is suppressed.
569 --template=FILE|URL
571 Use the specified file as a custom template for the generated
572 document. Implies --standalone. See Templates, below, for a
573 description of template syntax. If no extension is specified,
574 an extension corresponding to the writer will be added, so that
575 --template=special looks for special.html for HTML output. If
576 the template is not found, pandoc will search for it in the tem‐
577 plates subdirectory of the user data directory (see --data-dir).
578 If this option is not used, a default template appropriate for
579 the output format will be used (see -D/--print-default-tem‐
580 plate).
581 -V KEY[=VAL], --variable=KEY[:VAL]
583 Set the template variable KEY to the value VAL when rendering
584 the document in standalone mode. This is generally only useful
585 when the --template option is used to specify a custom template,
586 since pandoc automatically sets the variables used in the
587 default templates. If no VAL is specified, the key will be
588 given the value true.
589 -D FORMAT, --print-default-template=FORMAT
591 Print the system default template for an output FORMAT. (See -t
592 for a list of possible FORMATs.) Templates in the user data
593 directory are ignored.
594 --print-default-data-file=FILE
596 Print a system default data file. Files in the user data direc‐
597 tory are ignored.
598 --eol=crlf|lf|native
600 Manually specify line endings: crlf (Windows), lf (mac‐
601 OS/Linux/UNIX), or native (line endings appropriate to the OS on
602 which pandoc is being run). The default is native.
603 --dpi=NUMBER
605 Specify the dpi (dots per inch) value for conversion from pixels
606 to inch/centimeters and vice versa. The default is 96dpi.
607 Technically, the correct term would be ppi (pixels per inch).
608 --wrap=auto|none|preserve
610 Determine how text is wrapped in the output (the source code,
611 not the rendered version). With auto (the default), pandoc will
612 attempt to wrap lines to the column width specified by --columns
613 (default 72). With none, pandoc will not wrap lines at all.
614 With preserve, pandoc will attempt to preserve the wrapping from
615 the source document (that is, where there are nonsemantic new‐
616 lines in the source, there will be nonsemantic newlines in the
617 output as well). Automatic wrapping does not currently work in
618 HTML output.
619 --columns=NUMBER
621 Specify length of lines in characters. This affects text wrap‐
622 ping in the generated source code (see --wrap). It also affects
623 calculation of column widths for plain text tables (see Tables
624 below).
625 --toc, --table-of-contents
627 Include an automatically generated table of contents (or, in the
628 case of latex, context, docx, odt, opendocument, rst, or ms, an
629 instruction to create one) in the output document. This option
630 has no effect unless -s/--standalone is used, and it has no
631 effect on man, docbook4, docbook5, or jats output.
632 --toc-depth=NUMBER
634 Specify the number of section levels to include in the table of
635 contents. The default is 3 (which means that level 1, 2, and 3
636 headers will be listed in the contents).
637 --strip-comments
639 Strip out HTML comments in the Markdown or Textile source,
640 rather than passing them on to Markdown, Textile or HTML output
641 as raw HTML. This does not apply to HTML comments inside raw
642 HTML blocks when the markdown_in_html_blocks extension is not
643 set.
644 --no-highlight
646 Disables syntax highlighting for code blocks and inlines, even
647 when a language attribute is given.
648 --highlight-style=STYLE|FILE
650 Specifies the coloring style to be used in highlighted source
651 code. Options are pygments (the default), kate, monochrome,
652 breezeDark, espresso, zenburn, haddock, and tango. For more
653 information on syntax highlighting in pandoc, see Syntax high‐
654 lighting, below. See also --list-highlight-styles.
655 Instead of a STYLE name, a JSON file with extension .theme may
657 be supplied. This will be parsed as a KDE syntax highlighting
658 theme and (if valid) used as the highlighting style.
659 To generate the JSON version of an existing style, use
661 --print-highlight-style.
662 --print-highlight-style=STYLE|FILE
664 Prints a JSON version of a highlighting style, which can be mod‐
665 ified, saved with a .theme extension, and used with --high‐
666 light-style.
667 --syntax-definition=FILE
669 Instructs pandoc to load a KDE XML syntax definition file, which
670 will be used for syntax highlighting of appropriately marked
671 code blocks. This can be used to add support for new languages
672 or to use altered syntax definitions for existing languages.
673 -H FILE, --include-in-header=FILE
675 Include contents of FILE, verbatim, at the end of the header.
676 This can be used, for example, to include special CSS or
677 JavaScript in HTML documents. This option can be used repeat‐
678 edly to include multiple files in the header. They will be
679 included in the order specified. Implies --standalone.
680 -B FILE, --include-before-body=FILE
682 Include contents of FILE, verbatim, at the beginning of the doc‐
683 ument body (e.g. after the <body> tag in HTML, or the
684 \begin{document} command in LaTeX). This can be used to include
685 navigation bars or banners in HTML documents. This option can
686 be used repeatedly to include multiple files. They will be
687 included in the order specified. Implies --standalone.
688 -A FILE, --include-after-body=FILE
690 Include contents of FILE, verbatim, at the end of the document
691 body (before the </body> tag in HTML, or the \end{document} com‐
692 mand in LaTeX). This option can be used repeatedly to include
693 multiple files. They will be included in the order specified.
694 Implies --standalone.
695 --resource-path=SEARCHPATH
697 List of paths to search for images and other resources. The
698 paths should be separated by : on Linux, UNIX, and macOS sys‐
699 tems, and by ; on Windows. If --resource-path is not specified,
700 the default resource path is the working directory. Note that,
701 if --resource-path is specified, the working directory must be
702 explicitly listed or it will not be searched. For example:
703 --resource-path=.:test will search the working directory and the
704 test subdirectory, in that order.
705 --resource-path only has an effect if (a) the output format
707 embeds images (for example, docx, pdf, or html with --self-con‐
708 tained) or (b) it is used together with --extract-media.
709 --request-header=NAME:VAL
711 Set the request header NAME to the value VAL when making HTTP
712 requests (for example, when a URL is given on the command line,
713 or when resources used in a document must be downloaded). If
714 you're behind a proxy, you also need to set the environment
715 variable http_proxy to http://....
716 Options affecting specific writers
718 --self-contained
719 Produce a standalone HTML file with no external dependencies,
720 using data: URIs to incorporate the contents of linked scripts,
721 stylesheets, images, and videos. Implies --standalone. The
722 resulting file should be "self-contained," in the sense that it
723 needs no external files and no net access to be displayed prop‐
724 erly by a browser. This option works only with HTML output for‐
725 mats, including html4, html5, html+lhs, html5+lhs, s5, slidy,
726 slideous, dzslides, and revealjs. Scripts, images, and
727 stylesheets at absolute URLs will be downloaded; those at rela‐
728 tive URLs will be sought relative to the working directory (if
729 the first source file is local) or relative to the base URL (if
730 the first source file is remote). Elements with the attribute
731 data-external="1" will be left alone; the documents they link to
732 will not be incorporated in the document. Limitation: resources
733 that are loaded dynamically through JavaScript cannot be incor‐
734 porated; as a result, --self-contained does not work with
735 --mathjax, and some advanced features (e.g. zoom or speaker
736 notes) may not work in an offline "self-contained" reveal.js
737 slide show.
738 --html-q-tags
740 Use <q> tags for quotes in HTML.
741 --ascii
743 Use only ASCII characters in output. Currently supported for
744 XML and HTML formats (which use entities instead of UTF-8 when
745 this option is selected), CommonMark, gfm, and Markdown (which
746 use entities), roff ms (which use hexadecimal escapes), and to a
747 limited degree LaTeX (which uses standard commands for accented
748 characters when possible). roff man output uses ASCII by
749 default.
750 --reference-links
752 Use reference-style links, rather than inline links, in writing
753 Markdown or reStructuredText. By default inline links are used.
754 The placement of link references is affected by the --refer‐
755 ence-location option.
756 --reference-location = block|section|document
758 Specify whether footnotes (and references, if reference-links is
759 set) are placed at the end of the current (top-level) block, the
760 current section, or the document. The default is document.
761 Currently only affects the markdown writer.
762 --atx-headers
764 Use ATX-style headers in Markdown output. The default is to use
765 setext-style headers for levels 1-2, and then ATX headers.
766 (Note: for gfm output, ATX headers are always used.)
767 --top-level-division=[default|section|chapter|part]
769 Treat top-level headers as the given division type in LaTeX,
770 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
771 chapter, then section; all headers are shifted such that the
772 top-level header becomes the specified type. The default behav‐
773 ior is to determine the best division type via heuristics:
774 unless other conditions apply, section is chosen. When the
775 LaTeX document class is set to report, book, or memoir (unless
776 the article option is specified), chapter is implied as the set‐
777 ting for this option. If beamer is the output format, specify‐
778 ing either chapter or part will cause top-level headers to
779 become \part{..}, while second-level headers remain as their
780 default type.
781 -N, --number-sections
783 Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
784 By default, sections are not numbered. Sections with class
785 unnumbered will never be numbered, even if --number-sections is
786 specified.
787 --number-offset=NUMBER[,NUMBER,...]
789 Offset for section headings in HTML output (ignored in other
790 output formats). The first number is added to the section num‐
791 ber for top-level headers, the second for second-level headers,
792 and so on. So, for example, if you want the first top-level
793 header in your document to be numbered "6", specify --num‐
794 ber-offset=5. If your document starts with a level-2 header
795 which you want to be numbered "1.5", specify --number-off‐
796 set=1,4. Offsets are 0 by default. Implies --number-sections.
797 --listings
799 Use the listings package for LaTeX code blocks. The package
800 does not support multi-byte encoding for source code. To handle
801 UTF-8 you would need to use a custom template. This issue is
802 fully documented here: Encoding issue with the listings package.
803 -i, --incremental
805 Make list items in slide shows display incrementally (one by
806 one). The default is for lists to be displayed all at once.
807 --slide-level=NUMBER
809 Specifies that headers with the specified level create slides
810 (for beamer, s5, slidy, slideous, dzslides). Headers above this
811 level in the hierarchy are used to divide the slide show into
812 sections; headers below this level create subheads within a
813 slide. Note that content that is not contained under
814 slide-level headers will not appear in the slide show. The
815 default is to set the slide level based on the contents of the
816 document; see Structuring the slide show.
817 --section-divs
819 Wrap sections in <section> tags (or <div> tags for html4), and
820 attach identifiers to the enclosing <section> (or <div>) rather
821 than the header itself. See Header identifiers, below.
822 --email-obfuscation=none|javascript|references
824 Specify a method for obfuscating mailto: links in HTML docu‐
825 ments. none leaves mailto: links as they are. javascript
826 obfuscates them using JavaScript. references obfuscates them by
827 printing their letters as decimal or hexadecimal character ref‐
828 erences. The default is none.
829 --id-prefix=STRING
831 Specify a prefix to be added to all identifiers and internal
832 links in HTML and DocBook output, and to footnote numbers in
833 Markdown and Haddock output. This is useful for preventing
834 duplicate identifiers when generating fragments to be included
835 in other pages.
836 -T STRING, --title-prefix=STRING
838 Specify STRING as a prefix at the beginning of the title that
839 appears in the HTML header (but not in the title as it appears
840 at the beginning of the HTML body). Implies --standalone.
841 -c URL, --css=URL
843 Link to a CSS style sheet. This option can be used repeatedly
844 to include multiple files. They will be included in the order
845 specified.
846 A stylesheet is required for generating EPUB. If none is pro‐
848 vided using this option (or the css or stylesheet metadata
849 fields), pandoc will look for a file epub.css in the user data
850 directory (see --data-dir). If it is not found there, sensible
851 defaults will be used.
852 --reference-doc=FILE
854 Use the specified file as a style reference in producing a docx
855 or ODT file.
856 Docx For best results, the reference docx should be a modified
858 version of a docx file produced using pandoc. The con‐
859 tents of the reference docx are ignored, but its
860 stylesheets and document properties (including margins,
861 page size, header, and footer) are used in the new docx.
862 If no reference docx is specified on the command line,
863 pandoc will look for a file reference.docx in the user
864 data directory (see --data-dir). If this is not found
865 either, sensible defaults will be used.
866 To produce a custom reference.docx, first get a copy of
868 the default reference.docx: pandoc
869 --print-default-data-file reference.docx > custom-refer‐
870 ence.docx. Then open custom-reference.docx in Word, mod‐
871 ify the styles as you wish, and save the file. For best
872 results, do not make changes to this file other than mod‐
873 ifying the styles used by pandoc: [paragraph] Normal,
874 Body Text, First Paragraph, Compact, Title, Subtitle,
875 Author, Date, Abstract, Bibliography, Heading 1, Heading
876 2, Heading 3, Heading 4, Heading 5, Heading 6, Heading 7,
877 Heading 8, Heading 9, Block Text, Footnote Text, Defini‐
878 tion Term, Definition, Caption, Table Caption, Image Cap‐
879 tion, Figure, Captioned Figure, TOC Heading; [character]
880 Default Paragraph Font, Body Text Char, Verbatim Char,
881 Footnote Reference, Hyperlink; [table] Table.
882 ODT For best results, the reference ODT should be a modified
884 version of an ODT produced using pandoc. The contents of
885 the reference ODT are ignored, but its stylesheets are
886 used in the new ODT. If no reference ODT is specified on
887 the command line, pandoc will look for a file refer‐
888 ence.odt in the user data directory (see --data-dir). If
889 this is not found either, sensible defaults will be used.
890 To produce a custom reference.odt, first get a copy of
892 the default reference.odt: pandoc
893 --print-default-data-file reference.odt > custom-refer‐
894 ence.odt. Then open custom-reference.odt in LibreOffice,
895 modify the styles as you wish, and save the file.
896 PowerPoint
898 Any template included with a recent install of Microsoft
899 PowerPoint (either with .pptx or .potx extension) should
900 work, as will most templates derived from these.
901 The specific requirement is that the template should con‐
903 tain the following four layouts as its first four lay‐
904 outs:
905 1. Title Slide
907 2. Title and Content
909 3. Section Header
911 4. Two Content
913 All templates included with a recent version of MS Power‐
915 Point will fit these criteria. (You can click on Layout
916 under the Home menu to check.)
917 You can also modify the default reference.pptx: first run
919 pandoc --print-default-data-file reference.pptx > cus‐
920 tom-reference.pptx, and then modify custom-reference.pptx
921 in MS PowerPoint (pandoc will use the first four layout
922 slides, as mentioned above).
923 --epub-cover-image=FILE
925 Use the specified image as the EPUB cover. It is recommended
926 that the image be less than 1000px in width and height. Note
927 that in a Markdown source document you can also specify
928 cover-image in a YAML metadata block (see EPUB Metadata, below).
929 --epub-metadata=FILE
931 Look in the specified XML file for metadata for the EPUB. The
932 file should contain a series of Dublin Core elements. For exam‐
933 ple:
934 <dc:rights>Creative Commons</dc:rights>
936 <dc:language>es-AR</dc:language>
937 By default, pandoc will include the following metadata elements:
939 <dc:title> (from the document title), <dc:creator> (from the
940 document authors), <dc:date> (from the document date, which
941 should be in ISO 8601 format), <dc:language> (from the lang
942 variable, or, if is not set, the locale), and <dc:identifier
943 id="BookId"> (a randomly generated UUID). Any of these may be
944 overridden by elements in the metadata file.
945 Note: if the source document is Markdown, a YAML metadata block
947 in the document can be used instead. See below under EPUB Meta‐
948 data.
949 --epub-embed-font=FILE
951 Embed the specified font in the EPUB. This option can be
952 repeated to embed multiple fonts. Wildcards can also be used:
953 for example, DejaVuSans-*.ttf. However, if you use wildcards on
954 the command line, be sure to escape them or put the whole file‐
955 name in single quotes, to prevent them from being interpreted by
956 the shell. To use the embedded fonts, you will need to add dec‐
957 larations like the following to your CSS (see --css):
958 @font-face {
960 font-family: DejaVuSans;
961 font-style: normal;
962 font-weight: normal;
963 src:url("DejaVuSans-Regular.ttf");
964 }
965 @font-face {
966 font-family: DejaVuSans;
967 font-style: normal;
968 font-weight: bold;
969 src:url("DejaVuSans-Bold.ttf");
970 }
971 @font-face {
972 font-family: DejaVuSans;
973 font-style: italic;
974 font-weight: normal;
975 src:url("DejaVuSans-Oblique.ttf");
976 }
977 @font-face {
978 font-family: DejaVuSans;
979 font-style: italic;
980 font-weight: bold;
981 src:url("DejaVuSans-BoldOblique.ttf");
982 }
983 body { font-family: "DejaVuSans"; }
984 --epub-chapter-level=NUMBER
986 Specify the header level at which to split the EPUB into sepa‐
987 rate "chapter" files. The default is to split into chapters at
988 level 1 headers. This option only affects the internal composi‐
989 tion of the EPUB, not the way chapters and sections are dis‐
990 played to users. Some readers may be slow if the chapter files
991 are too large, so for large documents with few level 1 headers,
992 one might want to use a chapter level of 2 or 3.
993 --epub-subdirectory=DIRNAME
995 Specify the subdirectory in the OCF container that is to hold
996 the EPUB-specific contents. The default is EPUB. To put the
997 EPUB contents in the top level, use an empty string.
998 --pdf-engine=pdflatex|lualatex|xelatex|wkhtml‐
1000 topdf|weasyprint|prince|context|pdfroff
1001 Use the specified engine when producing PDF output. The default
1002 is pdflatex. If the engine is not in your PATH, the full path
1003 of the engine may be specified here.
1004 --pdf-engine-opt=STRING
1006 Use the given string as a command-line argument to the
1007 pdf-engine. If used multiple times, the arguments are provided
1008 with spaces between them. Note that no check for duplicate
1009 options is done.
1010 Citation rendering
1012 --bibliography=FILE
1013 Set the bibliography field in the document's metadata to FILE,
1014 overriding any value set in the metadata, and process citations
1015 using pandoc-citeproc. (This is equivalent to --metadata bibli‐
1016 ography=FILE --filter pandoc-citeproc.) If --natbib or --bibla‐
1017 tex is also supplied, pandoc-citeproc is not used, making this
1018 equivalent to --metadata bibliography=FILE. If you supply this
1019 argument multiple times, each FILE will be added to bibliogra‐
1020 phy.
1021 --csl=FILE
1023 Set the csl field in the document's metadata to FILE, overriding
1024 any value set in the metadata. (This is equivalent to --meta‐
1025 data csl=FILE.) This option is only relevant with pan‐
1026 doc-citeproc.
1027 --citation-abbreviations=FILE
1029 Set the citation-abbreviations field in the document's metadata
1030 to FILE, overriding any value set in the metadata. (This is
1031 equivalent to --metadata citation-abbreviations=FILE.) This
1032 option is only relevant with pandoc-citeproc.
1033 --natbib
1035 Use natbib for citations in LaTeX output. This option is not
1036 for use with the pandoc-citeproc filter or with PDF output. It
1037 is intended for use in producing a LaTeX file that can be pro‐
1038 cessed with bibtex.
1039 --biblatex
1041 Use biblatex for citations in LaTeX output. This option is not
1042 for use with the pandoc-citeproc filter or with PDF output. It
1043 is intended for use in producing a LaTeX file that can be pro‐
1044 cessed with bibtex or biber.
1045 Math rendering in HTML
1047 The default is to render TeX math as far as possible using Unicode
1048 characters. Formulas are put inside a span with class="math", so that
1049 they may be styled differently from the surrounding text if needed.
1050 However, this gives acceptable results only for basic math, usually you
1051 will want to use --mathjax or another of the following options.
1052 --mathjax[=URL]
1054 Use MathJax to display embedded TeX math in HTML output. TeX
1055 math will be put between \(...\) (for inline math) or \[...\]
1056 (for display math) and wrapped in <span> tags with class math.
1057 Then the MathJax JavaScript will render it. The URL should
1058 point to the MathJax.js load script. If a URL is not provided,
1059 a link to the Cloudflare CDN will be inserted.
1060 --mathml
1062 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
1063 html4 and html5). This is the default in odt output. Note that
1064 currently only Firefox and Safari (and select e-book readers)
1065 natively support MathML.
1066 --webtex[=URL]
1068 Convert TeX formulas to <img> tags that link to an external
1069 script that converts formulas to images. The formula will be
1070 URL-encoded and concatenated with the URL provided. For SVG
1071 images you can for example use --webtex
1072 https://latex.codecogs.com/svg.latex?. If no URL is specified,
1073 the CodeCogs URL generating PNGs will be used
1074 (https://latex.codecogs.com/png.latex?). Note: the --webtex
1075 option will affect Markdown output as well as HTML, which is
1076 useful if you're targeting a version of Markdown without native
1077 math support.
1078 --katex[=URL]
1080 Use KaTeX to display embedded TeX math in HTML output. The URL
1081 is the base URL for the KaTeX library. That directory should
1082 contain a katex.min.js and a katex.min.css file. If a URL is
1083 not provided, a link to the KaTeX CDN will be inserted.
1084 --gladtex
1086 Enclose TeX math in <eq> tags in HTML output. The resulting
1087 HTML can then be processed by GladTeX to produce images of the
1088 typeset formulas and an HTML file with links to these images.
1089 So, the procedure is:
1090 pandoc -s --gladtex input.md -o myfile.htex
1092 gladtex -d myfile-images myfile.htex
1093 # produces myfile.html and images in myfile-images
1094 Options for wrapper scripts
1096 --dump-args
1097 Print information about command-line arguments to stdout, then
1098 exit. This option is intended primarily for use in wrapper
1099 scripts. The first line of output contains the name of the out‐
1100 put file specified with the -o option, or - (for stdout) if no
1101 output file was specified. The remaining lines contain the com‐
1102 mand-line arguments, one per line, in the order they appear.
1103 These do not include regular pandoc options and their arguments,
1104 but do include any options appearing after a -- separator at the
1105 end of the line.
1106 --ignore-args
1108 Ignore command-line arguments (for use in wrapper scripts).
1109 Regular pandoc options are not ignored. Thus, for example,
1110 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1112 is equivalent to
1114 pandoc -o foo.html -s
1116
1118 When the -s/--standalone option is used, pandoc uses a template to add
1119 header and footer material that is needed for a self-standing document.
1120 To see the default template that is used, just type
1121 pandoc -D *FORMAT*
1123 where FORMAT is the name of the output format. A custom template can
1125 be specified using the --template option. You can also override the
1126 system default templates for a given output format FORMAT by putting a
1127 file templates/default.*FORMAT* in the user data directory (see
1128 --data-dir, above). Exceptions:
1129 · For odt output, customize the default.opendocument template.
1131 · For pdf output, customize the default.latex template (or the
1133 default.context template, if you use -t context, or the default.ms
1134 template, if you use -t ms, or the default.html template, if you use
1135 -t html).
1136 · docx has no template (however, you can use --reference-doc to custom‐
1138 ize the output).
1139 Templates contain variables, which allow for the inclusion of arbitrary
1141 information at any point in the file. They may be set at the command
1142 line using the -V/--variable option. If a variable is not set, pandoc
1143 will look for the key in the document's metadata – which can be set
1144 using either YAML metadata blocks or with the --metadata option.
1145 Variables set by pandoc
1147 Some variables are set automatically by pandoc. These vary somewhat
1148 depending on the output format, but include the following:
1149 sourcefile, outputfile
1151 source and destination filenames, as given on the command line.
1152 sourcefile can also be a list if input comes from multiple
1153 files, or empty if input is from stdin. You can use the follow‐
1154 ing snippet in your template to distinguish them:
1155 $if(sourcefile)$
1157 $for(sourcefile)$
1158 $sourcefile$
1159 $endfor$
1160 $else$
1161 (stdin)
1162 $endif$
1163 Similarly, outputfile can be - if output goes to the terminal.
1165 title, author, date
1167 allow identification of basic aspects of the document. Included
1168 in PDF metadata through LaTeX and ConTeXt. These can be set
1169 through a pandoc title block, which allows for multiple authors,
1170 or through a YAML metadata block:
1171 ---
1173 author:
1174 - Aristotle
1175 - Peter Abelard
1176 ...
1177 subtitle
1179 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
1180 Word docx; renders in LaTeX only when using a document class
1181 that supports \subtitle, such as beamer or the KOMA-Script
1182 series (scrartcl, scrreprt, scrbook).
1183 institute
1185 author affiliations (in LaTeX and Beamer only). Can be a list,
1186 when there are multiple authors.
1187 abstract
1189 document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word
1190 docx
1191 keywords
1193 list of keywords to be included in HTML, PDF, and AsciiDoc meta‐
1194 data; may be repeated as for author, above
1195 header-includes
1197 contents specified by -H/--include-in-header (may have multiple
1198 values)
1199 toc non-null value if --toc/--table-of-contents was specified
1201 toc-title
1203 title of table of contents (works only with EPUB, opendocument,
1204 odt, docx, pptx, beamer, LaTeX)
1205 include-before
1207 contents specified by -B/--include-before-body (may have multi‐
1208 ple values)
1209 include-after
1211 contents specified by -A/--include-after-body (may have multiple
1212 values)
1213 body body of document
1215 meta-json
1217 JSON representation of all of the document's metadata. Field
1218 values are transformed to the selected output format.
1219 Language variables
1221 lang identifies the main language of the document, using a code
1222 according to BCP 47 (e.g. en or en-GB). For some output for‐
1223 mats, pandoc will convert it to an appropriate format stored in
1224 the additional variables babel-lang, polyglossia-lang (LaTeX)
1225 and context-lang (ConTeXt).
1226 Native pandoc Spans and Divs with the lang attribute (value in
1228 BCP 47) can be used to switch the language in that range. In
1229 LaTeX output, babel-otherlangs and polyglossia-otherlangs vari‐
1230 ables will be generated automatically based on the lang
1231 attributes of Spans and Divs in the document.
1232 dir the base direction of the document, either rtl (right-to-left)
1234 or ltr (left-to-right).
1235 For bidirectional documents, native pandoc spans and divs with
1237 the dir attribute (value rtl or ltr) can be used to override the
1238 base direction in some output formats. This may not always be
1239 necessary if the final renderer (e.g. the browser, when gener‐
1240 ating HTML) supports the Unicode Bidirectional Algorithm.
1241 When using LaTeX for bidirectional documents, only the xelatex
1243 engine is fully supported (use --pdf-engine=xelatex).
1244 Variables for slides
1246 Variables are available for producing slide shows with pandoc, includ‐
1247 ing all reveal.js configuration options.
1248 titlegraphic
1250 title graphic for Beamer documents
1251 logo logo for Beamer documents
1253 slidy-url
1255 base URL for Slidy documents (defaults to
1256 https://www.w3.org/Talks/Tools/Slidy2)
1257 slideous-url
1259 base URL for Slideous documents (defaults to slideous)
1260 s5-url base URL for S5 documents (defaults to s5/default)
1262 revealjs-url
1264 base URL for reveal.js documents (defaults to reveal.js)
1265 theme, colortheme, fonttheme, innertheme, outertheme
1267 themes for LaTeX beamer documents
1268 themeoptions
1270 options for LaTeX beamer themes (a list).
1271 navigation
1273 controls navigation symbols in beamer documents (default is
1274 empty for no navigation symbols; other valid values are frame,
1275 vertical, and horizontal).
1276 section-titles
1278 enables on "title pages" for new sections in beamer documents
1279 (default = true).
1280 beamerarticle
1282 when true, the beamerarticle package is loaded (for producing an
1283 article from beamer slides).
1284 aspectratio
1286 aspect ratio of slides (for beamer only, 1610 for 16:10, 169 for
1287 16:9, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 43 for 4:3 which
1288 is the default, and 32 for 3:2).
1289 Variables for LaTeX
1291 LaTeX variables are used when creating a PDF.
1292 papersize
1294 paper size, e.g. letter, a4
1295 fontsize
1297 font size for body text (e.g. 10pt, 12pt)
1298 documentclass
1300 document class, e.g. article, report, book, memoir
1301 classoption
1303 option for document class, e.g. oneside; may be repeated for
1304 multiple options
1305 beameroption
1307 In beamer, add extra beamer option with \setbeameroption{}
1308 geometry
1310 option for geometry package, e.g. margin=1in; may be repeated
1311 for multiple options
1312 margin-left, margin-right, margin-top, margin-bottom
1314 sets margins, if geometry is not used (otherwise geometry over‐
1315 rides these)
1316 linestretch
1318 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
1319 fontfamily
1321 font package for use with pdflatex: TeX Live includes many
1322 options, documented in the LaTeX Font Catalogue. The default is
1323 Latin Modern.
1324 fontfamilyoptions
1326 options for package used as fontfamily: e.g. osf,sc with font‐
1327 family set to mathpazo provides Palatino with old-style figures
1328 and true small caps; may be repeated for multiple options
1329 mainfont, romanfont, sansfont, monofont, mathfont, CJKmainfont
1331 font families for use with xelatex or lualatex: take the name of
1332 any system font, using the fontspec package. Note that if CJK‐
1333 mainfont is used, the xecjk package must be available.
1334 mainfontoptions, romanfontoptions, sansfontoptions, monofontoptions,
1336 mathfontoptions, CJKoptions
1337 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
1338 mainfont in xelatex and lualatex. Allow for any choices avail‐
1339 able through fontspec, such as the OpenType features Num‐
1340 bers=OldStyle,Numbers=Proportional. May be repeated for multi‐
1341 ple options.
1342 fontenc
1344 allows font encoding to be specified through fontenc package
1345 (with pdflatex); default is T1 (see guide to LaTeX font encod‐
1346 ings)
1347 microtypeoptions
1349 options to pass to the microtype package
1350 colorlinks
1352 add color to link text; automatically enabled if any of link‐
1353 color, filecolor, citecolor, urlcolor, or toccolor are set
1354 linkcolor, filecolor, citecolor, urlcolor, toccolor
1356 color for internal links, external links, citation links, linked
1357 URLs, and links in table of contents, respectively: uses options
1358 allowed by xcolor, including the dvipsnames, svgnames, and
1359 x11names lists
1360 links-as-notes
1362 causes links to be printed as footnotes
1363 indent uses document class settings for indentation (the default LaTeX
1365 template otherwise removes indentation and adds space between
1366 paragraphs)
1367 subparagraph
1369 disables default behavior of LaTeX template that redefines
1370 (sub)paragraphs as sections, changing the appearance of nested
1371 headings in some classes
1372 thanks specifies contents of acknowledgments footnote after document
1374 title.
1375 toc include table of contents (can also be set using --toc/--ta‐
1377 ble-of-contents)
1378 toc-depth
1380 level of section to include in table of contents
1381 secnumdepth
1383 numbering depth for sections, if sections are numbered
1384 lof, lot
1386 include list of figures, list of tables
1387 bibliography
1389 bibliography to use for resolving references
1390 biblio-style
1392 bibliography style, when used with --natbib and --biblatex.
1393 biblio-title
1395 bibliography title, when used with --natbib and --biblatex.
1396 biblatexoptions
1398 list of options for biblatex.
1399 natbiboptions
1401 list of options for natbib.
1402 pagestyle
1404 An option for LaTeX's \pagestyle{}. The default article class
1405 supports 'plain' (default), 'empty', and 'headings'; headings
1406 puts section titles in the header.
1407 Variables for ConTeXt
1409 papersize
1410 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
1411 up); may be repeated for multiple options
1412 layout options for page margins and text arrangement (see ConTeXt Lay‐
1414 out); may be repeated for multiple options
1415 margin-left, margin-right, margin-top, margin-bottom
1417 sets margins, if layout is not used (otherwise layout overrides
1418 these)
1419 fontsize
1421 font size for body text (e.g. 10pt, 12pt)
1422 mainfont, sansfont, monofont, mathfont
1424 font families: take the name of any system font (see ConTeXt
1425 Font Switching)
1426 linkcolor, contrastcolor
1428 color for links outside and inside a page, e.g. red, blue (see
1429 ConTeXt Color)
1430 linkstyle
1432 typeface style for links, e.g. normal, bold, slanted, bold‐
1433 slanted, type, cap, small
1434 indenting
1436 controls indentation of paragraphs, e.g. yes,small,next (see
1437 ConTeXt Indentation); may be repeated for multiple options
1438 whitespace
1440 spacing between paragraphs, e.g. none, small (using setup‐
1441 whitespace)
1442 interlinespace
1444 adjusts line spacing, e.g. 4ex (using setupinterlinespace); may
1445 be repeated for multiple options
1446 headertext, footertext
1448 text to be placed in running header or footer (see ConTeXt Head‐
1449 ers and Footers); may be repeated up to four times for different
1450 placement
1451 pagenumbering
1453 page number style and location (using setuppagenumbering); may
1454 be repeated for multiple options
1455 toc include table of contents (can also be set using --toc/--ta‐
1457 ble-of-contents)
1458 lof, lot
1460 include list of figures, list of tables
1461 pdfa adds to the preamble the setup necessary to generate
1463 PDF/A-1b:2005. To successfully generate PDF/A the required ICC
1464 color profiles have to be available and the content and all
1465 included files (such as images) have to be standard conforming.
1466 The ICC profiles can be obtained from ConTeXt ICC Profiles. See
1467 also ConTeXt PDFA for more details.
1468 Variables for man pages
1470 section
1471 section number in man pages
1472 header header in man pages
1474 footer footer in man pages
1476 adjusting
1478 adjusts text to left (l), right (r), center (c), or both (b)
1479 margins
1480 hyphenate
1482 if true (the default), hyphenation will be used
1483 Variables for ms
1485 pointsize
1486 point size (e.g. 10p)
1487 lineheight
1489 line height (e.g. 12p)
1490 fontfamily
1492 font family (e.g. T or P)
1493 indent paragraph indent (e.g. 2m)
1495 Using variables in templates
1497 Variable names are sequences of alphanumerics, -, and _, starting with
1498 a letter. A variable name surrounded by $ signs will be replaced by
1499 its value. For example, the string $title$ in
1500 <title>$title$</title>
1502 will be replaced by the document title.
1504 To write a literal $ in a template, use $$.
1506 Templates may contain conditionals. The syntax is as follows:
1508 $if(variable)$
1510 X
1511 $else$
1512 Y
1513 $endif$
1514 This will include X in the template if variable has a truthy value;
1516 otherwise it will include Y. Here a truthy value is any of the follow‐
1517 ing:
1518 · a string that is not entirely white space,
1520 · a non-empty array where the first value is truthy,
1522 · any number (including zero),
1524 · any object,
1526 · the boolean true (to specify the boolean true value using YAML meta‐
1528 data or the --metadata flag, use true, True, or TRUE; with the
1529 --variable flag, simply omit a value for the variable, e.g. --vari‐
1530 able draft).
1531 X and Y are placeholders for any valid template text, and may include
1533 interpolated variables or other conditionals. The $else$ section may
1534 be omitted.
1535 When variables can have multiple values (for example, author in a
1537 multi-author document), you can use the $for$ keyword:
1538 $for(author)$
1540 <meta name="author" content="$author$" />
1541 $endfor$
1542 You can optionally specify a separator to be used between consecutive
1544 items:
1545 $for(author)$$author$$sep$, $endfor$
1547 A dot can be used to select a field of a variable that takes an object
1549 as its value. So, for example:
1550 $author.name$ ($author.affiliation$)
1552 If you use custom templates, you may need to revise them as pandoc
1554 changes. We recommend tracking the changes in the default templates,
1555 and modifying your custom templates accordingly. An easy way to do
1556 this is to fork the pandoc-templates repository and merge in changes
1557 after each pandoc release.
1558 Templates may contain comments: anything on a line after $-- will be
1560 treated as a comment and ignored.
1561
1563 The behavior of some of the readers and writers can be adjusted by
1564 enabling or disabling various extensions.
1565 An extension can be enabled by adding +EXTENSION to the format name and
1567 disabled by adding -EXTENSION. For example, --from mark‐
1568 down_strict+footnotes is strict Markdown with footnotes enabled, while
1569 --from markdown-footnotes-pipe_tables is pandoc's Markdown without
1570 footnotes or pipe tables.
1571 The markdown reader and writer make by far the most use of extensions.
1573 Extensions only used by them are therefore covered in the section Pan‐
1574 doc's Markdown below (See Markdown variants for commonmark and gfm.) In
1575 the following, extensions that also work for other formats are covered.
1576 Typography
1578 Extension: smart
1579 Interpret straight quotes as curly quotes, --- as em-dashes, -- as
1580 en-dashes, and ... as ellipses. Nonbreaking spaces are inserted after
1581 certain abbreviations, such as "Mr."
1582 This extension can be enabled/disabled for the following formats:
1584 input formats
1586 markdown, commonmark, latex, mediawiki, org, rst, twiki
1587 output formats
1589 markdown, latex, context, rst
1590 enabled by default in
1592 markdown, latex, context (both input and output)
1593 Note: If you are writing Markdown, then the smart extension has the
1595 reverse effect: what would have been curly quotes comes out straight.
1596 In LaTeX, smart means to use the standard TeX ligatures for quotation
1598 marks (`` and '' for double quotes, ` and ' for single quotes) and
1599 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
1600 then in reading LaTeX pandoc will parse these characters literally. In
1601 writing LaTeX, enabling smart tells pandoc to use the ligatures when
1602 possible; if smart is disabled pandoc will use unicode quotation mark
1603 and dash characters.
1604 Headers and sections
1606 Extension: auto_identifiers
1607 A header without an explicitly specified identifier will be automati‐
1608 cally assigned a unique identifier based on the header text.
1609 This extension can be enabled/disabled for the following formats:
1611 input formats
1613 markdown, latex, rst, mediawiki, textile
1614 output formats
1616 markdown, muse
1617 enabled by default in
1619 markdown, muse
1620 The default algorithm used to derive the identifier from the header
1622 text is:
1623 · Remove all formatting, links, etc.
1625 · Remove all footnotes.
1627 · Remove all punctuation, except underscores, hyphens, and periods.
1629 · Replace all spaces and newlines with hyphens.
1631 · Convert all alphabetic characters to lowercase.
1633 · Remove everything up to the first letter (identifiers may not begin
1635 with a number or punctuation mark).
1636 · If nothing is left after this, use the identifier section.
1638 Thus, for example,
1640 Header Identifier
1642 ────────────────────────────────────────────────────────
1643 Header identifiers in HTML header-identifiers-in-html
1644 *Dogs*?--in *my* house? dogs--in-my-house
1645 [HTML], [S5], or [RTF]? html-s5-or-rtf
1646 3. Applications applications
1647 33 section
1648 These rules should, in most cases, allow one to determine the identi‐
1650 fier from the header text. The exception is when several headers have
1651 the same text; in this case, the first will get an identifier as
1652 described above; the second will get the same identifier with -1
1653 appended; the third with -2; and so on.
1654 (However, a different algorithm is used if gfm_auto_identifiers is
1656 enabled; see below.)
1657 These identifiers are used to provide link targets in the table of con‐
1659 tents generated by the --toc|--table-of-contents option. They also
1660 make it easy to provide links from one section of a document to
1661 another. A link to this section, for example, might look like this:
1662 See the section on
1664 [header identifiers](#header-identifiers-in-html-latex-and-context).
1665 Note, however, that this method of providing links to sections works
1667 only in HTML, LaTeX, and ConTeXt formats.
1668 If the --section-divs option is specified, then each section will be
1670 wrapped in a section (or a div, if html4 was specified), and the iden‐
1671 tifier will be attached to the enclosing <section> (or <div>) tag
1672 rather than the header itself. This allows entire sections to be
1673 manipulated using JavaScript or treated differently in CSS.
1674 Extension: ascii_identifiers
1676 Causes the identifiers produced by auto_identifiers to be pure ASCII.
1677 Accents are stripped off of accented Latin letters, and non-Latin let‐
1678 ters are omitted.
1679 Extension: gfm_auto_identifiers
1681 Changes the algorithm used by auto_identifiers to conform to GitHub's
1682 method. Spaces are converted to dashes (-), uppercase characters to
1683 lowercase characters, and punctuation characters other than - and _ are
1684 removed.
1685 Math Input
1687 The extensions tex_math_dollars, tex_math_single_backslash, and
1688 tex_math_double_backslash are described in the section about Pandoc's
1689 Markdown.
1690 However, they can also be used with HTML input. This is handy for
1692 reading web pages formatted using MathJax, for example.
1693 Raw HTML/TeX
1695 The following extensions (especially how they affect Markdown
1696 input/output) are also described in more detail in their respective
1697 sections of Pandoc's Markdown.
1698 Extension: raw_html
1700 When converting from HTML, parse elements to raw HTML which are not
1701 representable in pandoc's AST. By default, this is disabled for HTML
1702 input.
1703 Extension: raw_tex
1705 Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
1706 This extension can be enabled/disabled for the following formats (in
1708 addition to markdown):
1709 input formats
1711 latex, org, textile, html (environments, \ref, and \eqref only)
1712 output formats
1714 textile, commonmark
1715 Extension: native_divs
1717 This extension is enabled by default for HTML input. This means that
1718 divs are parsed to pandoc native elements. (Alternatively, you can
1719 parse them to raw HTML using -f html-native_divs+raw_html.)
1720 When converting HTML to Markdown, for example, you may want to drop all
1722 divs and spans:
1723 pandoc -f html-native_divs-native_spans -t markdown
1725 Extension: native_spans
1727 Analogous to native_divs above.
1728 Literate Haskell support
1730 Extension: literate_haskell
1731 Treat the document as literate Haskell source.
1732 This extension can be enabled/disabled for the following formats:
1734 input formats
1736 markdown, rst, latex
1737 output formats
1739 markdown, rst, latex, html
1740 If you append +lhs (or +literate_haskell) to one of the formats above,
1742 pandoc will treat the document as literate Haskell source. This means
1743 that
1744 · In Markdown input, "bird track" sections will be parsed as Haskell
1746 code rather than block quotations. Text between \begin{code} and
1747 \end{code} will also be treated as Haskell code. For ATX-style head‐
1748 ers the character '=' will be used instead of '#'.
1749 · In Markdown output, code blocks with classes haskell and literate
1751 will be rendered using bird tracks, and block quotations will be
1752 indented one space, so they will not be treated as Haskell code. In
1753 addition, headers will be rendered setext-style (with underlines)
1754 rather than ATX-style (with '#' characters). (This is because ghc
1755 treats '#' characters in column 1 as introducing line numbers.)
1756 · In restructured text input, "bird track" sections will be parsed as
1758 Haskell code.
1759 · In restructured text output, code blocks with class haskell will be
1761 rendered using bird tracks.
1762 · In LaTeX input, text in code environments will be parsed as Haskell
1764 code.
1765 · In LaTeX output, code blocks with class haskell will be rendered
1767 inside code environments.
1768 · In HTML output, code blocks with class haskell will be rendered with
1770 class literatehaskell and bird tracks.
1771 Examples:
1773 pandoc -f markdown+lhs -t html
1775 reads literate Haskell source formatted with Markdown conventions and
1777 writes ordinary HTML (without bird tracks).
1778 pandoc -f markdown+lhs -t html+lhs
1780 writes HTML with the Haskell code in bird tracks, so it can be copied
1782 and pasted as literate Haskell source.
1783 Note that GHC expects the bird tracks in the first column, so indented
1785 literate code blocks (e.g. inside an itemized environment) will not be
1786 picked up by the Haskell compiler.
1787 Other extensions
1789 Extension: empty_paragraphs
1790 Allows empty paragraphs. By default empty paragraphs are omitted.
1791 This extension can be enabled/disabled for the following formats:
1793 input formats
1795 docx, html
1796 output formats
1798 docx, odt, opendocument, html
1799 Extension: styles
1801 Read all docx styles as divs (for paragraph styles) and spans (for
1802 character styles) regardless of whether pandoc understands the meaning
1803 of these styles. This can be used with docx custom styles. Disabled
1804 by default.
1805 input formats
1807 docx
1808 Extension: amuse
1810 In the muse input format, this enables Text::Amuse extensions to Emacs
1811 Muse markup.
1812 Extension: citations
1814 Some aspects of Pandoc's Markdown citation syntax are also accepted in
1815 org input.
1816 Extension: ntb
1818 In the context output format this enables the use of Natural Tables
1819 (TABLE) instead of the default Extreme Tables (xtables). Natural
1820 tables allow more fine-grained global customization but come at a per‐
1821 formance penalty compared to extreme tables.
1822
1824 Pandoc understands an extended and slightly revised version of John
1825 Gruber's Markdown syntax. This document explains the syntax, noting
1826 differences from standard Markdown. Except where noted, these differ‐
1827 ences can be suppressed by using the markdown_strict format instead of
1828 markdown. Extensions can be enabled or disabled to specify the behav‐
1829 ior more granularly. They are described in the following. See also
1830 Extensions above, for extensions that work also on other formats.
1831 Philosophy
1833 Markdown is designed to be easy to write, and, even more importantly,
1834 easy to read:
1835 A Markdown-formatted document should be publishable as-is, as
1837 plain text, without looking like it's been marked up with tags
1838 or formatting instructions. -- John Gruber
1839 This principle has guided pandoc's decisions in finding syntax for
1841 tables, footnotes, and other extensions.
1842 There is, however, one respect in which pandoc's aims are different
1844 from the original aims of Markdown. Whereas Markdown was originally
1845 designed with HTML generation in mind, pandoc is designed for multiple
1846 output formats. Thus, while pandoc allows the embedding of raw HTML,
1847 it discourages it, and provides other, non-HTMLish ways of representing
1848 important document elements like definition lists, tables, mathematics,
1849 and footnotes.
1850 Paragraphs
1852 A paragraph is one or more lines of text followed by one or more blank
1853 lines. Newlines are treated as spaces, so you can reflow your para‐
1854 graphs as you like. If you need a hard line break, put two or more
1855 spaces at the end of a line.
1856 Extension: escaped_line_breaks
1858 A backslash followed by a newline is also a hard line break. Note: in
1859 multiline and grid table cells, this is the only way to create a hard
1860 line break, since trailing spaces in the cells are ignored.
1861 Headers
1863 There are two kinds of headers: Setext and ATX.
1864 Setext-style headers
1866 A setext-style header is a line of text "underlined" with a row of =
1867 signs (for a level one header) or - signs (for a level two header):
1868 A level-one header
1870 ==================
1871 A level-two header
1873 ------------------
1874 The header text can contain inline formatting, such as emphasis (see
1876 Inline formatting, below).
1877 ATX-style headers
1879 An ATX-style header consists of one to six # signs and a line of text,
1880 optionally followed by any number of # signs. The number of # signs at
1881 the beginning of the line is the header level:
1882 ## A level-two header
1884 ### A level-three header ###
1886 As with setext-style headers, the header text can contain formatting:
1888 # A level-one header with a [link](/url) and *emphasis*
1890 Extension: blank_before_header
1892 Standard Markdown syntax does not require a blank line before a header.
1893 Pandoc does require this (except, of course, at the beginning of the
1894 document). The reason for the requirement is that it is all too easy
1895 for a # to end up at the beginning of a line by accident (perhaps
1896 through line wrapping). Consider, for example:
1897 I like several of their flavors of ice cream:
1899 #22, for example, and #5.
1900 Extension: space_in_atx_header
1902 Many Markdown implementations do not require a space between the open‐
1903 ing #s of an ATX header and the header text, so that #5 bolt and #hash‐
1904 tag count as headers. With this extension, pandoc does require the
1905 space.
1906 Header identifiers
1908 See also the auto_identifiers extension above.
1909 Extension: header_attributes
1911 Headers can be assigned attributes using this syntax at the end of the
1912 line containing the header text:
1913 {#identifier .class .class key=value key=value}
1915 Thus, for example, the following headers will all be assigned the iden‐
1917 tifier foo:
1918 # My header {#foo}
1920 ## My header ## {#foo}
1922 My other header {#foo}
1924 ---------------
1925 (This syntax is compatible with PHP Markdown Extra.)
1927 Note that although this syntax allows assignment of classes and
1929 key/value attributes, writers generally don't use all of this informa‐
1930 tion. Identifiers, classes, and key/value attributes are used in HTML
1931 and HTML-based formats such as EPUB and slidy. Identifiers are used
1932 for labels and link anchors in the LaTeX, ConTeXt, Textile, and Asci‐
1933 iDoc writers.
1934 Headers with the class unnumbered will not be numbered, even if --num‐
1936 ber-sections is specified. A single hyphen (-) in an attribute context
1937 is equivalent to .unnumbered, and preferable in non-English documents.
1938 So,
1939 # My header {-}
1941 is just the same as
1943 # My header {.unnumbered}
1945 Extension: implicit_header_references
1947 Pandoc behaves as if reference links have been defined for each header.
1948 So, to link to a header
1949 # Header identifiers in HTML
1951 you can simply write
1953 [Header identifiers in HTML]
1955 or
1957 [Header identifiers in HTML][]
1959 or
1961 [the section on header identifiers][header identifiers in
1963 HTML]
1964 instead of giving the identifier explicitly:
1966 [Header identifiers in HTML](#header-identifiers-in-html)
1968 If there are multiple headers with identical text, the corresponding
1970 reference will link to the first one only, and you will need to use
1971 explicit links to link to the others, as described above.
1972 Like regular reference links, these references are case-insensitive.
1974 Explicit link reference definitions always take priority over implicit
1976 header references. So, in the following example, the link will point
1977 to bar, not to #foo:
1978 # Foo
1980 [foo]: bar
1982 See [foo]
1984 Block quotations
1986 Markdown uses email conventions for quoting blocks of text. A block
1987 quotation is one or more paragraphs or other block elements (such as
1988 lists or headers), with each line preceded by a > character and an
1989 optional space. (The > need not start at the left margin, but it
1990 should not be indented more than three spaces.)
1991 > This is a block quote. This
1993 > paragraph has two lines.
1994 >
1995 > 1. This is a list inside a block quote.
1996 > 2. Second item.
1997 A "lazy" form, which requires the > character only on the first line of
1999 each block, is also allowed:
2000 > This is a block quote. This
2002 paragraph has two lines.
2003 > 1. This is a list inside a block quote.
2005 2. Second item.
2006 Among the block elements that can be contained in a block quote are
2008 other block quotes. That is, block quotes can be nested:
2009 > This is a block quote.
2011 >
2012 > > A block quote within a block quote.
2013 If the > character is followed by an optional space, that space will be
2015 considered part of the block quote marker and not part of the indenta‐
2016 tion of the contents. Thus, to put an indented code block in a block
2017 quote, you need five spaces after the >:
2018 > code
2020 Extension: blank_before_blockquote
2022 Standard Markdown syntax does not require a blank line before a block
2023 quote. Pandoc does require this (except, of course, at the beginning
2024 of the document). The reason for the requirement is that it is all too
2025 easy for a > to end up at the beginning of a line by accident (perhaps
2026 through line wrapping). So, unless the markdown_strict format is used,
2027 the following does not produce a nested block quote in pandoc:
2028 > This is a block quote.
2030 >> Nested.
2031 Verbatim (code) blocks
2033 Indented code blocks
2034 A block of text indented four spaces (or one tab) is treated as verba‐
2035 tim text: that is, special characters do not trigger special format‐
2036 ting, and all spaces and line breaks are preserved. For example,
2037 if (a > 3) {
2039 moveShip(5 * gravity, DOWN);
2040 }
2041 The initial (four space or one tab) indentation is not considered part
2043 of the verbatim text, and is removed in the output.
2044 Note: blank lines in the verbatim text need not begin with four spaces.
2046 Fenced code blocks
2048 Extension: fenced_code_blocks
2049 In addition to standard indented code blocks, pandoc supports fenced
2050 code blocks. These begin with a row of three or more tildes (~) and
2051 end with a row of tildes that must be at least as long as the starting
2052 row. Everything between these lines is treated as code. No indenta‐
2053 tion is necessary:
2054 ~~~~~~~
2056 if (a > 3) {
2057 moveShip(5 * gravity, DOWN);
2058 }
2059 ~~~~~~~
2060 Like regular code blocks, fenced code blocks must be separated from
2062 surrounding text by blank lines.
2063 If the code itself contains a row of tildes or backticks, just use a
2065 longer row of tildes or backticks at the start and end:
2066 ~~~~~~~~~~~~~~~~
2068 ~~~~~~~~~~
2069 code including tildes
2070 ~~~~~~~~~~
2071 ~~~~~~~~~~~~~~~~
2072 Extension: backtick_code_blocks
2074 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
2075 (~).
2076 Extension: fenced_code_attributes
2078 Optionally, you may attach attributes to fenced or backtick code block
2079 using this syntax:
2080 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
2082 qsort [] = []
2083 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
2084 qsort (filter (>= x) xs)
2085 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2086 Here mycode is an identifier, haskell and numberLines are classes, and
2088 startFrom is an attribute with value 100. Some output formats can use
2089 this information to do syntax highlighting. Currently, the only output
2090 formats that uses this information are HTML, LaTeX, Docx, Ms, and Pow‐
2091 erPoint. If highlighting is supported for your output format and lan‐
2092 guage, then the code block above will appear highlighted, with numbered
2093 lines. (To see which languages are supported, type pandoc --list-high‐
2094 light-languages.) Otherwise, the code block above will appear as fol‐
2095 lows:
2096 <pre id="mycode" class="haskell numberLines" startFrom="100">
2098 <code>
2099 ...
2100 </code>
2101 </pre>
2102 The numberLines (or number-lines) class will cause the lines of the
2104 code block to be numbered, starting with 1 or the value of the start‐
2105 From attribute. The lineAnchors (or line-anchors) class will cause the
2106 lines to be clickable anchors in HTML output.
2107 A shortcut form can also be used for specifying the language of the
2109 code block:
2110 ```haskell
2112 qsort [] = []
2113 ```
2114 This is equivalent to:
2116 ``` {.haskell}
2118 qsort [] = []
2119 ```
2120 If the fenced_code_attributes extension is disabled, but input contains
2122 class attribute(s) for the code block, the first class attribute will
2123 be printed after the opening fence as a bare word.
2124 To prevent all highlighting, use the --no-highlight flag. To set the
2126 highlighting style, use --highlight-style. For more information on
2127 highlighting, see Syntax highlighting, below.
2128 Line blocks
2130 Extension: line_blocks
2131 A line block is a sequence of lines beginning with a vertical bar (|)
2132 followed by a space. The division into lines will be preserved in the
2133 output, as will any leading spaces; otherwise, the lines will be for‐
2134 matted as Markdown. This is useful for verse and addresses:
2135 | The limerick packs laughs anatomical
2137 | In space that is quite economical.
2138 | But the good ones I've seen
2139 | So seldom are clean
2140 | And the clean ones so seldom are comical
2141 | 200 Main St.
2143 | Berkeley, CA 94718
2144 The lines can be hard-wrapped if needed, but the continuation line must
2146 begin with a space.
2147 | The Right Honorable Most Venerable and Righteous Samuel L.
2149 Constable, Jr.
2150 | 200 Main St.
2151 | Berkeley, CA 94718
2152 This syntax is borrowed from reStructuredText.
2154 Lists
2156 Bullet lists
2157 A bullet list is a list of bulleted list items. A bulleted list item
2158 begins with a bullet (*, +, or -). Here is a simple example:
2159 * one
2161 * two
2162 * three
2163 This will produce a "compact" list. If you want a "loose" list, in
2165 which each item is formatted as a paragraph, put spaces between the
2166 items:
2167 * one
2169 * two
2171 * three
2173 The bullets need not be flush with the left margin; they may be
2175 indented one, two, or three spaces. The bullet must be followed by
2176 whitespace.
2177 List items look best if subsequent lines are flush with the first line
2179 (after the bullet):
2180 * here is my first
2182 list item.
2183 * and my second.
2184 But Markdown also allows a "lazy" format:
2186 * here is my first
2188 list item.
2189 * and my second.
2190 Block content in list items
2192 A list item may contain multiple paragraphs and other block-level con‐
2193 tent. However, subsequent paragraphs must be preceded by a blank line
2194 and indented to line up with the first non-space content after the list
2195 marker.
2196 * First paragraph.
2198 Continued.
2200 * Second paragraph. With a code block, which must be indented
2202 eight spaces:
2203 { code }
2205 Exception: if the list marker is followed by an indented code block,
2207 which must begin 5 spaces after the list marker, then subsequent para‐
2208 graphs must begin two columns after the last character of the list
2209 marker:
2210 * code
2212 continuation paragraph
2214 List items may include other lists. In this case the preceding blank
2216 line is optional. The nested list must be indented to line up with the
2217 first non-space character after the list marker of the containing list
2218 item.
2219 * fruits
2221 + apples
2222 - macintosh
2223 - red delicious
2224 + pears
2225 + peaches
2226 * vegetables
2227 + broccoli
2228 + chard
2229 As noted above, Markdown allows you to write list items "lazily,"
2231 instead of indenting continuation lines. However, if there are multi‐
2232 ple paragraphs or other blocks in a list item, the first line of each
2233 must be indented.
2234 + A lazy, lazy, list
2236 item.
2237 + Another one; this looks
2239 bad but is legal.
2240 Second paragraph of second
2242 list item.
2243 Ordered lists
2245 Ordered lists work just like bulleted lists, except that the items
2246 begin with enumerators rather than bullets.
2247 In standard Markdown, enumerators are decimal numbers followed by a
2249 period and a space. The numbers themselves are ignored, so there is no
2250 difference between this list:
2251 1. one
2253 2. two
2254 3. three
2255 and this one:
2257 5. one
2259 7. two
2260 1. three
2261 Extension: fancy_lists
2263 Unlike standard Markdown, pandoc allows ordered list items to be marked
2264 with uppercase and lowercase letters and roman numerals, in addition to
2265 Arabic numerals. List markers may be enclosed in parentheses or fol‐
2266 lowed by a single right-parentheses or period. They must be separated
2267 from the text that follows by at least one space, and, if the list
2268 marker is a capital letter with a period, by at least two spaces.
2269 The fancy_lists extension also allows '#' to be used as an ordered list
2271 marker in place of a numeral:
2272 #. one
2274 #. two
2275 Extension: startnum
2277 Pandoc also pays attention to the type of list marker used, and to the
2278 starting number, and both of these are preserved where possible in the
2279 output format. Thus, the following yields a list with numbers followed
2280 by a single parenthesis, starting with 9, and a sublist with lowercase
2281 roman numerals:
2282 9) Ninth
2284 10) Tenth
2285 11) Eleventh
2286 i. subone
2287 ii. subtwo
2288 iii. subthree
2289 Pandoc will start a new list each time a different type of list marker
2291 is used. So, the following will create three lists:
2292 (2) Two
2294 (5) Three
2295 1. Four
2296 * Five
2297 If default list markers are desired, use #.:
2299 #. one
2301 #. two
2302 #. three
2303 Definition lists
2305 Extension: definition_lists
2306 Pandoc supports definition lists, using the syntax of PHP Markdown
2307 Extra with some extensions.
2308 Term 1
2310 : Definition 1
2312 Term 2 with *inline markup*
2314 : Definition 2
2316 { some code, part of Definition 2 }
2318 Third paragraph of definition 2.
2320 Each term must fit on one line, which may optionally be followed by a
2322 blank line, and must be followed by one or more definitions. A defini‐
2323 tion begins with a colon or tilde, which may be indented one or two
2324 spaces.
2325 A term may have multiple definitions, and each definition may consist
2327 of one or more block elements (paragraph, code block, list, etc.), each
2328 indented four spaces or one tab stop. The body of the definition
2329 (including the first line, aside from the colon or tilde) should be
2330 indented four spaces. However, as with other Markdown lists, you can
2331 "lazily" omit indentation except at the beginning of a paragraph or
2332 other block element:
2333 Term 1
2335 : Definition
2337 with lazy continuation.
2338 Second paragraph of the definition.
2340 If you leave space before the definition (as in the example above), the
2342 text of the definition will be treated as a paragraph. In some output
2343 formats, this will mean greater spacing between term/definition pairs.
2344 For a more compact definition list, omit the space before the defini‐
2345 tion:
2346 Term 1
2348 ~ Definition 1
2349 Term 2
2351 ~ Definition 2a
2352 ~ Definition 2b
2353 Note that space between items in a definition list is required. (A
2355 variant that loosens this requirement, but disallows "lazy" hard wrap‐
2356 ping, can be activated with compact_definition_lists: see Non-pandoc
2357 extensions, below.)
2358 Numbered example lists
2360 Extension: example_lists
2361 The special list marker @ can be used for sequentially numbered exam‐
2362 ples. The first list item with a @ marker will be numbered '1', the
2363 next '2', and so on, throughout the document. The numbered examples
2364 need not occur in a single list; each new list using @ will take up
2365 where the last stopped. So, for example:
2366 (@) My first example will be numbered (1).
2368 (@) My second example will be numbered (2).
2369 Explanation of examples.
2371 (@) My third example will be numbered (3).
2373 Numbered examples can be labeled and referred to elsewhere in the docu‐
2375 ment:
2376 (@good) This is a good example.
2378 As (@good) illustrates, ...
2380 The label can be any string of alphanumeric characters, underscores, or
2382 hyphens.
2383 Note: continuation paragraphs in example lists must always be indented
2385 four spaces, regardless of the length of the list marker. That is,
2386 example lists always behave as if the four_space_rule extension is set.
2387 This is because example labels tend to be long, and indenting content
2388 to the first non-space character after the label would be awkward.
2389 Compact and loose lists
2391 Pandoc behaves differently from Markdown.pl on some "edge cases"
2392 involving lists. Consider this source:
2393 + First
2395 + Second:
2396 - Fee
2397 - Fie
2398 - Foe
2399 + Third
2401 Pandoc transforms this into a "compact list" (with no <p> tags around
2403 "First", "Second", or "Third"), while Markdown puts <p> tags around
2404 "Second" and "Third" (but not "First"), because of the blank space
2405 around "Third". Pandoc follows a simple rule: if the text is followed
2406 by a blank line, it is treated as a paragraph. Since "Second" is fol‐
2407 lowed by a list, and not a blank line, it isn't treated as a paragraph.
2408 The fact that the list is followed by a blank line is irrelevant.
2409 (Note: Pandoc works this way even when the markdown_strict format is
2410 specified. This behavior is consistent with the official Markdown syn‐
2411 tax description, even though it is different from that of Markdown.pl.)
2412 Ending a list
2414 What if you want to put an indented code block after a list?
2415 - item one
2417 - item two
2418 { my code block }
2420 Trouble! Here pandoc (like other Markdown implementations) will treat {
2422 my code block } as the second paragraph of item two, and not as a code
2423 block.
2424 To "cut off" the list after item two, you can insert some non-indented
2426 content, like an HTML comment, which won't produce visible output in
2427 any format:
2428 - item one
2430 - item two
2431 <!-- end of list -->
2433 { my code block }
2435 You can use the same trick if you want two consecutive lists instead of
2437 one big list:
2438 1. one
2440 2. two
2441 3. three
2442 <!-- -->
2444 1. uno
2446 2. dos
2447 3. tres
2448 Horizontal rules
2450 A line containing a row of three or more *, -, or _ characters (option‐
2451 ally separated by spaces) produces a horizontal rule:
2452 * * * *
2454 ---------------
2456 Tables
2458 Four kinds of tables may be used. The first three kinds presuppose the
2459 use of a fixed-width font, such as Courier. The fourth kind can be
2460 used with proportionally spaced fonts, as it does not require lining up
2461 columns.
2462 Extension: table_captions
2464 A caption may optionally be provided with all 4 kinds of tables (as
2465 illustrated in the examples below). A caption is a paragraph beginning
2466 with the string Table: (or just :), which will be stripped off. It may
2467 appear either before or after the table.
2468 Extension: simple_tables
2470 Simple tables look like this:
2471 Right Left Center Default
2473 ------- ------ ---------- -------
2474 12 12 12 12
2475 123 123 123 123
2476 1 1 1 1
2477 Table: Demonstration of simple table syntax.
2479 The headers and table rows must each fit on one line. Column align‐
2481 ments are determined by the position of the header text relative to the
2482 dashed line below it:
2483 · If the dashed line is flush with the header text on the right side
2485 but extends beyond it on the left, the column is right-aligned.
2486 · If the dashed line is flush with the header text on the left side but
2488 extends beyond it on the right, the column is left-aligned.
2489 · If the dashed line extends beyond the header text on both sides, the
2491 column is centered.
2492 · If the dashed line is flush with the header text on both sides, the
2494 default alignment is used (in most cases, this will be left).
2495 The table must end with a blank line, or a line of dashes followed by a
2497 blank line.
2498 The column headers may be omitted, provided a dashed line is used to
2500 end the table. For example:
2501 ------- ------ ---------- -------
2503 12 12 12 12
2504 123 123 123 123
2505 1 1 1 1
2506 ------- ------ ---------- -------
2507 When headers are omitted, column alignments are determined on the basis
2509 of the first line of the table body. So, in the tables above, the col‐
2510 umns would be right, left, center, and right aligned, respectively.
2511 Extension: multiline_tables
2513 Multiline tables allow headers and table rows to span multiple lines of
2514 text (but cells that span multiple columns or rows of the table are not
2515 supported). Here is an example:
2516 -------------------------------------------------------------
2518 Centered Default Right Left
2519 Header Aligned Aligned Aligned
2520 ----------- ------- --------------- -------------------------
2521 First row 12.0 Example of a row that
2522 spans multiple lines.
2523 Second row 5.0 Here's another one. Note
2525 the blank line between
2526 rows.
2527 -------------------------------------------------------------
2528 Table: Here's the caption. It, too, may span
2530 multiple lines.
2531 These work like simple tables, but with the following differences:
2533 · They must begin with a row of dashes, before the header text (unless
2535 the headers are omitted).
2536 · They must end with a row of dashes, then a blank line.
2538 · The rows must be separated by blank lines.
2540 In multiline tables, the table parser pays attention to the widths of
2542 the columns, and the writers try to reproduce these relative widths in
2543 the output. So, if you find that one of the columns is too narrow in
2544 the output, try widening it in the Markdown source.
2545 Headers may be omitted in multiline tables as well as simple tables:
2547 ----------- ------- --------------- -------------------------
2549 First row 12.0 Example of a row that
2550 spans multiple lines.
2551 Second row 5.0 Here's another one. Note
2553 the blank line between
2554 rows.
2555 ----------- ------- --------------- -------------------------
2556 : Here's a multiline table without headers.
2558 It is possible for a multiline table to have just one row, but the row
2560 should be followed by a blank line (and then the row of dashes that
2561 ends the table), or the table may be interpreted as a simple table.
2562 Extension: grid_tables
2564 Grid tables look like this:
2565 : Sample grid table.
2567 +---------------+---------------+--------------------+
2569 | Fruit | Price | Advantages |
2570 +===============+===============+====================+
2571 | Bananas | $1.34 | - built-in wrapper |
2572 | | | - bright color |
2573 +---------------+---------------+--------------------+
2574 | Oranges | $2.10 | - cures scurvy |
2575 | | | - tasty |
2576 +---------------+---------------+--------------------+
2577 The row of =s separates the header from the table body, and can be
2579 omitted for a headerless table. The cells of grid tables may contain
2580 arbitrary block elements (multiple paragraphs, code blocks, lists,
2581 etc.). Cells that span multiple columns or rows are not supported.
2582 Grid tables can be created easily using Emacs table mode.
2583 Alignments can be specified as with pipe tables, by putting colons at
2585 the boundaries of the separator line after the header:
2586 +---------------+---------------+--------------------+
2588 | Right | Left | Centered |
2589 +==============:+:==============+:==================:+
2590 | Bananas | $1.34 | built-in wrapper |
2591 +---------------+---------------+--------------------+
2592 For headerless tables, the colons go on the top line instead:
2594 +--------------:+:--------------+:------------------:+
2596 | Right | Left | Centered |
2597 +---------------+---------------+--------------------+
2598 Grid Table Limitations
2600 Pandoc does not support grid tables with row spans or column spans.
2601 This means that neither variable numbers of columns across rows nor
2602 variable numbers of rows across columns are supported by Pandoc. All
2603 grid tables must have the same number of columns in each row, and the
2604 same number of rows in each column. For example, the Docutils sample
2605 grid tables will not render as expected with Pandoc.
2606 Extension: pipe_tables
2608 Pipe tables look like this:
2609 | Right | Left | Default | Center |
2611 |------:|:-----|---------|:------:|
2612 | 12 | 12 | 12 | 12 |
2613 | 123 | 123 | 123 | 123 |
2614 | 1 | 1 | 1 | 1 |
2615 : Demonstration of pipe table syntax.
2617 The syntax is identical to PHP Markdown Extra tables. The beginning
2619 and ending pipe characters are optional, but pipes are required between
2620 all columns. The colons indicate column alignment as shown. The
2621 header cannot be omitted. To simulate a headerless table, include a
2622 header with blank cells.
2623 Since the pipes indicate column boundaries, columns need not be verti‐
2625 cally aligned, as they are in the above example. So, this is a per‐
2626 fectly legal (though ugly) pipe table:
2627 fruit| price
2629 -----|-----:
2630 apple|2.05
2631 pear|1.37
2632 orange|3.09
2633 The cells of pipe tables cannot contain block elements like paragraphs
2635 and lists, and cannot span multiple lines. If a pipe table contains a
2636 row whose printable content is wider than the column width (see --col‐
2637 umns), then the table will take up the full text width and the cell
2638 contents will wrap, with the relative cell widths determined by the
2639 number of dashes in the line separating the table header from the table
2640 body. (For example ---|- would make the first column 3/4 and the sec‐
2641 ond column 1/4 of the full text width.) On the other hand, if no lines
2642 are wider than column width, then cell contents will not be wrapped,
2643 and the cells will be sized to their contents.
2644 Note: pandoc also recognizes pipe tables of the following form, as can
2646 be produced by Emacs' orgtbl-mode:
2647 | One | Two |
2649 |-----+-------|
2650 | my | table |
2651 | is | nice |
2652 The difference is that + is used instead of |. Other orgtbl features
2654 are not supported. In particular, to get non-default column alignment,
2655 you'll need to add colons as above.
2656 Metadata blocks
2658 Extension: pandoc_title_block
2659 If the file begins with a title block
2660 % title
2662 % author(s) (separated by semicolons)
2663 % date
2664 it will be parsed as bibliographic information, not regular text. (It
2666 will be used, for example, in the title of standalone LaTeX or HTML
2667 output.) The block may contain just a title, a title and an author, or
2668 all three elements. If you want to include an author but no title, or
2669 a title and a date but no author, you need a blank line:
2670 %
2672 % Author
2673 % My title
2675 %
2676 % June 15, 2006
2677 The title may occupy multiple lines, but continuation lines must begin
2679 with leading space, thus:
2680 % My title
2682 on multiple lines
2683 If a document has multiple authors, the authors may be put on separate
2685 lines with leading space, or separated by semicolons, or both. So, all
2686 of the following are equivalent:
2687 % Author One
2689 Author Two
2690 % Author One; Author Two
2692 % Author One;
2694 Author Two
2695 The date must fit on one line.
2697 All three metadata fields may contain standard inline formatting (ital‐
2699 ics, links, footnotes, etc.).
2700 Title blocks will always be parsed, but they will affect the output
2702 only when the --standalone (-s) option is chosen. In HTML output,
2703 titles will appear twice: once in the document head -- this is the
2704 title that will appear at the top of the window in a browser -- and
2705 once at the beginning of the document body. The title in the document
2706 head can have an optional prefix attached (--title-prefix or -T
2707 option). The title in the body appears as an H1 element with class
2708 "title", so it can be suppressed or reformatted with CSS. If a title
2709 prefix is specified with -T and no title block appears in the document,
2710 the title prefix will be used by itself as the HTML title.
2711 The man page writer extracts a title, man page section number, and
2713 other header and footer information from the title line. The title is
2714 assumed to be the first word on the title line, which may optionally
2715 end with a (single-digit) section number in parentheses. (There should
2716 be no space between the title and the parentheses.) Anything after
2717 this is assumed to be additional footer and header text. A single pipe
2718 character (|) should be used to separate the footer text from the
2719 header text. Thus,
2720 % PANDOC(1)
2722 will yield a man page with the title PANDOC and section 1.
2724 % PANDOC(1) Pandoc User Manuals
2726 will also have "Pandoc User Manuals" in the footer.
2728 % PANDOC(1) Pandoc User Manuals | Version 4.0
2730 will also have "Version 4.0" in the header.
2732 Extension: yaml_metadata_block
2734 A YAML metadata block is a valid YAML object, delimited by a line of
2735 three hyphens (---) at the top and a line of three hyphens (---) or
2736 three dots (...) at the bottom. A YAML metadata block may occur any‐
2737 where in the document, but if it is not at the beginning, it must be
2738 preceded by a blank line. (Note that, because of the way pandoc con‐
2739 catenates input files when several are provided, you may also keep the
2740 metadata in a separate YAML file and pass it to pandoc as an argument,
2741 along with your Markdown files:
2742 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
2744 Just be sure that the YAML file begins with --- and ends with --- or
2746 ....) Alternatively, you can use the --metadata-file option. Using
2747 that approach however, you cannot reference content (like footnotes)
2748 from the main markdown input document.
2749 Metadata will be taken from the fields of the YAML object and added to
2751 any existing document metadata. Metadata can contain lists and objects
2752 (nested arbitrarily), but all string scalars will be interpreted as
2753 Markdown. Fields with names ending in an underscore will be ignored by
2754 pandoc. (They may be given a role by external processors.) Field names
2755 must not be interpretable as YAML numbers or boolean values (so, for
2756 example, yes, True, and 15 cannot be used as field names).
2757 A document may contain multiple metadata blocks. The metadata fields
2759 will be combined through a left-biased union: if two metadata blocks
2760 attempt to set the same field, the value from the first block will be
2761 taken.
2762 When pandoc is used with -t markdown to create a Markdown document, a
2764 YAML metadata block will be produced only if the -s/--standalone option
2765 is used. All of the metadata will appear in a single block at the
2766 beginning of the document.
2767 Note that YAML escaping rules must be followed. Thus, for example, if
2769 a title contains a colon, it must be quoted. The pipe character (|)
2770 can be used to begin an indented block that will be interpreted liter‐
2771 ally, without need for escaping. This form is necessary when the field
2772 contains blank lines or block-level formatting:
2773 ---
2775 title: 'This is the title: it contains a colon'
2776 author:
2777 - Author One
2778 - Author Two
2779 keywords: [nothing, nothingness]
2780 abstract: |
2781 This is the abstract.
2782 It consists of two paragraphs.
2784 ...
2785 Template variables will be set automatically from the metadata. Thus,
2787 for example, in writing HTML, the variable abstract will be set to the
2788 HTML equivalent of the Markdown in the abstract field:
2789 <p>This is the abstract.</p>
2791 <p>It consists of two paragraphs.</p>
2792 Variables can contain arbitrary YAML structures, but the template must
2794 match this structure. The author variable in the default templates
2795 expects a simple list or string, but can be changed to support more
2796 complicated structures. The following combination, for example, would
2797 add an affiliation to the author if one is given:
2798 ---
2800 title: The document title
2801 author:
2802 - name: Author One
2803 affiliation: University of Somewhere
2804 - name: Author Two
2805 affiliation: University of Nowhere
2806 ...
2807 To use the structured authors in the example above, you would need a
2809 custom template:
2810 $for(author)$
2812 $if(author.name)$
2813 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
2814 $else$
2815 $author$
2816 $endif$
2817 $endfor$
2818 Raw content to include in the document's header may be specified using
2820 header-includes; however, it is important to mark up this content as
2821 raw code for a particular output format, using the raw_attribute exten‐
2822 sion), or it will be interpreted as markdown. For example:
2823 header-includes:
2825 - |
2826 ```{=latex}
2827 \let\oldsection\section
2828 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
2829 ```
2830 Backslash escapes
2832 Extension: all_symbols_escapable
2833 Except inside a code block or inline code, any punctuation or space
2834 character preceded by a backslash will be treated literally, even if it
2835 would normally indicate formatting. Thus, for example, if one writes
2836 *\*hello\**
2838 one will get
2840 <em>*hello*</em>
2842 instead of
2844 <strong>hello</strong>
2846 This rule is easier to remember than standard Markdown's rule, which
2848 allows only the following characters to be backslash-escaped:
2849 \`*_{}[]()>#+-.!
2851 (However, if the markdown_strict format is used, the standard Markdown
2853 rule will be used.)
2854 A backslash-escaped space is parsed as a nonbreaking space. It will
2856 appear in TeX output as ~ and in HTML and XML as \  or \ .
2857 A backslash-escaped newline (i.e. a backslash occurring at the end of
2859 a line) is parsed as a hard line break. It will appear in TeX output
2860 as \\ and in HTML as <br />. This is a nice alternative to Markdown's
2861 "invisible" way of indicating hard line breaks using two trailing spa‐
2862 ces on a line.
2863 Backslash escapes do not work in verbatim contexts.
2865 Inline formatting
2867 Emphasis
2868 To emphasize some text, surround it with *s or _, like this:
2869 This text is _emphasized with underscores_, and this
2871 is *emphasized with asterisks*.
2872 Double * or _ produces strong emphasis:
2874 This is **strong emphasis** and __with underscores__.
2876 A * or _ character surrounded by spaces, or backslash-escaped, will not
2878 trigger emphasis:
2879 This is * not emphasized *, and \*neither is this\*.
2881 Extension: intraword_underscores
2883 Because _ is sometimes used inside words and identifiers, pandoc does
2884 not interpret a _ surrounded by alphanumeric characters as an emphasis
2885 marker. If you want to emphasize just part of a word, use *:
2886 feas*ible*, not feas*able*.
2888 Strikeout
2890 Extension: strikeout
2891 To strikeout a section of text with a horizontal line, begin and end it
2892 with ~~. Thus, for example,
2893 This ~~is deleted text.~~
2895 Superscripts and subscripts
2897 Extension: superscript, subscript
2898 Superscripts may be written by surrounding the superscripted text by ^
2899 characters; subscripts may be written by surrounding the subscripted
2900 text by ~ characters. Thus, for example,
2901 H~2~O is a liquid. 2^10^ is 1024.
2903 If the superscripted or subscripted text contains spaces, these spaces
2905 must be escaped with backslashes. (This is to prevent accidental
2906 superscripting and subscripting through the ordinary use of ~ and ^.)
2907 Thus, if you want the letter P with 'a cat' in subscripts, use P~a\
2908 cat~, not P~a cat~.
2909 Verbatim
2911 To make a short span of text verbatim, put it inside backticks:
2912 What is the difference between `>>=` and `>>`?
2914 If the verbatim text includes a backtick, use double backticks:
2916 Here is a literal backtick `` ` ``.
2918 (The spaces after the opening backticks and before the closing back‐
2920 ticks will be ignored.)
2921 The general rule is that a verbatim span starts with a string of con‐
2923 secutive backticks (optionally followed by a space) and ends with a
2924 string of the same number of backticks (optionally preceded by a
2925 space).
2926 Note that backslash-escapes (and other Markdown constructs) do not work
2928 in verbatim contexts:
2929 This is a backslash followed by an asterisk: `\*`.
2931 Extension: inline_code_attributes
2933 Attributes can be attached to verbatim text, just as with fenced code
2934 blocks:
2935 `<$>`{.haskell}
2937 Small caps
2939 To write small caps, use the smallcaps class:
2940 [Small caps]{.smallcaps}
2942 Or, without the bracketed_spans extension:
2944 <span class="smallcaps">Small caps</span>
2946 For compatibility with other Markdown flavors, CSS is also supported:
2948 <span style="font-variant:small-caps;">Small caps</span>
2950 This will work in all output formats that support small caps.
2952 Math
2954 Extension: tex_math_dollars
2955 Anything between two $ characters will be treated as TeX math. The
2956 opening $ must have a non-space character immediately to its right,
2957 while the closing $ must have a non-space character immediately to its
2958 left, and must not be followed immediately by a digit. Thus, $20,000
2959 and $30,000 won't parse as math. If for some reason you need to
2960 enclose text in literal $ characters, backslash-escape them and they
2961 won't be treated as math delimiters.
2962 TeX math will be printed in all output formats. How it is rendered
2964 depends on the output format:
2965 LaTeX It will appear verbatim surrounded by \(...\) (for inline math)
2967 or \[...\] (for display math).
2968 Markdown, Emacs Org mode, ConTeXt, ZimWiki
2970 It will appear verbatim surrounded by $...$ (for inline math) or
2971 $$...$$ (for display math).
2972 reStructuredText
2974 It will be rendered using an interpreted text role :math:.
2975 AsciiDoc
2977 It will be rendered as latexmath:[...].
2978 Texinfo
2980 It will be rendered inside a @math command.
2981 roff man
2983 It will be rendered verbatim without $'s.
2984 MediaWiki, DokuWiki
2986 It will be rendered inside <math> tags.
2987 Textile
2989 It will be rendered inside <span class="math"> tags.
2990 RTF, OpenDocument
2992 It will be rendered, if possible, using Unicode characters, and
2993 will otherwise appear verbatim.
2994 ODT It will be rendered, if possible, using MathML.
2996 DocBook
2998 If the --mathml flag is used, it will be rendered using MathML
2999 in an inlineequation or informalequation tag. Otherwise it will
3000 be rendered, if possible, using Unicode characters.
3001 Docx It will be rendered using OMML math markup.
3003 FictionBook2
3005 If the --webtex option is used, formulas are rendered as images
3006 using CodeCogs or other compatible web service, downloaded and
3007 embedded in the e-book. Otherwise, they will appear verbatim.
3008 HTML, Slidy, DZSlides, S5, EPUB
3010 The way math is rendered in HTML will depend on the command-line
3011 options selected. Therefore see Math rendering in HTML above.
3012 Raw HTML
3014 Extension: raw_html
3015 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
3016 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
3017 erally). (Technically this is not an extension, since standard Mark‐
3018 down allows it, but it has been made an extension so that it can be
3019 disabled if desired.)
3020 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
3022 DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile out‐
3023 put, and suppressed in other formats.
3024 In the CommonMark format, if raw_html is enabled, superscripts, sub‐
3026 scripts, strikeouts and small capitals will be represented as HTML.
3027 Otherwise, plain-text fallbacks will be used. Note that even if
3028 raw_html is disabled, tables will be rendered with HTML syntax if they
3029 cannot use pipe syntax.
3030 Extension: markdown_in_html_blocks
3032 Standard Markdown allows you to include HTML "blocks": blocks of HTML
3033 between balanced tags that are separated from the surrounding text with
3034 blank lines, and start and end at the left margin. Within these
3035 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
3036 ple), * does not signify emphasis.
3037 Pandoc behaves this way when the markdown_strict format is used; but by
3039 default, pandoc interprets material between HTML block tags as Mark‐
3040 down. Thus, for example, pandoc will turn
3041 <table>
3043 <tr>
3044 <td>*one*</td>
3045 <td>[a link](http://google.com)</td>
3046 </tr>
3047 </table>
3048 into
3050 <table>
3052 <tr>
3053 <td><em>one</em></td>
3054 <td><a href="http://google.com">a link</a></td>
3055 </tr>
3056 </table>
3057 whereas Markdown.pl will preserve it as is.
3059 There is one exception to this rule: text between <script> and <style>
3061 tags is not interpreted as Markdown.
3062 This departure from standard Markdown should make it easier to mix
3064 Markdown with HTML block elements. For example, one can surround a
3065 block of Markdown text with <div> tags without preventing it from being
3066 interpreted as Markdown.
3067 Extension: native_divs
3069 Use native pandoc Div blocks for content inside <div> tags. For the
3070 most part this should give the same output as markdown_in_html_blocks,
3071 but it makes it easier to write pandoc filters to manipulate groups of
3072 blocks.
3073 Extension: native_spans
3075 Use native pandoc Span blocks for content inside <span> tags. For the
3076 most part this should give the same output as raw_html, but it makes it
3077 easier to write pandoc filters to manipulate groups of inlines.
3078 Extension: raw_tex
3080 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
3081 be included in a document. Inline TeX commands will be preserved and
3082 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
3083 you can use LaTeX to include BibTeX citations:
3084 This result was proved in \cite{jones.1967}.
3086 Note that in LaTeX environments, like
3088 \begin{tabular}{|l|l|}\hline
3090 Age & Frequency \\ \hline
3091 18--25 & 15 \\
3092 26--35 & 33 \\
3093 36--45 & 22 \\ \hline
3094 \end{tabular}
3095 the material between the begin and end tags will be interpreted as raw
3097 LaTeX, not as Markdown.
3098 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
3100 Emacs Org mode, and ConTeXt.
3101 Generic raw attribute
3103 Extension: raw_attribute
3104 Inline spans and fenced code blocks with a special kind of attribute
3105 will be parsed as raw content with the designated format. For example,
3106 the following produces a raw roff ms block:
3107 ```{=ms}
3109 .MYMACRO
3110 blah blah
3111 ```
3112 And the following produces a raw html inline element:
3114 This is `<a>html</a>`{=html}
3116 This can be useful to insert raw xml into docx documents, e.g. a page‐
3118 break:
3119 ```{=openxml}
3121 <w:p>
3122 <w:r>
3123 <w:br w:type="page"/>
3124 </w:r>
3125 </w:p>
3126 ```
3127 The format name should match the target format name (see -t/--to,
3129 above, for a list, or use pandoc --list-output-formats). Use openxml
3130 for docx output, opendocument for odt output, html5 for epub3 output,
3131 html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output
3132 (depending on what you use for --pdf-engine).
3133 This extension presupposes that the relevant kind of inline code or
3135 fenced code block is enabled. Thus, for example, to use a raw
3136 attribute with a backtick code block, backtick_code_blocks must be
3137 enabled.
3138 The raw attribute cannot be combined with regular attributes.
3140 LaTeX macros
3142 Extension: latex_macros
3143 When this extension is enabled, pandoc will parse LaTeX macro defini‐
3144 tions and apply the resulting macros to all LaTeX math and raw LaTeX.
3145 So, for example, the following will work in all output formats, not
3146 just LaTeX:
3147 \newcommand{\tuple}[1]{\langle #1 \rangle}
3149 $\tuple{a, b, c}$
3151 Note that LaTeX macros will not be applied if they occur inside inside
3153 a raw span or block marked with the raw_attribute extension.
3154 When latex_macros is disabled, the raw LaTeX and math will not have
3156 macros applied. This is usually a better approach when you are target‐
3157 ing LaTeX or PDF.
3158 Whether or not latex_macros is enabled, the macro definitions will
3160 still be passed through as raw LaTeX.
3161 Links
3163 Markdown allows links to be specified in several ways.
3164 Automatic links
3166 If you enclose a URL or email address in pointy brackets, it will
3167 become a link:
3168 <http://google.com>
3170 <sam@green.eggs.ham>
3171 Inline links
3173 An inline link consists of the link text in square brackets, followed
3174 by the URL in parentheses. (Optionally, the URL can be followed by a
3175 link title, in quotes.)
3176 This is an [inline link](/url), and here's [one with
3178 a title](http://fsf.org "click here for a good time!").
3179 There can be no space between the bracketed part and the parenthesized
3181 part. The link text can contain formatting (such as emphasis), but the
3182 title cannot.
3183 Email addresses in inline links are not autodetected, so they have to
3185 be prefixed with mailto:
3186 [Write me!](mailto:sam@green.eggs.ham)
3188 Reference links
3190 An explicit reference link has two parts, the link itself and the link
3191 definition, which may occur elsewhere in the document (either before or
3192 after the link).
3193 The link consists of link text in square brackets, followed by a label
3195 in square brackets. (There cannot be space between the two unless the
3196 spaced_reference_links extension is enabled.) The link definition con‐
3197 sists of the bracketed label, followed by a colon and a space, followed
3198 by the URL, and optionally (after a space) a link title either in
3199 quotes or in parentheses. The label must not be parseable as a cita‐
3200 tion (assuming the citations extension is enabled): citations take
3201 precedence over link labels.
3202 Here are some examples:
3204 [my label 1]: /foo/bar.html "My title, optional"
3206 [my label 2]: /foo
3207 [my label 3]: http://fsf.org (The free software foundation)
3208 [my label 4]: /bar#special 'A title in single quotes'
3209 The URL may optionally be surrounded by angle brackets:
3211 [my label 5]: <http://foo.bar.baz>
3213 The title may go on the next line:
3215 [my label 3]: http://fsf.org
3217 "The free software foundation"
3218 Note that link labels are not case sensitive. So, this will work:
3220 Here is [my link][FOO]
3222 [Foo]: /bar/baz
3224 In an implicit reference link, the second pair of brackets is empty:
3226 See [my website][].
3228 [my website]: http://foo.bar.baz
3230 Note: In Markdown.pl and most other Markdown implementations, reference
3232 link definitions cannot occur in nested constructions such as list
3233 items or block quotes. Pandoc lifts this arbitrary seeming restric‐
3234 tion. So the following is fine in pandoc, though not in most other
3235 implementations:
3236 > My block [quote].
3238 >
3239 > [quote]: /foo
3240 Extension: shortcut_reference_links
3242 In a shortcut reference link, the second pair of brackets may be omit‐
3243 ted entirely:
3244 See [my website].
3246 [my website]: http://foo.bar.baz
3248 Internal links
3250 To link to another section of the same document, use the automatically
3251 generated identifier (see Header identifiers). For example:
3252 See the [Introduction](#introduction).
3254 or
3256 See the [Introduction].
3258 [Introduction]: #introduction
3260 Internal links are currently supported for HTML formats (including HTML
3262 slide shows and EPUB), LaTeX, and ConTeXt.
3263 Images
3265 A link immediately preceded by a ! will be treated as an image. The
3266 link text will be used as the image's alt text:
3267 
3269 ![movie reel]
3271 [movie reel]: movie.gif
3273 Extension: implicit_figures
3275 An image with nonempty alt text, occurring by itself in a paragraph,
3276 will be rendered as a figure with a caption. The image's alt text will
3277 be used as the caption.
3278 
3280 How this is rendered depends on the output format. Some output formats
3282 (e.g. RTF) do not yet support figures. In those formats, you'll just
3283 get an image in a paragraph by itself, with no caption.
3284 If you just want a regular inline image, just make sure it is not the
3286 only thing in the paragraph. One way to do this is to insert a non‐
3287 breaking space after the image:
3288 \
3290 Note that in reveal.js slide shows, an image in a paragraph by itself
3292 that has the stretch class will fill the screen, and the caption and
3293 figure tags will be omitted.
3294 Extension: link_attributes
3296 Attributes can be set on links and images:
3297 An inline {#id .class width=30 height=20px}
3299 and a reference ![image][ref] with attributes.
3300 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
3302 (This syntax is compatible with PHP Markdown Extra when only #id and
3304 .class are used.)
3305 For HTML and EPUB, all attributes except width and height (but includ‐
3307 ing srcset and sizes) are passed through as is. The other writers
3308 ignore attributes that are not supported by their output format.
3309 The width and height attributes on images are treated specially. When
3311 used without a unit, the unit is assumed to be pixels. However, any of
3312 the following unit identifiers can be used: px, cm, mm, in, inch and %.
3313 There must not be any spaces between the number and the unit. For
3314 example:
3315 { width=50% }
3317 · Dimensions are converted to inches for output in page-based formats
3319 like LaTeX. Dimensions are converted to pixels for output in
3320 HTML-like formats. Use the --dpi option to specify the number of
3321 pixels per inch. The default is 96dpi.
3322 · The % unit is generally relative to some available space. For exam‐
3324 ple the above example will render to the following.
3325 · HTML: <img href="file.jpg" style="width: 50%;" />
3327 · LaTeX: \includegraphics[width=0.5\textwidth,height=\tex‐
3329 theight]{file.jpg} (If you're using a custom template, you need to
3330 configure graphicx as in the default template.)
3331 · ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
3333 · Some output formats have a notion of a class (ConTeXt) or a unique
3335 identifier (LaTeX \caption), or both (HTML).
3336 · When no width or height attributes are specified, the fallback is to
3338 look at the image resolution and the dpi metadata embedded in the
3339 image file.
3340 Divs and Spans
3342 Using the native_divs and native_spans extensions (see above), HTML
3343 syntax can be used as part of markdown to create native Div and Span
3344 elements in the pandoc AST (as opposed to raw HTML). However, there is
3345 also nicer syntax available:
3346 Extension: fenced_divs
3348 Allow special fenced syntax for native Div blocks. A Div starts with a
3349 fence containing at least three consecutive colons plus some
3350 attributes. The attributes may optionally be followed by another
3351 string of consecutive colons. The attribute syntax is exactly as in
3352 fenced code blocks (see Extension: fenced_code_attributes). As with
3353 fenced code blocks, one can use either attributes in curly braces or a
3354 single unbraced word, which will be treated as a class name. The Div
3355 ends with another line containing a string of at least three consecu‐
3356 tive colons. The fenced Div should be separated by blank lines from
3357 preceding and following blocks.
3358 Example:
3360 ::::: {#special .sidebar}
3362 Here is a paragraph.
3363 And another.
3365 :::::
3366 Fenced divs can be nested. Opening fences are distinguished because
3368 they must have attributes:
3369 ::: Warning ::::::
3371 This is a warning.
3372 ::: Danger
3374 This is a warning within a warning.
3375 :::
3376 ::::::::::::::::::
3377 Fences without attributes are always closing fences. Unlike with
3379 fenced code blocks, the number of colons in the closing fence need not
3380 match the number in the opening fence. However, it can be helpful for
3381 visual clarity to use fences of different lengths to distinguish nested
3382 divs from their parents.
3383 Extension: bracketed_spans
3385 A bracketed sequence of inlines, as one would use to begin a link, will
3386 be treated as a Span with attributes if it is followed immediately by
3387 attributes:
3388 [This is *some text*]{.class key="val"}
3390 Footnotes
3392 Extension: footnotes
3393 Pandoc's Markdown allows footnotes, using the following syntax:
3394 Here is a footnote reference,[^1] and another.[^longnote]
3396 [^1]: Here is the footnote.
3398 [^longnote]: Here's one with multiple blocks.
3400 Subsequent paragraphs are indented to show that they
3402 belong to the previous footnote.
3403 { some.code }
3405 The whole paragraph can be indented, or just the first
3407 line. In this way, multi-paragraph footnotes work like
3408 multi-paragraph list items.
3409 This paragraph won't be part of the note, because it
3411 isn't indented.
3412 The identifiers in footnote references may not contain spaces, tabs, or
3414 newlines. These identifiers are used only to correlate the footnote
3415 reference with the note itself; in the output, footnotes will be num‐
3416 bered sequentially.
3417 The footnotes themselves need not be placed at the end of the document.
3419 They may appear anywhere except inside other block elements (lists,
3420 block quotes, tables, etc.). Each footnote should be separated from
3421 surrounding content (including other footnotes) by blank lines.
3422 Extension: inline_notes
3424 Inline footnotes are also allowed (though, unlike regular notes, they
3425 cannot contain multiple paragraphs). The syntax is as follows:
3426 Here is an inline note.^[Inlines notes are easier to write, since
3428 you don't have to pick an identifier and move down to type the
3429 note.]
3430 Inline and regular footnotes may be mixed freely.
3432 Citations
3434 Extension: citations
3435 Using an external filter, pandoc-citeproc, pandoc can automatically
3436 generate citations and a bibliography in a number of styles. Basic
3437 usage is
3438 pandoc --filter pandoc-citeproc myinput.txt
3440 In order to use this feature, you will need to specify a bibliography
3442 file using the bibliography metadata field in a YAML metadata section,
3443 or --bibliography command line argument. You can supply multiple
3444 --bibliography arguments or set bibliography metadata field to YAML
3445 array, if you want to use multiple bibliography files. The bibliogra‐
3446 phy may have any of these formats:
3447 Format File extension
3449 ─────────────────────────────
3450 BibLaTeX .bib
3451 BibTeX .bibtex
3452 Copac .copac
3453 CSL JSON .json
3454 CSL YAML .yaml
3455 EndNote .enl
3456 EndNote XML .xml
3457 ISI .wos
3458 MEDLINE .medline
3459 MODS .mods
3460 RIS .ris
3461 Note that .bib can be used with both BibTeX and BibLaTeX files; use
3463 .bibtex to force BibTeX.
3464 Note that pandoc-citeproc --bib2json and pandoc-citeproc --bib2yaml can
3466 produce .json and .yaml files from any of the supported formats.
3467 In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
3469 parses a subset of LaTeX markup; in CSL YAML databases, pandoc Mark‐
3470 down; and in CSL JSON databases, an HTML-like markup:
3471 <i>...</i>
3473 italics
3474 <b>...</b>
3476 bold
3477 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
3479 small capitals
3480 <sub>...</sub>
3482 subscript
3483 <sup>...</sup>
3485 superscript
3486 <span class="nocase">...</span>
3488 prevent a phrase from being capitalized as title case
3489 pandoc-citeproc -j and -y interconvert the CSL JSON and CSL YAML for‐
3491 mats as far as possible.
3492 As an alternative to specifying a bibliography file using --bibliogra‐
3494 phy or the YAML metadata field bibliography, you can include the cita‐
3495 tion data directly in the references field of the document's YAML meta‐
3496 data. The field should contain an array of YAML-encoded references,
3497 for example:
3498 ---
3500 references:
3501 - type: article-journal
3502 id: WatsonCrick1953
3503 author:
3504 - family: Watson
3505 given: J. D.
3506 - family: Crick
3507 given: F. H. C.
3508 issued:
3509 date-parts:
3510 - - 1953
3511 - 4
3512 - 25
3513 title: 'Molecular structure of nucleic acids: a structure for deoxyribose
3514 nucleic acid'
3515 title-short: Molecular structure of nucleic acids
3516 container-title: Nature
3517 volume: 171
3518 issue: 4356
3519 page: 737-738
3520 DOI: 10.1038/171737a0
3521 URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
3522 language: en-GB
3523 ...
3524 (pandoc-citeproc --bib2yaml can produce these from a bibliography file
3526 in one of the supported formats.)
3527 Citations and references can be formatted using any style supported by
3529 the Citation Style Language, listed in the Zotero Style Repository.
3530 These files are specified using the --csl option or the csl metadata
3531 field. By default, pandoc-citeproc will use the Chicago Manual of
3532 Style author-date format. The CSL project provides further information
3533 on finding and editing styles.
3534 To make your citations hyperlinks to the corresponding bibliography
3536 entries, add link-citations: true to your YAML metadata.
3537 Citations go inside square brackets and are separated by semicolons.
3539 Each citation must have a key, composed of '@' + the citation identi‐
3540 fier from the database, and may optionally have a prefix, a locator,
3541 and a suffix. The citation key must begin with a letter, digit, or _,
3542 and may contain alphanumerics, _, and internal punctuation characters
3543 (:.#$%&-+?<>~/). Here are some examples:
3544 Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
3546 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
3548 Blah blah [@smith04; @doe99].
3550 pandoc-citeproc detects locator terms in the CSL locale files. Either
3552 abbreviated or unabbreviated forms are accepted. In the en-US locale,
3553 locator terms can be written in either singular or plural forms, as
3554 book, bk./bks.; chapter, chap./chaps.; column, col./cols.; figure,
3555 fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note,
3556 n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part,
3557 pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.;
3558 volume, vol./vols.; ¶/¶¶; §/§§. If no locator term is used, "page" is
3559 assumed.
3560 pandoc-citeproc will use heuristics to distinguish the locator from the
3562 suffix. In complex cases, the locator can be enclosed in curly braces
3563 (using pandoc-citeproc 0.15 and higher only):
3564 [@smith{ii, A, D-Z}, with a suffix]
3566 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
3567 A minus sign (-) before the @ will suppress mention of the author in
3569 the citation. This can be useful when the author is already mentioned
3570 in the text:
3571 Smith says blah [-@smith04].
3573 You can also write an in-text citation, as follows:
3575 @smith04 says blah.
3577 @smith04 [p. 33] says blah.
3579 If the style calls for a list of works cited, it will be placed in a
3581 div with id refs, if one exists:
3582 ::: #refs
3584 :::
3585 Otherwise, it will be placed at the end of the document. Generation of
3587 the bibliography can be suppressed by setting suppress-bibliography:
3588 true in the YAML metadata.
3589 If you wish the bibliography to have a section header, you can set ref‐
3591 erence-section-title in the metadata, or put the header at the begin‐
3592 ning of the div with id refs (if you are using it) or at the end of
3593 your document:
3594 last paragraph...
3596 # References
3598 The bibliography will be inserted after this header. Note that the
3600 unnumbered class will be added to this header, so that the section will
3601 not be numbered.
3602 If you want to include items in the bibliography without actually cit‐
3604 ing them in the body text, you can define a dummy nocite metadata field
3605 and put the citations there:
3606 ---
3608 nocite: |
3609 @item1, @item2
3610 ...
3611 @item3
3613 In this example, the document will contain a citation for item3 only,
3615 but the bibliography will contain entries for item1, item2, and item3.
3616 It is possible to create a bibliography with all the citations, whether
3618 or not they appear in the document, by using a wildcard:
3619 ---
3621 nocite: |
3622 @*
3623 ...
3624 For LaTeX output, you can also use natbib or biblatex to render the
3626 bibliography. In order to do so, specify bibliography files as out‐
3627 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
3628 tion. Bear in mind that bibliography files have to be in respective
3629 format (either BibTeX or BibLaTeX).
3630 For more information, see the pandoc-citeproc man page.
3632 Non-pandoc extensions
3634 The following Markdown syntax extensions are not enabled by default in
3635 pandoc, but may be enabled by adding +EXTENSION to the format name,
3636 where EXTENSION is the name of the extension. Thus, for example, mark‐
3637 down+hard_line_breaks is Markdown with hard line breaks.
3638 Extension: old_dashes
3640 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: -
3641 before a numeral is an en-dash, and -- is an em-dash. This option only
3642 has an effect if smart is enabled. It is selected automatically for
3643 textile input.
3644 Extension: angle_brackets_escapable
3646 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
3647 vored Markdown but not original Markdown. This is implied by pandoc's
3648 default all_symbols_escapable.
3649 Extension: lists_without_preceding_blankline
3651 Allow a list to occur right after a paragraph, with no intervening
3652 blank space.
3653 Extension: four_space_rule
3655 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
3656 ces indent are needed for list item continuation paragraphs.
3657 Extension: spaced_reference_links
3659 Allow whitespace between the two components of a reference link, for
3660 example,
3661 [foo] [bar].
3663 Extension: hard_line_breaks
3665 Causes all newlines within a paragraph to be interpreted as hard line
3666 breaks instead of spaces.
3667 Extension: ignore_line_breaks
3669 Causes newlines within a paragraph to be ignored, rather than being
3670 treated as spaces or as hard line breaks. This option is intended for
3671 use with East Asian languages where spaces are not used between words,
3672 but text is divided into lines for readability.
3673 Extension: east_asian_line_breaks
3675 Causes newlines within a paragraph to be ignored, rather than being
3676 treated as spaces or as hard line breaks, when they occur between two
3677 East Asian wide characters. This is a better choice than
3678 ignore_line_breaks for texts that include a mix of East Asian wide
3679 characters and other characters.
3680 Extension: emoji
3682 Parses textual emojis like :smile: as Unicode emoticons.
3683 Extension: tex_math_single_backslash
3685 Causes anything between \( and \) to be interpreted as inline TeX math,
3686 and anything between \[ and \] to be interpreted as display TeX math.
3687 Note: a drawback of this extension is that it precludes escaping ( and
3688 [.
3689 Extension: tex_math_double_backslash
3691 Causes anything between \\( and \\) to be interpreted as inline TeX
3692 math, and anything between \\[ and \\] to be interpreted as display TeX
3693 math.
3694 Extension: markdown_attribute
3696 By default, pandoc interprets material inside block-level tags as Mark‐
3697 down. This extension changes the behavior so that Markdown is only
3698 parsed inside block-level tags if the tags have the attribute mark‐
3699 down=1.
3700 Extension: mmd_title_block
3702 Enables a MultiMarkdown style title block at the top of the document,
3703 for example:
3704 Title: My title
3706 Author: John Doe
3707 Date: September 1, 2008
3708 Comment: This is a sample mmd title block, with
3709 a field spanning multiple lines.
3710 See the MultiMarkdown documentation for details. If pandoc_title_block
3712 or yaml_metadata_block is enabled, it will take precedence over
3713 mmd_title_block.
3714 Extension: abbreviations
3716 Parses PHP Markdown Extra abbreviation keys, like
3717 *[HTML]: Hypertext Markup Language
3719 Note that the pandoc document model does not support abbreviations, so
3721 if this extension is enabled, abbreviation keys are simply skipped (as
3722 opposed to being parsed as paragraphs).
3723 Extension: autolink_bare_uris
3725 Makes all absolute URIs into links, even when not surrounded by pointy
3726 braces <...>.
3727 Extension: mmd_link_attributes
3729 Parses multimarkdown style key-value attributes on link and image ref‐
3730 erences. This extension should not be confused with the
3731 link_attributes extension.
3732 This is a reference ![image][ref] with multimarkdown attributes.
3734 [ref]: http://path.to/image "Image title" width=20px height=30px
3736 id=myId class="myClass1 myClass2"
3737 Extension: mmd_header_identifiers
3739 Parses multimarkdown style header identifiers (in square brackets,
3740 after the header but before any trailing #s in an ATX header).
3741 Extension: compact_definition_lists
3743 Activates the definition list syntax of pandoc 1.12.x and earlier.
3744 This syntax differs from the one described above under Definition lists
3745 in several respects:
3746 · No blank line is required between consecutive items of the definition
3748 list.
3749 · To get a "tight" or "compact" list, omit space between consecutive
3751 items; the space between a term and its definition does not affect
3752 anything.
3753 · Lazy wrapping of paragraphs is not allowed: the entire definition
3755 must be indented four spaces.
3756 Markdown variants
3758 In addition to pandoc's extended Markdown, the following Markdown vari‐
3759 ants are supported:
3760 markdown_phpextra (PHP Markdown Extra)
3762 footnotes, pipe_tables, raw_html, markdown_attribute,
3763 fenced_code_blocks, definition_lists, intraword_underscores,
3764 header_attributes, link_attributes, abbreviations, shortcut_ref‐
3765 erence_links, spaced_reference_links.
3766 markdown_github (deprecated GitHub-Flavored Markdown)
3768 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
3769 gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris,
3770 space_in_atx_header, intraword_underscores, strikeout, emoji,
3771 shortcut_reference_links, angle_brackets_escapable, lists_with‐
3772 out_preceding_blankline.
3773 markdown_mmd (MultiMarkdown)
3775 pipe_tables, raw_html, markdown_attribute, mmd_link_attributes,
3776 tex_math_double_backslash, intraword_underscores,
3777 mmd_title_block, footnotes, definition_lists, all_sym‐
3778 bols_escapable, implicit_header_references, auto_identifiers,
3779 mmd_header_identifiers, shortcut_reference_links, implicit_fig‐
3780 ures, superscript, subscript, backtick_code_blocks, spaced_ref‐
3781 erence_links, raw_attribute.
3782 markdown_strict (Markdown.pl)
3784 raw_html, shortcut_reference_links, spaced_reference_links.
3785 We also support commonmark and gfm (GitHub-Flavored Markdown, which is
3787 implemented as a set of extensions on commonmark).
3788 Note, however, that commonmark and gfm have limited support for exten‐
3790 sions. Only those listed below (and smart and raw_tex) will work. The
3791 extensions can, however, all be individually disabled. Also, raw_tex
3792 only affects gfm output, not input.
3793 gfm (GitHub-Flavored Markdown)
3795 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
3796 gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris,
3797 space_in_atx_header, intraword_underscores, strikeout, emoji,
3798 shortcut_reference_links, angle_brackets_escapable, lists_with‐
3799 out_preceding_blankline.
3800
3802 You can use pandoc to produce an HTML + JavaScript slide presentation
3803 that can be viewed via a web browser. There are five ways to do this,
3804 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
3805 duce a PDF slide show using LaTeX beamer, or slides shows in Microsoft
3806 PowerPoint format.
3807 Here's the Markdown source for a simple slide show, habits.txt:
3809 % Habits
3811 % John Doe
3812 % March 22, 2005
3813 # In the morning
3815 ## Getting up
3817 - Turn off alarm
3819 - Get out of bed
3820 ## Breakfast
3822 - Eat eggs
3824 - Drink coffee
3825 # In the evening
3827 ## Dinner
3829 - Eat spaghetti
3831 - Drink wine
3832 ------------------
3834 
3836 ## Going to sleep
3838 - Get in bed
3840 - Count sheep
3841 To produce an HTML/JavaScript slide show, simply type
3843 pandoc -t FORMAT -s habits.txt -o habits.html
3845 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
3847 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
3849 with the -s/--standalone option embeds a link to JavaScript and CSS
3850 files, which are assumed to be available at the relative path
3851 s5/default (for S5), slideous (for Slideous), reveal.js (for
3852 reveal.js), or at the Slidy website at w3.org (for Slidy). (These
3853 paths can be changed by setting the slidy-url, slideous-url,
3854 revealjs-url, or s5-url variables; see Variables for slides, above.)
3855 For DZSlides, the (relatively short) JavaScript and CSS are included in
3856 the file by default.
3857 With all HTML slide formats, the --self-contained option can be used to
3859 produce a single file that contains all of the data necessary to dis‐
3860 play the slide show, including linked scripts, stylesheets, images, and
3861 videos.
3862 To produce a PDF slide show using beamer, type
3864 pandoc -t beamer habits.txt -o habits.pdf
3866 Note that a reveal.js slide show can also be converted to a PDF by
3868 printing it to a file from the browser.
3869 To produce a Powerpoint slide show, type
3871 pandoc habits.txt -o habits.pptx
3873 Structuring the slide show
3875 By default, the slide level is the highest header level in the hierar‐
3876 chy that is followed immediately by content, and not another header,
3877 somewhere in the document. In the example above, level 1 headers are
3878 always followed by level 2 headers, which are followed by content, so 2
3879 is the slide level. This default can be overridden using the
3880 --slide-level option.
3881 The document is carved up into slides according to the following rules:
3883 · A horizontal rule always starts a new slide.
3885 · A header at the slide level always starts a new slide.
3887 · Headers below the slide level in the hierarchy create headers within
3889 a slide.
3890 · Headers above the slide level in the hierarchy create "title slides,"
3892 which just contain the section title and help to break the slide show
3893 into sections.
3894 · Content above the slide level will not appear in the slide show.
3896 · A title page is constructed automatically from the document's title
3898 block, if present. (In the case of beamer, this can be disabled by
3899 commenting out some lines in the default template.)
3900 These rules are designed to support many different styles of slide
3902 show. If you don't care about structuring your slides into sections
3903 and subsections, you can just use level 1 headers for all each slide.
3904 (In that case, level 1 will be the slide level.) But you can also
3905 structure the slide show into sections, as in the example above.
3906 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
3908 layout will be produced, with level 1 headers building horizontally and
3909 level 2 headers building vertically. It is not recommended that you
3910 use deeper nesting of section levels with reveal.js.
3911 Incremental lists
3913 By default, these writers produce lists that display "all at once." If
3914 you want your lists to display incrementally (one item at a time), use
3915 the -i option. If you want a particular list to depart from the
3916 default, put it in a div block with class incremental or nonincremen‐
3917 tal. So, for example, using the fenced div syntax, the following would
3918 be incremental regardless of the document default:
3919 ::: incremental
3921 - Eat spaghetti
3923 - Drink wine
3924 :::
3926 or
3928 ::: nonincremental
3930 - Eat spaghetti
3932 - Drink wine
3933 :::
3935 While using incremental and nonincremental divs are the recommended
3937 method of setting incremental lists on a per-case basis, an older
3938 method is also supported: putting lists inside a blockquote will depart
3939 from the document default (that is, it will display incrementally with‐
3940 out the -i option and all at once with the -i option):
3941 > - Eat spaghetti
3943 > - Drink wine
3944 Both methods allow incremental and nonincremental lists to be mixed in
3946 a single document.
3947 Inserting pauses
3949 You can add "pauses" within a slide by including a paragraph containing
3950 three dots, separated by spaces:
3951 # Slide with a pause
3953 content before the pause
3955 . . .
3957 content after the pause
3959 Styling the slides
3961 You can change the style of HTML slides by putting customized CSS files
3962 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
3963 $DATADIR/slideous (for Slideous), where $DATADIR is the user data
3964 directory (see --data-dir, above). The originals may be found in pan‐
3965 doc's system data directory (generally $CABALDIR/pandoc-VER‐
3966 SION/s5/default). Pandoc will look there for any files it does not
3967 find in the user data directory.
3968 For dzslides, the CSS is included in the HTML file itself, and may be
3970 modified there.
3971 All reveal.js configuration options can be set through variables. For
3973 example, themes can be used by setting the theme variable:
3974 -V theme=moon
3976 Or you can specify a custom stylesheet using the --css option.
3978 To style beamer slides, you can specify a theme, colortheme, fonttheme,
3980 innertheme, and outertheme, using the -V option:
3981 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
3983 Note that header attributes will turn into slide attributes (on a <div>
3985 or <section>) in HTML slide formats, allowing you to style individual
3986 slides. In beamer, the only header attribute that affects slides is
3987 the allowframebreaks class, which sets the allowframebreaks option,
3988 causing multiple slides to be created if the content overfills the
3989 frame. This is recommended especially for bibliographies:
3990 # References {.allowframebreaks}
3992 Speaker notes
3994 Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
3995 You can add notes to your Markdown document thus:
3996 ::: notes
3998 This is my note.
4000 - It can contain Markdown
4002 - like this list
4003 :::
4005 To show the notes window in reveal.js, press s while viewing the pre‐
4007 sentation. Speaker notes in PowerPoint will be available, as usual, in
4008 handouts and presenter view.
4009 Notes are not yet supported for other slide formats, but the notes will
4011 not appear on the slides themselves.
4012 Columns
4014 To put material in side by side columns, you can use a native div con‐
4015 tainer with class columns, containing two or more div containers with
4016 class column and a width attribute:
4017 :::::::::::::: {.columns}
4019 ::: {.column width="40%"}
4020 contents...
4021 :::
4022 ::: {.column width="60%"}
4023 contents...
4024 :::
4025 ::::::::::::::
4026 Frame attributes in beamer
4028 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
4029 in beamer (for example, when using the minted environment). This can
4030 be forced by adding the fragile class to the header introducing the
4031 slide:
4032 # Fragile slide {.fragile}
4034 All of the other frame attributes described in Section 8.1 of the
4036 Beamer User's Guide may also be used: allowdisplaybreaks, allowframe‐
4037 breaks, b, c, t, environment, label, plain, shrink, standout, nofra‐
4038 menumbering.
4039 Background in reveal.js and beamer
4041 Background images can be added to self-contained reveal.js slideshows
4042 and to beamer slideshows.
4043 For the same image on every slide, use the configuration option back‐
4045 ground-image either in the YAML metadata block or as a command-line
4046 variable. (There are no other options in beamer and the rest of this
4047 section concerns reveal.js slideshows.)
4048 For reveal.js, you can instead use the reveal.js-native option paral‐
4050 laxBackgroundImage. You can also set parallaxBackgroundHorizontal and
4051 parallaxBackgroundVertical the same way and must also set parallaxBack‐
4052 groundSize to have your values take effect.
4053 To set an image for a particular reveal.js slide, add {data-back‐
4055 ground-image="/path/to/image"} to the first slide-level header on the
4056 slide (which may even be empty).
4057 In reveal.js's overview mode, the parallaxBackgroundImage will show up
4059 only on the first slide.
4060 Other reveal.js background settings also work on individual slides,
4062 including data-background-size, data-background-repeat, data-back‐
4063 ground-color, data-transition, and data-transition-speed.
4064 See the reveal.js documentation for more details.
4066 For example in reveal.js:
4068 ---
4070 title: My Slideshow
4071 parallaxBackgroundImage: /path/to/my/background_image.png
4072 ---
4073 ## Slide One
4075 Slide 1 has background_image.png as its background.
4077 ## {data-background-image="/path/to/special_image.jpg"}
4079 Slide 2 has a special image for its background, even though the header has no content.
4081
4083 EPUB Metadata
4084 EPUB metadata may be specified using the --epub-metadata option, but if
4085 the source document is Markdown, it is better to use a YAML metadata
4086 block. Here is an example:
4087 ---
4089 title:
4090 - type: main
4091 text: My Book
4092 - type: subtitle
4093 text: An investigation of metadata
4094 creator:
4095 - role: author
4096 text: John Smith
4097 - role: editor
4098 text: Sarah Jones
4099 identifier:
4100 - scheme: DOI
4101 text: doi:10.234234.234/33
4102 publisher: My Press
4103 rights: © 2007 John Smith, CC BY-NC
4104 ibooks:
4105 version: 1.3.4
4106 ...
4107 The following fields are recognized:
4109 identifier
4111 Either a string value or an object with fields text and scheme.
4112 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
4113 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
4114 ISMN-13, ISBN-A, JP, OLCC.
4115 title Either a string value, or an object with fields file-as and
4117 type, or a list of such objects. Valid values for type are
4118 main, subtitle, short, collection, edition, extended.
4119 creator
4121 Either a string value, or an object with fields role, file-as,
4122 and text, or a list of such objects. Valid values for role are
4123 MARC relators, but pandoc will attempt to translate the
4124 human-readable versions (like "author" and "editor") to the
4125 appropriate marc relators.
4126 contributor
4128 Same format as creator.
4129 date A string value in YYYY-MM-DD format. (Only the year is neces‐
4131 sary.) Pandoc will attempt to convert other common date formats.
4132 lang (or legacy: language)
4134 A string value in BCP 47 format. Pandoc will default to the
4135 local language if nothing is specified.
4136 subject
4138 A string value or a list of such values.
4139 description
4141 A string value.
4142 type A string value.
4144 format A string value.
4146 relation
4148 A string value.
4149 coverage
4151 A string value.
4152 rights A string value.
4154 cover-image
4156 A string value (path to cover image).
4157 css (or legacy: stylesheet)
4159 A string value (path to CSS stylesheet).
4160 page-progression-direction
4162 Either ltr or rtl. Specifies the page-progression-direction
4163 attribute for the spine element.
4164 ibooks iBooks-specific metadata, with the following fields:
4166 · version: (string)
4168 · specified-fonts: true|false (default false)
4170 · ipad-orientation-lock: portrait-only|landscape-only
4172 · iphone-orientation-lock: portrait-only|landscape-only
4174 · binding: true|false (default true)
4176 · scroll-axis: vertical|horizontal|default
4178 The epub:type attribute
4180 For epub3 output, you can mark up the header that corresponds to an
4181 EPUB chapter using the epub:type attribute. For example, to set the
4182 attribute to the value prologue, use this markdown:
4183 # My chapter {epub:type=prologue}
4185 Which will result in:
4187 <body epub:type="frontmatter">
4189 <section epub:type="prologue">
4190 <h1>My chapter</h1>
4191 Pandoc will output <body epub:type="bodymatter">, unless you use one of
4193 the following values, in which case either frontmatter or backmatter
4194 will be output.
4195 epub:type of first section epub:type of body
4197 ───────────────────────────────────────────────
4198 prologue frontmatter
4199 abstract frontmatter
4200 acknowledgments frontmatter
4201 copyright-page frontmatter
4202 dedication frontmatter
4203 foreword frontmatter
4204 halftitle, frontmatter
4205 introduction frontmatter
4206 preface frontmatter
4207 seriespage frontmatter
4208 titlepage frontmatter
4209 afterword backmatter
4210 appendix backmatter
4211 colophon backmatter
4212 conclusion backmatter
4213 epigraph backmatter
4214 Linked media
4216 By default, pandoc will download media referenced from any <img>,
4217 <audio>, <video> or <source> element present in the generated EPUB, and
4218 include it in the EPUB container, yielding a completely self-contained
4219 EPUB. If you want to link to external media resources instead, use raw
4220 HTML in your source and add data-external="1" to the tag with the src
4221 attribute. For example:
4222 <audio controls="1">
4224 <source src="http://example.com/music/toccata.mp3"
4225 data-external="1" type="audio/mpeg">
4226 </source>
4227 </audio>
4228
4230 Pandoc will automatically highlight syntax in fenced code blocks that
4231 are marked with a language name. The Haskell library skylighting is
4232 used for highlighting. Currently highlighting is supported only for
4233 HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language
4234 names that pandoc will recognize, type pandoc --list-highlight-lan‐
4235 guages.
4236 The color scheme can be selected using the --highlight-style option.
4238 The default color scheme is pygments, which imitates the default color
4239 scheme used by the Python library pygments (though pygments is not
4240 actually used to do the highlighting). To see a list of highlight
4241 styles, type pandoc --list-highlight-styles.
4242 If you are not satisfied with the predefined styles, you can use
4244 --print-highlight-style to generate a JSON .theme file which can be
4245 modified and used as the argument to --highlight-style. To get a JSON
4246 version of the pygments style, for example:
4247 pandoc --print-highlight-style pygments > my.theme
4249 Then edit my.theme and use it like this:
4251 pandoc --highlight-style my.theme
4253 If you are not satisfied with the built-in highlighting, or you want
4255 highlight a language that isn't supported, you can use the --syn‐
4256 tax-definition option to load a KDE-style XML syntax definition file.
4257 Before writing your own, have a look at KDE's repository of syntax def‐
4258 initions.
4259 To disable highlighting, use the --no-highlight option.
4261
4263 Input
4264 The docx reader, by default, only reads those styles that it can con‐
4265 vert into pandoc elements, either by direct conversion or interpreting
4266 the derivation of the input document's styles.
4267 By enabling the styles extension in the docx reader (-f docx+styles),
4269 you can produce output that maintains the styles of the input document,
4270 using the custom-style class. Paragraph styles are interpreted as
4271 divs, while character styles are interpreted as spans.
4272 For example, using the custom-style-reference.docx file in the test
4274 directory, we have the following different outputs:
4275 Without the +styles extension:
4277 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
4279 This is some text.
4280 This is text with an *emphasized* text style. And this is text with a
4282 **strengthened** text style.
4283 > Here is a styled paragraph that inherits from Block Text.
4285 And with the extension:
4287 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
4289 ::: {custom-style="FirstParagraph"}
4291 This is some text.
4292 :::
4293 ::: {custom-style="BodyText"}
4295 This is text with an [emphasized]{custom-style="Emphatic"} text style.
4296 And this is text with a [strengthened]{custom-style="Strengthened"}
4297 text style.
4298 :::
4299 ::: {custom-style="MyBlockStyle"}
4301 > Here is a styled paragraph that inherits from Block Text.
4302 :::
4303 With these custom styles, you can use your input document as a refer‐
4305 ence-doc while creating docx output (see below), and maintain the same
4306 styles in your input and output files.
4307 Output
4309 By default, pandoc's docx output applies a predefined set of styles for
4310 blocks such as paragraphs and block quotes, and uses largely default
4311 formatting (italics, bold) for inlines. This will work for most pur‐
4312 poses, especially alongside a reference.docx file. However, if you
4313 need to apply your own styles to blocks, or match a preexisting set of
4314 styles, pandoc allows you to define custom styles for blocks and text
4315 using divs and spans, respectively.
4316 If you define a div or span with the attribute custom-style, pandoc
4318 will apply your specified style to the contained elements. So, for
4319 example using the bracketed_spans syntax,
4320 [Get out]{custom-style="Emphatically"}, he said.
4322 would produce a docx file with "Get out" styled with character style
4324 Emphatically. Similarly, using the fenced_divs syntax,
4325 Dickinson starts the poem simply:
4327 ::: {custom-style="Poetry"}
4329 | A Bird came down the Walk---
4330 | He did not know I saw---
4331 :::
4332 would style the two contained lines with the Poetry paragraph style.
4334 If the styles are not yet in your reference.docx, they will be defined
4336 in the output file as inheriting from normal text. If they are already
4337 defined, pandoc will not alter the definition.
4338 This feature allows for greatest customization in conjunction with pan‐
4340 doc filters. If you want all paragraphs after block quotes to be
4341 indented, you can write a filter to apply the styles necessary. If you
4342 want all italics to be transformed to the Emphasis character style
4343 (perhaps to change their color), you can write a filter which will
4344 transform all italicized inlines to inlines within an Emphasis cus‐
4345 tom-style span.
4346
4348 Pandoc can be extended with custom writers written in lua. (Pandoc
4349 includes a lua interpreter, so lua need not be installed separately.)
4350 To use a custom writer, simply specify the path to the lua script in
4352 place of the output format. For example:
4353 pandoc -t data/sample.lua
4355 Creating a custom writer requires writing a lua function for each pos‐
4357 sible element in a pandoc document. To get a documented example which
4358 you can modify according to your needs, do
4359 pandoc --print-default-data-file sample.lua
4361
4363 If you use pandoc to convert user-contributed content in a web applica‐
4364 tion, here are some things to keep in mind:
4365 1. Although pandoc itself will not create or modify any files other
4367 than those you explicitly ask it create (with the exception of tem‐
4368 porary files used in producing PDFs), a filter or custom writer
4369 could in principle do anything on your file system. Please audit
4370 filters and custom writers very carefully before using them.
4371 2. If your application uses pandoc as a Haskell library (rather than
4373 shelling out to the executable), it is possible to use it in a mode
4374 that fully isolates pandoc from your file system, by running the
4375 pandoc operations in the PandocPure monad. See the document Using
4376 the pandoc API for more details.
4377 3. Pandoc's parsers can exhibit pathological performance on some corner
4379 cases. It is wise to put any pandoc operations under a timeout, to
4380 avoid DOS attacks that exploit these issues. If you are using the
4381 pandoc executable, you can add the command line options +RTS -M512M
4382 -RTS (for example) to limit the heap size to 512MB.
4383 4. The HTML generated by pandoc is not guaranteed to be safe. If
4385 raw_html is enabled for the Markdown input, users can inject arbi‐
4386 trary HTML. Even if raw_html is disabled, users can include danger‐
4387 ous content in attributes for headers, spans, and code blocks. To
4388 be safe, you should run all the generated HTML through an HTML sani‐
4389 tizer.
4390
4392 Copyright 2006-2017 John MacFarlane (jgm@berkeley.edu). Released under
4393 the GPL, version 2 or greater. This software carries no warranty of
4394 any kind. (See COPYRIGHT for full copyright and warranty notices.) For
4395 a full list of contributors, see the file AUTHORS.md in the pandoc
4396 source code.
4397 The Pandoc source code and all documentation may be downloaded from
4399 <http://pandoc.org>.
4400pandoc 2.5 November 25, 2018 PANDOC(1)