1PANDOC(1) General Commands Manual PANDOC(1)
2
6 pandoc - general markup converter
7
9 pandoc [options] [input-file]...
10
12 Pandoc is a Haskell library for converting from one markup format to
13 another, and a command-line tool that uses this library.
14 Pandoc can convert between numerous markup and word processing formats,
16 including, but not limited to, various flavors of Markdown, HTML, LaTeX
17 and Word docx. For the full lists of input and output formats, see the
18 --from and --to options below. Pandoc can also produce PDF output: see
19 creating a PDF, below.
20 Pandoc's enhanced version of Markdown includes syntax for tables, defi‐
22 nition lists, metadata blocks, footnotes, citations, math, and much
23 more. See below under Pandoc's Markdown.
24 Pandoc has a modular design: it consists of a set of readers, which
26 parse text in a given format and produce a native representation of the
27 document (an abstract syntax tree or AST), and a set of writers, which
28 convert this native representation into a target format. Thus, adding
29 an input or output format requires only adding a reader or writer.
30 Users can also run custom pandoc filters to modify the intermediate
31 AST.
32 Because pandoc's intermediate representation of a document is less
34 expressive than many of the formats it converts between, one should not
35 expect perfect conversions between every format and every other. Pan‐
36 doc attempts to preserve the structural elements of a document, but not
37 formatting details such as margin size. And some document elements,
38 such as complex tables, may not fit into pandoc's simple document
39 model. While conversions from pandoc's Markdown to all formats aspire
40 to be perfect, conversions from formats more expressive than pandoc's
41 Markdown can be expected to be lossy.
42 Using pandoc
44 If no input-files are specified, input is read from stdin. Output goes
45 to stdout by default. For output to a file, use the -o option:
46 pandoc -o output.html input.txt
48 By default, pandoc produces a document fragment. To produce a stand‐
50 alone document (e.g. a valid HTML file including <head> and <body>),
51 use the -s or --standalone flag:
52 pandoc -s -o output.html input.txt
54 For more information on how standalone documents are produced, see Tem‐
56 plates below.
57 If multiple input files are given, pandoc will concatenate them all
59 (with blank lines between them) before parsing. (Use --file-scope to
60 parse files individually.)
61 Specifying formats
63 The format of the input and output can be specified explicitly using
64 command-line options. The input format can be specified using the
65 -f/--from option, the output format using the -t/--to option. Thus, to
66 convert hello.txt from Markdown to LaTeX, you could type:
67 pandoc -f markdown -t latex hello.txt
69 To convert hello.html from HTML to Markdown:
71 pandoc -f html -t markdown hello.html
73 Supported input and output formats are listed below under Options (see
75 -f for input formats and -t for output formats). You can also use pan‐
76 doc --list-input-formats and pandoc --list-output-formats to print
77 lists of supported formats.
78 If the input or output format is not specified explicitly, pandoc will
80 attempt to guess it from the extensions of the filenames. Thus, for
81 example,
82 pandoc -o hello.tex hello.txt
84 will convert hello.txt from Markdown to LaTeX. If no output file is
86 specified (so that output goes to stdout), or if the output file's
87 extension is unknown, the output format will default to HTML. If no
88 input file is specified (so that input comes from stdin), or if the
89 input files' extensions are unknown, the input format will be assumed
90 to be Markdown.
91 Character encoding
93 Pandoc uses the UTF-8 character encoding for both input and output. If
94 your local character encoding is not UTF-8, you should pipe input and
95 output through iconv:
96 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
98 Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
100 OPML, DocBook, and Texinfo), information about the character encoding
101 is included in the document header, which will only be included if you
102 use the -s/--standalone option.
103 Creating a PDF
105 To produce a PDF, specify an output file with a .pdf extension:
106 pandoc test.txt -o test.pdf
108 By default, pandoc will use LaTeX to create the PDF, which requires
110 that a LaTeX engine be installed (see --pdf-engine below).
111 Alternatively, pandoc can use ConTeXt, pdfroff, or any of the following
113 HTML/CSS-to-PDF-engines, to create a PDF: wkhtmltopdf, weasyprint or
114 prince. To do this, specify an output file with a .pdf extension, as
115 before, but add the --pdf-engine option or -t context, -t html, or -t
116 ms to the command line (-t html defaults to --pdf-engine=wkhtmltopdf).
117 PDF output uses variables for LaTeX (with a LaTeX engine); variables
119 for ConTeXt (with ConTeXt); or variables for wkhtmltopdf (an HTML/CSS-
120 to-PDF engine; --css also affects the output).
121 To debug the PDF creation, it can be useful to look at the intermediate
123 representation: instead of -o test.pdf, use for example -s -o test.tex
124 to output the generated LaTeX. You can then test it with pdflatex
125 test.tex.
126 When using LaTeX, the following packages need to be available (they are
128 included with all recent versions of TeX Live): amsfonts, amsmath, lm,
129 unicode-math, ifxetex, ifluatex, listings (if the --listings option is
130 used), fancyvrb, longtable, booktabs, graphicx and grffile (if the doc‐
131 ument contains images), hyperref, xcolor, ulem, geometry (with the
132 geometry variable set), setspace (with linestretch), and babel (with
133 lang). The use of xelatex or lualatex as the PDF engine requires
134 fontspec. xelatex uses polyglossia (with lang), xecjk, and bidi (with
135 the dir variable set). If the mathspec variable is set, xelatex will
136 use mathspec instead of unicode-math. The upquote and microtype pack‐
137 ages are used if available, and csquotes will be used for typography if
138 \usepackage{csquotes} is present in the template or included via
139 /H/--include-in-header. The natbib, biblatex, bibtex, and biber pack‐
140 ages can optionally be used for citation rendering. The following
141 packages will be used to improve output quality if present, but pandoc
142 does not require them to be present: upquote (for straight quotes in
143 verbatim environments), microtype (for better spacing adjustments),
144 parskip (for better inter-paragraph spaces), xurl (for better line
145 breaks in URLs), bookmark (for better PDF bookmarks), and footnotehyper
146 or footnote (to allow footnotes in tables).
147 Reading from the Web
149 Instead of an input file, an absolute URI may be given. In this case
150 pandoc will fetch the content using HTTP:
151 pandoc -f html -t markdown http://www.fsf.org
153 It is possible to supply a custom User-Agent string or other header
155 when requesting a document from a URL:
156 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
158 http://www.fsf.org
159
161 General options
162 -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
163 Specify input format. FORMAT can be:
164 · commonmark (CommonMark Markdown)
166 · creole (Creole 1.0)
168 · docbook (DocBook)
170 · docx (Word docx)
172 · dokuwiki (DokuWiki markup)
174 · epub (EPUB)
176 · fb2 (FictionBook2 e-book)
178 · gfm (GitHub-Flavored Markdown), or the deprecated and less
180 accurate markdown_github; use markdown_github only if you need
181 extensions not supported in gfm.
182 · haddock (Haddock markup)
184 · html (HTML)
186 · ipynb (Jupyter notebook)
188 · jats (JATS XML)
190 · json (JSON version of native AST)
192 · latex (LaTeX)
194 · markdown (Pandoc's Markdown)
196 · markdown_mmd (MultiMarkdown)
198 · markdown_phpextra (PHP Markdown Extra)
200 · markdown_strict (original unextended Markdown)
202 · mediawiki (MediaWiki markup)
204 · man (roff man)
206 · muse (Muse)
208 · native (native Haskell)
210 · odt (ODT)
212 · opml (OPML)
214 · org (Emacs Org mode)
216 · rst (reStructuredText)
218 · t2t (txt2tags)
220 · textile (Textile)
222 · tikiwiki (TikiWiki markup)
224 · twiki (TWiki markup)
226 · vimwiki (Vimwiki)
228 Extensions can be individually enabled or disabled by appending
230 +EXTENSION or -EXTENSION to the format name. See Extensions
231 below, for a list of extensions and their names. See --list-
232 input-formats and --list-extensions, below.
233 -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
235 Specify output format. FORMAT can be:
236 · asciidoc (AsciiDoc) or asciidoctor (AsciiDoctor)
238 · beamer (LaTeX beamer slide show)
240 · commonmark (CommonMark Markdown)
242 · context (ConTeXt)
244 · docbook or docbook4 (DocBook 4)
246 · docbook5 (DocBook 5)
248 · docx (Word docx)
250 · dokuwiki (DokuWiki markup)
252 · epub or epub3 (EPUB v3 book)
254 · epub2 (EPUB v2)
256 · fb2 (FictionBook2 e-book)
258 · gfm (GitHub-Flavored Markdown), or the deprecated and less
260 accurate markdown_github; use markdown_github only if you need
261 extensions not supported in gfm.
262 · haddock (Haddock markup)
264 · html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
266 · html4 (XHTML 1.0 Transitional)
268 · icml (InDesign ICML)
270 · ipynb (Jupyter notebook)
272 · jats (JATS XML)
274 · jira (Jira wiki markup)
276 · json (JSON version of native AST)
278 · latex (LaTeX)
280 · man (roff man)
282 · markdown (Pandoc's Markdown)
284 · markdown_mmd (MultiMarkdown)
286 · markdown_phpextra (PHP Markdown Extra)
288 · markdown_strict (original unextended Markdown)
290 · mediawiki (MediaWiki markup)
292 · ms (roff ms)
294 · muse (Muse),
296 · native (native Haskell),
298 · odt (OpenOffice text document)
300 · opml (OPML)
302 · opendocument (OpenDocument)
304 · org (Emacs Org mode)
306 · plain (plain text),
308 · pptx (PowerPoint slide show)
310 · rst (reStructuredText)
312 · rtf (Rich Text Format)
314 · texinfo (GNU Texinfo)
316 · textile (Textile)
318 · slideous (Slideous HTML and JavaScript slide show)
320 · slidy (Slidy HTML and JavaScript slide show)
322 · dzslides (DZSlides HTML5 + JavaScript slide show),
324 · revealjs (reveal.js HTML5 + JavaScript slide show)
326 · s5 (S5 HTML and JavaScript slide show)
328 · tei (TEI Simple)
330 · xwiki (XWiki markup)
332 · zimwiki (ZimWiki markup)
334 · the path of a custom lua writer, see Custom writers below
336 Note that odt, docx, and epub output will not be directed to
338 stdout unless forced with -o -.
339 Extensions can be individually enabled or disabled by appending
341 +EXTENSION or -EXTENSION to the format name. See Extensions
342 below, for a list of extensions and their names. See --list-
343 output-formats and --list-extensions, below.
344 -o FILE, --output=FILE
346 Write output to FILE instead of stdout. If FILE is -, output
347 will go to stdout, even if a non-textual format (docx, odt,
348 epub2, epub3) is specified.
349 --data-dir=DIRECTORY
351 Specify the user data directory to search for pandoc data files.
352 If this option is not specified, the default user data directory
353 will be used. On *nix and macOS systems this will be the pandoc
354 subdirectory of the XDG data directory (by default,
355 $HOME/.local/share, overridable by setting the XDG_DATA_HOME
356 environment variable). If that directory does not exist,
357 $HOME/.pandoc will be used (for backwards compatibility). In
358 Windows the default user data directory is C:\Users\USER‐
359 NAME\AppData\Roaming\pandoc. You can find the default user data
360 directory on your system by looking at the output of pandoc
361 --version. A reference.odt, reference.docx, epub.css, tem‐
362 plates, slidy, slideous, or s5 directory placed in this direc‐
363 tory will override pandoc's normal defaults.
364 --bash-completion
366 Generate a bash completion script. To enable bash completion
367 with pandoc, add this to your .bashrc:
368 eval "$(pandoc --bash-completion)"
370 --verbose
372 Give verbose debugging output. Currently this only has an
373 effect with PDF output.
374 --quiet
376 Suppress warning messages.
377 --fail-if-warnings
379 Exit with error status if there are any warnings.
380 --log=FILE
382 Write log messages in machine-readable JSON format to FILE. All
383 messages above DEBUG level will be written, regardless of ver‐
384 bosity settings (--verbose, --quiet).
385 --list-input-formats
387 List supported input formats, one per line.
388 --list-output-formats
390 List supported output formats, one per line.
391 --list-extensions[=FORMAT]
393 List supported extensions, one per line, preceded by a + or -
394 indicating whether it is enabled by default in FORMAT. If FOR‐
395 MAT is not specified, defaults for pandoc's Markdown are given.
396 --list-highlight-languages
398 List supported languages for syntax highlighting, one per line.
399 --list-highlight-styles
401 List supported styles for syntax highlighting, one per line.
402 See --highlight-style.
403 -v, --version
405 Print version.
406 -h, --help
408 Show usage message.
409 Reader options
411 --base-header-level=NUMBER
412 Specify the base level for headings (defaults to 1).
413 --strip-empty-paragraphs
415 Deprecated. Use the +empty_paragraphs extension instead. Ignore
416 paragraphs with no content. This option is useful for convert‐
417 ing word processing documents where users have used empty para‐
418 graphs to create inter-paragraph space.
419 --indented-code-classes=CLASSES
421 Specify classes to use for indented code blocks--for example,
422 perl,numberLines or haskell. Multiple classes may be separated
423 by spaces or commas.
424 --default-image-extension=EXTENSION
426 Specify a default extension to use when image paths/URLs have no
427 extension. This allows you to use the same source for formats
428 that require different kinds of images. Currently this option
429 only affects the Markdown and LaTeX readers.
430 --file-scope
432 Parse each file individually before combining for multifile doc‐
433 uments. This will allow footnotes in different files with the
434 same identifiers to work as expected. If this option is set,
435 footnotes and links will not work across files. Reading binary
436 files (docx, odt, epub) implies --file-scope.
437 -F PROGRAM, --filter=PROGRAM
439 Specify an executable to be used as a filter transforming the
440 pandoc AST after the input is parsed and before the output is
441 written. The executable should read JSON from stdin and write
442 JSON to stdout. The JSON must be formatted like pandoc's own
443 JSON input and output. The name of the output format will be
444 passed to the filter as the first argument. Hence,
445 pandoc --filter ./caps.py -t latex
447 is equivalent to
449 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
451 The latter form may be useful for debugging filters.
453 Filters may be written in any language. Text.Pandoc.JSON
455 exports toJSONFilter to facilitate writing filters in Haskell.
456 Those who would prefer to write filters in python can use the
457 module pandocfilters, installable from PyPI. There are also
458 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
459 In order of preference, pandoc will look for filters in
461 1. a specified full or relative path (executable or non-exe‐
463 cutable)
464 2. $DATADIR/filters (executable or non-executable) where
466 $DATADIR is the user data directory (see --data-dir, above).
467 3. $PATH (executable only)
469 Filters and lua-filters are applied in the order specified on
471 the command line.
472 --lua-filter=SCRIPT
474 Transform the document in a similar fashion as JSON filters (see
475 --filter), but use pandoc's build-in lua filtering system. The
476 given lua script is expected to return a list of lua filters
477 which will be applied in order. Each lua filter must contain
478 element-transforming functions indexed by the name of the AST
479 element on which the filter function should be applied.
480 The pandoc lua module provides helper functions for element cre‐
482 ation. It is always loaded into the script's lua environment.
483 The following is an example lua script for macro-expansion:
485 function expand_hello_world(inline)
487 if inline.c == '{{helloworld}}' then
488 return pandoc.Emph{ pandoc.Str "Hello, World" }
489 else
490 return inline
491 end
492 end
493 return {{Str = expand_hello_world}}
495 In order of preference, pandoc will look for lua filters in
497 1. a specified full or relative path (executable or non-exe‐
499 cutable)
500 2. $DATADIR/filters (executable or non-executable) where
502 $DATADIR is the user data directory (see --data-dir, above).
503 -M KEY[=VAL], --metadata=KEY[:VAL]
505 Set the metadata field KEY to the value VAL. A value specified
506 on the command line overrides a value specified in the document
507 using YAML metadata blocks. Values will be parsed as YAML bool‐
508 ean or string values. If no value is specified, the value will
509 be treated as Boolean true. Like --variable, --metadata causes
510 template variables to be set. But unlike --variable, --metadata
511 affects the metadata of the underlying document (which is acces‐
512 sible from filters and may be printed in some output formats)
513 and metadata values will be escaped when inserted into the tem‐
514 plate.
515 --metadata-file=FILE
517 Read metadata from the supplied YAML (or JSON) file. This
518 option can be used with every input format, but string scalars
519 in the YAML file will always be parsed as Markdown. Generally,
520 the input will be handled the same as in YAML metadata blocks.
521 Metadata values specified inside the document, or by using -M,
522 overwrite values specified with this option.
523 -p, --preserve-tabs
525 Preserve tabs instead of converting them to spaces (the
526 default). Note that this will only affect tabs in literal code
527 spans and code blocks; tabs in regular text will be treated as
528 spaces.
529 --tab-stop=NUMBER
531 Specify the number of spaces per tab (default is 4).
532 --track-changes=accept|reject|all
534 Specifies what to do with insertions, deletions, and comments
535 produced by the MS Word "Track Changes" feature. accept (the
536 default), inserts all insertions, and ignores all deletions.
537 reject inserts all deletions and ignores insertions. Both
538 accept and reject ignore comments. all puts in insertions,
539 deletions, and comments, wrapped in spans with insertion, dele‐
540 tion, comment-start, and comment-end classes, respectively. The
541 author and time of change is included. all is useful for
542 scripting: only accepting changes from a certain reviewer, say,
543 or before a certain date. If a paragraph is inserted or
544 deleted, track-changes=all produces a span with the class para‐
545 graph-insertion/paragraph-deletion before the affected paragraph
546 break. This option only affects the docx reader.
547 --extract-media=DIR
549 Extract images and other media contained in or linked from the
550 source document to the path DIR, creating it if necessary, and
551 adjust the images references in the document so they point to
552 the extracted files. If the source format is a binary container
553 (docx, epub, or odt), the media is extracted from the container
554 and the original filenames are used. Otherwise the media is
555 read from the file system or downloaded, and new filenames are
556 constructed based on SHA1 hashes of the contents.
557 --abbreviations=FILE
559 Specifies a custom abbreviations file, with abbreviations one to
560 a line. If this option is not specified, pandoc will read the
561 data file abbreviations from the user data directory or fall
562 back on a system default. To see the system default, use pandoc
563 --print-default-data-file=abbreviations. The only use pandoc
564 makes of this list is in the Markdown reader. Strings ending in
565 a period that are found in this list will be followed by a non‐
566 breaking space, so that the period will not produce sentence-
567 ending space in formats like LaTeX.
568 General writer options
570 -s, --standalone
571 Produce output with an appropriate header and footer (e.g. a
572 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
573 option is set automatically for pdf, epub, epub3, fb2, docx, and
574 odt output. For native output, this option causes metadata to
575 be included; otherwise, metadata is suppressed.
576 --template=FILE|URL
578 Use the specified file as a custom template for the generated
579 document. Implies --standalone. See Templates, below, for a
580 description of template syntax. If no extension is specified,
581 an extension corresponding to the writer will be added, so that
582 --template=special looks for special.html for HTML output. If
583 the template is not found, pandoc will search for it in the tem‐
584 plates subdirectory of the user data directory (see --data-dir).
585 If this option is not used, a default template appropriate for
586 the output format will be used (see -D/--print-default-tem‐
587 plate).
588 -V KEY[=VAL], --variable=KEY[:VAL]
590 Set the template variable KEY to the value VAL when rendering
591 the document in standalone mode. This is generally only useful
592 when the --template option is used to specify a custom template,
593 since pandoc automatically sets the variables used in the
594 default templates. If no VAL is specified, the key will be
595 given the value true.
596 -D FORMAT, --print-default-template=FORMAT
598 Print the system default template for an output FORMAT. (See -t
599 for a list of possible FORMATs.) Templates in the user data
600 directory are ignored. This option may be used with -o/--output
601 to redirect output to a file, but -o/--output must come before
602 --print-default-template on the command line.
603 --print-default-data-file=FILE
605 Print a system default data file. Files in the user data direc‐
606 tory are ignored. This option may be used with -o/--output to
607 redirect output to a file, but -o/--output must come before
608 --print-default-data-file on the command line.
609 --eol=crlf|lf|native
611 Manually specify line endings: crlf (Windows), lf (mac‐
612 OS/Linux/UNIX), or native (line endings appropriate to the OS on
613 which pandoc is being run). The default is native.
614 --dpi=NUMBER
616 Specify the dpi (dots per inch) value for conversion from pixels
617 to inch/centimeters and vice versa. The default is 96dpi.
618 Technically, the correct term would be ppi (pixels per inch).
619 --wrap=auto|none|preserve
621 Determine how text is wrapped in the output (the source code,
622 not the rendered version). With auto (the default), pandoc will
623 attempt to wrap lines to the column width specified by --columns
624 (default 72). With none, pandoc will not wrap lines at all.
625 With preserve, pandoc will attempt to preserve the wrapping from
626 the source document (that is, where there are nonsemantic new‐
627 lines in the source, there will be nonsemantic newlines in the
628 output as well). Automatic wrapping does not currently work in
629 HTML output. In ipynb output, this option affects wrapping of
630 the contents of markdown cells.
631 --columns=NUMBER
633 Specify length of lines in characters. This affects text wrap‐
634 ping in the generated source code (see --wrap). It also affects
635 calculation of column widths for plain text tables (see Tables
636 below).
637 --toc, --table-of-contents
639 Include an automatically generated table of contents (or, in the
640 case of latex, context, docx, odt, opendocument, rst, or ms, an
641 instruction to create one) in the output document. This option
642 has no effect unless -s/--standalone is used, and it has no
643 effect on man, docbook4, docbook5, or jats output.
644 Note that if you are producing a PDF via ms, the table of con‐
646 tents will appear at the beginning of the document, before the
647 title. If you would prefer it to be at the end of the document,
648 use the option --pdf-engine-opt=--no-toc-relocation.
649 --toc-depth=NUMBER
651 Specify the number of section levels to include in the table of
652 contents. The default is 3 (which means that level-1, 2, and 3
653 headings will be listed in the contents).
654 --strip-comments
656 Strip out HTML comments in the Markdown or Textile source,
657 rather than passing them on to Markdown, Textile or HTML output
658 as raw HTML. This does not apply to HTML comments inside raw
659 HTML blocks when the markdown_in_html_blocks extension is not
660 set.
661 --no-highlight
663 Disables syntax highlighting for code blocks and inlines, even
664 when a language attribute is given.
665 --highlight-style=STYLE|FILE
667 Specifies the coloring style to be used in highlighted source
668 code. Options are pygments (the default), kate, monochrome,
669 breezeDark, espresso, zenburn, haddock, and tango. For more
670 information on syntax highlighting in pandoc, see Syntax high‐
671 lighting, below. See also --list-highlight-styles.
672 Instead of a STYLE name, a JSON file with extension .theme may
674 be supplied. This will be parsed as a KDE syntax highlighting
675 theme and (if valid) used as the highlighting style.
676 To generate the JSON version of an existing style, use --print-
678 highlight-style.
679 --print-highlight-style=STYLE|FILE
681 Prints a JSON version of a highlighting style, which can be mod‐
682 ified, saved with a .theme extension, and used with --highlight-
683 style. This option may be used with -o/--output to redirect
684 output to a file, but -o/--output must come before --print-high‐
685 light-style on the command line.
686 --syntax-definition=FILE
688 Instructs pandoc to load a KDE XML syntax definition file, which
689 will be used for syntax highlighting of appropriately marked
690 code blocks. This can be used to add support for new languages
691 or to use altered syntax definitions for existing languages.
692 -H FILE, --include-in-header=FILE|URL
694 Include contents of FILE, verbatim, at the end of the header.
695 This can be used, for example, to include special CSS or
696 JavaScript in HTML documents. This option can be used repeat‐
697 edly to include multiple files in the header. They will be
698 included in the order specified. Implies --standalone.
699 -B FILE, --include-before-body=FILE|URL
701 Include contents of FILE, verbatim, at the beginning of the doc‐
702 ument body (e.g. after the <body> tag in HTML, or the
703 \begin{document} command in LaTeX). This can be used to include
704 navigation bars or banners in HTML documents. This option can
705 be used repeatedly to include multiple files. They will be
706 included in the order specified. Implies --standalone.
707 -A FILE, --include-after-body=FILE|URL
709 Include contents of FILE, verbatim, at the end of the document
710 body (before the </body> tag in HTML, or the \end{document} com‐
711 mand in LaTeX). This option can be used repeatedly to include
712 multiple files. They will be included in the order specified.
713 Implies --standalone.
714 --resource-path=SEARCHPATH
716 List of paths to search for images and other resources. The
717 paths should be separated by : on Linux, UNIX, and macOS sys‐
718 tems, and by ; on Windows. If --resource-path is not specified,
719 the default resource path is the working directory. Note that,
720 if --resource-path is specified, the working directory must be
721 explicitly listed or it will not be searched. For example:
722 --resource-path=.:test will search the working directory and the
723 test subdirectory, in that order.
724 --resource-path only has an effect if (a) the output format
726 embeds images (for example, docx, pdf, or html with --self-con‐
727 tained) or (b) it is used together with --extract-media.
728 --request-header=NAME:VAL
730 Set the request header NAME to the value VAL when making HTTP
731 requests (for example, when a URL is given on the command line,
732 or when resources used in a document must be downloaded). If
733 you're behind a proxy, you also need to set the environment
734 variable http_proxy to http://....
735 Options affecting specific writers
737 --self-contained
738 Produce a standalone HTML file with no external dependencies,
739 using data: URIs to incorporate the contents of linked scripts,
740 stylesheets, images, and videos. Implies --standalone. The
741 resulting file should be "self-contained," in the sense that it
742 needs no external files and no net access to be displayed prop‐
743 erly by a browser. This option works only with HTML output for‐
744 mats, including html4, html5, html+lhs, html5+lhs, s5, slidy,
745 slideous, dzslides, and revealjs. Scripts, images, and
746 stylesheets at absolute URLs will be downloaded; those at rela‐
747 tive URLs will be sought relative to the working directory (if
748 the first source file is local) or relative to the base URL (if
749 the first source file is remote). Elements with the attribute
750 data-external="1" will be left alone; the documents they link to
751 will not be incorporated in the document. Limitation: resources
752 that are loaded dynamically through JavaScript cannot be incor‐
753 porated; as a result, --self-contained does not work with
754 --mathjax, and some advanced features (e.g. zoom or speaker
755 notes) may not work in an offline "self-contained" reveal.js
756 slide show.
757 --html-q-tags
759 Use <q> tags for quotes in HTML.
760 --ascii
762 Use only ASCII characters in output. Currently supported for
763 XML and HTML formats (which use entities instead of UTF-8 when
764 this option is selected), CommonMark, gfm, and Markdown (which
765 use entities), roff ms (which use hexadecimal escapes), and to a
766 limited degree LaTeX (which uses standard commands for accented
767 characters when possible). roff man output uses ASCII by
768 default.
769 --reference-links
771 Use reference-style links, rather than inline links, in writing
772 Markdown or reStructuredText. By default inline links are used.
773 The placement of link references is affected by the --reference-
774 location option.
775 --reference-location = block|section|document
777 Specify whether footnotes (and references, if reference-links is
778 set) are placed at the end of the current (top-level) block, the
779 current section, or the document. The default is document.
780 Currently only affects the markdown writer.
781 --atx-headers
783 Use ATX-style headings in Markdown output. The default is to
784 use setext-style headings for levels 1 to 2, and then ATX head‐
785 ings. (Note: for gfm output, ATX headings are always used.)
786 This option also affects markdown cells in ipynb output.
787 --top-level-division=[default|section|chapter|part]
789 Treat top-level headings as the given division type in LaTeX,
790 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
791 chapter, then section; all headings are shifted such that the
792 top-level heading becomes the specified type. The default
793 behavior is to determine the best division type via heuristics:
794 unless other conditions apply, section is chosen. When the
795 LaTeX document class is set to report, book, or memoir (unless
796 the article option is specified), chapter is implied as the set‐
797 ting for this option. If beamer is the output format, specify‐
798 ing either chapter or part will cause top-level headings to
799 become \part{..}, while second-level headings remain as their
800 default type.
801 -N, --number-sections
803 Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
804 By default, sections are not numbered. Sections with class
805 unnumbered will never be numbered, even if --number-sections is
806 specified.
807 --number-offset=NUMBER[,NUMBER,...]
809 Offset for section headings in HTML output (ignored in other
810 output formats). The first number is added to the section num‐
811 ber for top-level headings, the second for second-level head‐
812 ings, and so on. So, for example, if you want the first top-
813 level heading in your document to be numbered "6", specify
814 --number-offset=5. If your document starts with a level-2 head‐
815 ing which you want to be numbered "1.5", specify --number-off‐
816 set=1,4. Offsets are 0 by default. Implies --number-sections.
817 --listings
819 Use the listings package for LaTeX code blocks. The package
820 does not support multi-byte encoding for source code. To handle
821 UTF-8 you would need to use a custom template. This issue is
822 fully documented here: Encoding issue with the listings package.
823 -i, --incremental
825 Make list items in slide shows display incrementally (one by
826 one). The default is for lists to be displayed all at once.
827 --slide-level=NUMBER
829 Specifies that headings with the specified level create slides
830 (for beamer, s5, slidy, slideous, dzslides). Headings above
831 this level in the hierarchy are used to divide the slide show
832 into sections; headings below this level create subheads within
833 a slide. Note that content that is not contained under slide-
834 level headings will not appear in the slide show. The default
835 is to set the slide level based on the contents of the document;
836 see Structuring the slide show.
837 --section-divs
839 Wrap sections in <section> tags (or <div> tags for html4), and
840 attach identifiers to the enclosing <section> (or <div>) rather
841 than the heading itself. See Heading identifiers, below.
842 --email-obfuscation=none|javascript|references
844 Specify a method for obfuscating mailto: links in HTML docu‐
845 ments. none leaves mailto: links as they are. javascript
846 obfuscates them using JavaScript. references obfuscates them by
847 printing their letters as decimal or hexadecimal character ref‐
848 erences. The default is none.
849 --id-prefix=STRING
851 Specify a prefix to be added to all identifiers and internal
852 links in HTML and DocBook output, and to footnote numbers in
853 Markdown and Haddock output. This is useful for preventing
854 duplicate identifiers when generating fragments to be included
855 in other pages.
856 -T STRING, --title-prefix=STRING
858 Specify STRING as a prefix at the beginning of the title that
859 appears in the HTML header (but not in the title as it appears
860 at the beginning of the HTML body). Implies --standalone.
861 -c URL, --css=URL
863 Link to a CSS style sheet. This option can be used repeatedly
864 to include multiple files. They will be included in the order
865 specified.
866 A stylesheet is required for generating EPUB. If none is pro‐
868 vided using this option (or the css or stylesheet metadata
869 fields), pandoc will look for a file epub.css in the user data
870 directory (see --data-dir). If it is not found there, sensible
871 defaults will be used.
872 --reference-doc=FILE
874 Use the specified file as a style reference in producing a docx
875 or ODT file.
876 Docx For best results, the reference docx should be a modified
878 version of a docx file produced using pandoc. The con‐
879 tents of the reference docx are ignored, but its
880 stylesheets and document properties (including margins,
881 page size, header, and footer) are used in the new docx.
882 If no reference docx is specified on the command line,
883 pandoc will look for a file reference.docx in the user
884 data directory (see --data-dir). If this is not found
885 either, sensible defaults will be used.
886 To produce a custom reference.docx, first get a copy of
888 the default reference.docx: pandoc -o custom-refer‐
889 ence.docx --print-default-data-file reference.docx. Then
890 open custom-reference.docx in Word, modify the styles as
891 you wish, and save the file. For best results, do not
892 make changes to this file other than modifying the styles
893 used by pandoc:
894 Paragraph styles:
896 · Normal
898 · Body Text
900 · First Paragraph
902 · Compact
904 · Title
906 · Subtitle
908 · Author
910 · Date
912 · Abstract
914 · Bibliography
916 · Heading 1
918 · Heading 2
920 · Heading 3
922 · Heading 4
924 · Heading 5
926 · Heading 6
928 · Heading 7
930 · Heading 8
932 · Heading 9
934 · Block Text
936 · Footnote Text
938 · Definition Term
940 · Definition
942 · Caption
944 · Table Caption
946 · Image Caption
948 · Figure
950 · Captioned Figure
952 · TOC Heading
954 Character styles:
956 · Default Paragraph Font
958 · Body Text Char
960 · Verbatim Char
962 · Footnote Reference
964 · Hyperlink
966 Table style:
968 · Table
970 ODT For best results, the reference ODT should be a modified
972 version of an ODT produced using pandoc. The contents of
973 the reference ODT are ignored, but its stylesheets are
974 used in the new ODT. If no reference ODT is specified on
975 the command line, pandoc will look for a file refer‐
976 ence.odt in the user data directory (see --data-dir). If
977 this is not found either, sensible defaults will be used.
978 To produce a custom reference.odt, first get a copy of
980 the default reference.odt: pandoc -o custom-reference.odt
981 --print-default-data-file reference.odt. Then open cus‐
982 tom-reference.odt in LibreOffice, modify the styles as
983 you wish, and save the file.
984 PowerPoint
986 Templates included with Microsoft PowerPoint 2013 (either
987 with .pptx or .potx extension) are known to work, as are
988 most templates derived from these.
989 The specific requirement is that the template should
991 begin with the following first four layouts:
992 1. Title Slide
994 2. Title and Content
996 3. Section Header
998 4. Two Content
1000 All templates included with a recent version of MS Power‐
1002 Point will fit these criteria. (You can click on Layout
1003 under the Home menu to check.)
1004 You can also modify the default reference.pptx: first run
1006 pandoc -o custom-reference.pptx --print-default-data-file
1007 reference.pptx, and then modify custom-reference.pptx in
1008 MS PowerPoint (pandoc will use the first four layout
1009 slides, as mentioned above).
1010 --epub-cover-image=FILE
1012 Use the specified image as the EPUB cover. It is recommended
1013 that the image be less than 1000px in width and height. Note
1014 that in a Markdown source document you can also specify cover-
1015 image in a YAML metadata block (see EPUB Metadata, below).
1016 --epub-metadata=FILE
1018 Look in the specified XML file for metadata for the EPUB. The
1019 file should contain a series of Dublin Core elements. For exam‐
1020 ple:
1021 <dc:rights>Creative Commons</dc:rights>
1023 <dc:language>es-AR</dc:language>
1024 By default, pandoc will include the following metadata elements:
1026 <dc:title> (from the document title), <dc:creator> (from the
1027 document authors), <dc:date> (from the document date, which
1028 should be in ISO 8601 format), <dc:language> (from the lang
1029 variable, or, if is not set, the locale), and <dc:identifier
1030 id="BookId"> (a randomly generated UUID). Any of these may be
1031 overridden by elements in the metadata file.
1032 Note: if the source document is Markdown, a YAML metadata block
1034 in the document can be used instead. See below under EPUB Meta‐
1035 data.
1036 --epub-embed-font=FILE
1038 Embed the specified font in the EPUB. This option can be
1039 repeated to embed multiple fonts. Wildcards can also be used:
1040 for example, DejaVuSans-*.ttf. However, if you use wildcards on
1041 the command line, be sure to escape them or put the whole file‐
1042 name in single quotes, to prevent them from being interpreted by
1043 the shell. To use the embedded fonts, you will need to add dec‐
1044 larations like the following to your CSS (see --css):
1045 @font-face {
1047 font-family: DejaVuSans;
1048 font-style: normal;
1049 font-weight: normal;
1050 src:url("DejaVuSans-Regular.ttf");
1051 }
1052 @font-face {
1053 font-family: DejaVuSans;
1054 font-style: normal;
1055 font-weight: bold;
1056 src:url("DejaVuSans-Bold.ttf");
1057 }
1058 @font-face {
1059 font-family: DejaVuSans;
1060 font-style: italic;
1061 font-weight: normal;
1062 src:url("DejaVuSans-Oblique.ttf");
1063 }
1064 @font-face {
1065 font-family: DejaVuSans;
1066 font-style: italic;
1067 font-weight: bold;
1068 src:url("DejaVuSans-BoldOblique.ttf");
1069 }
1070 body { font-family: "DejaVuSans"; }
1071 --epub-chapter-level=NUMBER
1073 Specify the heading level at which to split the EPUB into sepa‐
1074 rate "chapter" files. The default is to split into chapters at
1075 level-1 headings. This option only affects the internal compo‐
1076 sition of the EPUB, not the way chapters and sections are dis‐
1077 played to users. Some readers may be slow if the chapter files
1078 are too large, so for large documents with few level-1 headings,
1079 one might want to use a chapter level of 2 or 3.
1080 --epub-subdirectory=DIRNAME
1082 Specify the subdirectory in the OCF container that is to hold
1083 the EPUB-specific contents. The default is EPUB. To put the
1084 EPUB contents in the top level, use an empty string.
1085 --ipynb-output=all|none|best
1087 Determines how ipynb output cells are treated. all means that
1088 all of the data formats included in the original are preserved.
1089 none means that the contents of data cells are omitted. best
1090 causes pandoc to try to pick the richest data block in each out‐
1091 put cell that is compatible with the output format. The default
1092 is best.
1093 --pdf-engine=PROGRAM
1095 Use the specified engine when producing PDF output. Valid val‐
1096 ues are pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtml‐
1097 topdf, weasyprint, prince, context, and pdfroff. The default is
1098 pdflatex. If the engine is not in your PATH, the full path of
1099 the engine may be specified here.
1100 --pdf-engine-opt=STRING
1102 Use the given string as a command-line argument to the pdf-
1103 engine. For example, to use a persistent directory foo for
1104 latexmk's auxiliary files, use --pdf-engine-opt=-outdir=foo.
1105 Note that no check for duplicate options is done.
1106 Citation rendering
1108 --bibliography=FILE
1109 Set the bibliography field in the document's metadata to FILE,
1110 overriding any value set in the metadata, and process citations
1111 using pandoc-citeproc. (This is equivalent to --metadata bibli‐
1112 ography=FILE --filter pandoc-citeproc.) If --natbib or --bibla‐
1113 tex is also supplied, pandoc-citeproc is not used, making this
1114 equivalent to --metadata bibliography=FILE. If you supply this
1115 argument multiple times, each FILE will be added to bibliogra‐
1116 phy.
1117 --csl=FILE
1119 Set the csl field in the document's metadata to FILE, overriding
1120 any value set in the metadata. (This is equivalent to --meta‐
1121 data csl=FILE.) This option is only relevant with pandoc-
1122 citeproc.
1123 --citation-abbreviations=FILE
1125 Set the citation-abbreviations field in the document's metadata
1126 to FILE, overriding any value set in the metadata. (This is
1127 equivalent to --metadata citation-abbreviations=FILE.) This
1128 option is only relevant with pandoc-citeproc.
1129 --natbib
1131 Use natbib for citations in LaTeX output. This option is not
1132 for use with the pandoc-citeproc filter or with PDF output. It
1133 is intended for use in producing a LaTeX file that can be pro‐
1134 cessed with bibtex.
1135 --biblatex
1137 Use biblatex for citations in LaTeX output. This option is not
1138 for use with the pandoc-citeproc filter or with PDF output. It
1139 is intended for use in producing a LaTeX file that can be pro‐
1140 cessed with bibtex or biber.
1141 Math rendering in HTML
1143 The default is to render TeX math as far as possible using Unicode
1144 characters. Formulas are put inside a span with class="math", so that
1145 they may be styled differently from the surrounding text if needed.
1146 However, this gives acceptable results only for basic math, usually you
1147 will want to use --mathjax or another of the following options.
1148 --mathjax[=URL]
1150 Use MathJax to display embedded TeX math in HTML output. TeX
1151 math will be put between \(...\) (for inline math) or \[...\]
1152 (for display math) and wrapped in <span> tags with class math.
1153 Then the MathJax JavaScript will render it. The URL should
1154 point to the MathJax.js load script. If a URL is not provided,
1155 a link to the Cloudflare CDN will be inserted.
1156 --mathml
1158 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
1159 html4 and html5). This is the default in odt output. Note that
1160 currently only Firefox and Safari (and select e-book readers)
1161 natively support MathML.
1162 --webtex[=URL]
1164 Convert TeX formulas to <img> tags that link to an external
1165 script that converts formulas to images. The formula will be
1166 URL-encoded and concatenated with the URL provided. For SVG
1167 images you can for example use --webtex
1168 https://latex.codecogs.com/svg.latex?. If no URL is specified,
1169 the CodeCogs URL generating PNGs will be used
1170 (https://latex.codecogs.com/png.latex?). Note: the --webtex
1171 option will affect Markdown output as well as HTML, which is
1172 useful if you're targeting a version of Markdown without native
1173 math support.
1174 --katex[=URL]
1176 Use KaTeX to display embedded TeX math in HTML output. The URL
1177 is the base URL for the KaTeX library. That directory should
1178 contain a katex.min.js and a katex.min.css file. If a URL is
1179 not provided, a link to the KaTeX CDN will be inserted.
1180 --gladtex
1182 Enclose TeX math in <eq> tags in HTML output. The resulting
1183 HTML can then be processed by GladTeX to produce images of the
1184 typeset formulas and an HTML file with links to these images.
1185 So, the procedure is:
1186 pandoc -s --gladtex input.md -o myfile.htex
1188 gladtex -d myfile-images myfile.htex
1189 # produces myfile.html and images in myfile-images
1190 Options for wrapper scripts
1192 --dump-args
1193 Print information about command-line arguments to stdout, then
1194 exit. This option is intended primarily for use in wrapper
1195 scripts. The first line of output contains the name of the out‐
1196 put file specified with the -o option, or - (for stdout) if no
1197 output file was specified. The remaining lines contain the com‐
1198 mand-line arguments, one per line, in the order they appear.
1199 These do not include regular pandoc options and their arguments,
1200 but do include any options appearing after a -- separator at the
1201 end of the line.
1202 --ignore-args
1204 Ignore command-line arguments (for use in wrapper scripts).
1205 Regular pandoc options are not ignored. Thus, for example,
1206 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1208 is equivalent to
1210 pandoc -o foo.html -s
1212
1214 When the -s/--standalone option is used, pandoc uses a template to add
1215 header and footer material that is needed for a self-standing document.
1216 To see the default template that is used, just type
1217 pandoc -D *FORMAT*
1219 where FORMAT is the name of the output format. A custom template can
1221 be specified using the --template option. You can also override the
1222 system default templates for a given output format FORMAT by putting a
1223 file templates/default.*FORMAT* in the user data directory (see --data-
1224 dir, above). Exceptions:
1225 · For odt output, customize the default.opendocument template.
1227 · For pdf output, customize the default.latex template (or the
1229 default.context template, if you use -t context, or the default.ms
1230 template, if you use -t ms, or the default.html template, if you use
1231 -t html).
1232 · docx and pptx have no template (however, you can use --reference-doc
1234 to customize the output).
1235 Templates contain variables, which allow for the inclusion of arbitrary
1237 information at any point in the file. They may be set at the command
1238 line using the -V/--variable option. If a variable is not set, pandoc
1239 will look for the key in the document's metadata – which can be set
1240 using either YAML metadata blocks or with the -M/--metadata option.
1241 Metadata variables
1243 title, author, date
1244 allow identification of basic aspects of the document. Included
1245 in PDF metadata through LaTeX and ConTeXt. These can be set
1246 through a pandoc title block, which allows for multiple authors,
1247 or through a YAML metadata block:
1248 ---
1250 author:
1251 - Aristotle
1252 - Peter Abelard
1253 ...
1254 Note that if you just want to set PDF or HTML metadata, without
1256 including a title block in the document itself, you can set the
1257 title-meta, author-meta, and date-meta variables. (By default
1258 these are set automatically, based on title, author, and date.)
1259 subtitle
1261 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
1262 docx documents
1263 abstract
1265 document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
1266 documents
1267 keywords
1269 list of keywords to be included in HTML, PDF, ODT, pptx, docx
1270 and AsciiDoc metadata; repeat as for author, above
1271 subject
1273 document subject, included in ODT, PDF, docx and pptx metadata
1274 description
1276 document description, included in ODT, docx and pptx metadata.
1277 Some applications show this as Comments metadata.
1278 category
1280 document category, included in docx and pptx metadata
1281 Additionally, any root-level string metadata, not included in ODT, docx
1283 or pptx metadata is added as a custom property. The following YAML
1284 metadata block for instance:
1285 ---
1287 title: 'This is the title'
1288 subtitle: "This is the subtitle"
1289 author:
1290 - Author One
1291 - Author Two
1292 description: |
1293 This is a long
1294 description.
1295 It consists of two paragraphs
1297 ...
1298 will include title, author and description as standard document proper‐
1300 ties and subtitle as a custom property when converting to docx, ODT or
1301 pptx.
1302 Language variables
1304 lang identifies the main language of the document using IETF language
1305 tags (following the BCP 47 standard), such as en or en-GB. The
1306 Language subtag lookup tool can look up or verify these tags.
1307 This affects most formats, and controls hyphenation in PDF out‐
1308 put when using LaTeX (through babel and polyglossia) or ConTeXt.
1309 Use native pandoc Divs and Spans with the lang attribute to
1311 switch the language:
1312 ---
1314 lang: en-GB
1315 ...
1316 Text in the main document language (British English).
1318 ::: {lang=fr-CA}
1320 > Cette citation est écrite en français canadien.
1321 :::
1322 More text in English. ['Zitat auf Deutsch.']{lang=de}
1324 dir the base script direction, either rtl (right-to-left) or ltr
1326 (left-to-right).
1327 For bidirectional documents, native pandoc spans and divs with
1329 the dir attribute (value rtl or ltr) can be used to override the
1330 base direction in some output formats. This may not always be
1331 necessary if the final renderer (e.g. the browser, when gener‐
1332 ating HTML) supports the Unicode Bidirectional Algorithm.
1333 When using LaTeX for bidirectional documents, only the xelatex
1335 engine is fully supported (use --pdf-engine=xelatex).
1336 Variables for HTML slides
1338 These affect HTML output when producing slide shows with pandoc. All
1339 reveal.js configuration options are available as variables.
1340 revealjs-url
1342 base URL for reveal.js documents (defaults to reveal.js)
1343 s5-url base URL for S5 documents (defaults to s5/default)
1345 slidy-url
1347 base URL for Slidy documents (defaults to
1348 https://www.w3.org/Talks/Tools/Slidy2)
1349 slideous-url
1351 base URL for Slideous documents (defaults to slideous)
1352 Variables for Beamer slides
1354 These variables change the appearance of PDF slides using beamer.
1355 aspectratio
1357 slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for
1358 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)
1359 beamerarticle
1361 produce an article from Beamer slides
1362 beameroption
1364 add extra beamer option with \setbeameroption{}
1365 institute
1367 author affiliations: can be a list when there are multiple
1368 authors
1369 logo logo image for slides
1371 navigation
1373 controls navigation symbols (default is empty for no navigation
1374 symbols; other valid values are frame, vertical, and horizontal)
1375 section-titles
1377 enables "title pages" for new sections (default is true)
1378 theme, colortheme, fonttheme, innertheme, outertheme
1380 beamer themes:
1381 themeoptions
1383 options for LaTeX beamer themes (a list).
1384 titlegraphic
1386 image for title slide
1387 Variables for LaTeX
1389 Pandoc uses these variables when creating a PDF with a LaTeX engine.
1390 Layout
1392 block-headings
1393 make \paragraph and \subparagraph (fourth- and fifth-level head‐
1394 ings, or fifth- and sixth-level with book classes) free-standing
1395 rather than run-in; requires further formatting to distinguish
1396 from \subsubsection (third- or fourth-level headings). Instead
1397 of using this option, KOMA-Script can adjust headings more
1398 extensively:
1399 ---
1401 documentclass: scrartcl
1402 header-includes: |
1403 \RedeclareSectionCommand[
1404 beforeskip=-10pt plus -2pt minus -1pt,
1405 afterskip=1sp plus -1sp minus 1sp,
1406 font=\normalfont\itshape]{paragraph}
1407 \RedeclareSectionCommand[
1408 beforeskip=-10pt plus -2pt minus -1pt,
1409 afterskip=1sp plus -1sp minus 1sp,
1410 font=\normalfont\scshape,
1411 indent=0pt]{subparagraph}
1412 ...
1413 classoption
1415 option for document class, e.g. oneside; repeat for multiple
1416 options:
1417 ---
1419 classoption:
1420 - twocolumn
1421 - landscape
1422 ...
1423 documentclass
1425 document class: usually one of the standard classes, article,
1426 book, and report; the KOMA-Script equivalents, scrartcl, scr‐
1427 book, and scrreprt, which default to smaller margins; or memoir
1428 geometry
1430 option for geometry package, e.g. margin=1in; repeat for multi‐
1431 ple options:
1432 ---
1434 geometry:
1435 - top=30mm
1436 - left=20mm
1437 - heightrounded
1438 ...
1439 indent uses document class settings for indentation (the default LaTeX
1441 template otherwise removes indentation and adds space between
1442 paragraphs)
1443 linestretch
1445 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
1446 margin-left, margin-right, margin-top, margin-bottom
1448 sets margins if geometry is not used (otherwise geometry over‐
1449 rides these)
1450 pagestyle
1452 control \pagestyle{}: the default article class supports plain
1453 (default), empty (no running heads or page numbers), and head‐
1454 ings (section titles in running heads)
1455 papersize
1457 paper size, e.g. letter, a4
1458 secnumdepth
1460 numbering depth for sections (with --number-sections option or
1461 numbersections variable)
1462 Fonts
1464 fontenc
1465 allows font encoding to be specified through fontenc package
1466 (with pdflatex); default is T1 (see LaTeX font encodings guide)
1467 fontfamily
1469 font package for use with pdflatex: TeX Live includes many
1470 options, documented in the LaTeX Font Catalogue. The default is
1471 Latin Modern.
1472 fontfamilyoptions
1474 options for package used as fontfamily; repeat for multiple
1475 options. For example, to use the Libertine font with propor‐
1476 tional lowercase (old-style) figures through the libertinus
1477 package:
1478 ---
1480 fontfamily: libertinus
1481 fontfamilyoptions:
1482 - osf
1483 - p
1484 ...
1485 fontsize
1487 font size for body text. The standard classes allow 10pt, 11pt,
1488 and 12pt. To use another size, set documentclass to one of the
1489 KOMA-Script classes, such as scrartcl or scrbook.
1490 mainfont, sansfont, monofont, mathfont, CJKmainfont
1492 font families for use with xelatex or lualatex: take the name of
1493 any system font, using the fontspec package. CJKmainfont uses
1494 the xecjk package.
1495 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions,
1497 CJKoptions
1498 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
1499 mainfont in xelatex and lualatex. Allow for any choices avail‐
1500 able through fontspec; repeat for multiple options. For exam‐
1501 ple, to use the TeX Gyre version of Palatino with lowercase fig‐
1502 ures:
1503 ---
1505 mainfont: TeX Gyre Pagella
1506 mainfontoptions:
1507 - Numbers=Lowercase
1508 - Numbers=Proportional
1509 ...
1510 microtypeoptions
1512 options to pass to the microtype package
1513 Links
1515 colorlinks
1516 add color to link text; automatically enabled if any of link‐
1517 color, filecolor, citecolor, urlcolor, or toccolor are set
1518 linkcolor, filecolor, citecolor, urlcolor, toccolor
1520 color for internal links, external links, citation links, linked
1521 URLs, and links in table of contents, respectively: uses options
1522 allowed by xcolor, including the dvipsnames, svgnames, and
1523 x11names lists
1524 links-as-notes
1526 causes links to be printed as footnotes
1527 Front matter
1529 lof, lot
1530 include list of figures, list of tables
1531 thanks contents of acknowledgments footnote after document title
1533 toc include table of contents (can also be set using --toc/--table-
1535 of-contents)
1536 toc-depth
1538 level of section to include in table of contents
1539 BibLaTeX Bibliographies
1541 These variables function when using BibLaTeX for citation rendering.
1542 biblatexoptions
1544 list of options for biblatex
1545 biblio-style
1547 bibliography style, when used with --natbib and --biblatex.
1548 biblio-title
1550 bibliography title, when used with --natbib and --biblatex.
1551 bibliography
1553 bibliography to use for resolving references
1554 natbiboptions
1556 list of options for natbib
1557 Variables for ConTeXt
1559 Pandoc uses these variables when creating a PDF with ConTeXt.
1560 fontsize
1562 font size for body text (e.g. 10pt, 12pt)
1563 headertext, footertext
1565 text to be placed in running header or footer (see ConTeXt Head‐
1566 ers and Footers); repeat up to four times for different place‐
1567 ment
1568 indenting
1570 controls indentation of paragraphs, e.g. yes,small,next (see
1571 ConTeXt Indentation); repeat for multiple options
1572 interlinespace
1574 adjusts line spacing, e.g. 4ex (using setupinterlinespace);
1575 repeat for multiple options
1576 layout options for page margins and text arrangement (see ConTeXt Lay‐
1578 out); repeat for multiple options
1579 linkcolor, contrastcolor
1581 color for links outside and inside a page, e.g. red, blue (see
1582 ConTeXt Color)
1583 linkstyle
1585 typeface style for links, e.g. normal, bold, slanted, bold‐
1586 slanted, type, cap, small
1587 lof, lot
1589 include list of figures, list of tables
1590 mainfont, sansfont, monofont, mathfont
1592 font families: take the name of any system font (see ConTeXt
1593 Font Switching)
1594 margin-left, margin-right, margin-top, margin-bottom
1596 sets margins, if layout is not used (otherwise layout overrides
1597 these)
1598 pagenumbering
1600 page number style and location (using setuppagenumbering);
1601 repeat for multiple options
1602 papersize
1604 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
1605 up); repeat for multiple options
1606 pdfa adds to the preamble the setup necessary to generate
1608 PDF/A-1b:2005. To successfully generate PDF/A the required ICC
1609 color profiles have to be available and the content and all
1610 included files (such as images) have to be standard conforming.
1611 The ICC profiles can be obtained from ConTeXt ICC Profiles. See
1612 also ConTeXt PDFA for more details.
1613 toc include table of contents (can also be set using --toc/--table-
1615 of-contents)
1616 whitespace
1618 spacing between paragraphs, e.g. none, small (using setup‐
1619 whitespace)
1620 Variables for wkhtmltopdf
1622 Pandoc uses these variables when creating a PDF with wkhtmltopdf. The
1623 --css option also affects the output.
1624 footer-html, header-html
1626 add information to the header and footer
1627 margin-left, margin-right, margin-top, margin-bottom
1629 set the page margins
1630 papersize
1632 sets the PDF paper size
1633 Variables for man pages
1635 adjusting
1636 adjusts text to left (l), right (r), center (c), or both (b)
1637 margins
1638 footer footer in man pages
1640 header header in man pages
1642 hyphenate
1644 if true (the default), hyphenation will be used
1645 section
1647 section number in man pages
1648 Variables for ms
1650 fontfamily
1651 font family (e.g. T or P)
1652 indent paragraph indent (e.g. 2m)
1654 lineheight
1656 line height (e.g. 12p)
1657 pointsize
1659 point size (e.g. 10p)
1660 Structural variables
1662 Pandoc sets these variables automatically in response to options or
1663 document contents; users can also modify them. These vary depending on
1664 the output format, and include the following:
1665 body body of document
1667 date-meta
1669 the date variable converted to ISO 8601 YYYY-MM-DD, included in
1670 all HTML based formats (dzslides, epub, html, html4, html5,
1671 revealjs, s5, slideous, slidy). The recognized formats for date
1672 are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy
1673 (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy (e.g.
1674 Apr. 02, 2018 or April 02, 2018),yyyy[mm[dd]]](e.g.20180402,
1675 201804 or 2018).
1676 header-includes
1678 contents specified by -H/--include-in-header (may have multiple
1679 values)
1680 include-before
1682 contents specified by -B/--include-before-body (may have multi‐
1683 ple values)
1684 include-after
1686 contents specified by -A/--include-after-body (may have multiple
1687 values)
1688 meta-json
1690 JSON representation of all of the document's metadata. Field
1691 values are transformed to the selected output format.
1692 numbersections
1694 non-null value if -N/--number-sections was specified
1695 sourcefile, outputfile
1697 source and destination filenames, as given on the command line.
1698 sourcefile can also be a list if input comes from multiple
1699 files, or empty if input is from stdin. You can use the follow‐
1700 ing snippet in your template to distinguish them:
1701 $if(sourcefile)$
1703 $for(sourcefile)$
1704 $sourcefile$
1705 $endfor$
1706 $else$
1707 (stdin)
1708 $endif$
1709 Similarly, outputfile can be - if output goes to the terminal.
1711 If you need absolute paths, use e.g. $curdir$/$sourcefile$.
1713 curdir working directory from which pandoc is run.
1715 toc non-null value if --toc/--table-of-contents was specified
1717 toc-title
1719 title of table of contents (works only with EPUB, opendocument,
1720 odt, docx, pptx, beamer, LaTeX)
1721 Using variables in templates
1723 Variable names are sequences of alphanumerics, -, and _, starting with
1724 a letter. A variable name surrounded by $ signs will be replaced by
1725 its value. For example, the string $title$ in
1726 <title>$title$</title>
1728 will be replaced by the document title.
1730 To write a literal $ in a template, use $$.
1732 Templates may contain conditionals. The syntax is as follows:
1734 $if(variable)$
1736 X
1737 $else$
1738 Y
1739 $endif$
1740 This will include X in the template if variable has a truthy value;
1742 otherwise it will include Y. Here a truthy value is any of the follow‐
1743 ing:
1744 · a string that is not entirely white space,
1746 · a non-empty array where the first value is truthy,
1748 · any number (including zero),
1750 · any object,
1752 · the boolean true (to specify the boolean true value using YAML meta‐
1754 data or the --metadata flag, use true, True, or TRUE; with the
1755 --variable flag, simply omit a value for the variable, e.g. --vari‐
1756 able draft).
1757 X and Y are placeholders for any valid template text, and may include
1759 interpolated variables or other conditionals. The $else$ section may
1760 be omitted.
1761 When variables can have multiple values (for example, author in a
1763 multi-author document), you can use the $for$ keyword:
1764 $for(author)$
1766 <meta name="author" content="$author$" />
1767 $endfor$
1768 You can optionally specify a separator to be used between consecutive
1770 items:
1771 $for(author)$$author$$sep$, $endfor$
1773 Note that the separator needs to be specified immediately before the
1775 $endfor keyword.
1776 A dot can be used to select a field of a variable that takes an object
1778 as its value. So, for example:
1779 $author.name$ ($author.affiliation$)
1781 The value of a variable will be indented to the same level as the vari‐
1783 able.
1784 If you use custom templates, you may need to revise them as pandoc
1786 changes. We recommend tracking the changes in the default templates,
1787 and modifying your custom templates accordingly. An easy way to do
1788 this is to fork the pandoc-templates repository and merge in changes
1789 after each pandoc release.
1790 Templates may contain comments: anything on a line after $-- will be
1792 treated as a comment and ignored.
1793
1795 The behavior of some of the readers and writers can be adjusted by
1796 enabling or disabling various extensions.
1797 An extension can be enabled by adding +EXTENSION to the format name and
1799 disabled by adding -EXTENSION. For example, --from mark‐
1800 down_strict+footnotes is strict Markdown with footnotes enabled, while
1801 --from markdown-footnotes-pipe_tables is pandoc's Markdown without
1802 footnotes or pipe tables.
1803 The markdown reader and writer make by far the most use of extensions.
1805 Extensions only used by them are therefore covered in the section Pan‐
1806 doc's Markdown below (See Markdown variants for commonmark and gfm.) In
1807 the following, extensions that also work for other formats are covered.
1808 Note that markdown extensions added to the ipynb format affect Markdown
1810 cells in Jupyter notebooks (as do command-line options like --atx-head‐
1811 ers).
1812 Typography
1814 Extension: smart
1815 Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-
1816 dashes, and ... as ellipses. Nonbreaking spaces are inserted after
1817 certain abbreviations, such as "Mr."
1818 This extension can be enabled/disabled for the following formats:
1820 input formats
1822 markdown, commonmark, latex, mediawiki, org, rst, twiki
1823 output formats
1825 markdown, latex, context, rst
1826 enabled by default in
1828 markdown, latex, context (both input and output)
1829 Note: If you are writing Markdown, then the smart extension has the
1831 reverse effect: what would have been curly quotes comes out straight.
1832 In LaTeX, smart means to use the standard TeX ligatures for quotation
1834 marks (`` and '' for double quotes, ` and ' for single quotes) and
1835 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
1836 then in reading LaTeX pandoc will parse these characters literally. In
1837 writing LaTeX, enabling smart tells pandoc to use the ligatures when
1838 possible; if smart is disabled pandoc will use unicode quotation mark
1839 and dash characters.
1840 Headings and sections
1842 Extension: auto_identifiers
1843 A heading without an explicitly specified identifier will be automati‐
1844 cally assigned a unique identifier based on the heading text.
1845 This extension can be enabled/disabled for the following formats:
1847 input formats
1849 markdown, latex, rst, mediawiki, textile
1850 output formats
1852 markdown, muse
1853 enabled by default in
1855 markdown, muse
1856 The default algorithm used to derive the identifier from the heading
1858 text is:
1859 · Remove all formatting, links, etc.
1861 · Remove all footnotes.
1863 · Remove all non-alphanumeric characters, except underscores, hyphens,
1865 and periods.
1866 · Replace all spaces and newlines with hyphens.
1868 · Convert all alphabetic characters to lowercase.
1870 · Remove everything up to the first letter (identifiers may not begin
1872 with a number or punctuation mark).
1873 · If nothing is left after this, use the identifier section.
1875 Thus, for example,
1877 Heading Identifier
1879 ─────────────────────────────────────────────────────
1880 Heading identifiers in heading-identifiers-in-
1881 HTML html
1882 Maître d'hôtel maître-dhôtel
1883 *Dogs*?--in *my* house? dogs--in-my-house
1884 [HTML], [S5], or [RTF]? html-s5-or-rtf
1885 3. Applications applications
1886 33 section
1887 These rules should, in most cases, allow one to determine the identi‐
1889 fier from the heading text. The exception is when several headings
1890 have the same text; in this case, the first will get an identifier as
1891 described above; the second will get the same identifier with -1
1892 appended; the third with -2; and so on.
1893 (However, a different algorithm is used if gfm_auto_identifiers is
1895 enabled; see below.)
1896 These identifiers are used to provide link targets in the table of con‐
1898 tents generated by the --toc|--table-of-contents option. They also
1899 make it easy to provide links from one section of a document to
1900 another. A link to this section, for example, might look like this:
1901 See the section on
1903 [heading identifiers](#heading-identifiers-in-html-latex-and-context).
1904 Note, however, that this method of providing links to sections works
1906 only in HTML, LaTeX, and ConTeXt formats.
1907 If the --section-divs option is specified, then each section will be
1909 wrapped in a section (or a div, if html4 was specified), and the iden‐
1910 tifier will be attached to the enclosing <section> (or <div>) tag
1911 rather than the heading itself. This allows entire sections to be
1912 manipulated using JavaScript or treated differently in CSS.
1913 Extension: ascii_identifiers
1915 Causes the identifiers produced by auto_identifiers to be pure ASCII.
1916 Accents are stripped off of accented Latin letters, and non-Latin let‐
1917 ters are omitted.
1918 Extension: gfm_auto_identifiers
1920 Changes the algorithm used by auto_identifiers to conform to GitHub's
1921 method. Spaces are converted to dashes (-), uppercase characters to
1922 lowercase characters, and punctuation characters other than - and _ are
1923 removed.
1924 Math Input
1926 The extensions tex_math_dollars, tex_math_single_backslash, and
1927 tex_math_double_backslash are described in the section about Pandoc's
1928 Markdown.
1929 However, they can also be used with HTML input. This is handy for
1931 reading web pages formatted using MathJax, for example.
1932 Raw HTML/TeX
1934 The following extensions (especially how they affect Markdown
1935 input/output) are also described in more detail in their respective
1936 sections of Pandoc's Markdown.
1937 Extension: raw_html
1939 When converting from HTML, parse elements to raw HTML which are not
1940 representable in pandoc's AST. By default, this is disabled for HTML
1941 input.
1942 Extension: raw_tex
1944 Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
1945 This extension can be enabled/disabled for the following formats (in
1947 addition to markdown):
1948 input formats
1950 latex, org, textile, html (environments, \ref, and \eqref only),
1951 ipynb
1952 output formats
1954 textile, commonmark
1955 Note: as applied to ipynb, raw_html and raw_tex affect not only raw TeX
1957 in markdown cells, but data with mime type text/html in output cells.
1958 Since the ipynb reader attempts to preserve the richest possible out‐
1959 puts when several options are given, you will get best results if you
1960 disable raw_html and raw_tex when converting to formats like docx which
1961 don't allow raw html or tex.
1962 Extension: native_divs
1964 This extension is enabled by default for HTML input. This means that
1965 divs are parsed to pandoc native elements. (Alternatively, you can
1966 parse them to raw HTML using -f html-native_divs+raw_html.)
1967 When converting HTML to Markdown, for example, you may want to drop all
1969 divs and spans:
1970 pandoc -f html-native_divs-native_spans -t markdown
1972 Extension: native_spans
1974 Analogous to native_divs above.
1975 Literate Haskell support
1977 Extension: literate_haskell
1978 Treat the document as literate Haskell source.
1979 This extension can be enabled/disabled for the following formats:
1981 input formats
1983 markdown, rst, latex
1984 output formats
1986 markdown, rst, latex, html
1987 If you append +lhs (or +literate_haskell) to one of the formats above,
1989 pandoc will treat the document as literate Haskell source. This means
1990 that
1991 · In Markdown input, "bird track" sections will be parsed as Haskell
1993 code rather than block quotations. Text between \begin{code} and
1994 \end{code} will also be treated as Haskell code. For ATX-style head‐
1995 ings the character '=' will be used instead of '#'.
1996 · In Markdown output, code blocks with classes haskell and literate
1998 will be rendered using bird tracks, and block quotations will be
1999 indented one space, so they will not be treated as Haskell code. In
2000 addition, headings will be rendered setext-style (with underlines)
2001 rather than ATX-style (with '#' characters). (This is because ghc
2002 treats '#' characters in column 1 as introducing line numbers.)
2003 · In restructured text input, "bird track" sections will be parsed as
2005 Haskell code.
2006 · In restructured text output, code blocks with class haskell will be
2008 rendered using bird tracks.
2009 · In LaTeX input, text in code environments will be parsed as Haskell
2011 code.
2012 · In LaTeX output, code blocks with class haskell will be rendered
2014 inside code environments.
2015 · In HTML output, code blocks with class haskell will be rendered with
2017 class literatehaskell and bird tracks.
2018 Examples:
2020 pandoc -f markdown+lhs -t html
2022 reads literate Haskell source formatted with Markdown conventions and
2024 writes ordinary HTML (without bird tracks).
2025 pandoc -f markdown+lhs -t html+lhs
2027 writes HTML with the Haskell code in bird tracks, so it can be copied
2029 and pasted as literate Haskell source.
2030 Note that GHC expects the bird tracks in the first column, so indented
2032 literate code blocks (e.g. inside an itemized environment) will not be
2033 picked up by the Haskell compiler.
2034 Other extensions
2036 Extension: empty_paragraphs
2037 Allows empty paragraphs. By default empty paragraphs are omitted.
2038 This extension can be enabled/disabled for the following formats:
2040 input formats
2042 docx, html
2043 output formats
2045 docx, odt, opendocument, html
2046 Extension: styles
2048 When converting from docx, read all docx styles as divs (for paragraph
2049 styles) and spans (for character styles) regardless of whether pandoc
2050 understands the meaning of these styles. This can be used with docx
2051 custom styles. Disabled by default.
2052 input formats
2054 docx
2055 Extension: amuse
2057 In the muse input format, this enables Text::Amuse extensions to Emacs
2058 Muse markup.
2059 Extension: citations
2061 Some aspects of Pandoc's Markdown citation syntax are also accepted in
2062 org input.
2063 Extension: ntb
2065 In the context output format this enables the use of Natural Tables
2066 (TABLE) instead of the default Extreme Tables (xtables). Natural
2067 tables allow more fine-grained global customization but come at a per‐
2068 formance penalty compared to extreme tables.
2069
2071 Pandoc understands an extended and slightly revised version of John
2072 Gruber's Markdown syntax. This document explains the syntax, noting
2073 differences from standard Markdown. Except where noted, these differ‐
2074 ences can be suppressed by using the markdown_strict format instead of
2075 markdown. Extensions can be enabled or disabled to specify the behav‐
2076 ior more granularly. They are described in the following. See also
2077 Extensions above, for extensions that work also on other formats.
2078 Philosophy
2080 Markdown is designed to be easy to write, and, even more importantly,
2081 easy to read:
2082 A Markdown-formatted document should be publishable as-is, as
2084 plain text, without looking like it's been marked up with tags
2085 or formatting instructions. -- John Gruber
2086 This principle has guided pandoc's decisions in finding syntax for
2088 tables, footnotes, and other extensions.
2089 There is, however, one respect in which pandoc's aims are different
2091 from the original aims of Markdown. Whereas Markdown was originally
2092 designed with HTML generation in mind, pandoc is designed for multiple
2093 output formats. Thus, while pandoc allows the embedding of raw HTML,
2094 it discourages it, and provides other, non-HTMLish ways of representing
2095 important document elements like definition lists, tables, mathematics,
2096 and footnotes.
2097 Paragraphs
2099 A paragraph is one or more lines of text followed by one or more blank
2100 lines. Newlines are treated as spaces, so you can reflow your para‐
2101 graphs as you like. If you need a hard line break, put two or more
2102 spaces at the end of a line.
2103 Extension: escaped_line_breaks
2105 A backslash followed by a newline is also a hard line break. Note: in
2106 multiline and grid table cells, this is the only way to create a hard
2107 line break, since trailing spaces in the cells are ignored.
2108 Headings
2110 There are two kinds of headings: Setext and ATX.
2111 Setext-style headings
2113 A setext-style heading is a line of text "underlined" with a row of =
2114 signs (for a level-one heading) or - signs (for a level-two heading):
2115 A level-one heading
2117 ===================
2118 A level-two heading
2120 -------------------
2121 The heading text can contain inline formatting, such as emphasis (see
2123 Inline formatting, below).
2124 ATX-style headings
2126 An ATX-style heading consists of one to six # signs and a line of text,
2127 optionally followed by any number of # signs. The number of # signs at
2128 the beginning of the line is the heading level:
2129 ## A level-two heading
2131 ### A level-three heading ###
2133 As with setext-style headings, the heading text can contain formatting:
2135 # A level-one heading with a [link](/url) and *emphasis*
2137 Extension: blank_before_header
2139 Standard Markdown syntax does not require a blank line before a head‐
2140 ing. Pandoc does require this (except, of course, at the beginning of
2141 the document). The reason for the requirement is that it is all too
2142 easy for a # to end up at the beginning of a line by accident (perhaps
2143 through line wrapping). Consider, for example:
2144 I like several of their flavors of ice cream:
2146 #22, for example, and #5.
2147 Extension: space_in_atx_header
2149 Many Markdown implementations do not require a space between the open‐
2150 ing #s of an ATX heading and the heading text, so that #5 bolt and
2151 #hashtag count as headings. With this extension, pandoc does require
2152 the space.
2153 Heading identifiers
2155 See also the auto_identifiers extension above.
2156 Extension: header_attributes
2158 Headings can be assigned attributes using this syntax at the end of the
2159 line containing the heading text:
2160 {#identifier .class .class key=value key=value}
2162 Thus, for example, the following headings will all be assigned the
2164 identifier foo:
2165 # My heading {#foo}
2167 ## My heading ## {#foo}
2169 My other heading {#foo}
2171 ---------------
2172 (This syntax is compatible with PHP Markdown Extra.)
2174 Note that although this syntax allows assignment of classes and
2176 key/value attributes, writers generally don't use all of this informa‐
2177 tion. Identifiers, classes, and key/value attributes are used in HTML
2178 and HTML-based formats such as EPUB and slidy. Identifiers are used
2179 for labels and link anchors in the LaTeX, ConTeXt, Textile, Jira
2180 markup, and AsciiDoc writers.
2181 Headings with the class unnumbered will not be numbered, even if --num‐
2183 ber-sections is specified. A single hyphen (-) in an attribute context
2184 is equivalent to .unnumbered, and preferable in non-English documents.
2185 So,
2186 # My heading {-}
2188 is just the same as
2190 # My heading {.unnumbered}
2192 Extension: implicit_header_references
2194 Pandoc behaves as if reference links have been defined for each head‐
2195 ing. So, to link to a heading
2196 # Heading identifiers in HTML
2198 you can simply write
2200 [Heading identifiers in HTML]
2202 or
2204 [Heading identifiers in HTML][]
2206 or
2208 [the section on heading identifiers][heading identifiers in
2210 HTML]
2211 instead of giving the identifier explicitly:
2213 [Heading identifiers in HTML](#heading-identifiers-in-html)
2215 If there are multiple headings with identical text, the corresponding
2217 reference will link to the first one only, and you will need to use
2218 explicit links to link to the others, as described above.
2219 Like regular reference links, these references are case-insensitive.
2221 Explicit link reference definitions always take priority over implicit
2223 heading references. So, in the following example, the link will point
2224 to bar, not to #foo:
2225 # Foo
2227 [foo]: bar
2229 See [foo]
2231 Block quotations
2233 Markdown uses email conventions for quoting blocks of text. A block
2234 quotation is one or more paragraphs or other block elements (such as
2235 lists or headings), with each line preceded by a > character and an
2236 optional space. (The > need not start at the left margin, but it
2237 should not be indented more than three spaces.)
2238 > This is a block quote. This
2240 > paragraph has two lines.
2241 >
2242 > 1. This is a list inside a block quote.
2243 > 2. Second item.
2244 A "lazy" form, which requires the > character only on the first line of
2246 each block, is also allowed:
2247 > This is a block quote. This
2249 paragraph has two lines.
2250 > 1. This is a list inside a block quote.
2252 2. Second item.
2253 Among the block elements that can be contained in a block quote are
2255 other block quotes. That is, block quotes can be nested:
2256 > This is a block quote.
2258 >
2259 > > A block quote within a block quote.
2260 If the > character is followed by an optional space, that space will be
2262 considered part of the block quote marker and not part of the indenta‐
2263 tion of the contents. Thus, to put an indented code block in a block
2264 quote, you need five spaces after the >:
2265 > code
2267 Extension: blank_before_blockquote
2269 Standard Markdown syntax does not require a blank line before a block
2270 quote. Pandoc does require this (except, of course, at the beginning
2271 of the document). The reason for the requirement is that it is all too
2272 easy for a > to end up at the beginning of a line by accident (perhaps
2273 through line wrapping). So, unless the markdown_strict format is used,
2274 the following does not produce a nested block quote in pandoc:
2275 > This is a block quote.
2277 >> Nested.
2278 Verbatim (code) blocks
2280 Indented code blocks
2281 A block of text indented four spaces (or one tab) is treated as verba‐
2282 tim text: that is, special characters do not trigger special format‐
2283 ting, and all spaces and line breaks are preserved. For example,
2284 if (a > 3) {
2286 moveShip(5 * gravity, DOWN);
2287 }
2288 The initial (four space or one tab) indentation is not considered part
2290 of the verbatim text, and is removed in the output.
2291 Note: blank lines in the verbatim text need not begin with four spaces.
2293 Fenced code blocks
2295 Extension: fenced_code_blocks
2296 In addition to standard indented code blocks, pandoc supports fenced
2297 code blocks. These begin with a row of three or more tildes (~) and
2298 end with a row of tildes that must be at least as long as the starting
2299 row. Everything between these lines is treated as code. No indenta‐
2300 tion is necessary:
2301 ~~~~~~~
2303 if (a > 3) {
2304 moveShip(5 * gravity, DOWN);
2305 }
2306 ~~~~~~~
2307 Like regular code blocks, fenced code blocks must be separated from
2309 surrounding text by blank lines.
2310 If the code itself contains a row of tildes or backticks, just use a
2312 longer row of tildes or backticks at the start and end:
2313 ~~~~~~~~~~~~~~~~
2315 ~~~~~~~~~~
2316 code including tildes
2317 ~~~~~~~~~~
2318 ~~~~~~~~~~~~~~~~
2319 Extension: backtick_code_blocks
2321 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
2322 (~).
2323 Extension: fenced_code_attributes
2325 Optionally, you may attach attributes to fenced or backtick code block
2326 using this syntax:
2327 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
2329 qsort [] = []
2330 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
2331 qsort (filter (>= x) xs)
2332 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2333 Here mycode is an identifier, haskell and numberLines are classes, and
2335 startFrom is an attribute with value 100. Some output formats can use
2336 this information to do syntax highlighting. Currently, the only output
2337 formats that uses this information are HTML, LaTeX, Docx, Ms, and Pow‐
2338 erPoint. If highlighting is supported for your output format and lan‐
2339 guage, then the code block above will appear highlighted, with numbered
2340 lines. (To see which languages are supported, type pandoc --list-high‐
2341 light-languages.) Otherwise, the code block above will appear as fol‐
2342 lows:
2343 <pre id="mycode" class="haskell numberLines" startFrom="100">
2345 <code>
2346 ...
2347 </code>
2348 </pre>
2349 The numberLines (or number-lines) class will cause the lines of the
2351 code block to be numbered, starting with 1 or the value of the start‐
2352 From attribute. The lineAnchors (or line-anchors) class will cause the
2353 lines to be clickable anchors in HTML output.
2354 A shortcut form can also be used for specifying the language of the
2356 code block:
2357 ```haskell
2359 qsort [] = []
2360 ```
2361 This is equivalent to:
2363 ``` {.haskell}
2365 qsort [] = []
2366 ```
2367 If the fenced_code_attributes extension is disabled, but input contains
2369 class attribute(s) for the code block, the first class attribute will
2370 be printed after the opening fence as a bare word.
2371 To prevent all highlighting, use the --no-highlight flag. To set the
2373 highlighting style, use --highlight-style. For more information on
2374 highlighting, see Syntax highlighting, below.
2375 Line blocks
2377 Extension: line_blocks
2378 A line block is a sequence of lines beginning with a vertical bar (|)
2379 followed by a space. The division into lines will be preserved in the
2380 output, as will any leading spaces; otherwise, the lines will be for‐
2381 matted as Markdown. This is useful for verse and addresses:
2382 | The limerick packs laughs anatomical
2384 | In space that is quite economical.
2385 | But the good ones I've seen
2386 | So seldom are clean
2387 | And the clean ones so seldom are comical
2388 | 200 Main St.
2390 | Berkeley, CA 94718
2391 The lines can be hard-wrapped if needed, but the continuation line must
2393 begin with a space.
2394 | The Right Honorable Most Venerable and Righteous Samuel L.
2396 Constable, Jr.
2397 | 200 Main St.
2398 | Berkeley, CA 94718
2399 This syntax is borrowed from reStructuredText.
2401 Lists
2403 Bullet lists
2404 A bullet list is a list of bulleted list items. A bulleted list item
2405 begins with a bullet (*, +, or -). Here is a simple example:
2406 * one
2408 * two
2409 * three
2410 This will produce a "compact" list. If you want a "loose" list, in
2412 which each item is formatted as a paragraph, put spaces between the
2413 items:
2414 * one
2416 * two
2418 * three
2420 The bullets need not be flush with the left margin; they may be
2422 indented one, two, or three spaces. The bullet must be followed by
2423 whitespace.
2424 List items look best if subsequent lines are flush with the first line
2426 (after the bullet):
2427 * here is my first
2429 list item.
2430 * and my second.
2431 But Markdown also allows a "lazy" format:
2433 * here is my first
2435 list item.
2436 * and my second.
2437 Block content in list items
2439 A list item may contain multiple paragraphs and other block-level con‐
2440 tent. However, subsequent paragraphs must be preceded by a blank line
2441 and indented to line up with the first non-space content after the list
2442 marker.
2443 * First paragraph.
2445 Continued.
2447 * Second paragraph. With a code block, which must be indented
2449 eight spaces:
2450 { code }
2452 Exception: if the list marker is followed by an indented code block,
2454 which must begin 5 spaces after the list marker, then subsequent para‐
2455 graphs must begin two columns after the last character of the list
2456 marker:
2457 * code
2459 continuation paragraph
2461 List items may include other lists. In this case the preceding blank
2463 line is optional. The nested list must be indented to line up with the
2464 first non-space character after the list marker of the containing list
2465 item.
2466 * fruits
2468 + apples
2469 - macintosh
2470 - red delicious
2471 + pears
2472 + peaches
2473 * vegetables
2474 + broccoli
2475 + chard
2476 As noted above, Markdown allows you to write list items "lazily,"
2478 instead of indenting continuation lines. However, if there are multi‐
2479 ple paragraphs or other blocks in a list item, the first line of each
2480 must be indented.
2481 + A lazy, lazy, list
2483 item.
2484 + Another one; this looks
2486 bad but is legal.
2487 Second paragraph of second
2489 list item.
2490 Ordered lists
2492 Ordered lists work just like bulleted lists, except that the items
2493 begin with enumerators rather than bullets.
2494 In standard Markdown, enumerators are decimal numbers followed by a
2496 period and a space. The numbers themselves are ignored, so there is no
2497 difference between this list:
2498 1. one
2500 2. two
2501 3. three
2502 and this one:
2504 5. one
2506 7. two
2507 1. three
2508 Extension: fancy_lists
2510 Unlike standard Markdown, pandoc allows ordered list items to be marked
2511 with uppercase and lowercase letters and roman numerals, in addition to
2512 Arabic numerals. List markers may be enclosed in parentheses or fol‐
2513 lowed by a single right-parentheses or period. They must be separated
2514 from the text that follows by at least one space, and, if the list
2515 marker is a capital letter with a period, by at least two spaces.
2516 The fancy_lists extension also allows '#' to be used as an ordered list
2518 marker in place of a numeral:
2519 #. one
2521 #. two
2522 Extension: startnum
2524 Pandoc also pays attention to the type of list marker used, and to the
2525 starting number, and both of these are preserved where possible in the
2526 output format. Thus, the following yields a list with numbers followed
2527 by a single parenthesis, starting with 9, and a sublist with lowercase
2528 roman numerals:
2529 9) Ninth
2531 10) Tenth
2532 11) Eleventh
2533 i. subone
2534 ii. subtwo
2535 iii. subthree
2536 Pandoc will start a new list each time a different type of list marker
2538 is used. So, the following will create three lists:
2539 (2) Two
2541 (5) Three
2542 1. Four
2543 * Five
2544 If default list markers are desired, use #.:
2546 #. one
2548 #. two
2549 #. three
2550 Extension: task_lists
2552 Pandoc supports task lists, using the syntax of GitHub-Flavored Mark‐
2553 down.
2554 - [ ] an unchecked task list item
2556 - [x] checked item
2557 Definition lists
2559 Extension: definition_lists
2560 Pandoc supports definition lists, using the syntax of PHP Markdown
2561 Extra with some extensions.
2562 Term 1
2564 : Definition 1
2566 Term 2 with *inline markup*
2568 : Definition 2
2570 { some code, part of Definition 2 }
2572 Third paragraph of definition 2.
2574 Each term must fit on one line, which may optionally be followed by a
2576 blank line, and must be followed by one or more definitions. A defini‐
2577 tion begins with a colon or tilde, which may be indented one or two
2578 spaces.
2579 A term may have multiple definitions, and each definition may consist
2581 of one or more block elements (paragraph, code block, list, etc.), each
2582 indented four spaces or one tab stop. The body of the definition
2583 (including the first line, aside from the colon or tilde) should be
2584 indented four spaces. However, as with other Markdown lists, you can
2585 "lazily" omit indentation except at the beginning of a paragraph or
2586 other block element:
2587 Term 1
2589 : Definition
2591 with lazy continuation.
2592 Second paragraph of the definition.
2594 If you leave space before the definition (as in the example above), the
2596 text of the definition will be treated as a paragraph. In some output
2597 formats, this will mean greater spacing between term/definition pairs.
2598 For a more compact definition list, omit the space before the defini‐
2599 tion:
2600 Term 1
2602 ~ Definition 1
2603 Term 2
2605 ~ Definition 2a
2606 ~ Definition 2b
2607 Note that space between items in a definition list is required. (A
2609 variant that loosens this requirement, but disallows "lazy" hard wrap‐
2610 ping, can be activated with compact_definition_lists: see Non-pandoc
2611 extensions, below.)
2612 Numbered example lists
2614 Extension: example_lists
2615 The special list marker @ can be used for sequentially numbered exam‐
2616 ples. The first list item with a @ marker will be numbered '1', the
2617 next '2', and so on, throughout the document. The numbered examples
2618 need not occur in a single list; each new list using @ will take up
2619 where the last stopped. So, for example:
2620 (@) My first example will be numbered (1).
2622 (@) My second example will be numbered (2).
2623 Explanation of examples.
2625 (@) My third example will be numbered (3).
2627 Numbered examples can be labeled and referred to elsewhere in the docu‐
2629 ment:
2630 (@good) This is a good example.
2632 As (@good) illustrates, ...
2634 The label can be any string of alphanumeric characters, underscores, or
2636 hyphens.
2637 Note: continuation paragraphs in example lists must always be indented
2639 four spaces, regardless of the length of the list marker. That is,
2640 example lists always behave as if the four_space_rule extension is set.
2641 This is because example labels tend to be long, and indenting content
2642 to the first non-space character after the label would be awkward.
2643 Compact and loose lists
2645 Pandoc behaves differently from Markdown.pl on some "edge cases"
2646 involving lists. Consider this source:
2647 + First
2649 + Second:
2650 - Fee
2651 - Fie
2652 - Foe
2653 + Third
2655 Pandoc transforms this into a "compact list" (with no <p> tags around
2657 "First", "Second", or "Third"), while Markdown puts <p> tags around
2658 "Second" and "Third" (but not "First"), because of the blank space
2659 around "Third". Pandoc follows a simple rule: if the text is followed
2660 by a blank line, it is treated as a paragraph. Since "Second" is fol‐
2661 lowed by a list, and not a blank line, it isn't treated as a paragraph.
2662 The fact that the list is followed by a blank line is irrelevant.
2663 (Note: Pandoc works this way even when the markdown_strict format is
2664 specified. This behavior is consistent with the official Markdown syn‐
2665 tax description, even though it is different from that of Markdown.pl.)
2666 Ending a list
2668 What if you want to put an indented code block after a list?
2669 - item one
2671 - item two
2672 { my code block }
2674 Trouble! Here pandoc (like other Markdown implementations) will treat {
2676 my code block } as the second paragraph of item two, and not as a code
2677 block.
2678 To "cut off" the list after item two, you can insert some non-indented
2680 content, like an HTML comment, which won't produce visible output in
2681 any format:
2682 - item one
2684 - item two
2685 <!-- end of list -->
2687 { my code block }
2689 You can use the same trick if you want two consecutive lists instead of
2691 one big list:
2692 1. one
2694 2. two
2695 3. three
2696 <!-- -->
2698 1. uno
2700 2. dos
2701 3. tres
2702 Horizontal rules
2704 A line containing a row of three or more *, -, or _ characters (option‐
2705 ally separated by spaces) produces a horizontal rule:
2706 * * * *
2708 ---------------
2710 Tables
2712 Four kinds of tables may be used. The first three kinds presuppose the
2713 use of a fixed-width font, such as Courier. The fourth kind can be
2714 used with proportionally spaced fonts, as it does not require lining up
2715 columns.
2716 Extension: table_captions
2718 A caption may optionally be provided with all 4 kinds of tables (as
2719 illustrated in the examples below). A caption is a paragraph beginning
2720 with the string Table: (or just :), which will be stripped off. It may
2721 appear either before or after the table.
2722 Extension: simple_tables
2724 Simple tables look like this:
2725 Right Left Center Default
2727 ------- ------ ---------- -------
2728 12 12 12 12
2729 123 123 123 123
2730 1 1 1 1
2731 Table: Demonstration of simple table syntax.
2733 The header and table rows must each fit on one line. Column alignments
2735 are determined by the position of the header text relative to the
2736 dashed line below it:
2737 · If the dashed line is flush with the header text on the right side
2739 but extends beyond it on the left, the column is right-aligned.
2740 · If the dashed line is flush with the header text on the left side but
2742 extends beyond it on the right, the column is left-aligned.
2743 · If the dashed line extends beyond the header text on both sides, the
2745 column is centered.
2746 · If the dashed line is flush with the header text on both sides, the
2748 default alignment is used (in most cases, this will be left).
2749 The table must end with a blank line, or a line of dashes followed by a
2751 blank line.
2752 The column header row may be omitted, provided a dashed line is used to
2754 end the table. For example:
2755 ------- ------ ---------- -------
2757 12 12 12 12
2758 123 123 123 123
2759 1 1 1 1
2760 ------- ------ ---------- -------
2761 When the header row is omitted, column alignments are determined on the
2763 basis of the first line of the table body. So, in the tables above,
2764 the columns would be right, left, center, and right aligned, respec‐
2765 tively.
2766 Extension: multiline_tables
2768 Multiline tables allow header and table rows to span multiple lines of
2769 text (but cells that span multiple columns or rows of the table are not
2770 supported). Here is an example:
2771 -------------------------------------------------------------
2773 Centered Default Right Left
2774 Header Aligned Aligned Aligned
2775 ----------- ------- --------------- -------------------------
2776 First row 12.0 Example of a row that
2777 spans multiple lines.
2778 Second row 5.0 Here's another one. Note
2780 the blank line between
2781 rows.
2782 -------------------------------------------------------------
2783 Table: Here's the caption. It, too, may span
2785 multiple lines.
2786 These work like simple tables, but with the following differences:
2788 · They must begin with a row of dashes, before the header text (unless
2790 the header row is omitted).
2791 · They must end with a row of dashes, then a blank line.
2793 · The rows must be separated by blank lines.
2795 In multiline tables, the table parser pays attention to the widths of
2797 the columns, and the writers try to reproduce these relative widths in
2798 the output. So, if you find that one of the columns is too narrow in
2799 the output, try widening it in the Markdown source.
2800 The header may be omitted in multiline tables as well as simple tables:
2802 ----------- ------- --------------- -------------------------
2804 First row 12.0 Example of a row that
2805 spans multiple lines.
2806 Second row 5.0 Here's another one. Note
2808 the blank line between
2809 rows.
2810 ----------- ------- --------------- -------------------------
2811 : Here's a multiline table without a header.
2813 It is possible for a multiline table to have just one row, but the row
2815 should be followed by a blank line (and then the row of dashes that
2816 ends the table), or the table may be interpreted as a simple table.
2817 Extension: grid_tables
2819 Grid tables look like this:
2820 : Sample grid table.
2822 +---------------+---------------+--------------------+
2824 | Fruit | Price | Advantages |
2825 +===============+===============+====================+
2826 | Bananas | $1.34 | - built-in wrapper |
2827 | | | - bright color |
2828 +---------------+---------------+--------------------+
2829 | Oranges | $2.10 | - cures scurvy |
2830 | | | - tasty |
2831 +---------------+---------------+--------------------+
2832 The row of =s separates the header from the table body, and can be
2834 omitted for a headerless table. The cells of grid tables may contain
2835 arbitrary block elements (multiple paragraphs, code blocks, lists,
2836 etc.). Cells that span multiple columns or rows are not supported.
2837 Grid tables can be created easily using Emacs table mode.
2838 Alignments can be specified as with pipe tables, by putting colons at
2840 the boundaries of the separator line after the header:
2841 +---------------+---------------+--------------------+
2843 | Right | Left | Centered |
2844 +==============:+:==============+:==================:+
2845 | Bananas | $1.34 | built-in wrapper |
2846 +---------------+---------------+--------------------+
2847 For headerless tables, the colons go on the top line instead:
2849 +--------------:+:--------------+:------------------:+
2851 | Right | Left | Centered |
2852 +---------------+---------------+--------------------+
2853 Grid Table Limitations
2855 Pandoc does not support grid tables with row spans or column spans.
2856 This means that neither variable numbers of columns across rows nor
2857 variable numbers of rows across columns are supported by Pandoc. All
2858 grid tables must have the same number of columns in each row, and the
2859 same number of rows in each column. For example, the Docutils sample
2860 grid tables will not render as expected with Pandoc.
2861 Extension: pipe_tables
2863 Pipe tables look like this:
2864 | Right | Left | Default | Center |
2866 |------:|:-----|---------|:------:|
2867 | 12 | 12 | 12 | 12 |
2868 | 123 | 123 | 123 | 123 |
2869 | 1 | 1 | 1 | 1 |
2870 : Demonstration of pipe table syntax.
2872 The syntax is identical to PHP Markdown Extra tables. The beginning
2874 and ending pipe characters are optional, but pipes are required between
2875 all columns. The colons indicate column alignment as shown. The
2876 header cannot be omitted. To simulate a headerless table, include a
2877 header with blank cells.
2878 Since the pipes indicate column boundaries, columns need not be verti‐
2880 cally aligned, as they are in the above example. So, this is a per‐
2881 fectly legal (though ugly) pipe table:
2882 fruit| price
2884 -----|-----:
2885 apple|2.05
2886 pear|1.37
2887 orange|3.09
2888 The cells of pipe tables cannot contain block elements like paragraphs
2890 and lists, and cannot span multiple lines. If a pipe table contains a
2891 row whose printable content is wider than the column width (see --col‐
2892 umns), then the table will take up the full text width and the cell
2893 contents will wrap, with the relative cell widths determined by the
2894 number of dashes in the line separating the table header from the table
2895 body. (For example ---|- would make the first column 3/4 and the sec‐
2896 ond column 1/4 of the full text width.) On the other hand, if no lines
2897 are wider than column width, then cell contents will not be wrapped,
2898 and the cells will be sized to their contents.
2899 Note: pandoc also recognizes pipe tables of the following form, as can
2901 be produced by Emacs' orgtbl-mode:
2902 | One | Two |
2904 |-----+-------|
2905 | my | table |
2906 | is | nice |
2907 The difference is that + is used instead of |. Other orgtbl features
2909 are not supported. In particular, to get non-default column alignment,
2910 you'll need to add colons as above.
2911 Metadata blocks
2913 Extension: pandoc_title_block
2914 If the file begins with a title block
2915 % title
2917 % author(s) (separated by semicolons)
2918 % date
2919 it will be parsed as bibliographic information, not regular text. (It
2921 will be used, for example, in the title of standalone LaTeX or HTML
2922 output.) The block may contain just a title, a title and an author, or
2923 all three elements. If you want to include an author but no title, or
2924 a title and a date but no author, you need a blank line:
2925 %
2927 % Author
2928 % My title
2930 %
2931 % June 15, 2006
2932 The title may occupy multiple lines, but continuation lines must begin
2934 with leading space, thus:
2935 % My title
2937 on multiple lines
2938 If a document has multiple authors, the authors may be put on separate
2940 lines with leading space, or separated by semicolons, or both. So, all
2941 of the following are equivalent:
2942 % Author One
2944 Author Two
2945 % Author One; Author Two
2947 % Author One;
2949 Author Two
2950 The date must fit on one line.
2952 All three metadata fields may contain standard inline formatting (ital‐
2954 ics, links, footnotes, etc.).
2955 Title blocks will always be parsed, but they will affect the output
2957 only when the --standalone (-s) option is chosen. In HTML output,
2958 titles will appear twice: once in the document head -- this is the
2959 title that will appear at the top of the window in a browser -- and
2960 once at the beginning of the document body. The title in the document
2961 head can have an optional prefix attached (--title-prefix or -T
2962 option). The title in the body appears as an H1 element with class
2963 "title", so it can be suppressed or reformatted with CSS. If a title
2964 prefix is specified with -T and no title block appears in the document,
2965 the title prefix will be used by itself as the HTML title.
2966 The man page writer extracts a title, man page section number, and
2968 other header and footer information from the title line. The title is
2969 assumed to be the first word on the title line, which may optionally
2970 end with a (single-digit) section number in parentheses. (There should
2971 be no space between the title and the parentheses.) Anything after
2972 this is assumed to be additional footer and header text. A single pipe
2973 character (|) should be used to separate the footer text from the
2974 header text. Thus,
2975 % PANDOC(1)
2977 will yield a man page with the title PANDOC and section 1.
2979 % PANDOC(1) Pandoc User Manuals
2981 will also have "Pandoc User Manuals" in the footer.
2983 % PANDOC(1) Pandoc User Manuals | Version 4.0
2985 will also have "Version 4.0" in the header.
2987 Extension: yaml_metadata_block
2989 A YAML metadata block is a valid YAML object, delimited by a line of
2990 three hyphens (---) at the top and a line of three hyphens (---) or
2991 three dots (...) at the bottom. A YAML metadata block may occur any‐
2992 where in the document, but if it is not at the beginning, it must be
2993 preceded by a blank line. (Note that, because of the way pandoc con‐
2994 catenates input files when several are provided, you may also keep the
2995 metadata in a separate YAML file and pass it to pandoc as an argument,
2996 along with your Markdown files:
2997 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
2999 Just be sure that the YAML file begins with --- and ends with --- or
3001 ....) Alternatively, you can use the --metadata-file option. Using
3002 that approach however, you cannot reference content (like footnotes)
3003 from the main markdown input document.
3004 Metadata will be taken from the fields of the YAML object and added to
3006 any existing document metadata. Metadata can contain lists and objects
3007 (nested arbitrarily), but all string scalars will be interpreted as
3008 Markdown. Fields with names ending in an underscore will be ignored by
3009 pandoc. (They may be given a role by external processors.) Field names
3010 must not be interpretable as YAML numbers or boolean values (so, for
3011 example, yes, True, and 15 cannot be used as field names).
3012 A document may contain multiple metadata blocks. The metadata fields
3014 will be combined through a left-biased union: if two metadata blocks
3015 attempt to set the same field, the value from the first block will be
3016 taken.
3017 When pandoc is used with -t markdown to create a Markdown document, a
3019 YAML metadata block will be produced only if the -s/--standalone option
3020 is used. All of the metadata will appear in a single block at the
3021 beginning of the document.
3022 Note that YAML escaping rules must be followed. Thus, for example, if
3024 a title contains a colon, it must be quoted. The pipe character (|)
3025 can be used to begin an indented block that will be interpreted liter‐
3026 ally, without need for escaping. This form is necessary when the field
3027 contains blank lines or block-level formatting:
3028 ---
3030 title: 'This is the title: it contains a colon'
3031 author:
3032 - Author One
3033 - Author Two
3034 keywords: [nothing, nothingness]
3035 abstract: |
3036 This is the abstract.
3037 It consists of two paragraphs.
3039 ...
3040 Template variables will be set automatically from the metadata. Thus,
3042 for example, in writing HTML, the variable abstract will be set to the
3043 HTML equivalent of the Markdown in the abstract field:
3044 <p>This is the abstract.</p>
3046 <p>It consists of two paragraphs.</p>
3047 Variables can contain arbitrary YAML structures, but the template must
3049 match this structure. The author variable in the default templates
3050 expects a simple list or string, but can be changed to support more
3051 complicated structures. The following combination, for example, would
3052 add an affiliation to the author if one is given:
3053 ---
3055 title: The document title
3056 author:
3057 - name: Author One
3058 affiliation: University of Somewhere
3059 - name: Author Two
3060 affiliation: University of Nowhere
3061 ...
3062 To use the structured authors in the example above, you would need a
3064 custom template:
3065 $for(author)$
3067 $if(author.name)$
3068 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
3069 $else$
3070 $author$
3071 $endif$
3072 $endfor$
3073 Raw content to include in the document's header may be specified using
3075 header-includes; however, it is important to mark up this content as
3076 raw code for a particular output format, using the raw_attribute exten‐
3077 sion), or it will be interpreted as markdown. For example:
3078 header-includes:
3080 - |
3081 ```{=latex}
3082 \let\oldsection\section
3083 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
3084 ```
3085 Backslash escapes
3087 Extension: all_symbols_escapable
3088 Except inside a code block or inline code, any punctuation or space
3089 character preceded by a backslash will be treated literally, even if it
3090 would normally indicate formatting. Thus, for example, if one writes
3091 *\*hello\**
3093 one will get
3095 <em>*hello*</em>
3097 instead of
3099 <strong>hello</strong>
3101 This rule is easier to remember than standard Markdown's rule, which
3103 allows only the following characters to be backslash-escaped:
3104 \`*_{}[]()>#+-.!
3106 (However, if the markdown_strict format is used, the standard Markdown
3108 rule will be used.)
3109 A backslash-escaped space is parsed as a nonbreaking space. It will
3111 appear in TeX output as ~ and in HTML and XML as \  or \ .
3112 A backslash-escaped newline (i.e. a backslash occurring at the end of
3114 a line) is parsed as a hard line break. It will appear in TeX output
3115 as \\ and in HTML as <br />. This is a nice alternative to Markdown's
3116 "invisible" way of indicating hard line breaks using two trailing spa‐
3117 ces on a line.
3118 Backslash escapes do not work in verbatim contexts.
3120 Inline formatting
3122 Emphasis
3123 To emphasize some text, surround it with *s or _, like this:
3124 This text is _emphasized with underscores_, and this
3126 is *emphasized with asterisks*.
3127 Double * or _ produces strong emphasis:
3129 This is **strong emphasis** and __with underscores__.
3131 A * or _ character surrounded by spaces, or backslash-escaped, will not
3133 trigger emphasis:
3134 This is * not emphasized *, and \*neither is this\*.
3136 Extension: intraword_underscores
3138 Because _ is sometimes used inside words and identifiers, pandoc does
3139 not interpret a _ surrounded by alphanumeric characters as an emphasis
3140 marker. If you want to emphasize just part of a word, use *:
3141 feas*ible*, not feas*able*.
3143 Strikeout
3145 Extension: strikeout
3146 To strikeout a section of text with a horizontal line, begin and end it
3147 with ~~. Thus, for example,
3148 This ~~is deleted text.~~
3150 Superscripts and subscripts
3152 Extension: superscript, subscript
3153 Superscripts may be written by surrounding the superscripted text by ^
3154 characters; subscripts may be written by surrounding the subscripted
3155 text by ~ characters. Thus, for example,
3156 H~2~O is a liquid. 2^10^ is 1024.
3158 If the superscripted or subscripted text contains spaces, these spaces
3160 must be escaped with backslashes. (This is to prevent accidental
3161 superscripting and subscripting through the ordinary use of ~ and ^.)
3162 Thus, if you want the letter P with 'a cat' in subscripts, use P~a\
3163 cat~, not P~a cat~.
3164 Verbatim
3166 To make a short span of text verbatim, put it inside backticks:
3167 What is the difference between `>>=` and `>>`?
3169 If the verbatim text includes a backtick, use double backticks:
3171 Here is a literal backtick `` ` ``.
3173 (The spaces after the opening backticks and before the closing back‐
3175 ticks will be ignored.)
3176 The general rule is that a verbatim span starts with a string of con‐
3178 secutive backticks (optionally followed by a space) and ends with a
3179 string of the same number of backticks (optionally preceded by a
3180 space).
3181 Note that backslash-escapes (and other Markdown constructs) do not work
3183 in verbatim contexts:
3184 This is a backslash followed by an asterisk: `\*`.
3186 Extension: inline_code_attributes
3188 Attributes can be attached to verbatim text, just as with fenced code
3189 blocks:
3190 `<$>`{.haskell}
3192 Small caps
3194 To write small caps, use the smallcaps class:
3195 [Small caps]{.smallcaps}
3197 Or, without the bracketed_spans extension:
3199 <span class="smallcaps">Small caps</span>
3201 For compatibility with other Markdown flavors, CSS is also supported:
3203 <span style="font-variant:small-caps;">Small caps</span>
3205 This will work in all output formats that support small caps.
3207 Math
3209 Extension: tex_math_dollars
3210 Anything between two $ characters will be treated as TeX math. The
3211 opening $ must have a non-space character immediately to its right,
3212 while the closing $ must have a non-space character immediately to its
3213 left, and must not be followed immediately by a digit. Thus, $20,000
3214 and $30,000 won't parse as math. If for some reason you need to
3215 enclose text in literal $ characters, backslash-escape them and they
3216 won't be treated as math delimiters.
3217 TeX math will be printed in all output formats. How it is rendered
3219 depends on the output format:
3220 LaTeX It will appear verbatim surrounded by \(...\) (for inline math)
3222 or \[...\] (for display math).
3223 Markdown, Emacs Org mode, ConTeXt, ZimWiki
3225 It will appear verbatim surrounded by $...$ (for inline math) or
3226 $$...$$ (for display math).
3227 XWiki It will appear verbatim surrounded by {{formula}}..{{/formula}}.
3229 reStructuredText
3231 It will be rendered using an interpreted text role :math:.
3232 AsciiDoc
3234 For AsciiDoc output format (-t asciidoc) it will appear verbatim
3235 surrounded by latexmath:[$...$] (for inline math) or [latex‐
3236 math]++++\[...\]+++ (for display math). For AsciiDoctor output
3237 format (-t asciidoctor) the LaTex delimiters ($..$ and \[..\])
3238 are omitted.
3239 Texinfo
3241 It will be rendered inside a @math command.
3242 roff man, Jira markup
3244 It will be rendered verbatim without $'s.
3245 MediaWiki, DokuWiki
3247 It will be rendered inside <math> tags.
3248 Textile
3250 It will be rendered inside <span class="math"> tags.
3251 RTF, OpenDocument
3253 It will be rendered, if possible, using Unicode characters, and
3254 will otherwise appear verbatim.
3255 ODT It will be rendered, if possible, using MathML.
3257 DocBook
3259 If the --mathml flag is used, it will be rendered using MathML
3260 in an inlineequation or informalequation tag. Otherwise it will
3261 be rendered, if possible, using Unicode characters.
3262 Docx It will be rendered using OMML math markup.
3264 FictionBook2
3266 If the --webtex option is used, formulas are rendered as images
3267 using CodeCogs or other compatible web service, downloaded and
3268 embedded in the e-book. Otherwise, they will appear verbatim.
3269 HTML, Slidy, DZSlides, S5, EPUB
3271 The way math is rendered in HTML will depend on the command-line
3272 options selected. Therefore see Math rendering in HTML above.
3273 Raw HTML
3275 Extension: raw_html
3276 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
3277 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
3278 erally). (Technically this is not an extension, since standard Mark‐
3279 down allows it, but it has been made an extension so that it can be
3280 disabled if desired.)
3281 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
3283 DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile out‐
3284 put, and suppressed in other formats.
3285 For a more explicit way of including raw HTML in a Markdown document,
3287 see the raw_attribute extension.
3288 In the CommonMark format, if raw_html is enabled, superscripts, sub‐
3290 scripts, strikeouts and small capitals will be represented as HTML.
3291 Otherwise, plain-text fallbacks will be used. Note that even if
3292 raw_html is disabled, tables will be rendered with HTML syntax if they
3293 cannot use pipe syntax.
3294 Extension: markdown_in_html_blocks
3296 Standard Markdown allows you to include HTML "blocks": blocks of HTML
3297 between balanced tags that are separated from the surrounding text with
3298 blank lines, and start and end at the left margin. Within these
3299 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
3300 ple), * does not signify emphasis.
3301 Pandoc behaves this way when the markdown_strict format is used; but by
3303 default, pandoc interprets material between HTML block tags as Mark‐
3304 down. Thus, for example, pandoc will turn
3305 <table>
3307 <tr>
3308 <td>*one*</td>
3309 <td>[a link](http://google.com)</td>
3310 </tr>
3311 </table>
3312 into
3314 <table>
3316 <tr>
3317 <td><em>one</em></td>
3318 <td><a href="http://google.com">a link</a></td>
3319 </tr>
3320 </table>
3321 whereas Markdown.pl will preserve it as is.
3323 There is one exception to this rule: text between <script> and <style>
3325 tags is not interpreted as Markdown.
3326 This departure from standard Markdown should make it easier to mix
3328 Markdown with HTML block elements. For example, one can surround a
3329 block of Markdown text with <div> tags without preventing it from being
3330 interpreted as Markdown.
3331 Extension: native_divs
3333 Use native pandoc Div blocks for content inside <div> tags. For the
3334 most part this should give the same output as markdown_in_html_blocks,
3335 but it makes it easier to write pandoc filters to manipulate groups of
3336 blocks.
3337 Extension: native_spans
3339 Use native pandoc Span blocks for content inside <span> tags. For the
3340 most part this should give the same output as raw_html, but it makes it
3341 easier to write pandoc filters to manipulate groups of inlines.
3342 Extension: raw_tex
3344 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
3345 be included in a document. Inline TeX commands will be preserved and
3346 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
3347 you can use LaTeX to include BibTeX citations:
3348 This result was proved in \cite{jones.1967}.
3350 Note that in LaTeX environments, like
3352 \begin{tabular}{|l|l|}\hline
3354 Age & Frequency \\ \hline
3355 18--25 & 15 \\
3356 26--35 & 33 \\
3357 36--45 & 22 \\ \hline
3358 \end{tabular}
3359 the material between the begin and end tags will be interpreted as raw
3361 LaTeX, not as Markdown.
3362 For a more explicit and flexible way of including raw TeX in a Markdown
3364 document, see the raw_attribute extension.
3365 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
3367 Emacs Org mode, and ConTeXt.
3368 Generic raw attribute
3370 Extension: raw_attribute
3371 Inline spans and fenced code blocks with a special kind of attribute
3372 will be parsed as raw content with the designated format. For example,
3373 the following produces a raw roff ms block:
3374 ```{=ms}
3376 .MYMACRO
3377 blah blah
3378 ```
3379 And the following produces a raw html inline element:
3381 This is `<a>html</a>`{=html}
3383 This can be useful to insert raw xml into docx documents, e.g. a page‐
3385 break:
3386 ```{=openxml}
3388 <w:p>
3389 <w:r>
3390 <w:br w:type="page"/>
3391 </w:r>
3392 </w:p>
3393 ```
3394 The format name should match the target format name (see -t/--to,
3396 above, for a list, or use pandoc --list-output-formats). Use openxml
3397 for docx output, opendocument for odt output, html5 for epub3 output,
3398 html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output
3399 (depending on what you use for --pdf-engine).
3400 This extension presupposes that the relevant kind of inline code or
3402 fenced code block is enabled. Thus, for example, to use a raw
3403 attribute with a backtick code block, backtick_code_blocks must be
3404 enabled.
3405 The raw attribute cannot be combined with regular attributes.
3407 LaTeX macros
3409 Extension: latex_macros
3410 When this extension is enabled, pandoc will parse LaTeX macro defini‐
3411 tions and apply the resulting macros to all LaTeX math and raw LaTeX.
3412 So, for example, the following will work in all output formats, not
3413 just LaTeX:
3414 \newcommand{\tuple}[1]{\langle #1 \rangle}
3416 $\tuple{a, b, c}$
3418 Note that LaTeX macros will not be applied if they occur inside a raw
3420 span or block marked with the raw_attribute extension.
3421 When latex_macros is disabled, the raw LaTeX and math will not have
3423 macros applied. This is usually a better approach when you are target‐
3424 ing LaTeX or PDF.
3425 Whether or not latex_macros is enabled, the macro definitions will
3427 still be passed through as raw LaTeX.
3428 Links
3430 Markdown allows links to be specified in several ways.
3431 Automatic links
3433 If you enclose a URL or email address in pointy brackets, it will
3434 become a link:
3435 <http://google.com>
3437 <sam@green.eggs.ham>
3438 Inline links
3440 An inline link consists of the link text in square brackets, followed
3441 by the URL in parentheses. (Optionally, the URL can be followed by a
3442 link title, in quotes.)
3443 This is an [inline link](/url), and here's [one with
3445 a title](http://fsf.org "click here for a good time!").
3446 There can be no space between the bracketed part and the parenthesized
3448 part. The link text can contain formatting (such as emphasis), but the
3449 title cannot.
3450 Email addresses in inline links are not autodetected, so they have to
3452 be prefixed with mailto:
3453 [Write me!](mailto:sam@green.eggs.ham)
3455 Reference links
3457 An explicit reference link has two parts, the link itself and the link
3458 definition, which may occur elsewhere in the document (either before or
3459 after the link).
3460 The link consists of link text in square brackets, followed by a label
3462 in square brackets. (There cannot be space between the two unless the
3463 spaced_reference_links extension is enabled.) The link definition con‐
3464 sists of the bracketed label, followed by a colon and a space, followed
3465 by the URL, and optionally (after a space) a link title either in
3466 quotes or in parentheses. The label must not be parseable as a cita‐
3467 tion (assuming the citations extension is enabled): citations take
3468 precedence over link labels.
3469 Here are some examples:
3471 [my label 1]: /foo/bar.html "My title, optional"
3473 [my label 2]: /foo
3474 [my label 3]: http://fsf.org (The free software foundation)
3475 [my label 4]: /bar#special 'A title in single quotes'
3476 The URL may optionally be surrounded by angle brackets:
3478 [my label 5]: <http://foo.bar.baz>
3480 The title may go on the next line:
3482 [my label 3]: http://fsf.org
3484 "The free software foundation"
3485 Note that link labels are not case sensitive. So, this will work:
3487 Here is [my link][FOO]
3489 [Foo]: /bar/baz
3491 In an implicit reference link, the second pair of brackets is empty:
3493 See [my website][].
3495 [my website]: http://foo.bar.baz
3497 Note: In Markdown.pl and most other Markdown implementations, reference
3499 link definitions cannot occur in nested constructions such as list
3500 items or block quotes. Pandoc lifts this arbitrary seeming restric‐
3501 tion. So the following is fine in pandoc, though not in most other
3502 implementations:
3503 > My block [quote].
3505 >
3506 > [quote]: /foo
3507 Extension: shortcut_reference_links
3509 In a shortcut reference link, the second pair of brackets may be omit‐
3510 ted entirely:
3511 See [my website].
3513 [my website]: http://foo.bar.baz
3515 Internal links
3517 To link to another section of the same document, use the automatically
3518 generated identifier (see Heading identifiers). For example:
3519 See the [Introduction](#introduction).
3521 or
3523 See the [Introduction].
3525 [Introduction]: #introduction
3527 Internal links are currently supported for HTML formats (including HTML
3529 slide shows and EPUB), LaTeX, and ConTeXt.
3530 Images
3532 A link immediately preceded by a ! will be treated as an image. The
3533 link text will be used as the image's alt text:
3534 
3536 ![movie reel]
3538 [movie reel]: movie.gif
3540 Extension: implicit_figures
3542 An image with nonempty alt text, occurring by itself in a paragraph,
3543 will be rendered as a figure with a caption. The image's alt text will
3544 be used as the caption.
3545 
3547 How this is rendered depends on the output format. Some output formats
3549 (e.g. RTF) do not yet support figures. In those formats, you'll just
3550 get an image in a paragraph by itself, with no caption.
3551 If you just want a regular inline image, just make sure it is not the
3553 only thing in the paragraph. One way to do this is to insert a non‐
3554 breaking space after the image:
3555 \
3557 Note that in reveal.js slide shows, an image in a paragraph by itself
3559 that has the stretch class will fill the screen, and the caption and
3560 figure tags will be omitted.
3561 Extension: link_attributes
3563 Attributes can be set on links and images:
3564 An inline {#id .class width=30 height=20px}
3566 and a reference ![image][ref] with attributes.
3567 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
3569 (This syntax is compatible with PHP Markdown Extra when only #id and
3571 .class are used.)
3572 For HTML and EPUB, all attributes except width and height (but includ‐
3574 ing srcset and sizes) are passed through as is. The other writers
3575 ignore attributes that are not supported by their output format.
3576 The width and height attributes on images are treated specially. When
3578 used without a unit, the unit is assumed to be pixels. However, any of
3579 the following unit identifiers can be used: px, cm, mm, in, inch and %.
3580 There must not be any spaces between the number and the unit. For
3581 example:
3582 { width=50% }
3584 · Dimensions are converted to inches for output in page-based formats
3586 like LaTeX. Dimensions are converted to pixels for output in HTML-
3587 like formats. Use the --dpi option to specify the number of pixels
3588 per inch. The default is 96dpi.
3589 · The % unit is generally relative to some available space. For exam‐
3591 ple the above example will render to the following.
3592 · HTML: <img href="file.jpg" style="width: 50%;" />
3594 · LaTeX: \includegraphics[width=0.5\textwidth,height=\tex‐
3596 theight]{file.jpg} (If you're using a custom template, you need to
3597 configure graphicx as in the default template.)
3598 · ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
3600 · Some output formats have a notion of a class (ConTeXt) or a unique
3602 identifier (LaTeX \caption), or both (HTML).
3603 · When no width or height attributes are specified, the fallback is to
3605 look at the image resolution and the dpi metadata embedded in the
3606 image file.
3607 Divs and Spans
3609 Using the native_divs and native_spans extensions (see above), HTML
3610 syntax can be used as part of markdown to create native Div and Span
3611 elements in the pandoc AST (as opposed to raw HTML). However, there is
3612 also nicer syntax available:
3613 Extension: fenced_divs
3615 Allow special fenced syntax for native Div blocks. A Div starts with a
3616 fence containing at least three consecutive colons plus some
3617 attributes. The attributes may optionally be followed by another
3618 string of consecutive colons. The attribute syntax is exactly as in
3619 fenced code blocks (see Extension: fenced_code_attributes). As with
3620 fenced code blocks, one can use either attributes in curly braces or a
3621 single unbraced word, which will be treated as a class name. The Div
3622 ends with another line containing a string of at least three consecu‐
3623 tive colons. The fenced Div should be separated by blank lines from
3624 preceding and following blocks.
3625 Example:
3627 ::::: {#special .sidebar}
3629 Here is a paragraph.
3630 And another.
3632 :::::
3633 Fenced divs can be nested. Opening fences are distinguished because
3635 they must have attributes:
3636 ::: Warning ::::::
3638 This is a warning.
3639 ::: Danger
3641 This is a warning within a warning.
3642 :::
3643 ::::::::::::::::::
3644 Fences without attributes are always closing fences. Unlike with
3646 fenced code blocks, the number of colons in the closing fence need not
3647 match the number in the opening fence. However, it can be helpful for
3648 visual clarity to use fences of different lengths to distinguish nested
3649 divs from their parents.
3650 Extension: bracketed_spans
3652 A bracketed sequence of inlines, as one would use to begin a link, will
3653 be treated as a Span with attributes if it is followed immediately by
3654 attributes:
3655 [This is *some text*]{.class key="val"}
3657 Footnotes
3659 Extension: footnotes
3660 Pandoc's Markdown allows footnotes, using the following syntax:
3661 Here is a footnote reference,[^1] and another.[^longnote]
3663 [^1]: Here is the footnote.
3665 [^longnote]: Here's one with multiple blocks.
3667 Subsequent paragraphs are indented to show that they
3669 belong to the previous footnote.
3670 { some.code }
3672 The whole paragraph can be indented, or just the first
3674 line. In this way, multi-paragraph footnotes work like
3675 multi-paragraph list items.
3676 This paragraph won't be part of the note, because it
3678 isn't indented.
3679 The identifiers in footnote references may not contain spaces, tabs, or
3681 newlines. These identifiers are used only to correlate the footnote
3682 reference with the note itself; in the output, footnotes will be num‐
3683 bered sequentially.
3684 The footnotes themselves need not be placed at the end of the document.
3686 They may appear anywhere except inside other block elements (lists,
3687 block quotes, tables, etc.). Each footnote should be separated from
3688 surrounding content (including other footnotes) by blank lines.
3689 Extension: inline_notes
3691 Inline footnotes are also allowed (though, unlike regular notes, they
3692 cannot contain multiple paragraphs). The syntax is as follows:
3693 Here is an inline note.^[Inlines notes are easier to write, since
3695 you don't have to pick an identifier and move down to type the
3696 note.]
3697 Inline and regular footnotes may be mixed freely.
3699 Citations
3701 Extension: citations
3702 Using an external filter, pandoc-citeproc, pandoc can automatically
3703 generate citations and a bibliography in a number of styles. Basic
3704 usage is
3705 pandoc --filter pandoc-citeproc myinput.txt
3707 In order to use this feature, you will need to specify a bibliography
3709 file using the bibliography metadata field in a YAML metadata section,
3710 or --bibliography command line argument. You can supply multiple
3711 --bibliography arguments or set bibliography metadata field to YAML
3712 array, if you want to use multiple bibliography files. The bibliogra‐
3713 phy may have any of these formats:
3714 Format File extension
3716 ─────────────────────────────
3717 BibLaTeX .bib
3718 BibTeX .bibtex
3719 Copac .copac
3720 CSL JSON .json
3721 CSL YAML .yaml
3722 EndNote .enl
3723 EndNote XML .xml
3724 ISI .wos
3725 MEDLINE .medline
3726 MODS .mods
3727 RIS .ris
3728 Note that .bib can be used with both BibTeX and BibLaTeX files; use
3730 .bibtex to force BibTeX.
3731 Note that pandoc-citeproc --bib2json and pandoc-citeproc --bib2yaml can
3733 produce .json and .yaml files from any of the supported formats.
3734 In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
3736 parses a subset of LaTeX markup; in CSL YAML databases, pandoc Mark‐
3737 down; and in CSL JSON databases, an HTML-like markup:
3738 <i>...</i>
3740 italics
3741 <b>...</b>
3743 bold
3744 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
3746 small capitals
3747 <sub>...</sub>
3749 subscript
3750 <sup>...</sup>
3752 superscript
3753 <span class="nocase">...</span>
3755 prevent a phrase from being capitalized as title case
3756 pandoc-citeproc -j and -y interconvert the CSL JSON and CSL YAML for‐
3758 mats as far as possible.
3759 As an alternative to specifying a bibliography file using --bibliogra‐
3761 phy or the YAML metadata field bibliography, you can include the cita‐
3762 tion data directly in the references field of the document's YAML meta‐
3763 data. The field should contain an array of YAML-encoded references,
3764 for example:
3765 ---
3767 references:
3768 - type: article-journal
3769 id: WatsonCrick1953
3770 author:
3771 - family: Watson
3772 given: J. D.
3773 - family: Crick
3774 given: F. H. C.
3775 issued:
3776 date-parts:
3777 - - 1953
3778 - 4
3779 - 25
3780 title: 'Molecular structure of nucleic acids: a structure for deoxyribose
3781 nucleic acid'
3782 title-short: Molecular structure of nucleic acids
3783 container-title: Nature
3784 volume: 171
3785 issue: 4356
3786 page: 737-738
3787 DOI: 10.1038/171737a0
3788 URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
3789 language: en-GB
3790 ...
3791 (pandoc-citeproc --bib2yaml can produce these from a bibliography file
3793 in one of the supported formats.)
3794 Citations and references can be formatted using any style supported by
3796 the Citation Style Language, listed in the Zotero Style Repository.
3797 These files are specified using the --csl option or the csl metadata
3798 field. By default, pandoc-citeproc will use the Chicago Manual of
3799 Style author-date format. The CSL project provides further information
3800 on finding and editing styles.
3801 To make your citations hyperlinks to the corresponding bibliography
3803 entries, add link-citations: true to your YAML metadata.
3804 Citations go inside square brackets and are separated by semicolons.
3806 Each citation must have a key, composed of '@' + the citation identi‐
3807 fier from the database, and may optionally have a prefix, a locator,
3808 and a suffix. The citation key must begin with a letter, digit, or _,
3809 and may contain alphanumerics, _, and internal punctuation characters
3810 (:.#$%&-+?<>~/). Here are some examples:
3811 Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
3813 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
3815 Blah blah [@smith04; @doe99].
3817 pandoc-citeproc detects locator terms in the CSL locale files. Either
3819 abbreviated or unabbreviated forms are accepted. In the en-US locale,
3820 locator terms can be written in either singular or plural forms, as
3821 book, bk./bks.; chapter, chap./chaps.; column, col./cols.; figure,
3822 fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note,
3823 n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part,
3824 pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.;
3825 volume, vol./vols.; ¶/¶¶; §/§§. If no locator term is used, "page" is
3826 assumed.
3827 pandoc-citeproc will use heuristics to distinguish the locator from the
3829 suffix. In complex cases, the locator can be enclosed in curly braces
3830 (using pandoc-citeproc 0.15 and higher only):
3831 [@smith{ii, A, D-Z}, with a suffix]
3833 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
3834 A minus sign (-) before the @ will suppress mention of the author in
3836 the citation. This can be useful when the author is already mentioned
3837 in the text:
3838 Smith says blah [-@smith04].
3840 You can also write an in-text citation, as follows:
3842 @smith04 says blah.
3844 @smith04 [p. 33] says blah.
3846 If the style calls for a list of works cited, it will be placed in a
3848 div with id refs, if one exists:
3849 ::: {#refs}
3851 :::
3852 Otherwise, it will be placed at the end of the document. Generation of
3854 the bibliography can be suppressed by setting suppress-bibliography:
3855 true in the YAML metadata.
3856 If you wish the bibliography to have a section heading, you can set
3858 reference-section-title in the metadata, or put the heading at the
3859 beginning of the div with id refs (if you are using it) or at the end
3860 of your document:
3861 last paragraph...
3863 # References
3865 The bibliography will be inserted after this heading. Note that the
3867 unnumbered class will be added to this heading, so that the section
3868 will not be numbered.
3869 If you want to include items in the bibliography without actually cit‐
3871 ing them in the body text, you can define a dummy nocite metadata field
3872 and put the citations there:
3873 ---
3875 nocite: |
3876 @item1, @item2
3877 ...
3878 @item3
3880 In this example, the document will contain a citation for item3 only,
3882 but the bibliography will contain entries for item1, item2, and item3.
3883 It is possible to create a bibliography with all the citations, whether
3885 or not they appear in the document, by using a wildcard:
3886 ---
3888 nocite: |
3889 @*
3890 ...
3891 For LaTeX output, you can also use natbib or biblatex to render the
3893 bibliography. In order to do so, specify bibliography files as out‐
3894 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
3895 tion. Bear in mind that bibliography files have to be in respective
3896 format (either BibTeX or BibLaTeX).
3897 For more information, see the pandoc-citeproc man page.
3899 Non-pandoc extensions
3901 The following Markdown syntax extensions are not enabled by default in
3902 pandoc, but may be enabled by adding +EXTENSION to the format name,
3903 where EXTENSION is the name of the extension. Thus, for example, mark‐
3904 down+hard_line_breaks is Markdown with hard line breaks.
3905 Extension: old_dashes
3907 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: -
3908 before a numeral is an en-dash, and -- is an em-dash. This option only
3909 has an effect if smart is enabled. It is selected automatically for
3910 textile input.
3911 Extension: angle_brackets_escapable
3913 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
3914 vored Markdown but not original Markdown. This is implied by pandoc's
3915 default all_symbols_escapable.
3916 Extension: lists_without_preceding_blankline
3918 Allow a list to occur right after a paragraph, with no intervening
3919 blank space.
3920 Extension: four_space_rule
3922 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
3923 ces indent are needed for list item continuation paragraphs.
3924 Extension: spaced_reference_links
3926 Allow whitespace between the two components of a reference link, for
3927 example,
3928 [foo] [bar].
3930 Extension: hard_line_breaks
3932 Causes all newlines within a paragraph to be interpreted as hard line
3933 breaks instead of spaces.
3934 Extension: ignore_line_breaks
3936 Causes newlines within a paragraph to be ignored, rather than being
3937 treated as spaces or as hard line breaks. This option is intended for
3938 use with East Asian languages where spaces are not used between words,
3939 but text is divided into lines for readability.
3940 Extension: east_asian_line_breaks
3942 Causes newlines within a paragraph to be ignored, rather than being
3943 treated as spaces or as hard line breaks, when they occur between two
3944 East Asian wide characters. This is a better choice than
3945 ignore_line_breaks for texts that include a mix of East Asian wide
3946 characters and other characters.
3947 Extension: emoji
3949 Parses textual emojis like :smile: as Unicode emoticons.
3950 Extension: tex_math_single_backslash
3952 Causes anything between \( and \) to be interpreted as inline TeX math,
3953 and anything between \[ and \] to be interpreted as display TeX math.
3954 Note: a drawback of this extension is that it precludes escaping ( and
3955 [.
3956 Extension: tex_math_double_backslash
3958 Causes anything between \\( and \\) to be interpreted as inline TeX
3959 math, and anything between \\[ and \\] to be interpreted as display TeX
3960 math.
3961 Extension: markdown_attribute
3963 By default, pandoc interprets material inside block-level tags as Mark‐
3964 down. This extension changes the behavior so that Markdown is only
3965 parsed inside block-level tags if the tags have the attribute mark‐
3966 down=1.
3967 Extension: mmd_title_block
3969 Enables a MultiMarkdown style title block at the top of the document,
3970 for example:
3971 Title: My title
3973 Author: John Doe
3974 Date: September 1, 2008
3975 Comment: This is a sample mmd title block, with
3976 a field spanning multiple lines.
3977 See the MultiMarkdown documentation for details. If pandoc_title_block
3979 or yaml_metadata_block is enabled, it will take precedence over
3980 mmd_title_block.
3981 Extension: abbreviations
3983 Parses PHP Markdown Extra abbreviation keys, like
3984 *[HTML]: Hypertext Markup Language
3986 Note that the pandoc document model does not support abbreviations, so
3988 if this extension is enabled, abbreviation keys are simply skipped (as
3989 opposed to being parsed as paragraphs).
3990 Extension: autolink_bare_uris
3992 Makes all absolute URIs into links, even when not surrounded by pointy
3993 braces <...>.
3994 Extension: mmd_link_attributes
3996 Parses multimarkdown style key-value attributes on link and image ref‐
3997 erences. This extension should not be confused with the
3998 link_attributes extension.
3999 This is a reference ![image][ref] with multimarkdown attributes.
4001 [ref]: http://path.to/image "Image title" width=20px height=30px
4003 id=myId class="myClass1 myClass2"
4004 Extension: mmd_header_identifiers
4006 Parses multimarkdown style heading identifiers (in square brackets,
4007 after the heading but before any trailing #s in an ATX heading).
4008 Extension: compact_definition_lists
4010 Activates the definition list syntax of pandoc 1.12.x and earlier.
4011 This syntax differs from the one described above under Definition lists
4012 in several respects:
4013 · No blank line is required between consecutive items of the definition
4015 list.
4016 · To get a "tight" or "compact" list, omit space between consecutive
4018 items; the space between a term and its definition does not affect
4019 anything.
4020 · Lazy wrapping of paragraphs is not allowed: the entire definition
4022 must be indented four spaces.
4023 Markdown variants
4025 In addition to pandoc's extended Markdown, the following Markdown vari‐
4026 ants are supported:
4027 markdown_phpextra (PHP Markdown Extra)
4029 footnotes, pipe_tables, raw_html, markdown_attribute,
4030 fenced_code_blocks, definition_lists, intraword_underscores,
4031 header_attributes, link_attributes, abbreviations, shortcut_ref‐
4032 erence_links, spaced_reference_links.
4033 markdown_github (deprecated GitHub-Flavored Markdown)
4035 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
4036 gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris,
4037 space_in_atx_header, intraword_underscores, strikeout,
4038 task_lists, emoji, shortcut_reference_links, angle_brack‐
4039 ets_escapable, lists_without_preceding_blankline.
4040 markdown_mmd (MultiMarkdown)
4042 pipe_tables, raw_html, markdown_attribute, mmd_link_attributes,
4043 tex_math_double_backslash, intraword_underscores,
4044 mmd_title_block, footnotes, definition_lists, all_sym‐
4045 bols_escapable, implicit_header_references, auto_identifiers,
4046 mmd_header_identifiers, shortcut_reference_links, implicit_fig‐
4047 ures, superscript, subscript, backtick_code_blocks, spaced_ref‐
4048 erence_links, raw_attribute.
4049 markdown_strict (Markdown.pl)
4051 raw_html, shortcut_reference_links, spaced_reference_links.
4052 We also support commonmark and gfm (GitHub-Flavored Markdown, which is
4054 implemented as a set of extensions on commonmark).
4055 Note, however, that commonmark and gfm have limited support for exten‐
4057 sions. Only those listed below (and smart, raw_tex, and
4058 hard_line_breaks) will work. The extensions can, however, all be indi‐
4059 vidually disabled. Also, raw_tex only affects gfm output, not input.
4060 gfm (GitHub-Flavored Markdown)
4062 pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
4063 gfm_auto_identifiers, backtick_code_blocks, autolink_bare_uris,
4064 space_in_atx_header, intraword_underscores, strikeout,
4065 task_lists, emoji, shortcut_reference_links, angle_brack‐
4066 ets_escapable, lists_without_preceding_blankline.
4067
4069 You can use pandoc to produce an HTML + JavaScript slide presentation
4070 that can be viewed via a web browser. There are five ways to do this,
4071 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
4072 duce a PDF slide show using LaTeX beamer, or slides shows in Microsoft
4073 PowerPoint format.
4074 Here's the Markdown source for a simple slide show, habits.txt:
4076 % Habits
4078 % John Doe
4079 % March 22, 2005
4080 # In the morning
4082 ## Getting up
4084 - Turn off alarm
4086 - Get out of bed
4087 ## Breakfast
4089 - Eat eggs
4091 - Drink coffee
4092 # In the evening
4094 ## Dinner
4096 - Eat spaghetti
4098 - Drink wine
4099 ------------------
4101 
4103 ## Going to sleep
4105 - Get in bed
4107 - Count sheep
4108 To produce an HTML/JavaScript slide show, simply type
4110 pandoc -t FORMAT -s habits.txt -o habits.html
4112 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
4114 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
4116 with the -s/--standalone option embeds a link to JavaScript and CSS
4117 files, which are assumed to be available at the relative path
4118 s5/default (for S5), slideous (for Slideous), reveal.js (for
4119 reveal.js), or at the Slidy website at w3.org (for Slidy). (These
4120 paths can be changed by setting the slidy-url, slideous-url, revealjs-
4121 url, or s5-url variables; see Variables for HTML slides, above.) For
4122 DZSlides, the (relatively short) JavaScript and CSS are included in the
4123 file by default.
4124 With all HTML slide formats, the --self-contained option can be used to
4126 produce a single file that contains all of the data necessary to dis‐
4127 play the slide show, including linked scripts, stylesheets, images, and
4128 videos.
4129 To produce a PDF slide show using beamer, type
4131 pandoc -t beamer habits.txt -o habits.pdf
4133 Note that a reveal.js slide show can also be converted to a PDF by
4135 printing it to a file from the browser.
4136 To produce a Powerpoint slide show, type
4138 pandoc habits.txt -o habits.pptx
4140 Structuring the slide show
4142 By default, the slide level is the highest heading level in the hierar‐
4143 chy that is followed immediately by content, and not another heading,
4144 somewhere in the document. In the example above, level-1 headings are
4145 always followed by level-2 headings, which are followed by content, so
4146 the slide level is 2. This default can be overridden using the
4147 --slide-level option.
4148 The document is carved up into slides according to the following rules:
4150 · A horizontal rule always starts a new slide.
4152 · A heading at the slide level always starts a new slide.
4154 · Headings below the slide level in the hierarchy create headings
4156 within a slide.
4157 · Headings above the slide level in the hierarchy create "title
4159 slides," which just contain the section title and help to break the
4160 slide show into sections. Non-slide content under these headings
4161 will be included on the title slide (for HTML slide shows) or in a
4162 subsequent slide with the same title (for beamer).
4163 · A title page is constructed automatically from the document's title
4165 block, if present. (In the case of beamer, this can be disabled by
4166 commenting out some lines in the default template.)
4167 These rules are designed to support many different styles of slide
4169 show. If you don't care about structuring your slides into sections
4170 and subsections, you can just use level-1 headings for all each slide.
4171 (In that case, level-1 will be the slide level.) But you can also
4172 structure the slide show into sections, as in the example above.
4173 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
4175 layout will be produced, with level-1 headings building horizontally
4176 and level-2 headings building vertically. It is not recommended that
4177 you use deeper nesting of section levels with reveal.js.
4178 Incremental lists
4180 By default, these writers produce lists that display "all at once." If
4181 you want your lists to display incrementally (one item at a time), use
4182 the -i option. If you want a particular list to depart from the
4183 default, put it in a div block with class incremental or nonincremen‐
4184 tal. So, for example, using the fenced div syntax, the following would
4185 be incremental regardless of the document default:
4186 ::: incremental
4188 - Eat spaghetti
4190 - Drink wine
4191 :::
4193 or
4195 ::: nonincremental
4197 - Eat spaghetti
4199 - Drink wine
4200 :::
4202 While using incremental and nonincremental divs are the recommended
4204 method of setting incremental lists on a per-case basis, an older
4205 method is also supported: putting lists inside a blockquote will depart
4206 from the document default (that is, it will display incrementally with‐
4207 out the -i option and all at once with the -i option):
4208 > - Eat spaghetti
4210 > - Drink wine
4211 Both methods allow incremental and nonincremental lists to be mixed in
4213 a single document.
4214 Inserting pauses
4216 You can add "pauses" within a slide by including a paragraph containing
4217 three dots, separated by spaces:
4218 # Slide with a pause
4220 content before the pause
4222 . . .
4224 content after the pause
4226 Styling the slides
4228 You can change the style of HTML slides by putting customized CSS files
4229 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
4230 $DATADIR/slideous (for Slideous), where $DATADIR is the user data
4231 directory (see --data-dir, above). The originals may be found in pan‐
4232 doc's system data directory (generally $CABALDIR/pandoc-VER‐
4233 SION/s5/default). Pandoc will look there for any files it does not
4234 find in the user data directory.
4235 For dzslides, the CSS is included in the HTML file itself, and may be
4237 modified there.
4238 All reveal.js configuration options can be set through variables. For
4240 example, themes can be used by setting the theme variable:
4241 -V theme=moon
4243 Or you can specify a custom stylesheet using the --css option.
4245 To style beamer slides, you can specify a theme, colortheme, fonttheme,
4247 innertheme, and outertheme, using the -V option:
4248 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
4250 Note that heading attributes will turn into slide attributes (on a
4252 <div> or <section>) in HTML slide formats, allowing you to style indi‐
4253 vidual slides. In beamer, the only heading attribute that affects
4254 slides is the allowframebreaks class, which sets the allowframebreaks
4255 option, causing multiple slides to be created if the content overfills
4256 the frame. This is recommended especially for bibliographies:
4257 # References {.allowframebreaks}
4259 Speaker notes
4261 Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
4262 You can add notes to your Markdown document thus:
4263 ::: notes
4265 This is my note.
4267 - It can contain Markdown
4269 - like this list
4270 :::
4272 To show the notes window in reveal.js, press s while viewing the pre‐
4274 sentation. Speaker notes in PowerPoint will be available, as usual, in
4275 handouts and presenter view.
4276 Notes are not yet supported for other slide formats, but the notes will
4278 not appear on the slides themselves.
4279 Columns
4281 To put material in side by side columns, you can use a native div con‐
4282 tainer with class columns, containing two or more div containers with
4283 class column and a width attribute:
4284 :::::::::::::: {.columns}
4286 ::: {.column width="40%"}
4287 contents...
4288 :::
4289 ::: {.column width="60%"}
4290 contents...
4291 :::
4292 ::::::::::::::
4293 Frame attributes in beamer
4295 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
4296 in beamer (for example, when using the minted environment). This can
4297 be forced by adding the fragile class to the heading introducing the
4298 slide:
4299 # Fragile slide {.fragile}
4301 All of the other frame attributes described in Section 8.1 of the
4303 Beamer User's Guide may also be used: allowdisplaybreaks, allowframe‐
4304 breaks, b, c, t, environment, label, plain, shrink, standout, nofra‐
4305 menumbering.
4306 Background in reveal.js and beamer
4308 Background images can be added to self-contained reveal.js slideshows
4309 and to beamer slideshows.
4310 For the same image on every slide, use the configuration option back‐
4312 ground-image either in the YAML metadata block or as a command-line
4313 variable. (There are no other options in beamer and the rest of this
4314 section concerns reveal.js slideshows.)
4315 For reveal.js, you can instead use the reveal.js-native option paral‐
4317 laxBackgroundImage. You can also set parallaxBackgroundHorizontal and
4318 parallaxBackgroundVertical the same way and must also set parallaxBack‐
4319 groundSize to have your values take effect.
4320 To set an image for a particular reveal.js slide, add {data-background-
4322 image="/path/to/image"} to the first slide-level heading on the slide
4323 (which may even be empty).
4324 In reveal.js's overview mode, the parallaxBackgroundImage will show up
4326 only on the first slide.
4327 Other reveal.js background settings also work on individual slides,
4329 including data-background-size, data-background-repeat, data-back‐
4330 ground-color, data-transition, and data-transition-speed.
4331 See the reveal.js documentation for more details.
4333 For example in reveal.js:
4335 ---
4337 title: My Slideshow
4338 parallaxBackgroundImage: /path/to/my/background_image.png
4339 ---
4340 ## Slide One
4342 Slide 1 has background_image.png as its background.
4344 ## {data-background-image="/path/to/special_image.jpg"}
4346 Slide 2 has a special image for its background, even though the heading has no content.
4348
4350 EPUB Metadata
4351 EPUB metadata may be specified using the --epub-metadata option, but if
4352 the source document is Markdown, it is better to use a YAML metadata
4353 block. Here is an example:
4354 ---
4356 title:
4357 - type: main
4358 text: My Book
4359 - type: subtitle
4360 text: An investigation of metadata
4361 creator:
4362 - role: author
4363 text: John Smith
4364 - role: editor
4365 text: Sarah Jones
4366 identifier:
4367 - scheme: DOI
4368 text: doi:10.234234.234/33
4369 publisher: My Press
4370 rights: © 2007 John Smith, CC BY-NC
4371 ibooks:
4372 version: 1.3.4
4373 ...
4374 The following fields are recognized:
4376 identifier
4378 Either a string value or an object with fields text and scheme.
4379 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
4380 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
4381 ISMN-13, ISBN-A, JP, OLCC.
4382 title Either a string value, or an object with fields file-as and
4384 type, or a list of such objects. Valid values for type are
4385 main, subtitle, short, collection, edition, extended.
4386 creator
4388 Either a string value, or an object with fields role, file-as,
4389 and text, or a list of such objects. Valid values for role are
4390 MARC relators, but pandoc will attempt to translate the human-
4391 readable versions (like "author" and "editor") to the appropri‐
4392 ate marc relators.
4393 contributor
4395 Same format as creator.
4396 date A string value in YYYY-MM-DD format. (Only the year is neces‐
4398 sary.) Pandoc will attempt to convert other common date formats.
4399 lang (or legacy: language)
4401 A string value in BCP 47 format. Pandoc will default to the
4402 local language if nothing is specified.
4403 subject
4405 A string value or a list of such values.
4406 description
4408 A string value.
4409 type A string value.
4411 format A string value.
4413 relation
4415 A string value.
4416 coverage
4418 A string value.
4419 rights A string value.
4421 cover-image
4423 A string value (path to cover image).
4424 css (or legacy: stylesheet)
4426 A string value (path to CSS stylesheet).
4427 page-progression-direction
4429 Either ltr or rtl. Specifies the page-progression-direction
4430 attribute for the spine element.
4431 ibooks iBooks-specific metadata, with the following fields:
4433 · version: (string)
4435 · specified-fonts: true|false (default false)
4437 · ipad-orientation-lock: portrait-only|landscape-only
4439 · iphone-orientation-lock: portrait-only|landscape-only
4441 · binding: true|false (default true)
4443 · scroll-axis: vertical|horizontal|default
4445 The epub:type attribute
4447 For epub3 output, you can mark up the heading that corresponds to an
4448 EPUB chapter using the epub:type attribute. For example, to set the
4449 attribute to the value prologue, use this markdown:
4450 # My chapter {epub:type=prologue}
4452 Which will result in:
4454 <body epub:type="frontmatter">
4456 <section epub:type="prologue">
4457 <h1>My chapter</h1>
4458 Pandoc will output <body epub:type="bodymatter">, unless you use one of
4460 the following values, in which case either frontmatter or backmatter
4461 will be output.
4462 epub:type of first section epub:type of body
4464 ───────────────────────────────────────────────
4465 prologue frontmatter
4466 abstract frontmatter
4467 acknowledgments frontmatter
4469 copyright-page frontmatter
4470 dedication frontmatter
4471 credits frontmatter
4472 keywords frontmatter
4473 imprint frontmatter
4474 contributors frontmatter
4475 other-credits frontmatter
4476 errata frontmatter
4477 revision-history frontmatter
4478 titlepage frontmatter
4479 halftitlepage frontmatter
4480 seriespage frontmatter
4481 foreword frontmatter
4482 preface frontmatter
4483 seriespage frontmatter
4484 titlepage frontmatter
4485 appendix backmatter
4486 colophon backmatter
4487 bibliography backmatter
4488 index backmatter
4489 Linked media
4491 By default, pandoc will download media referenced from any <img>,
4492 <audio>, <video> or <source> element present in the generated EPUB, and
4493 include it in the EPUB container, yielding a completely self-contained
4494 EPUB. If you want to link to external media resources instead, use raw
4495 HTML in your source and add data-external="1" to the tag with the src
4496 attribute. For example:
4497 <audio controls="1">
4499 <source src="http://example.com/music/toccata.mp3"
4500 data-external="1" type="audio/mpeg">
4501 </source>
4502 </audio>
4503
4505 When creating a Jupyter notebook, pandoc will try to infer the notebook
4506 structure. Code blocks with the class code will be taken as code
4507 cells, and intervening content will be taken as Markdown cells.
4508 Attachments will automatically be created for images in Markdown cells.
4509 Metadata will be taken from the jupyter metadata field. For example:
4510 ---
4512 title: My notebook
4513 jupyter:
4514 nbformat: 4
4515 nbformat_minor: 5
4516 kernelspec:
4517 display_name: Python 2
4518 language: python
4519 name: python2
4520 language_info:
4521 codemirror_mode:
4522 name: ipython
4523 version: 2
4524 file_extension: ".py"
4525 mimetype: "text/x-python"
4526 name: "python"
4527 nbconvert_exporter: "python"
4528 pygments_lexer: "ipython2"
4529 version: "2.7.15"
4530 ---
4531 # Lorem ipsum
4533 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
4535 bibendum felis dictum sodales.
4536 ``` code
4538 print("hello")
4539 ```
4540 ## Pyout
4542 ``` code
4544 from IPython.display import HTML
4545 HTML("""
4546 <script>
4547 console.log("hello");
4548 </script>
4549 <b>HTML</b>
4550 """)
4551 ```
4552 ## Image
4554 This image  will be
4556 included as a cell attachment.
4557 If you want to add cell attributes, group cells differently, or add
4559 output to code cells, then you need to include divs to indicate the
4560 structure. You can use either fenced divs or native divs for this.
4561 Here is an example:
4562 :::::: {.cell .markdown}
4564 # Lorem
4565 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
4567 bibendum felis dictum sodales.
4568 ::::::
4569 :::::: {.cell .code execution_count=1}
4571 ``` {.python}
4572 print("hello")
4573 ```
4574 ::: {.output .stream .stdout}
4576 ```
4577 hello
4578 ```
4579 :::
4580 ::::::
4581 :::::: {.cell .code execution_count=2}
4583 ``` {.python}
4584 from IPython.display import HTML
4585 HTML("""
4586 <script>
4587 console.log("hello");
4588 </script>
4589 <b>HTML</b>
4590 """)
4591 ```
4592 ::: {.output .execute_result execution_count=2}
4594 ```{=html}
4595 <script>
4596 console.log("hello");
4597 </script>
4598 <b>HTML</b>
4599 hello
4600 ```
4601 :::
4602 ::::::
4603 If you include raw HTML or TeX in an output cell, use the [raw
4605 attribute][Extension: fenced_attribute], as shown in the last cell of
4606 the example above. Although pandoc can process "bare" raw HTML and
4607 TeX, the result is often interspersed raw elements and normal textual
4608 elements, and in an output cell pandoc expects a single, connected raw
4609 block. To avoid using raw HTML or TeX except when marked explicitly
4610 using raw attributes, we recommend specifying the extensions -raw_html-
4611 raw_tex+raw_attribute when translating between Markdown and ipynb note‐
4612 books.
4613 Note that options and extensions that affect reading and writing of
4615 Markdown will also affect Markdown cells in ipynb notebooks. For exam‐
4616 ple, --wrap=preserve will preserve soft line breaks in Markdown cells;
4617 --atx-headers will cause ATX-style headings to be used; and --preserve-
4618 tabs will prevent tabs from being turned to spaces.
4619
4621 Pandoc will automatically highlight syntax in fenced code blocks that
4622 are marked with a language name. The Haskell library skylighting is
4623 used for highlighting. Currently highlighting is supported only for
4624 HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language
4625 names that pandoc will recognize, type pandoc --list-highlight-lan‐
4626 guages.
4627 The color scheme can be selected using the --highlight-style option.
4629 The default color scheme is pygments, which imitates the default color
4630 scheme used by the Python library pygments (though pygments is not
4631 actually used to do the highlighting). To see a list of highlight
4632 styles, type pandoc --list-highlight-styles.
4633 If you are not satisfied with the predefined styles, you can use
4635 --print-highlight-style to generate a JSON .theme file which can be
4636 modified and used as the argument to --highlight-style. To get a JSON
4637 version of the pygments style, for example:
4638 pandoc --print-highlight-style pygments > my.theme
4640 Then edit my.theme and use it like this:
4642 pandoc --highlight-style my.theme
4644 If you are not satisfied with the built-in highlighting, or you want
4646 highlight a language that isn't supported, you can use the --syntax-
4647 definition option to load a KDE-style XML syntax definition file.
4648 Before writing your own, have a look at KDE's repository of syntax def‐
4649 initions.
4650 To disable highlighting, use the --no-highlight option.
4652
4654 Custom styles can be used in the docx and ICML formats.
4655 Output
4657 By default, pandoc's docx and ICML output applies a predefined set of
4658 styles for blocks such as paragraphs and block quotes, and uses largely
4659 default formatting (italics, bold) for inlines. This will work for
4660 most purposes, especially alongside a reference.docx file. However, if
4661 you need to apply your own styles to blocks, or match a preexisting set
4662 of styles, pandoc allows you to define custom styles for blocks and
4663 text using divs and spans, respectively.
4664 If you define a div or span with the attribute custom-style, pandoc
4666 will apply your specified style to the contained elements. So, for
4667 example using the bracketed_spans syntax,
4668 [Get out]{custom-style="Emphatically"}, he said.
4670 would produce a docx file with "Get out" styled with character style
4672 Emphatically. Similarly, using the fenced_divs syntax,
4673 Dickinson starts the poem simply:
4675 ::: {custom-style="Poetry"}
4677 | A Bird came down the Walk---
4678 | He did not know I saw---
4679 :::
4680 would style the two contained lines with the Poetry paragraph style.
4682 For docx output, styles will be defined in the output file as inherit‐
4684 ing from normal text, if the styles are not yet in your reference.docx.
4685 If they are already defined, pandoc will not alter the definition.
4686 This feature allows for greatest customization in conjunction with pan‐
4688 doc filters. If you want all paragraphs after block quotes to be
4689 indented, you can write a filter to apply the styles necessary. If you
4690 want all italics to be transformed to the Emphasis character style
4691 (perhaps to change their color), you can write a filter which will
4692 transform all italicized inlines to inlines within an Emphasis custom-
4693 style span.
4694 For docx output, you don't need to enable any extensions for custom
4696 styles to work.
4697 Input
4699 The docx reader, by default, only reads those styles that it can con‐
4700 vert into pandoc elements, either by direct conversion or interpreting
4701 the derivation of the input document's styles.
4702 By enabling the styles extension in the docx reader (-f docx+styles),
4704 you can produce output that maintains the styles of the input document,
4705 using the custom-style class. Paragraph styles are interpreted as
4706 divs, while character styles are interpreted as spans.
4707 For example, using the custom-style-reference.docx file in the test
4709 directory, we have the following different outputs:
4710 Without the +styles extension:
4712 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
4714 This is some text.
4715 This is text with an *emphasized* text style. And this is text with a
4717 **strengthened** text style.
4718 > Here is a styled paragraph that inherits from Block Text.
4720 And with the extension:
4722 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
4724 ::: {custom-style="FirstParagraph"}
4726 This is some text.
4727 :::
4728 ::: {custom-style="BodyText"}
4730 This is text with an [emphasized]{custom-style="Emphatic"} text style.
4731 And this is text with a [strengthened]{custom-style="Strengthened"}
4732 text style.
4733 :::
4734 ::: {custom-style="MyBlockStyle"}
4736 > Here is a styled paragraph that inherits from Block Text.
4737 :::
4738 With these custom styles, you can use your input document as a refer‐
4740 ence-doc while creating docx output (see below), and maintain the same
4741 styles in your input and output files.
4742
4744 Pandoc can be extended with custom writers written in lua. (Pandoc
4745 includes a lua interpreter, so lua need not be installed separately.)
4746 To use a custom writer, simply specify the path to the lua script in
4748 place of the output format. For example:
4749 pandoc -t data/sample.lua
4751 Creating a custom writer requires writing a lua function for each pos‐
4753 sible element in a pandoc document. To get a documented example which
4754 you can modify according to your needs, do
4755 pandoc --print-default-data-file sample.lua
4757
4759 If you use pandoc to convert user-contributed content in a web applica‐
4760 tion, here are some things to keep in mind:
4761 1. Although pandoc itself will not create or modify any files other
4763 than those you explicitly ask it create (with the exception of tem‐
4764 porary files used in producing PDFs), a filter or custom writer
4765 could in principle do anything on your file system. Please audit
4766 filters and custom writers very carefully before using them.
4767 2. If your application uses pandoc as a Haskell library (rather than
4769 shelling out to the executable), it is possible to use it in a mode
4770 that fully isolates pandoc from your file system, by running the
4771 pandoc operations in the PandocPure monad. See the document Using
4772 the pandoc API for more details.
4773 3. Pandoc's parsers can exhibit pathological performance on some corner
4775 cases. It is wise to put any pandoc operations under a timeout, to
4776 avoid DOS attacks that exploit these issues. If you are using the
4777 pandoc executable, you can add the command line options +RTS -M512M
4778 -RTS (for example) to limit the heap size to 512MB.
4779 4. The HTML generated by pandoc is not guaranteed to be safe. If
4781 raw_html is enabled for the Markdown input, users can inject arbi‐
4782 trary HTML. Even if raw_html is disabled, users can include danger‐
4783 ous content in attributes for headings, spans, and code blocks. To
4784 be safe, you should run all the generated HTML through an HTML sani‐
4785 tizer.
4786
4788 Copyright 2006--2019 John MacFarlane (jgm@berkeley.edu). Released
4789 under the GPL, version 2 or greater. This software carries no warranty
4790 of any kind. (See COPYRIGHT for full copyright and warranty notices.)
4791 For a full list of contributors, see the file AUTHORS.md in the pandoc
4792 source code.
4793 The Pandoc source code and all documentation may be downloaded from
4795 <http://pandoc.org>.
4796pandoc 2.7.3 June 11, 2019 PANDOC(1)