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 read Markdown, CommonMark, PHP Markdown Extra, GitHub-Fla‐
16 vored Markdown, MultiMarkdown, and (subsets of) Textile, reStructured‐
17 Text, HTML, LaTeX, MediaWiki markup, TWiki markup, TikiWiki markup,
18 Creole 1.0, Haddock markup, OPML, Emacs Org mode, DocBook, JATS, Muse,
19 txt2tags, Vimwiki, EPUB, ODT, and Word docx.
20 Pandoc can write plain text, Markdown, CommonMark, PHP Markdown Extra,
22 GitHub-Flavored Markdown, MultiMarkdown, reStructuredText, XHTML,
23 HTML5, LaTeX (including beamer slide shows), ConTeXt, RTF, OPML, Doc‐
24 Book, JATS, OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki
25 markup, DokuWiki markup, ZimWiki markup, Haddock markup, EPUB (v2 or
26 v3), FictionBook2, Textile, groff man, groff ms, Emacs Org mode, Asci‐
27 iDoc, InDesign ICML, TEI Simple, Muse, PowerPoint slide shows and
28 Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows. It can
29 also produce PDF output on systems where LaTeX, ConTeXt, pdfroff,
30 wkhtmltopdf, prince, or weasyprint is installed.
31 Pandoc's enhanced version of Markdown includes syntax for tables, defi‐
33 nition lists, metadata blocks, Div blocks, footnotes and citations,
34 embedded LaTeX (including math), Markdown inside HTML block elements,
35 and much more. These enhancements, described further under Pandoc's
36 Markdown, can be disabled using the markdown_strict format.
37 Pandoc has a modular design: it consists of a set of readers, which
39 parse text in a given format and produce a native representation of the
40 document (like an abstract syntax tree or AST), and a set of writers,
41 which convert this native representation into a target format. Thus,
42 adding an input or output format requires only adding a reader or
43 writer. Users can also run custom pandoc filters to modify the inter‐
44 mediate AST.
45 Because pandoc's intermediate representation of a document is less
47 expressive than many of the formats it converts between, one should not
48 expect perfect conversions between every format and every other. Pan‐
49 doc attempts to preserve the structural elements of a document, but not
50 formatting details such as margin size. And some document elements,
51 such as complex tables, may not fit into pandoc's simple document
52 model. While conversions from pandoc's Markdown to all formats aspire
53 to be perfect, conversions from formats more expressive than pandoc's
54 Markdown can be expected to be lossy.
55 Using pandoc
57 If no input-files are specified, input is read from stdin. Output goes
58 to stdout by default. For output to a file, use the -o option:
59 pandoc -o output.html input.txt
61 By default, pandoc produces a document fragment. To produce a stand‐
63 alone document (e.g. a valid HTML file including <head> and <body>),
64 use the -s or --standalone flag:
65 pandoc -s -o output.html input.txt
67 For more information on how standalone documents are produced, see Tem‐
69 plates below.
70 If multiple input files are given, pandoc will concatenate them all
72 (with blank lines between them) before parsing. (Use --file-scope to
73 parse files individually.)
74 Specifying formats
76 The format of the input and output can be specified explicitly using
77 command-line options. The input format can be specified using the
78 -f/--from option, the output format using the -t/--to option. Thus, to
79 convert hello.txt from Markdown to LaTeX, you could type:
80 pandoc -f markdown -t latex hello.txt
82 To convert hello.html from HTML to Markdown:
84 pandoc -f html -t markdown hello.html
86 Supported input and output formats are listed below under Options (see
88 -f for input formats and -t for output formats). You can also use pan‐
89 doc --list-input-formats and pandoc --list-output-formats to print
90 lists of supported formats.
91 If the input or output format is not specified explicitly, pandoc will
93 attempt to guess it from the extensions of the filenames. Thus, for
94 example,
95 pandoc -o hello.tex hello.txt
97 will convert hello.txt from Markdown to LaTeX. If no output file is
99 specified (so that output goes to stdout), or if the output file's
100 extension is unknown, the output format will default to HTML. If no
101 input file is specified (so that input comes from stdin), or if the
102 input files' extensions are unknown, the input format will be assumed
103 to be Markdown.
104 Character encoding
106 Pandoc uses the UTF-8 character encoding for both input and output. If
107 your local character encoding is not UTF-8, you should pipe input and
108 output through iconv:
109 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
111 Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
113 OPML, DocBook, and Texinfo), information about the character encoding
114 is included in the document header, which will only be included if you
115 use the -s/--standalone option.
116 Creating a PDF
118 To produce a PDF, specify an output file with a .pdf extension:
119 pandoc test.txt -o test.pdf
121 By default, pandoc will use LaTeX to create the PDF, which requires
123 that a LaTeX engine be installed (see --pdf-engine below).
124 Alternatively, pandoc can use ConTeXt, pdfroff, or any of the following
126 HTML/CSS-to-PDF-engines, to create a PDF: wkhtmltopdf, weasyprint or
127 prince. To do this, specify an output file with a .pdf extension, as
128 before, but add the --pdf-engine option or -t context, -t html, or
129 -t ms to the command line (-t html defaults to --pdf-engine=wkhtml‐
130 topdf).
131 PDF output can be controlled using variables for LaTeX (if LaTeX is
133 used) and variables for ConTeXt (if ConTeXt is used). When using an
134 HTML/CSS-to-PDF-engine, --css affects the output. If wkhtmltopdf is
135 used, then the variables margin-left, margin-right, margin-top, mar‐
136 gin-bottom, footer-html, header-html and papersize will affect the out‐
137 put.
138 To debug the PDF creation, it can be useful to look at the intermediate
140 representation: instead of -o test.pdf, use for example -s -o test.tex
141 to output the generated LaTeX. You can then test it with pdfla‐
142 tex test.tex.
143 When using LaTeX, the following packages need to be available (they are
145 included with all recent versions of TeX Live): amsfonts, amsmath, lm,
146 unicode-math, ifxetex, ifluatex, listings (if the --listings option is
147 used), fancyvrb, longtable, booktabs, graphicx and grffile (if the doc‐
148 ument contains images), hyperref, xcolor (with colorlinks), ulem, geom‐
149 etry (with the geometry variable set), setspace (with linestretch), and
150 babel (with lang). The use of xelatex or lualatex as the LaTeX engine
151 requires fontspec. xelatex uses polyglossia (with lang), xecjk, and
152 bidi (with the dir variable set). If the mathspec variable is set,
153 xelatex will use mathspec instead of unicode-math. The upquote and
154 microtype packages are used if available, and csquotes will be used for
155 typography if added to the template or included in any header file.
156 The natbib, biblatex, bibtex, and biber packages can optionally be used
157 for citation rendering.
158 Reading from the Web
160 Instead of an input file, an absolute URI may be given. In this case
161 pandoc will fetch the content using HTTP:
162 pandoc -f html -t markdown http://www.fsf.org
164 It is possible to supply a custom User-Agent string or other header
166 when requesting a document from a URL:
167 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
169 http://www.fsf.org
170
172 General options
173 -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
174 Specify input format. FORMAT can be native (native Haskell),
175 json (JSON version of native AST), markdown (pandoc's extended
176 Markdown), markdown_strict (original unextended Markdown), mark‐
177 down_phpextra (PHP Markdown Extra), markdown_mmd (MultiMark‐
178 down), gfm (GitHub-Flavored Markdown), commonmark (CommonMark
179 Markdown), textile (Textile), rst (reStructuredText), html
180 (HTML), docbook (DocBook), t2t (txt2tags), docx (docx), odt
181 (ODT), epub (EPUB), opml (OPML), org (Emacs Org mode), mediawiki
182 (MediaWiki markup), twiki (TWiki markup), tikiwiki (TikiWiki
183 markup), creole (Creole 1.0), haddock (Haddock markup), or latex
184 (LaTeX). (markdown_github provides deprecated and less accurate
185 support for Github-Flavored Markdown; please use gfm instead,
186 unless you need to use extensions other than smart.) Extensions
187 can be individually enabled or disabled by appending +EXTENSION
188 or -EXTENSION to the format name. See Extensions below, for a
189 list of extensions and their names. See --list-input-formats
190 and --list-extensions, below.
191 -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
193 Specify output format. FORMAT can be native (native Haskell),
194 json (JSON version of native AST), plain (plain text), markdown
195 (pandoc's extended Markdown), markdown_strict (original unex‐
196 tended Markdown), markdown_phpextra (PHP Markdown Extra), mark‐
197 down_mmd (MultiMarkdown), gfm (GitHub-Flavored Markdown), com‐
198 monmark (CommonMark Markdown), rst (reStructuredText), html4
199 (XHTML 1.0 Transitional), html or html5 (HTML5/XHTML polyglot
200 markup), latex (LaTeX), beamer (LaTeX beamer slide show), con‐
201 text (ConTeXt), man (groff man), mediawiki (MediaWiki markup),
202 dokuwiki (DokuWiki markup), zimwiki (ZimWiki markup), textile
203 (Textile), org (Emacs Org mode), texinfo (GNU Texinfo), opml
204 (OPML), docbook or docbook4 (DocBook 4), docbook5 (DocBook 5),
205 jats (JATS XML), opendocument (OpenDocument), odt (OpenOffice
206 text document), docx (Word docx), haddock (Haddock markup), rtf
207 (rich text format), epub2 (EPUB v2 book), epub or epub3 (EPUB
208 v3), fb2 (FictionBook2 e-book), asciidoc (AsciiDoc), icml (InDe‐
209 sign ICML), tei (TEI Simple), slidy (Slidy HTML and JavaScript
210 slide show), slideous (Slideous HTML and JavaScript slide show),
211 dzslides (DZSlides HTML5 + JavaScript slide show), revealjs
212 (reveal.js HTML5 + JavaScript slide show), s5 (S5 HTML and
213 JavaScript slide show), pptx (PowerPoint slide show) or the path
214 of a custom lua writer (see Custom writers, below). (mark‐
215 down_github provides deprecated and less accurate support for
216 Github-Flavored Markdown; please use gfm instead, unless you use
217 extensions that do not work with gfm.) Note that odt, docx, and
218 epub output will not be directed to stdout unless forced with
219 -o -. Extensions can be individually enabled or disabled by
220 appending +EXTENSION or -EXTENSION to the format name. See
221 Extensions below, for a list of extensions and their names. See
222 --list-output-formats and --list-extensions, below.
223 -o FILE, --output=FILE
225 Write output to FILE instead of stdout. If FILE is -, output
226 will go to stdout, even if a non-textual format (docx, odt,
227 epub2, epub3) is specified.
228 --data-dir=DIRECTORY
230 Specify the user data directory to search for pandoc data files.
231 If this option is not specified, the default user data directory
232 will be used. This is, in UNIX:
233 $HOME/.pandoc
235 in Windows XP:
237 C:\Documents And Settings\USERNAME\Application Data\pandoc
239 and in Windows Vista or later:
241 C:\Users\USERNAME\AppData\Roaming\pandoc
243 You can find the default user data directory on your system by
245 looking at the output of pandoc --version. A reference.odt,
246 reference.docx, epub.css, templates, slidy, slideous, or s5
247 directory placed in this directory will override pandoc's normal
248 defaults.
249 --bash-completion
251 Generate a bash completion script. To enable bash completion
252 with pandoc, add this to your .bashrc:
253 eval "$(pandoc --bash-completion)"
255 --verbose
257 Give verbose debugging output. Currently this only has an
258 effect with PDF output.
259 --quiet
261 Suppress warning messages.
262 --fail-if-warnings
264 Exit with error status if there are any warnings.
265 --log=FILE
267 Write log messages in machine-readable JSON format to FILE. All
268 messages above DEBUG level will be written, regardless of ver‐
269 bosity settings (--verbose, --quiet).
270 --list-input-formats
272 List supported input formats, one per line.
273 --list-output-formats
275 List supported output formats, one per line.
276 --list-extensions[=FORMAT]
278 List supported extensions, one per line, preceded by a + or -
279 indicating whether it is enabled by default in FORMAT. If FOR‐
280 MAT is not specified, defaults for pandoc's Markdown are given.
281 --list-highlight-languages
283 List supported languages for syntax highlighting, one per line.
284 --list-highlight-styles
286 List supported styles for syntax highlighting, one per line.
287 See --highlight-style.
288 -v, --version
290 Print version.
291 -h, --help
293 Show usage message.
294 Reader options
296 --base-header-level=NUMBER
297 Specify the base level for headers (defaults to 1).
298 --strip-empty-paragraphs
300 Deprecated. Use the +empty_paragraphs extension instead. Ignore
301 paragraphs with no content. This option is useful for convert‐
302 ing word processing documents where users have used empty para‐
303 graphs to create inter-paragraph space.
304 --indented-code-classes=CLASSES
306 Specify classes to use for indented code blocks--for example,
307 perl,numberLines or haskell. Multiple classes may be separated
308 by spaces or commas.
309 --default-image-extension=EXTENSION
311 Specify a default extension to use when image paths/URLs have no
312 extension. This allows you to use the same source for formats
313 that require different kinds of images. Currently this option
314 only affects the Markdown and LaTeX readers.
315 --file-scope
317 Parse each file individually before combining for multifile doc‐
318 uments. This will allow footnotes in different files with the
319 same identifiers to work as expected. If this option is set,
320 footnotes and links will not work across files. Reading binary
321 files (docx, odt, epub) implies --file-scope.
322 --filter=PROGRAM
324 Specify an executable to be used as a filter transforming the
325 pandoc AST after the input is parsed and before the output is
326 written. The executable should read JSON from stdin and write
327 JSON to stdout. The JSON must be formatted like pandoc's own
328 JSON input and output. The name of the output format will be
329 passed to the filter as the first argument. Hence,
330 pandoc --filter ./caps.py -t latex
332 is equivalent to
334 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
336 The latter form may be useful for debugging filters.
338 Filters may be written in any language. Text.Pandoc.JSON
340 exports toJSONFilter to facilitate writing filters in Haskell.
341 Those who would prefer to write filters in python can use the
342 module pandocfilters, installable from PyPI. There are also
343 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
344 In order of preference, pandoc will look for filters in
346 1. a specified full or relative path (executable or non-exe‐
348 cutable)
349 2. $DATADIR/filters (executable or non-executable) where
351 $DATADIR is the user data directory (see --data-dir, above).
352 3. $PATH (executable only)
354 Filters and lua-filters are applied in the order specified on
356 the command line.
357 --lua-filter=SCRIPT
359 Transform the document in a similar fashion as JSON filters (see
360 --filter), but use pandoc's build-in lua filtering system. The
361 given lua script is expected to return a list of lua filters
362 which will be applied in order. Each lua filter must contain
363 element-transforming functions indexed by the name of the AST
364 element on which the filter function should be applied.
365 The pandoc lua module provides helper functions for element cre‐
367 ation. It is always loaded into the script's lua environment.
368 The following is an example lua script for macro-expansion:
370 function expand_hello_world(inline)
372 if inline.c == '{{helloworld}}' then
373 return pandoc.Emph{ pandoc.Str "Hello, World" }
374 else
375 return inline
376 end
377 end
378 return {{Str = expand_hello_world}}
380 -M KEY[=VAL], --metadata=KEY[:VAL]
382 Set the metadata field KEY to the value VAL. A value specified
383 on the command line overrides a value specified in the document.
384 Values will be parsed as YAML boolean or string values. If no
385 value is specified, the value will be treated as Boolean true.
386 Like --variable, --metadata causes template variables to be set.
387 But unlike --variable, --metadata affects the metadata of the
388 underlying document (which is accessible from filters and may be
389 printed in some output formats).
390 -p, --preserve-tabs
392 Preserve tabs instead of converting them to spaces (the
393 default). Note that this will only affect tabs in literal code
394 spans and code blocks; tabs in regular text will be treated as
395 spaces.
396 --tab-stop=NUMBER
398 Specify the number of spaces per tab (default is 4).
399 --track-changes=accept|reject|all
401 Specifies what to do with insertions, deletions, and comments
402 produced by the MS Word "Track Changes" feature. accept (the
403 default), inserts all insertions, and ignores all deletions.
404 reject inserts all deletions and ignores insertions. Both
405 accept and reject ignore comments. all puts in insertions,
406 deletions, and comments, wrapped in spans with insertion, dele‐
407 tion, comment-start, and comment-end classes, respectively. The
408 author and time of change is included. all is useful for
409 scripting: only accepting changes from a certain reviewer, say,
410 or before a certain date. If a paragraph is inserted or
411 deleted, track-changes=all produces a span with the class para‐
412 graph-insertion/paragraph-deletion before the affected paragraph
413 break. This option only affects the docx reader.
414 --extract-media=DIR
416 Extract images and other media contained in or linked from the
417 source document to the path DIR, creating it if necessary, and
418 adjust the images references in the document so they point to
419 the extracted files. If the source format is a binary container
420 (docx, epub, or odt), the media is extracted from the container
421 and the original filenames are used. Otherwise the media is
422 read from the file system or downloaded, and new filenames are
423 constructed based on SHA1 hashes of the contents.
424 --abbreviations=FILE
426 Specifies a custom abbreviations file, with abbreviations one to
427 a line. If this option is not specified, pandoc will read the
428 data file abbreviations from the user data directory or fall
429 back on a system default. To see the system default, use pan‐
430 doc --print-default-data-file=abbreviations. The only use pan‐
431 doc makes of this list is in the Markdown reader. Strings end‐
432 ing in a period that are found in this list will be followed by
433 a nonbreaking space, so that the period will not produce sen‐
434 tence-ending space in formats like LaTeX.
435 General writer options
437 -s, --standalone
438 Produce output with an appropriate header and footer (e.g. a
439 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
440 option is set automatically for pdf, epub, epub3, fb2, docx, and
441 odt output.
442 --template=FILE
444 Use FILE as a custom template for the generated document.
445 Implies --standalone. See Templates, below, for a description
446 of template syntax. If no extension is specified, an extension
447 corresponding to the writer will be added, so that --tem‐
448 plate=special looks for special.html for HTML output. If the
449 template is not found, pandoc will search for it in the tem‐
450 plates subdirectory of the user data directory (see --data-dir).
451 If this option is not used, a default template appropriate for
452 the output format will be used (see -D/--print-default-tem‐
453 plate).
454 -V KEY[=VAL], --variable=KEY[:VAL]
456 Set the template variable KEY to the value VAL when rendering
457 the document in standalone mode. This is generally only useful
458 when the --template option is used to specify a custom template,
459 since pandoc automatically sets the variables used in the
460 default templates. If no VAL is specified, the key will be
461 given the value true.
462 -D FORMAT, --print-default-template=FORMAT
464 Print the system default template for an output FORMAT. (See -t
465 for a list of possible FORMATs.) Templates in the user data
466 directory are ignored.
467 --print-default-data-file=FILE
469 Print a system default data file. Files in the user data direc‐
470 tory are ignored.
471 --eol=crlf|lf|native
473 Manually specify line endings: crlf (Windows), lf (mac‐
474 OS/Linux/UNIX), or native (line endings appropriate to the OS on
475 which pandoc is being run). The default is native.
476 --dpi=NUMBER
478 Specify the dpi (dots per inch) value for conversion from pixels
479 to inch/centimeters and vice versa. The default is 96dpi.
480 Technically, the correct term would be ppi (pixels per inch).
481 --wrap=auto|none|preserve
483 Determine how text is wrapped in the output (the source code,
484 not the rendered version). With auto (the default), pandoc will
485 attempt to wrap lines to the column width specified by --columns
486 (default 72). With none, pandoc will not wrap lines at all.
487 With preserve, pandoc will attempt to preserve the wrapping from
488 the source document (that is, where there are nonsemantic new‐
489 lines in the source, there will be nonsemantic newlines in the
490 output as well). Automatic wrapping does not currently work in
491 HTML output.
492 --columns=NUMBER
494 Specify length of lines in characters. This affects text wrap‐
495 ping in the generated source code (see --wrap). It also affects
496 calculation of column widths for plain text tables (see Tables
497 below).
498 --toc, --table-of-contents
500 Include an automatically generated table of contents (or, in the
501 case of latex, context, docx, odt, opendocument, rst, or ms, an
502 instruction to create one) in the output document. This option
503 has no effect on man, docbook4, docbook5, or jats output.
504 --toc-depth=NUMBER
506 Specify the number of section levels to include in the table of
507 contents. The default is 3 (which means that level 1, 2, and 3
508 headers will be listed in the contents).
509 --strip-comments
511 Strip out HTML comments in the Markdown or Textile source,
512 rather than passing them on to Markdown, Textile or HTML output
513 as raw HTML. This does not apply to HTML comments inside raw
514 HTML blocks when the markdown_in_html_blocks extension is not
515 set.
516 --no-highlight
518 Disables syntax highlighting for code blocks and inlines, even
519 when a language attribute is given.
520 --highlight-style=STYLE|FILE
522 Specifies the coloring style to be used in highlighted source
523 code. Options are pygments (the default), kate, monochrome,
524 breezeDark, espresso, zenburn, haddock, and tango. For more
525 information on syntax highlighting in pandoc, see Syntax high‐
526 lighting, below. See also --list-highlight-styles.
527 Instead of a STYLE name, a JSON file with extension .theme may
529 be supplied. This will be parsed as a KDE syntax highlighting
530 theme and (if valid) used as the highlighting style.
531 To generate the JSON version of an existing style, use
533 --print-highlight-style.
534 --print-highlight-style=STYLE|FILE
536 Prints a JSON version of a highlighting style, which can be mod‐
537 ified, saved with a .theme extension, and used with --high‐
538 light-style.
539 --syntax-definition=FILE
541 Instructs pandoc to load a KDE XML syntax definition file, which
542 will be used for syntax highlighting of appropriately marked
543 code blocks. This can be used to add support for new languages
544 or to use altered syntax definitions for existing languages.
545 -H FILE, --include-in-header=FILE
547 Include contents of FILE, verbatim, at the end of the header.
548 This can be used, for example, to include special CSS or
549 JavaScript in HTML documents. This option can be used repeat‐
550 edly to include multiple files in the header. They will be
551 included in the order specified. Implies --standalone.
552 -B FILE, --include-before-body=FILE
554 Include contents of FILE, verbatim, at the beginning of the doc‐
555 ument body (e.g. after the <body> tag in HTML, or the
556 \begin{document} command in LaTeX). This can be used to include
557 navigation bars or banners in HTML documents. This option can
558 be used repeatedly to include multiple files. They will be
559 included in the order specified. Implies --standalone.
560 -A FILE, --include-after-body=FILE
562 Include contents of FILE, verbatim, at the end of the document
563 body (before the </body> tag in HTML, or the \end{document} com‐
564 mand in LaTeX). This option can be used repeatedly to include
565 multiple files. They will be included in the order specified.
566 Implies --standalone.
567 --resource-path=SEARCHPATH
569 List of paths to search for images and other resources. The
570 paths should be separated by : on Linux, UNIX, and macOS sys‐
571 tems, and by ; on Windows. If --resource-path is not specified,
572 the default resource path is the working directory. Note that,
573 if --resource-path is specified, the working directory must be
574 explicitly listed or it will not be searched. For example:
575 --resource-path=.:test will search the working directory and the
576 test subdirectory, in that order.
577 --request-header=NAME:VAL
579 Set the request header NAME to the value VAL when making HTTP
580 requests (for example, when a URL is given on the command line,
581 or when resources used in a document must be downloaded).
582 Options affecting specific writers
584 --self-contained
585 Produce a standalone HTML file with no external dependencies,
586 using data: URIs to incorporate the contents of linked scripts,
587 stylesheets, images, and videos. Implies --standalone. The
588 resulting file should be "self-contained," in the sense that it
589 needs no external files and no net access to be displayed prop‐
590 erly by a browser. This option works only with HTML output for‐
591 mats, including html4, html5, html+lhs, html5+lhs, s5, slidy,
592 slideous, dzslides, and revealjs. Scripts, images, and
593 stylesheets at absolute URLs will be downloaded; those at rela‐
594 tive URLs will be sought relative to the working directory (if
595 the first source file is local) or relative to the base URL (if
596 the first source file is remote). Elements with the attribute
597 data-external="1" will be left alone; the documents they link to
598 will not be incorporated in the document. Limitation: resources
599 that are loaded dynamically through JavaScript cannot be incor‐
600 porated; as a result, --self-contained does not work with
601 --mathjax, and some advanced features (e.g. zoom or speaker
602 notes) may not work in an offline "self-contained" reveal.js
603 slide show.
604 --html-q-tags
606 Use <q> tags for quotes in HTML.
607 --ascii
609 Use only ASCII characters in output. Currently supported only
610 for HTML and DocBook output (which uses numerical entities
611 instead of UTF-8 when this option is selected).
612 --reference-links
614 Use reference-style links, rather than inline links, in writing
615 Markdown or reStructuredText. By default inline links are used.
616 The placement of link references is affected by the --refer‐
617 ence-location option.
618 --reference-location = block|section|document
620 Specify whether footnotes (and references, if reference-links is
621 set) are placed at the end of the current (top-level) block, the
622 current section, or the document. The default is document.
623 Currently only affects the markdown writer.
624 --atx-headers
626 Use ATX-style headers in Markdown and AsciiDoc output. The
627 default is to use setext-style headers for levels 1-2, and then
628 ATX headers. (Note: for gfm output, ATX headers are always
629 used.)
630 --top-level-division=[default|section|chapter|part]
632 Treat top-level headers as the given division type in LaTeX,
633 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
634 chapter, then section; all headers are shifted such that the
635 top-level header becomes the specified type. The default behav‐
636 ior is to determine the best division type via heuristics:
637 unless other conditions apply, section is chosen. When the
638 LaTeX document class is set to report, book, or memoir (unless
639 the article option is specified), chapter is implied as the set‐
640 ting for this option. If beamer is the output format, specify‐
641 ing either chapter or part will cause top-level headers to
642 become \part{..}, while second-level headers remain as their
643 default type.
644 -N, --number-sections
646 Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
647 By default, sections are not numbered. Sections with class
648 unnumbered will never be numbered, even if --number-sections is
649 specified.
650 --number-offset=NUMBER[,NUMBER,...]
652 Offset for section headings in HTML output (ignored in other
653 output formats). The first number is added to the section num‐
654 ber for top-level headers, the second for second-level headers,
655 and so on. So, for example, if you want the first top-level
656 header in your document to be numbered "6", specify --num‐
657 ber-offset=5. If your document starts with a level-2 header
658 which you want to be numbered "1.5", specify --number-off‐
659 set=1,4. Offsets are 0 by default. Implies --number-sections.
660 --listings
662 Use the listings package for LaTeX code blocks
663 -i, --incremental
665 Make list items in slide shows display incrementally (one by
666 one). The default is for lists to be displayed all at once.
667 --slide-level=NUMBER
669 Specifies that headers with the specified level create slides
670 (for beamer, s5, slidy, slideous, dzslides). Headers above this
671 level in the hierarchy are used to divide the slide show into
672 sections; headers below this level create subheads within a
673 slide. Note that content that is not contained under
674 slide-level headers will not appear in the slide show. The
675 default is to set the slide level based on the contents of the
676 document; see Structuring the slide show.
677 --section-divs
679 Wrap sections in <section> tags (or <div> tags for html4), and
680 attach identifiers to the enclosing <section> (or <div>) rather
681 than the header itself. See Header identifiers, below.
682 --email-obfuscation=none|javascript|references
684 Specify a method for obfuscating mailto: links in HTML docu‐
685 ments. none leaves mailto: links as they are. javascript
686 obfuscates them using JavaScript. references obfuscates them by
687 printing their letters as decimal or hexadecimal character ref‐
688 erences. The default is none.
689 --id-prefix=STRING
691 Specify a prefix to be added to all identifiers and internal
692 links in HTML and DocBook output, and to footnote numbers in
693 Markdown and Haddock output. This is useful for preventing
694 duplicate identifiers when generating fragments to be included
695 in other pages.
696 -T STRING, --title-prefix=STRING
698 Specify STRING as a prefix at the beginning of the title that
699 appears in the HTML header (but not in the title as it appears
700 at the beginning of the HTML body). Implies --standalone.
701 -c URL, --css=URL
703 Link to a CSS style sheet. This option can be used repeatedly
704 to include multiple files. They will be included in the order
705 specified.
706 A stylesheet is required for generating EPUB. If none is pro‐
708 vided using this option (or the stylesheet metadata field), pan‐
709 doc will look for a file epub.css in the user data directory
710 (see --data-dir). If it is not found there, sensible defaults
711 will be used.
712 --reference-doc=FILE
714 Use the specified file as a style reference in producing a docx
715 or ODT file.
716 Docx For best results, the reference docx should be a modified
718 version of a docx file produced using pandoc. The con‐
719 tents of the reference docx are ignored, but its
720 stylesheets and document properties (including margins,
721 page size, header, and footer) are used in the new docx.
722 If no reference docx is specified on the command line,
723 pandoc will look for a file reference.docx in the user
724 data directory (see --data-dir). If this is not found
725 either, sensible defaults will be used.
726 To produce a custom reference.docx, first get a copy of
728 the default reference.docx: pan‐
729 doc --print-default-data-file reference.docx > cus‐
730 tom-reference.docx. Then open custom-reference.docx in
731 Word, modify the styles as you wish, and save the file.
732 For best results, do not make changes to this file other
733 than modifying the styles used by pandoc: [paragraph]
734 Normal, Body Text, First Paragraph, Compact, Title, Sub‐
735 title, Author, Date, Abstract, Bibliography, Heading 1,
736 Heading 2, Heading 3, Heading 4, Heading 5, Heading 6,
737 Heading 7, Heading 8, Heading 9, Block Text, Footnote
738 Text, Definition Term, Definition, Caption, Table Cap‐
739 tion, Image Caption, Figure, Captioned Figure, TOC Head‐
740 ing; [character] Default Paragraph Font, Body Text Char,
741 Verbatim Char, Footnote Reference, Hyperlink; [table] Ta‐
742 ble.
743 ODT For best results, the reference ODT should be a modified
745 version of an ODT produced using pandoc. The contents of
746 the reference ODT are ignored, but its stylesheets are
747 used in the new ODT. If no reference ODT is specified on
748 the command line, pandoc will look for a file refer‐
749 ence.odt in the user data directory (see --data-dir). If
750 this is not found either, sensible defaults will be used.
751 To produce a custom reference.odt, first get a copy of
753 the default reference.odt: pan‐
754 doc --print-default-data-file reference.odt > custom-ref‐
755 erence.odt. Then open custom-reference.odt in LibreOf‐
756 fice, modify the styles as you wish, and save the file.
757 PowerPoint
759 Any template included with a recent install of Microsoft
760 PowerPoint (either with .pptx or .potx extension) should
761 work, as will most templates derived from these.
762 The specific requirement is that the template should con‐
764 tain the following four layouts as its first four lay‐
765 outs:
766 1. Title Slide
768 2. Title and Content
770 3. Section Header
772 4. Two Content
774 All templates included with a recent version of MS Power‐
776 Point will fit these criteria. (You can click on Layout
777 under the Home menu to check.)
778 You can also modify the default reference.pptx: first run
780 pandoc --print-default-data-file reference.pptx > cus‐
781 tom-reference.pptx, and then modify custom-reference.pptx
782 in MS PowerPoint (pandoc will use the first four layout
783 slides, as mentioned above).
784 --epub-cover-image=FILE
786 Use the specified image as the EPUB cover. It is recommended
787 that the image be less than 1000px in width and height. Note
788 that in a Markdown source document you can also specify
789 cover-image in a YAML metadata block (see EPUB Metadata, below).
790 --epub-metadata=FILE
792 Look in the specified XML file for metadata for the EPUB. The
793 file should contain a series of Dublin Core elements. For exam‐
794 ple:
795 <dc:rights>Creative Commons</dc:rights>
797 <dc:language>es-AR</dc:language>
798 By default, pandoc will include the following metadata elements:
800 <dc:title> (from the document title), <dc:creator> (from the
801 document authors), <dc:date> (from the document date, which
802 should be in ISO 8601 format), <dc:language> (from the lang
803 variable, or, if is not set, the locale), and <dc:identi‐
804 fier id="BookId"> (a randomly generated UUID). Any of these may
805 be overridden by elements in the metadata file.
806 Note: if the source document is Markdown, a YAML metadata block
808 in the document can be used instead. See below under EPUB Meta‐
809 data.
810 --epub-embed-font=FILE
812 Embed the specified font in the EPUB. This option can be
813 repeated to embed multiple fonts. Wildcards can also be used:
814 for example, DejaVuSans-*.ttf. However, if you use wildcards on
815 the command line, be sure to escape them or put the whole file‐
816 name in single quotes, to prevent them from being interpreted by
817 the shell. To use the embedded fonts, you will need to add dec‐
818 larations like the following to your CSS (see --css):
819 @font-face {
821 font-family: DejaVuSans;
822 font-style: normal;
823 font-weight: normal;
824 src:url("DejaVuSans-Regular.ttf");
825 }
826 @font-face {
827 font-family: DejaVuSans;
828 font-style: normal;
829 font-weight: bold;
830 src:url("DejaVuSans-Bold.ttf");
831 }
832 @font-face {
833 font-family: DejaVuSans;
834 font-style: italic;
835 font-weight: normal;
836 src:url("DejaVuSans-Oblique.ttf");
837 }
838 @font-face {
839 font-family: DejaVuSans;
840 font-style: italic;
841 font-weight: bold;
842 src:url("DejaVuSans-BoldOblique.ttf");
843 }
844 body { font-family: "DejaVuSans"; }
845 --epub-chapter-level=NUMBER
847 Specify the header level at which to split the EPUB into sepa‐
848 rate "chapter" files. The default is to split into chapters at
849 level 1 headers. This option only affects the internal composi‐
850 tion of the EPUB, not the way chapters and sections are dis‐
851 played to users. Some readers may be slow if the chapter files
852 are too large, so for large documents with few level 1 headers,
853 one might want to use a chapter level of 2 or 3.
854 --epub-subdirectory=DIRNAME
856 Specify the subdirectory in the OCF container that is to hold
857 the EPUB-specific contents. The default is EPUB. To put the
858 EPUB contents in the top level, use an empty string.
859 --pdf-engine=pdflatex|lualatex|xelatex|wkhtml‐
861 topdf|weasyprint|prince|context|pdfroff
862 Use the specified engine when producing PDF output. The default
863 is pdflatex. If the engine is not in your PATH, the full path
864 of the engine may be specified here.
865 --pdf-engine-opt=STRING
867 Use the given string as a command-line argument to the
868 pdf-engine. If used multiple times, the arguments are provided
869 with spaces between them. Note that no check for duplicate
870 options is done.
871 Citation rendering
873 --bibliography=FILE
874 Set the bibliography field in the document's metadata to FILE,
875 overriding any value set in the metadata, and process citations
876 using pandoc-citeproc. (This is equivalent to --metadata bibli‐
877 ography=FILE --filter pandoc-citeproc.) If --natbib or --bibla‐
878 tex is also supplied, pandoc-citeproc is not used, making this
879 equivalent to --metadata bibliography=FILE. If you supply this
880 argument multiple times, each FILE will be added to bibliogra‐
881 phy.
882 --csl=FILE
884 Set the csl field in the document's metadata to FILE, overriding
885 any value set in the metadata. (This is equivalent to --meta‐
886 data csl=FILE.) This option is only relevant with pan‐
887 doc-citeproc.
888 --citation-abbreviations=FILE
890 Set the citation-abbreviations field in the document's metadata
891 to FILE, overriding any value set in the metadata. (This is
892 equivalent to --metadata citation-abbreviations=FILE.) This
893 option is only relevant with pandoc-citeproc.
894 --natbib
896 Use natbib for citations in LaTeX output. This option is not
897 for use with the pandoc-citeproc filter or with PDF output. It
898 is intended for use in producing a LaTeX file that can be pro‐
899 cessed with bibtex.
900 --biblatex
902 Use biblatex for citations in LaTeX output. This option is not
903 for use with the pandoc-citeproc filter or with PDF output. It
904 is intended for use in producing a LaTeX file that can be pro‐
905 cessed with bibtex or biber.
906 Math rendering in HTML
908 The default is to render TeX math as far as possible using Unicode
909 characters. Formulas are put inside a span with class="math", so that
910 they may be styled differently from the surrounding text if needed.
911 However, this gives acceptable results only for basic math, usually you
912 will want to use --mathjax or another of the following options.
913 --mathjax[=URL]
915 Use MathJax to display embedded TeX math in HTML output. TeX
916 math will be put between \(...\) (for inline math) or \[...\]
917 (for display math) and wrapped in <span> tags with class math.
918 Then the MathJax JavaScript will render it. The URL should
919 point to the MathJax.js load script. If a URL is not provided,
920 a link to the Cloudflare CDN will be inserted.
921 --mathml
923 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
924 html4 and html5). This is the default in odt output. Note that
925 currently only Firefox and Safari (and select e-book readers)
926 natively support MathML.
927 --webtex[=URL]
929 Convert TeX formulas to <img> tags that link to an external
930 script that converts formulas to images. The formula will be
931 URL-encoded and concatenated with the URL provided. For SVG
932 images you can for example use --web‐
933 tex https://latex.codecogs.com/svg.latex?. If no URL is speci‐
934 fied, the CodeCogs URL generating PNGs will be used
935 (https://latex.codecogs.com/png.latex?). Note: the --webtex
936 option will affect Markdown output as well as HTML, which is
937 useful if you're targeting a version of Markdown without native
938 math support.
939 --katex[=URL]
941 Use KaTeX to display embedded TeX math in HTML output. The URL
942 is the base URL for the KaTeX library. If a URL is not pro‐
943 vided, a link to the KaTeX CDN will be inserted.
944 --katex-stylesheet=URL
946 The URL should point to the katex.css stylesheet. If this
947 option is not specified, a link to the KaTeX CDN will be
948 inserted. Note that this option does not imply --katex.
949 -m [URL], --latexmathml[=URL]
951 Deprecated. Use the LaTeXMathML script to display embedded TeX
952 math in HTML output. TeX math will be displayed between $ or $$
953 characters and put in <span> tags with class LaTeX. The LaTeX‐
954 MathML JavaScript will then change it to MathML. Note that cur‐
955 rently only Firefox and Safari (and select e-book readers)
956 natively support MathML. To insert a link the LaTeXMathML.js
957 script, provide a URL.
958 --jsmath[=URL]
960 Deprecated. Use jsMath (the predecessor of MathJax) to display
961 embedded TeX math in HTML output. TeX math will be put inside
962 <span> tags (for inline math) or <div> tags (for display math)
963 with class math and rendered by the jsMath script. The URL
964 should point to the script (e.g. jsMath/easy/load.js); if pro‐
965 vided, it will be linked to in the header of standalone HTML
966 documents. If a URL is not provided, no link to the jsMath load
967 script will be inserted; it is then up to the author to provide
968 such a link in the HTML template.
969 --gladtex
971 Deprecated. Enclose TeX math in <eq> tags in HTML output. The
972 resulting HTML can then be processed by gladTeX to produce
973 images of the typeset formulas and an HTML file with links to
974 these images. So, the procedure is:
975 pandoc -s --gladtex input.md -o myfile.htex
977 gladtex -d myfile-images myfile.htex
978 # produces myfile.html and images in myfile-images
979 --mimetex[=URL]
981 Deprecated. Render TeX math using the mimeTeX CGI script, which
982 generates an image for each TeX formula. This should work in
983 all browsers. If URL is not specified, it is assumed that the
984 script is at /cgi-bin/mimetex.cgi.
985 Options for wrapper scripts
987 --dump-args
988 Print information about command-line arguments to stdout, then
989 exit. This option is intended primarily for use in wrapper
990 scripts. The first line of output contains the name of the out‐
991 put file specified with the -o option, or - (for stdout) if no
992 output file was specified. The remaining lines contain the com‐
993 mand-line arguments, one per line, in the order they appear.
994 These do not include regular pandoc options and their arguments,
995 but do include any options appearing after a -- separator at the
996 end of the line.
997 --ignore-args
999 Ignore command-line arguments (for use in wrapper scripts).
1000 Regular pandoc options are not ignored. Thus, for example,
1001 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1003 is equivalent to
1005 pandoc -o foo.html -s
1007
1009 When the -s/--standalone option is used, pandoc uses a template to add
1010 header and footer material that is needed for a self-standing document.
1011 To see the default template that is used, just type
1012 pandoc -D *FORMAT*
1014 where FORMAT is the name of the output format. A custom template can
1016 be specified using the --template option. You can also override the
1017 system default templates for a given output format FORMAT by putting a
1018 file templates/default.*FORMAT* in the user data directory (see
1019 --data-dir, above). Exceptions:
1020 · For odt output, customize the default.opendocument template.
1022 · For pdf output, customize the default.latex template (or the
1024 default.context template, if you use -t context, or the default.ms
1025 template, if you use -t ms, or the default.html5 template, if you use
1026 -t html5).
1027 · docx has no template (however, you can use --reference-doc to custom‐
1029 ize the output).
1030 Templates contain variables, which allow for the inclusion of arbitrary
1032 information at any point in the file. Variables may be set within the
1033 document using YAML metadata blocks. They may also be set at the com‐
1034 mand line using the -V/--variable option: variables set in this way
1035 override metadata fields with the same name.
1036 Variables set by pandoc
1038 Some variables are set automatically by pandoc. These vary somewhat
1039 depending on the output format, but include metadata fields as well as
1040 the following:
1041 sourcefile, outputfile
1043 source and destination filenames, as given on the command line.
1044 sourcefile can also be a list if input comes from multiple
1045 files, or empty if input is from stdin. You can use the follow‐
1046 ing snippet in your template to distinguish them:
1047 $if(sourcefile)$
1049 $for(sourcefile)$
1050 $sourcefile$
1051 $endfor$
1052 $else$
1053 (stdin)
1054 $endif$
1055 Similarly, outputfile can be - if output goes to the terminal.
1057 title, author, date
1059 allow identification of basic aspects of the document. Included
1060 in PDF metadata through LaTeX and ConTeXt. These can be set
1061 through a pandoc title block, which allows for multiple authors,
1062 or through a YAML metadata block:
1063 ---
1065 author:
1066 - Aristotle
1067 - Peter Abelard
1068 ...
1069 subtitle
1071 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
1072 Word docx; renders in LaTeX only when using a document class
1073 that supports \subtitle, such as beamer or the KOMA-Script
1074 series (scrartcl, scrreprt, scrbook).
1075 institute
1077 author affiliations (in LaTeX and Beamer only). Can be a list,
1078 when there are multiple authors.
1079 abstract
1081 document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word
1082 docx
1083 keywords
1085 list of keywords to be included in HTML, PDF, and AsciiDoc meta‐
1086 data; may be repeated as for author, above
1087 header-includes
1089 contents specified by -H/--include-in-header (may have multiple
1090 values)
1091 toc non-null value if --toc/--table-of-contents was specified
1093 toc-title
1095 title of table of contents (works only with EPUB, opendocument,
1096 odt, docx, pptx)
1097 include-before
1099 contents specified by -B/--include-before-body (may have multi‐
1100 ple values)
1101 include-after
1103 contents specified by -A/--include-after-body (may have multiple
1104 values)
1105 body body of document
1107 meta-json
1109 JSON representation of all of the document's metadata. Field
1110 values are transformed to the selected output format.
1111 Language variables
1113 lang identifies the main language of the document, using a code
1114 according to BCP 47 (e.g. en or en-GB). For some output for‐
1115 mats, pandoc will convert it to an appropriate format stored in
1116 the additional variables babel-lang, polyglossia-lang (LaTeX)
1117 and context-lang (ConTeXt).
1118 Native pandoc Spans and Divs with the lang attribute (value in
1120 BCP 47) can be used to switch the language in that range. In
1121 LaTeX output, babel-otherlangs and polyglossia-otherlangs vari‐
1122 ables will be generated automatically based on the lang
1123 attributes of Spans and Divs in the document.
1124 dir the base direction of the document, either rtl (right-to-left)
1126 or ltr (left-to-right).
1127 For bidirectional documents, native pandoc spans and divs with
1129 the dir attribute (value rtl or ltr) can be used to override the
1130 base direction in some output formats. This may not always be
1131 necessary if the final renderer (e.g. the browser, when gener‐
1132 ating HTML) supports the Unicode Bidirectional Algorithm.
1133 When using LaTeX for bidirectional documents, only the xelatex
1135 engine is fully supported (use --pdf-engine=xelatex).
1136 Variables for slides
1138 Variables are available for producing slide shows with pandoc, includ‐
1139 ing all reveal.js configuration options.
1140 titlegraphic
1142 title graphic for Beamer documents
1143 logo logo for Beamer documents
1145 slidy-url
1147 base URL for Slidy documents (defaults to
1148 https://www.w3.org/Talks/Tools/Slidy2)
1149 slideous-url
1151 base URL for Slideous documents (defaults to slideous)
1152 s5-url base URL for S5 documents (defaults to s5/default)
1154 revealjs-url
1156 base URL for reveal.js documents (defaults to reveal.js)
1157 theme, colortheme, fonttheme, innertheme, outertheme
1159 themes for LaTeX beamer documents
1160 themeoptions
1162 options for LaTeX beamer themes (a list).
1163 navigation
1165 controls navigation symbols in beamer documents (default is
1166 empty for no navigation symbols; other valid values are frame,
1167 vertical, and horizontal).
1168 section-titles
1170 enables on "title pages" for new sections in beamer documents
1171 (default = true).
1172 beamerarticle
1174 when true, the beamerarticle package is loaded (for producing an
1175 article from beamer slides).
1176 aspectratio
1178 aspect ratio of slides (for beamer only, 1610 for 16:10, 169 for
1179 16:9, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 43 for 4:3 which
1180 is the default, and 32 for 3:2).
1181 Variables for LaTeX
1183 LaTeX variables are used when creating a PDF.
1184 papersize
1186 paper size, e.g. letter, a4
1187 fontsize
1189 font size for body text (e.g. 10pt, 12pt)
1190 documentclass
1192 document class, e.g. article, report, book, memoir
1193 classoption
1195 option for document class, e.g. oneside; may be repeated for
1196 multiple options
1197 geometry
1199 option for geometry package, e.g. margin=1in; may be repeated
1200 for multiple options
1201 margin-left, margin-right, margin-top, margin-bottom
1203 sets margins, if geometry is not used (otherwise geometry over‐
1204 rides these)
1205 linestretch
1207 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
1208 fontfamily
1210 font package for use with pdflatex: TeX Live includes many
1211 options, documented in the LaTeX Font Catalogue. The default is
1212 Latin Modern.
1213 fontfamilyoptions
1215 options for package used as fontfamily: e.g. osf,sc with font‐
1216 family set to mathpazo provides Palatino with old-style figures
1217 and true small caps; may be repeated for multiple options
1218 mainfont, sansfont, monofont, mathfont, CJKmainfont
1220 font families for use with xelatex or lualatex: take the name of
1221 any system font, using the fontspec package. Note that if CJK‐
1222 mainfont is used, the xecjk package must be available.
1223 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions,
1225 CJKoptions
1226 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
1227 mainfont in xelatex and lualatex. Allow for any choices avail‐
1228 able through fontspec, such as the OpenType features Num‐
1229 bers=OldStyle,Numbers=Proportional. May be repeated for multi‐
1230 ple options.
1231 fontenc
1233 allows font encoding to be specified through fontenc package
1234 (with pdflatex); default is T1 (see guide to LaTeX font encod‐
1235 ings)
1236 microtypeoptions
1238 options to pass to the microtype package
1239 colorlinks
1241 add color to link text; automatically enabled if any of link‐
1242 color, citecolor, urlcolor, or toccolor are set
1243 linkcolor, citecolor, urlcolor, toccolor
1245 color for internal links, citation links, external links, and
1246 links in table of contents: uses options allowed by xcolor,
1247 including the dvipsnames, svgnames, and x11names lists
1248 links-as-notes
1250 causes links to be printed as footnotes
1251 indent uses document class settings for indentation (the default LaTeX
1253 template otherwise removes indentation and adds space between
1254 paragraphs)
1255 subparagraph
1257 disables default behavior of LaTeX template that redefines
1258 (sub)paragraphs as sections, changing the appearance of nested
1259 headings in some classes
1260 thanks specifies contents of acknowledgments footnote after document
1262 title.
1263 toc include table of contents (can also be set using --toc/--ta‐
1265 ble-of-contents)
1266 toc-depth
1268 level of section to include in table of contents
1269 secnumdepth
1271 numbering depth for sections, if sections are numbered
1272 lof, lot
1274 include list of figures, list of tables
1275 bibliography
1277 bibliography to use for resolving references
1278 biblio-style
1280 bibliography style, when used with --natbib and --biblatex.
1281 biblio-title
1283 bibliography title, when used with --natbib and --biblatex.
1284 biblatexoptions
1286 list of options for biblatex.
1287 natbiboptions
1289 list of options for natbib.
1290 pagestyle
1292 An option for LaTeX's \pagestyle{}. The default article class
1293 supports 'plain' (default), 'empty', and 'headings'; headings
1294 puts section titles in the header.
1295 Variables for ConTeXt
1297 papersize
1298 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
1299 up); may be repeated for multiple options
1300 layout options for page margins and text arrangement (see ConTeXt Lay‐
1302 out); may be repeated for multiple options
1303 margin-left, margin-right, margin-top, margin-bottom
1305 sets margins, if layout is not used (otherwise layout overrides
1306 these)
1307 fontsize
1309 font size for body text (e.g. 10pt, 12pt)
1310 mainfont, sansfont, monofont, mathfont
1312 font families: take the name of any system font (see ConTeXt
1313 Font Switching)
1314 linkcolor, contrastcolor
1316 color for links outside and inside a page, e.g. red, blue (see
1317 ConTeXt Color)
1318 linkstyle
1320 typeface style for links, e.g. normal, bold, slanted, bold‐
1321 slanted, type, cap, small
1322 indenting
1324 controls indentation of paragraphs, e.g. yes,small,next (see
1325 ConTeXt Indentation); may be repeated for multiple options
1326 whitespace
1328 spacing between paragraphs, e.g. none, small (using setup‐
1329 whitespace)
1330 interlinespace
1332 adjusts line spacing, e.g. 4ex (using setupinterlinespace); may
1333 be repeated for multiple options
1334 headertext, footertext
1336 text to be placed in running header or footer (see ConTeXt Head‐
1337 ers and Footers); may be repeated up to four times for different
1338 placement
1339 pagenumbering
1341 page number style and location (using setuppagenumbering); may
1342 be repeated for multiple options
1343 toc include table of contents (can also be set using --toc/--ta‐
1345 ble-of-contents)
1346 lof, lot
1348 include list of figures, list of tables
1349 Variables for man pages
1351 section
1352 section number in man pages
1353 header header in man pages
1355 footer footer in man pages
1357 adjusting
1359 adjusts text to left (l), right (r), center (c), or both (b)
1360 margins
1361 hyphenate
1363 if true (the default), hyphenation will be used
1364 Variables for ms
1366 pointsize
1367 point size (e.g. 10p)
1368 lineheight
1370 line height (e.g. 12p)
1371 fontfamily
1373 font family (e.g. T or P)
1374 indent paragraph indent (e.g. 2m)
1376 Using variables in templates
1378 Variable names are sequences of alphanumerics, -, and _, starting with
1379 a letter. A variable name surrounded by $ signs will be replaced by
1380 its value. For example, the string $title$ in
1381 <title>$title$</title>
1383 will be replaced by the document title.
1385 To write a literal $ in a template, use $$.
1387 Templates may contain conditionals. The syntax is as follows:
1389 $if(variable)$
1391 X
1392 $else$
1393 Y
1394 $endif$
1395 This will include X in the template if variable has a non-null value;
1397 otherwise it will include Y. X and Y are placeholders for any valid
1398 template text, and may include interpolated variables or other condi‐
1399 tionals. The $else$ section may be omitted.
1400 When variables can have multiple values (for example, author in a
1402 multi-author document), you can use the $for$ keyword:
1403 $for(author)$
1405 <meta name="author" content="$author$" />
1406 $endfor$
1407 You can optionally specify a separator to be used between consecutive
1409 items:
1410 $for(author)$$author$$sep$, $endfor$
1412 A dot can be used to select a field of a variable that takes an object
1414 as its value. So, for example:
1415 $author.name$ ($author.affiliation$)
1417 If you use custom templates, you may need to revise them as pandoc
1419 changes. We recommend tracking the changes in the default templates,
1420 and modifying your custom templates accordingly. An easy way to do
1421 this is to fork the pandoc-templates repository and merge in changes
1422 after each pandoc release.
1423 Templates may contain comments: anything on a line after $-- will be
1425 treated as a comment and ignored.
1426
1428 The behavior of some of the readers and writers can be adjusted by
1429 enabling or disabling various extensions.
1430 An extension can be enabled by adding +EXTENSION to the format name and
1432 disabled by adding -EXTENSION. For example, --from mark‐
1433 down_strict+footnotes is strict Markdown with footnotes enabled, while
1434 --from markdown-footnotes-pipe_tables is pandoc's Markdown without
1435 footnotes or pipe tables.
1436 The markdown reader and writer make by far the most use of extensions.
1438 Extensions only used by them are therefore covered in the section Pan‐
1439 doc's Markdown below (See Markdown variants for commonmark and gfm.) In
1440 the following, extensions that also work for other formats are covered.
1441 Typography
1443 Extension: smart
1444 Interpret straight quotes as curly quotes, --- as em-dashes, -- as
1445 en-dashes, and ... as ellipses. Nonbreaking spaces are inserted after
1446 certain abbreviations, such as "Mr."
1447 This extension can be enabled/disabled for the following formats:
1449 input formats
1451 markdown, commonmark, latex, mediawiki, org, rst, twiki
1452 output formats
1454 markdown, latex, context, rst
1455 enabled by default in
1457 markdown, latex, context (both input and output)
1458 Note: If you are writing Markdown, then the smart extension has the
1460 reverse effect: what would have been curly quotes comes out straight.
1461 In LaTeX, smart means to use the standard TeX ligatures for quotation
1463 marks (`` and '' for double quotes, ` and ' for single quotes) and
1464 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
1465 then in reading LaTeX pandoc will parse these characters literally. In
1466 writing LaTeX, enabling smart tells pandoc to use the ligatures when
1467 possible; if smart is disabled pandoc will use unicode quotation mark
1468 and dash characters.
1469 Headers and sections
1471 Extension: auto_identifiers
1472 A header without an explicitly specified identifier will be automati‐
1473 cally assigned a unique identifier based on the header text.
1474 This extension can be enabled/disabled for the following formats:
1476 input formats
1478 markdown, latex, rst, mediawiki, textile
1479 output formats
1481 markdown, muse
1482 enabled by default in
1484 markdown, muse
1485 The algorithm used to derive the identifier from the header text is:
1487 · Remove all formatting, links, etc.
1489 · Remove all footnotes.
1491 · Remove all punctuation, except underscores, hyphens, and periods.
1493 · Replace all spaces and newlines with hyphens.
1495 · Convert all alphabetic characters to lowercase.
1497 · Remove everything up to the first letter (identifiers may not begin
1499 with a number or punctuation mark).
1500 · If nothing is left after this, use the identifier section.
1502 Thus, for example,
1504 Header Identifier
1506 ────────────────────────────────────────────────────────
1507 Header identifiers in HTML header-identifiers-in-html
1508 *Dogs*?--in *my* house? dogs--in-my-house
1509 [HTML], [S5], or [RTF]? html-s5-or-rtf
1510 3. Applications applications
1511 33 section
1512 These rules should, in most cases, allow one to determine the identi‐
1514 fier from the header text. The exception is when several headers have
1515 the same text; in this case, the first will get an identifier as
1516 described above; the second will get the same identifier with -1
1517 appended; the third with -2; and so on.
1518 These identifiers are used to provide link targets in the table of con‐
1520 tents generated by the --toc|--table-of-contents option. They also
1521 make it easy to provide links from one section of a document to
1522 another. A link to this section, for example, might look like this:
1523 See the section on
1525 [header identifiers](#header-identifiers-in-html-latex-and-context).
1526 Note, however, that this method of providing links to sections works
1528 only in HTML, LaTeX, and ConTeXt formats.
1529 If the --section-divs option is specified, then each section will be
1531 wrapped in a section (or a div, if html4 was specified), and the iden‐
1532 tifier will be attached to the enclosing <section> (or <div>) tag
1533 rather than the header itself. This allows entire sections to be
1534 manipulated using JavaScript or treated differently in CSS.
1535 Extension: ascii_identifiers
1537 Causes the identifiers produced by auto_identifiers to be pure ASCII.
1538 Accents are stripped off of accented Latin letters, and non-Latin let‐
1539 ters are omitted.
1540 Math Input
1542 The extensions tex_math_dollars, tex_math_single_backslash, and
1543 tex_math_double_backslash are described in the section about Pandoc's
1544 Markdown.
1545 However, they can also be used with HTML input. This is handy for
1547 reading web pages formatted using MathJax, for example.
1548 Raw HTML/TeX
1550 The following extensions (especially how they affect Markdown
1551 input/output) are also described in more detail in their respective
1552 sections of Pandoc's Markdown.
1553 Extension: raw_html
1555 When converting from HTML, parse elements to raw HTML which are not
1556 representable in pandoc's AST. By default, this is disabled for HTML
1557 input.
1558 Extension: raw_tex
1560 Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
1561 This extension can be enabled/disabled for the following formats (in
1563 addition to markdown):
1564 input formats
1566 latex, org, textile
1567 output formats
1569 textile
1570 Extension: native_divs
1572 This extension is enabled by default for HTML input. This means that
1573 divs are parsed to pandoc native elements. (Alternatively, you can
1574 parse them to raw HTML using -f html-native_divs+raw_html.)
1575 When converting HTML to Markdown, for example, you may want to drop all
1577 divs and spans:
1578 pandoc -f html-native_divs-native_spans -t markdown
1580 Extension: native_spans
1582 Analogous to native_divs above.
1583 Literate Haskell support
1585 Extension: literate_haskell
1586 Treat the document as literate Haskell source.
1587 This extension can be enabled/disabled for the following formats:
1589 input formats
1591 markdown, rst, latex
1592 output formats
1594 markdown, rst, latex, html
1595 If you append +lhs (or +literate_haskell) to one of the formats above,
1597 pandoc will treat the document as literate Haskell source. This means
1598 that
1599 · In Markdown input, "bird track" sections will be parsed as Haskell
1601 code rather than block quotations. Text between \begin{code} and
1602 \end{code} will also be treated as Haskell code. For ATX-style head‐
1603 ers the character '=' will be used instead of '#'.
1604 · In Markdown output, code blocks with classes haskell and literate
1606 will be rendered using bird tracks, and block quotations will be
1607 indented one space, so they will not be treated as Haskell code. In
1608 addition, headers will be rendered setext-style (with underlines)
1609 rather than ATX-style (with '#' characters). (This is because ghc
1610 treats '#' characters in column 1 as introducing line numbers.)
1611 · In restructured text input, "bird track" sections will be parsed as
1613 Haskell code.
1614 · In restructured text output, code blocks with class haskell will be
1616 rendered using bird tracks.
1617 · In LaTeX input, text in code environments will be parsed as Haskell
1619 code.
1620 · In LaTeX output, code blocks with class haskell will be rendered
1622 inside code environments.
1623 · In HTML output, code blocks with class haskell will be rendered with
1625 class literatehaskell and bird tracks.
1626 Examples:
1628 pandoc -f markdown+lhs -t html
1630 reads literate Haskell source formatted with Markdown conventions and
1632 writes ordinary HTML (without bird tracks).
1633 pandoc -f markdown+lhs -t html+lhs
1635 writes HTML with the Haskell code in bird tracks, so it can be copied
1637 and pasted as literate Haskell source.
1638 Note that GHC expects the bird tracks in the first column, so indentend
1640 literate code blocks (e.g. inside an itemized environment) will not be
1641 picked up by the Haskell compiler.
1642 Other extensions
1644 Extension: empty_paragraphs
1645 Allows empty paragraphs. By default empty paragraphs are omitted.
1646 This extension can be enabled/disabled for the following formats:
1648 input formats
1650 docx, html
1651 output formats
1653 markdown, docx, odt, opendocument, html
1654 Extension: styles
1656 Read all docx styles as divs (for paragraph styles) and spans (for
1657 character styles) regardless of whether pandoc understands the meaning
1658 of these styles. This can be used with docx custom styles. Disabled
1659 by default.
1660 input formats
1662 docx
1663 Extension: amuse
1665 In the muse input format, this enables Text::Amuse extensions to Emacs
1666 Muse markup.
1667 Extension: citations
1669 Some aspects of Pandoc's Markdown citation syntax are also accepted in
1670 org input.
1671 Extension: ntb
1673 In the context output format this enables the use of Natural Tables
1674 (TABLE) instead of the default Extreme Tables (xtables). Natural
1675 tables allow more fine-grained global customization but come at a per‐
1676 formance penalty compared to extreme tables.
1677
1679 Pandoc understands an extended and slightly revised version of John
1680 Gruber's Markdown syntax. This document explains the syntax, noting
1681 differences from standard Markdown. Except where noted, these differ‐
1682 ences can be suppressed by using the markdown_strict format instead of
1683 markdown. Extensions can be enabled or disabled to specify the behav‐
1684 ior more granularly. They are described in the following. See also
1685 Extensions above, for extensions that work also on other formats.
1686 Philosophy
1688 Markdown is designed to be easy to write, and, even more importantly,
1689 easy to read:
1690 A Markdown-formatted document should be publishable as-is, as
1692 plain text, without looking like it's been marked up with tags
1693 or formatting instructions. -- John Gruber
1694 This principle has guided pandoc's decisions in finding syntax for
1696 tables, footnotes, and other extensions.
1697 There is, however, one respect in which pandoc's aims are different
1699 from the original aims of Markdown. Whereas Markdown was originally
1700 designed with HTML generation in mind, pandoc is designed for multiple
1701 output formats. Thus, while pandoc allows the embedding of raw HTML,
1702 it discourages it, and provides other, non-HTMLish ways of representing
1703 important document elements like definition lists, tables, mathematics,
1704 and footnotes.
1705 Paragraphs
1707 A paragraph is one or more lines of text followed by one or more blank
1708 lines. Newlines are treated as spaces, so you can reflow your para‐
1709 graphs as you like. If you need a hard line break, put two or more
1710 spaces at the end of a line.
1711 Extension: escaped_line_breaks
1713 A backslash followed by a newline is also a hard line break. Note: in
1714 multiline and grid table cells, this is the only way to create a hard
1715 line break, since trailing spaces in the cells are ignored.
1716 Headers
1718 There are two kinds of headers: Setext and ATX.
1719 Setext-style headers
1721 A setext-style header is a line of text "underlined" with a row of =
1722 signs (for a level one header) or - signs (for a level two header):
1723 A level-one header
1725 ==================
1726 A level-two header
1728 ------------------
1729 The header text can contain inline formatting, such as emphasis (see
1731 Inline formatting, below).
1732 ATX-style headers
1734 An ATX-style header consists of one to six # signs and a line of text,
1735 optionally followed by any number of # signs. The number of # signs at
1736 the beginning of the line is the header level:
1737 ## A level-two header
1739 ### A level-three header ###
1741 As with setext-style headers, the header text can contain formatting:
1743 # A level-one header with a [link](/url) and *emphasis*
1745 Extension: blank_before_header
1747 Standard Markdown syntax does not require a blank line before a header.
1748 Pandoc does require this (except, of course, at the beginning of the
1749 document). The reason for the requirement is that it is all too easy
1750 for a # to end up at the beginning of a line by accident (perhaps
1751 through line wrapping). Consider, for example:
1752 I like several of their flavors of ice cream:
1754 #22, for example, and #5.
1755 Extension: space_in_atx_header
1757 Many Markdown implementations do not require a space between the open‐
1758 ing #s of an ATX header and the header text, so that #5 bolt and #hash‐
1759 tag count as headers. With this extension, pandoc does require the
1760 space.
1761 Header identifiers
1763 See also the auto_identifiers extension above.
1764 Extension: header_attributes
1766 Headers can be assigned attributes using this syntax at the end of the
1767 line containing the header text:
1768 {#identifier .class .class key=value key=value}
1770 Thus, for example, the following headers will all be assigned the iden‐
1772 tifier foo:
1773 # My header {#foo}
1775 ## My header ## {#foo}
1777 My other header {#foo}
1779 ---------------
1780 (This syntax is compatible with PHP Markdown Extra.)
1782 Note that although this syntax allows assignment of classes and
1784 key/value attributes, writers generally don't use all of this informa‐
1785 tion. Identifiers, classes, and key/value attributes are used in HTML
1786 and HTML-based formats such as EPUB and slidy. Identifiers are used
1787 for labels and link anchors in the LaTeX, ConTeXt, Textile, and Asci‐
1788 iDoc writers.
1789 Headers with the class unnumbered will not be numbered, even if --num‐
1791 ber-sections is specified. A single hyphen (-) in an attribute context
1792 is equivalent to .unnumbered, and preferable in non-English documents.
1793 So,
1794 # My header {-}
1796 is just the same as
1798 # My header {.unnumbered}
1800 Extension: implicit_header_references
1802 Pandoc behaves as if reference links have been defined for each header.
1803 So, to link to a header
1804 # Header identifiers in HTML
1806 you can simply write
1808 [Header identifiers in HTML]
1810 or
1812 [Header identifiers in HTML][]
1814 or
1816 [the section on header identifiers][header identifiers in
1818 HTML]
1819 instead of giving the identifier explicitly:
1821 [Header identifiers in HTML](#header-identifiers-in-html)
1823 If there are multiple headers with identical text, the corresponding
1825 reference will link to the first one only, and you will need to use
1826 explicit links to link to the others, as described above.
1827 Like regular reference links, these references are case-insensitive.
1829 Explicit link reference definitions always take priority over implicit
1831 header references. So, in the following example, the link will point
1832 to bar, not to #foo:
1833 # Foo
1835 [foo]: bar
1837 See [foo]
1839 Block quotations
1841 Markdown uses email conventions for quoting blocks of text. A block
1842 quotation is one or more paragraphs or other block elements (such as
1843 lists or headers), with each line preceded by a > character and an
1844 optional space. (The > need not start at the left margin, but it
1845 should not be indented more than three spaces.)
1846 > This is a block quote. This
1848 > paragraph has two lines.
1849 >
1850 > 1. This is a list inside a block quote.
1851 > 2. Second item.
1852 A "lazy" form, which requires the > character only on the first line of
1854 each block, is also allowed:
1855 > This is a block quote. This
1857 paragraph has two lines.
1858 > 1. This is a list inside a block quote.
1860 2. Second item.
1861 Among the block elements that can be contained in a block quote are
1863 other block quotes. That is, block quotes can be nested:
1864 > This is a block quote.
1866 >
1867 > > A block quote within a block quote.
1868 If the > character is followed by an optional space, that space will be
1870 considered part of the block quote marker and not part of the indenta‐
1871 tion of the contents. Thus, to put an indented code block in a block
1872 quote, you need five spaces after the >:
1873 > code
1875 Extension: blank_before_blockquote
1877 Standard Markdown syntax does not require a blank line before a block
1878 quote. Pandoc does require this (except, of course, at the beginning
1879 of the document). The reason for the requirement is that it is all too
1880 easy for a > to end up at the beginning of a line by accident (perhaps
1881 through line wrapping). So, unless the markdown_strict format is used,
1882 the following does not produce a nested block quote in pandoc:
1883 > This is a block quote.
1885 >> Nested.
1886 Verbatim (code) blocks
1888 Indented code blocks
1889 A block of text indented four spaces (or one tab) is treated as verba‐
1890 tim text: that is, special characters do not trigger special format‐
1891 ting, and all spaces and line breaks are preserved. For example,
1892 if (a > 3) {
1894 moveShip(5 * gravity, DOWN);
1895 }
1896 The initial (four space or one tab) indentation is not considered part
1898 of the verbatim text, and is removed in the output.
1899 Note: blank lines in the verbatim text need not begin with four spaces.
1901 Fenced code blocks
1903 Extension: fenced_code_blocks
1904 In addition to standard indented code blocks, pandoc supports fenced
1905 code blocks. These begin with a row of three or more tildes (~) and
1906 end with a row of tildes that must be at least as long as the starting
1907 row. Everything between these lines is treated as code. No indenta‐
1908 tion is necessary:
1909 ~~~~~~~
1911 if (a > 3) {
1912 moveShip(5 * gravity, DOWN);
1913 }
1914 ~~~~~~~
1915 Like regular code blocks, fenced code blocks must be separated from
1917 surrounding text by blank lines.
1918 If the code itself contains a row of tildes or backticks, just use a
1920 longer row of tildes or backticks at the start and end:
1921 ~~~~~~~~~~~~~~~~
1923 ~~~~~~~~~~
1924 code including tildes
1925 ~~~~~~~~~~
1926 ~~~~~~~~~~~~~~~~
1927 Extension: backtick_code_blocks
1929 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
1930 (~).
1931 Extension: fenced_code_attributes
1933 Optionally, you may attach attributes to fenced or backtick code block
1934 using this syntax:
1935 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
1937 qsort [] = []
1938 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
1939 qsort (filter (>= x) xs)
1940 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1941 Here mycode is an identifier, haskell and numberLines are classes, and
1943 startFrom is an attribute with value 100. Some output formats can use
1944 this information to do syntax highlighting. Currently, the only output
1945 formats that uses this information are HTML, LaTeX, Docx, Ms, and Pow‐
1946 erPoint. If highlighting is supported for your output format and lan‐
1947 guage, then the code block above will appear highlighted, with numbered
1948 lines. (To see which languages are supported, type pandoc --list-high‐
1949 light-languages.) Otherwise, the code block above will appear as fol‐
1950 lows:
1951 <pre id="mycode" class="haskell numberLines" startFrom="100">
1953 <code>
1954 ...
1955 </code>
1956 </pre>
1957 The numberLines (or number-lines) class will cause the lines of the
1959 code block to be numbered, starting with 1 or the value of the start‐
1960 From attribute. The lineAnchors (or line-anchors) class will cause the
1961 lines to be clickable anchors in HTML output.
1962 A shortcut form can also be used for specifying the language of the
1964 code block:
1965 ```haskell
1967 qsort [] = []
1968 ```
1969 This is equivalent to:
1971 ``` {.haskell}
1973 qsort [] = []
1974 ```
1975 If the fenced_code_attributes extension is disabled, but input contains
1977 class attribute(s) for the code block, the first class attribute will
1978 be printed after the opening fence as a bare word.
1979 To prevent all highlighting, use the --no-highlight flag. To set the
1981 highlighting style, use --highlight-style. For more information on
1982 highlighting, see Syntax highlighting, below.
1983 Line blocks
1985 Extension: line_blocks
1986 A line block is a sequence of lines beginning with a vertical bar (|)
1987 followed by a space. The division into lines will be preserved in the
1988 output, as will any leading spaces; otherwise, the lines will be for‐
1989 matted as Markdown. This is useful for verse and addresses:
1990 | The limerick packs laughs anatomical
1992 | In space that is quite economical.
1993 | But the good ones I've seen
1994 | So seldom are clean
1995 | And the clean ones so seldom are comical
1996 | 200 Main St.
1998 | Berkeley, CA 94718
1999 The lines can be hard-wrapped if needed, but the continuation line must
2001 begin with a space.
2002 | The Right Honorable Most Venerable and Righteous Samuel L.
2004 Constable, Jr.
2005 | 200 Main St.
2006 | Berkeley, CA 94718
2007 This syntax is borrowed from reStructuredText.
2009 Lists
2011 Bullet lists
2012 A bullet list is a list of bulleted list items. A bulleted list item
2013 begins with a bullet (*, +, or -). Here is a simple example:
2014 * one
2016 * two
2017 * three
2018 This will produce a "compact" list. If you want a "loose" list, in
2020 which each item is formatted as a paragraph, put spaces between the
2021 items:
2022 * one
2024 * two
2026 * three
2028 The bullets need not be flush with the left margin; they may be
2030 indented one, two, or three spaces. The bullet must be followed by
2031 whitespace.
2032 List items look best if subsequent lines are flush with the first line
2034 (after the bullet):
2035 * here is my first
2037 list item.
2038 * and my second.
2039 But Markdown also allows a "lazy" format:
2041 * here is my first
2043 list item.
2044 * and my second.
2045 Block content in list items
2047 A list item may contain multiple paragraphs and other block-level con‐
2048 tent. However, subsequent paragraphs must be preceded by a blank line
2049 and indented to line up with the first non-space content after the list
2050 marker.
2051 * First paragraph.
2053 Continued.
2055 * Second paragraph. With a code block, which must be indented
2057 eight spaces:
2058 { code }
2060 Exception: if the list marker is followed by an indented code block,
2062 which must begin 5 spaces after the list marker, then subsequent para‐
2063 graphs must begin two columns after the last character of the list
2064 marker:
2065 * code
2067 continuation paragraph
2069 List items may include other lists. In this case the preceding blank
2071 line is optional. The nested list must be indented to line up with the
2072 first non-space character after the list marker of the containing list
2073 item.
2074 * fruits
2076 + apples
2077 - macintosh
2078 - red delicious
2079 + pears
2080 + peaches
2081 * vegetables
2082 + broccoli
2083 + chard
2084 As noted above, Markdown allows you to write list items "lazily,"
2086 instead of indenting continuation lines. However, if there are multi‐
2087 ple paragraphs or other blocks in a list item, the first line of each
2088 must be indented.
2089 + A lazy, lazy, list
2091 item.
2092 + Another one; this looks
2094 bad but is legal.
2095 Second paragraph of second
2097 list item.
2098 Ordered lists
2100 Ordered lists work just like bulleted lists, except that the items
2101 begin with enumerators rather than bullets.
2102 In standard Markdown, enumerators are decimal numbers followed by a
2104 period and a space. The numbers themselves are ignored, so there is no
2105 difference between this list:
2106 1. one
2108 2. two
2109 3. three
2110 and this one:
2112 5. one
2114 7. two
2115 1. three
2116 Extension: fancy_lists
2118 Unlike standard Markdown, pandoc allows ordered list items to be marked
2119 with uppercase and lowercase letters and roman numerals, in addition to
2120 Arabic numerals. List markers may be enclosed in parentheses or fol‐
2121 lowed by a single right-parentheses or period. They must be separated
2122 from the text that follows by at least one space, and, if the list
2123 marker is a capital letter with a period, by at least two spaces.
2124 The fancy_lists extension also allows '#' to be used as an ordered list
2126 marker in place of a numeral:
2127 #. one
2129 #. two
2130 Extension: startnum
2132 Pandoc also pays attention to the type of list marker used, and to the
2133 starting number, and both of these are preserved where possible in the
2134 output format. Thus, the following yields a list with numbers followed
2135 by a single parenthesis, starting with 9, and a sublist with lowercase
2136 roman numerals:
2137 9) Ninth
2139 10) Tenth
2140 11) Eleventh
2141 i. subone
2142 ii. subtwo
2143 iii. subthree
2144 Pandoc will start a new list each time a different type of list marker
2146 is used. So, the following will create three lists:
2147 (2) Two
2149 (5) Three
2150 1. Four
2151 * Five
2152 If default list markers are desired, use #.:
2154 #. one
2156 #. two
2157 #. three
2158 Definition lists
2160 Extension: definition_lists
2161 Pandoc supports definition lists, using the syntax of PHP Markdown
2162 Extra with some extensions.
2163 Term 1
2165 : Definition 1
2167 Term 2 with *inline markup*
2169 : Definition 2
2171 { some code, part of Definition 2 }
2173 Third paragraph of definition 2.
2175 Each term must fit on one line, which may optionally be followed by a
2177 blank line, and must be followed by one or more definitions. A defini‐
2178 tion begins with a colon or tilde, which may be indented one or two
2179 spaces.
2180 A term may have multiple definitions, and each definition may consist
2182 of one or more block elements (paragraph, code block, list, etc.), each
2183 indented four spaces or one tab stop. The body of the definition
2184 (including the first line, aside from the colon or tilde) should be
2185 indented four spaces. However, as with other Markdown lists, you can
2186 "lazily" omit indentation except at the beginning of a paragraph or
2187 other block element:
2188 Term 1
2190 : Definition
2192 with lazy continuation.
2193 Second paragraph of the definition.
2195 If you leave space before the definition (as in the example above), the
2197 text of the definition will be treated as a paragraph. In some output
2198 formats, this will mean greater spacing between term/definition pairs.
2199 For a more compact definition list, omit the space before the defini‐
2200 tion:
2201 Term 1
2203 ~ Definition 1
2204 Term 2
2206 ~ Definition 2a
2207 ~ Definition 2b
2208 Note that space between items in a definition list is required. (A
2210 variant that loosens this requirement, but disallows "lazy" hard wrap‐
2211 ping, can be activated with compact_definition_lists: see Non-pandoc
2212 extensions, below.)
2213 Numbered example lists
2215 Extension: example_lists
2216 The special list marker @ can be used for sequentially numbered exam‐
2217 ples. The first list item with a @ marker will be numbered '1', the
2218 next '2', and so on, throughout the document. The numbered examples
2219 need not occur in a single list; each new list using @ will take up
2220 where the last stopped. So, for example:
2221 (@) My first example will be numbered (1).
2223 (@) My second example will be numbered (2).
2224 Explanation of examples.
2226 (@) My third example will be numbered (3).
2228 Numbered examples can be labeled and referred to elsewhere in the docu‐
2230 ment:
2231 (@good) This is a good example.
2233 As (@good) illustrates, ...
2235 The label can be any string of alphanumeric characters, underscores, or
2237 hyphens.
2238 Note: continuation paragraphs in example lists must always be indented
2240 four spaces, regardless of the length of the list marker. That is,
2241 example lists always behave as if the four_space_rule extension is set.
2242 This is because example labels tend to be long, and indenting content
2243 to the first non-space character after the label would be awkward.
2244 Compact and loose lists
2246 Pandoc behaves differently from Markdown.pl on some "edge cases"
2247 involving lists. Consider this source:
2248 + First
2250 + Second:
2251 - Fee
2252 - Fie
2253 - Foe
2254 + Third
2256 Pandoc transforms this into a "compact list" (with no <p> tags around
2258 "First", "Second", or "Third"), while Markdown puts <p> tags around
2259 "Second" and "Third" (but not "First"), because of the blank space
2260 around "Third". Pandoc follows a simple rule: if the text is followed
2261 by a blank line, it is treated as a paragraph. Since "Second" is fol‐
2262 lowed by a list, and not a blank line, it isn't treated as a paragraph.
2263 The fact that the list is followed by a blank line is irrelevant.
2264 (Note: Pandoc works this way even when the markdown_strict format is
2265 specified. This behavior is consistent with the official Markdown syn‐
2266 tax description, even though it is different from that of Markdown.pl.)
2267 Ending a list
2269 What if you want to put an indented code block after a list?
2270 - item one
2272 - item two
2273 { my code block }
2275 Trouble! Here pandoc (like other Markdown implementations) will treat
2277 { my code block } as the second paragraph of item two, and not as a
2278 code block.
2279 To "cut off" the list after item two, you can insert some non-indented
2281 content, like an HTML comment, which won't produce visible output in
2282 any format:
2283 - item one
2285 - item two
2286 <!-- end of list -->
2288 { my code block }
2290 You can use the same trick if you want two consecutive lists instead of
2292 one big list:
2293 1. one
2295 2. two
2296 3. three
2297 <!-- -->
2299 1. uno
2301 2. dos
2302 3. tres
2303 Horizontal rules
2305 A line containing a row of three or more *, -, or _ characters (option‐
2306 ally separated by spaces) produces a horizontal rule:
2307 * * * *
2309 ---------------
2311 Tables
2313 Four kinds of tables may be used. The first three kinds presuppose the
2314 use of a fixed-width font, such as Courier. The fourth kind can be
2315 used with proportionally spaced fonts, as it does not require lining up
2316 columns.
2317 Extension: table_captions
2319 A caption may optionally be provided with all 4 kinds of tables (as
2320 illustrated in the examples below). A caption is a paragraph beginning
2321 with the string Table: (or just :), which will be stripped off. It may
2322 appear either before or after the table.
2323 Extension: simple_tables
2325 Simple tables look like this:
2326 Right Left Center Default
2328 ------- ------ ---------- -------
2329 12 12 12 12
2330 123 123 123 123
2331 1 1 1 1
2332 Table: Demonstration of simple table syntax.
2334 The headers and table rows must each fit on one line. Column align‐
2336 ments are determined by the position of the header text relative to the
2337 dashed line below it:
2338 · If the dashed line is flush with the header text on the right side
2340 but extends beyond it on the left, the column is right-aligned.
2341 · If the dashed line is flush with the header text on the left side but
2343 extends beyond it on the right, the column is left-aligned.
2344 · If the dashed line extends beyond the header text on both sides, the
2346 column is centered.
2347 · If the dashed line is flush with the header text on both sides, the
2349 default alignment is used (in most cases, this will be left).
2350 The table must end with a blank line, or a line of dashes followed by a
2352 blank line.
2353 The column headers may be omitted, provided a dashed line is used to
2355 end the table. For example:
2356 ------- ------ ---------- -------
2358 12 12 12 12
2359 123 123 123 123
2360 1 1 1 1
2361 ------- ------ ---------- -------
2362 When headers are omitted, column alignments are determined on the basis
2364 of the first line of the table body. So, in the tables above, the col‐
2365 umns would be right, left, center, and right aligned, respectively.
2366 Extension: multiline_tables
2368 Multiline tables allow headers and table rows to span multiple lines of
2369 text (but cells that span multiple columns or rows of the table are not
2370 supported). Here is an example:
2371 -------------------------------------------------------------
2373 Centered Default Right Left
2374 Header Aligned Aligned Aligned
2375 ----------- ------- --------------- -------------------------
2376 First row 12.0 Example of a row that
2377 spans multiple lines.
2378 Second row 5.0 Here's another one. Note
2380 the blank line between
2381 rows.
2382 -------------------------------------------------------------
2383 Table: Here's the caption. It, too, may span
2385 multiple lines.
2386 These work like simple tables, but with the following differences:
2388 · They must begin with a row of dashes, before the header text (unless
2390 the headers are omitted).
2391 · They must end with a row of dashes, then a blank line.
2393 · The rows must be separated by blank lines.
2395 In multiline tables, the table parser pays attention to the widths of
2397 the columns, and the writers try to reproduce these relative widths in
2398 the output. So, if you find that one of the columns is too narrow in
2399 the output, try widening it in the Markdown source.
2400 Headers may be omitted in multiline tables as well as simple tables:
2402 ----------- ------- --------------- -------------------------
2404 First row 12.0 Example of a row that
2405 spans multiple lines.
2406 Second row 5.0 Here's another one. Note
2408 the blank line between
2409 rows.
2410 ----------- ------- --------------- -------------------------
2411 : Here's a multiline table without headers.
2413 It is possible for a multiline table to have just one row, but the row
2415 should be followed by a blank line (and then the row of dashes that
2416 ends the table), or the table may be interpreted as a simple table.
2417 Extension: grid_tables
2419 Grid tables look like this:
2420 : Sample grid table.
2422 +---------------+---------------+--------------------+
2424 | Fruit | Price | Advantages |
2425 +===============+===============+====================+
2426 | Bananas | $1.34 | - built-in wrapper |
2427 | | | - bright color |
2428 +---------------+---------------+--------------------+
2429 | Oranges | $2.10 | - cures scurvy |
2430 | | | - tasty |
2431 +---------------+---------------+--------------------+
2432 The row of =s separates the header from the table body, and can be
2434 omitted for a headerless table. The cells of grid tables may contain
2435 arbitrary block elements (multiple paragraphs, code blocks, lists,
2436 etc.). Cells that span multiple columns or rows are not supported.
2437 Grid tables can be created easily using Emacs table mode.
2438 Alignments can be specified as with pipe tables, by putting colons at
2440 the boundaries of the separator line after the header:
2441 +---------------+---------------+--------------------+
2443 | Right | Left | Centered |
2444 +==============:+:==============+:==================:+
2445 | Bananas | $1.34 | built-in wrapper |
2446 +---------------+---------------+--------------------+
2447 For headerless tables, the colons go on the top line instead:
2449 +--------------:+:--------------+:------------------:+
2451 | Right | Left | Centered |
2452 +---------------+---------------+--------------------+
2453 Grid Table Limitations
2455 Pandoc does not support grid tables with row spans or column spans.
2456 This means that neither variable numbers of columns across rows nor
2457 variable numbers of rows across columns are supported by Pandoc. All
2458 grid tables must have the same number of columns in each row, and the
2459 same number of rows in each column. For example, the Docutils sample
2460 grid tables will not render as expected with Pandoc.
2461 Extension: pipe_tables
2463 Pipe tables look like this:
2464 | Right | Left | Default | Center |
2466 |------:|:-----|---------|:------:|
2467 | 12 | 12 | 12 | 12 |
2468 | 123 | 123 | 123 | 123 |
2469 | 1 | 1 | 1 | 1 |
2470 : Demonstration of pipe table syntax.
2472 The syntax is identical to PHP Markdown Extra tables. The beginning
2474 and ending pipe characters are optional, but pipes are required between
2475 all columns. The colons indicate column alignment as shown. The
2476 header cannot be omitted. To simulate a headerless table, include a
2477 header with blank cells.
2478 Since the pipes indicate column boundaries, columns need not be verti‐
2480 cally aligned, as they are in the above example. So, this is a per‐
2481 fectly legal (though ugly) pipe table:
2482 fruit| price
2484 -----|-----:
2485 apple|2.05
2486 pear|1.37
2487 orange|3.09
2488 The cells of pipe tables cannot contain block elements like paragraphs
2490 and lists, and cannot span multiple lines. If a pipe table contains a
2491 row whose printable content is wider than the column width (see --col‐
2492 umns), then the cell contents will wrap, with the relative cell widths
2493 determined by the widths of the separator lines. (In this case, the
2494 table will take up the full text width.) If no lines are wider than
2495 column width, then cell contents will not be wrapped, and the cells
2496 will be sized to their contents.
2497 Note: pandoc also recognizes pipe tables of the following form, as can
2499 be produced by Emacs' orgtbl-mode:
2500 | One | Two |
2502 |-----+-------|
2503 | my | table |
2504 | is | nice |
2505 The difference is that + is used instead of |. Other orgtbl features
2507 are not supported. In particular, to get non-default column alignment,
2508 you'll need to add colons as above.
2509 Metadata blocks
2511 Extension: pandoc_title_block
2512 If the file begins with a title block
2513 % title
2515 % author(s) (separated by semicolons)
2516 % date
2517 it will be parsed as bibliographic information, not regular text. (It
2519 will be used, for example, in the title of standalone LaTeX or HTML
2520 output.) The block may contain just a title, a title and an author, or
2521 all three elements. If you want to include an author but no title, or
2522 a title and a date but no author, you need a blank line:
2523 %
2525 % Author
2526 % My title
2528 %
2529 % June 15, 2006
2530 The title may occupy multiple lines, but continuation lines must begin
2532 with leading space, thus:
2533 % My title
2535 on multiple lines
2536 If a document has multiple authors, the authors may be put on separate
2538 lines with leading space, or separated by semicolons, or both. So, all
2539 of the following are equivalent:
2540 % Author One
2542 Author Two
2543 % Author One; Author Two
2545 % Author One;
2547 Author Two
2548 The date must fit on one line.
2550 All three metadata fields may contain standard inline formatting (ital‐
2552 ics, links, footnotes, etc.).
2553 Title blocks will always be parsed, but they will affect the output
2555 only when the --standalone (-s) option is chosen. In HTML output,
2556 titles will appear twice: once in the document head -- this is the
2557 title that will appear at the top of the window in a browser -- and
2558 once at the beginning of the document body. The title in the document
2559 head can have an optional prefix attached (--title-prefix or -T
2560 option). The title in the body appears as an H1 element with class
2561 "title", so it can be suppressed or reformatted with CSS. If a title
2562 prefix is specified with -T and no title block appears in the document,
2563 the title prefix will be used by itself as the HTML title.
2564 The man page writer extracts a title, man page section number, and
2566 other header and footer information from the title line. The title is
2567 assumed to be the first word on the title line, which may optionally
2568 end with a (single-digit) section number in parentheses. (There should
2569 be no space between the title and the parentheses.) Anything after
2570 this is assumed to be additional footer and header text. A single pipe
2571 character (|) should be used to separate the footer text from the
2572 header text. Thus,
2573 % PANDOC(1)
2575 will yield a man page with the title PANDOC and section 1.
2577 % PANDOC(1) Pandoc User Manuals
2579 will also have "Pandoc User Manuals" in the footer.
2581 % PANDOC(1) Pandoc User Manuals | Version 4.0
2583 will also have "Version 4.0" in the header.
2585 Extension: yaml_metadata_block
2587 A YAML metadata block is a valid YAML object, delimited by a line of
2588 three hyphens (---) at the top and a line of three hyphens (---) or
2589 three dots (...) at the bottom. A YAML metadata block may occur any‐
2590 where in the document, but if it is not at the beginning, it must be
2591 preceded by a blank line. (Note that, because of the way pandoc con‐
2592 catenates input files when several are provided, you may also keep the
2593 metadata in a separate YAML file and pass it to pandoc as an argument,
2594 along with your Markdown files:
2595 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
2597 Just be sure that the YAML file begins with --- and ends with --- or
2599 ....)
2600 Metadata will be taken from the fields of the YAML object and added to
2602 any existing document metadata. Metadata can contain lists and objects
2603 (nested arbitrarily), but all string scalars will be interpreted as
2604 Markdown. Fields with names ending in an underscore will be ignored by
2605 pandoc. (They may be given a role by external processors.)
2606 A document may contain multiple metadata blocks. The metadata fields
2608 will be combined through a left-biased union: if two metadata blocks
2609 attempt to set the same field, the value from the first block will be
2610 taken.
2611 When pandoc is used with -t markdown to create a Markdown document, a
2613 YAML metadata block will be produced only if the -s/--standalone option
2614 is used. All of the metadata will appear in a single block at the
2615 beginning of the document.
2616 Note that YAML escaping rules must be followed. Thus, for example, if
2618 a title contains a colon, it must be quoted. The pipe character (|)
2619 can be used to begin an indented block that will be interpreted liter‐
2620 ally, without need for escaping. This form is necessary when the field
2621 contains blank lines or block-level formatting:
2622 ---
2624 title: 'This is the title: it contains a colon'
2625 author:
2626 - Author One
2627 - Author Two
2628 tags: [nothing, nothingness]
2629 abstract: |
2630 This is the abstract.
2631 It consists of two paragraphs.
2633 ...
2634 Template variables will be set automatically from the metadata. Thus,
2636 for example, in writing HTML, the variable abstract will be set to the
2637 HTML equivalent of the Markdown in the abstract field:
2638 <p>This is the abstract.</p>
2640 <p>It consists of two paragraphs.</p>
2641 Variables can contain arbitrary YAML structures, but the template must
2643 match this structure. The author variable in the default templates
2644 expects a simple list or string, but can be changed to support more
2645 complicated structures. The following combination, for example, would
2646 add an affiliation to the author if one is given:
2647 ---
2649 title: The document title
2650 author:
2651 - name: Author One
2652 affiliation: University of Somewhere
2653 - name: Author Two
2654 affiliation: University of Nowhere
2655 ...
2656 To use the structured authors in the example above, you would need a
2658 custom template:
2659 $for(author)$
2661 $if(author.name)$
2662 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
2663 $else$
2664 $author$
2665 $endif$
2666 $endfor$
2667 Raw content to include in the document's header may be specified using
2669 header-includes; however, it is important to mark up this content as
2670 raw code for a particular output format, using the raw_attribute exten‐
2671 sion), or it will be interpreted as markdown. For example:
2672 header-includes:
2674 - ```{=latex}
2675 \let\oldsection\section
2676 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
2677 ```
2678 Backslash escapes
2680 Extension: all_symbols_escapable
2681 Except inside a code block or inline code, any punctuation or space
2682 character preceded by a backslash will be treated literally, even if it
2683 would normally indicate formatting. Thus, for example, if one writes
2684 *\*hello\**
2686 one will get
2688 <em>*hello*</em>
2690 instead of
2692 <strong>hello</strong>
2694 This rule is easier to remember than standard Markdown's rule, which
2696 allows only the following characters to be backslash-escaped:
2697 \`*_{}[]()>#+-.!
2699 (However, if the markdown_strict format is used, the standard Markdown
2701 rule will be used.)
2702 A backslash-escaped space is parsed as a nonbreaking space. It will
2704 appear in TeX output as ~ and in HTML and XML as \  or \ .
2705 A backslash-escaped newline (i.e. a backslash occurring at the end of
2707 a line) is parsed as a hard line break. It will appear in TeX output
2708 as \\ and in HTML as <br />. This is a nice alternative to Markdown's
2709 "invisible" way of indicating hard line breaks using two trailing spa‐
2710 ces on a line.
2711 Backslash escapes do not work in verbatim contexts.
2713 Inline formatting
2715 Emphasis
2716 To emphasize some text, surround it with *s or _, like this:
2717 This text is _emphasized with underscores_, and this
2719 is *emphasized with asterisks*.
2720 Double * or _ produces strong emphasis:
2722 This is **strong emphasis** and __with underscores__.
2724 A * or _ character surrounded by spaces, or backslash-escaped, will not
2726 trigger emphasis:
2727 This is * not emphasized *, and \*neither is this\*.
2729 Extension: intraword_underscores
2731 Because _ is sometimes used inside words and identifiers, pandoc does
2732 not interpret a _ surrounded by alphanumeric characters as an emphasis
2733 marker. If you want to emphasize just part of a word, use *:
2734 feas*ible*, not feas*able*.
2736 Strikeout
2738 Extension: strikeout
2739 To strikeout a section of text with a horizontal line, begin and end it
2740 with ~~. Thus, for example,
2741 This ~~is deleted text.~~
2743 Superscripts and subscripts
2745 Extension: superscript, subscript
2746 Superscripts may be written by surrounding the superscripted text by ^
2747 characters; subscripts may be written by surrounding the subscripted
2748 text by ~ characters. Thus, for example,
2749 H~2~O is a liquid. 2^10^ is 1024.
2751 If the superscripted or subscripted text contains spaces, these spaces
2753 must be escaped with backslashes. (This is to prevent accidental
2754 superscripting and subscripting through the ordinary use of ~ and ^.)
2755 Thus, if you want the letter P with 'a cat' in subscripts, use
2756 P~a\ cat~, not P~a cat~.
2757 Verbatim
2759 To make a short span of text verbatim, put it inside backticks:
2760 What is the difference between `>>=` and `>>`?
2762 If the verbatim text includes a backtick, use double backticks:
2764 Here is a literal backtick `` ` ``.
2766 (The spaces after the opening backticks and before the closing back‐
2768 ticks will be ignored.)
2769 The general rule is that a verbatim span starts with a string of con‐
2771 secutive backticks (optionally followed by a space) and ends with a
2772 string of the same number of backticks (optionally preceded by a
2773 space).
2774 Note that backslash-escapes (and other Markdown constructs) do not work
2776 in verbatim contexts:
2777 This is a backslash followed by an asterisk: `\*`.
2779 Extension: inline_code_attributes
2781 Attributes can be attached to verbatim text, just as with fenced code
2782 blocks:
2783 `<$>`{.haskell}
2785 Small caps
2787 To write small caps, use the smallcaps class:
2788 [Small caps]{.smallcaps}
2790 Or, without the bracketed_spans extension:
2792 <span class="smallcaps">Small caps</span>
2794 For compatibility with other Markdown flavors, CSS is also supported:
2796 <span style="font-variant:small-caps;">Small caps</span>
2798 This will work in all output formats that support small caps.
2800 Math
2802 Extension: tex_math_dollars
2803 Anything between two $ characters will be treated as TeX math. The
2804 opening $ must have a non-space character immediately to its right,
2805 while the closing $ must have a non-space character immediately to its
2806 left, and must not be followed immediately by a digit. Thus,
2807 $20,000 and $30,000 won't parse as math. If for some reason you need
2808 to enclose text in literal $ characters, backslash-escape them and they
2809 won't be treated as math delimiters.
2810 TeX math will be printed in all output formats. How it is rendered
2812 depends on the output format:
2813 Markdown, LaTeX, Emacs Org mode, ConTeXt, ZimWiki
2815 It will appear verbatim between $ characters.
2816 reStructuredText
2818 It will be rendered using an interpreted text role :math:.
2819 AsciiDoc
2821 It will be rendered as latexmath:[...].
2822 Texinfo
2824 It will be rendered inside a @math command.
2825 groff man
2827 It will be rendered verbatim without $'s.
2828 MediaWiki, DokuWiki
2830 It will be rendered inside <math> tags.
2831 Textile
2833 It will be rendered inside <span class="math"> tags.
2834 RTF, OpenDocument
2836 It will be rendered, if possible, using Unicode characters, and
2837 will otherwise appear verbatim.
2838 ODT It will be rendered, if possible, using MathML.
2840 DocBook
2842 If the --mathml flag is used, it will be rendered using MathML
2843 in an inlineequation or informalequation tag. Otherwise it will
2844 be rendered, if possible, using Unicode characters.
2845 Docx It will be rendered using OMML math markup.
2847 FictionBook2
2849 If the --webtex option is used, formulas are rendered as images
2850 using CodeCogs or other compatible web service, downloaded and
2851 embedded in the e-book. Otherwise, they will appear verbatim.
2852 HTML, Slidy, DZSlides, S5, EPUB
2854 The way math is rendered in HTML will depend on the command-line
2855 options selected. Therefore see Math rendering in HTML above.
2856 Raw HTML
2858 Extension: raw_html
2859 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
2860 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
2861 erally). (Technically this is not an extension, since standard Mark‐
2862 down allows it, but it has been made an extension so that it can be
2863 disabled if desired.)
2864 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
2866 DZSlides, EPUB, Markdown, Emacs Org mode, and Textile output, and sup‐
2867 pressed in other formats.
2868 Extension: markdown_in_html_blocks
2870 Standard Markdown allows you to include HTML "blocks": blocks of HTML
2871 between balanced tags that are separated from the surrounding text with
2872 blank lines, and start and end at the left margin. Within these
2873 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
2874 ple), * does not signify emphasis.
2875 Pandoc behaves this way when the markdown_strict format is used; but by
2877 default, pandoc interprets material between HTML block tags as Mark‐
2878 down. Thus, for example, pandoc will turn
2879 <table>
2881 <tr>
2882 <td>*one*</td>
2883 <td>[a link](http://google.com)</td>
2884 </tr>
2885 </table>
2886 into
2888 <table>
2890 <tr>
2891 <td><em>one</em></td>
2892 <td><a href="http://google.com">a link</a></td>
2893 </tr>
2894 </table>
2895 whereas Markdown.pl will preserve it as is.
2897 There is one exception to this rule: text between <script> and <style>
2899 tags is not interpreted as Markdown.
2900 This departure from standard Markdown should make it easier to mix
2902 Markdown with HTML block elements. For example, one can surround a
2903 block of Markdown text with <div> tags without preventing it from being
2904 interpreted as Markdown.
2905 Extension: native_divs
2907 Use native pandoc Div blocks for content inside <div> tags. For the
2908 most part this should give the same output as markdown_in_html_blocks,
2909 but it makes it easier to write pandoc filters to manipulate groups of
2910 blocks.
2911 Extension: native_spans
2913 Use native pandoc Span blocks for content inside <span> tags. For the
2914 most part this should give the same output as raw_html, but it makes it
2915 easier to write pandoc filters to manipulate groups of inlines.
2916 Extension: raw_tex
2918 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
2919 be included in a document. Inline TeX commands will be preserved and
2920 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
2921 you can use LaTeX to include BibTeX citations:
2922 This result was proved in \cite{jones.1967}.
2924 Note that in LaTeX environments, like
2926 \begin{tabular}{|l|l|}\hline
2928 Age & Frequency \\ \hline
2929 18--25 & 15 \\
2930 26--35 & 33 \\
2931 36--45 & 22 \\ \hline
2932 \end{tabular}
2933 the material between the begin and end tags will be interpreted as raw
2935 LaTeX, not as Markdown.
2936 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
2938 Emacs Org mode, and ConTeXt.
2939 Generic raw attribute
2941 Extension: raw_attribute
2942 Inline spans and fenced code blocks with a special kind of attribute
2943 will be parsed as raw content with the designated format. For example,
2944 the following produces a raw groff ms block:
2945 ```{=ms}
2947 .MYMACRO
2948 blah blah
2949 ```
2950 And the following produces a raw html inline element:
2952 This is `<a>html</a>`{=html}
2954 The format name should match the target format name (see -t/--to,
2956 above, for a list, or use pandoc --list-output-formats).
2957 This extension presupposes that the relevant kind of inline code or
2959 fenced code block is enabled. Thus, for example, to use a raw
2960 attribute with a backtick code block, backtick_code_blocks must be
2961 enabled.
2962 The raw attribute cannot be combined with regular attributes.
2964 LaTeX macros
2966 Extension: latex_macros
2967 For output formats other than LaTeX, pandoc will parse LaTeX macro def‐
2968 initions and apply the resulting macros to all LaTeX math and raw
2969 LaTeX. So, for example, the following will work in all output formats,
2970 not just LaTeX:
2971 \newcommand{\tuple}[1]{\langle #1 \rangle}
2973 $\tuple{a, b, c}$
2975 Note that LaTeX macros will not be applied if they occur inside inside
2977 a raw span or block marked with the raw_attribute extension.
2978 When latex_macros is disabled, the raw LaTeX and math will not have
2980 macros applied. This is usually a better approach when you are target‐
2981 ing LaTeX or PDF.
2982 Whether or not latex_macros is enabled, the macro definitions will
2984 still be passed through as raw LaTeX.
2985 Links
2987 Markdown allows links to be specified in several ways.
2988 Automatic links
2990 If you enclose a URL or email address in pointy brackets, it will
2991 become a link:
2992 <http://google.com>
2994 <sam@green.eggs.ham>
2995 Inline links
2997 An inline link consists of the link text in square brackets, followed
2998 by the URL in parentheses. (Optionally, the URL can be followed by a
2999 link title, in quotes.)
3000 This is an [inline link](/url), and here's [one with
3002 a title](http://fsf.org "click here for a good time!").
3003 There can be no space between the bracketed part and the parenthesized
3005 part. The link text can contain formatting (such as emphasis), but the
3006 title cannot.
3007 Email addresses in inline links are not autodetected, so they have to
3009 be prefixed with mailto:
3010 [Write me!](mailto:sam@green.eggs.ham)
3012 Reference links
3014 An explicit reference link has two parts, the link itself and the link
3015 definition, which may occur elsewhere in the document (either before or
3016 after the link).
3017 The link consists of link text in square brackets, followed by a label
3019 in square brackets. (There cannot be space between the two unless the
3020 spaced_reference_links extension is enabled.) The link definition con‐
3021 sists of the bracketed label, followed by a colon and a space, followed
3022 by the URL, and optionally (after a space) a link title either in
3023 quotes or in parentheses. The label must not be parseable as a cita‐
3024 tion (assuming the citations extension is enabled): citations take
3025 precedence over link labels.
3026 Here are some examples:
3028 [my label 1]: /foo/bar.html "My title, optional"
3030 [my label 2]: /foo
3031 [my label 3]: http://fsf.org (The free software foundation)
3032 [my label 4]: /bar#special 'A title in single quotes'
3033 The URL may optionally be surrounded by angle brackets:
3035 [my label 5]: <http://foo.bar.baz>
3037 The title may go on the next line:
3039 [my label 3]: http://fsf.org
3041 "The free software foundation"
3042 Note that link labels are not case sensitive. So, this will work:
3044 Here is [my link][FOO]
3046 [Foo]: /bar/baz
3048 In an implicit reference link, the second pair of brackets is empty:
3050 See [my website][].
3052 [my website]: http://foo.bar.baz
3054 Note: In Markdown.pl and most other Markdown implementations, reference
3056 link definitions cannot occur in nested constructions such as list
3057 items or block quotes. Pandoc lifts this arbitrary seeming restric‐
3058 tion. So the following is fine in pandoc, though not in most other
3059 implementations:
3060 > My block [quote].
3062 >
3063 > [quote]: /foo
3064 Extension: shortcut_reference_links
3066 In a shortcut reference link, the second pair of brackets may be omit‐
3067 ted entirely:
3068 See [my website].
3070 [my website]: http://foo.bar.baz
3072 Internal links
3074 To link to another section of the same document, use the automatically
3075 generated identifier (see Header identifiers). For example:
3076 See the [Introduction](#introduction).
3078 or
3080 See the [Introduction].
3082 [Introduction]: #introduction
3084 Internal links are currently supported for HTML formats (including HTML
3086 slide shows and EPUB), LaTeX, and ConTeXt.
3087 Images
3089 A link immediately preceded by a ! will be treated as an image. The
3090 link text will be used as the image's alt text:
3091 
3093 ![movie reel]
3095 [movie reel]: movie.gif
3097 Extension: implicit_figures
3099 An image with nonempty alt text, occurring by itself in a paragraph,
3100 will be rendered as a figure with a caption. The image's alt text will
3101 be used as the caption.
3102 
3104 How this is rendered depends on the output format. Some output formats
3106 (e.g. RTF) do not yet support figures. In those formats, you'll just
3107 get an image in a paragraph by itself, with no caption.
3108 If you just want a regular inline image, just make sure it is not the
3110 only thing in the paragraph. One way to do this is to insert a non‐
3111 breaking space after the image:
3112 \
3114 Note that in reveal.js slide shows, an image in a paragraph by itself
3116 that has the stretch class will fill the screen, and the caption and
3117 figure tags will be omitted.
3118 Extension: link_attributes
3120 Attributes can be set on links and images:
3121 An inline {#id .class width=30 height=20px}
3123 and a reference ![image][ref] with attributes.
3124 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
3126 (This syntax is compatible with PHP Markdown Extra when only #id and
3128 .class are used.)
3129 For HTML and EPUB, all attributes except width and height (but includ‐
3131 ing srcset and sizes) are passed through as is. The other writers
3132 ignore attributes that are not supported by their output format.
3133 The width and height attributes on images are treated specially. When
3135 used without a unit, the unit is assumed to be pixels. However, any of
3136 the following unit identifiers can be used: px, cm, mm, in, inch and %.
3137 There must not be any spaces between the number and the unit. For
3138 example:
3139 { width=50% }
3141 · Dimensions are converted to inches for output in page-based formats
3143 like LaTeX. Dimensions are converted to pixels for output in
3144 HTML-like formats. Use the --dpi option to specify the number of
3145 pixels per inch. The default is 96dpi.
3146 · The % unit is generally relative to some available space. For exam‐
3148 ple the above example will render to
3149 <img href="file.jpg" style="width: 50%;" /> (HTML), \includegraph‐
3150 ics[width=0.5\textwidth]{file.jpg} (LaTeX), or \externalfig‐
3151 ure[file.jpg][width=0.5\textwidth] (ConTeXt).
3152 · Some output formats have a notion of a class (ConTeXt) or a unique
3154 identifier (LaTeX \caption), or both (HTML).
3155 · When no width or height attributes are specified, the fallback is to
3157 look at the image resolution and the dpi metadata embedded in the
3158 image file.
3159 Divs and Spans
3161 Using the native_divs and native_spans extensions (see above), HTML
3162 syntax can be used as part of markdown to create native Div and Span
3163 elements in the pandoc AST (as opposed to raw HTML). However, there is
3164 also nicer syntax available:
3165 Extension: fenced_divs
3167 Allow special fenced syntax for native Div blocks. A Div starts with a
3168 fence containing at least three consecutive colons plus some
3169 attributes. The attributes may optionally be followed by another
3170 string of consecutive colons. The attribute syntax is exactly as in
3171 fenced code blocks (see Extension: fenced_code_attributes). As with
3172 fenced code blocks, one can use either attributes in curly braces or a
3173 single unbraced word, which will be treated as a class name. The Div
3174 ends with another line containing a string of at least three consecu‐
3175 tive colons. The fenced Div should be separated by blank lines from
3176 preceding and following blocks.
3177 Example:
3179 ::::: {#special .sidebar}
3181 Here is a paragraph.
3182 And another.
3184 :::::
3185 Fenced divs can be nested. Opening fences are distinguished because
3187 they must have attributes:
3188 ::: Warning ::::::
3190 This is a warning.
3191 ::: Danger
3193 This is a warning within a warning.
3194 :::
3195 ::::::::::::::::::
3196 Fences without attributes are always closing fences. Unlike with
3198 fenced code blocks, the number of colons in the closing fence need not
3199 match the number in the opening fence. However, it can be helpful for
3200 visual clarity to use fences of different lengths to distinguish nested
3201 divs from their parents.
3202 Extension: bracketed_spans
3204 A bracketed sequence of inlines, as one would use to begin a link, will
3205 be treated as a Span with attributes if it is followed immediately by
3206 attributes:
3207 [This is *some text*]{.class key="val"}
3209 Footnotes
3211 Extension: footnotes
3212 Pandoc's Markdown allows footnotes, using the following syntax:
3213 Here is a footnote reference,[^1] and another.[^longnote]
3215 [^1]: Here is the footnote.
3217 [^longnote]: Here's one with multiple blocks.
3219 Subsequent paragraphs are indented to show that they
3221 belong to the previous footnote.
3222 { some.code }
3224 The whole paragraph can be indented, or just the first
3226 line. In this way, multi-paragraph footnotes work like
3227 multi-paragraph list items.
3228 This paragraph won't be part of the note, because it
3230 isn't indented.
3231 The identifiers in footnote references may not contain spaces, tabs, or
3233 newlines. These identifiers are used only to correlate the footnote
3234 reference with the note itself; in the output, footnotes will be num‐
3235 bered sequentially.
3236 The footnotes themselves need not be placed at the end of the document.
3238 They may appear anywhere except inside other block elements (lists,
3239 block quotes, tables, etc.). Each footnote should be separated from
3240 surrounding content (including other footnotes) by blank lines.
3241 Extension: inline_notes
3243 Inline footnotes are also allowed (though, unlike regular notes, they
3244 cannot contain multiple paragraphs). The syntax is as follows:
3245 Here is an inline note.^[Inlines notes are easier to write, since
3247 you don't have to pick an identifier and move down to type the
3248 note.]
3249 Inline and regular footnotes may be mixed freely.
3251 Citations
3253 Extension: citations
3254 Using an external filter, pandoc-citeproc, pandoc can automatically
3255 generate citations and a bibliography in a number of styles. Basic
3256 usage is
3257 pandoc --filter pandoc-citeproc myinput.txt
3259 In order to use this feature, you will need to specify a bibliography
3261 file using the bibliography metadata field in a YAML metadata section,
3262 or --bibliography command line argument. You can supply multiple
3263 --bibliography arguments or set bibliography metadata field to YAML
3264 array, if you want to use multiple bibliography files. The bibliogra‐
3265 phy may have any of these formats:
3266 Format File extension
3268 ─────────────────────────────
3269 BibLaTeX .bib
3270 BibTeX .bibtex
3271 Copac .copac
3272 CSL JSON .json
3273 CSL YAML .yaml
3274 EndNote .enl
3275 EndNote XML .xml
3276 ISI .wos
3277 MEDLINE .medline
3278 MODS .mods
3279 RIS .ris
3280 Note that .bib can be used with both BibTeX and BibLaTeX files; use
3282 .bibtex to force BibTeX.
3283 Note that pandoc-citeproc --bib2json and pandoc-citeproc --bib2yaml can
3285 produce .json and .yaml files from any of the supported formats.
3286 In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
3288 parses a subset of LaTeX markup; in CSL YAML databases, pandoc Mark‐
3289 down; and in CSL JSON databases, an HTML-like markup:
3290 <i>...</i>
3292 italics
3293 <b>...</b>
3295 bold
3296 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
3298 small capitals
3299 <sub>...</sub>
3301 subscript
3302 <sup>...</sup>
3304 superscript
3305 <span class="nocase">...</span>
3307 prevent a phrase from being capitalized as title case
3308 pandoc-citeproc -j and -y interconvert the CSL JSON and CSL YAML for‐
3310 mats as far as possible.
3311 As an alternative to specifying a bibliography file using --bibliogra‐
3313 phy or the YAML metadata field bibliography, you can include the cita‐
3314 tion data directly in the references field of the document's YAML meta‐
3315 data. The field should contain an array of YAML-encoded references,
3316 for example:
3317 ---
3319 references:
3320 - type: article-journal
3321 id: WatsonCrick1953
3322 author:
3323 - family: Watson
3324 given: J. D.
3325 - family: Crick
3326 given: F. H. C.
3327 issued:
3328 date-parts:
3329 - - 1953
3330 - 4
3331 - 25
3332 title: 'Molecular structure of nucleic acids: a structure for deoxyribose
3333 nucleic acid'
3334 title-short: Molecular structure of nucleic acids
3335 container-title: Nature
3336 volume: 171
3337 issue: 4356
3338 page: 737-738
3339 DOI: 10.1038/171737a0
3340 URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
3341 language: en-GB
3342 ...
3343 (pandoc-citeproc --bib2yaml can produce these from a bibliography file
3345 in one of the supported formats.)
3346 Citations and references can be formatted using any style supported by
3348 the Citation Style Language, listed in the Zotero Style Repository.
3349 These files are specified using the --csl option or the csl metadata
3350 field. By default, pandoc-citeproc will use the Chicago Manual of
3351 Style author-date format. The CSL project provides further information
3352 on finding and editing styles.
3353 To make your citations hyperlinks to the corresponding bibliography
3355 entries, add link-citations: true to your YAML metadata.
3356 Citations go inside square brackets and are separated by semicolons.
3358 Each citation must have a key, composed of '@' + the citation identi‐
3359 fier from the database, and may optionally have a prefix, a locator,
3360 and a suffix. The citation key must begin with a letter, digit, or _,
3361 and may contain alphanumerics, _, and internal punctuation characters
3362 (:.#$%&-+?<>~/). Here are some examples:
3363 Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
3365 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
3367 Blah blah [@smith04; @doe99].
3369 pandoc-citeproc detects locator terms in the CSL locale files. Either
3371 abbreviated or unabbreviated forms are accepted. In the en-US locale,
3372 locator terms can be written in either singular or plural forms, as
3373 book, bk./bks.; chapter, chap./chaps.; column, col./cols.; figure,
3374 fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note,
3375 n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part,
3376 pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.;
3377 volume, vol./vols.; ¶/¶¶; §/§§. If no locator term is used, "page" is
3378 assumed.
3379 A minus sign (-) before the @ will suppress mention of the author in
3381 the citation. This can be useful when the author is already mentioned
3382 in the text:
3383 Smith says blah [-@smith04].
3385 You can also write an in-text citation, as follows:
3387 @smith04 says blah.
3389 @smith04 [p. 33] says blah.
3391 If the style calls for a list of works cited, it will be placed at the
3393 end of the document. Normally, you will want to end your document with
3394 an appropriate header:
3395 last paragraph...
3397 # References
3399 The bibliography will be inserted after this header. Note that the
3401 unnumbered class will be added to this header, so that the section will
3402 not be numbered.
3403 If you want to include items in the bibliography without actually cit‐
3405 ing them in the body text, you can define a dummy nocite metadata field
3406 and put the citations there:
3407 ---
3409 nocite: |
3410 @item1, @item2
3411 ...
3412 @item3
3414 In this example, the document will contain a citation for item3 only,
3416 but the bibliography will contain entries for item1, item2, and item3.
3417 It is possible to create a bibliography with all the citations, whether
3419 or not they appear in the document, by using a wildcard:
3420 ---
3422 nocite: |
3423 @*
3424 ...
3425 For LaTeX or PDF output, you can also use natbib or biblatex to render
3427 bibliography. In order to do so, specify bibliography files as out‐
3428 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
3429 tion. Bear in mind that bibliography files have to be in respective
3430 format (either BibTeX or BibLaTeX).
3431 For more information, see the pandoc-citeproc man page.
3433 Non-pandoc extensions
3435 The following Markdown syntax extensions are not enabled by default in
3436 pandoc, but may be enabled by adding +EXTENSION to the format name,
3437 where EXTENSION is the name of the extension. Thus, for example, mark‐
3438 down+hard_line_breaks is Markdown with hard line breaks.
3439 Extension: old_dashes
3441 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: -
3442 before a numeral is an en-dash, and -- is an em-dash. This option only
3443 has an effect if smart is enabled. It is selected automatically for
3444 textile input.
3445 Extension: angle_brackets_escapable
3447 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
3448 vored Markdown but not original Markdown. This is implied by pandoc's
3449 default all_symbols_escapable.
3450 Extension: lists_without_preceding_blankline
3452 Allow a list to occur right after a paragraph, with no intervening
3453 blank space.
3454 Extension: four_space_rule
3456 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
3457 ces indent are needed for list item continuation paragraphs.
3458 Extension: spaced_reference_links
3460 Allow whitespace between the two components of a reference link, for
3461 example,
3462 [foo] [bar].
3464 Extension: hard_line_breaks
3466 Causes all newlines within a paragraph to be interpreted as hard line
3467 breaks instead of spaces.
3468 Extension: ignore_line_breaks
3470 Causes newlines within a paragraph to be ignored, rather than being
3471 treated as spaces or as hard line breaks. This option is intended for
3472 use with East Asian languages where spaces are not used between words,
3473 but text is divided into lines for readability.
3474 Extension: east_asian_line_breaks
3476 Causes newlines within a paragraph to be ignored, rather than being
3477 treated as spaces or as hard line breaks, when they occur between two
3478 East Asian wide characters. This is a better choice than
3479 ignore_line_breaks for texts that include a mix of East Asian wide
3480 characters and other characters.
3481 Extension: emoji
3483 Parses textual emojis like :smile: as Unicode emoticons.
3484 Extension: tex_math_single_backslash
3486 Causes anything between \( and \) to be interpreted as inline TeX math,
3487 and anything between \[ and \] to be interpreted as display TeX math.
3488 Note: a drawback of this extension is that it precludes escaping ( and
3489 [.
3490 Extension: tex_math_double_backslash
3492 Causes anything between \\( and \\) to be interpreted as inline TeX
3493 math, and anything between \\[ and \\] to be interpreted as display TeX
3494 math.
3495 Extension: markdown_attribute
3497 By default, pandoc interprets material inside block-level tags as Mark‐
3498 down. This extension changes the behavior so that Markdown is only
3499 parsed inside block-level tags if the tags have the attribute mark‐
3500 down=1.
3501 Extension: mmd_title_block
3503 Enables a MultiMarkdown style title block at the top of the document,
3504 for example:
3505 Title: My title
3507 Author: John Doe
3508 Date: September 1, 2008
3509 Comment: This is a sample mmd title block, with
3510 a field spanning multiple lines.
3511 See the MultiMarkdown documentation for details. If pandoc_title_block
3513 or yaml_metadata_block is enabled, it will take precedence over
3514 mmd_title_block.
3515 Extension: abbreviations
3517 Parses PHP Markdown Extra abbreviation keys, like
3518 *[HTML]: Hypertext Markup Language
3520 Note that the pandoc document model does not support abbreviations, so
3522 if this extension is enabled, abbreviation keys are simply skipped (as
3523 opposed to being parsed as paragraphs).
3524 Extension: autolink_bare_uris
3526 Makes all absolute URIs into links, even when not surrounded by pointy
3527 braces <...>.
3528 Extension: mmd_link_attributes
3530 Parses multimarkdown style key-value attributes on link and image ref‐
3531 erences. This extension should not be confused with the
3532 link_attributes extension.
3533 This is a reference ![image][ref] with multimarkdown attributes.
3535 [ref]: http://path.to/image "Image title" width=20px height=30px
3537 id=myId class="myClass1 myClass2"
3538 Extension: mmd_header_identifiers
3540 Parses multimarkdown style header identifiers (in square brackets,
3541 after the header but before any trailing #s in an ATX header).
3542 Extension: compact_definition_lists
3544 Activates the definition list syntax of pandoc 1.12.x and earlier.
3545 This syntax differs from the one described above under Definition lists
3546 in several respects:
3547 · No blank line is required between consecutive items of the definition
3549 list.
3550 · To get a "tight" or "compact" list, omit space between consecutive
3552 items; the space between a term and its definition does not affect
3553 anything.
3554 · Lazy wrapping of paragraphs is not allowed: the entire definition
3556 must be indented four spaces.
3557 Markdown variants
3559 In addition to pandoc's extended Markdown, the following Markdown vari‐
3560 ants are supported:
3561 markdown_phpextra (PHP Markdown Extra)
3563 footnotes, pipe_tables, raw_html, markdown_attribute,
3564 fenced_code_blocks, definition_lists, intraword_underscores,
3565 header_attributes, link_attributes, abbreviations, shortcut_ref‐
3566 erence_links, spaced_reference_links.
3567 markdown_github (deprecated GitHub-Flavored Markdown)
3569 pipe_tables, raw_html, fenced_code_blocks, gfm_auto_identifiers,
3570 ascii_identifiers, backtick_code_blocks, autolink_bare_uris,
3571 space_in_atx_header, intraword_underscores, strikeout, emoji,
3572 shortcut_reference_links, angle_brackets_escapable, lists_with‐
3573 out_preceding_blankline.
3574 markdown_mmd (MultiMarkdown)
3576 pipe_tables, raw_html, markdown_attribute, mmd_link_attributes,
3577 tex_math_double_backslash, intraword_underscores,
3578 mmd_title_block, footnotes, definition_lists, all_sym‐
3579 bols_escapable, implicit_header_references, auto_identifiers,
3580 mmd_header_identifiers, shortcut_reference_links, implicit_fig‐
3581 ures, superscript, subscript, backtick_code_blocks, spaced_ref‐
3582 erence_links, raw_attribute.
3583 markdown_strict (Markdown.pl)
3585 raw_html, shortcut_reference_links, spaced_reference_links.
3586 We also support commonmark and gfm (GitHub-Flavored Markdown, which is
3588 implemented as a set of extensions on commonmark).
3589 Note, however, that commonmark and gfm have limited support for exten‐
3591 sions. Only those listed below (and smart and raw_tex) will work. The
3592 extensions can, however, all be individually disabled. Also, raw_tex
3593 only affects gfm output, not input.
3594 gfm (GitHub-Flavored Markdown)
3596 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
3597 ascii_identifiers, backtick_code_blocks, autolink_bare_uris,
3598 intraword_underscores, strikeout, hard_line_breaks, emoji,
3599 shortcut_reference_links, angle_brackets_escapable.
3600
3602 You can use pandoc to produce an HTML + JavaScript slide presentation
3603 that can be viewed via a web browser. There are five ways to do this,
3604 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
3605 duce a PDF slide show using LaTeX beamer, or slides shows in Microsoft
3606 PowerPoint format.
3607 Here's the Markdown source for a simple slide show, habits.txt:
3609 % Habits
3611 % John Doe
3612 % March 22, 2005
3613 # In the morning
3615 ## Getting up
3617 - Turn off alarm
3619 - Get out of bed
3620 ## Breakfast
3622 - Eat eggs
3624 - Drink coffee
3625 # In the evening
3627 ## Dinner
3629 - Eat spaghetti
3631 - Drink wine
3632 ------------------
3634 
3636 ## Going to sleep
3638 - Get in bed
3640 - Count sheep
3641 To produce an HTML/JavaScript slide show, simply type
3643 pandoc -t FORMAT -s habits.txt -o habits.html
3645 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
3647 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
3649 with the -s/--standalone option embeds a link to JavaScript and CSS
3650 files, which are assumed to be available at the relative path
3651 s5/default (for S5), slideous (for Slideous), reveal.js (for
3652 reveal.js), or at the Slidy website at w3.org (for Slidy). (These
3653 paths can be changed by setting the slidy-url, slideous-url,
3654 revealjs-url, or s5-url variables; see Variables for slides, above.)
3655 For DZSlides, the (relatively short) JavaScript and CSS are included in
3656 the file by default.
3657 With all HTML slide formats, the --self-contained option can be used to
3659 produce a single file that contains all of the data necessary to dis‐
3660 play the slide show, including linked scripts, stylesheets, images, and
3661 videos.
3662 To produce a PDF slide show using beamer, type
3664 pandoc -t beamer habits.txt -o habits.pdf
3666 Note that a reveal.js slide show can also be converted to a PDF by
3668 printing it to a file from the browser.
3669 To produce a Powerpoint slide show, type
3671 pandoc habits.txt -o habits.pptx
3673 Structuring the slide show
3675 By default, the slide level is the highest header level in the hierar‐
3676 chy that is followed immediately by content, and not another header,
3677 somewhere in the document. In the example above, level 1 headers are
3678 always followed by level 2 headers, which are followed by content, so 2
3679 is the slide level. This default can be overridden using the
3680 --slide-level option.
3681 The document is carved up into slides according to the following rules:
3683 · A horizontal rule always starts a new slide.
3685 · A header at the slide level always starts a new slide.
3687 · Headers below the slide level in the hierarchy create headers within
3689 a slide.
3690 · Headers above the slide level in the hierarchy create "title slides,"
3692 which just contain the section title and help to break the slide show
3693 into sections.
3694 · Content above the slide level will not appear in the slide show.
3696 · A title page is constructed automatically from the document's title
3698 block, if present. (In the case of beamer, this can be disabled by
3699 commenting out some lines in the default template.)
3700 These rules are designed to support many different styles of slide
3702 show. If you don't care about structuring your slides into sections
3703 and subsections, you can just use level 1 headers for all each slide.
3704 (In that case, level 1 will be the slide level.) But you can also
3705 structure the slide show into sections, as in the example above.
3706 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
3708 layout will be produced, with level 1 headers building horizontally and
3709 level 2 headers building vertically. It is not recommended that you
3710 use deeper nesting of section levels with reveal.js.
3711 Incremental lists
3713 By default, these writers produce lists that display "all at once." If
3714 you want your lists to display incrementally (one item at a time), use
3715 the -i option. If you want a particular list to depart from the
3716 default, put it in a div block with class incremental or nonincremen‐
3717 tal. So, for example, using the fenced div syntax, the following would
3718 be incremental regardless of the document default:
3719 ::: incremental
3721 - Eat spaghetti
3723 - Drink wine
3724 :::
3726 or
3728 ::: nonincremental
3730 - Eat spaghetti
3732 - Drink wine
3733 :::
3735 While using incremental and nonincremental divs are the recommended
3737 method of setting incremental lists on a per-case basis, an older
3738 method is also supported: putting lists inside a blockquote will depart
3739 from the document default (that is, it will display incrementally with‐
3740 out the -i option and all at once with the -i option):
3741 > - Eat spaghetti
3743 > - Drink wine
3744 Both methods allow incremental and nonincremental lists to be mixed in
3746 a single document.
3747 Inserting pauses
3749 You can add "pauses" within a slide by including a paragraph containing
3750 three dots, separated by spaces:
3751 # Slide with a pause
3753 content before the pause
3755 . . .
3757 content after the pause
3759 Styling the slides
3761 You can change the style of HTML slides by putting customized CSS files
3762 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
3763 $DATADIR/slideous (for Slideous), where $DATADIR is the user data
3764 directory (see --data-dir, above). The originals may be found in pan‐
3765 doc's system data directory (generally $CABALDIR/pandoc-VER‐
3766 SION/s5/default). Pandoc will look there for any files it does not
3767 find in the user data directory.
3768 For dzslides, the CSS is included in the HTML file itself, and may be
3770 modified there.
3771 All reveal.js configuration options can be set through variables. For
3773 example, themes can be used by setting the theme variable:
3774 -V theme=moon
3776 Or you can specify a custom stylesheet using the --css option.
3778 To style beamer slides, you can specify a theme, colortheme, fonttheme,
3780 innertheme, and outertheme, using the -V option:
3781 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
3783 Note that header attributes will turn into slide attributes (on a <div>
3785 or <section>) in HTML slide formats, allowing you to style individual
3786 slides. In beamer, the only header attribute that affects slides is
3787 the allowframebreaks class, which sets the allowframebreaks option,
3788 causing multiple slides to be created if the content overfills the
3789 frame. This is recommended especially for bibliographies:
3790 # References {.allowframebreaks}
3792 Speaker notes
3794 Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
3795 You can add notes to your Markdown document thus:
3796 ::: notes
3798 This is my note.
3800 - It can contain Markdown
3802 - like this list
3803 :::
3805 To show the notes window in reveal.js, press s while viewing the pre‐
3807 sentation. Speaker notes in PowerPoint will be available, as usual, in
3808 handouts and presenter view.
3809 Notes are not yet supported for other slide formats, but the notes will
3811 not appear on the slides themselves.
3812 Columns
3814 To put material in side by side columns, you can use a native div con‐
3815 tainer with class columns, containing two or more div containers with
3816 class column and a width attribute:
3817 :::::::::::::: {.columns}
3819 ::: {.column width="40%"}
3820 contents...
3821 :::
3822 ::: {.column width="60%"}
3823 contents...
3824 :::
3825 ::::::::::::::
3826 Frame attributes in beamer
3828 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
3829 in beamer (for example, when using the minted environment). This can
3830 be forced by adding the fragile class to the header introducing the
3831 slide:
3832 # Fragile slide {.fragile}
3834 All of the other frame attributes described in Section 8.1 of the
3836 Beamer User's Guide may also be used: allowdisplaybreaks, allowframe‐
3837 breaks, b, c, t, environment, label, plain, shrink.
3838
3840 EPUB Metadata
3841 EPUB metadata may be specified using the --epub-metadata option, but if
3842 the source document is Markdown, it is better to use a YAML metadata
3843 block. Here is an example:
3844 ---
3846 title:
3847 - type: main
3848 text: My Book
3849 - type: subtitle
3850 text: An investigation of metadata
3851 creator:
3852 - role: author
3853 text: John Smith
3854 - role: editor
3855 text: Sarah Jones
3856 identifier:
3857 - scheme: DOI
3858 text: doi:10.234234.234/33
3859 publisher: My Press
3860 rights: © 2007 John Smith, CC BY-NC
3861 ibooks:
3862 version: 1.3.4
3863 ...
3864 The following fields are recognized:
3866 identifier
3868 Either a string value or an object with fields text and scheme.
3869 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
3870 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
3871 ISMN-13, ISBN-A, JP, OLCC.
3872 title Either a string value, or an object with fields file-as and
3874 type, or a list of such objects. Valid values for type are
3875 main, subtitle, short, collection, edition, extended.
3876 creator
3878 Either a string value, or an object with fields role, file-as,
3879 and text, or a list of such objects. Valid values for role are
3880 MARC relators, but pandoc will attempt to translate the
3881 human-readable versions (like "author" and "editor") to the
3882 appropriate marc relators.
3883 contributor
3885 Same format as creator.
3886 date A string value in YYYY-MM-DD format. (Only the year is neces‐
3888 sary.) Pandoc will attempt to convert other common date formats.
3889 lang (or legacy: language)
3891 A string value in BCP 47 format. Pandoc will default to the
3892 local language if nothing is specified.
3893 subject
3895 A string value or a list of such values.
3896 description
3898 A string value.
3899 type A string value.
3901 format A string value.
3903 relation
3905 A string value.
3906 coverage
3908 A string value.
3909 rights A string value.
3911 cover-image
3913 A string value (path to cover image).
3914 stylesheet
3916 A string value (path to CSS stylesheet).
3917 page-progression-direction
3919 Either ltr or rtl. Specifies the page-progression-direction
3920 attribute for the spine element.
3921 ibooks iBooks-specific metadata, with the following fields:
3923 · version: (string)
3925 · specified-fonts: true|false (default false)
3927 · ipad-orientation-lock: portrait-only|landscape-only
3929 · iphone-orientation-lock: portrait-only|landscape-only
3931 · binding: true|false (default true)
3933 · scroll-axis: vertical|horizontal|default
3935 Linked media
3937 By default, pandoc will download linked media (including audio and
3938 video) and include it in the EPUB container, yielding a completely
3939 self-contained EPUB. If you want to link to external media resources
3940 instead, use raw HTML in your source and add data-external="1" to the
3941 tag with the src attribute. For example:
3942 <audio controls="1">
3944 <source src="http://example.com/music/toccata.mp3"
3945 data-external="1" type="audio/mpeg">
3946 </source>
3947 </audio>
3948
3950 Pandoc will automatically highlight syntax in fenced code blocks that
3951 are marked with a language name. The Haskell library skylighting is
3952 used for highlighting, which works in HTML, Docx, Ms, and LaTeX/PDF
3953 output. To see a list of language names that pandoc will recognize,
3954 type pandoc --list-highlight-languages.
3955 The color scheme can be selected using the --highlight-style option.
3957 The default color scheme is pygments, which imitates the default color
3958 scheme used by the Python library pygments (though pygments is not
3959 actually used to do the highlighting). To see a list of highlight
3960 styles, type pandoc --list-highlight-styles.
3961 To disable highlighting, use the --no-highlight option.
3963
3965 Input
3966 The docx reader, by default, only reads those styles that it can con‐
3967 vert into pandoc elements, either by direct conversion or interpreting
3968 the derivation of the input document's styles.
3969 By enabling the styles extension in the docx reader (-f docx+styles),
3971 you can produce output that maintains the styles of the input document,
3972 using the custom-style class. Paragraph styles are interpreted as
3973 divs, while character styles are interpreted as spans.
3974 For example, using the custom-style-reference.docx file in the test
3976 directory, we have the following different outputs:
3977 Without the +styles extension:
3979 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
3981 This is some text.
3982 This is text with an *emphasized* text style. And this is text with a
3984 **strengthened** text style.
3985 > Here is a styled paragraph that inherits from Block Text.
3987 And with the extension:
3989 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
3991 ::: {custom-style="FirstParagraph"}
3993 This is some text.
3994 :::
3995 ::: {custom-style="BodyText"}
3997 This is text with an [emphasized]{custom-style="Emphatic"} text style.
3998 And this is text with a [strengthened]{custom-style="Strengthened"}
3999 text style.
4000 :::
4001 ::: {custom-style="MyBlockStyle"}
4003 > Here is a styled paragraph that inherits from Block Text.
4004 :::
4005 With these custom styles, you can use your input document as a refer‐
4007 ence-doc while creating docx output (see below), and maintain the same
4008 styles in your input and output files.
4009 Output
4011 By default, pandoc's docx output applies a predefined set of styles for
4012 blocks such as paragraphs and block quotes, and uses largely default
4013 formatting (italics, bold) for inlines. This will work for most pur‐
4014 poses, especially alongside a reference.docx file. However, if you
4015 need to apply your own styles to blocks, or match a preexisting set of
4016 styles, pandoc allows you to define custom styles for blocks and text
4017 using divs and spans, respectively.
4018 If you define a div or span with the attribute custom-style, pandoc
4020 will apply your specified style to the contained elements. So, for
4021 example using the bracketed_spans syntax,
4022 [Get out]{custom-style="Emphatically"}, he said.
4024 would produce a docx file with "Get out" styled with character style
4026 Emphatically. Similarly, using the fenced_divs syntax,
4027 Dickinson starts the poem simply:
4029 ::: {custom-style="Poetry"}
4031 | A Bird came down the Walk---
4032 | He did not know I saw---
4033 :::
4034 would style the two contained lines with the Poetry paragraph style.
4036 If the styles are not yet in your reference.docx, they will be defined
4038 in the output file as inheriting from normal text. If they are already
4039 defined, pandoc will not alter the definition.
4040 This feature allows for greatest customization in conjunction with pan‐
4042 doc filters. If you want all paragraphs after block quotes to be
4043 indented, you can write a filter to apply the styles necessary. If you
4044 want all italics to be transformed to the Emphasis character style
4045 (perhaps to change their color), you can write a filter which will
4046 transform all italicized inlines to inlines within an Emphasis cus‐
4047 tom-style span.
4048
4050 Pandoc can be extended with custom writers written in lua. (Pandoc
4051 includes a lua interpreter, so lua need not be installed separately.)
4052 To use a custom writer, simply specify the path to the lua script in
4054 place of the output format. For example:
4055 pandoc -t data/sample.lua
4057 Creating a custom writer requires writing a lua function for each pos‐
4059 sible element in a pandoc document. To get a documented example which
4060 you can modify according to your needs, do
4061 pandoc --print-default-data-file sample.lua
4063
4065 Copyright 2006-2017 John MacFarlane (jgm@berkeley.edu). Released under
4066 the GPL, version 2 or greater. This software carries no warranty of
4067 any kind. (See COPYRIGHT for full copyright and warranty notices.) For
4068 a full list of contributors, see the file AUTHORS.md in the pandoc
4069 source code.
4070 The Pandoc source code and all documentation may be downloaded from
4072 <http://pandoc.org>.
4073pandoc 2.1.2 March 2, 2018 PANDOC(1)