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
116 -t ms to the command line (-t html defaults to --pdf-engine=wkhtml‐
117 topdf).
118 PDF output can be controlled using variables for LaTeX (if LaTeX is
120 used) and variables for ConTeXt (if ConTeXt is used). When using an
121 HTML/CSS-to-PDF-engine, --css affects the output. If wkhtmltopdf is
122 used, then the variables margin-left, margin-right, margin-top, mar‐
123 gin-bottom, footer-html, header-html and papersize will affect the out‐
124 put.
125 To debug the PDF creation, it can be useful to look at the intermediate
127 representation: instead of -o test.pdf, use for example -s -o test.tex
128 to output the generated LaTeX. You can then test it with pdfla‐
129 tex test.tex.
130 When using LaTeX, the following packages need to be available (they are
132 included with all recent versions of TeX Live): amsfonts, amsmath, lm,
133 unicode-math, ifxetex, ifluatex, listings (if the --listings option is
134 used), fancyvrb, longtable, booktabs, graphicx and grffile (if the doc‐
135 ument contains images), hyperref, xcolor (with colorlinks), ulem, geom‐
136 etry (with the geometry variable set), setspace (with linestretch), and
137 babel (with lang). The use of xelatex or lualatex as the LaTeX engine
138 requires fontspec. xelatex uses polyglossia (with lang), xecjk, and
139 bidi (with the dir variable set). If the mathspec variable is set,
140 xelatex will use mathspec instead of unicode-math. The upquote and
141 microtype packages are used if available, and csquotes will be used for
142 typography if added to the template or included in any header file.
143 The natbib, biblatex, bibtex, and biber packages can optionally be used
144 for citation rendering.
145 Reading from the Web
147 Instead of an input file, an absolute URI may be given. In this case
148 pandoc will fetch the content using HTTP:
149 pandoc -f html -t markdown http://www.fsf.org
151 It is possible to supply a custom User-Agent string or other header
153 when requesting a document from a URL:
154 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
156 http://www.fsf.org
157
159 General options
160 -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
161 Specify input format. FORMAT can be:
162 · commonmark (CommonMark Markdown)
164 · creole (Creole 1.0)
166 · docbook (DocBook)
168 · docx (Word docx)
170 · epub (EPUB)
172 · fb2 (FictionBook2 e-book)
174 · gfm (GitHub-Flavored Markdown), or markdown_github, which pro‐
176 vides deprecated and less accurate support for Github-Flavored
177 Markdown; please use gfm instead, unless you need to use
178 extensions other than smart.
179 · haddock (Haddock markup)
181 · html (HTML)
183 · jats (JATS XML)
185 · json (JSON version of native AST)
187 · latex (LaTeX)
189 · markdown (Pandoc's Markdown)
191 · markdown_mmd (MultiMarkdown)
193 · markdown_phpextra (PHP Markdown Extra)
195 · markdown_strict (original unextended Markdown)
197 · mediawiki (MediaWiki markup)
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 markdown_github, which pro‐
253 vides deprecated and less accurate support for Github-Flavored
254 Markdown; please use gfm instead, unless you use extensions
255 that do not work with gfm.
256 · haddock (Haddock markup)
258 · html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
260 · html4 (XHTML 1.0 Transitional)
262 · icml (InDesign ICML)
264 · jats (JATS XML)
266 · json (JSON version of native AST)
268 · latex (LaTeX)
270 · man (groff man)
272 · markdown (Pandoc's Markdown)
274 · markdown_mmd (MultiMarkdown)
276 · markdown_phpextra (PHP Markdown Extra)
278 · markdown_strict (original unextended Markdown)
280 · mediawiki (MediaWiki markup)
282 · ms (groff ms)
284 · muse (Muse),
286 · native (native Haskell),
288 · odt (OpenOffice text document)
290 · opml (OPML)
292 · opendocument (OpenDocument)
294 · org (Emacs Org mode)
296 · plain (plain text),
298 · pptx (PowerPoint slide show)
300 · rst (reStructuredText)
302 · rtf (Rich Text Format)
304 · texinfo (GNU Texinfo)
306 · textile (Textile)
308 · slideous (Slideous HTML and JavaScript slide show)
310 · slidy (Slidy HTML and JavaScript slide show)
312 · dzslides (DZSlides HTML5 + JavaScript slide show),
314 · revealjs (reveal.js HTML5 + JavaScript slide show)
316 · s5 (S5 HTML and JavaScript slide show)
318 · tei (TEI Simple)
320 · zimwiki (ZimWiki markup)
322 · the path of a custom lua writer, see Custom writers below
324 Note that odt, docx, and epub output will not be directed to
326 stdout unless forced with -o -.
327 Extensions can be individually enabled or disabled by appending
329 +EXTENSION or -EXTENSION to the format name. See Extensions
330 below, for a list of extensions and their names. See
331 --list-output-formats and --list-extensions, below.
332 -o FILE, --output=FILE
334 Write output to FILE instead of stdout. If FILE is -, output
335 will go to stdout, even if a non-textual format (docx, odt,
336 epub2, epub3) is specified.
337 --data-dir=DIRECTORY
339 Specify the user data directory to search for pandoc data files.
340 If this option is not specified, the default user data directory
341 will be used. This is, in UNIX:
342 $HOME/.pandoc
344 in Windows XP:
346 C:\Documents And Settings\USERNAME\Application Data\pandoc
348 and in Windows Vista or later:
350 C:\Users\USERNAME\AppData\Roaming\pandoc
352 You can find the default user data directory on your system by
354 looking at the output of pandoc --version. A reference.odt,
355 reference.docx, epub.css, templates, slidy, slideous, or s5
356 directory placed in this directory will override pandoc's normal
357 defaults.
358 --bash-completion
360 Generate a bash completion script. To enable bash completion
361 with pandoc, add this to your .bashrc:
362 eval "$(pandoc --bash-completion)"
364 --verbose
366 Give verbose debugging output. Currently this only has an
367 effect with PDF output.
368 --quiet
370 Suppress warning messages.
371 --fail-if-warnings
373 Exit with error status if there are any warnings.
374 --log=FILE
376 Write log messages in machine-readable JSON format to FILE. All
377 messages above DEBUG level will be written, regardless of ver‐
378 bosity settings (--verbose, --quiet).
379 --list-input-formats
381 List supported input formats, one per line.
382 --list-output-formats
384 List supported output formats, one per line.
385 --list-extensions[=FORMAT]
387 List supported extensions, one per line, preceded by a + or -
388 indicating whether it is enabled by default in FORMAT. If FOR‐
389 MAT is not specified, defaults for pandoc's Markdown are given.
390 --list-highlight-languages
392 List supported languages for syntax highlighting, one per line.
393 --list-highlight-styles
395 List supported styles for syntax highlighting, one per line.
396 See --highlight-style.
397 -v, --version
399 Print version.
400 -h, --help
402 Show usage message.
403 Reader options
405 --base-header-level=NUMBER
406 Specify the base level for headers (defaults to 1).
407 --strip-empty-paragraphs
409 Deprecated. Use the +empty_paragraphs extension instead. Ignore
410 paragraphs with no content. This option is useful for convert‐
411 ing word processing documents where users have used empty para‐
412 graphs to create inter-paragraph space.
413 --indented-code-classes=CLASSES
415 Specify classes to use for indented code blocks--for example,
416 perl,numberLines or haskell. Multiple classes may be separated
417 by spaces or commas.
418 --default-image-extension=EXTENSION
420 Specify a default extension to use when image paths/URLs have no
421 extension. This allows you to use the same source for formats
422 that require different kinds of images. Currently this option
423 only affects the Markdown and LaTeX readers.
424 --file-scope
426 Parse each file individually before combining for multifile doc‐
427 uments. This will allow footnotes in different files with the
428 same identifiers to work as expected. If this option is set,
429 footnotes and links will not work across files. Reading binary
430 files (docx, odt, epub) implies --file-scope.
431 --filter=PROGRAM
433 Specify an executable to be used as a filter transforming the
434 pandoc AST after the input is parsed and before the output is
435 written. The executable should read JSON from stdin and write
436 JSON to stdout. The JSON must be formatted like pandoc's own
437 JSON input and output. The name of the output format will be
438 passed to the filter as the first argument. Hence,
439 pandoc --filter ./caps.py -t latex
441 is equivalent to
443 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
445 The latter form may be useful for debugging filters.
447 Filters may be written in any language. Text.Pandoc.JSON
449 exports toJSONFilter to facilitate writing filters in Haskell.
450 Those who would prefer to write filters in python can use the
451 module pandocfilters, installable from PyPI. There are also
452 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
453 In order of preference, pandoc will look for filters in
455 1. a specified full or relative path (executable or non-exe‐
457 cutable)
458 2. $DATADIR/filters (executable or non-executable) where
460 $DATADIR is the user data directory (see --data-dir, above).
461 3. $PATH (executable only)
463 Filters and lua-filters are applied in the order specified on
465 the command line.
466 --lua-filter=SCRIPT
468 Transform the document in a similar fashion as JSON filters (see
469 --filter), but use pandoc's build-in lua filtering system. The
470 given lua script is expected to return a list of lua filters
471 which will be applied in order. Each lua filter must contain
472 element-transforming functions indexed by the name of the AST
473 element on which the filter function should be applied.
474 The pandoc lua module provides helper functions for element cre‐
476 ation. It is always loaded into the script's lua environment.
477 The following is an example lua script for macro-expansion:
479 function expand_hello_world(inline)
481 if inline.c == '{{helloworld}}' then
482 return pandoc.Emph{ pandoc.Str "Hello, World" }
483 else
484 return inline
485 end
486 end
487 return {{Str = expand_hello_world}}
489 In order of preference, pandoc will look for lua filters in
491 1. a specified full or relative path (executable or non-exe‐
493 cutable)
494 2. $DATADIR/filters (executable or non-executable) where
496 $DATADIR is the user data directory (see --data-dir, above).
497 -M KEY[=VAL], --metadata=KEY[:VAL]
499 Set the metadata field KEY to the value VAL. A value specified
500 on the command line overrides a value specified in the document
501 using YAML metadata blocks. Values will be parsed as YAML bool‐
502 ean or string values. If no value is specified, the value will
503 be treated as Boolean true. Like --variable, --metadata causes
504 template variables to be set. But unlike --variable, --metadata
505 affects the metadata of the underlying document (which is acces‐
506 sible from filters and may be printed in some output formats)
507 and metadata values will be escaped when inserted into the tem‐
508 plate.
509 -p, --preserve-tabs
511 Preserve tabs instead of converting them to spaces (the
512 default). Note that this will only affect tabs in literal code
513 spans and code blocks; tabs in regular text will be treated as
514 spaces.
515 --tab-stop=NUMBER
517 Specify the number of spaces per tab (default is 4).
518 --track-changes=accept|reject|all
520 Specifies what to do with insertions, deletions, and comments
521 produced by the MS Word "Track Changes" feature. accept (the
522 default), inserts all insertions, and ignores all deletions.
523 reject inserts all deletions and ignores insertions. Both
524 accept and reject ignore comments. all puts in insertions,
525 deletions, and comments, wrapped in spans with insertion, dele‐
526 tion, comment-start, and comment-end classes, respectively. The
527 author and time of change is included. all is useful for
528 scripting: only accepting changes from a certain reviewer, say,
529 or before a certain date. If a paragraph is inserted or
530 deleted, track-changes=all produces a span with the class para‐
531 graph-insertion/paragraph-deletion before the affected paragraph
532 break. This option only affects the docx reader.
533 --extract-media=DIR
535 Extract images and other media contained in or linked from the
536 source document to the path DIR, creating it if necessary, and
537 adjust the images references in the document so they point to
538 the extracted files. If the source format is a binary container
539 (docx, epub, or odt), the media is extracted from the container
540 and the original filenames are used. Otherwise the media is
541 read from the file system or downloaded, and new filenames are
542 constructed based on SHA1 hashes of the contents.
543 --abbreviations=FILE
545 Specifies a custom abbreviations file, with abbreviations one to
546 a line. If this option is not specified, pandoc will read the
547 data file abbreviations from the user data directory or fall
548 back on a system default. To see the system default, use pan‐
549 doc --print-default-data-file=abbreviations. The only use pan‐
550 doc makes of this list is in the Markdown reader. Strings end‐
551 ing in a period that are found in this list will be followed by
552 a nonbreaking space, so that the period will not produce sen‐
553 tence-ending space in formats like LaTeX.
554 General writer options
556 -s, --standalone
557 Produce output with an appropriate header and footer (e.g. a
558 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
559 option is set automatically for pdf, epub, epub3, fb2, docx, and
560 odt output. For native output, this option causes metadata to
561 be included; otherwise, metadata is suppressed.
562 --template=FILE
564 Use FILE as a custom template for the generated document.
565 Implies --standalone. See Templates, below, for a description
566 of template syntax. If no extension is specified, an extension
567 corresponding to the writer will be added, so that --tem‐
568 plate=special looks for special.html for HTML output. If the
569 template is not found, pandoc will search for it in the tem‐
570 plates subdirectory of the user data directory (see --data-dir).
571 If this option is not used, a default template appropriate for
572 the output format will be used (see -D/--print-default-tem‐
573 plate).
574 -V KEY[=VAL], --variable=KEY[:VAL]
576 Set the template variable KEY to the value VAL when rendering
577 the document in standalone mode. This is generally only useful
578 when the --template option is used to specify a custom template,
579 since pandoc automatically sets the variables used in the
580 default templates. If no VAL is specified, the key will be
581 given the value true.
582 -D FORMAT, --print-default-template=FORMAT
584 Print the system default template for an output FORMAT. (See -t
585 for a list of possible FORMATs.) Templates in the user data
586 directory are ignored.
587 --print-default-data-file=FILE
589 Print a system default data file. Files in the user data direc‐
590 tory are ignored.
591 --eol=crlf|lf|native
593 Manually specify line endings: crlf (Windows), lf (mac‐
594 OS/Linux/UNIX), or native (line endings appropriate to the OS on
595 which pandoc is being run). The default is native.
596 --dpi=NUMBER
598 Specify the dpi (dots per inch) value for conversion from pixels
599 to inch/centimeters and vice versa. The default is 96dpi.
600 Technically, the correct term would be ppi (pixels per inch).
601 --wrap=auto|none|preserve
603 Determine how text is wrapped in the output (the source code,
604 not the rendered version). With auto (the default), pandoc will
605 attempt to wrap lines to the column width specified by --columns
606 (default 72). With none, pandoc will not wrap lines at all.
607 With preserve, pandoc will attempt to preserve the wrapping from
608 the source document (that is, where there are nonsemantic new‐
609 lines in the source, there will be nonsemantic newlines in the
610 output as well). Automatic wrapping does not currently work in
611 HTML output.
612 --columns=NUMBER
614 Specify length of lines in characters. This affects text wrap‐
615 ping in the generated source code (see --wrap). It also affects
616 calculation of column widths for plain text tables (see Tables
617 below).
618 --toc, --table-of-contents
620 Include an automatically generated table of contents (or, in the
621 case of latex, context, docx, odt, opendocument, rst, or ms, an
622 instruction to create one) in the output document. This option
623 has no effect on man, docbook4, docbook5, or jats output.
624 --toc-depth=NUMBER
626 Specify the number of section levels to include in the table of
627 contents. The default is 3 (which means that level 1, 2, and 3
628 headers will be listed in the contents).
629 --strip-comments
631 Strip out HTML comments in the Markdown or Textile source,
632 rather than passing them on to Markdown, Textile or HTML output
633 as raw HTML. This does not apply to HTML comments inside raw
634 HTML blocks when the markdown_in_html_blocks extension is not
635 set.
636 --no-highlight
638 Disables syntax highlighting for code blocks and inlines, even
639 when a language attribute is given.
640 --highlight-style=STYLE|FILE
642 Specifies the coloring style to be used in highlighted source
643 code. Options are pygments (the default), kate, monochrome,
644 breezeDark, espresso, zenburn, haddock, and tango. For more
645 information on syntax highlighting in pandoc, see Syntax high‐
646 lighting, below. See also --list-highlight-styles.
647 Instead of a STYLE name, a JSON file with extension .theme may
649 be supplied. This will be parsed as a KDE syntax highlighting
650 theme and (if valid) used as the highlighting style.
651 To generate the JSON version of an existing style, use
653 --print-highlight-style.
654 --print-highlight-style=STYLE|FILE
656 Prints a JSON version of a highlighting style, which can be mod‐
657 ified, saved with a .theme extension, and used with --high‐
658 light-style.
659 --syntax-definition=FILE
661 Instructs pandoc to load a KDE XML syntax definition file, which
662 will be used for syntax highlighting of appropriately marked
663 code blocks. This can be used to add support for new languages
664 or to use altered syntax definitions for existing languages.
665 -H FILE, --include-in-header=FILE
667 Include contents of FILE, verbatim, at the end of the header.
668 This can be used, for example, to include special CSS or
669 JavaScript in HTML documents. This option can be used repeat‐
670 edly to include multiple files in the header. They will be
671 included in the order specified. Implies --standalone.
672 -B FILE, --include-before-body=FILE
674 Include contents of FILE, verbatim, at the beginning of the doc‐
675 ument body (e.g. after the <body> tag in HTML, or the
676 \begin{document} command in LaTeX). This can be used to include
677 navigation bars or banners in HTML documents. This option can
678 be used repeatedly to include multiple files. They will be
679 included in the order specified. Implies --standalone.
680 -A FILE, --include-after-body=FILE
682 Include contents of FILE, verbatim, at the end of the document
683 body (before the </body> tag in HTML, or the \end{document} com‐
684 mand in LaTeX). This option can be used repeatedly to include
685 multiple files. They will be included in the order specified.
686 Implies --standalone.
687 --resource-path=SEARCHPATH
689 List of paths to search for images and other resources. The
690 paths should be separated by : on Linux, UNIX, and macOS sys‐
691 tems, and by ; on Windows. If --resource-path is not specified,
692 the default resource path is the working directory. Note that,
693 if --resource-path is specified, the working directory must be
694 explicitly listed or it will not be searched. For example:
695 --resource-path=.:test will search the working directory and the
696 test subdirectory, in that order.
697 --request-header=NAME:VAL
699 Set the request header NAME to the value VAL when making HTTP
700 requests (for example, when a URL is given on the command line,
701 or when resources used in a document must be downloaded).
702 Options affecting specific writers
704 --self-contained
705 Produce a standalone HTML file with no external dependencies,
706 using data: URIs to incorporate the contents of linked scripts,
707 stylesheets, images, and videos. Implies --standalone. The
708 resulting file should be "self-contained," in the sense that it
709 needs no external files and no net access to be displayed prop‐
710 erly by a browser. This option works only with HTML output for‐
711 mats, including html4, html5, html+lhs, html5+lhs, s5, slidy,
712 slideous, dzslides, and revealjs. Scripts, images, and
713 stylesheets at absolute URLs will be downloaded; those at rela‐
714 tive URLs will be sought relative to the working directory (if
715 the first source file is local) or relative to the base URL (if
716 the first source file is remote). Elements with the attribute
717 data-external="1" will be left alone; the documents they link to
718 will not be incorporated in the document. Limitation: resources
719 that are loaded dynamically through JavaScript cannot be incor‐
720 porated; as a result, --self-contained does not work with
721 --mathjax, and some advanced features (e.g. zoom or speaker
722 notes) may not work in an offline "self-contained" reveal.js
723 slide show.
724 --html-q-tags
726 Use <q> tags for quotes in HTML.
727 --ascii
729 Use only ASCII characters in output. Currently supported for
730 XML and HTML formats (which use numerical entities instead of
731 UTF-8 when this option is selected) and for groff ms and man
732 (which use hexadecimal escapes).
733 --reference-links
735 Use reference-style links, rather than inline links, in writing
736 Markdown or reStructuredText. By default inline links are used.
737 The placement of link references is affected by the --refer‐
738 ence-location option.
739 --reference-location = block|section|document
741 Specify whether footnotes (and references, if reference-links is
742 set) are placed at the end of the current (top-level) block, the
743 current section, or the document. The default is document.
744 Currently only affects the markdown writer.
745 --atx-headers
747 Use ATX-style headers in Markdown and AsciiDoc output. The
748 default is to use setext-style headers for levels 1-2, and then
749 ATX headers. (Note: for gfm output, ATX headers are always
750 used.)
751 --top-level-division=[default|section|chapter|part]
753 Treat top-level headers as the given division type in LaTeX,
754 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
755 chapter, then section; all headers are shifted such that the
756 top-level header becomes the specified type. The default behav‐
757 ior is to determine the best division type via heuristics:
758 unless other conditions apply, section is chosen. When the
759 LaTeX document class is set to report, book, or memoir (unless
760 the article option is specified), chapter is implied as the set‐
761 ting for this option. If beamer is the output format, specify‐
762 ing either chapter or part will cause top-level headers to
763 become \part{..}, while second-level headers remain as their
764 default type.
765 -N, --number-sections
767 Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
768 By default, sections are not numbered. Sections with class
769 unnumbered will never be numbered, even if --number-sections is
770 specified.
771 --number-offset=NUMBER[,NUMBER,...]
773 Offset for section headings in HTML output (ignored in other
774 output formats). The first number is added to the section num‐
775 ber for top-level headers, the second for second-level headers,
776 and so on. So, for example, if you want the first top-level
777 header in your document to be numbered "6", specify --num‐
778 ber-offset=5. If your document starts with a level-2 header
779 which you want to be numbered "1.5", specify --number-off‐
780 set=1,4. Offsets are 0 by default. Implies --number-sections.
781 --listings
783 Use the listings package for LaTeX code blocks
784 -i, --incremental
786 Make list items in slide shows display incrementally (one by
787 one). The default is for lists to be displayed all at once.
788 --slide-level=NUMBER
790 Specifies that headers with the specified level create slides
791 (for beamer, s5, slidy, slideous, dzslides). Headers above this
792 level in the hierarchy are used to divide the slide show into
793 sections; headers below this level create subheads within a
794 slide. Note that content that is not contained under
795 slide-level headers will not appear in the slide show. The
796 default is to set the slide level based on the contents of the
797 document; see Structuring the slide show.
798 --section-divs
800 Wrap sections in <section> tags (or <div> tags for html4), and
801 attach identifiers to the enclosing <section> (or <div>) rather
802 than the header itself. See Header identifiers, below.
803 --email-obfuscation=none|javascript|references
805 Specify a method for obfuscating mailto: links in HTML docu‐
806 ments. none leaves mailto: links as they are. javascript
807 obfuscates them using JavaScript. references obfuscates them by
808 printing their letters as decimal or hexadecimal character ref‐
809 erences. The default is none.
810 --id-prefix=STRING
812 Specify a prefix to be added to all identifiers and internal
813 links in HTML and DocBook output, and to footnote numbers in
814 Markdown and Haddock output. This is useful for preventing
815 duplicate identifiers when generating fragments to be included
816 in other pages.
817 -T STRING, --title-prefix=STRING
819 Specify STRING as a prefix at the beginning of the title that
820 appears in the HTML header (but not in the title as it appears
821 at the beginning of the HTML body). Implies --standalone.
822 -c URL, --css=URL
824 Link to a CSS style sheet. This option can be used repeatedly
825 to include multiple files. They will be included in the order
826 specified.
827 A stylesheet is required for generating EPUB. If none is pro‐
829 vided using this option (or the stylesheet metadata field), pan‐
830 doc will look for a file epub.css in the user data directory
831 (see --data-dir). If it is not found there, sensible defaults
832 will be used.
833 --reference-doc=FILE
835 Use the specified file as a style reference in producing a docx
836 or ODT file.
837 Docx For best results, the reference docx should be a modified
839 version of a docx file produced using pandoc. The con‐
840 tents of the reference docx are ignored, but its
841 stylesheets and document properties (including margins,
842 page size, header, and footer) are used in the new docx.
843 If no reference docx is specified on the command line,
844 pandoc will look for a file reference.docx in the user
845 data directory (see --data-dir). If this is not found
846 either, sensible defaults will be used.
847 To produce a custom reference.docx, first get a copy of
849 the default reference.docx: pan‐
850 doc --print-default-data-file reference.docx > cus‐
851 tom-reference.docx. Then open custom-reference.docx in
852 Word, modify the styles as you wish, and save the file.
853 For best results, do not make changes to this file other
854 than modifying the styles used by pandoc: [paragraph]
855 Normal, Body Text, First Paragraph, Compact, Title, Sub‐
856 title, Author, Date, Abstract, Bibliography, Heading 1,
857 Heading 2, Heading 3, Heading 4, Heading 5, Heading 6,
858 Heading 7, Heading 8, Heading 9, Block Text, Footnote
859 Text, Definition Term, Definition, Caption, Table Cap‐
860 tion, Image Caption, Figure, Captioned Figure, TOC Head‐
861 ing; [character] Default Paragraph Font, Body Text Char,
862 Verbatim Char, Footnote Reference, Hyperlink; [table] Ta‐
863 ble.
864 ODT For best results, the reference ODT should be a modified
866 version of an ODT produced using pandoc. The contents of
867 the reference ODT are ignored, but its stylesheets are
868 used in the new ODT. If no reference ODT is specified on
869 the command line, pandoc will look for a file refer‐
870 ence.odt in the user data directory (see --data-dir). If
871 this is not found either, sensible defaults will be used.
872 To produce a custom reference.odt, first get a copy of
874 the default reference.odt: pan‐
875 doc --print-default-data-file reference.odt > custom-ref‐
876 erence.odt. Then open custom-reference.odt in LibreOf‐
877 fice, modify the styles as you wish, and save the file.
878 PowerPoint
880 Any template included with a recent install of Microsoft
881 PowerPoint (either with .pptx or .potx extension) should
882 work, as will most templates derived from these.
883 The specific requirement is that the template should con‐
885 tain the following four layouts as its first four lay‐
886 outs:
887 1. Title Slide
889 2. Title and Content
891 3. Section Header
893 4. Two Content
895 All templates included with a recent version of MS Power‐
897 Point will fit these criteria. (You can click on Layout
898 under the Home menu to check.)
899 You can also modify the default reference.pptx: first run
901 pandoc --print-default-data-file reference.pptx > cus‐
902 tom-reference.pptx, and then modify custom-reference.pptx
903 in MS PowerPoint (pandoc will use the first four layout
904 slides, as mentioned above).
905 --epub-cover-image=FILE
907 Use the specified image as the EPUB cover. It is recommended
908 that the image be less than 1000px in width and height. Note
909 that in a Markdown source document you can also specify
910 cover-image in a YAML metadata block (see EPUB Metadata, below).
911 --epub-metadata=FILE
913 Look in the specified XML file for metadata for the EPUB. The
914 file should contain a series of Dublin Core elements. For exam‐
915 ple:
916 <dc:rights>Creative Commons</dc:rights>
918 <dc:language>es-AR</dc:language>
919 By default, pandoc will include the following metadata elements:
921 <dc:title> (from the document title), <dc:creator> (from the
922 document authors), <dc:date> (from the document date, which
923 should be in ISO 8601 format), <dc:language> (from the lang
924 variable, or, if is not set, the locale), and <dc:identi‐
925 fier id="BookId"> (a randomly generated UUID). Any of these may
926 be overridden by elements in the metadata file.
927 Note: if the source document is Markdown, a YAML metadata block
929 in the document can be used instead. See below under EPUB Meta‐
930 data.
931 --epub-embed-font=FILE
933 Embed the specified font in the EPUB. This option can be
934 repeated to embed multiple fonts. Wildcards can also be used:
935 for example, DejaVuSans-*.ttf. However, if you use wildcards on
936 the command line, be sure to escape them or put the whole file‐
937 name in single quotes, to prevent them from being interpreted by
938 the shell. To use the embedded fonts, you will need to add dec‐
939 larations like the following to your CSS (see --css):
940 @font-face {
942 font-family: DejaVuSans;
943 font-style: normal;
944 font-weight: normal;
945 src:url("DejaVuSans-Regular.ttf");
946 }
947 @font-face {
948 font-family: DejaVuSans;
949 font-style: normal;
950 font-weight: bold;
951 src:url("DejaVuSans-Bold.ttf");
952 }
953 @font-face {
954 font-family: DejaVuSans;
955 font-style: italic;
956 font-weight: normal;
957 src:url("DejaVuSans-Oblique.ttf");
958 }
959 @font-face {
960 font-family: DejaVuSans;
961 font-style: italic;
962 font-weight: bold;
963 src:url("DejaVuSans-BoldOblique.ttf");
964 }
965 body { font-family: "DejaVuSans"; }
966 --epub-chapter-level=NUMBER
968 Specify the header level at which to split the EPUB into sepa‐
969 rate "chapter" files. The default is to split into chapters at
970 level 1 headers. This option only affects the internal composi‐
971 tion of the EPUB, not the way chapters and sections are dis‐
972 played to users. Some readers may be slow if the chapter files
973 are too large, so for large documents with few level 1 headers,
974 one might want to use a chapter level of 2 or 3.
975 --epub-subdirectory=DIRNAME
977 Specify the subdirectory in the OCF container that is to hold
978 the EPUB-specific contents. The default is EPUB. To put the
979 EPUB contents in the top level, use an empty string.
980 --pdf-engine=pdflatex|lualatex|xelatex|wkhtml‐
982 topdf|weasyprint|prince|context|pdfroff
983 Use the specified engine when producing PDF output. The default
984 is pdflatex. If the engine is not in your PATH, the full path
985 of the engine may be specified here.
986 --pdf-engine-opt=STRING
988 Use the given string as a command-line argument to the
989 pdf-engine. If used multiple times, the arguments are provided
990 with spaces between them. Note that no check for duplicate
991 options is done.
992 Citation rendering
994 --bibliography=FILE
995 Set the bibliography field in the document's metadata to FILE,
996 overriding any value set in the metadata, and process citations
997 using pandoc-citeproc. (This is equivalent to --metadata bibli‐
998 ography=FILE --filter pandoc-citeproc.) If --natbib or --bibla‐
999 tex is also supplied, pandoc-citeproc is not used, making this
1000 equivalent to --metadata bibliography=FILE. If you supply this
1001 argument multiple times, each FILE will be added to bibliogra‐
1002 phy.
1003 --csl=FILE
1005 Set the csl field in the document's metadata to FILE, overriding
1006 any value set in the metadata. (This is equivalent to --meta‐
1007 data csl=FILE.) This option is only relevant with pan‐
1008 doc-citeproc.
1009 --citation-abbreviations=FILE
1011 Set the citation-abbreviations field in the document's metadata
1012 to FILE, overriding any value set in the metadata. (This is
1013 equivalent to --metadata citation-abbreviations=FILE.) This
1014 option is only relevant with pandoc-citeproc.
1015 --natbib
1017 Use natbib for citations in LaTeX output. This option is not
1018 for use with the pandoc-citeproc filter or with PDF output. It
1019 is intended for use in producing a LaTeX file that can be pro‐
1020 cessed with bibtex.
1021 --biblatex
1023 Use biblatex for citations in LaTeX output. This option is not
1024 for use with the pandoc-citeproc filter or with PDF output. It
1025 is intended for use in producing a LaTeX file that can be pro‐
1026 cessed with bibtex or biber.
1027 Math rendering in HTML
1029 The default is to render TeX math as far as possible using Unicode
1030 characters. Formulas are put inside a span with class="math", so that
1031 they may be styled differently from the surrounding text if needed.
1032 However, this gives acceptable results only for basic math, usually you
1033 will want to use --mathjax or another of the following options.
1034 --mathjax[=URL]
1036 Use MathJax to display embedded TeX math in HTML output. TeX
1037 math will be put between \(...\) (for inline math) or \[...\]
1038 (for display math) and wrapped in <span> tags with class math.
1039 Then the MathJax JavaScript will render it. The URL should
1040 point to the MathJax.js load script. If a URL is not provided,
1041 a link to the Cloudflare CDN will be inserted.
1042 --mathml
1044 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
1045 html4 and html5). This is the default in odt output. Note that
1046 currently only Firefox and Safari (and select e-book readers)
1047 natively support MathML.
1048 --webtex[=URL]
1050 Convert TeX formulas to <img> tags that link to an external
1051 script that converts formulas to images. The formula will be
1052 URL-encoded and concatenated with the URL provided. For SVG
1053 images you can for example use --web‐
1054 tex https://latex.codecogs.com/svg.latex?. If no URL is speci‐
1055 fied, the CodeCogs URL generating PNGs will be used
1056 (https://latex.codecogs.com/png.latex?). Note: the --webtex
1057 option will affect Markdown output as well as HTML, which is
1058 useful if you're targeting a version of Markdown without native
1059 math support.
1060 --katex[=URL]
1062 Use KaTeX to display embedded TeX math in HTML output. The URL
1063 is the base URL for the KaTeX library. If a URL is not pro‐
1064 vided, a link to the KaTeX CDN will be inserted.
1065 --katex-stylesheet=URL
1067 The URL should point to the katex.css stylesheet. If this
1068 option is not specified, a link to the KaTeX CDN will be
1069 inserted. Note that this option does not imply --katex.
1070 --gladtex
1072 Enclose TeX math in <eq> tags in HTML output. The resulting
1073 HTML can then be processed by GladTeX to produce images of the
1074 typeset formulas and an HTML file with links to these images.
1075 So, the procedure is:
1076 pandoc -s --gladtex input.md -o myfile.htex
1078 gladtex -d myfile-images myfile.htex
1079 # produces myfile.html and images in myfile-images
1080 Options for wrapper scripts
1082 --dump-args
1083 Print information about command-line arguments to stdout, then
1084 exit. This option is intended primarily for use in wrapper
1085 scripts. The first line of output contains the name of the out‐
1086 put file specified with the -o option, or - (for stdout) if no
1087 output file was specified. The remaining lines contain the com‐
1088 mand-line arguments, one per line, in the order they appear.
1089 These do not include regular pandoc options and their arguments,
1090 but do include any options appearing after a -- separator at the
1091 end of the line.
1092 --ignore-args
1094 Ignore command-line arguments (for use in wrapper scripts).
1095 Regular pandoc options are not ignored. Thus, for example,
1096 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1098 is equivalent to
1100 pandoc -o foo.html -s
1102
1104 When the -s/--standalone option is used, pandoc uses a template to add
1105 header and footer material that is needed for a self-standing document.
1106 To see the default template that is used, just type
1107 pandoc -D *FORMAT*
1109 where FORMAT is the name of the output format. A custom template can
1111 be specified using the --template option. You can also override the
1112 system default templates for a given output format FORMAT by putting a
1113 file templates/default.*FORMAT* in the user data directory (see
1114 --data-dir, above). Exceptions:
1115 · For odt output, customize the default.opendocument template.
1117 · For pdf output, customize the default.latex template (or the
1119 default.context template, if you use -t context, or the default.ms
1120 template, if you use -t ms, or the default.html template, if you use
1121 -t html).
1122 · docx has no template (however, you can use --reference-doc to custom‐
1124 ize the output).
1125 Templates contain variables, which allow for the inclusion of arbitrary
1127 information at any point in the file. They may be set at the command
1128 line using the -V/--variable option. If a variable is not set, pandoc
1129 will look for the key in the document's metadata – which can be set
1130 using either YAML metadata blocks or with the --metadata option.
1131 Variables set by pandoc
1133 Some variables are set automatically by pandoc. These vary somewhat
1134 depending on the output format, but include the following:
1135 sourcefile, outputfile
1137 source and destination filenames, as given on the command line.
1138 sourcefile can also be a list if input comes from multiple
1139 files, or empty if input is from stdin. You can use the follow‐
1140 ing snippet in your template to distinguish them:
1141 $if(sourcefile)$
1143 $for(sourcefile)$
1144 $sourcefile$
1145 $endfor$
1146 $else$
1147 (stdin)
1148 $endif$
1149 Similarly, outputfile can be - if output goes to the terminal.
1151 title, author, date
1153 allow identification of basic aspects of the document. Included
1154 in PDF metadata through LaTeX and ConTeXt. These can be set
1155 through a pandoc title block, which allows for multiple authors,
1156 or through a YAML metadata block:
1157 ---
1159 author:
1160 - Aristotle
1161 - Peter Abelard
1162 ...
1163 subtitle
1165 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
1166 Word docx; renders in LaTeX only when using a document class
1167 that supports \subtitle, such as beamer or the KOMA-Script
1168 series (scrartcl, scrreprt, scrbook).
1169 institute
1171 author affiliations (in LaTeX and Beamer only). Can be a list,
1172 when there are multiple authors.
1173 abstract
1175 document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word
1176 docx
1177 keywords
1179 list of keywords to be included in HTML, PDF, and AsciiDoc meta‐
1180 data; may be repeated as for author, above
1181 header-includes
1183 contents specified by -H/--include-in-header (may have multiple
1184 values)
1185 toc non-null value if --toc/--table-of-contents was specified
1187 toc-title
1189 title of table of contents (works only with EPUB, opendocument,
1190 odt, docx, pptx)
1191 include-before
1193 contents specified by -B/--include-before-body (may have multi‐
1194 ple values)
1195 include-after
1197 contents specified by -A/--include-after-body (may have multiple
1198 values)
1199 body body of document
1201 meta-json
1203 JSON representation of all of the document's metadata. Field
1204 values are transformed to the selected output format.
1205 Language variables
1207 lang identifies the main language of the document, using a code
1208 according to BCP 47 (e.g. en or en-GB). For some output for‐
1209 mats, pandoc will convert it to an appropriate format stored in
1210 the additional variables babel-lang, polyglossia-lang (LaTeX)
1211 and context-lang (ConTeXt).
1212 Native pandoc Spans and Divs with the lang attribute (value in
1214 BCP 47) can be used to switch the language in that range. In
1215 LaTeX output, babel-otherlangs and polyglossia-otherlangs vari‐
1216 ables will be generated automatically based on the lang
1217 attributes of Spans and Divs in the document.
1218 dir the base direction of the document, either rtl (right-to-left)
1220 or ltr (left-to-right).
1221 For bidirectional documents, native pandoc spans and divs with
1223 the dir attribute (value rtl or ltr) can be used to override the
1224 base direction in some output formats. This may not always be
1225 necessary if the final renderer (e.g. the browser, when gener‐
1226 ating HTML) supports the Unicode Bidirectional Algorithm.
1227 When using LaTeX for bidirectional documents, only the xelatex
1229 engine is fully supported (use --pdf-engine=xelatex).
1230 Variables for slides
1232 Variables are available for producing slide shows with pandoc, includ‐
1233 ing all reveal.js configuration options.
1234 titlegraphic
1236 title graphic for Beamer documents
1237 logo logo for Beamer documents
1239 slidy-url
1241 base URL for Slidy documents (defaults to
1242 https://www.w3.org/Talks/Tools/Slidy2)
1243 slideous-url
1245 base URL for Slideous documents (defaults to slideous)
1246 s5-url base URL for S5 documents (defaults to s5/default)
1248 revealjs-url
1250 base URL for reveal.js documents (defaults to reveal.js)
1251 theme, colortheme, fonttheme, innertheme, outertheme
1253 themes for LaTeX beamer documents
1254 themeoptions
1256 options for LaTeX beamer themes (a list).
1257 navigation
1259 controls navigation symbols in beamer documents (default is
1260 empty for no navigation symbols; other valid values are frame,
1261 vertical, and horizontal).
1262 section-titles
1264 enables on "title pages" for new sections in beamer documents
1265 (default = true).
1266 beamerarticle
1268 when true, the beamerarticle package is loaded (for producing an
1269 article from beamer slides).
1270 aspectratio
1272 aspect ratio of slides (for beamer only, 1610 for 16:10, 169 for
1273 16:9, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 43 for 4:3 which
1274 is the default, and 32 for 3:2).
1275 Variables for LaTeX
1277 LaTeX variables are used when creating a PDF.
1278 papersize
1280 paper size, e.g. letter, a4
1281 fontsize
1283 font size for body text (e.g. 10pt, 12pt)
1284 documentclass
1286 document class, e.g. article, report, book, memoir
1287 classoption
1289 option for document class, e.g. oneside; may be repeated for
1290 multiple options
1291 beameroption
1293 In beamer, add extra beamer option with \setbeameroption{}
1294 geometry
1296 option for geometry package, e.g. margin=1in; may be repeated
1297 for multiple options
1298 margin-left, margin-right, margin-top, margin-bottom
1300 sets margins, if geometry is not used (otherwise geometry over‐
1301 rides these)
1302 linestretch
1304 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
1305 fontfamily
1307 font package for use with pdflatex: TeX Live includes many
1308 options, documented in the LaTeX Font Catalogue. The default is
1309 Latin Modern.
1310 fontfamilyoptions
1312 options for package used as fontfamily: e.g. osf,sc with font‐
1313 family set to mathpazo provides Palatino with old-style figures
1314 and true small caps; may be repeated for multiple options
1315 mainfont, sansfont, monofont, mathfont, CJKmainfont
1317 font families for use with xelatex or lualatex: take the name of
1318 any system font, using the fontspec package. Note that if CJK‐
1319 mainfont is used, the xecjk package must be available.
1320 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions,
1322 CJKoptions
1323 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
1324 mainfont in xelatex and lualatex. Allow for any choices avail‐
1325 able through fontspec, such as the OpenType features Num‐
1326 bers=OldStyle,Numbers=Proportional. May be repeated for multi‐
1327 ple options.
1328 fontenc
1330 allows font encoding to be specified through fontenc package
1331 (with pdflatex); default is T1 (see guide to LaTeX font encod‐
1332 ings)
1333 microtypeoptions
1335 options to pass to the microtype package
1336 colorlinks
1338 add color to link text; automatically enabled if any of link‐
1339 color, citecolor, urlcolor, or toccolor are set
1340 linkcolor, citecolor, urlcolor, toccolor
1342 color for internal links, citation links, external links, and
1343 links in table of contents: uses options allowed by xcolor,
1344 including the dvipsnames, svgnames, and x11names lists
1345 links-as-notes
1347 causes links to be printed as footnotes
1348 indent uses document class settings for indentation (the default LaTeX
1350 template otherwise removes indentation and adds space between
1351 paragraphs)
1352 subparagraph
1354 disables default behavior of LaTeX template that redefines
1355 (sub)paragraphs as sections, changing the appearance of nested
1356 headings in some classes
1357 thanks specifies contents of acknowledgments footnote after document
1359 title.
1360 toc include table of contents (can also be set using --toc/--ta‐
1362 ble-of-contents)
1363 toc-depth
1365 level of section to include in table of contents
1366 secnumdepth
1368 numbering depth for sections, if sections are numbered
1369 lof, lot
1371 include list of figures, list of tables
1372 bibliography
1374 bibliography to use for resolving references
1375 biblio-style
1377 bibliography style, when used with --natbib and --biblatex.
1378 biblio-title
1380 bibliography title, when used with --natbib and --biblatex.
1381 biblatexoptions
1383 list of options for biblatex.
1384 natbiboptions
1386 list of options for natbib.
1387 pagestyle
1389 An option for LaTeX's \pagestyle{}. The default article class
1390 supports 'plain' (default), 'empty', and 'headings'; headings
1391 puts section titles in the header.
1392 Variables for ConTeXt
1394 papersize
1395 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
1396 up); may be repeated for multiple options
1397 layout options for page margins and text arrangement (see ConTeXt Lay‐
1399 out); may be repeated for multiple options
1400 margin-left, margin-right, margin-top, margin-bottom
1402 sets margins, if layout is not used (otherwise layout overrides
1403 these)
1404 fontsize
1406 font size for body text (e.g. 10pt, 12pt)
1407 mainfont, sansfont, monofont, mathfont
1409 font families: take the name of any system font (see ConTeXt
1410 Font Switching)
1411 linkcolor, contrastcolor
1413 color for links outside and inside a page, e.g. red, blue (see
1414 ConTeXt Color)
1415 linkstyle
1417 typeface style for links, e.g. normal, bold, slanted, bold‐
1418 slanted, type, cap, small
1419 indenting
1421 controls indentation of paragraphs, e.g. yes,small,next (see
1422 ConTeXt Indentation); may be repeated for multiple options
1423 whitespace
1425 spacing between paragraphs, e.g. none, small (using setup‐
1426 whitespace)
1427 interlinespace
1429 adjusts line spacing, e.g. 4ex (using setupinterlinespace); may
1430 be repeated for multiple options
1431 headertext, footertext
1433 text to be placed in running header or footer (see ConTeXt Head‐
1434 ers and Footers); may be repeated up to four times for different
1435 placement
1436 pagenumbering
1438 page number style and location (using setuppagenumbering); may
1439 be repeated for multiple options
1440 toc include table of contents (can also be set using --toc/--ta‐
1442 ble-of-contents)
1443 lof, lot
1445 include list of figures, list of tables
1446 pdfa adds to the preamble the setup necessary to generate
1448 PDF/A-1b:2005. To successfully generate PDF/A the required ICC
1449 color profiles have to be available and the content and all
1450 included files (such as images) have to be standard conforming.
1451 The ICC profiles can be obtained from ConTeXt ICC Profiles. See
1452 also ConTeXt PDFA for more details.
1453 Variables for man pages
1455 section
1456 section number in man pages
1457 header header in man pages
1459 footer footer in man pages
1461 adjusting
1463 adjusts text to left (l), right (r), center (c), or both (b)
1464 margins
1465 hyphenate
1467 if true (the default), hyphenation will be used
1468 Variables for ms
1470 pointsize
1471 point size (e.g. 10p)
1472 lineheight
1474 line height (e.g. 12p)
1475 fontfamily
1477 font family (e.g. T or P)
1478 indent paragraph indent (e.g. 2m)
1480 Using variables in templates
1482 Variable names are sequences of alphanumerics, -, and _, starting with
1483 a letter. A variable name surrounded by $ signs will be replaced by
1484 its value. For example, the string $title$ in
1485 <title>$title$</title>
1487 will be replaced by the document title.
1489 To write a literal $ in a template, use $$.
1491 Templates may contain conditionals. The syntax is as follows:
1493 $if(variable)$
1495 X
1496 $else$
1497 Y
1498 $endif$
1499 This will include X in the template if variable has a truthy value;
1501 otherwise it will include Y. Here a truthy value is any of the follow‐
1502 ing:
1503 · a string that is not entirely white space,
1505 · a non-empty array where the first value is truthy,
1507 · any number (including zero),
1509 · any object,
1511 · the boolean true (to specify the boolean true value using YAML meta‐
1513 data or the --metadata flag, use y, Y, yes, Yes, YES, true, True,
1514 TRUE, on, On, or ON; with the --variable flag, simply omit a value
1515 for the variable, e.g. --variable draft).
1516 X and Y are placeholders for any valid template text, and may include
1518 interpolated variables or other conditionals. The $else$ section may
1519 be omitted.
1520 When variables can have multiple values (for example, author in a
1522 multi-author document), you can use the $for$ keyword:
1523 $for(author)$
1525 <meta name="author" content="$author$" />
1526 $endfor$
1527 You can optionally specify a separator to be used between consecutive
1529 items:
1530 $for(author)$$author$$sep$, $endfor$
1532 A dot can be used to select a field of a variable that takes an object
1534 as its value. So, for example:
1535 $author.name$ ($author.affiliation$)
1537 If you use custom templates, you may need to revise them as pandoc
1539 changes. We recommend tracking the changes in the default templates,
1540 and modifying your custom templates accordingly. An easy way to do
1541 this is to fork the pandoc-templates repository and merge in changes
1542 after each pandoc release.
1543 Templates may contain comments: anything on a line after $-- will be
1545 treated as a comment and ignored.
1546
1548 The behavior of some of the readers and writers can be adjusted by
1549 enabling or disabling various extensions.
1550 An extension can be enabled by adding +EXTENSION to the format name and
1552 disabled by adding -EXTENSION. For example, --from mark‐
1553 down_strict+footnotes is strict Markdown with footnotes enabled, while
1554 --from markdown-footnotes-pipe_tables is pandoc's Markdown without
1555 footnotes or pipe tables.
1556 The markdown reader and writer make by far the most use of extensions.
1558 Extensions only used by them are therefore covered in the section Pan‐
1559 doc's Markdown below (See Markdown variants for commonmark and gfm.) In
1560 the following, extensions that also work for other formats are covered.
1561 Typography
1563 Extension: smart
1564 Interpret straight quotes as curly quotes, --- as em-dashes, -- as
1565 en-dashes, and ... as ellipses. Nonbreaking spaces are inserted after
1566 certain abbreviations, such as "Mr."
1567 This extension can be enabled/disabled for the following formats:
1569 input formats
1571 markdown, commonmark, latex, mediawiki, org, rst, twiki
1572 output formats
1574 markdown, latex, context, rst
1575 enabled by default in
1577 markdown, latex, context (both input and output)
1578 Note: If you are writing Markdown, then the smart extension has the
1580 reverse effect: what would have been curly quotes comes out straight.
1581 In LaTeX, smart means to use the standard TeX ligatures for quotation
1583 marks (`` and '' for double quotes, ` and ' for single quotes) and
1584 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
1585 then in reading LaTeX pandoc will parse these characters literally. In
1586 writing LaTeX, enabling smart tells pandoc to use the ligatures when
1587 possible; if smart is disabled pandoc will use unicode quotation mark
1588 and dash characters.
1589 Headers and sections
1591 Extension: auto_identifiers
1592 A header without an explicitly specified identifier will be automati‐
1593 cally assigned a unique identifier based on the header text.
1594 This extension can be enabled/disabled for the following formats:
1596 input formats
1598 markdown, latex, rst, mediawiki, textile
1599 output formats
1601 markdown, muse
1602 enabled by default in
1604 markdown, muse
1605 The algorithm used to derive the identifier from the header text is:
1607 · Remove all formatting, links, etc.
1609 · Remove all footnotes.
1611 · Remove all punctuation, except underscores, hyphens, and periods.
1613 · Replace all spaces and newlines with hyphens.
1615 · Convert all alphabetic characters to lowercase.
1617 · Remove everything up to the first letter (identifiers may not begin
1619 with a number or punctuation mark).
1620 · If nothing is left after this, use the identifier section.
1622 Thus, for example,
1624 Header Identifier
1626 ────────────────────────────────────────────────────────
1627 Header identifiers in HTML header-identifiers-in-html
1628 *Dogs*?--in *my* house? dogs--in-my-house
1629 [HTML], [S5], or [RTF]? html-s5-or-rtf
1630 3. Applications applications
1631 33 section
1632 These rules should, in most cases, allow one to determine the identi‐
1634 fier from the header text. The exception is when several headers have
1635 the same text; in this case, the first will get an identifier as
1636 described above; the second will get the same identifier with -1
1637 appended; the third with -2; and so on.
1638 These identifiers are used to provide link targets in the table of con‐
1640 tents generated by the --toc|--table-of-contents option. They also
1641 make it easy to provide links from one section of a document to
1642 another. A link to this section, for example, might look like this:
1643 See the section on
1645 [header identifiers](#header-identifiers-in-html-latex-and-context).
1646 Note, however, that this method of providing links to sections works
1648 only in HTML, LaTeX, and ConTeXt formats.
1649 If the --section-divs option is specified, then each section will be
1651 wrapped in a section (or a div, if html4 was specified), and the iden‐
1652 tifier will be attached to the enclosing <section> (or <div>) tag
1653 rather than the header itself. This allows entire sections to be
1654 manipulated using JavaScript or treated differently in CSS.
1655 Extension: ascii_identifiers
1657 Causes the identifiers produced by auto_identifiers to be pure ASCII.
1658 Accents are stripped off of accented Latin letters, and non-Latin let‐
1659 ters are omitted.
1660 Math Input
1662 The extensions tex_math_dollars, tex_math_single_backslash, and
1663 tex_math_double_backslash are described in the section about Pandoc's
1664 Markdown.
1665 However, they can also be used with HTML input. This is handy for
1667 reading web pages formatted using MathJax, for example.
1668 Raw HTML/TeX
1670 The following extensions (especially how they affect Markdown
1671 input/output) are also described in more detail in their respective
1672 sections of Pandoc's Markdown.
1673 Extension: raw_html
1675 When converting from HTML, parse elements to raw HTML which are not
1676 representable in pandoc's AST. By default, this is disabled for HTML
1677 input.
1678 Extension: raw_tex
1680 Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
1681 This extension can be enabled/disabled for the following formats (in
1683 addition to markdown):
1684 input formats
1686 latex, org, textile
1687 output formats
1689 textile
1690 Extension: native_divs
1692 This extension is enabled by default for HTML input. This means that
1693 divs are parsed to pandoc native elements. (Alternatively, you can
1694 parse them to raw HTML using -f html-native_divs+raw_html.)
1695 When converting HTML to Markdown, for example, you may want to drop all
1697 divs and spans:
1698 pandoc -f html-native_divs-native_spans -t markdown
1700 Extension: native_spans
1702 Analogous to native_divs above.
1703 Literate Haskell support
1705 Extension: literate_haskell
1706 Treat the document as literate Haskell source.
1707 This extension can be enabled/disabled for the following formats:
1709 input formats
1711 markdown, rst, latex
1712 output formats
1714 markdown, rst, latex, html
1715 If you append +lhs (or +literate_haskell) to one of the formats above,
1717 pandoc will treat the document as literate Haskell source. This means
1718 that
1719 · In Markdown input, "bird track" sections will be parsed as Haskell
1721 code rather than block quotations. Text between \begin{code} and
1722 \end{code} will also be treated as Haskell code. For ATX-style head‐
1723 ers the character '=' will be used instead of '#'.
1724 · In Markdown output, code blocks with classes haskell and literate
1726 will be rendered using bird tracks, and block quotations will be
1727 indented one space, so they will not be treated as Haskell code. In
1728 addition, headers will be rendered setext-style (with underlines)
1729 rather than ATX-style (with '#' characters). (This is because ghc
1730 treats '#' characters in column 1 as introducing line numbers.)
1731 · In restructured text input, "bird track" sections will be parsed as
1733 Haskell code.
1734 · In restructured text output, code blocks with class haskell will be
1736 rendered using bird tracks.
1737 · In LaTeX input, text in code environments will be parsed as Haskell
1739 code.
1740 · In LaTeX output, code blocks with class haskell will be rendered
1742 inside code environments.
1743 · In HTML output, code blocks with class haskell will be rendered with
1745 class literatehaskell and bird tracks.
1746 Examples:
1748 pandoc -f markdown+lhs -t html
1750 reads literate Haskell source formatted with Markdown conventions and
1752 writes ordinary HTML (without bird tracks).
1753 pandoc -f markdown+lhs -t html+lhs
1755 writes HTML with the Haskell code in bird tracks, so it can be copied
1757 and pasted as literate Haskell source.
1758 Note that GHC expects the bird tracks in the first column, so indented
1760 literate code blocks (e.g. inside an itemized environment) will not be
1761 picked up by the Haskell compiler.
1762 Other extensions
1764 Extension: empty_paragraphs
1765 Allows empty paragraphs. By default empty paragraphs are omitted.
1766 This extension can be enabled/disabled for the following formats:
1768 input formats
1770 docx, html
1771 output formats
1773 docx, odt, opendocument, html
1774 Extension: styles
1776 Read all docx styles as divs (for paragraph styles) and spans (for
1777 character styles) regardless of whether pandoc understands the meaning
1778 of these styles. This can be used with docx custom styles. Disabled
1779 by default.
1780 input formats
1782 docx
1783 Extension: amuse
1785 In the muse input format, this enables Text::Amuse extensions to Emacs
1786 Muse markup.
1787 Extension: citations
1789 Some aspects of Pandoc's Markdown citation syntax are also accepted in
1790 org input.
1791 Extension: ntb
1793 In the context output format this enables the use of Natural Tables
1794 (TABLE) instead of the default Extreme Tables (xtables). Natural
1795 tables allow more fine-grained global customization but come at a per‐
1796 formance penalty compared to extreme tables.
1797
1799 Pandoc understands an extended and slightly revised version of John
1800 Gruber's Markdown syntax. This document explains the syntax, noting
1801 differences from standard Markdown. Except where noted, these differ‐
1802 ences can be suppressed by using the markdown_strict format instead of
1803 markdown. Extensions can be enabled or disabled to specify the behav‐
1804 ior more granularly. They are described in the following. See also
1805 Extensions above, for extensions that work also on other formats.
1806 Philosophy
1808 Markdown is designed to be easy to write, and, even more importantly,
1809 easy to read:
1810 A Markdown-formatted document should be publishable as-is, as
1812 plain text, without looking like it's been marked up with tags
1813 or formatting instructions. -- John Gruber
1814 This principle has guided pandoc's decisions in finding syntax for
1816 tables, footnotes, and other extensions.
1817 There is, however, one respect in which pandoc's aims are different
1819 from the original aims of Markdown. Whereas Markdown was originally
1820 designed with HTML generation in mind, pandoc is designed for multiple
1821 output formats. Thus, while pandoc allows the embedding of raw HTML,
1822 it discourages it, and provides other, non-HTMLish ways of representing
1823 important document elements like definition lists, tables, mathematics,
1824 and footnotes.
1825 Paragraphs
1827 A paragraph is one or more lines of text followed by one or more blank
1828 lines. Newlines are treated as spaces, so you can reflow your para‐
1829 graphs as you like. If you need a hard line break, put two or more
1830 spaces at the end of a line.
1831 Extension: escaped_line_breaks
1833 A backslash followed by a newline is also a hard line break. Note: in
1834 multiline and grid table cells, this is the only way to create a hard
1835 line break, since trailing spaces in the cells are ignored.
1836 Headers
1838 There are two kinds of headers: Setext and ATX.
1839 Setext-style headers
1841 A setext-style header is a line of text "underlined" with a row of =
1842 signs (for a level one header) or - signs (for a level two header):
1843 A level-one header
1845 ==================
1846 A level-two header
1848 ------------------
1849 The header text can contain inline formatting, such as emphasis (see
1851 Inline formatting, below).
1852 ATX-style headers
1854 An ATX-style header consists of one to six # signs and a line of text,
1855 optionally followed by any number of # signs. The number of # signs at
1856 the beginning of the line is the header level:
1857 ## A level-two header
1859 ### A level-three header ###
1861 As with setext-style headers, the header text can contain formatting:
1863 # A level-one header with a [link](/url) and *emphasis*
1865 Extension: blank_before_header
1867 Standard Markdown syntax does not require a blank line before a header.
1868 Pandoc does require this (except, of course, at the beginning of the
1869 document). The reason for the requirement is that it is all too easy
1870 for a # to end up at the beginning of a line by accident (perhaps
1871 through line wrapping). Consider, for example:
1872 I like several of their flavors of ice cream:
1874 #22, for example, and #5.
1875 Extension: space_in_atx_header
1877 Many Markdown implementations do not require a space between the open‐
1878 ing #s of an ATX header and the header text, so that #5 bolt and #hash‐
1879 tag count as headers. With this extension, pandoc does require the
1880 space.
1881 Header identifiers
1883 See also the auto_identifiers extension above.
1884 Extension: header_attributes
1886 Headers can be assigned attributes using this syntax at the end of the
1887 line containing the header text:
1888 {#identifier .class .class key=value key=value}
1890 Thus, for example, the following headers will all be assigned the iden‐
1892 tifier foo:
1893 # My header {#foo}
1895 ## My header ## {#foo}
1897 My other header {#foo}
1899 ---------------
1900 (This syntax is compatible with PHP Markdown Extra.)
1902 Note that although this syntax allows assignment of classes and
1904 key/value attributes, writers generally don't use all of this informa‐
1905 tion. Identifiers, classes, and key/value attributes are used in HTML
1906 and HTML-based formats such as EPUB and slidy. Identifiers are used
1907 for labels and link anchors in the LaTeX, ConTeXt, Textile, and Asci‐
1908 iDoc writers.
1909 Headers with the class unnumbered will not be numbered, even if --num‐
1911 ber-sections is specified. A single hyphen (-) in an attribute context
1912 is equivalent to .unnumbered, and preferable in non-English documents.
1913 So,
1914 # My header {-}
1916 is just the same as
1918 # My header {.unnumbered}
1920 Extension: implicit_header_references
1922 Pandoc behaves as if reference links have been defined for each header.
1923 So, to link to a header
1924 # Header identifiers in HTML
1926 you can simply write
1928 [Header identifiers in HTML]
1930 or
1932 [Header identifiers in HTML][]
1934 or
1936 [the section on header identifiers][header identifiers in
1938 HTML]
1939 instead of giving the identifier explicitly:
1941 [Header identifiers in HTML](#header-identifiers-in-html)
1943 If there are multiple headers with identical text, the corresponding
1945 reference will link to the first one only, and you will need to use
1946 explicit links to link to the others, as described above.
1947 Like regular reference links, these references are case-insensitive.
1949 Explicit link reference definitions always take priority over implicit
1951 header references. So, in the following example, the link will point
1952 to bar, not to #foo:
1953 # Foo
1955 [foo]: bar
1957 See [foo]
1959 Block quotations
1961 Markdown uses email conventions for quoting blocks of text. A block
1962 quotation is one or more paragraphs or other block elements (such as
1963 lists or headers), with each line preceded by a > character and an
1964 optional space. (The > need not start at the left margin, but it
1965 should not be indented more than three spaces.)
1966 > This is a block quote. This
1968 > paragraph has two lines.
1969 >
1970 > 1. This is a list inside a block quote.
1971 > 2. Second item.
1972 A "lazy" form, which requires the > character only on the first line of
1974 each block, is also allowed:
1975 > This is a block quote. This
1977 paragraph has two lines.
1978 > 1. This is a list inside a block quote.
1980 2. Second item.
1981 Among the block elements that can be contained in a block quote are
1983 other block quotes. That is, block quotes can be nested:
1984 > This is a block quote.
1986 >
1987 > > A block quote within a block quote.
1988 If the > character is followed by an optional space, that space will be
1990 considered part of the block quote marker and not part of the indenta‐
1991 tion of the contents. Thus, to put an indented code block in a block
1992 quote, you need five spaces after the >:
1993 > code
1995 Extension: blank_before_blockquote
1997 Standard Markdown syntax does not require a blank line before a block
1998 quote. Pandoc does require this (except, of course, at the beginning
1999 of the document). The reason for the requirement is that it is all too
2000 easy for a > to end up at the beginning of a line by accident (perhaps
2001 through line wrapping). So, unless the markdown_strict format is used,
2002 the following does not produce a nested block quote in pandoc:
2003 > This is a block quote.
2005 >> Nested.
2006 Verbatim (code) blocks
2008 Indented code blocks
2009 A block of text indented four spaces (or one tab) is treated as verba‐
2010 tim text: that is, special characters do not trigger special format‐
2011 ting, and all spaces and line breaks are preserved. For example,
2012 if (a > 3) {
2014 moveShip(5 * gravity, DOWN);
2015 }
2016 The initial (four space or one tab) indentation is not considered part
2018 of the verbatim text, and is removed in the output.
2019 Note: blank lines in the verbatim text need not begin with four spaces.
2021 Fenced code blocks
2023 Extension: fenced_code_blocks
2024 In addition to standard indented code blocks, pandoc supports fenced
2025 code blocks. These begin with a row of three or more tildes (~) and
2026 end with a row of tildes that must be at least as long as the starting
2027 row. Everything between these lines is treated as code. No indenta‐
2028 tion is necessary:
2029 ~~~~~~~
2031 if (a > 3) {
2032 moveShip(5 * gravity, DOWN);
2033 }
2034 ~~~~~~~
2035 Like regular code blocks, fenced code blocks must be separated from
2037 surrounding text by blank lines.
2038 If the code itself contains a row of tildes or backticks, just use a
2040 longer row of tildes or backticks at the start and end:
2041 ~~~~~~~~~~~~~~~~
2043 ~~~~~~~~~~
2044 code including tildes
2045 ~~~~~~~~~~
2046 ~~~~~~~~~~~~~~~~
2047 Extension: backtick_code_blocks
2049 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
2050 (~).
2051 Extension: fenced_code_attributes
2053 Optionally, you may attach attributes to fenced or backtick code block
2054 using this syntax:
2055 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
2057 qsort [] = []
2058 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
2059 qsort (filter (>= x) xs)
2060 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2061 Here mycode is an identifier, haskell and numberLines are classes, and
2063 startFrom is an attribute with value 100. Some output formats can use
2064 this information to do syntax highlighting. Currently, the only output
2065 formats that uses this information are HTML, LaTeX, Docx, Ms, and Pow‐
2066 erPoint. If highlighting is supported for your output format and lan‐
2067 guage, then the code block above will appear highlighted, with numbered
2068 lines. (To see which languages are supported, type pandoc --list-high‐
2069 light-languages.) Otherwise, the code block above will appear as fol‐
2070 lows:
2071 <pre id="mycode" class="haskell numberLines" startFrom="100">
2073 <code>
2074 ...
2075 </code>
2076 </pre>
2077 The numberLines (or number-lines) class will cause the lines of the
2079 code block to be numbered, starting with 1 or the value of the start‐
2080 From attribute. The lineAnchors (or line-anchors) class will cause the
2081 lines to be clickable anchors in HTML output.
2082 A shortcut form can also be used for specifying the language of the
2084 code block:
2085 ```haskell
2087 qsort [] = []
2088 ```
2089 This is equivalent to:
2091 ``` {.haskell}
2093 qsort [] = []
2094 ```
2095 If the fenced_code_attributes extension is disabled, but input contains
2097 class attribute(s) for the code block, the first class attribute will
2098 be printed after the opening fence as a bare word.
2099 To prevent all highlighting, use the --no-highlight flag. To set the
2101 highlighting style, use --highlight-style. For more information on
2102 highlighting, see Syntax highlighting, below.
2103 Line blocks
2105 Extension: line_blocks
2106 A line block is a sequence of lines beginning with a vertical bar (|)
2107 followed by a space. The division into lines will be preserved in the
2108 output, as will any leading spaces; otherwise, the lines will be for‐
2109 matted as Markdown. This is useful for verse and addresses:
2110 | The limerick packs laughs anatomical
2112 | In space that is quite economical.
2113 | But the good ones I've seen
2114 | So seldom are clean
2115 | And the clean ones so seldom are comical
2116 | 200 Main St.
2118 | Berkeley, CA 94718
2119 The lines can be hard-wrapped if needed, but the continuation line must
2121 begin with a space.
2122 | The Right Honorable Most Venerable and Righteous Samuel L.
2124 Constable, Jr.
2125 | 200 Main St.
2126 | Berkeley, CA 94718
2127 This syntax is borrowed from reStructuredText.
2129 Lists
2131 Bullet lists
2132 A bullet list is a list of bulleted list items. A bulleted list item
2133 begins with a bullet (*, +, or -). Here is a simple example:
2134 * one
2136 * two
2137 * three
2138 This will produce a "compact" list. If you want a "loose" list, in
2140 which each item is formatted as a paragraph, put spaces between the
2141 items:
2142 * one
2144 * two
2146 * three
2148 The bullets need not be flush with the left margin; they may be
2150 indented one, two, or three spaces. The bullet must be followed by
2151 whitespace.
2152 List items look best if subsequent lines are flush with the first line
2154 (after the bullet):
2155 * here is my first
2157 list item.
2158 * and my second.
2159 But Markdown also allows a "lazy" format:
2161 * here is my first
2163 list item.
2164 * and my second.
2165 Block content in list items
2167 A list item may contain multiple paragraphs and other block-level con‐
2168 tent. However, subsequent paragraphs must be preceded by a blank line
2169 and indented to line up with the first non-space content after the list
2170 marker.
2171 * First paragraph.
2173 Continued.
2175 * Second paragraph. With a code block, which must be indented
2177 eight spaces:
2178 { code }
2180 Exception: if the list marker is followed by an indented code block,
2182 which must begin 5 spaces after the list marker, then subsequent para‐
2183 graphs must begin two columns after the last character of the list
2184 marker:
2185 * code
2187 continuation paragraph
2189 List items may include other lists. In this case the preceding blank
2191 line is optional. The nested list must be indented to line up with the
2192 first non-space character after the list marker of the containing list
2193 item.
2194 * fruits
2196 + apples
2197 - macintosh
2198 - red delicious
2199 + pears
2200 + peaches
2201 * vegetables
2202 + broccoli
2203 + chard
2204 As noted above, Markdown allows you to write list items "lazily,"
2206 instead of indenting continuation lines. However, if there are multi‐
2207 ple paragraphs or other blocks in a list item, the first line of each
2208 must be indented.
2209 + A lazy, lazy, list
2211 item.
2212 + Another one; this looks
2214 bad but is legal.
2215 Second paragraph of second
2217 list item.
2218 Ordered lists
2220 Ordered lists work just like bulleted lists, except that the items
2221 begin with enumerators rather than bullets.
2222 In standard Markdown, enumerators are decimal numbers followed by a
2224 period and a space. The numbers themselves are ignored, so there is no
2225 difference between this list:
2226 1. one
2228 2. two
2229 3. three
2230 and this one:
2232 5. one
2234 7. two
2235 1. three
2236 Extension: fancy_lists
2238 Unlike standard Markdown, pandoc allows ordered list items to be marked
2239 with uppercase and lowercase letters and roman numerals, in addition to
2240 Arabic numerals. List markers may be enclosed in parentheses or fol‐
2241 lowed by a single right-parentheses or period. They must be separated
2242 from the text that follows by at least one space, and, if the list
2243 marker is a capital letter with a period, by at least two spaces.
2244 The fancy_lists extension also allows '#' to be used as an ordered list
2246 marker in place of a numeral:
2247 #. one
2249 #. two
2250 Extension: startnum
2252 Pandoc also pays attention to the type of list marker used, and to the
2253 starting number, and both of these are preserved where possible in the
2254 output format. Thus, the following yields a list with numbers followed
2255 by a single parenthesis, starting with 9, and a sublist with lowercase
2256 roman numerals:
2257 9) Ninth
2259 10) Tenth
2260 11) Eleventh
2261 i. subone
2262 ii. subtwo
2263 iii. subthree
2264 Pandoc will start a new list each time a different type of list marker
2266 is used. So, the following will create three lists:
2267 (2) Two
2269 (5) Three
2270 1. Four
2271 * Five
2272 If default list markers are desired, use #.:
2274 #. one
2276 #. two
2277 #. three
2278 Definition lists
2280 Extension: definition_lists
2281 Pandoc supports definition lists, using the syntax of PHP Markdown
2282 Extra with some extensions.
2283 Term 1
2285 : Definition 1
2287 Term 2 with *inline markup*
2289 : Definition 2
2291 { some code, part of Definition 2 }
2293 Third paragraph of definition 2.
2295 Each term must fit on one line, which may optionally be followed by a
2297 blank line, and must be followed by one or more definitions. A defini‐
2298 tion begins with a colon or tilde, which may be indented one or two
2299 spaces.
2300 A term may have multiple definitions, and each definition may consist
2302 of one or more block elements (paragraph, code block, list, etc.), each
2303 indented four spaces or one tab stop. The body of the definition
2304 (including the first line, aside from the colon or tilde) should be
2305 indented four spaces. However, as with other Markdown lists, you can
2306 "lazily" omit indentation except at the beginning of a paragraph or
2307 other block element:
2308 Term 1
2310 : Definition
2312 with lazy continuation.
2313 Second paragraph of the definition.
2315 If you leave space before the definition (as in the example above), the
2317 text of the definition will be treated as a paragraph. In some output
2318 formats, this will mean greater spacing between term/definition pairs.
2319 For a more compact definition list, omit the space before the defini‐
2320 tion:
2321 Term 1
2323 ~ Definition 1
2324 Term 2
2326 ~ Definition 2a
2327 ~ Definition 2b
2328 Note that space between items in a definition list is required. (A
2330 variant that loosens this requirement, but disallows "lazy" hard wrap‐
2331 ping, can be activated with compact_definition_lists: see Non-pandoc
2332 extensions, below.)
2333 Numbered example lists
2335 Extension: example_lists
2336 The special list marker @ can be used for sequentially numbered exam‐
2337 ples. The first list item with a @ marker will be numbered '1', the
2338 next '2', and so on, throughout the document. The numbered examples
2339 need not occur in a single list; each new list using @ will take up
2340 where the last stopped. So, for example:
2341 (@) My first example will be numbered (1).
2343 (@) My second example will be numbered (2).
2344 Explanation of examples.
2346 (@) My third example will be numbered (3).
2348 Numbered examples can be labeled and referred to elsewhere in the docu‐
2350 ment:
2351 (@good) This is a good example.
2353 As (@good) illustrates, ...
2355 The label can be any string of alphanumeric characters, underscores, or
2357 hyphens.
2358 Note: continuation paragraphs in example lists must always be indented
2360 four spaces, regardless of the length of the list marker. That is,
2361 example lists always behave as if the four_space_rule extension is set.
2362 This is because example labels tend to be long, and indenting content
2363 to the first non-space character after the label would be awkward.
2364 Compact and loose lists
2366 Pandoc behaves differently from Markdown.pl on some "edge cases"
2367 involving lists. Consider this source:
2368 + First
2370 + Second:
2371 - Fee
2372 - Fie
2373 - Foe
2374 + Third
2376 Pandoc transforms this into a "compact list" (with no <p> tags around
2378 "First", "Second", or "Third"), while Markdown puts <p> tags around
2379 "Second" and "Third" (but not "First"), because of the blank space
2380 around "Third". Pandoc follows a simple rule: if the text is followed
2381 by a blank line, it is treated as a paragraph. Since "Second" is fol‐
2382 lowed by a list, and not a blank line, it isn't treated as a paragraph.
2383 The fact that the list is followed by a blank line is irrelevant.
2384 (Note: Pandoc works this way even when the markdown_strict format is
2385 specified. This behavior is consistent with the official Markdown syn‐
2386 tax description, even though it is different from that of Markdown.pl.)
2387 Ending a list
2389 What if you want to put an indented code block after a list?
2390 - item one
2392 - item two
2393 { my code block }
2395 Trouble! Here pandoc (like other Markdown implementations) will treat
2397 { my code block } as the second paragraph of item two, and not as a
2398 code block.
2399 To "cut off" the list after item two, you can insert some non-indented
2401 content, like an HTML comment, which won't produce visible output in
2402 any format:
2403 - item one
2405 - item two
2406 <!-- end of list -->
2408 { my code block }
2410 You can use the same trick if you want two consecutive lists instead of
2412 one big list:
2413 1. one
2415 2. two
2416 3. three
2417 <!-- -->
2419 1. uno
2421 2. dos
2422 3. tres
2423 Horizontal rules
2425 A line containing a row of three or more *, -, or _ characters (option‐
2426 ally separated by spaces) produces a horizontal rule:
2427 * * * *
2429 ---------------
2431 Tables
2433 Four kinds of tables may be used. The first three kinds presuppose the
2434 use of a fixed-width font, such as Courier. The fourth kind can be
2435 used with proportionally spaced fonts, as it does not require lining up
2436 columns.
2437 Extension: table_captions
2439 A caption may optionally be provided with all 4 kinds of tables (as
2440 illustrated in the examples below). A caption is a paragraph beginning
2441 with the string Table: (or just :), which will be stripped off. It may
2442 appear either before or after the table.
2443 Extension: simple_tables
2445 Simple tables look like this:
2446 Right Left Center Default
2448 ------- ------ ---------- -------
2449 12 12 12 12
2450 123 123 123 123
2451 1 1 1 1
2452 Table: Demonstration of simple table syntax.
2454 The headers and table rows must each fit on one line. Column align‐
2456 ments are determined by the position of the header text relative to the
2457 dashed line below it:
2458 · If the dashed line is flush with the header text on the right side
2460 but extends beyond it on the left, the column is right-aligned.
2461 · If the dashed line is flush with the header text on the left side but
2463 extends beyond it on the right, the column is left-aligned.
2464 · If the dashed line extends beyond the header text on both sides, the
2466 column is centered.
2467 · If the dashed line is flush with the header text on both sides, the
2469 default alignment is used (in most cases, this will be left).
2470 The table must end with a blank line, or a line of dashes followed by a
2472 blank line.
2473 The column headers may be omitted, provided a dashed line is used to
2475 end the table. For example:
2476 ------- ------ ---------- -------
2478 12 12 12 12
2479 123 123 123 123
2480 1 1 1 1
2481 ------- ------ ---------- -------
2482 When headers are omitted, column alignments are determined on the basis
2484 of the first line of the table body. So, in the tables above, the col‐
2485 umns would be right, left, center, and right aligned, respectively.
2486 Extension: multiline_tables
2488 Multiline tables allow headers and table rows to span multiple lines of
2489 text (but cells that span multiple columns or rows of the table are not
2490 supported). Here is an example:
2491 -------------------------------------------------------------
2493 Centered Default Right Left
2494 Header Aligned Aligned Aligned
2495 ----------- ------- --------------- -------------------------
2496 First row 12.0 Example of a row that
2497 spans multiple lines.
2498 Second row 5.0 Here's another one. Note
2500 the blank line between
2501 rows.
2502 -------------------------------------------------------------
2503 Table: Here's the caption. It, too, may span
2505 multiple lines.
2506 These work like simple tables, but with the following differences:
2508 · They must begin with a row of dashes, before the header text (unless
2510 the headers are omitted).
2511 · They must end with a row of dashes, then a blank line.
2513 · The rows must be separated by blank lines.
2515 In multiline tables, the table parser pays attention to the widths of
2517 the columns, and the writers try to reproduce these relative widths in
2518 the output. So, if you find that one of the columns is too narrow in
2519 the output, try widening it in the Markdown source.
2520 Headers may be omitted in multiline tables as well as simple tables:
2522 ----------- ------- --------------- -------------------------
2524 First row 12.0 Example of a row that
2525 spans multiple lines.
2526 Second row 5.0 Here's another one. Note
2528 the blank line between
2529 rows.
2530 ----------- ------- --------------- -------------------------
2531 : Here's a multiline table without headers.
2533 It is possible for a multiline table to have just one row, but the row
2535 should be followed by a blank line (and then the row of dashes that
2536 ends the table), or the table may be interpreted as a simple table.
2537 Extension: grid_tables
2539 Grid tables look like this:
2540 : Sample grid table.
2542 +---------------+---------------+--------------------+
2544 | Fruit | Price | Advantages |
2545 +===============+===============+====================+
2546 | Bananas | $1.34 | - built-in wrapper |
2547 | | | - bright color |
2548 +---------------+---------------+--------------------+
2549 | Oranges | $2.10 | - cures scurvy |
2550 | | | - tasty |
2551 +---------------+---------------+--------------------+
2552 The row of =s separates the header from the table body, and can be
2554 omitted for a headerless table. The cells of grid tables may contain
2555 arbitrary block elements (multiple paragraphs, code blocks, lists,
2556 etc.). Cells that span multiple columns or rows are not supported.
2557 Grid tables can be created easily using Emacs table mode.
2558 Alignments can be specified as with pipe tables, by putting colons at
2560 the boundaries of the separator line after the header:
2561 +---------------+---------------+--------------------+
2563 | Right | Left | Centered |
2564 +==============:+:==============+:==================:+
2565 | Bananas | $1.34 | built-in wrapper |
2566 +---------------+---------------+--------------------+
2567 For headerless tables, the colons go on the top line instead:
2569 +--------------:+:--------------+:------------------:+
2571 | Right | Left | Centered |
2572 +---------------+---------------+--------------------+
2573 Grid Table Limitations
2575 Pandoc does not support grid tables with row spans or column spans.
2576 This means that neither variable numbers of columns across rows nor
2577 variable numbers of rows across columns are supported by Pandoc. All
2578 grid tables must have the same number of columns in each row, and the
2579 same number of rows in each column. For example, the Docutils sample
2580 grid tables will not render as expected with Pandoc.
2581 Extension: pipe_tables
2583 Pipe tables look like this:
2584 | Right | Left | Default | Center |
2586 |------:|:-----|---------|:------:|
2587 | 12 | 12 | 12 | 12 |
2588 | 123 | 123 | 123 | 123 |
2589 | 1 | 1 | 1 | 1 |
2590 : Demonstration of pipe table syntax.
2592 The syntax is identical to PHP Markdown Extra tables. The beginning
2594 and ending pipe characters are optional, but pipes are required between
2595 all columns. The colons indicate column alignment as shown. The
2596 header cannot be omitted. To simulate a headerless table, include a
2597 header with blank cells.
2598 Since the pipes indicate column boundaries, columns need not be verti‐
2600 cally aligned, as they are in the above example. So, this is a per‐
2601 fectly legal (though ugly) pipe table:
2602 fruit| price
2604 -----|-----:
2605 apple|2.05
2606 pear|1.37
2607 orange|3.09
2608 The cells of pipe tables cannot contain block elements like paragraphs
2610 and lists, and cannot span multiple lines. If a pipe table contains a
2611 row whose printable content is wider than the column width (see --col‐
2612 umns), then the table will take up the full text width and the cell
2613 contents will wrap, with the relative cell widths determined by the
2614 number of dashes in the line separating the table header from the table
2615 body. (For example ---|- would make the first column 3/4 and the sec‐
2616 ond column 1/4 of the full text width.) On the other hand, if no lines
2617 are wider than column width, then cell contents will not be wrapped,
2618 and the cells will be sized to their contents.
2619 Note: pandoc also recognizes pipe tables of the following form, as can
2621 be produced by Emacs' orgtbl-mode:
2622 | One | Two |
2624 |-----+-------|
2625 | my | table |
2626 | is | nice |
2627 The difference is that + is used instead of |. Other orgtbl features
2629 are not supported. In particular, to get non-default column alignment,
2630 you'll need to add colons as above.
2631 Metadata blocks
2633 Extension: pandoc_title_block
2634 If the file begins with a title block
2635 % title
2637 % author(s) (separated by semicolons)
2638 % date
2639 it will be parsed as bibliographic information, not regular text. (It
2641 will be used, for example, in the title of standalone LaTeX or HTML
2642 output.) The block may contain just a title, a title and an author, or
2643 all three elements. If you want to include an author but no title, or
2644 a title and a date but no author, you need a blank line:
2645 %
2647 % Author
2648 % My title
2650 %
2651 % June 15, 2006
2652 The title may occupy multiple lines, but continuation lines must begin
2654 with leading space, thus:
2655 % My title
2657 on multiple lines
2658 If a document has multiple authors, the authors may be put on separate
2660 lines with leading space, or separated by semicolons, or both. So, all
2661 of the following are equivalent:
2662 % Author One
2664 Author Two
2665 % Author One; Author Two
2667 % Author One;
2669 Author Two
2670 The date must fit on one line.
2672 All three metadata fields may contain standard inline formatting (ital‐
2674 ics, links, footnotes, etc.).
2675 Title blocks will always be parsed, but they will affect the output
2677 only when the --standalone (-s) option is chosen. In HTML output,
2678 titles will appear twice: once in the document head -- this is the
2679 title that will appear at the top of the window in a browser -- and
2680 once at the beginning of the document body. The title in the document
2681 head can have an optional prefix attached (--title-prefix or -T
2682 option). The title in the body appears as an H1 element with class
2683 "title", so it can be suppressed or reformatted with CSS. If a title
2684 prefix is specified with -T and no title block appears in the document,
2685 the title prefix will be used by itself as the HTML title.
2686 The man page writer extracts a title, man page section number, and
2688 other header and footer information from the title line. The title is
2689 assumed to be the first word on the title line, which may optionally
2690 end with a (single-digit) section number in parentheses. (There should
2691 be no space between the title and the parentheses.) Anything after
2692 this is assumed to be additional footer and header text. A single pipe
2693 character (|) should be used to separate the footer text from the
2694 header text. Thus,
2695 % PANDOC(1)
2697 will yield a man page with the title PANDOC and section 1.
2699 % PANDOC(1) Pandoc User Manuals
2701 will also have "Pandoc User Manuals" in the footer.
2703 % PANDOC(1) Pandoc User Manuals | Version 4.0
2705 will also have "Version 4.0" in the header.
2707 Extension: yaml_metadata_block
2709 A YAML metadata block is a valid YAML object, delimited by a line of
2710 three hyphens (---) at the top and a line of three hyphens (---) or
2711 three dots (...) at the bottom. A YAML metadata block may occur any‐
2712 where in the document, but if it is not at the beginning, it must be
2713 preceded by a blank line. (Note that, because of the way pandoc con‐
2714 catenates input files when several are provided, you may also keep the
2715 metadata in a separate YAML file and pass it to pandoc as an argument,
2716 along with your Markdown files:
2717 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
2719 Just be sure that the YAML file begins with --- and ends with --- or
2721 ....)
2722 Metadata will be taken from the fields of the YAML object and added to
2724 any existing document metadata. Metadata can contain lists and objects
2725 (nested arbitrarily), but all string scalars will be interpreted as
2726 Markdown. Fields with names ending in an underscore will be ignored by
2727 pandoc. (They may be given a role by external processors.)
2728 A document may contain multiple metadata blocks. The metadata fields
2730 will be combined through a left-biased union: if two metadata blocks
2731 attempt to set the same field, the value from the first block will be
2732 taken.
2733 When pandoc is used with -t markdown to create a Markdown document, a
2735 YAML metadata block will be produced only if the -s/--standalone option
2736 is used. All of the metadata will appear in a single block at the
2737 beginning of the document.
2738 Note that YAML escaping rules must be followed. Thus, for example, if
2740 a title contains a colon, it must be quoted. The pipe character (|)
2741 can be used to begin an indented block that will be interpreted liter‐
2742 ally, without need for escaping. This form is necessary when the field
2743 contains blank lines or block-level formatting:
2744 ---
2746 title: 'This is the title: it contains a colon'
2747 author:
2748 - Author One
2749 - Author Two
2750 tags: [nothing, nothingness]
2751 abstract: |
2752 This is the abstract.
2753 It consists of two paragraphs.
2755 ...
2756 Template variables will be set automatically from the metadata. Thus,
2758 for example, in writing HTML, the variable abstract will be set to the
2759 HTML equivalent of the Markdown in the abstract field:
2760 <p>This is the abstract.</p>
2762 <p>It consists of two paragraphs.</p>
2763 Variables can contain arbitrary YAML structures, but the template must
2765 match this structure. The author variable in the default templates
2766 expects a simple list or string, but can be changed to support more
2767 complicated structures. The following combination, for example, would
2768 add an affiliation to the author if one is given:
2769 ---
2771 title: The document title
2772 author:
2773 - name: Author One
2774 affiliation: University of Somewhere
2775 - name: Author Two
2776 affiliation: University of Nowhere
2777 ...
2778 To use the structured authors in the example above, you would need a
2780 custom template:
2781 $for(author)$
2783 $if(author.name)$
2784 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
2785 $else$
2786 $author$
2787 $endif$
2788 $endfor$
2789 Raw content to include in the document's header may be specified using
2791 header-includes; however, it is important to mark up this content as
2792 raw code for a particular output format, using the raw_attribute exten‐
2793 sion), or it will be interpreted as markdown. For example:
2794 header-includes:
2796 - |
2797 ```{=latex}
2798 \let\oldsection\section
2799 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
2800 ```
2801 Backslash escapes
2803 Extension: all_symbols_escapable
2804 Except inside a code block or inline code, any punctuation or space
2805 character preceded by a backslash will be treated literally, even if it
2806 would normally indicate formatting. Thus, for example, if one writes
2807 *\*hello\**
2809 one will get
2811 <em>*hello*</em>
2813 instead of
2815 <strong>hello</strong>
2817 This rule is easier to remember than standard Markdown's rule, which
2819 allows only the following characters to be backslash-escaped:
2820 \`*_{}[]()>#+-.!
2822 (However, if the markdown_strict format is used, the standard Markdown
2824 rule will be used.)
2825 A backslash-escaped space is parsed as a nonbreaking space. It will
2827 appear in TeX output as ~ and in HTML and XML as \  or \ .
2828 A backslash-escaped newline (i.e. a backslash occurring at the end of
2830 a line) is parsed as a hard line break. It will appear in TeX output
2831 as \\ and in HTML as <br />. This is a nice alternative to Markdown's
2832 "invisible" way of indicating hard line breaks using two trailing spa‐
2833 ces on a line.
2834 Backslash escapes do not work in verbatim contexts.
2836 Inline formatting
2838 Emphasis
2839 To emphasize some text, surround it with *s or _, like this:
2840 This text is _emphasized with underscores_, and this
2842 is *emphasized with asterisks*.
2843 Double * or _ produces strong emphasis:
2845 This is **strong emphasis** and __with underscores__.
2847 A * or _ character surrounded by spaces, or backslash-escaped, will not
2849 trigger emphasis:
2850 This is * not emphasized *, and \*neither is this\*.
2852 Extension: intraword_underscores
2854 Because _ is sometimes used inside words and identifiers, pandoc does
2855 not interpret a _ surrounded by alphanumeric characters as an emphasis
2856 marker. If you want to emphasize just part of a word, use *:
2857 feas*ible*, not feas*able*.
2859 Strikeout
2861 Extension: strikeout
2862 To strikeout a section of text with a horizontal line, begin and end it
2863 with ~~. Thus, for example,
2864 This ~~is deleted text.~~
2866 Superscripts and subscripts
2868 Extension: superscript, subscript
2869 Superscripts may be written by surrounding the superscripted text by ^
2870 characters; subscripts may be written by surrounding the subscripted
2871 text by ~ characters. Thus, for example,
2872 H~2~O is a liquid. 2^10^ is 1024.
2874 If the superscripted or subscripted text contains spaces, these spaces
2876 must be escaped with backslashes. (This is to prevent accidental
2877 superscripting and subscripting through the ordinary use of ~ and ^.)
2878 Thus, if you want the letter P with 'a cat' in subscripts, use
2879 P~a\ cat~, not P~a cat~.
2880 Verbatim
2882 To make a short span of text verbatim, put it inside backticks:
2883 What is the difference between `>>=` and `>>`?
2885 If the verbatim text includes a backtick, use double backticks:
2887 Here is a literal backtick `` ` ``.
2889 (The spaces after the opening backticks and before the closing back‐
2891 ticks will be ignored.)
2892 The general rule is that a verbatim span starts with a string of con‐
2894 secutive backticks (optionally followed by a space) and ends with a
2895 string of the same number of backticks (optionally preceded by a
2896 space).
2897 Note that backslash-escapes (and other Markdown constructs) do not work
2899 in verbatim contexts:
2900 This is a backslash followed by an asterisk: `\*`.
2902 Extension: inline_code_attributes
2904 Attributes can be attached to verbatim text, just as with fenced code
2905 blocks:
2906 `<$>`{.haskell}
2908 Small caps
2910 To write small caps, use the smallcaps class:
2911 [Small caps]{.smallcaps}
2913 Or, without the bracketed_spans extension:
2915 <span class="smallcaps">Small caps</span>
2917 For compatibility with other Markdown flavors, CSS is also supported:
2919 <span style="font-variant:small-caps;">Small caps</span>
2921 This will work in all output formats that support small caps.
2923 Math
2925 Extension: tex_math_dollars
2926 Anything between two $ characters will be treated as TeX math. The
2927 opening $ must have a non-space character immediately to its right,
2928 while the closing $ must have a non-space character immediately to its
2929 left, and must not be followed immediately by a digit. Thus,
2930 $20,000 and $30,000 won't parse as math. If for some reason you need
2931 to enclose text in literal $ characters, backslash-escape them and they
2932 won't be treated as math delimiters.
2933 TeX math will be printed in all output formats. How it is rendered
2935 depends on the output format:
2936 Markdown, LaTeX, Emacs Org mode, ConTeXt, ZimWiki
2938 It will appear verbatim between $ characters.
2939 reStructuredText
2941 It will be rendered using an interpreted text role :math:.
2942 AsciiDoc
2944 It will be rendered as latexmath:[...].
2945 Texinfo
2947 It will be rendered inside a @math command.
2948 groff man
2950 It will be rendered verbatim without $'s.
2951 MediaWiki, DokuWiki
2953 It will be rendered inside <math> tags.
2954 Textile
2956 It will be rendered inside <span class="math"> tags.
2957 RTF, OpenDocument
2959 It will be rendered, if possible, using Unicode characters, and
2960 will otherwise appear verbatim.
2961 ODT It will be rendered, if possible, using MathML.
2963 DocBook
2965 If the --mathml flag is used, it will be rendered using MathML
2966 in an inlineequation or informalequation tag. Otherwise it will
2967 be rendered, if possible, using Unicode characters.
2968 Docx It will be rendered using OMML math markup.
2970 FictionBook2
2972 If the --webtex option is used, formulas are rendered as images
2973 using CodeCogs or other compatible web service, downloaded and
2974 embedded in the e-book. Otherwise, they will appear verbatim.
2975 HTML, Slidy, DZSlides, S5, EPUB
2977 The way math is rendered in HTML will depend on the command-line
2978 options selected. Therefore see Math rendering in HTML above.
2979 Raw HTML
2981 Extension: raw_html
2982 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
2983 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
2984 erally). (Technically this is not an extension, since standard Mark‐
2985 down allows it, but it has been made an extension so that it can be
2986 disabled if desired.)
2987 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
2989 DZSlides, EPUB, Markdown, Emacs Org mode, and Textile output, and sup‐
2990 pressed in other formats.
2991 Extension: markdown_in_html_blocks
2993 Standard Markdown allows you to include HTML "blocks": blocks of HTML
2994 between balanced tags that are separated from the surrounding text with
2995 blank lines, and start and end at the left margin. Within these
2996 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
2997 ple), * does not signify emphasis.
2998 Pandoc behaves this way when the markdown_strict format is used; but by
3000 default, pandoc interprets material between HTML block tags as Mark‐
3001 down. Thus, for example, pandoc will turn
3002 <table>
3004 <tr>
3005 <td>*one*</td>
3006 <td>[a link](http://google.com)</td>
3007 </tr>
3008 </table>
3009 into
3011 <table>
3013 <tr>
3014 <td><em>one</em></td>
3015 <td><a href="http://google.com">a link</a></td>
3016 </tr>
3017 </table>
3018 whereas Markdown.pl will preserve it as is.
3020 There is one exception to this rule: text between <script> and <style>
3022 tags is not interpreted as Markdown.
3023 This departure from standard Markdown should make it easier to mix
3025 Markdown with HTML block elements. For example, one can surround a
3026 block of Markdown text with <div> tags without preventing it from being
3027 interpreted as Markdown.
3028 Extension: native_divs
3030 Use native pandoc Div blocks for content inside <div> tags. For the
3031 most part this should give the same output as markdown_in_html_blocks,
3032 but it makes it easier to write pandoc filters to manipulate groups of
3033 blocks.
3034 Extension: native_spans
3036 Use native pandoc Span blocks for content inside <span> tags. For the
3037 most part this should give the same output as raw_html, but it makes it
3038 easier to write pandoc filters to manipulate groups of inlines.
3039 Extension: raw_tex
3041 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
3042 be included in a document. Inline TeX commands will be preserved and
3043 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
3044 you can use LaTeX to include BibTeX citations:
3045 This result was proved in \cite{jones.1967}.
3047 Note that in LaTeX environments, like
3049 \begin{tabular}{|l|l|}\hline
3051 Age & Frequency \\ \hline
3052 18--25 & 15 \\
3053 26--35 & 33 \\
3054 36--45 & 22 \\ \hline
3055 \end{tabular}
3056 the material between the begin and end tags will be interpreted as raw
3058 LaTeX, not as Markdown.
3059 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
3061 Emacs Org mode, and ConTeXt.
3062 Generic raw attribute
3064 Extension: raw_attribute
3065 Inline spans and fenced code blocks with a special kind of attribute
3066 will be parsed as raw content with the designated format. For example,
3067 the following produces a raw groff ms block:
3068 ```{=ms}
3070 .MYMACRO
3071 blah blah
3072 ```
3073 And the following produces a raw html inline element:
3075 This is `<a>html</a>`{=html}
3077 This can be useful to insert raw xml into docx documents, e.g. a page‐
3079 break:
3080 ```{=openxml}
3082 <w:p>
3083 <w:r>
3084 <w:br w:type="page"/>
3085 </w:r>
3086 </w:p>
3087 ```
3088 The format name should match the target format name (see -t/--to,
3090 above, for a list, or use pandoc --list-output-formats). Use openxml
3091 for docx output, opendocument for odt output, html5 for epub3 output,
3092 html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output
3093 (depending on what you use for --pdf-engine).
3094 This extension presupposes that the relevant kind of inline code or
3096 fenced code block is enabled. Thus, for example, to use a raw
3097 attribute with a backtick code block, backtick_code_blocks must be
3098 enabled.
3099 The raw attribute cannot be combined with regular attributes.
3101 LaTeX macros
3103 Extension: latex_macros
3104 For output formats other than LaTeX, pandoc will parse LaTeX macro def‐
3105 initions and apply the resulting macros to all LaTeX math and raw
3106 LaTeX. So, for example, the following will work in all output formats,
3107 not just LaTeX:
3108 \newcommand{\tuple}[1]{\langle #1 \rangle}
3110 $\tuple{a, b, c}$
3112 Note that LaTeX macros will not be applied if they occur inside inside
3114 a raw span or block marked with the raw_attribute extension.
3115 When latex_macros is disabled, the raw LaTeX and math will not have
3117 macros applied. This is usually a better approach when you are target‐
3118 ing LaTeX or PDF.
3119 Whether or not latex_macros is enabled, the macro definitions will
3121 still be passed through as raw LaTeX.
3122 Links
3124 Markdown allows links to be specified in several ways.
3125 Automatic links
3127 If you enclose a URL or email address in pointy brackets, it will
3128 become a link:
3129 <http://google.com>
3131 <sam@green.eggs.ham>
3132 Inline links
3134 An inline link consists of the link text in square brackets, followed
3135 by the URL in parentheses. (Optionally, the URL can be followed by a
3136 link title, in quotes.)
3137 This is an [inline link](/url), and here's [one with
3139 a title](http://fsf.org "click here for a good time!").
3140 There can be no space between the bracketed part and the parenthesized
3142 part. The link text can contain formatting (such as emphasis), but the
3143 title cannot.
3144 Email addresses in inline links are not autodetected, so they have to
3146 be prefixed with mailto:
3147 [Write me!](mailto:sam@green.eggs.ham)
3149 Reference links
3151 An explicit reference link has two parts, the link itself and the link
3152 definition, which may occur elsewhere in the document (either before or
3153 after the link).
3154 The link consists of link text in square brackets, followed by a label
3156 in square brackets. (There cannot be space between the two unless the
3157 spaced_reference_links extension is enabled.) The link definition con‐
3158 sists of the bracketed label, followed by a colon and a space, followed
3159 by the URL, and optionally (after a space) a link title either in
3160 quotes or in parentheses. The label must not be parseable as a cita‐
3161 tion (assuming the citations extension is enabled): citations take
3162 precedence over link labels.
3163 Here are some examples:
3165 [my label 1]: /foo/bar.html "My title, optional"
3167 [my label 2]: /foo
3168 [my label 3]: http://fsf.org (The free software foundation)
3169 [my label 4]: /bar#special 'A title in single quotes'
3170 The URL may optionally be surrounded by angle brackets:
3172 [my label 5]: <http://foo.bar.baz>
3174 The title may go on the next line:
3176 [my label 3]: http://fsf.org
3178 "The free software foundation"
3179 Note that link labels are not case sensitive. So, this will work:
3181 Here is [my link][FOO]
3183 [Foo]: /bar/baz
3185 In an implicit reference link, the second pair of brackets is empty:
3187 See [my website][].
3189 [my website]: http://foo.bar.baz
3191 Note: In Markdown.pl and most other Markdown implementations, reference
3193 link definitions cannot occur in nested constructions such as list
3194 items or block quotes. Pandoc lifts this arbitrary seeming restric‐
3195 tion. So the following is fine in pandoc, though not in most other
3196 implementations:
3197 > My block [quote].
3199 >
3200 > [quote]: /foo
3201 Extension: shortcut_reference_links
3203 In a shortcut reference link, the second pair of brackets may be omit‐
3204 ted entirely:
3205 See [my website].
3207 [my website]: http://foo.bar.baz
3209 Internal links
3211 To link to another section of the same document, use the automatically
3212 generated identifier (see Header identifiers). For example:
3213 See the [Introduction](#introduction).
3215 or
3217 See the [Introduction].
3219 [Introduction]: #introduction
3221 Internal links are currently supported for HTML formats (including HTML
3223 slide shows and EPUB), LaTeX, and ConTeXt.
3224 Images
3226 A link immediately preceded by a ! will be treated as an image. The
3227 link text will be used as the image's alt text:
3228 
3230 ![movie reel]
3232 [movie reel]: movie.gif
3234 Extension: implicit_figures
3236 An image with nonempty alt text, occurring by itself in a paragraph,
3237 will be rendered as a figure with a caption. The image's alt text will
3238 be used as the caption.
3239 
3241 How this is rendered depends on the output format. Some output formats
3243 (e.g. RTF) do not yet support figures. In those formats, you'll just
3244 get an image in a paragraph by itself, with no caption.
3245 If you just want a regular inline image, just make sure it is not the
3247 only thing in the paragraph. One way to do this is to insert a non‐
3248 breaking space after the image:
3249 \
3251 Note that in reveal.js slide shows, an image in a paragraph by itself
3253 that has the stretch class will fill the screen, and the caption and
3254 figure tags will be omitted.
3255 Extension: link_attributes
3257 Attributes can be set on links and images:
3258 An inline {#id .class width=30 height=20px}
3260 and a reference ![image][ref] with attributes.
3261 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
3263 (This syntax is compatible with PHP Markdown Extra when only #id and
3265 .class are used.)
3266 For HTML and EPUB, all attributes except width and height (but includ‐
3268 ing srcset and sizes) are passed through as is. The other writers
3269 ignore attributes that are not supported by their output format.
3270 The width and height attributes on images are treated specially. When
3272 used without a unit, the unit is assumed to be pixels. However, any of
3273 the following unit identifiers can be used: px, cm, mm, in, inch and %.
3274 There must not be any spaces between the number and the unit. For
3275 example:
3276 { width=50% }
3278 · Dimensions are converted to inches for output in page-based formats
3280 like LaTeX. Dimensions are converted to pixels for output in
3281 HTML-like formats. Use the --dpi option to specify the number of
3282 pixels per inch. The default is 96dpi.
3283 · The % unit is generally relative to some available space. For exam‐
3285 ple the above example will render to
3286 <img href="file.jpg" style="width: 50%;" /> (HTML), \includegraph‐
3287 ics[width=0.5\textwidth]{file.jpg} (LaTeX), or \externalfig‐
3288 ure[file.jpg][width=0.5\textwidth] (ConTeXt).
3289 · Some output formats have a notion of a class (ConTeXt) or a unique
3291 identifier (LaTeX \caption), or both (HTML).
3292 · When no width or height attributes are specified, the fallback is to
3294 look at the image resolution and the dpi metadata embedded in the
3295 image file.
3296 Divs and Spans
3298 Using the native_divs and native_spans extensions (see above), HTML
3299 syntax can be used as part of markdown to create native Div and Span
3300 elements in the pandoc AST (as opposed to raw HTML). However, there is
3301 also nicer syntax available:
3302 Extension: fenced_divs
3304 Allow special fenced syntax for native Div blocks. A Div starts with a
3305 fence containing at least three consecutive colons plus some
3306 attributes. The attributes may optionally be followed by another
3307 string of consecutive colons. The attribute syntax is exactly as in
3308 fenced code blocks (see Extension: fenced_code_attributes). As with
3309 fenced code blocks, one can use either attributes in curly braces or a
3310 single unbraced word, which will be treated as a class name. The Div
3311 ends with another line containing a string of at least three consecu‐
3312 tive colons. The fenced Div should be separated by blank lines from
3313 preceding and following blocks.
3314 Example:
3316 ::::: {#special .sidebar}
3318 Here is a paragraph.
3319 And another.
3321 :::::
3322 Fenced divs can be nested. Opening fences are distinguished because
3324 they must have attributes:
3325 ::: Warning ::::::
3327 This is a warning.
3328 ::: Danger
3330 This is a warning within a warning.
3331 :::
3332 ::::::::::::::::::
3333 Fences without attributes are always closing fences. Unlike with
3335 fenced code blocks, the number of colons in the closing fence need not
3336 match the number in the opening fence. However, it can be helpful for
3337 visual clarity to use fences of different lengths to distinguish nested
3338 divs from their parents.
3339 Extension: bracketed_spans
3341 A bracketed sequence of inlines, as one would use to begin a link, will
3342 be treated as a Span with attributes if it is followed immediately by
3343 attributes:
3344 [This is *some text*]{.class key="val"}
3346 Footnotes
3348 Extension: footnotes
3349 Pandoc's Markdown allows footnotes, using the following syntax:
3350 Here is a footnote reference,[^1] and another.[^longnote]
3352 [^1]: Here is the footnote.
3354 [^longnote]: Here's one with multiple blocks.
3356 Subsequent paragraphs are indented to show that they
3358 belong to the previous footnote.
3359 { some.code }
3361 The whole paragraph can be indented, or just the first
3363 line. In this way, multi-paragraph footnotes work like
3364 multi-paragraph list items.
3365 This paragraph won't be part of the note, because it
3367 isn't indented.
3368 The identifiers in footnote references may not contain spaces, tabs, or
3370 newlines. These identifiers are used only to correlate the footnote
3371 reference with the note itself; in the output, footnotes will be num‐
3372 bered sequentially.
3373 The footnotes themselves need not be placed at the end of the document.
3375 They may appear anywhere except inside other block elements (lists,
3376 block quotes, tables, etc.). Each footnote should be separated from
3377 surrounding content (including other footnotes) by blank lines.
3378 Extension: inline_notes
3380 Inline footnotes are also allowed (though, unlike regular notes, they
3381 cannot contain multiple paragraphs). The syntax is as follows:
3382 Here is an inline note.^[Inlines notes are easier to write, since
3384 you don't have to pick an identifier and move down to type the
3385 note.]
3386 Inline and regular footnotes may be mixed freely.
3388 Citations
3390 Extension: citations
3391 Using an external filter, pandoc-citeproc, pandoc can automatically
3392 generate citations and a bibliography in a number of styles. Basic
3393 usage is
3394 pandoc --filter pandoc-citeproc myinput.txt
3396 In order to use this feature, you will need to specify a bibliography
3398 file using the bibliography metadata field in a YAML metadata section,
3399 or --bibliography command line argument. You can supply multiple
3400 --bibliography arguments or set bibliography metadata field to YAML
3401 array, if you want to use multiple bibliography files. The bibliogra‐
3402 phy may have any of these formats:
3403 Format File extension
3405 ─────────────────────────────
3406 BibLaTeX .bib
3407 BibTeX .bibtex
3409 Copac .copac
3410 CSL JSON .json
3411 CSL YAML .yaml
3412 EndNote .enl
3413 EndNote XML .xml
3414 ISI .wos
3415 MEDLINE .medline
3416 MODS .mods
3417 RIS .ris
3418 Note that .bib can be used with both BibTeX and BibLaTeX files; use
3420 .bibtex to force BibTeX.
3421 Note that pandoc-citeproc --bib2json and pandoc-citeproc --bib2yaml can
3423 produce .json and .yaml files from any of the supported formats.
3424 In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
3426 parses a subset of LaTeX markup; in CSL YAML databases, pandoc Mark‐
3427 down; and in CSL JSON databases, an HTML-like markup:
3428 <i>...</i>
3430 italics
3431 <b>...</b>
3433 bold
3434 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
3436 small capitals
3437 <sub>...</sub>
3439 subscript
3440 <sup>...</sup>
3442 superscript
3443 <span class="nocase">...</span>
3445 prevent a phrase from being capitalized as title case
3446 pandoc-citeproc -j and -y interconvert the CSL JSON and CSL YAML for‐
3448 mats as far as possible.
3449 As an alternative to specifying a bibliography file using --bibliogra‐
3451 phy or the YAML metadata field bibliography, you can include the cita‐
3452 tion data directly in the references field of the document's YAML meta‐
3453 data. The field should contain an array of YAML-encoded references,
3454 for example:
3455 ---
3457 references:
3458 - type: article-journal
3459 id: WatsonCrick1953
3460 author:
3461 - family: Watson
3462 given: J. D.
3463 - family: Crick
3464 given: F. H. C.
3465 issued:
3466 date-parts:
3467 - - 1953
3468 - 4
3469 - 25
3470 title: 'Molecular structure of nucleic acids: a structure for deoxyribose
3471 nucleic acid'
3472 title-short: Molecular structure of nucleic acids
3473 container-title: Nature
3474 volume: 171
3475 issue: 4356
3476 page: 737-738
3477 DOI: 10.1038/171737a0
3478 URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
3479 language: en-GB
3480 ...
3481 (pandoc-citeproc --bib2yaml can produce these from a bibliography file
3483 in one of the supported formats.)
3484 Citations and references can be formatted using any style supported by
3486 the Citation Style Language, listed in the Zotero Style Repository.
3487 These files are specified using the --csl option or the csl metadata
3488 field. By default, pandoc-citeproc will use the Chicago Manual of
3489 Style author-date format. The CSL project provides further information
3490 on finding and editing styles.
3491 To make your citations hyperlinks to the corresponding bibliography
3493 entries, add link-citations: true to your YAML metadata.
3494 Citations go inside square brackets and are separated by semicolons.
3496 Each citation must have a key, composed of '@' + the citation identi‐
3497 fier from the database, and may optionally have a prefix, a locator,
3498 and a suffix. The citation key must begin with a letter, digit, or _,
3499 and may contain alphanumerics, _, and internal punctuation characters
3500 (:.#$%&-+?<>~/). Here are some examples:
3501 Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
3503 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
3505 Blah blah [@smith04; @doe99].
3507 pandoc-citeproc detects locator terms in the CSL locale files. Either
3509 abbreviated or unabbreviated forms are accepted. In the en-US locale,
3510 locator terms can be written in either singular or plural forms, as
3511 book, bk./bks.; chapter, chap./chaps.; column, col./cols.; figure,
3512 fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note,
3513 n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part,
3514 pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.;
3515 volume, vol./vols.; ¶/¶¶; §/§§. If no locator term is used, "page" is
3516 assumed.
3517 A minus sign (-) before the @ will suppress mention of the author in
3519 the citation. This can be useful when the author is already mentioned
3520 in the text:
3521 Smith says blah [-@smith04].
3523 You can also write an in-text citation, as follows:
3525 @smith04 says blah.
3527 @smith04 [p. 33] says blah.
3529 If the style calls for a list of works cited, it will be placed at the
3531 end of the document. Normally, you will want to end your document with
3532 an appropriate header:
3533 last paragraph...
3535 # References
3537 The bibliography will be inserted after this header. Note that the
3539 unnumbered class will be added to this header, so that the section will
3540 not be numbered.
3541 If you want to include items in the bibliography without actually cit‐
3543 ing them in the body text, you can define a dummy nocite metadata field
3544 and put the citations there:
3545 ---
3547 nocite: |
3548 @item1, @item2
3549 ...
3550 @item3
3552 In this example, the document will contain a citation for item3 only,
3554 but the bibliography will contain entries for item1, item2, and item3.
3555 It is possible to create a bibliography with all the citations, whether
3557 or not they appear in the document, by using a wildcard:
3558 ---
3560 nocite: |
3561 @*
3562 ...
3563 For LaTeX or PDF output, you can also use natbib or biblatex to render
3565 bibliography. In order to do so, specify bibliography files as out‐
3566 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
3567 tion. Bear in mind that bibliography files have to be in respective
3568 format (either BibTeX or BibLaTeX).
3569 For more information, see the pandoc-citeproc man page.
3571 Non-pandoc extensions
3573 The following Markdown syntax extensions are not enabled by default in
3574 pandoc, but may be enabled by adding +EXTENSION to the format name,
3575 where EXTENSION is the name of the extension. Thus, for example, mark‐
3576 down+hard_line_breaks is Markdown with hard line breaks.
3577 Extension: old_dashes
3579 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: -
3580 before a numeral is an en-dash, and -- is an em-dash. This option only
3581 has an effect if smart is enabled. It is selected automatically for
3582 textile input.
3583 Extension: angle_brackets_escapable
3585 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
3586 vored Markdown but not original Markdown. This is implied by pandoc's
3587 default all_symbols_escapable.
3588 Extension: lists_without_preceding_blankline
3590 Allow a list to occur right after a paragraph, with no intervening
3591 blank space.
3592 Extension: four_space_rule
3594 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
3595 ces indent are needed for list item continuation paragraphs.
3596 Extension: spaced_reference_links
3598 Allow whitespace between the two components of a reference link, for
3599 example,
3600 [foo] [bar].
3602 Extension: hard_line_breaks
3604 Causes all newlines within a paragraph to be interpreted as hard line
3605 breaks instead of spaces.
3606 Extension: ignore_line_breaks
3608 Causes newlines within a paragraph to be ignored, rather than being
3609 treated as spaces or as hard line breaks. This option is intended for
3610 use with East Asian languages where spaces are not used between words,
3611 but text is divided into lines for readability.
3612 Extension: east_asian_line_breaks
3614 Causes newlines within a paragraph to be ignored, rather than being
3615 treated as spaces or as hard line breaks, when they occur between two
3616 East Asian wide characters. This is a better choice than
3617 ignore_line_breaks for texts that include a mix of East Asian wide
3618 characters and other characters.
3619 Extension: emoji
3621 Parses textual emojis like :smile: as Unicode emoticons.
3622 Extension: tex_math_single_backslash
3624 Causes anything between \( and \) to be interpreted as inline TeX math,
3625 and anything between \[ and \] to be interpreted as display TeX math.
3626 Note: a drawback of this extension is that it precludes escaping ( and
3627 [.
3628 Extension: tex_math_double_backslash
3630 Causes anything between \\( and \\) to be interpreted as inline TeX
3631 math, and anything between \\[ and \\] to be interpreted as display TeX
3632 math.
3633 Extension: markdown_attribute
3635 By default, pandoc interprets material inside block-level tags as Mark‐
3636 down. This extension changes the behavior so that Markdown is only
3637 parsed inside block-level tags if the tags have the attribute mark‐
3638 down=1.
3639 Extension: mmd_title_block
3641 Enables a MultiMarkdown style title block at the top of the document,
3642 for example:
3643 Title: My title
3645 Author: John Doe
3646 Date: September 1, 2008
3647 Comment: This is a sample mmd title block, with
3648 a field spanning multiple lines.
3649 See the MultiMarkdown documentation for details. If pandoc_title_block
3651 or yaml_metadata_block is enabled, it will take precedence over
3652 mmd_title_block.
3653 Extension: abbreviations
3655 Parses PHP Markdown Extra abbreviation keys, like
3656 *[HTML]: Hypertext Markup Language
3658 Note that the pandoc document model does not support abbreviations, so
3660 if this extension is enabled, abbreviation keys are simply skipped (as
3661 opposed to being parsed as paragraphs).
3662 Extension: autolink_bare_uris
3664 Makes all absolute URIs into links, even when not surrounded by pointy
3665 braces <...>.
3666 Extension: mmd_link_attributes
3668 Parses multimarkdown style key-value attributes on link and image ref‐
3669 erences. This extension should not be confused with the
3670 link_attributes extension.
3671 This is a reference ![image][ref] with multimarkdown attributes.
3673 [ref]: http://path.to/image "Image title" width=20px height=30px
3675 id=myId class="myClass1 myClass2"
3676 Extension: mmd_header_identifiers
3678 Parses multimarkdown style header identifiers (in square brackets,
3679 after the header but before any trailing #s in an ATX header).
3680 Extension: compact_definition_lists
3682 Activates the definition list syntax of pandoc 1.12.x and earlier.
3683 This syntax differs from the one described above under Definition lists
3684 in several respects:
3685 · No blank line is required between consecutive items of the definition
3687 list.
3688 · To get a "tight" or "compact" list, omit space between consecutive
3690 items; the space between a term and its definition does not affect
3691 anything.
3692 · Lazy wrapping of paragraphs is not allowed: the entire definition
3694 must be indented four spaces.
3695 Markdown variants
3697 In addition to pandoc's extended Markdown, the following Markdown vari‐
3698 ants are supported:
3699 markdown_phpextra (PHP Markdown Extra)
3701 footnotes, pipe_tables, raw_html, markdown_attribute,
3702 fenced_code_blocks, definition_lists, intraword_underscores,
3703 header_attributes, link_attributes, abbreviations, shortcut_ref‐
3704 erence_links, spaced_reference_links.
3705 markdown_github (deprecated GitHub-Flavored Markdown)
3707 pipe_tables, raw_html, fenced_code_blocks, gfm_auto_identifiers,
3708 ascii_identifiers, backtick_code_blocks, autolink_bare_uris,
3709 space_in_atx_header, intraword_underscores, strikeout, emoji,
3710 shortcut_reference_links, angle_brackets_escapable, lists_with‐
3711 out_preceding_blankline.
3712 markdown_mmd (MultiMarkdown)
3714 pipe_tables, raw_html, markdown_attribute, mmd_link_attributes,
3715 tex_math_double_backslash, intraword_underscores,
3716 mmd_title_block, footnotes, definition_lists, all_sym‐
3717 bols_escapable, implicit_header_references, auto_identifiers,
3718 mmd_header_identifiers, shortcut_reference_links, implicit_fig‐
3719 ures, superscript, subscript, backtick_code_blocks, spaced_ref‐
3720 erence_links, raw_attribute.
3721 markdown_strict (Markdown.pl)
3723 raw_html, shortcut_reference_links, spaced_reference_links.
3724 We also support commonmark and gfm (GitHub-Flavored Markdown, which is
3726 implemented as a set of extensions on commonmark).
3727 Note, however, that commonmark and gfm have limited support for exten‐
3729 sions. Only those listed below (and smart and raw_tex) will work. The
3730 extensions can, however, all be individually disabled. Also, raw_tex
3731 only affects gfm output, not input.
3732 gfm (GitHub-Flavored Markdown)
3734 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
3735 ascii_identifiers, backtick_code_blocks, autolink_bare_uris,
3736 intraword_underscores, strikeout, hard_line_breaks, emoji,
3737 shortcut_reference_links, angle_brackets_escapable.
3738
3740 You can use pandoc to produce an HTML + JavaScript slide presentation
3741 that can be viewed via a web browser. There are five ways to do this,
3742 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
3743 duce a PDF slide show using LaTeX beamer, or slides shows in Microsoft
3744 PowerPoint format.
3745 Here's the Markdown source for a simple slide show, habits.txt:
3747 % Habits
3749 % John Doe
3750 % March 22, 2005
3751 # In the morning
3753 ## Getting up
3755 - Turn off alarm
3757 - Get out of bed
3758 ## Breakfast
3760 - Eat eggs
3762 - Drink coffee
3763 # In the evening
3765 ## Dinner
3767 - Eat spaghetti
3769 - Drink wine
3770 ------------------
3772 
3774 ## Going to sleep
3776 - Get in bed
3778 - Count sheep
3779 To produce an HTML/JavaScript slide show, simply type
3781 pandoc -t FORMAT -s habits.txt -o habits.html
3783 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
3785 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
3787 with the -s/--standalone option embeds a link to JavaScript and CSS
3788 files, which are assumed to be available at the relative path
3789 s5/default (for S5), slideous (for Slideous), reveal.js (for
3790 reveal.js), or at the Slidy website at w3.org (for Slidy). (These
3791 paths can be changed by setting the slidy-url, slideous-url,
3792 revealjs-url, or s5-url variables; see Variables for slides, above.)
3793 For DZSlides, the (relatively short) JavaScript and CSS are included in
3794 the file by default.
3795 With all HTML slide formats, the --self-contained option can be used to
3797 produce a single file that contains all of the data necessary to dis‐
3798 play the slide show, including linked scripts, stylesheets, images, and
3799 videos.
3800 To produce a PDF slide show using beamer, type
3802 pandoc -t beamer habits.txt -o habits.pdf
3804 Note that a reveal.js slide show can also be converted to a PDF by
3806 printing it to a file from the browser.
3807 To produce a Powerpoint slide show, type
3809 pandoc habits.txt -o habits.pptx
3811 Structuring the slide show
3813 By default, the slide level is the highest header level in the hierar‐
3814 chy that is followed immediately by content, and not another header,
3815 somewhere in the document. In the example above, level 1 headers are
3816 always followed by level 2 headers, which are followed by content, so 2
3817 is the slide level. This default can be overridden using the
3818 --slide-level option.
3819 The document is carved up into slides according to the following rules:
3821 · A horizontal rule always starts a new slide.
3823 · A header at the slide level always starts a new slide.
3825 · Headers below the slide level in the hierarchy create headers within
3827 a slide.
3828 · Headers above the slide level in the hierarchy create "title slides,"
3830 which just contain the section title and help to break the slide show
3831 into sections.
3832 · Content above the slide level will not appear in the slide show.
3834 · A title page is constructed automatically from the document's title
3836 block, if present. (In the case of beamer, this can be disabled by
3837 commenting out some lines in the default template.)
3838 These rules are designed to support many different styles of slide
3840 show. If you don't care about structuring your slides into sections
3841 and subsections, you can just use level 1 headers for all each slide.
3842 (In that case, level 1 will be the slide level.) But you can also
3843 structure the slide show into sections, as in the example above.
3844 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
3846 layout will be produced, with level 1 headers building horizontally and
3847 level 2 headers building vertically. It is not recommended that you
3848 use deeper nesting of section levels with reveal.js.
3849 Incremental lists
3851 By default, these writers produce lists that display "all at once." If
3852 you want your lists to display incrementally (one item at a time), use
3853 the -i option. If you want a particular list to depart from the
3854 default, put it in a div block with class incremental or nonincremen‐
3855 tal. So, for example, using the fenced div syntax, the following would
3856 be incremental regardless of the document default:
3857 ::: incremental
3859 - Eat spaghetti
3861 - Drink wine
3862 :::
3864 or
3866 ::: nonincremental
3868 - Eat spaghetti
3870 - Drink wine
3871 :::
3873 While using incremental and nonincremental divs are the recommended
3875 method of setting incremental lists on a per-case basis, an older
3876 method is also supported: putting lists inside a blockquote will depart
3877 from the document default (that is, it will display incrementally with‐
3878 out the -i option and all at once with the -i option):
3879 > - Eat spaghetti
3881 > - Drink wine
3882 Both methods allow incremental and nonincremental lists to be mixed in
3884 a single document.
3885 Inserting pauses
3887 You can add "pauses" within a slide by including a paragraph containing
3888 three dots, separated by spaces:
3889 # Slide with a pause
3891 content before the pause
3893 . . .
3895 content after the pause
3897 Styling the slides
3899 You can change the style of HTML slides by putting customized CSS files
3900 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
3901 $DATADIR/slideous (for Slideous), where $DATADIR is the user data
3902 directory (see --data-dir, above). The originals may be found in pan‐
3903 doc's system data directory (generally $CABALDIR/pandoc-VER‐
3904 SION/s5/default). Pandoc will look there for any files it does not
3905 find in the user data directory.
3906 For dzslides, the CSS is included in the HTML file itself, and may be
3908 modified there.
3909 All reveal.js configuration options can be set through variables. For
3911 example, themes can be used by setting the theme variable:
3912 -V theme=moon
3914 Or you can specify a custom stylesheet using the --css option.
3916 To style beamer slides, you can specify a theme, colortheme, fonttheme,
3918 innertheme, and outertheme, using the -V option:
3919 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
3921 Note that header attributes will turn into slide attributes (on a <div>
3923 or <section>) in HTML slide formats, allowing you to style individual
3924 slides. In beamer, the only header attribute that affects slides is
3925 the allowframebreaks class, which sets the allowframebreaks option,
3926 causing multiple slides to be created if the content overfills the
3927 frame. This is recommended especially for bibliographies:
3928 # References {.allowframebreaks}
3930 Speaker notes
3932 Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
3933 You can add notes to your Markdown document thus:
3934 ::: notes
3936 This is my note.
3938 - It can contain Markdown
3940 - like this list
3941 :::
3943 To show the notes window in reveal.js, press s while viewing the pre‐
3945 sentation. Speaker notes in PowerPoint will be available, as usual, in
3946 handouts and presenter view.
3947 Notes are not yet supported for other slide formats, but the notes will
3949 not appear on the slides themselves.
3950 Columns
3952 To put material in side by side columns, you can use a native div con‐
3953 tainer with class columns, containing two or more div containers with
3954 class column and a width attribute:
3955 :::::::::::::: {.columns}
3957 ::: {.column width="40%"}
3958 contents...
3959 :::
3960 ::: {.column width="60%"}
3961 contents...
3962 :::
3963 ::::::::::::::
3964 Frame attributes in beamer
3966 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
3967 in beamer (for example, when using the minted environment). This can
3968 be forced by adding the fragile class to the header introducing the
3969 slide:
3970 # Fragile slide {.fragile}
3972 All of the other frame attributes described in Section 8.1 of the
3974 Beamer User's Guide may also be used: allowdisplaybreaks, allowframe‐
3975 breaks, b, c, t, environment, label, plain, shrink.
3976 Background in reveal.js
3978 Background images can be added to self-contained reveal.js slideshows.
3979 For the same image on every slide, use the reveal.js configuration
3981 option parallaxBackgroundImage either in the YAML metadata block or as
3982 a command-line variable. You can also set parallaxBackgroundHorizontal
3983 and parallaxBackgroundVertical the same way and must also set paral‐
3984 laxBackgroundSize to have your values take effect.
3985 To set an image for a particular slide, add {data-back‐
3987 ground-image="/path/to/image"} to the first slide-level header on the
3988 slide (which may even be empty).
3989 In reveal.js's overview mode, the parallaxBackgroundImage will show up
3991 only on the first slide.
3992 Other background settings also work on individual slides, including
3994 data-background-size, data-background-repeat, data-background-color,
3995 data-transition, and data-transition-speed.
3996 See the reveal.js documentation for more details.
3998 For example:
4000 ---
4002 title: My Slideshow
4003 parallaxBackgroundImage: /path/to/my/background_image.png
4004 ---
4005 ## Slide One
4007 Slide 1 has background_image.png as its background.
4009 ## {data-background-image="/path/to/special_image.jpg"}
4011 Slide 2 has a special image for its background, even though the header has no content.
4013
4015 EPUB Metadata
4016 EPUB metadata may be specified using the --epub-metadata option, but if
4017 the source document is Markdown, it is better to use a YAML metadata
4018 block. Here is an example:
4019 ---
4021 title:
4022 - type: main
4023 text: My Book
4024 - type: subtitle
4025 text: An investigation of metadata
4026 creator:
4027 - role: author
4028 text: John Smith
4029 - role: editor
4030 text: Sarah Jones
4031 identifier:
4032 - scheme: DOI
4033 text: doi:10.234234.234/33
4034 publisher: My Press
4035 rights: © 2007 John Smith, CC BY-NC
4036 ibooks:
4037 version: 1.3.4
4038 ...
4039 The following fields are recognized:
4041 identifier
4043 Either a string value or an object with fields text and scheme.
4044 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
4045 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
4046 ISMN-13, ISBN-A, JP, OLCC.
4047 title Either a string value, or an object with fields file-as and
4049 type, or a list of such objects. Valid values for type are
4050 main, subtitle, short, collection, edition, extended.
4051 creator
4053 Either a string value, or an object with fields role, file-as,
4054 and text, or a list of such objects. Valid values for role are
4055 MARC relators, but pandoc will attempt to translate the
4056 human-readable versions (like "author" and "editor") to the
4057 appropriate marc relators.
4058 contributor
4060 Same format as creator.
4061 date A string value in YYYY-MM-DD format. (Only the year is neces‐
4063 sary.) Pandoc will attempt to convert other common date formats.
4064 lang (or legacy: language)
4066 A string value in BCP 47 format. Pandoc will default to the
4067 local language if nothing is specified.
4068 subject
4070 A string value or a list of such values.
4071 description
4073 A string value.
4074 type A string value.
4076 format A string value.
4078 relation
4080 A string value.
4081 coverage
4083 A string value.
4084 rights A string value.
4086 cover-image
4088 A string value (path to cover image).
4089 stylesheet
4091 A string value (path to CSS stylesheet).
4092 page-progression-direction
4094 Either ltr or rtl. Specifies the page-progression-direction
4095 attribute for the spine element.
4096 ibooks iBooks-specific metadata, with the following fields:
4098 · version: (string)
4100 · specified-fonts: true|false (default false)
4102 · ipad-orientation-lock: portrait-only|landscape-only
4104 · iphone-orientation-lock: portrait-only|landscape-only
4106 · binding: true|false (default true)
4108 · scroll-axis: vertical|horizontal|default
4110 Linked media
4112 By default, pandoc will download linked media (including audio and
4113 video) and include it in the EPUB container, yielding a completely
4114 self-contained EPUB. If you want to link to external media resources
4115 instead, use raw HTML in your source and add data-external="1" to the
4116 tag with the src attribute. For example:
4117 <audio controls="1">
4119 <source src="http://example.com/music/toccata.mp3"
4120 data-external="1" type="audio/mpeg">
4121 </source>
4122 </audio>
4123
4125 Pandoc will automatically highlight syntax in fenced code blocks that
4126 are marked with a language name. The Haskell library skylighting is
4127 used for highlighting, which works in HTML, Docx, Ms, and LaTeX/PDF
4128 output. To see a list of language names that pandoc will recognize,
4129 type pandoc --list-highlight-languages.
4130 The color scheme can be selected using the --highlight-style option.
4132 The default color scheme is pygments, which imitates the default color
4133 scheme used by the Python library pygments (though pygments is not
4134 actually used to do the highlighting). To see a list of highlight
4135 styles, type pandoc --list-highlight-styles.
4136 To disable highlighting, use the --no-highlight option.
4138
4140 Input
4141 The docx reader, by default, only reads those styles that it can con‐
4142 vert into pandoc elements, either by direct conversion or interpreting
4143 the derivation of the input document's styles.
4144 By enabling the styles extension in the docx reader (-f docx+styles),
4146 you can produce output that maintains the styles of the input document,
4147 using the custom-style class. Paragraph styles are interpreted as
4148 divs, while character styles are interpreted as spans.
4149 For example, using the custom-style-reference.docx file in the test
4151 directory, we have the following different outputs:
4152 Without the +styles extension:
4154 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
4156 This is some text.
4157 This is text with an *emphasized* text style. And this is text with a
4159 **strengthened** text style.
4160 > Here is a styled paragraph that inherits from Block Text.
4162 And with the extension:
4164 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
4166 ::: {custom-style="FirstParagraph"}
4168 This is some text.
4169 :::
4170 ::: {custom-style="BodyText"}
4172 This is text with an [emphasized]{custom-style="Emphatic"} text style.
4173 And this is text with a [strengthened]{custom-style="Strengthened"}
4174 text style.
4175 :::
4176 ::: {custom-style="MyBlockStyle"}
4178 > Here is a styled paragraph that inherits from Block Text.
4179 :::
4180 With these custom styles, you can use your input document as a refer‐
4182 ence-doc while creating docx output (see below), and maintain the same
4183 styles in your input and output files.
4184 Output
4186 By default, pandoc's docx output applies a predefined set of styles for
4187 blocks such as paragraphs and block quotes, and uses largely default
4188 formatting (italics, bold) for inlines. This will work for most pur‐
4189 poses, especially alongside a reference.docx file. However, if you
4190 need to apply your own styles to blocks, or match a preexisting set of
4191 styles, pandoc allows you to define custom styles for blocks and text
4192 using divs and spans, respectively.
4193 If you define a div or span with the attribute custom-style, pandoc
4195 will apply your specified style to the contained elements. So, for
4196 example using the bracketed_spans syntax,
4197 [Get out]{custom-style="Emphatically"}, he said.
4199 would produce a docx file with "Get out" styled with character style
4201 Emphatically. Similarly, using the fenced_divs syntax,
4202 Dickinson starts the poem simply:
4204 ::: {custom-style="Poetry"}
4206 | A Bird came down the Walk---
4207 | He did not know I saw---
4208 :::
4209 would style the two contained lines with the Poetry paragraph style.
4211 If the styles are not yet in your reference.docx, they will be defined
4213 in the output file as inheriting from normal text. If they are already
4214 defined, pandoc will not alter the definition.
4215 This feature allows for greatest customization in conjunction with pan‐
4217 doc filters. If you want all paragraphs after block quotes to be
4218 indented, you can write a filter to apply the styles necessary. If you
4219 want all italics to be transformed to the Emphasis character style
4220 (perhaps to change their color), you can write a filter which will
4221 transform all italicized inlines to inlines within an Emphasis cus‐
4222 tom-style span.
4223
4225 Pandoc can be extended with custom writers written in lua. (Pandoc
4226 includes a lua interpreter, so lua need not be installed separately.)
4227 To use a custom writer, simply specify the path to the lua script in
4229 place of the output format. For example:
4230 pandoc -t data/sample.lua
4232 Creating a custom writer requires writing a lua function for each pos‐
4234 sible element in a pandoc document. To get a documented example which
4235 you can modify according to your needs, do
4236 pandoc --print-default-data-file sample.lua
4238
4240 Copyright 2006-2017 John MacFarlane (jgm@berkeley.edu). Released under
4241 the GPL, version 2 or greater. This software carries no warranty of
4242 any kind. (See COPYRIGHT for full copyright and warranty notices.) For
4243 a full list of contributors, see the file AUTHORS.md in the pandoc
4244 source code.
4245 The Pandoc source code and all documentation may be downloaded from
4247 <http://pandoc.org>.
4248pandoc 2.2.1 May 10, 2018 PANDOC(1)