1Pandoc User’s Guide() Pandoc User’s Guide()
2
6 pandoc - general markup converter
7
9 pandoc [options] [input-file]...
10
12 Pandoc is a Haskell library for converting from one markup format to
13 another, and a command-line tool that uses this library.
14 Pandoc can convert between numerous markup and word processing formats,
16 including, but not limited to, various flavors of Markdown, HTML, LaTeX
17 and Word docx. For the full lists of input and output formats, see the
18 --from and --to options below. Pandoc can also produce PDF output: see
19 creating a PDF, below.
20 Pandoc’s enhanced version of Markdown includes syntax for tables, defi‐
22 nition lists, metadata blocks, footnotes, citations, math, and much
23 more. See below under Pandoc’s Markdown.
24 Pandoc has a modular design: it consists of a set of readers, which
26 parse text in a given format and produce a native representation of the
27 document (an abstract syntax tree or AST), and a set of writers, which
28 convert this native representation into a target format. Thus, adding
29 an input or output format requires only adding a reader or writer.
30 Users can also run custom pandoc filters to modify the intermediate
31 AST.
32 Because pandoc’s intermediate representation of a document is less ex‐
34 pressive than many of the formats it converts between, one should not
35 expect perfect conversions between every format and every other. Pan‐
36 doc attempts to preserve the structural elements of a document, but not
37 formatting details such as margin size. And some document elements,
38 such as complex tables, may not fit into pandoc’s simple document mod‐
39 el. While conversions from pandoc’s Markdown to all formats aspire to
40 be perfect, conversions from formats more expressive than pandoc’s
41 Markdown can be expected to be lossy.
42 Using pandoc
44 If no input-files are specified, input is read from stdin. Output goes
45 to stdout by default. For output to a file, use the -o option:
46 pandoc -o output.html input.txt
48 By default, pandoc produces a document fragment. To produce a stand‐
50 alone document (e.g. a valid HTML file including <head> and <body>),
51 use the -s or --standalone flag:
52 pandoc -s -o output.html input.txt
54 For more information on how standalone documents are produced, see Tem‐
56 plates below.
57 If multiple input files are given, pandoc will concatenate them all
59 (with blank lines between them) before parsing. (Use --file-scope to
60 parse files individually.)
61 Specifying formats
63 The format of the input and output can be specified explicitly using
64 command-line options. The input format can be specified using the
65 -f/--from option, the output format using the -t/--to option. Thus, to
66 convert hello.txt from Markdown to LaTeX, you could type:
67 pandoc -f markdown -t latex hello.txt
69 To convert hello.html from HTML to Markdown:
71 pandoc -f html -t markdown hello.html
73 Supported input and output formats are listed below under Options (see
75 -f for input formats and -t for output formats). You can also use pan‐
76 doc --list-input-formats and pandoc --list-output-formats to print
77 lists of supported formats.
78 If the input or output format is not specified explicitly, pandoc will
80 attempt to guess it from the extensions of the filenames. Thus, for
81 example,
82 pandoc -o hello.tex hello.txt
84 will convert hello.txt from Markdown to LaTeX. If no output file is
86 specified (so that output goes to stdout), or if the output file’s ex‐
87 tension is unknown, the output format will default to HTML. If no in‐
88 put file is specified (so that input comes from stdin), or if the input
89 files’ extensions are unknown, the input format will be assumed to be
90 Markdown.
91 Character encoding
93 Pandoc uses the UTF-8 character encoding for both input and output. If
94 your local character encoding is not UTF-8, you should pipe input and
95 output through iconv:
96 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
98 Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
100 OPML, DocBook, and Texinfo), information about the character encoding
101 is included in the document header, which will only be included if you
102 use the -s/--standalone option.
103 Creating a PDF
105 To produce a PDF, specify an output file with a .pdf extension:
106 pandoc test.txt -o test.pdf
108 By default, pandoc will use LaTeX to create the PDF, which requires
110 that a LaTeX engine be installed (see --pdf-engine below). Alterna‐
111 tively, pandoc can use ConTeXt, roff ms, or HTML as an intermediate
112 format. To do this, specify an output file with a .pdf extension, as
113 before, but add the --pdf-engine option or -t context, -t html, or -t
114 ms to the command line. The tool used to generate the PDF from the in‐
115 termediate format may be specified using --pdf-engine.
116 You can control the PDF style using variables, depending on the inter‐
118 mediate format used: see variables for LaTeX, variables for ConTeXt,
119 variables for wkhtmltopdf, variables for ms. When HTML is used as an
120 intermediate format, the output can be styled using --css.
121 To debug the PDF creation, it can be useful to look at the intermediate
123 representation: instead of -o test.pdf, use for example -s -o test.tex
124 to output the generated LaTeX. You can then test it with pdflatex
125 test.tex.
126 When using LaTeX, the following packages need to be available (they are
128 included with all recent versions of TeX Live): amsfonts, amsmath, lm,
129 unicode-math, iftex, listings (if the --listings option is used), fan‐
130 cyvrb, longtable, booktabs, graphicx (if the document contains images),
131 hyperref, xcolor, ulem, geometry (with the geometry variable set),
132 setspace (with linestretch), and babel (with lang). The use of xelatex
133 or lualatex as the PDF engine requires fontspec. lualatex uses selno‐
134 lig. xelatex uses polyglossia (with lang), xecjk, and bidi (with the
135 dir variable set). If the mathspec variable is set, xelatex will use
136 mathspec instead of unicode-math. The upquote and microtype packages
137 are used if available, and csquotes will be used for typography if the
138 csquotes variable or metadata field is set to a true value. The nat‐
139 bib, biblatex, bibtex, and biber packages can optionally be used for
140 citation rendering. The following packages will be used to improve
141 output quality if present, but pandoc does not require them to be
142 present: upquote (for straight quotes in verbatim environments), mi‐
143 crotype (for better spacing adjustments), parskip (for better inter-
144 paragraph spaces), xurl (for better line breaks in URLs), bookmark (for
145 better PDF bookmarks), and footnotehyper or footnote (to allow foot‐
146 notes 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 https://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 https://www.fsf.org
159
161 General options
162 -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
163 Specify input format. FORMAT can be:
164 • bibtex (BibTeX bibliography)
166 • biblatex (BibLaTeX bibliography)
168 • commonmark (CommonMark Markdown)
170 • commonmark_x (CommonMark Markdown with extensions)
172 • creole (Creole 1.0)
174 • csljson (CSL JSON bibliography)
176 • csv (CSV table)
178 • docbook (DocBook)
180 • docx (Word docx)
182 • dokuwiki (DokuWiki markup)
184 • epub (EPUB)
186 • fb2 (FictionBook2 e-book)
188 • gfm (GitHub-Flavored Markdown), or the deprecated and less ac‐
190 curate markdown_github; use markdown_github only if you need
191 extensions not supported in gfm.
192 • haddock (Haddock markup)
194 • html (HTML)
196 • ipynb (Jupyter notebook)
198 • jats (JATS XML)
200 • jira (Jira/Confluence wiki markup)
202 • json (JSON version of native AST)
204 • latex (LaTeX)
206 • markdown (Pandoc’s Markdown)
208 • markdown_mmd (MultiMarkdown)
210 • markdown_phpextra (PHP Markdown Extra)
212 • markdown_strict (original unextended Markdown)
214 • mediawiki (MediaWiki markup)
216 • man (roff man)
218 • muse (Muse)
220 • native (native Haskell)
222 • odt (ODT)
224 • opml (OPML)
226 • org (Emacs Org mode)
228 • rst (reStructuredText)
230 • t2t (txt2tags)
232 • textile (Textile)
234 • tikiwiki (TikiWiki markup)
236 • twiki (TWiki markup)
238 • vimwiki (Vimwiki)
240 Extensions can be individually enabled or disabled by appending
242 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
243 low, for a list of extensions and their names. See --list-in‐
244 put-formats and --list-extensions, below.
245 -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
247 Specify output format. FORMAT can be:
248 • asciidoc (AsciiDoc) or asciidoctor (AsciiDoctor)
250 • beamer (LaTeX beamer slide show)
252 • bibtex (BibTeX bibliography)
254 • biblatex (BibLaTeX bibliography)
256 • commonmark (CommonMark Markdown)
258 • commonmark_x (CommonMark Markdown with extensions)
260 • context (ConTeXt)
262 • csljson (CSL JSON bibliography)
264 • docbook or docbook4 (DocBook 4)
266 • docbook5 (DocBook 5)
268 • docx (Word docx)
270 • dokuwiki (DokuWiki markup)
272 • epub or epub3 (EPUB v3 book)
274 • epub2 (EPUB v2)
276 • fb2 (FictionBook2 e-book)
278 • gfm (GitHub-Flavored Markdown), or the deprecated and less ac‐
280 curate markdown_github; use markdown_github only if you need
281 extensions not supported in gfm.
282 • haddock (Haddock markup)
284 • html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
286 • html4 (XHTML 1.0 Transitional)
288 • icml (InDesign ICML)
290 • ipynb (Jupyter notebook)
292 • jats_archiving (JATS XML, Archiving and Interchange Tag Set)
294 • jats_articleauthoring (JATS XML, Article Authoring Tag Set)
296 • jats_publishing (JATS XML, Journal Publishing Tag Set)
298 • jats (alias for jats_archiving)
300 • jira (Jira/Confluence wiki markup)
302 • json (JSON version of native AST)
304 • latex (LaTeX)
306 • man (roff man)
308 • markdown (Pandoc’s Markdown)
310 • markdown_mmd (MultiMarkdown)
312 • markdown_phpextra (PHP Markdown Extra)
314 • markdown_strict (original unextended Markdown)
316 • mediawiki (MediaWiki markup)
318 • ms (roff ms)
320 • muse (Muse),
322 • native (native Haskell),
324 • odt (OpenOffice text document)
326 • opml (OPML)
328 • opendocument (OpenDocument)
330 • org (Emacs Org mode)
332 • pdf (PDF)
334 • plain (plain text),
336 • pptx (PowerPoint slide show)
338 • rst (reStructuredText)
340 • rtf (Rich Text Format)
342 • texinfo (GNU Texinfo)
344 • textile (Textile)
346 • slideous (Slideous HTML and JavaScript slide show)
348 • slidy (Slidy HTML and JavaScript slide show)
350 • dzslides (DZSlides HTML5 + JavaScript slide show),
352 • revealjs (reveal.js HTML5 + JavaScript slide show)
354 • s5 (S5 HTML and JavaScript slide show)
356 • tei (TEI Simple)
358 • xwiki (XWiki markup)
360 • zimwiki (ZimWiki markup)
362 • the path of a custom Lua writer, see Custom writers below
364 Note that odt, docx, epub, and pdf output will not be directed
366 to stdout unless forced with -o -.
367 Extensions can be individually enabled or disabled by appending
369 +EXTENSION or -EXTENSION to the format name. See Extensions be‐
370 low, for a list of extensions and their names. See --list-out‐
371 put-formats and --list-extensions, below.
372 -o FILE, --output=FILE
374 Write output to FILE instead of stdout. If FILE is -, output
375 will go to stdout, even if a non-textual format (docx, odt,
376 epub2, epub3) is specified.
377 --data-dir=DIRECTORY
379 Specify the user data directory to search for pandoc data files.
380 If this option is not specified, the default user data directory
381 will be used. On *nix and macOS systems this will be the pandoc
382 subdirectory of the XDG data directory (by default, $HOME/.lo‐
383 cal/share, overridable by setting the XDG_DATA_HOME environment
384 variable). If that directory does not exist and $HOME/.pandoc
385 exists, it will be used (for backwards compatibility). On Win‐
386 dows the default user data directory is C:\Users\USERNAME\AppDa‐
387 ta\Roaming\pandoc. You can find the default user data directory
388 on your system by looking at the output of pandoc --version.
389 Data files placed in this directory (for example, reference.odt,
390 reference.docx, epub.css, templates) will override pandoc’s nor‐
391 mal defaults.
392 -d FILE, --defaults=FILE
394 Specify a set of default option settings. FILE is a YAML file
395 whose fields correspond to command-line option settings. All
396 options for document conversion, including input and output
397 files, can be set using a defaults file. The file will be
398 searched for first in the working directory, and then in the de‐
399 faults subdirectory of the user data directory (see --data-dir).
400 The .yaml extension may be omitted. See the section Default
401 files for more information on the file format. Settings from
402 the defaults file may be overridden or extended by subsequent
403 options on the command line.
404 --bash-completion
406 Generate a bash completion script. To enable bash completion
407 with pandoc, add this to your .bashrc:
408 eval "$(pandoc --bash-completion)"
410 --verbose
412 Give verbose debugging output.
413 --quiet
415 Suppress warning messages.
416 --fail-if-warnings
418 Exit with error status if there are any warnings.
419 --log=FILE
421 Write log messages in machine-readable JSON format to FILE. All
422 messages above DEBUG level will be written, regardless of ver‐
423 bosity settings (--verbose, --quiet).
424 --list-input-formats
426 List supported input formats, one per line.
427 --list-output-formats
429 List supported output formats, one per line.
430 --list-extensions[=FORMAT]
432 List supported extensions for FORMAT, one per line, preceded by
433 a + or - indicating whether it is enabled by default in FORMAT.
434 If FORMAT is not specified, defaults for pandoc’s Markdown are
435 given.
436 --list-highlight-languages
438 List supported languages for syntax highlighting, one per line.
439 --list-highlight-styles
441 List supported styles for syntax highlighting, one per line.
442 See --highlight-style.
443 -v, --version
445 Print version.
446 -h, --help
448 Show usage message.
449 Reader options
451 --shift-heading-level-by=NUMBER
452 Shift heading levels by a positive or negative integer. For ex‐
453 ample, with --shift-heading-level-by=-1, level 2 headings become
454 level 1 headings, and level 3 headings become level 2 headings.
455 Headings cannot have a level less than 1, so a heading that
456 would be shifted below level 1 becomes a regular paragraph. Ex‐
457 ception: with a shift of -N, a level-N heading at the beginning
458 of the document replaces the metadata title. --shift-heading-
459 level-by=-1 is a good choice when converting HTML or Markdown
460 documents that use an initial level-1 heading for the document
461 title and level-2+ headings for sections. --shift-heading-lev‐
462 el-by=1 may be a good choice for converting Markdown documents
463 that use level-1 headings for sections to HTML, since pandoc us‐
464 es a level-1 heading to render the document title.
465 --base-header-level=NUMBER
467 Deprecated. Use --shift-heading-level-by=X instead, where X =
468 NUMBER - 1. Specify the base level for headings (defaults to 1).
469 --strip-empty-paragraphs
471 Deprecated. Use the +empty_paragraphs extension instead. Ignore
472 paragraphs with no content. This option is useful for convert‐
473 ing word processing documents where users have used empty para‐
474 graphs to create inter-paragraph space.
475 --indented-code-classes=CLASSES
477 Specify classes to use for indented code blocks–for example,
478 perl,numberLines or haskell. Multiple classes may be separated
479 by spaces or commas.
480 --default-image-extension=EXTENSION
482 Specify a default extension to use when image paths/URLs have no
483 extension. This allows you to use the same source for formats
484 that require different kinds of images. Currently this option
485 only affects the Markdown and LaTeX readers.
486 --file-scope
488 Parse each file individually before combining for multifile doc‐
489 uments. This will allow footnotes in different files with the
490 same identifiers to work as expected. If this option is set,
491 footnotes and links will not work across files. Reading binary
492 files (docx, odt, epub) implies --file-scope.
493 -F PROGRAM, --filter=PROGRAM
495 Specify an executable to be used as a filter transforming the
496 pandoc AST after the input is parsed and before the output is
497 written. The executable should read JSON from stdin and write
498 JSON to stdout. The JSON must be formatted like pandoc’s own
499 JSON input and output. The name of the output format will be
500 passed to the filter as the first argument. Hence,
501 pandoc --filter ./caps.py -t latex
503 is equivalent to
505 pandoc -t json | ./caps.py latex | pandoc -f json -t latex
507 The latter form may be useful for debugging filters.
509 Filters may be written in any language. Text.Pandoc.JSON ex‐
511 ports toJSONFilter to facilitate writing filters in Haskell.
512 Those who would prefer to write filters in python can use the
513 module pandocfilters, installable from PyPI. There are also
514 pandoc filter libraries in PHP, perl, and JavaScript/node.js.
515 In order of preference, pandoc will look for filters in
517 1. a specified full or relative path (executable or non-exe‐
519 cutable)
520 2. $DATADIR/filters (executable or non-executable) where
522 $DATADIR is the user data directory (see --data-dir, above).
523 3. $PATH (executable only)
525 Filters, Lua-filters, and citeproc processing are applied in the
527 order specified on the command line.
528 -L SCRIPT, --lua-filter=SCRIPT
530 Transform the document in a similar fashion as JSON filters (see
531 --filter), but use pandoc’s built-in Lua filtering system. The
532 given Lua script is expected to return a list of Lua filters
533 which will be applied in order. Each Lua filter must contain
534 element-transforming functions indexed by the name of the AST
535 element on which the filter function should be applied.
536 The pandoc Lua module provides helper functions for element cre‐
538 ation. It is always loaded into the script’s Lua environment.
539 See the Lua filters documentation for further details.
541 In order of preference, pandoc will look for Lua filters in
543 1. a specified full or relative path
545 2. $DATADIR/filters where $DATADIR is the user data directory
547 (see --data-dir, above).
548 Filters, Lua filters, and citeproc processing are applied in the
550 order specified on the command line.
551 -M KEY[=VAL], --metadata=KEY[:VAL]
553 Set the metadata field KEY to the value VAL. A value specified
554 on the command line overrides a value specified in the document
555 using YAML metadata blocks. Values will be parsed as YAML bool‐
556 ean or string values. If no value is specified, the value will
557 be treated as Boolean true. Like --variable, --metadata causes
558 template variables to be set. But unlike --variable, --metadata
559 affects the metadata of the underlying document (which is acces‐
560 sible from filters and may be printed in some output formats)
561 and metadata values will be escaped when inserted into the tem‐
562 plate.
563 --metadata-file=FILE
565 Read metadata from the supplied YAML (or JSON) file. This op‐
566 tion can be used with every input format, but string scalars in
567 the YAML file will always be parsed as Markdown. Generally, the
568 input will be handled the same as in YAML metadata blocks. This
569 option can be used repeatedly to include multiple metadata
570 files; values in files specified later on the command line will
571 be preferred over those specified in earlier files. Metadata
572 values specified inside the document, or by using -M, overwrite
573 values specified with this option.
574 -p, --preserve-tabs
576 Preserve tabs instead of converting them to spaces. (By de‐
577 fault, pandoc converts tabs to spaces before parsing its input.)
578 Note that this will only affect tabs in literal code spans and
579 code blocks. Tabs in regular text are always treated as spaces.
580 --tab-stop=NUMBER
582 Specify the number of spaces per tab (default is 4).
583 --track-changes=accept|reject|all
585 Specifies what to do with insertions, deletions, and comments
586 produced by the MS Word “Track Changes” feature. accept (the
587 default) processes all the insertions and deletions. reject ig‐
588 nores them. Both accept and reject ignore comments. all in‐
589 cludes all insertions, deletions, and comments, wrapped in spans
590 with insertion, deletion, comment-start, and comment-end class‐
591 es, respectively. The author and time of change is included.
592 all is useful for scripting: only accepting changes from a cer‐
593 tain reviewer, say, or before a certain date. If a paragraph is
594 inserted or deleted, track-changes=all produces a span with the
595 class paragraph-insertion/paragraph-deletion before the affected
596 paragraph break. This option only affects the docx reader.
597 --extract-media=DIR
599 Extract images and other media contained in or linked from the
600 source document to the path DIR, creating it if necessary, and
601 adjust the images references in the document so they point to
602 the extracted files. Media are downloaded, read from the file
603 system, or extracted from a binary container (e.g. docx), as
604 needed. The original file paths are used if they are relative
605 paths not containing ... Otherwise filenames are constructed
606 from the SHA1 hash of the contents.
607 --abbreviations=FILE
609 Specifies a custom abbreviations file, with abbreviations one to
610 a line. If this option is not specified, pandoc will read the
611 data file abbreviations from the user data directory or fall
612 back on a system default. To see the system default, use pandoc
613 --print-default-data-file=abbreviations. The only use pandoc
614 makes of this list is in the Markdown reader. Strings found in
615 this list will be followed by a nonbreaking space, and the peri‐
616 od will not produce sentence-ending space in formats like LaTeX.
617 The strings may not contain spaces.
618 General writer options
620 -s, --standalone
621 Produce output with an appropriate header and footer (e.g. a
622 standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This
623 option is set automatically for pdf, epub, epub3, fb2, docx, and
624 odt output. For native output, this option causes metadata to
625 be included; otherwise, metadata is suppressed.
626 --template=FILE|URL
628 Use the specified file as a custom template for the generated
629 document. Implies --standalone. See Templates, below, for a
630 description of template syntax. If no extension is specified,
631 an extension corresponding to the writer will be added, so that
632 --template=special looks for special.html for HTML output. If
633 the template is not found, pandoc will search for it in the tem‐
634 plates subdirectory of the user data directory (see --data-dir).
635 If this option is not used, a default template appropriate for
636 the output format will be used (see -D/--print-default-tem‐
637 plate).
638 -V KEY[=VAL], --variable=KEY[:VAL]
640 Set the template variable KEY to the value VAL when rendering
641 the document in standalone mode. If no VAL is specified, the
642 key will be given the value true.
643 -D FORMAT, --print-default-template=FORMAT
645 Print the system default template for an output FORMAT. (See -t
646 for a list of possible FORMATs.) Templates in the user data di‐
647 rectory are ignored. This option may be used with -o/--output
648 to redirect output to a file, but -o/--output must come before
649 --print-default-template on the command line.
650 Note that some of the default templates use partials, for exam‐
652 ple styles.html. To print the partials, use --print-default-da‐
653 ta-file: for example, --print-default-data-file=tem‐
654 plates/styles.html.
655 --print-default-data-file=FILE
657 Print a system default data file. Files in the user data direc‐
658 tory are ignored. This option may be used with -o/--output to
659 redirect output to a file, but -o/--output must come before
660 --print-default-data-file on the command line.
661 --eol=crlf|lf|native
663 Manually specify line endings: crlf (Windows), lf (macOS/Lin‐
664 ux/UNIX), or native (line endings appropriate to the OS on which
665 pandoc is being run). The default is native.
666 --dpi=NUMBER
668 Specify the default dpi (dots per inch) value for conversion
669 from pixels to inch/centimeters and vice versa. (Technically,
670 the correct term would be ppi: pixels per inch.) The default is
671 96dpi. When images contain information about dpi internally,
672 the encoded value is used instead of the default specified by
673 this option.
674 --wrap=auto|none|preserve
676 Determine how text is wrapped in the output (the source code,
677 not the rendered version). With auto (the default), pandoc will
678 attempt to wrap lines to the column width specified by --columns
679 (default 72). With none, pandoc will not wrap lines at all.
680 With preserve, pandoc will attempt to preserve the wrapping from
681 the source document (that is, where there are nonsemantic new‐
682 lines in the source, there will be nonsemantic newlines in the
683 output as well). Automatic wrapping does not currently work in
684 HTML output. In ipynb output, this option affects wrapping of
685 the contents of markdown cells.
686 --columns=NUMBER
688 Specify length of lines in characters. This affects text wrap‐
689 ping in the generated source code (see --wrap). It also affects
690 calculation of column widths for plain text tables (see Tables
691 below).
692 --toc, --table-of-contents
694 Include an automatically generated table of contents (or, in the
695 case of latex, context, docx, odt, opendocument, rst, or ms, an
696 instruction to create one) in the output document. This option
697 has no effect unless -s/--standalone is used, and it has no ef‐
698 fect on man, docbook4, docbook5, or jats output.
699 Note that if you are producing a PDF via ms, the table of con‐
701 tents will appear at the beginning of the document, before the
702 title. If you would prefer it to be at the end of the document,
703 use the option --pdf-engine-opt=--no-toc-relocation.
704 --toc-depth=NUMBER
706 Specify the number of section levels to include in the table of
707 contents. The default is 3 (which means that level-1, 2, and 3
708 headings will be listed in the contents).
709 --strip-comments
711 Strip out HTML comments in the Markdown or Textile source,
712 rather than passing them on to Markdown, Textile or HTML output
713 as raw HTML. This does not apply to HTML comments inside raw
714 HTML blocks when the markdown_in_html_blocks extension is not
715 set.
716 --no-highlight
718 Disables syntax highlighting for code blocks and inlines, even
719 when a language attribute is given.
720 --highlight-style=STYLE|FILE
722 Specifies the coloring style to be used in highlighted source
723 code. Options are pygments (the default), kate, monochrome,
724 breezeDark, espresso, zenburn, haddock, and tango. For more in‐
725 formation on syntax highlighting in pandoc, see Syntax high‐
726 lighting, below. See also --list-highlight-styles.
727 Instead of a STYLE name, a JSON file with extension .theme may
729 be supplied. This will be parsed as a KDE syntax highlighting
730 theme and (if valid) used as the highlighting style.
731 To generate the JSON version of an existing style, use --print-
733 highlight-style.
734 --print-highlight-style=STYLE|FILE
736 Prints a JSON version of a highlighting style, which can be mod‐
737 ified, saved with a .theme extension, and used with --highlight-
738 style. This option may be used with -o/--output to redirect
739 output to a file, but -o/--output must come before --print-high‐
740 light-style on the command line.
741 --syntax-definition=FILE
743 Instructs pandoc to load a KDE XML syntax definition file, which
744 will be used for syntax highlighting of appropriately marked
745 code blocks. This can be used to add support for new languages
746 or to use altered syntax definitions for existing languages.
747 This option may be repeated to add multiple syntax definitions.
748 -H FILE, --include-in-header=FILE|URL
750 Include contents of FILE, verbatim, at the end of the header.
751 This can be used, for example, to include special CSS or Java‐
752 Script in HTML documents. This option can be used repeatedly to
753 include multiple files in the header. They will be included in
754 the order specified. Implies --standalone.
755 -B FILE, --include-before-body=FILE|URL
757 Include contents of FILE, verbatim, at the beginning of the doc‐
758 ument body (e.g. after the <body> tag in HTML, or the \be‐
759 gin{document} command in LaTeX). This can be used to include
760 navigation bars or banners in HTML documents. This option can
761 be used repeatedly to include multiple files. They will be in‐
762 cluded in the order specified. Implies --standalone.
763 -A FILE, --include-after-body=FILE|URL
765 Include contents of FILE, verbatim, at the end of the document
766 body (before the </body> tag in HTML, or the \end{document} com‐
767 mand in LaTeX). This option can be used repeatedly to include
768 multiple files. They will be included in the order specified.
769 Implies --standalone.
770 --resource-path=SEARCHPATH
772 List of paths to search for images and other resources. The
773 paths should be separated by : on Linux, UNIX, and macOS sys‐
774 tems, and by ; on Windows. If --resource-path is not specified,
775 the default resource path is the working directory. Note that,
776 if --resource-path is specified, the working directory must be
777 explicitly listed or it will not be searched. For example:
778 --resource-path=.:test will search the working directory and the
779 test subdirectory, in that order. This option can be used re‐
780 peatedly. Search path components that come later on the command
781 line will be searched before those that come earlier, so --re‐
782 source-path foo:bar --resource-path baz:bim is equivalent to
783 --resource-path baz:bim:foo:bar.
784 --request-header=NAME:VAL
786 Set the request header NAME to the value VAL when making HTTP
787 requests (for example, when a URL is given on the command line,
788 or when resources used in a document must be downloaded). If
789 you’re behind a proxy, you also need to set the environment
790 variable http_proxy to http://....
791 --no-check-certificate
793 Disable the certificate verification to allow access to unsecure
794 HTTP resources (for example when the certificate is no longer
795 valid or self signed).
796 Options affecting specific writers
798 --self-contained
799 Produce a standalone HTML file with no external dependencies,
800 using data: URIs to incorporate the contents of linked scripts,
801 stylesheets, images, and videos. Implies --standalone. The re‐
802 sulting file should be “self-contained,” in the sense that it
803 needs no external files and no net access to be displayed prop‐
804 erly by a browser. This option works only with HTML output for‐
805 mats, including html4, html5, html+lhs, html5+lhs, s5, slidy,
806 slideous, dzslides, and revealjs. Scripts, images, and
807 stylesheets at absolute URLs will be downloaded; those at rela‐
808 tive URLs will be sought relative to the working directory (if
809 the first source file is local) or relative to the base URL (if
810 the first source file is remote). Elements with the attribute
811 data-external="1" will be left alone; the documents they link to
812 will not be incorporated in the document. Limitation: resources
813 that are loaded dynamically through JavaScript cannot be incor‐
814 porated; as a result, --self-contained does not work with
815 --mathjax, and some advanced features (e.g. zoom or speaker
816 notes) may not work in an offline “self-contained” reveal.js
817 slide show.
818 --html-q-tags
820 Use <q> tags for quotes in HTML. (This option only has an ef‐
821 fect if the smart extension is enabled for the input format
822 used.)
823 --ascii
825 Use only ASCII characters in output. Currently supported for
826 XML and HTML formats (which use entities instead of UTF-8 when
827 this option is selected), CommonMark, gfm, and Markdown (which
828 use entities), roff ms (which use hexadecimal escapes), and to a
829 limited degree LaTeX (which uses standard commands for accented
830 characters when possible). roff man output uses ASCII by de‐
831 fault.
832 --reference-links
834 Use reference-style links, rather than inline links, in writing
835 Markdown or reStructuredText. By default inline links are used.
836 The placement of link references is affected by the --reference-
837 location option.
838 --reference-location=block|section|document
840 Specify whether footnotes (and references, if reference-links is
841 set) are placed at the end of the current (top-level) block, the
842 current section, or the document. The default is document.
843 Currently only affects the markdown writer.
844 --markdown-headings=setext|atx
846 Specify whether to use ATX-style (#-prefixed) or Setext-style
847 (underlined) headings for level 1 and 2 headings in Markdown
848 output. (The default is atx.) ATX-style headings are always
849 used for levels 3+. This option also affects Markdown cells in
850 ipynb output.
851 --atx-headers
853 Deprecated synonym for --markdown-headings=atx.
854 --top-level-division=default|section|chapter|part
856 Treat top-level headings as the given division type in LaTeX,
857 ConTeXt, DocBook, and TEI output. The hierarchy order is part,
858 chapter, then section; all headings are shifted such that the
859 top-level heading becomes the specified type. The default be‐
860 havior is to determine the best division type via heuristics:
861 unless other conditions apply, section is chosen. When the doc‐
862 umentclass variable is set to report, book, or memoir (unless
863 the article option is specified), chapter is implied as the set‐
864 ting for this option. If beamer is the output format, specify‐
865 ing either chapter or part will cause top-level headings to be‐
866 come \part{..}, while second-level headings remain as their de‐
867 fault type.
868 -N, --number-sections
870 Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or
871 EPUB output. By default, sections are not numbered. Sections
872 with class unnumbered will never be numbered, even if --number-
873 sections is specified.
874 --number-offset=NUMBER[,NUMBER,...]
876 Offset for section headings in HTML output (ignored in other
877 output formats). The first number is added to the section num‐
878 ber for top-level headings, the second for second-level head‐
879 ings, and so on. So, for example, if you want the first top-
880 level heading in your document to be numbered “6”, specify
881 --number-offset=5. If your document starts with a level-2 head‐
882 ing which you want to be numbered “1.5”, specify --number-off‐
883 set=1,4. Offsets are 0 by default. Implies --number-sections.
884 --listings
886 Use the listings package for LaTeX code blocks. The package
887 does not support multi-byte encoding for source code. To handle
888 UTF-8 you would need to use a custom template. This issue is
889 fully documented here: Encoding issue with the listings package.
890 -i, --incremental
892 Make list items in slide shows display incrementally (one by
893 one). The default is for lists to be displayed all at once.
894 --slide-level=NUMBER
896 Specifies that headings with the specified level create slides
897 (for beamer, s5, slidy, slideous, dzslides). Headings above
898 this level in the hierarchy are used to divide the slide show
899 into sections; headings below this level create subheads within
900 a slide. Note that content that is not contained under slide-
901 level headings will not appear in the slide show. The default
902 is to set the slide level based on the contents of the document;
903 see Structuring the slide show.
904 --section-divs
906 Wrap sections in <section> tags (or <div> tags for html4), and
907 attach identifiers to the enclosing <section> (or <div>) rather
908 than the heading itself. See Heading identifiers, below.
909 --email-obfuscation=none|javascript|references
911 Specify a method for obfuscating mailto: links in HTML docu‐
912 ments. none leaves mailto: links as they are. javascript ob‐
913 fuscates them using JavaScript. references obfuscates them by
914 printing their letters as decimal or hexadecimal character ref‐
915 erences. The default is none.
916 --id-prefix=STRING
918 Specify a prefix to be added to all identifiers and internal
919 links in HTML and DocBook output, and to footnote numbers in
920 Markdown and Haddock output. This is useful for preventing du‐
921 plicate identifiers when generating fragments to be included in
922 other pages.
923 -T STRING, --title-prefix=STRING
925 Specify STRING as a prefix at the beginning of the title that
926 appears in the HTML header (but not in the title as it appears
927 at the beginning of the HTML body). Implies --standalone.
928 -c URL, --css=URL
930 Link to a CSS style sheet. This option can be used repeatedly
931 to include multiple files. They will be included in the order
932 specified.
933 A stylesheet is required for generating EPUB. If none is pro‐
935 vided using this option (or the css or stylesheet metadata
936 fields), pandoc will look for a file epub.css in the user data
937 directory (see --data-dir). If it is not found there, sensible
938 defaults will be used.
939 --reference-doc=FILE
941 Use the specified file as a style reference in producing a docx
942 or ODT file.
943 Docx For best results, the reference docx should be a modified
945 version of a docx file produced using pandoc. The con‐
946 tents of the reference docx are ignored, but its
947 stylesheets and document properties (including margins,
948 page size, header, and footer) are used in the new docx.
949 If no reference docx is specified on the command line,
950 pandoc will look for a file reference.docx in the user
951 data directory (see --data-dir). If this is not found
952 either, sensible defaults will be used.
953 To produce a custom reference.docx, first get a copy of
955 the default reference.docx: pandoc -o custom-refer‐
956 ence.docx --print-default-data-file reference.docx. Then
957 open custom-reference.docx in Word, modify the styles as
958 you wish, and save the file. For best results, do not
959 make changes to this file other than modifying the styles
960 used by pandoc:
961 Paragraph styles:
963 • Normal
965 • Body Text
967 • First Paragraph
969 • Compact
971 • Title
973 • Subtitle
975 • Author
977 • Date
979 • Abstract
981 • Bibliography
983 • Heading 1
985 • Heading 2
987 • Heading 3
989 • Heading 4
991 • Heading 5
993 • Heading 6
995 • Heading 7
997 • Heading 8
999 • Heading 9
1001 • Block Text
1003 • Footnote Text
1005 • Definition Term
1007 • Definition
1009 • Caption
1011 • Table Caption
1013 • Image Caption
1015 • Figure
1017 • Captioned Figure
1019 • TOC Heading
1021 Character styles:
1023 • Default Paragraph Font
1025 • Body Text Char
1027 • Verbatim Char
1029 • Footnote Reference
1031 • Hyperlink
1033 • Section Number
1035 Table style:
1037 • Table
1039 ODT For best results, the reference ODT should be a modified
1041 version of an ODT produced using pandoc. The contents of
1042 the reference ODT are ignored, but its stylesheets are
1043 used in the new ODT. If no reference ODT is specified on
1044 the command line, pandoc will look for a file refer‐
1045 ence.odt in the user data directory (see --data-dir). If
1046 this is not found either, sensible defaults will be used.
1047 To produce a custom reference.odt, first get a copy of
1049 the default reference.odt: pandoc -o custom-reference.odt
1050 --print-default-data-file reference.odt. Then open cus‐
1051 tom-reference.odt in LibreOffice, modify the styles as
1052 you wish, and save the file.
1053 PowerPoint
1055 Templates included with Microsoft PowerPoint 2013 (either
1056 with .pptx or .potx extension) are known to work, as are
1057 most templates derived from these.
1058 The specific requirement is that the template should be‐
1060 gin with the following first four layouts:
1061 1. Title Slide
1063 2. Title and Content
1065 3. Section Header
1067 4. Two Content
1069 All templates included with a recent version of MS Power‐
1071 Point will fit these criteria. (You can click on Layout
1072 under the Home menu to check.)
1073 You can also modify the default reference.pptx: first run
1075 pandoc -o custom-reference.pptx --print-default-data-file
1076 reference.pptx, and then modify custom-reference.pptx in
1077 MS PowerPoint (pandoc will use the first four layout
1078 slides, as mentioned above).
1079 --epub-cover-image=FILE
1081 Use the specified image as the EPUB cover. It is recommended
1082 that the image be less than 1000px in width and height. Note
1083 that in a Markdown source document you can also specify cover-
1084 image in a YAML metadata block (see EPUB Metadata, below).
1085 --epub-metadata=FILE
1087 Look in the specified XML file for metadata for the EPUB. The
1088 file should contain a series of Dublin Core elements. For exam‐
1089 ple:
1090 <dc:rights>Creative Commons</dc:rights>
1092 <dc:language>es-AR</dc:language>
1093 By default, pandoc will include the following metadata elements:
1095 <dc:title> (from the document title), <dc:creator> (from the
1096 document authors), <dc:date> (from the document date, which
1097 should be in ISO 8601 format), <dc:language> (from the lang
1098 variable, or, if is not set, the locale), and <dc:identifier
1099 id="BookId"> (a randomly generated UUID). Any of these may be
1100 overridden by elements in the metadata file.
1101 Note: if the source document is Markdown, a YAML metadata block
1103 in the document can be used instead. See below under EPUB Meta‐
1104 data.
1105 --epub-embed-font=FILE
1107 Embed the specified font in the EPUB. This option can be re‐
1108 peated to embed multiple fonts. Wildcards can also be used: for
1109 example, DejaVuSans-*.ttf. However, if you use wildcards on the
1110 command line, be sure to escape them or put the whole filename
1111 in single quotes, to prevent them from being interpreted by the
1112 shell. To use the embedded fonts, you will need to add declara‐
1113 tions like the following to your CSS (see --css):
1114 @font-face {
1116 font-family: DejaVuSans;
1117 font-style: normal;
1118 font-weight: normal;
1119 src:url("DejaVuSans-Regular.ttf");
1120 }
1121 @font-face {
1122 font-family: DejaVuSans;
1123 font-style: normal;
1124 font-weight: bold;
1125 src:url("DejaVuSans-Bold.ttf");
1126 }
1127 @font-face {
1128 font-family: DejaVuSans;
1129 font-style: italic;
1130 font-weight: normal;
1131 src:url("DejaVuSans-Oblique.ttf");
1132 }
1133 @font-face {
1134 font-family: DejaVuSans;
1135 font-style: italic;
1136 font-weight: bold;
1137 src:url("DejaVuSans-BoldOblique.ttf");
1138 }
1139 body { font-family: "DejaVuSans"; }
1140 --epub-chapter-level=NUMBER
1142 Specify the heading level at which to split the EPUB into sepa‐
1143 rate “chapter” files. The default is to split into chapters at
1144 level-1 headings. This option only affects the internal compo‐
1145 sition of the EPUB, not the way chapters and sections are dis‐
1146 played to users. Some readers may be slow if the chapter files
1147 are too large, so for large documents with few level-1 headings,
1148 one might want to use a chapter level of 2 or 3.
1149 --epub-subdirectory=DIRNAME
1151 Specify the subdirectory in the OCF container that is to hold
1152 the EPUB-specific contents. The default is EPUB. To put the
1153 EPUB contents in the top level, use an empty string.
1154 --ipynb-output=all|none|best
1156 Determines how ipynb output cells are treated. all means that
1157 all of the data formats included in the original are preserved.
1158 none means that the contents of data cells are omitted. best
1159 causes pandoc to try to pick the richest data block in each out‐
1160 put cell that is compatible with the output format. The default
1161 is best.
1162 --pdf-engine=PROGRAM
1164 Use the specified engine when producing PDF output. Valid val‐
1165 ues are pdflatex, lualatex, xelatex, latexmk, tectonic, wkhtml‐
1166 topdf, weasyprint, prince, context, and pdfroff. If the engine
1167 is not in your PATH, the full path of the engine may be speci‐
1168 fied here. If this option is not specified, pandoc uses the
1169 following defaults depending on the output format specified us‐
1170 ing -t/--to:
1171 • -t latex or none: pdflatex (other options: xelatex, lualatex,
1173 tectonic, latexmk)
1174 • -t context: context
1176 • -t html: wkhtmltopdf (other options: prince, weasyprint; see
1178 print-css.rocks for a good introduction to PDF generation from
1179 HTML/CSS.)
1180 • -t ms: pdfroff
1182 --pdf-engine-opt=STRING
1184 Use the given string as a command-line argument to the pdf-en‐
1185 gine. For example, to use a persistent directory foo for la‐
1186 texmk’s auxiliary files, use --pdf-engine-opt=-outdir=foo. Note
1187 that no check for duplicate options is done.
1188 Citation rendering
1190 -C, --citeproc
1191 Process the citations in the file, replacing them with rendered
1192 citations and adding a bibliography. Citation processing will
1193 not take place unless bibliographic data is supplied, either
1194 through an external file specified using the --bibliography op‐
1195 tion or the bibliography field in metadata, or via a references
1196 section in metadata containing a list of citations in CSL YAML
1197 format with Markdown formatting. The style is controlled by a
1198 CSL stylesheet specified using the --csl option or the csl field
1199 in metadata. (If no stylesheet is specified, the chicago-au‐
1200 thor-date style will be used by default.) The citation process‐
1201 ing transformation may be applied before or after filters or Lua
1202 filters (see --filter, --lua-filter): these transformations are
1203 applied in the order they appear on the command line. For more
1204 information, see the section on Citations.
1205 --bibliography=FILE
1207 Set the bibliography field in the document’s metadata to FILE,
1208 overriding any value set in the metadata. If you supply this
1209 argument multiple times, each FILE will be added to bibliogra‐
1210 phy. If FILE is a URL, it will be fetched via HTTP. If FILE is
1211 not found relative to the working directory, it will be sought
1212 in the resource path (see --resource-path).
1213 --csl=FILE
1215 Set the csl field in the document’s metadata to FILE, overriding
1216 any value set in the metadata. (This is equivalent to --metada‐
1217 ta csl=FILE.) If FILE is a URL, it will be fetched via HTTP. If
1218 FILE is not found relative to the working directory, it will be
1219 sought in the resource path (see --resource-path) and finally in
1220 the csl subdirectory of the pandoc user data directory.
1221 --citation-abbreviations=FILE
1223 Set the citation-abbreviations field in the document’s metadata
1224 to FILE, overriding any value set in the metadata. (This is
1225 equivalent to --metadata citation-abbreviations=FILE.) If FILE
1226 is a URL, it will be fetched via HTTP. If FILE is not found
1227 relative to the working directory, it will be sought in the re‐
1228 source path (see --resource-path) and finally in the csl subdi‐
1229 rectory of the pandoc user data directory.
1230 --natbib
1232 Use natbib for citations in LaTeX output. This option is not
1233 for use with the --citeproc option or with PDF output. It is
1234 intended for use in producing a LaTeX file that can be processed
1235 with bibtex.
1236 --biblatex
1238 Use biblatex for citations in LaTeX output. This option is not
1239 for use with the --citeproc option or with PDF output. It is
1240 intended for use in producing a LaTeX file that can be processed
1241 with bibtex or biber.
1242 Math rendering in HTML
1244 The default is to render TeX math as far as possible using Unicode
1245 characters. Formulas are put inside a span with class="math", so that
1246 they may be styled differently from the surrounding text if needed.
1247 However, this gives acceptable results only for basic math, usually you
1248 will want to use --mathjax or another of the following options.
1249 --mathjax[=URL]
1251 Use MathJax to display embedded TeX math in HTML output. TeX
1252 math will be put between \(...\) (for inline math) or \[...\]
1253 (for display math) and wrapped in <span> tags with class math.
1254 Then the MathJax JavaScript will render it. The URL should
1255 point to the MathJax.js load script. If a URL is not provided,
1256 a link to the Cloudflare CDN will be inserted.
1257 --mathml
1259 Convert TeX math to MathML (in epub3, docbook4, docbook5, jats,
1260 html4 and html5). This is the default in odt output. Note that
1261 currently only Firefox and Safari (and select e-book readers)
1262 natively support MathML.
1263 --webtex[=URL]
1265 Convert TeX formulas to <img> tags that link to an external
1266 script that converts formulas to images. The formula will be
1267 URL-encoded and concatenated with the URL provided. For SVG im‐
1268 ages you can for example use --webtex https://la‐
1269 tex.codecogs.com/svg.latex?. If no URL is specified, the
1270 CodeCogs URL generating PNGs will be used (https://la‐
1271 tex.codecogs.com/png.latex?). Note: the --webtex option will
1272 affect Markdown output as well as HTML, which is useful if
1273 you’re targeting a version of Markdown without native math sup‐
1274 port.
1275 --katex[=URL]
1277 Use KaTeX to display embedded TeX math in HTML output. The URL
1278 is the base URL for the KaTeX library. That directory should
1279 contain a katex.min.js and a katex.min.css file. If a URL is
1280 not provided, a link to the KaTeX CDN will be inserted.
1281 --gladtex
1283 Enclose TeX math in <eq> tags in HTML output. The resulting
1284 HTML can then be processed by GladTeX to produce SVG images of
1285 the typeset formulas and an HTML file with these images embed‐
1286 ded.
1287 pandoc -s --gladtex input.md -o myfile.htex
1289 gladtex -d image_dir myfile.htex
1290 # produces myfile.html and images in image_dir
1291 Options for wrapper scripts
1293 --dump-args
1294 Print information about command-line arguments to stdout, then
1295 exit. This option is intended primarily for use in wrapper
1296 scripts. The first line of output contains the name of the out‐
1297 put file specified with the -o option, or - (for stdout) if no
1298 output file was specified. The remaining lines contain the com‐
1299 mand-line arguments, one per line, in the order they appear.
1300 These do not include regular pandoc options and their arguments,
1301 but do include any options appearing after a -- separator at the
1302 end of the line.
1303 --ignore-args
1305 Ignore command-line arguments (for use in wrapper scripts).
1306 Regular pandoc options are not ignored. Thus, for example,
1307 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1309 is equivalent to
1311 pandoc -o foo.html -s
1313
1315 If pandoc completes successfully, it will return exit code 0. Nonzero
1316 exit codes have the following meanings:
1317 Code Error
1319 ─────────────────────────────────
1320 3 PandocFailOnWarningError
1321 4 PandocAppError
1322 5 PandocTemplateError
1323 6 PandocOptionError
1324 21 PandocUnknownReaderError
1325 22 PandocUnknownWriterError
1326 23 PandocUnsupportedExten‐
1327 sionError
1328 24 PandocCiteprocError
1329 31 PandocEpubSubdirectoryEr‐
1330 ror
1331 43 PandocPDFError
1332 44 PandocXMLError
1333 47 PandocPDFProgramNot‐
1334 FoundError
1335 61 PandocHttpError
1336 62 PandocShouldNeverHappen‐
1337 Error
1338 63 PandocSomeError
1339 64 PandocParseError
1340 65 PandocParsecError
1341 66 PandocMakePDFError
1342 67 PandocSyntaxMapError
1343 83 PandocFilterError
1344 91 PandocMacroLoop
1345 92 PandocUTF8DecodingError
1346 93 PandocIpynbDecodingError
1347 94 PandocUnsupported‐
1348 CharsetError
1349 97 PandocCouldNotFind‐
1350 DataFileError
1351 99 PandocResourceNotFound
1352
1354 The --defaults option may be used to specify a package of options.
1355 Here is a sample defaults file demonstrating all of the fields that may
1356 be used:
1357 from: markdown+emoji
1359 # reader: may be used instead of from:
1360 to: html5
1361 # writer: may be used instead of to:
1362 # leave blank for output to stdout:
1364 output-file:
1365 # leave blank for input from stdin, use [] for no input:
1366 input-files:
1367 - preface.md
1368 - content.md
1369 # or you may use input-file: with a single value
1370 # Include options from the specified defaults files.
1372 # The files will be searched for first in the working directory
1373 # and then in the defaults subdirectory of the user data directory.
1374 # The files are included in the same order in which they appear in
1375 # the list. Options specified in this defaults file always have
1376 # priority over the included ones.
1377 defaults:
1378 - defsA
1379 - defsB
1380 template: letter
1382 standalone: true
1383 self-contained: false
1384 # note that structured variables may be specified:
1386 variables:
1387 documentclass: book
1388 classoption:
1389 - twosides
1390 - draft
1391 # metadata values specified here are parsed as literal
1393 # string text, not markdown:
1394 metadata:
1395 author:
1396 - Sam Smith
1397 - Julie Liu
1398 metadata-files:
1399 - boilerplate.yaml
1400 # or you may use metadata-file: with a single value
1401 # Note that these take files, not their contents:
1403 include-before-body: []
1404 include-after-body: []
1405 include-in-header: []
1406 resource-path: ["."]
1407 # turn on built-in citation processing. Note that if you need
1409 # control over when the citeproc processing is done relative
1410 # to other filters, you should instead use `citeproc` in the
1411 # list of `filters` (see below).
1412 citeproc: true
1413 csl: ieee
1414 bibliography:
1415 - foobar.bib
1416 - barbaz.json
1417 citation-abbreviations: abbrevs.json
1418 # Filters will be assumed to be Lua filters if they have
1420 # the .lua extension, and json filters otherwise. But
1421 # the filter type can also be specified explicitly, as shown.
1422 # Filters are run in the order specified.
1423 # To include the built-in citeproc filter, use either `citeproc`
1424 # or `{type: citeproc}`.
1425 filters:
1426 - wordcount.lua
1427 - type: json
1428 path: foo.lua
1429 file-scope: false
1431 data-dir:
1433 # ERROR, WARNING, or INFO
1435 verbosity: INFO
1436 log-file: log.json
1437 # citeproc, natbib, or biblatex. This only affects LaTeX
1439 # output. If you want to use citeproc to format citations,
1440 # you should also set 'citeproc: true' (see above).
1441 cite-method: citeproc
1442 # part, chapter, section, or default:
1444 top-level-division: chapter
1445 abbreviations:
1446 pdf-engine: pdflatex
1448 pdf-engine-opts:
1449 - "-shell-escape"
1450 # you may also use pdf-engine-opt: with a single option
1451 # pdf-engine-opt: "-shell-escape"
1452 # auto, preserve, or none
1454 wrap: auto
1455 columns: 78
1456 dpi: 72
1457 extract-media: mediadir
1459 table-of-contents: true
1461 toc-depth: 2
1462 number-sections: false
1463 # a list of offsets at each heading level
1464 number-offset: [0,0,0,0,0,0]
1465 # toc: may also be used instead of table-of-contents:
1466 shift-heading-level-by: 1
1467 section-divs: true
1468 identifier-prefix: foo
1469 title-prefix: ""
1470 strip-empty-paragraphs: true
1471 # lf, crlf, or native
1472 eol: lf
1473 strip-comments: false
1474 indented-code-classes: []
1475 ascii: true
1476 default-image-extension: ".jpg"
1477 # either a style name of a style definition file:
1479 highlight-style: pygments
1480 syntax-definitions:
1481 - c.xml
1482 # or you may use syntax-definition: with a single value
1483 listings: false
1484 reference-doc: myref.docx
1486 # method is plain, webtex, gladtex, mathml, mathjax, katex
1488 # you may specify a url with webtex, mathjax, katex
1489 html-math-method:
1490 method: mathjax
1491 url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
1492 # none, references, or javascript
1493 email-obfuscation: javascript
1494 tab-stop: 8
1496 preserve-tabs: true
1497 incremental: false
1499 slide-level: 2
1500 epub-subdirectory: EPUB
1502 epub-metadata: meta.xml
1503 epub-fonts:
1504 - foobar.otf
1505 epub-chapter-level: 1
1506 epub-cover-image: cover.jpg
1507 reference-links: true
1509 # block, section, or document
1510 reference-location: block
1511 markdown-headings: setext
1512 # accept, reject, or all
1514 track-changes: accept
1515 html-q-tags: false
1517 css:
1518 - site.css
1519 # none, all, or best
1521 ipynb-output: best
1522 # A list of two-element lists
1524 request-headers:
1525 - ["User-Agent", "Mozilla/5.0"]
1526 fail-if-warnings: false
1528 dump-args: false
1529 ignore-args: false
1530 trace: false
1531 Fields that are omitted will just have their regular default values.
1533 So a defaults file can be as simple as one line:
1534 verbosity: INFO
1536 In fields that expect a file path (or list of file paths), the follow‐
1538 ing syntax may be used to interpolate environment variables:
1539 csl: ${HOME}/mycsldir/special.csl
1541 ${USERDATA} may also be used; this will always resolve to the user data
1543 directory that is current when the defaults file is parsed, regardless
1544 of the setting of the environment variable USERDATA.
1545 ${.} will resolve to the directory containing the default file itself.
1547 This allows you to refer to resources contained in that directory:
1548 epub-cover-image: ${.}/cover.jpg
1550 epub-metadata: ${.}/meta.xml
1551 resource-path:
1552 - . # the working directory from which pandoc is run
1553 - ${.}/images # the images subdirectory of the directory
1554 # containing this defaults file
1555 This environment variable interpolation syntax only works in fields
1557 that expect file paths.
1558 Default files can be placed in the defaults subdirectory of the user
1560 data directory and used from any directory. For example, one could
1561 create a file specifying defaults for writing letters, save it as let‐
1562 ter.yaml in the defaults subdirectory of the user data directory, and
1563 then invoke these defaults from any directory using pandoc --defaults
1564 letter or pandoc -dletter.
1565 When multiple defaults are used, their contents will be combined.
1567 Note that, where command-line arguments may be repeated (--metadata-
1569 file, --css, --include-in-header, --include-before-body, --include-af‐
1570 ter-body, --variable, --metadata, --syntax-definition), the values
1571 specified on the command line will combine with values specified in the
1572 defaults file, rather than replacing them.
1573
1575 When the -s/--standalone option is used, pandoc uses a template to add
1576 header and footer material that is needed for a self-standing document.
1577 To see the default template that is used, just type
1578 pandoc -D *FORMAT*
1580 where FORMAT is the name of the output format. A custom template can
1582 be specified using the --template option. You can also override the
1583 system default templates for a given output format FORMAT by putting a
1584 file templates/default.*FORMAT* in the user data directory (see --data-
1585 dir, above). Exceptions:
1586 • For odt output, customize the default.opendocument template.
1588 • For pdf output, customize the default.latex template (or the de‐
1590 fault.context template, if you use -t context, or the default.ms tem‐
1591 plate, if you use -t ms, or the default.html template, if you use -t
1592 html).
1593 • docx and pptx have no template (however, you can use --reference-doc
1595 to customize the output).
1596 Templates contain variables, which allow for the inclusion of arbitrary
1598 information at any point in the file. They may be set at the command
1599 line using the -V/--variable option. If a variable is not set, pandoc
1600 will look for the key in the document’s metadata, which can be set us‐
1601 ing either YAML metadata blocks or with the -M/--metadata option. In
1602 addition, some variables are given default values by pandoc. See Vari‐
1603 ables below for a list of variables used in pandoc’s default templates.
1604 If you use custom templates, you may need to revise them as pandoc
1606 changes. We recommend tracking the changes in the default templates,
1607 and modifying your custom templates accordingly. An easy way to do
1608 this is to fork the pandoc-templates repository and merge in changes
1609 after each pandoc release.
1610 Template syntax
1612 Comments
1613 Anything between the sequence $-- and the end of the line will be
1614 treated as a comment and omitted from the output.
1615 Delimiters
1617 To mark variables and control structures in the template, either $...$
1618 or ${...} may be used as delimiters. The styles may also be mixed in
1619 the same template, but the opening and closing delimiter must match in
1620 each case. The opening delimiter may be followed by one or more spaces
1621 or tabs, which will be ignored. The closing delimiter may be followed
1622 by one or more spaces or tabs, which will be ignored.
1623 To include a literal $ in the document, use $$.
1625 Interpolated variables
1627 A slot for an interpolated variable is a variable name surrounded by
1628 matched delimiters. Variable names must begin with a letter and can
1629 contain letters, numbers, _, -, and .. The keywords it, if, else, en‐
1630 dif, for, sep, and endfor may not be used as variable names. Examples:
1631 $foo$
1633 $foo.bar.baz$
1634 $foo_bar.baz-bim$
1635 $ foo $
1636 ${foo}
1637 ${foo.bar.baz}
1638 ${foo_bar.baz-bim}
1639 ${ foo }
1640 Variable names with periods are used to get at structured variable val‐
1642 ues. So, for example, employee.salary will return the value of the
1643 salary field of the object that is the value of the employee field.
1644 • If the value of the variable is simple value, it will be rendered
1646 verbatim. (Note that no escaping is done; the assumption is that the
1647 calling program will escape the strings appropriately for the output
1648 format.)
1649 • If the value is a list, the values will be concatenated.
1651 • If the value is a map, the string true will be rendered.
1653 • Every other value will be rendered as the empty string.
1655 Conditionals
1657 A conditional begins with if(variable) (enclosed in matched delimiters)
1658 and ends with endif (enclosed in matched delimiters). It may optional‐
1659 ly contain an else (enclosed in matched delimiters). The if section is
1660 used if variable has a non-empty value, otherwise the else section is
1661 used (if present). Examples:
1662 $if(foo)$bar$endif$
1664 $if(foo)$
1666 $foo$
1667 $endif$
1668 $if(foo)$
1670 part one
1671 $else$
1672 part two
1673 $endif$
1674 ${if(foo)}bar${endif}
1676 ${if(foo)}
1678 ${foo}
1679 ${endif}
1680 ${if(foo)}
1682 ${ foo.bar }
1683 ${else}
1684 no foo!
1685 ${endif}
1686 The keyword elseif may be used to simplify complex nested conditionals:
1688 $if(foo)$
1690 XXX
1691 $elseif(bar)$
1692 YYY
1693 $else$
1694 ZZZ
1695 $endif$
1696 For loops
1698 A for loop begins with for(variable) (enclosed in matched delimiters)
1699 and ends with endfor (enclosed in matched delimiters.
1700 • If variable is an array, the material inside the loop will be evalu‐
1702 ated repeatedly, with variable being set to each value of the array
1703 in turn, and concatenated.
1704 • If variable is a map, the material inside will be set to the map.
1706 • If the value of the associated variable is not an array or a map, a
1708 single iteration will be performed on its value.
1709 Examples:
1711 $for(foo)$$foo$$sep$, $endfor$
1713 $for(foo)$
1715 - $foo.last$, $foo.first$
1716 $endfor$
1717 ${ for(foo.bar) }
1719 - ${ foo.bar.last }, ${ foo.bar.first }
1720 ${ endfor }
1721 $for(mymap)$
1723 $it.name$: $it.office$
1724 $endfor$
1725 You may optionally specify a separator between consecutive values using
1727 sep (enclosed in matched delimiters). The material between sep and the
1728 endfor is the separator.
1729 ${ for(foo) }${ foo }${ sep }, ${ endfor }
1731 Instead of using variable inside the loop, the special anaphoric key‐
1733 word it may be used.
1734 ${ for(foo.bar) }
1736 - ${ it.last }, ${ it.first }
1737 ${ endfor }
1738 Partials
1740 Partials (subtemplates stored in different files) may be included by
1741 using the name of the partial, followed by (), for example:
1742 ${ styles() }
1744 Partials will be sought in the directory containing the main template.
1746 The file name will be assumed to have the same extension as the main
1747 template if it lacks an extension. When calling the partial, the full
1748 name including file extension can also be used:
1749 ${ styles.html() }
1751 (If a partial is not found in the directory of the template and the
1753 template path is given as a relative path, it will also be sought in
1754 the templates subdirectory of the user data directory.)
1755 Partials may optionally be applied to variables using a colon:
1757 ${ date:fancy() }
1759 ${ articles:bibentry() }
1761 If articles is an array, this will iterate over its values, applying
1763 the partial bibentry() to each one. So the second example above is
1764 equivalent to
1765 ${ for(articles) }
1767 ${ it:bibentry() }
1768 ${ endfor }
1769 Note that the anaphoric keyword it must be used when iterating over
1771 partials. In the above examples, the bibentry partial should contain
1772 it.title (and so on) instead of articles.title.
1773 Final newlines are omitted from included partials.
1775 Partials may include other partials.
1777 A separator between values of an array may be specified in square
1779 brackets, immediately after the variable name or partial:
1780 ${months[, ]}$
1782 ${articles:bibentry()[; ]$
1784 The separator in this case is literal and (unlike with sep in an ex‐
1786 plicit for loop) cannot contain interpolated variables or other tem‐
1787 plate directives.
1788 Nesting
1790 To ensure that content is “nested,” that is, subsequent lines indented,
1791 use the ^ directive:
1792 $item.number$ $^$$item.description$ ($item.price$)
1794 In this example, if item.description has multiple lines, they will all
1796 be indented to line up with the first line:
1797 00123 A fine bottle of 18-year old
1799 Oban whiskey. ($148)
1800 To nest multiple lines to the same level, align them with the ^ direc‐
1802 tive in the template. For example:
1803 $item.number$ $^$$item.description$ ($item.price$)
1805 (Available til $item.sellby$.)
1806 will produce
1808 00123 A fine bottle of 18-year old
1810 Oban whiskey. ($148)
1811 (Available til March 30, 2020.)
1812 If a variable occurs by itself on a line, preceded by whitespace and
1814 not followed by further text or directives on the same line, and the
1815 variable’s value contains multiple lines, it will be nested automati‐
1816 cally.
1817 Breakable spaces
1819 Normally, spaces in the template itself (as opposed to values of the
1820 interpolated variables) are not breakable, but they can be made break‐
1821 able in part of the template by using the ~ keyword (ended with another
1822 ~).
1823 $~$This long line may break if the document is rendered
1825 with a short line length.$~$
1826 Pipes
1828 A pipe transforms the value of a variable or partial. Pipes are speci‐
1829 fied using a slash (/) between the variable name (or partial) and the
1830 pipe name. Example:
1831 $for(name)$
1833 $name/uppercase$
1834 $endfor$
1835 $for(metadata/pairs)$
1837 - $it.key$: $it.value$
1838 $endfor$
1839 $employee:name()/uppercase$
1841 Pipes may be chained:
1843 $for(employees/pairs)$
1845 $it.key/alpha/uppercase$. $it.name$
1846 $endfor$
1847 Some pipes take parameters:
1849 |----------------------|------------|
1851 $for(employee)$
1852 $it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
1853 $endfor$
1854 |----------------------|------------|
1855 Currently the following pipes are predefined:
1857 • pairs: Converts a map or array to an array of maps, each with key and
1859 value fields. If the original value was an array, the key will be
1860 the array index, starting with 1.
1861 • uppercase: Converts text to uppercase.
1863 • lowercase: Converts text to lowercase.
1865 • length: Returns the length of the value: number of characters for a
1867 textual value, number of elements for a map or array.
1868 • reverse: Reverses a textual value or array, and has no effect on oth‐
1870 er values.
1871 • first: Returns the first value of an array, if applied to a non-empty
1873 array; otherwise returns the original value.
1874 • last: Returns the last value of an array, if applied to a non-empty
1876 array; otherwise returns the original value.
1877 • rest: Returns all but the first value of an array, if applied to a
1879 non-empty array; otherwise returns the original value.
1880 • allbutlast: Returns all but the last value of an array, if applied to
1882 a non-empty array; otherwise returns the original value.
1883 • chomp: Removes trailing newlines (and breakable space).
1885 • nowrap: Disables line wrapping on breakable spaces.
1887 • alpha: Converts textual values that can be read as an integer into
1889 lowercase alphabetic characters a..z (mod 26). This can be used to
1890 get lettered enumeration from array indices. To get uppercase let‐
1891 ters, chain with uppercase.
1892 • roman: Converts textual values that can be read as an integer into
1894 lowercase roman numerials. This can be used to get lettered enumera‐
1895 tion from array indices. To get uppercase roman, chain with upper‐
1896 case.
1897 • left n "leftborder" "rightborder": Renders a textual value in a block
1899 of width n, aligned to the left, with an optional left and right bor‐
1900 der. Has no effect on other values. This can be used to align mate‐
1901 rial in tables. Widths are positive integers indicating the number
1902 of characters. Borders are strings inside double quotes; literal "
1903 and \ characters must be backslash-escaped.
1904 • right n "leftborder" "rightborder": Renders a textual value in a
1906 block of width n, aligned to the right, and has no effect on other
1907 values.
1908 • center n "leftborder" "rightborder": Renders a textual value in a
1910 block of width n, aligned to the center, and has no effect on other
1911 values.
1912 Variables
1914 Metadata variables
1915 title, author, date
1916 allow identification of basic aspects of the document. Included
1917 in PDF metadata through LaTeX and ConTeXt. These can be set
1918 through a pandoc title block, which allows for multiple authors,
1919 or through a YAML metadata block:
1920 ---
1922 author:
1923 - Aristotle
1924 - Peter Abelard
1925 ...
1926 Note that if you just want to set PDF or HTML metadata, without
1928 including a title block in the document itself, you can set the
1929 title-meta, author-meta, and date-meta variables. (By default
1930 these are set automatically, based on title, author, and date.)
1931 The page title in HTML is set by pagetitle, which is equal to
1932 title by default.
1933 subtitle
1935 document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and
1936 docx documents
1937 abstract
1939 document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
1940 documents
1941 keywords
1943 list of keywords to be included in HTML, PDF, ODT, pptx, docx
1944 and AsciiDoc metadata; repeat as for author, above
1945 subject
1947 document subject, included in ODT, PDF, docx and pptx metadata
1948 description
1950 document description, included in ODT, docx and pptx metadata.
1951 Some applications show this as Comments metadata.
1952 category
1954 document category, included in docx and pptx metadata
1955 Additionally, any root-level string metadata, not included in ODT, docx
1957 or pptx metadata is added as a custom property. The following YAML
1958 metadata block for instance:
1959 ---
1961 title: 'This is the title'
1962 subtitle: "This is the subtitle"
1963 author:
1964 - Author One
1965 - Author Two
1966 description: |
1967 This is a long
1968 description.
1969 It consists of two paragraphs
1971 ...
1972 will include title, author and description as standard document proper‐
1974 ties and subtitle as a custom property when converting to docx, ODT or
1975 pptx.
1976 Language variables
1978 lang identifies the main language of the document using IETF language
1979 tags (following the BCP 47 standard), such as en or en-GB. The
1980 Language subtag lookup tool can look up or verify these tags.
1981 This affects most formats, and controls hyphenation in PDF out‐
1982 put when using LaTeX (through babel and polyglossia) or ConTeXt.
1983 Use native pandoc Divs and Spans with the lang attribute to
1985 switch the language:
1986 ---
1988 lang: en-GB
1989 ...
1990 Text in the main document language (British English).
1992 ::: {lang=fr-CA}
1994 > Cette citation est écrite en français canadien.
1995 :::
1996 More text in English. ['Zitat auf Deutsch.']{lang=de}
1998 dir the base script direction, either rtl (right-to-left) or ltr
2000 (left-to-right).
2001 For bidirectional documents, native pandoc spans and divs with
2003 the dir attribute (value rtl or ltr) can be used to override the
2004 base direction in some output formats. This may not always be
2005 necessary if the final renderer (e.g. the browser, when generat‐
2006 ing HTML) supports the Unicode Bidirectional Algorithm.
2007 When using LaTeX for bidirectional documents, only the xelatex
2009 engine is fully supported (use --pdf-engine=xelatex).
2010 Variables for HTML
2012 document-css
2013 Enables inclusion of most of the CSS in the styles.html partial
2014 (have a look with pandoc --print-default-data-file=tem‐
2015 plates/styles.html). Unless you use --css, this variable is set
2016 to true by default. You can disable it with e.g. pandoc -M doc‐
2017 ument-css=false.
2018 mainfont
2020 sets the CSS font-family property on the html element.
2021 fontsize
2023 sets the base CSS font-size, which you’d usually set to
2024 e.g. 20px, but it also accepts pt (12pt = 16px in most
2025 browsers).
2026 fontcolor
2028 sets the CSS color property on the html element.
2029 linkcolor
2031 sets the CSS color property on all links.
2032 monofont
2034 sets the CSS font-family property on code elements.
2035 monobackgroundcolor
2037 sets the CSS background-color property on code elements and adds
2038 extra padding.
2039 linestretch
2041 sets the CSS line-height property on the html element, which is
2042 preferred to be unitless.
2043 backgroundcolor
2045 sets the CSS background-color property on the html element.
2046 margin-left, margin-right, margin-top, margin-bottom
2048 sets the corresponding CSS padding properties on the body ele‐
2049 ment.
2050 To override or extend some CSS for just one document, include for exam‐
2052 ple:
2053 ---
2055 header-includes: |
2056 <style>
2057 blockquote {
2058 font-style: italic;
2059 }
2060 tr.even {
2061 background-color: #f0f0f0;
2062 }
2063 td, th {
2064 padding: 0.5em 2em 0.5em 0.5em;
2065 }
2066 tbody {
2067 border-bottom: none;
2068 }
2069 </style>
2070 ---
2071 Variables for HTML math
2073 classoption
2074 when using KaTeX, you can render display math equations flush
2075 left using YAML metadata or with -M classoption=fleqn.
2076 Variables for HTML slides
2078 These affect HTML output when [producing slide shows with pandoc].
2079 institute
2081 author affiliations: can be a list when there are multiple au‐
2082 thors
2083 revealjs-url
2085 base URL for reveal.js documents (defaults to
2086 https://unpkg.com/reveal.js@^4/)
2087 s5-url base URL for S5 documents (defaults to s5/default)
2089 slidy-url
2091 base URL for Slidy documents (defaults to
2092 https://www.w3.org/Talks/Tools/Slidy2)
2093 slideous-url
2095 base URL for Slideous documents (defaults to slideous)
2096 title-slide-attributes
2098 additional attributes for the title slide of reveal.js slide
2099 shows. See background in reveal.js and beamer for an example.
2100 All reveal.js configuration options are available as variables. To
2102 turn off boolean flags that default to true in reveal.js, use 0.
2103 Variables for Beamer slides
2105 These variables change the appearance of PDF slides using beamer.
2106 aspectratio
2108 slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for
2109 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)
2110 beamerarticle
2112 produce an article from Beamer slides
2113 beameroption
2115 add extra beamer option with \setbeameroption{}
2116 institute
2118 author affiliations: can be a list when there are multiple au‐
2119 thors
2120 logo logo image for slides
2122 navigation
2124 controls navigation symbols (default is empty for no navigation
2125 symbols; other valid values are frame, vertical, and horizontal)
2126 section-titles
2128 enables “title pages” for new sections (default is true)
2129 theme, colortheme, fonttheme, innertheme, outertheme
2131 beamer themes
2132 themeoptions
2134 options for LaTeX beamer themes (a list).
2135 titlegraphic
2137 image for title slide
2138 Variables for PowerPoint
2140 These variables control the visual aspects of a slide show that are not
2141 easily controlled via templates.
2142 monofont
2144 font to use for code.
2145 Variables for LaTeX
2147 Pandoc uses these variables when creating a PDF with a LaTeX engine.
2148 Layout
2150 block-headings
2151 make \paragraph and \subparagraph (fourth- and fifth-level head‐
2152 ings, or fifth- and sixth-level with book classes) free-standing
2153 rather than run-in; requires further formatting to distinguish
2154 from \subsubsection (third- or fourth-level headings). Instead
2155 of using this option, KOMA-Script can adjust headings more ex‐
2156 tensively:
2157 ---
2159 documentclass: scrartcl
2160 header-includes: |
2161 \RedeclareSectionCommand[
2162 beforeskip=-10pt plus -2pt minus -1pt,
2163 afterskip=1sp plus -1sp minus 1sp,
2164 font=\normalfont\itshape]{paragraph}
2165 \RedeclareSectionCommand[
2166 beforeskip=-10pt plus -2pt minus -1pt,
2167 afterskip=1sp plus -1sp minus 1sp,
2168 font=\normalfont\scshape,
2169 indent=0pt]{subparagraph}
2170 ...
2171 classoption
2173 option for document class, e.g. oneside; repeat for multiple op‐
2174 tions:
2175 ---
2177 classoption:
2178 - twocolumn
2179 - landscape
2180 ...
2181 documentclass
2183 document class: usually one of the standard classes, article,
2184 book, and report; the KOMA-Script equivalents, scrartcl, scr‐
2185 book, and scrreprt, which default to smaller margins; or memoir
2186 geometry
2188 option for geometry package, e.g. margin=1in; repeat for multi‐
2189 ple options:
2190 ---
2192 geometry:
2193 - top=30mm
2194 - left=20mm
2195 - heightrounded
2196 ...
2197 hyperrefoptions
2199 option for hyperref package, e.g. linktoc=all; repeat for multi‐
2200 ple options:
2201 ---
2203 hyperrefoptions:
2204 - linktoc=all
2205 - pdfwindowui
2206 - pdfpagemode=FullScreen
2207 ...
2208 indent if true, pandoc will use document class settings for indentation
2210 (the default LaTeX template otherwise removes indentation and
2211 adds space between paragraphs)
2212 linestretch
2214 adjusts line spacing using the setspace package, e.g. 1.25, 1.5
2215 margin-left, margin-right, margin-top, margin-bottom
2217 sets margins if geometry is not used (otherwise geometry over‐
2218 rides these)
2219 pagestyle
2221 control \pagestyle{}: the default article class supports plain
2222 (default), empty (no running heads or page numbers), and head‐
2223 ings (section titles in running heads)
2224 papersize
2226 paper size, e.g. letter, a4
2227 secnumdepth
2229 numbering depth for sections (with --number-sections option or
2230 numbersections variable)
2231 Fonts
2233 fontenc
2234 allows font encoding to be specified through fontenc package
2235 (with pdflatex); default is T1 (see LaTeX font encodings guide)
2236 fontfamily
2238 font package for use with pdflatex: TeX Live includes many op‐
2239 tions, documented in the LaTeX Font Catalogue. The default is
2240 Latin Modern.
2241 fontfamilyoptions
2243 options for package used as fontfamily; repeat for multiple op‐
2244 tions. For example, to use the Libertine font with proportional
2245 lowercase (old-style) figures through the libertinus package:
2246 ---
2248 fontfamily: libertinus
2249 fontfamilyoptions:
2250 - osf
2251 - p
2252 ...
2253 fontsize
2255 font size for body text. The standard classes allow 10pt, 11pt,
2256 and 12pt. To use another size, set documentclass to one of the
2257 KOMA-Script classes, such as scrartcl or scrbook.
2258 mainfont, sansfont, monofont, mathfont, CJKmainfont
2260 font families for use with xelatex or lualatex: take the name of
2261 any system font, using the fontspec package. CJKmainfont uses
2262 the xecjk package.
2263 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions,
2265 CJKoptions
2266 options to use with mainfont, sansfont, monofont, mathfont, CJK‐
2267 mainfont in xelatex and lualatex. Allow for any choices avail‐
2268 able through fontspec; repeat for multiple options. For exam‐
2269 ple, to use the TeX Gyre version of Palatino with lowercase fig‐
2270 ures:
2271 ---
2273 mainfont: TeX Gyre Pagella
2274 mainfontoptions:
2275 - Numbers=Lowercase
2276 - Numbers=Proportional
2277 ...
2278 microtypeoptions
2280 options to pass to the microtype package
2281 Links
2283 colorlinks
2284 add color to link text; automatically enabled if any of linkcol‐
2285 or, filecolor, citecolor, urlcolor, or toccolor are set
2286 linkcolor, filecolor, citecolor, urlcolor, toccolor
2288 color for internal links, external links, citation links, linked
2289 URLs, and links in table of contents, respectively: uses options
2290 allowed by xcolor, including the dvipsnames, svgnames, and
2291 x11names lists
2292 links-as-notes
2294 causes links to be printed as footnotes
2295 Front matter
2297 lof, lot
2298 include list of figures, list of tables
2299 thanks contents of acknowledgments footnote after document title
2301 toc include table of contents (can also be set using --toc/--table-
2303 of-contents)
2304 toc-depth
2306 level of section to include in table of contents
2307 BibLaTeX Bibliographies
2309 These variables function when using BibLaTeX for citation rendering.
2310 biblatexoptions
2312 list of options for biblatex
2313 biblio-style
2315 bibliography style, when used with --natbib and --biblatex.
2316 biblio-title
2318 bibliography title, when used with --natbib and --biblatex.
2319 bibliography
2321 bibliography to use for resolving references
2322 natbiboptions
2324 list of options for natbib
2325 Variables for ConTeXt
2327 Pandoc uses these variables when creating a PDF with ConTeXt.
2328 fontsize
2330 font size for body text (e.g. 10pt, 12pt)
2331 headertext, footertext
2333 text to be placed in running header or footer (see ConTeXt Head‐
2334 ers and Footers); repeat up to four times for different place‐
2335 ment
2336 indenting
2338 controls indentation of paragraphs, e.g. yes,small,next (see
2339 ConTeXt Indentation); repeat for multiple options
2340 interlinespace
2342 adjusts line spacing, e.g. 4ex (using setupinterlinespace); re‐
2343 peat for multiple options
2344 layout options for page margins and text arrangement (see ConTeXt Lay‐
2346 out); repeat for multiple options
2347 linkcolor, contrastcolor
2349 color for links outside and inside a page, e.g. red, blue (see
2350 ConTeXt Color)
2351 linkstyle
2353 typeface style for links, e.g. normal, bold, slanted, boldslant‐
2354 ed, type, cap, small
2355 lof, lot
2357 include list of figures, list of tables
2358 mainfont, sansfont, monofont, mathfont
2360 font families: take the name of any system font (see ConTeXt
2361 Font Switching)
2362 margin-left, margin-right, margin-top, margin-bottom
2364 sets margins, if layout is not used (otherwise layout overrides
2365 these)
2366 pagenumbering
2368 page number style and location (using setuppagenumbering); re‐
2369 peat for multiple options
2370 papersize
2372 paper size, e.g. letter, A4, landscape (see ConTeXt Paper Set‐
2373 up); repeat for multiple options
2374 pdfa adds to the preamble the setup necessary to generate PDF/A of
2376 the type specified, e.g. 1a:2005, 2a. If no type is specified
2377 (i.e. the value is set to True, by e.g. --metadata=pdfa or
2378 pdfa: true in a YAML metadata block), 1b:2005 will be used as
2379 default, for reasons of backwards compatibility. Using --vari‐
2380 able=pdfa without specified value is not supported. To success‐
2381 fully generate PDF/A the required ICC color profiles have to be
2382 available and the content and all included files (such as im‐
2383 ages) have to be standard conforming. The ICC profiles and out‐
2384 put intent may be specified using the variables pdfaiccprofile
2385 and pdfaintent. See also ConTeXt PDFA for more details.
2386 pdfaiccprofile
2388 when used in conjunction with pdfa, specifies the ICC profile to
2389 use in the PDF, e.g. default.cmyk. If left unspecified,
2390 sRGB.icc is used as default. May be repeated to include multi‐
2391 ple profiles. Note that the profiles have to be available on
2392 the system. They can be obtained from ConTeXt ICC Profiles.
2393 pdfaintent
2395 when used in conjunction with pdfa, specifies the output intent
2396 for the colors, e.g. ISO coated v2 300\letterpercent\space (ECI)
2397 If left unspecified, sRGB IEC61966-2.1 is used as default.
2398 toc include table of contents (can also be set using --toc/--table-
2400 of-contents)
2401 whitespace
2403 spacing between paragraphs, e.g. none, small (using setupwhites‐
2404 pace)
2405 includesource
2407 include all source documents as file attachments in the PDF file
2408 Variables for wkhtmltopdf
2410 Pandoc uses these variables when creating a PDF with wkhtmltopdf. The
2411 --css option also affects the output.
2412 footer-html, header-html
2414 add information to the header and footer
2415 margin-left, margin-right, margin-top, margin-bottom
2417 set the page margins
2418 papersize
2420 sets the PDF paper size
2421 Variables for man pages
2423 adjusting
2424 adjusts text to left (l), right (r), center (c), or both (b)
2425 margins
2426 footer footer in man pages
2428 header header in man pages
2430 hyphenate
2432 if true (the default), hyphenation will be used
2433 section
2435 section number in man pages
2436 Variables for ms
2438 fontfamily
2439 font family (e.g. T or P)
2440 indent paragraph indent (e.g. 2m)
2442 lineheight
2444 line height (e.g. 12p)
2445 pointsize
2447 point size (e.g. 10p)
2448 Variables set automatically
2450 Pandoc sets these variables automatically in response to options or
2451 document contents; users can also modify them. These vary depending on
2452 the output format, and include the following:
2453 body body of document
2455 date-meta
2457 the date variable converted to ISO 8601 YYYY-MM-DD, included in
2458 all HTML based formats (dzslides, epub, html, html4, html5, re‐
2459 vealjs, s5, slideous, slidy). The recognized formats for date
2460 are: mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy
2461 (e.g. either 02 Apr 2018 or 02 April 2018), MM dd, yyyy
2462 (e.g. Apr. 02, 2018 or April 02,
2463 2018),yyyy[mm[dd]]](e.g.20180402, 201804 or 2018).
2464 header-includes
2466 contents specified by -H/--include-in-header (may have multiple
2467 values)
2468 include-before
2470 contents specified by -B/--include-before-body (may have multi‐
2471 ple values)
2472 include-after
2474 contents specified by -A/--include-after-body (may have multiple
2475 values)
2476 meta-json
2478 JSON representation of all of the document’s metadata. Field
2479 values are transformed to the selected output format.
2480 numbersections
2482 non-null value if -N/--number-sections was specified
2483 sourcefile, outputfile
2485 source and destination filenames, as given on the command line.
2486 sourcefile can also be a list if input comes from multiple
2487 files, or empty if input is from stdin. You can use the follow‐
2488 ing snippet in your template to distinguish them:
2489 $if(sourcefile)$
2491 $for(sourcefile)$
2492 $sourcefile$
2493 $endfor$
2494 $else$
2495 (stdin)
2496 $endif$
2497 Similarly, outputfile can be - if output goes to the terminal.
2499 If you need absolute paths, use e.g. $curdir$/$sourcefile$.
2501 curdir working directory from which pandoc is run.
2503 toc non-null value if --toc/--table-of-contents was specified
2505 toc-title
2507 title of table of contents (works only with EPUB, HTML, opendoc‐
2508 ument, odt, docx, pptx, beamer, LaTeX)
2509
2511 The behavior of some of the readers and writers can be adjusted by en‐
2512 abling or disabling various extensions.
2513 An extension can be enabled by adding +EXTENSION to the format name and
2515 disabled by adding -EXTENSION. For example, --from mark‐
2516 down_strict+footnotes is strict Markdown with footnotes enabled, while
2517 --from markdown-footnotes-pipe_tables is pandoc’s Markdown without
2518 footnotes or pipe tables.
2519 The markdown reader and writer make by far the most use of extensions.
2521 Extensions only used by them are therefore covered in the section Pan‐
2522 doc’s Markdown below (See Markdown variants for commonmark and gfm.) In
2523 the following, extensions that also work for other formats are covered.
2524 Note that markdown extensions added to the ipynb format affect Markdown
2526 cells in Jupyter notebooks (as do command-line options like --atx-head‐
2527 ers).
2528 Typography
2530 Extension: smart
2531 Interpret straight quotes as curly quotes, --- as em-dashes, -- as en-
2532 dashes, and ... as ellipses. Nonbreaking spaces are inserted after
2533 certain abbreviations, such as “Mr.”
2534 This extension can be enabled/disabled for the following formats:
2536 input formats
2538 markdown, commonmark, latex, mediawiki, org, rst, twiki
2539 output formats
2541 markdown, latex, context, rst
2542 enabled by default in
2544 markdown, latex, context (both input and output)
2545 Note: If you are writing Markdown, then the smart extension has the re‐
2547 verse effect: what would have been curly quotes comes out straight.
2548 In LaTeX, smart means to use the standard TeX ligatures for quotation
2550 marks (`` and '' for double quotes, ` and ' for single quotes) and
2551 dashes (-- for en-dash and --- for em-dash). If smart is disabled,
2552 then in reading LaTeX pandoc will parse these characters literally. In
2553 writing LaTeX, enabling smart tells pandoc to use the ligatures when
2554 possible; if smart is disabled pandoc will use unicode quotation mark
2555 and dash characters.
2556 Headings and sections
2558 Extension: auto_identifiers
2559 A heading without an explicitly specified identifier will be automati‐
2560 cally assigned a unique identifier based on the heading text.
2561 This extension can be enabled/disabled for the following formats:
2563 input formats
2565 markdown, latex, rst, mediawiki, textile
2566 output formats
2568 markdown, muse
2569 enabled by default in
2571 markdown, muse
2572 The default algorithm used to derive the identifier from the heading
2574 text is:
2575 • Remove all formatting, links, etc.
2577 • Remove all footnotes.
2579 • Remove all non-alphanumeric characters, except underscores, hyphens,
2581 and periods.
2582 • Replace all spaces and newlines with hyphens.
2584 • Convert all alphabetic characters to lowercase.
2586 • Remove everything up to the first letter (identifiers may not begin
2588 with a number or punctuation mark).
2589 • If nothing is left after this, use the identifier section.
2591 Thus, for example,
2593 Heading Identifier
2595 ─────────────────────────────────────────────────────
2596 Heading identifiers in heading-identifiers-in-
2597 HTML html
2598 Maître d'hôtel maître-dhôtel
2599 *Dogs*?--in *my* house? dogs--in-my-house
2600 [HTML], [S5], or [RTF]? html-s5-or-rtf
2601 3. Applications applications
2602 33 section
2603 These rules should, in most cases, allow one to determine the identifi‐
2605 er from the heading text. The exception is when several headings have
2606 the same text; in this case, the first will get an identifier as de‐
2607 scribed above; the second will get the same identifier with -1 append‐
2608 ed; the third with -2; and so on.
2609 (However, a different algorithm is used if gfm_auto_identifiers is en‐
2611 abled; see below.)
2612 These identifiers are used to provide link targets in the table of con‐
2614 tents generated by the --toc|--table-of-contents option. They also
2615 make it easy to provide links from one section of a document to anoth‐
2616 er. A link to this section, for example, might look like this:
2617 See the section on
2619 [heading identifiers](#heading-identifiers-in-html-latex-and-context).
2620 Note, however, that this method of providing links to sections works
2622 only in HTML, LaTeX, and ConTeXt formats.
2623 If the --section-divs option is specified, then each section will be
2625 wrapped in a section (or a div, if html4 was specified), and the iden‐
2626 tifier will be attached to the enclosing <section> (or <div>) tag
2627 rather than the heading itself. This allows entire sections to be ma‐
2628 nipulated using JavaScript or treated differently in CSS.
2629 Extension: ascii_identifiers
2631 Causes the identifiers produced by auto_identifiers to be pure ASCII.
2632 Accents are stripped off of accented Latin letters, and non-Latin let‐
2633 ters are omitted.
2634 Extension: gfm_auto_identifiers
2636 Changes the algorithm used by auto_identifiers to conform to GitHub’s
2637 method. Spaces are converted to dashes (-), uppercase characters to
2638 lowercase characters, and punctuation characters other than - and _ are
2639 removed. Emojis are replaced by their names.
2640 Math Input
2642 The extensions tex_math_dollars, tex_math_single_backslash, and
2643 tex_math_double_backslash are described in the section about Pandoc’s
2644 Markdown.
2645 However, they can also be used with HTML input. This is handy for
2647 reading web pages formatted using MathJax, for example.
2648 Raw HTML/TeX
2650 The following extensions are described in more detail in their respec‐
2651 tive sections of Pandoc’s Markdown:
2652 • raw_html allows HTML elements which are not representable in pandoc’s
2654 AST to be parsed as raw HTML. By default, this is disabled for HTML
2655 input.
2656 • raw_tex allows raw LaTeX, TeX, and ConTeXt to be included in a docu‐
2658 ment. This extension can be enabled/disabled for the following for‐
2659 mats (in addition to markdown):
2660 input formats
2662 latex, textile, html (environments, \ref, and \eqref only),
2663 ipynb
2664 output formats
2666 textile, commonmark
2667 Note: as applied to ipynb, raw_html and raw_tex affect not only raw
2669 TeX in markdown cells, but data with mime type text/html in output
2670 cells. Since the ipynb reader attempts to preserve the richest pos‐
2671 sible outputs when several options are given, you will get best re‐
2672 sults if you disable raw_html and raw_tex when converting to formats
2673 like docx which don’t allow raw html or tex.
2674 • native_divs causes HTML div elements to be parsed as native pandoc
2676 Div blocks. If you want them to be parsed as raw HTML, use -f html-
2677 native_divs+raw_html.
2678 • native_spans causes HTML span elements to be parsed as native pandoc
2680 Span inlines. If you want them to be parsed as raw HTML, use -f
2681 html-native_spans+raw_html. If you want to drop all divs and spans
2682 when converting HTML to Markdown, you can use pandoc -f html-na‐
2683 tive_divs-native_spans -t markdown.
2684 Literate Haskell support
2686 Extension: literate_haskell
2687 Treat the document as literate Haskell source.
2688 This extension can be enabled/disabled for the following formats:
2690 input formats
2692 markdown, rst, latex
2693 output formats
2695 markdown, rst, latex, html
2696 If you append +lhs (or +literate_haskell) to one of the formats above,
2698 pandoc will treat the document as literate Haskell source. This means
2699 that
2700 • In Markdown input, “bird track” sections will be parsed as Haskell
2702 code rather than block quotations. Text between \begin{code} and
2703 \end{code} will also be treated as Haskell code. For ATX-style head‐
2704 ings the character `=' will be used instead of `#'.
2705 • In Markdown output, code blocks with classes haskell and literate
2707 will be rendered using bird tracks, and block quotations will be in‐
2708 dented one space, so they will not be treated as Haskell code. In
2709 addition, headings will be rendered setext-style (with underlines)
2710 rather than ATX-style (with `#' characters). (This is because ghc
2711 treats `#' characters in column 1 as introducing line numbers.)
2712 • In restructured text input, “bird track” sections will be parsed as
2714 Haskell code.
2715 • In restructured text output, code blocks with class haskell will be
2717 rendered using bird tracks.
2718 • In LaTeX input, text in code environments will be parsed as Haskell
2720 code.
2721 • In LaTeX output, code blocks with class haskell will be rendered in‐
2723 side code environments.
2724 • In HTML output, code blocks with class haskell will be rendered with
2726 class literatehaskell and bird tracks.
2727 Examples:
2729 pandoc -f markdown+lhs -t html
2731 reads literate Haskell source formatted with Markdown conventions and
2733 writes ordinary HTML (without bird tracks).
2734 pandoc -f markdown+lhs -t html+lhs
2736 writes HTML with the Haskell code in bird tracks, so it can be copied
2738 and pasted as literate Haskell source.
2739 Note that GHC expects the bird tracks in the first column, so indented
2741 literate code blocks (e.g. inside an itemized environment) will not be
2742 picked up by the Haskell compiler.
2743 Other extensions
2745 Extension: empty_paragraphs
2746 Allows empty paragraphs. By default empty paragraphs are omitted.
2747 This extension can be enabled/disabled for the following formats:
2749 input formats
2751 docx, html
2752 output formats
2754 docx, odt, opendocument, html
2755 Extension: native_numbering
2757 Enables native numbering of figures and tables. Enumeration starts at
2758 1.
2759 This extension can be enabled/disabled for the following formats:
2761 output formats
2763 odt, opendocument
2764 Extension: xrefs_name
2766 Links to headings, figures and tables inside the document are substi‐
2767 tuted with cross-references that will use the name or caption of the
2768 referenced item. The original link text is replaced once the generated
2769 document is refreshed. This extension can be combined with xrefs_num‐
2770 ber in which case numbers will appear before the name.
2771 Text in cross-references is only made consistent with the referenced
2773 item once the document has been refreshed.
2774 This extension can be enabled/disabled for the following formats:
2776 output formats
2778 odt, opendocument
2779 Extension: xrefs_number
2781 Links to headings, figures and tables inside the document are substi‐
2782 tuted with cross-references that will use the number of the referenced
2783 item. The original link text is discarded. This extension can be com‐
2784 bined with xrefs_name in which case the name or caption numbers will
2785 appear after the number.
2786 For the xrefs_number to be useful heading numbers must be enabled in
2788 the generated document, also table and figure captions must be enabled
2789 using for example the native_numbering extension.
2790 Numbers in cross-references are only visible in the final document once
2792 it has been refreshed.
2793 This extension can be enabled/disabled for the following formats:
2795 output formats
2797 odt, opendocument
2798 Extension: styles
2800 When converting from docx, read all docx styles as divs (for paragraph
2801 styles) and spans (for character styles) regardless of whether pandoc
2802 understands the meaning of these styles. This can be used with docx
2803 custom styles. Disabled by default.
2804 input formats
2806 docx
2807 Extension: amuse
2809 In the muse input format, this enables Text::Amuse extensions to Emacs
2810 Muse markup.
2811 Extension: raw_markdown
2813 In the ipynb input format, this causes Markdown cells to be included as
2814 raw Markdown blocks (allowing lossless round-tripping) rather than be‐
2815 ing parsed. Use this only when you are targeting ipynb or a markdown-
2816 based output format.
2817 Extension: citations
2819 Some aspects of Pandoc’s Markdown citation syntax are also accepted in
2820 org input.
2821 Extension: element_citations
2823 In the jats output formats, this causes reference items to be replaced
2824 with <element-citation> elements. These elements are not influenced by
2825 CSL styles, but all information on the item is included in tags.
2826 Extension: ntb
2828 In the context output format this enables the use of Natural Tables
2829 (TABLE) instead of the default Extreme Tables (xtables). Natural ta‐
2830 bles allow more fine-grained global customization but come at a perfor‐
2831 mance penalty compared to extreme tables.
2832
2834 Pandoc understands an extended and slightly revised version of John
2835 Gruber’s Markdown syntax. This document explains the syntax, noting
2836 differences from standard Markdown. Except where noted, these differ‐
2837 ences can be suppressed by using the markdown_strict format instead of
2838 markdown. Extensions can be enabled or disabled to specify the behav‐
2839 ior more granularly. They are described in the following. See also
2840 Extensions above, for extensions that work also on other formats.
2841 Philosophy
2843 Markdown is designed to be easy to write, and, even more importantly,
2844 easy to read:
2845 A Markdown-formatted document should be publishable as-is, as
2847 plain text, without looking like it’s been marked up with tags
2848 or formatting instructions. – John Gruber
2849 This principle has guided pandoc’s decisions in finding syntax for ta‐
2851 bles, footnotes, and other extensions.
2852 There is, however, one respect in which pandoc’s aims are different
2854 from the original aims of Markdown. Whereas Markdown was originally
2855 designed with HTML generation in mind, pandoc is designed for multiple
2856 output formats. Thus, while pandoc allows the embedding of raw HTML,
2857 it discourages it, and provides other, non-HTMLish ways of representing
2858 important document elements like definition lists, tables, mathematics,
2859 and footnotes.
2860 Paragraphs
2862 A paragraph is one or more lines of text followed by one or more blank
2863 lines. Newlines are treated as spaces, so you can reflow your para‐
2864 graphs as you like. If you need a hard line break, put two or more
2865 spaces at the end of a line.
2866 Extension: escaped_line_breaks
2868 A backslash followed by a newline is also a hard line break. Note: in
2869 multiline and grid table cells, this is the only way to create a hard
2870 line break, since trailing spaces in the cells are ignored.
2871 Headings
2873 There are two kinds of headings: Setext and ATX.
2874 Setext-style headings
2876 A setext-style heading is a line of text “underlined” with a row of =
2877 signs (for a level-one heading) or - signs (for a level-two heading):
2878 A level-one heading
2880 ===================
2881 A level-two heading
2883 -------------------
2884 The heading text can contain inline formatting, such as emphasis (see
2886 Inline formatting, below).
2887 ATX-style headings
2889 An ATX-style heading consists of one to six # signs and a line of text,
2890 optionally followed by any number of # signs. The number of # signs at
2891 the beginning of the line is the heading level:
2892 ## A level-two heading
2894 ### A level-three heading ###
2896 As with setext-style headings, the heading text can contain formatting:
2898 # A level-one heading with a [link](/url) and *emphasis*
2900 Extension: blank_before_header
2902 Standard Markdown syntax does not require a blank line before a head‐
2903 ing. Pandoc does require this (except, of course, at the beginning of
2904 the document). The reason for the requirement is that it is all too
2905 easy for a # to end up at the beginning of a line by accident (perhaps
2906 through line wrapping). Consider, for example:
2907 I like several of their flavors of ice cream:
2909 #22, for example, and #5.
2910 Extension: space_in_atx_header
2912 Many Markdown implementations do not require a space between the open‐
2913 ing #s of an ATX heading and the heading text, so that #5 bolt and
2914 #hashtag count as headings. With this extension, pandoc does require
2915 the space.
2916 Heading identifiers
2918 See also the auto_identifiers extension above.
2919 Extension: header_attributes
2921 Headings can be assigned attributes using this syntax at the end of the
2922 line containing the heading text:
2923 {#identifier .class .class key=value key=value}
2925 Thus, for example, the following headings will all be assigned the
2927 identifier foo:
2928 # My heading {#foo}
2930 ## My heading ## {#foo}
2932 My other heading {#foo}
2934 ---------------
2935 (This syntax is compatible with PHP Markdown Extra.)
2937 Note that although this syntax allows assignment of classes and
2939 key/value attributes, writers generally don’t use all of this informa‐
2940 tion. Identifiers, classes, and key/value attributes are used in HTML
2941 and HTML-based formats such as EPUB and slidy. Identifiers are used
2942 for labels and link anchors in the LaTeX, ConTeXt, Textile, Jira
2943 markup, and AsciiDoc writers.
2944 Headings with the class unnumbered will not be numbered, even if --num‐
2946 ber-sections is specified. A single hyphen (-) in an attribute context
2947 is equivalent to .unnumbered, and preferable in non-English documents.
2948 So,
2949 # My heading {-}
2951 is just the same as
2953 # My heading {.unnumbered}
2955 If the unlisted class is present in addition to unnumbered, the heading
2957 will not be included in a table of contents. (Currently this feature
2958 is only implemented for certain formats: those based on LaTeX and HTML,
2959 PowerPoint, and RTF.)
2960 Extension: implicit_header_references
2962 Pandoc behaves as if reference links have been defined for each head‐
2963 ing. So, to link to a heading
2964 # Heading identifiers in HTML
2966 you can simply write
2968 [Heading identifiers in HTML]
2970 or
2972 [Heading identifiers in HTML][]
2974 or
2976 [the section on heading identifiers][heading identifiers in
2978 HTML]
2979 instead of giving the identifier explicitly:
2981 [Heading identifiers in HTML](#heading-identifiers-in-html)
2983 If there are multiple headings with identical text, the corresponding
2985 reference will link to the first one only, and you will need to use ex‐
2986 plicit links to link to the others, as described above.
2987 Like regular reference links, these references are case-insensitive.
2989 Explicit link reference definitions always take priority over implicit
2991 heading references. So, in the following example, the link will point
2992 to bar, not to #foo:
2993 # Foo
2995 [foo]: bar
2997 See [foo]
2999 Block quotations
3001 Markdown uses email conventions for quoting blocks of text. A block
3002 quotation is one or more paragraphs or other block elements (such as
3003 lists or headings), with each line preceded by a > character and an op‐
3004 tional space. (The > need not start at the left margin, but it should
3005 not be indented more than three spaces.)
3006 > This is a block quote. This
3008 > paragraph has two lines.
3009 >
3010 > 1. This is a list inside a block quote.
3011 > 2. Second item.
3012 A “lazy” form, which requires the > character only on the first line of
3014 each block, is also allowed:
3015 > This is a block quote. This
3017 paragraph has two lines.
3018 > 1. This is a list inside a block quote.
3020 2. Second item.
3021 Among the block elements that can be contained in a block quote are
3023 other block quotes. That is, block quotes can be nested:
3024 > This is a block quote.
3026 >
3027 > > A block quote within a block quote.
3028 If the > character is followed by an optional space, that space will be
3030 considered part of the block quote marker and not part of the indenta‐
3031 tion of the contents. Thus, to put an indented code block in a block
3032 quote, you need five spaces after the >:
3033 > code
3035 Extension: blank_before_blockquote
3037 Standard Markdown syntax does not require a blank line before a block
3038 quote. Pandoc does require this (except, of course, at the beginning
3039 of the document). The reason for the requirement is that it is all too
3040 easy for a > to end up at the beginning of a line by accident (perhaps
3041 through line wrapping). So, unless the markdown_strict format is used,
3042 the following does not produce a nested block quote in pandoc:
3043 > This is a block quote.
3045 >> Nested.
3046 Verbatim (code) blocks
3048 Indented code blocks
3049 A block of text indented four spaces (or one tab) is treated as verba‐
3050 tim text: that is, special characters do not trigger special format‐
3051 ting, and all spaces and line breaks are preserved. For example,
3052 if (a > 3) {
3054 moveShip(5 * gravity, DOWN);
3055 }
3056 The initial (four space or one tab) indentation is not considered part
3058 of the verbatim text, and is removed in the output.
3059 Note: blank lines in the verbatim text need not begin with four spaces.
3061 Fenced code blocks
3063 Extension: fenced_code_blocks
3064 In addition to standard indented code blocks, pandoc supports fenced
3065 code blocks. These begin with a row of three or more tildes (~) and
3066 end with a row of tildes that must be at least as long as the starting
3067 row. Everything between these lines is treated as code. No indenta‐
3068 tion is necessary:
3069 ~~~~~~~
3071 if (a > 3) {
3072 moveShip(5 * gravity, DOWN);
3073 }
3074 ~~~~~~~
3075 Like regular code blocks, fenced code blocks must be separated from
3077 surrounding text by blank lines.
3078 If the code itself contains a row of tildes or backticks, just use a
3080 longer row of tildes or backticks at the start and end:
3081 ~~~~~~~~~~~~~~~~
3083 ~~~~~~~~~~
3084 code including tildes
3085 ~~~~~~~~~~
3086 ~~~~~~~~~~~~~~~~
3087 Extension: backtick_code_blocks
3089 Same as fenced_code_blocks, but uses backticks (`) instead of tildes
3090 (~).
3091 Extension: fenced_code_attributes
3093 Optionally, you may attach attributes to fenced or backtick code block
3094 using this syntax:
3095 ~~~~ {#mycode .haskell .numberLines startFrom="100"}
3097 qsort [] = []
3098 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3099 qsort (filter (>= x) xs)
3100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3101 Here mycode is an identifier, haskell and numberLines are classes, and
3103 startFrom is an attribute with value 100. Some output formats can use
3104 this information to do syntax highlighting. Currently, the only output
3105 formats that uses this information are HTML, LaTeX, Docx, Ms, and Pow‐
3106 erPoint. If highlighting is supported for your output format and lan‐
3107 guage, then the code block above will appear highlighted, with numbered
3108 lines. (To see which languages are supported, type pandoc --list-high‐
3109 light-languages.) Otherwise, the code block above will appear as fol‐
3110 lows:
3111 <pre id="mycode" class="haskell numberLines" startFrom="100">
3113 <code>
3114 ...
3115 </code>
3116 </pre>
3117 The numberLines (or number-lines) class will cause the lines of the
3119 code block to be numbered, starting with 1 or the value of the start‐
3120 From attribute. The lineAnchors (or line-anchors) class will cause the
3121 lines to be clickable anchors in HTML output.
3122 A shortcut form can also be used for specifying the language of the
3124 code block:
3125 ```haskell
3127 qsort [] = []
3128 ```
3129 This is equivalent to:
3131 ``` {.haskell}
3133 qsort [] = []
3134 ```
3135 If the fenced_code_attributes extension is disabled, but input contains
3137 class attribute(s) for the code block, the first class attribute will
3138 be printed after the opening fence as a bare word.
3139 To prevent all highlighting, use the --no-highlight flag. To set the
3141 highlighting style, use --highlight-style. For more information on
3142 highlighting, see Syntax highlighting, below.
3143 Line blocks
3145 Extension: line_blocks
3146 A line block is a sequence of lines beginning with a vertical bar (|)
3147 followed by a space. The division into lines will be preserved in the
3148 output, as will any leading spaces; otherwise, the lines will be for‐
3149 matted as Markdown. This is useful for verse and addresses:
3150 | The limerick packs laughs anatomical
3152 | In space that is quite economical.
3153 | But the good ones I've seen
3154 | So seldom are clean
3155 | And the clean ones so seldom are comical
3156 | 200 Main St.
3158 | Berkeley, CA 94718
3159 The lines can be hard-wrapped if needed, but the continuation line must
3161 begin with a space.
3162 | The Right Honorable Most Venerable and Righteous Samuel L.
3164 Constable, Jr.
3165 | 200 Main St.
3166 | Berkeley, CA 94718
3167 Inline formatting (such as emphasis) is allowed in the content, but not
3169 block-level formatting (such as block quotes or lists).
3170 This syntax is borrowed from reStructuredText.
3172 Lists
3174 Bullet lists
3175 A bullet list is a list of bulleted list items. A bulleted list item
3176 begins with a bullet (*, +, or -). Here is a simple example:
3177 * one
3179 * two
3180 * three
3181 This will produce a “compact” list. If you want a “loose” list, in
3183 which each item is formatted as a paragraph, put spaces between the
3184 items:
3185 * one
3187 * two
3189 * three
3191 The bullets need not be flush with the left margin; they may be indent‐
3193 ed one, two, or three spaces. The bullet must be followed by white‐
3194 space.
3195 List items look best if subsequent lines are flush with the first line
3197 (after the bullet):
3198 * here is my first
3200 list item.
3201 * and my second.
3202 But Markdown also allows a “lazy” format:
3204 * here is my first
3206 list item.
3207 * and my second.
3208 Block content in list items
3210 A list item may contain multiple paragraphs and other block-level con‐
3211 tent. However, subsequent paragraphs must be preceded by a blank line
3212 and indented to line up with the first non-space content after the list
3213 marker.
3214 * First paragraph.
3216 Continued.
3218 * Second paragraph. With a code block, which must be indented
3220 eight spaces:
3221 { code }
3223 Exception: if the list marker is followed by an indented code block,
3225 which must begin 5 spaces after the list marker, then subsequent para‐
3226 graphs must begin two columns after the last character of the list
3227 marker:
3228 * code
3230 continuation paragraph
3232 List items may include other lists. In this case the preceding blank
3234 line is optional. The nested list must be indented to line up with the
3235 first non-space character after the list marker of the containing list
3236 item.
3237 * fruits
3239 + apples
3240 - macintosh
3241 - red delicious
3242 + pears
3243 + peaches
3244 * vegetables
3245 + broccoli
3246 + chard
3247 As noted above, Markdown allows you to write list items “lazily,” in‐
3249 stead of indenting continuation lines. However, if there are multiple
3250 paragraphs or other blocks in a list item, the first line of each must
3251 be indented.
3252 + A lazy, lazy, list
3254 item.
3255 + Another one; this looks
3257 bad but is legal.
3258 Second paragraph of second
3260 list item.
3261 Ordered lists
3263 Ordered lists work just like bulleted lists, except that the items be‐
3264 gin with enumerators rather than bullets.
3265 In standard Markdown, enumerators are decimal numbers followed by a pe‐
3267 riod and a space. The numbers themselves are ignored, so there is no
3268 difference between this list:
3269 1. one
3271 2. two
3272 3. three
3273 and this one:
3275 5. one
3277 7. two
3278 1. three
3279 Extension: fancy_lists
3281 Unlike standard Markdown, pandoc allows ordered list items to be marked
3282 with uppercase and lowercase letters and roman numerals, in addition to
3283 Arabic numerals. List markers may be enclosed in parentheses or fol‐
3284 lowed by a single right-parentheses or period. They must be separated
3285 from the text that follows by at least one space, and, if the list
3286 marker is a capital letter with a period, by at least two spaces.
3287 The fancy_lists extension also allows `#' to be used as an ordered list
3289 marker in place of a numeral:
3290 #. one
3292 #. two
3293 Extension: startnum
3295 Pandoc also pays attention to the type of list marker used, and to the
3296 starting number, and both of these are preserved where possible in the
3297 output format. Thus, the following yields a list with numbers followed
3298 by a single parenthesis, starting with 9, and a sublist with lowercase
3299 roman numerals:
3300 9) Ninth
3302 10) Tenth
3303 11) Eleventh
3304 i. subone
3305 ii. subtwo
3306 iii. subthree
3307 Pandoc will start a new list each time a different type of list marker
3309 is used. So, the following will create three lists:
3310 (2) Two
3312 (5) Three
3313 1. Four
3314 * Five
3315 If default list markers are desired, use #.:
3317 #. one
3319 #. two
3320 #. three
3321 Extension: task_lists
3323 Pandoc supports task lists, using the syntax of GitHub-Flavored Mark‐
3324 down.
3325 - [ ] an unchecked task list item
3327 - [x] checked item
3328 Definition lists
3330 Extension: definition_lists
3331 Pandoc supports definition lists, using the syntax of PHP Markdown Ex‐
3332 tra with some extensions.
3333 Term 1
3335 : Definition 1
3337 Term 2 with *inline markup*
3339 : Definition 2
3341 { some code, part of Definition 2 }
3343 Third paragraph of definition 2.
3345 Each term must fit on one line, which may optionally be followed by a
3347 blank line, and must be followed by one or more definitions. A defini‐
3348 tion begins with a colon or tilde, which may be indented one or two
3349 spaces.
3350 A term may have multiple definitions, and each definition may consist
3352 of one or more block elements (paragraph, code block, list, etc.), each
3353 indented four spaces or one tab stop. The body of the definition (in‐
3354 cluding the first line, aside from the colon or tilde) should be in‐
3355 dented four spaces. However, as with other Markdown lists, you can
3356 “lazily” omit indentation except at the beginning of a paragraph or
3357 other block element:
3358 Term 1
3360 : Definition
3362 with lazy continuation.
3363 Second paragraph of the definition.
3365 If you leave space before the definition (as in the example above), the
3367 text of the definition will be treated as a paragraph. In some output
3368 formats, this will mean greater spacing between term/definition pairs.
3369 For a more compact definition list, omit the space before the defini‐
3370 tion:
3371 Term 1
3373 ~ Definition 1
3374 Term 2
3376 ~ Definition 2a
3377 ~ Definition 2b
3378 Note that space between items in a definition list is required. (A
3380 variant that loosens this requirement, but disallows “lazy” hard wrap‐
3381 ping, can be activated with compact_definition_lists: see Non-default
3382 extensions, below.)
3383 Numbered example lists
3385 Extension: example_lists
3386 The special list marker @ can be used for sequentially numbered exam‐
3387 ples. The first list item with a @ marker will be numbered `1', the
3388 next `2', and so on, throughout the document. The numbered examples
3389 need not occur in a single list; each new list using @ will take up
3390 where the last stopped. So, for example:
3391 (@) My first example will be numbered (1).
3393 (@) My second example will be numbered (2).
3394 Explanation of examples.
3396 (@) My third example will be numbered (3).
3398 Numbered examples can be labeled and referred to elsewhere in the docu‐
3400 ment:
3401 (@good) This is a good example.
3403 As (@good) illustrates, ...
3405 The label can be any string of alphanumeric characters, underscores, or
3407 hyphens.
3408 Note: continuation paragraphs in example lists must always be indented
3410 four spaces, regardless of the length of the list marker. That is, ex‐
3411 ample lists always behave as if the four_space_rule extension is set.
3412 This is because example labels tend to be long, and indenting content
3413 to the first non-space character after the label would be awkward.
3414 Ending a list
3416 What if you want to put an indented code block after a list?
3417 - item one
3419 - item two
3420 { my code block }
3422 Trouble! Here pandoc (like other Markdown implementations) will treat {
3424 my code block } as the second paragraph of item two, and not as a code
3425 block.
3426 To “cut off” the list after item two, you can insert some non-indented
3428 content, like an HTML comment, which won’t produce visible output in
3429 any format:
3430 - item one
3432 - item two
3433 <!-- end of list -->
3435 { my code block }
3437 You can use the same trick if you want two consecutive lists instead of
3439 one big list:
3440 1. one
3442 2. two
3443 3. three
3444 <!-- -->
3446 1. uno
3448 2. dos
3449 3. tres
3450 Horizontal rules
3452 A line containing a row of three or more *, -, or _ characters (option‐
3453 ally separated by spaces) produces a horizontal rule:
3454 * * * *
3456 ---------------
3458 Tables
3460 Four kinds of tables may be used. The first three kinds presuppose the
3461 use of a fixed-width font, such as Courier. The fourth kind can be
3462 used with proportionally spaced fonts, as it does not require lining up
3463 columns.
3464 Extension: table_captions
3466 A caption may optionally be provided with all 4 kinds of tables (as il‐
3467 lustrated in the examples below). A caption is a paragraph beginning
3468 with the string Table: (or just :), which will be stripped off. It may
3469 appear either before or after the table.
3470 Extension: simple_tables
3472 Simple tables look like this:
3473 Right Left Center Default
3475 ------- ------ ---------- -------
3476 12 12 12 12
3477 123 123 123 123
3478 1 1 1 1
3479 Table: Demonstration of simple table syntax.
3481 The header and table rows must each fit on one line. Column alignments
3483 are determined by the position of the header text relative to the
3484 dashed line below it:
3485 • If the dashed line is flush with the header text on the right side
3487 but extends beyond it on the left, the column is right-aligned.
3488 • If the dashed line is flush with the header text on the left side but
3490 extends beyond it on the right, the column is left-aligned.
3491 • If the dashed line extends beyond the header text on both sides, the
3493 column is centered.
3494 • If the dashed line is flush with the header text on both sides, the
3496 default alignment is used (in most cases, this will be left).
3497 The table must end with a blank line, or a line of dashes followed by a
3499 blank line.
3500 The column header row may be omitted, provided a dashed line is used to
3502 end the table. For example:
3503 ------- ------ ---------- -------
3505 12 12 12 12
3506 123 123 123 123
3507 1 1 1 1
3508 ------- ------ ---------- -------
3509 When the header row is omitted, column alignments are determined on the
3511 basis of the first line of the table body. So, in the tables above,
3512 the columns would be right, left, center, and right aligned, respec‐
3513 tively.
3514 Extension: multiline_tables
3516 Multiline tables allow header and table rows to span multiple lines of
3517 text (but cells that span multiple columns or rows of the table are not
3518 supported). Here is an example:
3519 -------------------------------------------------------------
3521 Centered Default Right Left
3522 Header Aligned Aligned Aligned
3523 ----------- ------- --------------- -------------------------
3524 First row 12.0 Example of a row that
3525 spans multiple lines.
3526 Second row 5.0 Here's another one. Note
3528 the blank line between
3529 rows.
3530 -------------------------------------------------------------
3531 Table: Here's the caption. It, too, may span
3533 multiple lines.
3534 These work like simple tables, but with the following differences:
3536 • They must begin with a row of dashes, before the header text (unless
3538 the header row is omitted).
3539 • They must end with a row of dashes, then a blank line.
3541 • The rows must be separated by blank lines.
3543 In multiline tables, the table parser pays attention to the widths of
3545 the columns, and the writers try to reproduce these relative widths in
3546 the output. So, if you find that one of the columns is too narrow in
3547 the output, try widening it in the Markdown source.
3548 The header may be omitted in multiline tables as well as simple tables:
3550 ----------- ------- --------------- -------------------------
3552 First row 12.0 Example of a row that
3553 spans multiple lines.
3554 Second row 5.0 Here's another one. Note
3556 the blank line between
3557 rows.
3558 ----------- ------- --------------- -------------------------
3559 : Here's a multiline table without a header.
3561 It is possible for a multiline table to have just one row, but the row
3563 should be followed by a blank line (and then the row of dashes that
3564 ends the table), or the table may be interpreted as a simple table.
3565 Extension: grid_tables
3567 Grid tables look like this:
3568 : Sample grid table.
3570 +---------------+---------------+--------------------+
3572 | Fruit | Price | Advantages |
3573 +===============+===============+====================+
3574 | Bananas | $1.34 | - built-in wrapper |
3575 | | | - bright color |
3576 +---------------+---------------+--------------------+
3577 | Oranges | $2.10 | - cures scurvy |
3578 | | | - tasty |
3579 +---------------+---------------+--------------------+
3580 The row of =s separates the header from the table body, and can be
3582 omitted for a headerless table. The cells of grid tables may contain
3583 arbitrary block elements (multiple paragraphs, code blocks, lists,
3584 etc.). Cells that span multiple columns or rows are not supported.
3585 Grid tables can be created easily using Emacs’ table-mode (M-x table-
3586 insert).
3587 Alignments can be specified as with pipe tables, by putting colons at
3589 the boundaries of the separator line after the header:
3590 +---------------+---------------+--------------------+
3592 | Right | Left | Centered |
3593 +==============:+:==============+:==================:+
3594 | Bananas | $1.34 | built-in wrapper |
3595 +---------------+---------------+--------------------+
3596 For headerless tables, the colons go on the top line instead:
3598 +--------------:+:--------------+:------------------:+
3600 | Right | Left | Centered |
3601 +---------------+---------------+--------------------+
3602 Grid Table Limitations
3604 Pandoc does not support grid tables with row spans or column spans.
3605 This means that neither variable numbers of columns across rows nor
3606 variable numbers of rows across columns are supported by Pandoc. All
3607 grid tables must have the same number of columns in each row, and the
3608 same number of rows in each column. For example, the Docutils sample
3609 grid tables will not render as expected with Pandoc.
3610 Extension: pipe_tables
3612 Pipe tables look like this:
3613 | Right | Left | Default | Center |
3615 |------:|:-----|---------|:------:|
3616 | 12 | 12 | 12 | 12 |
3617 | 123 | 123 | 123 | 123 |
3618 | 1 | 1 | 1 | 1 |
3619 : Demonstration of pipe table syntax.
3621 The syntax is identical to PHP Markdown Extra tables. The beginning
3623 and ending pipe characters are optional, but pipes are required between
3624 all columns. The colons indicate column alignment as shown. The head‐
3625 er cannot be omitted. To simulate a headerless table, include a header
3626 with blank cells.
3627 Since the pipes indicate column boundaries, columns need not be verti‐
3629 cally aligned, as they are in the above example. So, this is a per‐
3630 fectly legal (though ugly) pipe table:
3631 fruit| price
3633 -----|-----:
3634 apple|2.05
3635 pear|1.37
3636 orange|3.09
3637 The cells of pipe tables cannot contain block elements like paragraphs
3639 and lists, and cannot span multiple lines. If a pipe table contains a
3640 row whose Markdown content is wider than the column width (see --col‐
3641 umns), then the table will take up the full text width and the cell
3642 contents will wrap, with the relative cell widths determined by the
3643 number of dashes in the line separating the table header from the table
3644 body. (For example ---|- would make the first column 3/4 and the sec‐
3645 ond column 1/4 of the full text width.) On the other hand, if no lines
3646 are wider than column width, then cell contents will not be wrapped,
3647 and the cells will be sized to their contents.
3648 Note: pandoc also recognizes pipe tables of the following form, as can
3650 be produced by Emacs’ orgtbl-mode:
3651 | One | Two |
3653 |-----+-------|
3654 | my | table |
3655 | is | nice |
3656 The difference is that + is used instead of |. Other orgtbl features
3658 are not supported. In particular, to get non-default column alignment,
3659 you’ll need to add colons as above.
3660 Metadata blocks
3662 Extension: pandoc_title_block
3663 If the file begins with a title block
3664 % title
3666 % author(s) (separated by semicolons)
3667 % date
3668 it will be parsed as bibliographic information, not regular text. (It
3670 will be used, for example, in the title of standalone LaTeX or HTML
3671 output.) The block may contain just a title, a title and an author, or
3672 all three elements. If you want to include an author but no title, or
3673 a title and a date but no author, you need a blank line:
3674 %
3676 % Author
3677 % My title
3679 %
3680 % June 15, 2006
3681 The title may occupy multiple lines, but continuation lines must begin
3683 with leading space, thus:
3684 % My title
3686 on multiple lines
3687 If a document has multiple authors, the authors may be put on separate
3689 lines with leading space, or separated by semicolons, or both. So, all
3690 of the following are equivalent:
3691 % Author One
3693 Author Two
3694 % Author One; Author Two
3696 % Author One;
3698 Author Two
3699 The date must fit on one line.
3701 All three metadata fields may contain standard inline formatting (ital‐
3703 ics, links, footnotes, etc.).
3704 Title blocks will always be parsed, but they will affect the output on‐
3706 ly when the --standalone (-s) option is chosen. In HTML output, titles
3707 will appear twice: once in the document head – this is the title that
3708 will appear at the top of the window in a browser – and once at the be‐
3709 ginning of the document body. The title in the document head can have
3710 an optional prefix attached (--title-prefix or -T option). The title
3711 in the body appears as an H1 element with class “title”, so it can be
3712 suppressed or reformatted with CSS. If a title prefix is specified
3713 with -T and no title block appears in the document, the title prefix
3714 will be used by itself as the HTML title.
3715 The man page writer extracts a title, man page section number, and oth‐
3717 er header and footer information from the title line. The title is as‐
3718 sumed to be the first word on the title line, which may optionally end
3719 with a (single-digit) section number in parentheses. (There should be
3720 no space between the title and the parentheses.) Anything after this
3721 is assumed to be additional footer and header text. A single pipe
3722 character (|) should be used to separate the footer text from the head‐
3723 er text. Thus,
3724 % PANDOC(1)
3726 will yield a man page with the title PANDOC and section 1.
3728 % PANDOC(1) Pandoc User Manuals
3730 will also have “Pandoc User Manuals” in the footer.
3732 % PANDOC(1) Pandoc User Manuals | Version 4.0
3734 will also have “Version 4.0” in the header.
3736 Extension: yaml_metadata_block
3738 A YAML metadata block is a valid YAML object, delimited by a line of
3739 three hyphens (---) at the top and a line of three hyphens (---) or
3740 three dots (...) at the bottom. A YAML metadata block may occur any‐
3741 where in the document, but if it is not at the beginning, it must be
3742 preceded by a blank line. (Note that, because of the way pandoc con‐
3743 catenates input files when several are provided, you may also keep the
3744 metadata in a separate YAML file and pass it to pandoc as an argument,
3745 along with your Markdown files:
3746 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
3748 Just be sure that the YAML file begins with --- and ends with --- or
3750 ....) Alternatively, you can use the --metadata-file option. Using
3751 that approach however, you cannot reference content (like footnotes)
3752 from the main markdown input document.
3753 Metadata will be taken from the fields of the YAML object and added to
3755 any existing document metadata. Metadata can contain lists and objects
3756 (nested arbitrarily), but all string scalars will be interpreted as
3757 Markdown. Fields with names ending in an underscore will be ignored by
3758 pandoc. (They may be given a role by external processors.) Field names
3759 must not be interpretable as YAML numbers or boolean values (so, for
3760 example, yes, True, and 15 cannot be used as field names).
3761 A document may contain multiple metadata blocks. If two metadata
3763 blocks attempt to set the same field, the value from the second block
3764 will be taken.
3765 When pandoc is used with -t markdown to create a Markdown document, a
3767 YAML metadata block will be produced only if the -s/--standalone option
3768 is used. All of the metadata will appear in a single block at the be‐
3769 ginning of the document.
3770 Note that YAML escaping rules must be followed. Thus, for example, if
3772 a title contains a colon, it must be quoted, and if it contains a back‐
3773 slash escape, then it must be ensured that it is not treated as a YAML
3774 escape sequence. The pipe character (|) can be used to begin an in‐
3775 dented block that will be interpreted literally, without need for es‐
3776 caping. This form is necessary when the field contains blank lines or
3777 block-level formatting:
3778 ---
3780 title: 'This is the title: it contains a colon'
3781 author:
3782 - Author One
3783 - Author Two
3784 keywords: [nothing, nothingness]
3785 abstract: |
3786 This is the abstract.
3787 It consists of two paragraphs.
3789 ...
3790 The literal block after the | must be indented relative to the line
3792 containing the |. If it is not, the YAML will be invalid and pandoc
3793 will not interpret it as metadata. For an overview of the complex
3794 rules governing YAML, see the Wikipedia entry on YAML syntax.
3795 Template variables will be set automatically from the metadata. Thus,
3797 for example, in writing HTML, the variable abstract will be set to the
3798 HTML equivalent of the Markdown in the abstract field:
3799 <p>This is the abstract.</p>
3801 <p>It consists of two paragraphs.</p>
3802 Variables can contain arbitrary YAML structures, but the template must
3804 match this structure. The author variable in the default templates ex‐
3805 pects a simple list or string, but can be changed to support more com‐
3806 plicated structures. The following combination, for example, would add
3807 an affiliation to the author if one is given:
3808 ---
3810 title: The document title
3811 author:
3812 - name: Author One
3813 affiliation: University of Somewhere
3814 - name: Author Two
3815 affiliation: University of Nowhere
3816 ...
3817 To use the structured authors in the example above, you would need a
3819 custom template:
3820 $for(author)$
3822 $if(author.name)$
3823 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
3824 $else$
3825 $author$
3826 $endif$
3827 $endfor$
3828 Raw content to include in the document’s header may be specified using
3830 header-includes; however, it is important to mark up this content as
3831 raw code for a particular output format, using the raw_attribute exten‐
3832 sion), or it will be interpreted as markdown. For example:
3833 header-includes:
3835 - |
3836 ```{=latex}
3837 \let\oldsection\section
3838 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
3839 ```
3840 Note: the yaml_metadata_block extension works with commonmark as well
3842 as markdown (and it is enabled by default in gfm and commonmark_x).
3843 However, in these formats the following restrictions apply:
3844 • The YAML metadata block must occur at the beginning of the document
3846 (and there can be only one). If multiple files are given as argu‐
3847 ments to pandoc, only the first can be a YAML metadata block.
3848 • The leaf nodes of the YAML structure are parsed in isolation from
3850 each other and from the rest of the document. So, for example, you
3851 can’t use a reference link in these contexts if the link definition
3852 is somewhere else in the document.
3853 Backslash escapes
3855 Extension: all_symbols_escapable
3856 Except inside a code block or inline code, any punctuation or space
3857 character preceded by a backslash will be treated literally, even if it
3858 would normally indicate formatting. Thus, for example, if one writes
3859 *\*hello\**
3861 one will get
3863 <em>*hello*</em>
3865 instead of
3867 <strong>hello</strong>
3869 This rule is easier to remember than standard Markdown’s rule, which
3871 allows only the following characters to be backslash-escaped:
3872 \`*_{}[]()>#+-.!
3874 (However, if the markdown_strict format is used, the standard Markdown
3876 rule will be used.)
3877 A backslash-escaped space is parsed as a nonbreaking space. In TeX
3879 output, it will appear as ~. In HTML and XML output, it will appear as
3880 a literal unicode nonbreaking space character (note that it will thus
3881 actually look “invisible” in the generated HTML source; you can still
3882 use the --ascii command-line option to make it appear as an explicit
3883 entity).
3884 A backslash-escaped newline (i.e. a backslash occurring at the end of a
3886 line) is parsed as a hard line break. It will appear in TeX output as
3887 \\ and in HTML as <br />. This is a nice alternative to Markdown’s
3888 “invisible” way of indicating hard line breaks using two trailing spa‐
3889 ces on a line.
3890 Backslash escapes do not work in verbatim contexts.
3892 Inline formatting
3894 Emphasis
3895 To emphasize some text, surround it with *s or _, like this:
3896 This text is _emphasized with underscores_, and this
3898 is *emphasized with asterisks*.
3899 Double * or _ produces strong emphasis:
3901 This is **strong emphasis** and __with underscores__.
3903 A * or _ character surrounded by spaces, or backslash-escaped, will not
3905 trigger emphasis:
3906 This is * not emphasized *, and \*neither is this\*.
3908 Extension: intraword_underscores
3910 Because _ is sometimes used inside words and identifiers, pandoc does
3911 not interpret a _ surrounded by alphanumeric characters as an emphasis
3912 marker. If you want to emphasize just part of a word, use *:
3913 feas*ible*, not feas*able*.
3915 Strikeout
3917 Extension: strikeout
3918 To strikeout a section of text with a horizontal line, begin and end it
3919 with ~~. Thus, for example,
3920 This ~~is deleted text.~~
3922 Superscripts and subscripts
3924 Extension: superscript, subscript
3925 Superscripts may be written by surrounding the superscripted text by ^
3926 characters; subscripts may be written by surrounding the subscripted
3927 text by ~ characters. Thus, for example,
3928 H~2~O is a liquid. 2^10^ is 1024.
3930 The text between ^...^ or ~...~ may not contain spaces or newlines. If
3932 the superscripted or subscripted text contains spaces, these spaces
3933 must be escaped with backslashes. (This is to prevent accidental su‐
3934 perscripting and subscripting through the ordinary use of ~ and ^, and
3935 also bad interactions with footnotes.) Thus, if you want the letter P
3936 with `a cat' in subscripts, use P~a\ cat~, not P~a cat~.
3937 Verbatim
3939 To make a short span of text verbatim, put it inside backticks:
3940 What is the difference between `>>=` and `>>`?
3942 If the verbatim text includes a backtick, use double backticks:
3944 Here is a literal backtick `` ` ``.
3946 (The spaces after the opening backticks and before the closing back‐
3948 ticks will be ignored.)
3949 The general rule is that a verbatim span starts with a string of con‐
3951 secutive backticks (optionally followed by a space) and ends with a
3952 string of the same number of backticks (optionally preceded by a
3953 space).
3954 Note that backslash-escapes (and other Markdown constructs) do not work
3956 in verbatim contexts:
3957 This is a backslash followed by an asterisk: `\*`.
3959 Extension: inline_code_attributes
3961 Attributes can be attached to verbatim text, just as with fenced code
3962 blocks:
3963 `<$>`{.haskell}
3965 Small caps
3967 To write small caps, use the smallcaps class:
3968 [Small caps]{.smallcaps}
3970 Or, without the bracketed_spans extension:
3972 <span class="smallcaps">Small caps</span>
3974 For compatibility with other Markdown flavors, CSS is also supported:
3976 <span style="font-variant:small-caps;">Small caps</span>
3978 This will work in all output formats that support small caps.
3980 Math
3982 Extension: tex_math_dollars
3983 Anything between two $ characters will be treated as TeX math. The
3984 opening $ must have a non-space character immediately to its right,
3985 while the closing $ must have a non-space character immediately to its
3986 left, and must not be followed immediately by a digit. Thus, $20,000
3987 and $30,000 won’t parse as math. If for some reason you need to en‐
3988 close text in literal $ characters, backslash-escape them and they
3989 won’t be treated as math delimiters.
3990 For display math, use $$ delimiters. (In this case, the delimiters may
3992 be separated from the formula by whitespace. However, there can be no
3993 blank lines betwen the opening and closing $$ delimiters.)
3994 TeX math will be printed in all output formats. How it is rendered de‐
3996 pends on the output format:
3997 LaTeX It will appear verbatim surrounded by \(...\) (for inline math)
3999 or \[...\] (for display math).
4000 Markdown, Emacs Org mode, ConTeXt, ZimWiki
4002 It will appear verbatim surrounded by $...$ (for inline math) or
4003 $$...$$ (for display math).
4004 XWiki It will appear verbatim surrounded by {{formula}}..{{/formula}}.
4006 reStructuredText
4008 It will be rendered using an interpreted text role :math:.
4009 AsciiDoc
4011 For AsciiDoc output format (-t asciidoc) it will appear verbatim
4012 surrounded by latexmath:[$...$] (for inline math) or [latex‐
4013 math]++++\[...\]+++ (for display math). For AsciiDoctor output
4014 format (-t asciidoctor) the LaTex delimiters ($..$ and \[..\])
4015 are omitted.
4016 Texinfo
4018 It will be rendered inside a @math command.
4019 roff man, Jira markup
4021 It will be rendered verbatim without $’s.
4022 MediaWiki, DokuWiki
4024 It will be rendered inside <math> tags.
4025 Textile
4027 It will be rendered inside <span class="math"> tags.
4028 RTF, OpenDocument
4030 It will be rendered, if possible, using Unicode characters, and
4031 will otherwise appear verbatim.
4032 ODT It will be rendered, if possible, using MathML.
4034 DocBook
4036 If the --mathml flag is used, it will be rendered using MathML
4037 in an inlineequation or informalequation tag. Otherwise it will
4038 be rendered, if possible, using Unicode characters.
4039 Docx It will be rendered using OMML math markup.
4041 FictionBook2
4043 If the --webtex option is used, formulas are rendered as images
4044 using CodeCogs or other compatible web service, downloaded and
4045 embedded in the e-book. Otherwise, they will appear verbatim.
4046 HTML, Slidy, DZSlides, S5, EPUB
4048 The way math is rendered in HTML will depend on the command-line
4049 options selected. Therefore see Math rendering in HTML above.
4050 Raw HTML
4052 Extension: raw_html
4053 Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
4054 ment (except verbatim contexts, where <, >, and & are interpreted lit‐
4055 erally). (Technically this is not an extension, since standard Mark‐
4056 down allows it, but it has been made an extension so that it can be
4057 disabled if desired.)
4058 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
4060 DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile out‐
4061 put, and suppressed in other formats.
4062 For a more explicit way of including raw HTML in a Markdown document,
4064 see the raw_attribute extension.
4065 In the CommonMark format, if raw_html is enabled, superscripts, sub‐
4067 scripts, strikeouts and small capitals will be represented as HTML.
4068 Otherwise, plain-text fallbacks will be used. Note that even if
4069 raw_html is disabled, tables will be rendered with HTML syntax if they
4070 cannot use pipe syntax.
4071 Extension: markdown_in_html_blocks
4073 Standard Markdown allows you to include HTML “blocks”: blocks of HTML
4074 between balanced tags that are separated from the surrounding text with
4075 blank lines, and start and end at the left margin. Within these
4076 blocks, everything is interpreted as HTML, not Markdown; so (for exam‐
4077 ple), * does not signify emphasis.
4078 Pandoc behaves this way when the markdown_strict format is used; but by
4080 default, pandoc interprets material between HTML block tags as Mark‐
4081 down. Thus, for example, pandoc will turn
4082 <table>
4084 <tr>
4085 <td>*one*</td>
4086 <td>[a link](https://google.com)</td>
4087 </tr>
4088 </table>
4089 into
4091 <table>
4093 <tr>
4094 <td><em>one</em></td>
4095 <td><a href="https://google.com">a link</a></td>
4096 </tr>
4097 </table>
4098 whereas Markdown.pl will preserve it as is.
4100 There is one exception to this rule: text between <script>, <style>,
4102 and <textarea> tags is not interpreted as Markdown.
4103 This departure from standard Markdown should make it easier to mix
4105 Markdown with HTML block elements. For example, one can surround a
4106 block of Markdown text with <div> tags without preventing it from being
4107 interpreted as Markdown.
4108 Extension: native_divs
4110 Use native pandoc Div blocks for content inside <div> tags. For the
4111 most part this should give the same output as markdown_in_html_blocks,
4112 but it makes it easier to write pandoc filters to manipulate groups of
4113 blocks.
4114 Extension: native_spans
4116 Use native pandoc Span blocks for content inside <span> tags. For the
4117 most part this should give the same output as raw_html, but it makes it
4118 easier to write pandoc filters to manipulate groups of inlines.
4119 Extension: raw_tex
4121 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
4122 be included in a document. Inline TeX commands will be preserved and
4123 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
4124 you can use LaTeX to include BibTeX citations:
4125 This result was proved in \cite{jones.1967}.
4127 Note that in LaTeX environments, like
4129 \begin{tabular}{|l|l|}\hline
4131 Age & Frequency \\ \hline
4132 18--25 & 15 \\
4133 26--35 & 33 \\
4134 36--45 & 22 \\ \hline
4135 \end{tabular}
4136 the material between the begin and end tags will be interpreted as raw
4138 LaTeX, not as Markdown.
4139 For a more explicit and flexible way of including raw TeX in a Markdown
4141 document, see the raw_attribute extension.
4142 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
4144 Emacs Org mode, and ConTeXt.
4145 Generic raw attribute
4147 Extension: raw_attribute
4148 Inline spans and fenced code blocks with a special kind of attribute
4149 will be parsed as raw content with the designated format. For example,
4150 the following produces a raw roff ms block:
4151 ```{=ms}
4153 .MYMACRO
4154 blah blah
4155 ```
4156 And the following produces a raw html inline element:
4158 This is `<a>html</a>`{=html}
4160 This can be useful to insert raw xml into docx documents, e.g. a page‐
4162 break:
4163 ```{=openxml}
4165 <w:p>
4166 <w:r>
4167 <w:br w:type="page"/>
4168 </w:r>
4169 </w:p>
4170 ```
4171 The format name should match the target format name (see -t/--to,
4173 above, for a list, or use pandoc --list-output-formats). Use openxml
4174 for docx output, opendocument for odt output, html5 for epub3 output,
4175 html4 for epub2 output, and latex, beamer, ms, or html5 for pdf output
4176 (depending on what you use for --pdf-engine).
4177 This extension presupposes that the relevant kind of inline code or
4179 fenced code block is enabled. Thus, for example, to use a raw attri‐
4180 bute with a backtick code block, backtick_code_blocks must be enabled.
4181 The raw attribute cannot be combined with regular attributes.
4183 LaTeX macros
4185 Extension: latex_macros
4186 When this extension is enabled, pandoc will parse LaTeX macro defini‐
4187 tions and apply the resulting macros to all LaTeX math and raw LaTeX.
4188 So, for example, the following will work in all output formats, not
4189 just LaTeX:
4190 \newcommand{\tuple}[1]{\langle #1 \rangle}
4192 $\tuple{a, b, c}$
4194 Note that LaTeX macros will not be applied if they occur inside a raw
4196 span or block marked with the raw_attribute extension.
4197 When latex_macros is disabled, the raw LaTeX and math will not have
4199 macros applied. This is usually a better approach when you are target‐
4200 ing LaTeX or PDF.
4201 Macro definitions in LaTeX will be passed through as raw LaTeX only if
4203 latex_macros is not enabled. Macro definitions in Markdown source (or
4204 other formats allowing raw_tex) will be passed through regardless of
4205 whether latex_macros is enabled.
4206 Links
4208 Markdown allows links to be specified in several ways.
4209 Automatic links
4211 If you enclose a URL or email address in pointy brackets, it will be‐
4212 come a link:
4213 <https://google.com>
4215 <sam@green.eggs.ham>
4216 Inline links
4218 An inline link consists of the link text in square brackets, followed
4219 by the URL in parentheses. (Optionally, the URL can be followed by a
4220 link title, in quotes.)
4221 This is an [inline link](/url), and here's [one with
4223 a title](https://fsf.org "click here for a good time!").
4224 There can be no space between the bracketed part and the parenthesized
4226 part. The link text can contain formatting (such as emphasis), but the
4227 title cannot.
4228 Email addresses in inline links are not autodetected, so they have to
4230 be prefixed with mailto:
4231 [Write me!](mailto:sam@green.eggs.ham)
4233 Reference links
4235 An explicit reference link has two parts, the link itself and the link
4236 definition, which may occur elsewhere in the document (either before or
4237 after the link).
4238 The link consists of link text in square brackets, followed by a label
4240 in square brackets. (There cannot be space between the two unless the
4241 spaced_reference_links extension is enabled.) The link definition con‐
4242 sists of the bracketed label, followed by a colon and a space, followed
4243 by the URL, and optionally (after a space) a link title either in
4244 quotes or in parentheses. The label must not be parseable as a cita‐
4245 tion (assuming the citations extension is enabled): citations take
4246 precedence over link labels.
4247 Here are some examples:
4249 [my label 1]: /foo/bar.html "My title, optional"
4251 [my label 2]: /foo
4252 [my label 3]: https://fsf.org (The free software foundation)
4253 [my label 4]: /bar#special 'A title in single quotes'
4254 The URL may optionally be surrounded by angle brackets:
4256 [my label 5]: <http://foo.bar.baz>
4258 The title may go on the next line:
4260 [my label 3]: https://fsf.org
4262 "The free software foundation"
4263 Note that link labels are not case sensitive. So, this will work:
4265 Here is [my link][FOO]
4267 [Foo]: /bar/baz
4269 In an implicit reference link, the second pair of brackets is empty:
4271 See [my website][].
4273 [my website]: http://foo.bar.baz
4275 Note: In Markdown.pl and most other Markdown implementations, reference
4277 link definitions cannot occur in nested constructions such as list
4278 items or block quotes. Pandoc lifts this arbitrary seeming restric‐
4279 tion. So the following is fine in pandoc, though not in most other im‐
4280 plementations:
4281 > My block [quote].
4283 >
4284 > [quote]: /foo
4285 Extension: shortcut_reference_links
4287 In a shortcut reference link, the second pair of brackets may be omit‐
4288 ted entirely:
4289 See [my website].
4291 [my website]: http://foo.bar.baz
4293 Internal links
4295 To link to another section of the same document, use the automatically
4296 generated identifier (see Heading identifiers). For example:
4297 See the [Introduction](#introduction).
4299 or
4301 See the [Introduction].
4303 [Introduction]: #introduction
4305 Internal links are currently supported for HTML formats (including HTML
4307 slide shows and EPUB), LaTeX, and ConTeXt.
4308 Images
4310 A link immediately preceded by a ! will be treated as an image. The
4311 link text will be used as the image’s alt text:
4312 
4314 ![movie reel]
4316 [movie reel]: movie.gif
4318 Extension: implicit_figures
4320 An image with nonempty alt text, occurring by itself in a paragraph,
4321 will be rendered as a figure with a caption. The image’s alt text will
4322 be used as the caption.
4323 
4325 How this is rendered depends on the output format. Some output formats
4327 (e.g. RTF) do not yet support figures. In those formats, you’ll just
4328 get an image in a paragraph by itself, with no caption.
4329 If you just want a regular inline image, just make sure it is not the
4331 only thing in the paragraph. One way to do this is to insert a non‐
4332 breaking space after the image:
4333 \
4335 Note that in reveal.js slide shows, an image in a paragraph by itself
4337 that has the stretch class will fill the screen, and the caption and
4338 figure tags will be omitted.
4339 Extension: link_attributes
4341 Attributes can be set on links and images:
4342 An inline {#id .class width=30 height=20px}
4344 and a reference ![image][ref] with attributes.
4345 [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
4347 (This syntax is compatible with PHP Markdown Extra when only #id and
4349 .class are used.)
4350 For HTML and EPUB, all known HTML5 attributes except width and height
4352 (but including srcset and sizes) are passed through as is. Unknown at‐
4353 tributes are passed through as custom attributes, with data- prepended.
4354 The other writers ignore attributes that are not specifically supported
4355 by their output format.
4356 The width and height attributes on images are treated specially. When
4358 used without a unit, the unit is assumed to be pixels. However, any of
4359 the following unit identifiers can be used: px, cm, mm, in, inch and %.
4360 There must not be any spaces between the number and the unit. For ex‐
4361 ample:
4362 { width=50% }
4364 • Dimensions may be converted to a form that is compatible with the
4366 output format (for example, dimensions given in pixels will be con‐
4367 verted to inches when converting HTML to LaTeX). Conversion between
4368 pixels and physical measurements is affected by the --dpi option (by
4369 default, 96 dpi is assumed, unless the image itself contains dpi in‐
4370 formation).
4371 • The % unit is generally relative to some available space. For exam‐
4373 ple the above example will render to the following.
4374 • HTML: <img href="file.jpg" style="width: 50%;" />
4376 • LaTeX: \includegraphics[width=0.5\textwidth,height=\text‐
4378 height]{file.jpg} (If you’re using a custom template, you need to
4379 configure graphicx as in the default template.)
4380 • ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
4382 • Some output formats have a notion of a class (ConTeXt) or a unique
4384 identifier (LaTeX \caption), or both (HTML).
4385 • When no width or height attributes are specified, the fallback is to
4387 look at the image resolution and the dpi metadata embedded in the im‐
4388 age file.
4389 Divs and Spans
4391 Using the native_divs and native_spans extensions (see above), HTML
4392 syntax can be used as part of markdown to create native Div and Span
4393 elements in the pandoc AST (as opposed to raw HTML). However, there is
4394 also nicer syntax available:
4395 Extension: fenced_divs
4397 Allow special fenced syntax for native Div blocks. A Div starts with a
4398 fence containing at least three consecutive colons plus some at‐
4399 tributes. The attributes may optionally be followed by another string
4400 of consecutive colons. The attribute syntax is exactly as in fenced
4401 code blocks (see Extension: fenced_code_attributes). As with fenced
4402 code blocks, one can use either attributes in curly braces or a single
4403 unbraced word, which will be treated as a class name. The Div ends
4404 with another line containing a string of at least three consecutive
4405 colons. The fenced Div should be separated by blank lines from preced‐
4406 ing and following blocks.
4407 Example:
4409 ::::: {#special .sidebar}
4411 Here is a paragraph.
4412 And another.
4414 :::::
4415 Fenced divs can be nested. Opening fences are distinguished because
4417 they must have attributes:
4418 ::: Warning ::::::
4420 This is a warning.
4421 ::: Danger
4423 This is a warning within a warning.
4424 :::
4425 ::::::::::::::::::
4426 Fences without attributes are always closing fences. Unlike with
4428 fenced code blocks, the number of colons in the closing fence need not
4429 match the number in the opening fence. However, it can be helpful for
4430 visual clarity to use fences of different lengths to distinguish nested
4431 divs from their parents.
4432 Extension: bracketed_spans
4434 A bracketed sequence of inlines, as one would use to begin a link, will
4435 be treated as a Span with attributes if it is followed immediately by
4436 attributes:
4437 [This is *some text*]{.class key="val"}
4439 Footnotes
4441 Extension: footnotes
4442 Pandoc’s Markdown allows footnotes, using the following syntax:
4443 Here is a footnote reference,[^1] and another.[^longnote]
4445 [^1]: Here is the footnote.
4447 [^longnote]: Here's one with multiple blocks.
4449 Subsequent paragraphs are indented to show that they
4451 belong to the previous footnote.
4452 { some.code }
4454 The whole paragraph can be indented, or just the first
4456 line. In this way, multi-paragraph footnotes work like
4457 multi-paragraph list items.
4458 This paragraph won't be part of the note, because it
4460 isn't indented.
4461 The identifiers in footnote references may not contain spaces, tabs, or
4463 newlines. These identifiers are used only to correlate the footnote
4464 reference with the note itself; in the output, footnotes will be num‐
4465 bered sequentially.
4466 The footnotes themselves need not be placed at the end of the document.
4468 They may appear anywhere except inside other block elements (lists,
4469 block quotes, tables, etc.). Each footnote should be separated from
4470 surrounding content (including other footnotes) by blank lines.
4471 Extension: inline_notes
4473 Inline footnotes are also allowed (though, unlike regular notes, they
4474 cannot contain multiple paragraphs). The syntax is as follows:
4475 Here is an inline note.^[Inlines notes are easier to write, since
4477 you don't have to pick an identifier and move down to type the
4478 note.]
4479 Inline and regular footnotes may be mixed freely.
4481 Citation syntax
4483 Extension: citations
4484 To cite a bibliographic item with an identifier foo, use the syntax
4485 @foo. Normal citations should be included in square brackets, with
4486 semicolons separating distinct items:
4487 Blah blah [@doe99; @smith2000; @smith2004].
4489 How this is rendered depends on the citation style. In an author-date
4491 style, it might render as
4492 Blah blah (Doe 1999, Smith 2000, 2004).
4494 In a footnote style, it might render as
4496 Blah blah.[^1]
4498 [^1]: John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
4500 Susan Smith, "Flies," *Journal of Insects* (2000);
4501 Susan Smith, "Bees," *Journal of Insects* (2004).
4502 See the CSL user documentation for more information about CSL styles
4504 and how they affect rendering.
4505 Unless a citation key start with a letter, digit, or _, and contains
4507 only alphanumerics and internal punctuation characters (:.#$%&-+?<>~/),
4508 it must be surrounded by curly braces, which are not considered part of
4509 the key. In @Foo_bar.baz., the key is Foo_bar.baz. The final period
4510 is not internal punctuation, so it is not included in the key. In
4511 @{Foo_bar.baz.}, the key is Foo_bar.baz., including the final period.
4512 The curly braces are recommended if you use URLs as keys:
4513 [@{https://example.com/bib?name=foobar&date=2000}, p. 33].
4514 Citation items may optionally include a prefix, a locator, and a suf‐
4516 fix. In
4517 Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].
4519 The first item (doe99) has prefix see, locator pp. 33-35, and suffix
4521 and *passim*. The second item (smith04) has locator chap. 1 and no
4522 prefix or suffix.
4523 Pandoc uses some heuristics to separate the locator from the rest of
4525 the subject. It is sensitive to the locator terms defined in the CSL
4526 locale files. Either abbreviated or unabbreviated forms are accepted.
4527 In the en-US locale, locator terms can be written in either singular or
4528 plural forms, as book, bk./bks.; chapter, chap./chaps.; column,
4529 col./cols.; figure, fig./figs.; folio, fol./fols.; number, no./nos.;
4530 line, l./ll.; note, n./nn.; opus, op./opp.; page, p./pp.; paragraph,
4531 para./paras.; part, pt./pts.; section, sec./secs.; sub verbo,
4532 s.v./s.vv.; verse, v./vv.; volume, vol./vols.; ¶/¶¶; §/§§. If no loca‐
4533 tor term is used, “page” is assumed.
4534 In complex cases, you can force something to be treated as a locator by
4536 enclosing it in curly braces or prevent parsing the suffix as locator
4537 by prepending curly braces:
4538 [@smith{ii, A, D-Z}, with a suffix]
4540 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
4541 [@smith{}, 99 years later]
4542 A minus sign (-) before the @ will suppress mention of the author in
4544 the citation. This can be useful when the author is already mentioned
4545 in the text:
4546 Smith says blah [-@smith04].
4548 You can also write an author-in-text citation, by omitting the square
4550 brackets:
4551 @smith04 says blah.
4553 @smith04 [p. 33] says blah.
4555 This will cause the author’s name to be rendered, followed by the bib‐
4557 liographical details. Use this form when you want to make the citation
4558 the subject of a sentence.
4559 When you are using a note style, it is usually better to let citeproc
4561 create the footnotes from citations rather than writing an explicit
4562 note. If you do write an explicit note that contains a citation, note
4563 that normal citations will be put in parentheses, while author-in-text
4564 citations will not. For this reason, it is sometimes preferable to use
4565 the author-in-text style inside notes when using a note style.
4566 Non-default extensions
4568 The following Markdown syntax extensions are not enabled by default in
4569 pandoc, but may be enabled by adding +EXTENSION to the format name,
4570 where EXTENSION is the name of the extension. Thus, for example, mark‐
4571 down+hard_line_breaks is Markdown with hard line breaks.
4572 Extension: rebase_relative_paths
4574 Rewrite relative paths for Markdown links and images, depending on the
4575 path of the file containing the link or image link. For each link or
4576 image, pandoc will compute the directory of the containing file, rela‐
4577 tive to the working directory, and prepend the resulting path to the
4578 link or image path.
4579 The use of this extension is best understood by example. Suppose you
4581 have a a subdirectory for each chapter of a book, chap1, chap2, chap3.
4582 Each contains a file text.md and a number of images used in the chap‐
4583 ter. You would like to have  in chap1/text.md re‐
4584 fer to chap1/spider.jpg and  in chap2/text.md refer
4585 to chap2/spider.jpg. To do this, use
4586 pandoc chap*/*.md -f markdown+rebase_relative_paths
4588 Without this extension, you would have to use  in chap1/text.md and  in
4591 chap2/text.md. Links with relative paths will be rewritten in the same
4592 way as images.
4593 Absolute paths and URLs are not changed. Neither are empty paths or
4595 paths consisting entirely of a fragment, e.g., #foo.
4596 Note that relative paths in reference links and images will be rewrit‐
4598 ten relative to the file containing the link reference definition, not
4599 the file containing the reference link or image itself, if these dif‐
4600 fer.
4601 Extension: attributes
4603 Allows attributes to be attached to any inline or block-level element.
4604 The syntax for the attributes is the same as that used in header_at‐
4605 tributes.
4606 • Attributes that occur immediately after an inline element affect that
4608 element. If they follow a space, then they belong to the space.
4609 (Hence, this option subsumes inline_code_attributes and link_at‐
4610 tributes.)
4611 • Attributes that occur immediately before a block element, on a line
4613 by themselves, affect that element.
4614 • Consecutive attribute specifiers may be used, either for blocks or
4616 for inlines. Their attributes will be combined.
4617 • Attributes that occur at the end of the text of a Setext or ATX head‐
4619 ing (separated by whitespace from the text) affect the heading ele‐
4620 ment. (Hence, this option subsumes header_attributes.)
4621 • Attributes that occur after the opening fence in a fenced code block
4623 affect the code block element. (Hence, this option subsumes
4624 fenced_code_attributes.)
4625 • Attributes that occur at the end of a reference link definition af‐
4627 fect links that refer to that definition.
4628 Note that pandoc’s AST does not currently allow attributes to be at‐
4630 tached to arbitrary elements. Hence a Span or Div container will be
4631 added if needed.
4632 Extension: old_dashes
4634 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - be‐
4635 fore a numeral is an en-dash, and -- is an em-dash. This option only
4636 has an effect if smart is enabled. It is selected automatically for
4637 textile input.
4638 Extension: angle_brackets_escapable
4640 Allow < and > to be backslash-escaped, as they can be in GitHub fla‐
4641 vored Markdown but not original Markdown. This is implied by pandoc’s
4642 default all_symbols_escapable.
4643 Extension: lists_without_preceding_blankline
4645 Allow a list to occur right after a paragraph, with no intervening
4646 blank space.
4647 Extension: four_space_rule
4649 Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
4650 ces indent are needed for list item continuation paragraphs.
4651 Extension: spaced_reference_links
4653 Allow whitespace between the two components of a reference link, for
4654 example,
4655 [foo] [bar].
4657 Extension: hard_line_breaks
4659 Causes all newlines within a paragraph to be interpreted as hard line
4660 breaks instead of spaces.
4661 Extension: ignore_line_breaks
4663 Causes newlines within a paragraph to be ignored, rather than being
4664 treated as spaces or as hard line breaks. This option is intended for
4665 use with East Asian languages where spaces are not used between words,
4666 but text is divided into lines for readability.
4667 Extension: east_asian_line_breaks
4669 Causes newlines within a paragraph to be ignored, rather than being
4670 treated as spaces or as hard line breaks, when they occur between two
4671 East Asian wide characters. This is a better choice than ig‐
4672 nore_line_breaks for texts that include a mix of East Asian wide char‐
4673 acters and other characters.
4674 Extension: emoji
4676 Parses textual emojis like :smile: as Unicode emoticons.
4677 Extension: tex_math_single_backslash
4679 Causes anything between \( and \) to be interpreted as inline TeX math,
4680 and anything between \[ and \] to be interpreted as display TeX math.
4681 Note: a drawback of this extension is that it precludes escaping ( and
4682 [.
4683 Extension: tex_math_double_backslash
4685 Causes anything between \\( and \\) to be interpreted as inline TeX
4686 math, and anything between \\[ and \\] to be interpreted as display TeX
4687 math.
4688 Extension: markdown_attribute
4690 By default, pandoc interprets material inside block-level tags as Mark‐
4691 down. This extension changes the behavior so that Markdown is only
4692 parsed inside block-level tags if the tags have the attribute mark‐
4693 down=1.
4694 Extension: mmd_title_block
4696 Enables a MultiMarkdown style title block at the top of the document,
4697 for example:
4698 Title: My title
4700 Author: John Doe
4701 Date: September 1, 2008
4702 Comment: This is a sample mmd title block, with
4703 a field spanning multiple lines.
4704 See the MultiMarkdown documentation for details. If pandoc_title_block
4706 or yaml_metadata_block is enabled, it will take precedence over mmd_ti‐
4707 tle_block.
4708 Extension: abbreviations
4710 Parses PHP Markdown Extra abbreviation keys, like
4711 *[HTML]: Hypertext Markup Language
4713 Note that the pandoc document model does not support abbreviations, so
4715 if this extension is enabled, abbreviation keys are simply skipped (as
4716 opposed to being parsed as paragraphs).
4717 Extension: autolink_bare_uris
4719 Makes all absolute URIs into links, even when not surrounded by pointy
4720 braces <...>.
4721 Extension: mmd_link_attributes
4723 Parses multimarkdown style key-value attributes on link and image ref‐
4724 erences. This extension should not be confused with the link_at‐
4725 tributes extension.
4726 This is a reference ![image][ref] with multimarkdown attributes.
4728 [ref]: https://path.to/image "Image title" width=20px height=30px
4730 id=myId class="myClass1 myClass2"
4731 Extension: mmd_header_identifiers
4733 Parses multimarkdown style heading identifiers (in square brackets, af‐
4734 ter the heading but before any trailing #s in an ATX heading).
4735 Extension: compact_definition_lists
4737 Activates the definition list syntax of pandoc 1.12.x and earlier.
4738 This syntax differs from the one described above under Definition lists
4739 in several respects:
4740 • No blank line is required between consecutive items of the definition
4742 list.
4743 • To get a “tight” or “compact” list, omit space between consecutive
4745 items; the space between a term and its definition does not affect
4746 anything.
4747 • Lazy wrapping of paragraphs is not allowed: the entire definition
4749 must be indented four spaces.
4750 Extension: gutenberg
4752 Use Project Gutenberg conventions for plain output: all-caps for strong
4753 emphasis, surround by underscores for regular emphasis, add extra blank
4754 space around headings.
4755 Extension: sourcepos
4757 Include source position attributes when parsing commonmark. For ele‐
4758 ments that accept attributes, a data-pos attribute is added; other ele‐
4759 ments are placed in a surrounding Div or Span elemnet with a data-pos
4760 attribute.
4761 Markdown variants
4763 In addition to pandoc’s extended Markdown, the following Markdown vari‐
4764 ants are supported:
4765 • markdown_phpextra (PHP Markdown Extra)
4767 • markdown_github (deprecated GitHub-Flavored Markdown)
4769 • markdown_mmd (MultiMarkdown)
4771 • markdown_strict (Markdown.pl)
4773 • commonmark (CommonMark)
4775 • gfm (Github-Flavored Markdown)
4777 • commonmark_x (CommonMark with many pandoc extensions)
4779 To see which extensions are supported for a given format, and which are
4781 enabled by default, you can use the command
4782 pandoc --list-extensions=FORMAT
4784 where FORMAT is replaced with the name of the format.
4786 Note that the list of extensions for commonmark, gfm, and commonmark_x
4788 are defined relative to default commonmark. So, for example, back‐
4789 tick_code_blocks does not appear as an extension, since it is enabled
4790 by default and cannot be disabled.
4791
4793 When the --citeproc option is used, pandoc can automatically generate
4794 citations and a bibliography in a number of styles. Basic usage is
4795 pandoc --citeproc myinput.txt
4797 To use this feature, you will need to have
4799 • a document containing citations (see Extension: citations);
4801 • a source of bibliographic data: either an external bibliography file
4803 or a list of references in the document’s YAML metadata
4804 • optionally, a CSL citation style.
4806 Specifying bibliographic data
4808 You can specify an external bibliography using the bibliography metada‐
4809 ta field in a YAML metadata section or the --bibliography command line
4810 argument. If you want to use multiple bibliography files, you can sup‐
4811 ply multiple --bibliography arguments or set bibliography metadata
4812 field to YAML array. A bibliography may have any of these formats:
4813 Format File extension
4815 ──────────────────────────
4816 BibLaTeX .bib
4817 BibTeX .bibtex
4818 CSL JSON .json
4819 CSL YAML .yaml
4820 Note that .bib can be used with both BibTeX and BibLaTeX files; use the
4822 extension .bibtex to force interpretation as BibTeX.
4823 In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside
4825 fields such as title; in CSL YAML databases, pandoc Markdown; and in
4826 CSL JSON databases, an HTML-like markup:
4827 <i>...</i>
4829 italics
4830 <b>...</b>
4832 bold
4833 <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
4835 small capitals
4836 <sub>...</sub>
4838 subscript
4839 <sup>...</sup>
4841 superscript
4842 <span class="nocase">...</span>
4844 prevent a phrase from being capitalized as title case
4845 As an alternative to specifying a bibliography file using --bibliogra‐
4847 phy or the YAML metadata field bibliography, you can include the cita‐
4848 tion data directly in the references field of the document’s YAML meta‐
4849 data. The field should contain an array of YAML-encoded references,
4850 for example:
4851 ---
4853 references:
4854 - type: article-journal
4855 id: WatsonCrick1953
4856 author:
4857 - family: Watson
4858 given: J. D.
4859 - family: Crick
4860 given: F. H. C.
4861 issued:
4862 date-parts:
4863 - - 1953
4864 - 4
4865 - 25
4866 title: 'Molecular structure of nucleic acids: a structure for
4867 deoxyribose nucleic acid'
4868 title-short: Molecular structure of nucleic acids
4869 container-title: Nature
4870 volume: 171
4871 issue: 4356
4872 page: 737-738
4873 DOI: 10.1038/171737a0
4874 URL: https://www.nature.com/articles/171737a0
4875 language: en-GB
4876 ...
4877 If both an external bibliography and inline (YAML metadata) references
4879 are provided, both will be used. In case of conflicting ids, the in‐
4880 line references will take precedence.
4881 Note that pandoc can be used to produce such a YAML metadata section
4883 from a BibTeX, BibLaTeX, or CSL JSON bibliography:
4884 pandoc chem.bib -s -f biblatex -t markdown
4886 pandoc chem.json -s -f csljson -t markdown
4887 Indeed, pandoc can convert between any of these citation formats:
4889 pandoc chem.bib -s -f biblatex -t csljson
4891 pandoc chem.yaml -s -f markdown -t biblatex
4892 Running pandoc on a bibliography file with the --citeproc option will
4894 create a formatted bibliography in the format of your choice:
4895 pandoc chem.bib -s --citeproc -o chem.html
4897 pandoc chem.bib -s --citeproc -o chem.pdf
4898 Capitalization in titles
4900 If you are using a bibtex or biblatex bibliography, then observe the
4901 following rules:
4902 • English titles should be in title case. Non-English titles should be
4904 in sentence case, and the langid field in biblatex should be set to
4905 the relevant language. (The following values are treated as English:
4906 american, british, canadian, english, australian, newzealand, USen‐
4907 glish, or UKenglish.)
4908 • As is standard with bibtex/biblatex, proper names should be protected
4910 with curly braces so that they won’t be lowercased in styles that
4911 call for sentence case. For example:
4912 title = {My Dinner with {Andre}}
4914 • In addition, words that should remain lowercase (or camelCase) should
4916 be protected:
4917 title = {Spin Wave Dispersion on the {nm} Scale}
4919 Though this is not necessary in bibtex/biblatex, it is necessary with
4921 citeproc, which stores titles internally in sentence case, and con‐
4922 verts to title case in styles that require it. Here we protect “nm”
4923 so that it doesn’t get converted to “Nm” at this stage.
4924 If you are using a CSL bibliography (either JSON or YAML), then observe
4926 the following rules:
4927 • All titles should be in sentence case.
4929 • Use the language field for non-English titles to prevent their con‐
4931 version to title case in styles that call for this. (Conversion hap‐
4932 pens only if language begins with en or is left empty.)
4933 • Protect words that should not be converted to title case using this
4935 syntax:
4936 Spin wave dispersion on the <span class="nocase">nm</span> scale
4938 Conference Papers, Published vs. Unpublished
4940 For a formally published conference paper, use the biblatex entry type
4941 inproceedings (which will be mapped to CSL paper-conference).
4942 For an unpublished manuscript, use the biblatex entry type unpublished
4944 without an eventtitle field (this entry type will be mapped to CSL man‐
4945 uscript).
4946 For a talk, an unpublished conference paper, or a poster presentation,
4948 use the biblatex entry type unpublished with an eventtitle field (this
4949 entry type will be mapped to CSL speech). Use the biblatex type field
4950 to indicate the type, e.g. “Paper”, or “Poster”. venue and eventdate
4951 may be useful too, though eventdate will not be rendered by most CSL
4952 styles. Note that venue is for the event’s venue, unlike location
4953 which describes the publisher’s location; do not use the latter for an
4954 unpublished conference paper.
4955 Specifying a citation style
4957 Citations and references can be formatted using any style supported by
4958 the Citation Style Language, listed in the Zotero Style Repository.
4959 These files are specified using the --csl option or the csl (or cita‐
4960 tion-style) metadata field. By default, pandoc will use the Chicago
4961 Manual of Style author-date format. (You can override this default by
4962 copying a CSL style of your choice to default.csl in your user data di‐
4963 rectory.) The CSL project provides further information on finding and
4964 editing styles.
4965 The --citation-abbreviations option (or the citation-abbreviations
4967 metadata field) may be used to specify a JSON file containing abbrevia‐
4968 tions of journals that should be used in formatted bibliographies when
4969 form="short" is specified. The format of the file can be illustrated
4970 with an example:
4971 { "default": {
4973 "container-title": {
4974 "Lloyd's Law Reports": "Lloyd's Rep",
4975 "Estates Gazette": "EG",
4976 "Scots Law Times": "SLT"
4977 }
4978 }
4979 }
4980 Citations in note styles
4982 Pandoc’s citation processing is designed to allow you to move between
4983 author-date, numerical, and note styles without modifying the markdown
4984 source. When you’re using a note style, avoid inserting footnotes man‐
4985 ually. Instead, insert citations just as you would in an author-date
4986 style—for example,
4987 Blah blah [@foo, p. 33].
4989 The footnote will be created automatically. Pandoc will take care of
4991 removing the space and moving the note before or after the period, de‐
4992 pending on the setting of notes-after-punctuation, as described below
4993 in Other relevant metadata fields.
4994 In some cases you may need to put a citation inside a regular footnote.
4996 Normal citations in footnotes (such as [@foo, p. 33]) will be rendered
4997 in parentheses. In-text citations (such as @foo [p. 33]) will be ren‐
4998 dered without parentheses. (A comma will be added if appropriate.)
4999 Thus:
5000 [^1]: Some studies [@foo; @bar, p. 33] show that
5002 frubulicious zoosnaps are quantical. For a survey
5003 of the literature, see @baz [chap. 1].
5004 Raw content in a style
5006 To include raw content in a prefix, suffix, delimiter, or term, sur‐
5007 round it with these tags indicating the format:
5008 {{jats}}<ref>{{/jats}}
5010 Without the tags, the string will be interpreted as a string and es‐
5012 caped in the output, rather than being passed through raw.
5013 This feature allows stylesheets to be customized to give different out‐
5015 put for different output formats. However, stylesheets customized in
5016 this way will not be usable by other CSL implementations.
5017 Placement of the bibliography
5019 If the style calls for a list of works cited, it will be placed in a
5020 div with id refs, if one exists:
5021 ::: {#refs}
5023 :::
5024 Otherwise, it will be placed at the end of the document. Generation of
5026 the bibliography can be suppressed by setting suppress-bibliography:
5027 true in the YAML metadata.
5028 If you wish the bibliography to have a section heading, you can set
5030 reference-section-title in the metadata, or put the heading at the be‐
5031 ginning of the div with id refs (if you are using it) or at the end of
5032 your document:
5033 last paragraph...
5035 # References
5037 The bibliography will be inserted after this heading. Note that the
5039 unnumbered class will be added to this heading, so that the section
5040 will not be numbered.
5041 Including uncited items in the bibliography
5043 If you want to include items in the bibliography without actually cit‐
5044 ing them in the body text, you can define a dummy nocite metadata field
5045 and put the citations there:
5046 ---
5048 nocite: |
5049 @item1, @item2
5050 ...
5051 @item3
5053 In this example, the document will contain a citation for item3 only,
5055 but the bibliography will contain entries for item1, item2, and item3.
5056 It is possible to create a bibliography with all the citations, whether
5058 or not they appear in the document, by using a wildcard:
5059 ---
5061 nocite: |
5062 @*
5063 ...
5064 For LaTeX output, you can also use natbib or biblatex to render the
5066 bibliography. In order to do so, specify bibliography files as out‐
5067 lined above, and add --natbib or --biblatex argument to pandoc invoca‐
5068 tion. Bear in mind that bibliography files have to be in either BibTeX
5069 (for --natbib) or BibLaTeX (for --biblatex) format.
5070 Other relevant metadata fields
5072 A few other metadata fields affect bibliography formatting:
5073 link-citations
5075 If true, citations will be hyperlinked to the corresponding bib‐
5076 liography entries (for author-date and numerical styles only).
5077 lang The lang field will affect how the style is localized, for exam‐
5079 ple in the translation of labels, the use of quotation marks,
5080 and the way items are sorted. (For backwards compatibility, lo‐
5081 cale may be used instead of lang, but this use is deprecated.)
5082 A BCP 47 language tag is expected: for example, en, de, en-US,
5084 fr-CA, ug-Cyrl. The unicode extension syntax (after -u-) may be
5085 used to specify options for collation (sorting) more precisely.
5086 Here are some examples:
5087 • zh-u-co-pinyin – Chinese with the Pinyin collation.
5089 • es-u-co-trad – Spanish with the traditional collation (with Ch
5091 sorting after C).
5092 • fr-u-kb – French with “backwards” accent sorting (with coté
5094 sorting after côte).
5095 • en-US-u-kf-upper – English with uppercase letters sorting be‐
5097 fore lower (default is lower before upper).
5098 notes-after-punctuation
5100 If true (the default), pandoc will put footnote citations after
5101 following punctuation. For example, if the source contains blah
5102 blah [@jones99]., the result will look like blah blah.[^1], with
5103 the note moved after the period and the space collapsed. If
5104 false, the space will still be collapsed, but the footnote will
5105 not be moved after the punctuation.
5106
5108 You can use pandoc to produce an HTML + JavaScript slide presentation
5109 that can be viewed via a web browser. There are five ways to do this,
5110 using S5, DZSlides, Slidy, Slideous, or reveal.js. You can also pro‐
5111 duce a PDF slide show using LaTeX beamer, or slides shows in Microsoft
5112 PowerPoint format.
5113 Here’s the Markdown source for a simple slide show, habits.txt:
5115 % Habits
5117 % John Doe
5118 % March 22, 2005
5119 # In the morning
5121 ## Getting up
5123 - Turn off alarm
5125 - Get out of bed
5126 ## Breakfast
5128 - Eat eggs
5130 - Drink coffee
5131 # In the evening
5133 ## Dinner
5135 - Eat spaghetti
5137 - Drink wine
5138 ------------------
5140 
5142 ## Going to sleep
5144 - Get in bed
5146 - Count sheep
5147 To produce an HTML/JavaScript slide show, simply type
5149 pandoc -t FORMAT -s habits.txt -o habits.html
5151 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
5153 For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc
5155 with the -s/--standalone option embeds a link to JavaScript and CSS
5156 files, which are assumed to be available at the relative path s5/de‐
5157 fault (for S5), slideous (for Slideous), reveal.js (for reveal.js), or
5158 at the Slidy website at w3.org (for Slidy). (These paths can be
5159 changed by setting the slidy-url, slideous-url, revealjs-url, or s5-url
5160 variables; see Variables for HTML slides, above.) For DZSlides, the
5161 (relatively short) JavaScript and CSS are included in the file by de‐
5162 fault.
5163 With all HTML slide formats, the --self-contained option can be used to
5165 produce a single file that contains all of the data necessary to dis‐
5166 play the slide show, including linked scripts, stylesheets, images, and
5167 videos.
5168 To produce a PDF slide show using beamer, type
5170 pandoc -t beamer habits.txt -o habits.pdf
5172 Note that a reveal.js slide show can also be converted to a PDF by
5174 printing it to a file from the browser.
5175 To produce a Powerpoint slide show, type
5177 pandoc habits.txt -o habits.pptx
5179 Structuring the slide show
5181 By default, the slide level is the highest heading level in the hierar‐
5182 chy that is followed immediately by content, and not another heading,
5183 somewhere in the document. In the example above, level-1 headings are
5184 always followed by level-2 headings, which are followed by content, so
5185 the slide level is 2. This default can be overridden using the
5186 --slide-level option.
5187 The document is carved up into slides according to the following rules:
5189 • A horizontal rule always starts a new slide.
5191 • A heading at the slide level always starts a new slide.
5193 • Headings below the slide level in the hierarchy create headings with‐
5195 in a slide. (In beamer, a “block” will be created. If the heading
5196 has the class example, an exampleblock environment will be used; if
5197 it has the class alert, an alertblock will be used; otherwise a regu‐
5198 lar block will be used.)
5199 • Headings above the slide level in the hierarchy create “title
5201 slides,” which just contain the section title and help to break the
5202 slide show into sections. Non-slide content under these headings
5203 will be included on the title slide (for HTML slide shows) or in a
5204 subsequent slide with the same title (for beamer).
5205 • A title page is constructed automatically from the document’s title
5207 block, if present. (In the case of beamer, this can be disabled by
5208 commenting out some lines in the default template.)
5209 These rules are designed to support many different styles of slide
5211 show. If you don’t care about structuring your slides into sections
5212 and subsections, you can just use level-1 headings for all each slide.
5213 (In that case, level-1 will be the slide level.) But you can also
5214 structure the slide show into sections, as in the example above.
5215 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
5217 layout will be produced, with level-1 headings building horizontally
5218 and level-2 headings building vertically. It is not recommended that
5219 you use deeper nesting of section levels with reveal.js.
5220 Incremental lists
5222 By default, these writers produce lists that display “all at once.” If
5223 you want your lists to display incrementally (one item at a time), use
5224 the -i option. If you want a particular list to depart from the de‐
5225 fault, put it in a div block with class incremental or nonincremental.
5226 So, for example, using the fenced div syntax, the following would be
5227 incremental regardless of the document default:
5228 ::: incremental
5230 - Eat spaghetti
5232 - Drink wine
5233 :::
5235 or
5237 ::: nonincremental
5239 - Eat spaghetti
5241 - Drink wine
5242 :::
5244 While using incremental and nonincremental divs are the recommended
5246 method of setting incremental lists on a per-case basis, an older meth‐
5247 od is also supported: putting lists inside a blockquote will depart
5248 from the document default (that is, it will display incrementally with‐
5249 out the -i option and all at once with the -i option):
5250 > - Eat spaghetti
5252 > - Drink wine
5253 Both methods allow incremental and nonincremental lists to be mixed in
5255 a single document.
5256 Note: Neither the -i/--incremental option nor any of the methods de‐
5258 scribed here currently works for PowerPoint output.
5259 Inserting pauses
5261 You can add “pauses” within a slide by including a paragraph containing
5262 three dots, separated by spaces:
5263 # Slide with a pause
5265 content before the pause
5267 . . .
5269 content after the pause
5271 Note: this feature is not yet implemented for PowerPoint output.
5273 Styling the slides
5275 You can change the style of HTML slides by putting customized CSS files
5276 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), or
5277 $DATADIR/slideous (for Slideous), where $DATADIR is the user data di‐
5278 rectory (see --data-dir, above). The originals may be found in pan‐
5279 doc’s system data directory (generally $CABALDIR/pandoc-VERSION/s5/de‐
5280 fault). Pandoc will look there for any files it does not find in the
5281 user data directory.
5282 For dzslides, the CSS is included in the HTML file itself, and may be
5284 modified there.
5285 All reveal.js configuration options can be set through variables. For
5287 example, themes can be used by setting the theme variable:
5288 -V theme=moon
5290 Or you can specify a custom stylesheet using the --css option.
5292 To style beamer slides, you can specify a theme, colortheme, fonttheme,
5294 innertheme, and outertheme, using the -V option:
5295 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
5297 Note that heading attributes will turn into slide attributes (on a
5299 <div> or <section>) in HTML slide formats, allowing you to style indi‐
5300 vidual slides. In beamer, the only heading attribute that affects
5301 slides is the allowframebreaks class, which sets the allowframebreaks
5302 option, causing multiple slides to be created if the content overfills
5303 the frame. This is recommended especially for bibliographies:
5304 # References {.allowframebreaks}
5306 Speaker notes
5308 Speaker notes are supported in reveal.js and PowerPoint (pptx) output.
5309 You can add notes to your Markdown document thus:
5310 ::: notes
5312 This is my note.
5314 - It can contain Markdown
5316 - like this list
5317 :::
5319 To show the notes window in reveal.js, press s while viewing the pre‐
5321 sentation. Speaker notes in PowerPoint will be available, as usual, in
5322 handouts and presenter view.
5323 Notes are not yet supported for other slide formats, but the notes will
5325 not appear on the slides themselves.
5326 Columns
5328 To put material in side by side columns, you can use a native div con‐
5329 tainer with class columns, containing two or more div containers with
5330 class column and a width attribute:
5331 :::::::::::::: {.columns}
5333 ::: {.column width="40%"}
5334 contents...
5335 :::
5336 ::: {.column width="60%"}
5337 contents...
5338 :::
5339 ::::::::::::::
5340 Additional columns attributes in beamer
5342 The div containers with classes columns and column can optionally have
5343 an align attribute. The class columns can optionally have a totalwidth
5344 attribute or an onlytextwidth class.
5345 :::::::::::::: {.columns align=center totalwidth=8em}
5347 ::: {.column width="40%"}
5348 contents...
5349 :::
5350 ::: {.column width="60%" align=bottom}
5351 contents...
5352 :::
5353 ::::::::::::::
5354 The align attributes on columns and column can be used with the values
5356 top, top-baseline, center and bottom to vertically align the columns.
5357 It defaults to top in columns.
5358 The totalwidth attribute limits the width of the columns to the given
5360 value.
5361 :::::::::::::: {.columns align=top .onlytextwidth}
5363 ::: {.column width="40%" align=center}
5364 contents...
5365 :::
5366 ::: {.column width="60%"}
5367 contents...
5368 :::
5369 ::::::::::::::
5370 The class onlytextwidth sets the totalwidth to \textwidth.
5372 See Section 12.7 of the Beamer User’s Guide for more details.
5374 Frame attributes in beamer
5376 Sometimes it is necessary to add the LaTeX [fragile] option to a frame
5377 in beamer (for example, when using the minted environment). This can
5378 be forced by adding the fragile class to the heading introducing the
5379 slide:
5380 # Fragile slide {.fragile}
5382 All of the other frame attributes described in Section 8.1 of the Beam‐
5384 er User’s Guide may also be used: allowdisplaybreaks, allowframebreaks,
5385 b, c, t, environment, label, plain, shrink, standout, noframenumbering.
5386 Background in reveal.js and beamer
5388 Background images can be added to self-contained reveal.js slideshows
5389 and to beamer slideshows.
5390 For the same image on every slide, use the configuration option back‐
5392 ground-image either in the YAML metadata block or as a command-line
5393 variable. (There are no other options in beamer and the rest of this
5394 section concerns reveal.js slideshows.)
5395 For reveal.js, you can instead use the reveal.js-native option paral‐
5397 laxBackgroundImage. You can also set parallaxBackgroundHorizontal and
5398 parallaxBackgroundVertical the same way and must also set parallaxBack‐
5399 groundSize to have your values take effect.
5400 To set an image for a particular reveal.js slide, add {data-background-
5402 image="/path/to/image"} to the first slide-level heading on the slide
5403 (which may even be empty).
5404 In reveal.js’s overview mode, the parallaxBackgroundImage will show up
5406 only on the first slide.
5407 Other reveal.js background settings also work on individual slides, in‐
5409 cluding data-background-size, data-background-repeat, data-background-
5410 color, data-transition, and data-transition-speed.
5411 To add a background image to the automatically generated title slide,
5413 use the title-slide-attributes variable in the YAML metadata block. It
5414 must contain a map of attribute names and values.
5415 See the reveal.js documentation for more details.
5417 For example in reveal.js:
5419 ---
5421 title: My Slideshow
5422 parallaxBackgroundImage: /path/to/my/background_image.png
5423 title-slide-attributes:
5424 data-background-image: /path/to/title_image.png
5425 data-background-size: contain
5426 ---
5427 ## Slide One
5429 Slide 1 has background_image.png as its background.
5431 ## {data-background-image="/path/to/special_image.jpg"}
5433 Slide 2 has a special image for its background, even though the heading has no content.
5435
5437 EPUB Metadata
5438 EPUB metadata may be specified using the --epub-metadata option, but if
5439 the source document is Markdown, it is better to use a YAML metadata
5440 block. Here is an example:
5441 ---
5443 title:
5444 - type: main
5445 text: My Book
5446 - type: subtitle
5447 text: An investigation of metadata
5448 creator:
5449 - role: author
5450 text: John Smith
5451 - role: editor
5452 text: Sarah Jones
5453 identifier:
5454 - scheme: DOI
5455 text: doi:10.234234.234/33
5456 publisher: My Press
5457 rights: © 2007 John Smith, CC BY-NC
5458 ibooks:
5459 version: 1.3.4
5460 ...
5461 The following fields are recognized:
5463 identifier
5465 Either a string value or an object with fields text and scheme.
5466 Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
5467 LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC,
5468 ISMN-13, ISBN-A, JP, OLCC.
5469 title Either a string value, or an object with fields file-as and
5471 type, or a list of such objects. Valid values for type are
5472 main, subtitle, short, collection, edition, extended.
5473 creator
5475 Either a string value, or an object with fields role, file-as,
5476 and text, or a list of such objects. Valid values for role are
5477 MARC relators, but pandoc will attempt to translate the human-
5478 readable versions (like “author” and “editor”) to the appropri‐
5479 ate marc relators.
5480 contributor
5482 Same format as creator.
5483 date A string value in YYYY-MM-DD format. (Only the year is neces‐
5485 sary.) Pandoc will attempt to convert other common date formats.
5486 lang (or legacy: language)
5488 A string value in BCP 47 format. Pandoc will default to the lo‐
5489 cal language if nothing is specified.
5490 subject
5492 A string value or a list of such values.
5493 description
5495 A string value.
5496 type A string value.
5498 format A string value.
5500 relation
5502 A string value.
5503 coverage
5505 A string value.
5506 rights A string value.
5508 belongs-to-collection
5510 A string value. identifies the name of a collection to which
5511 the EPUB Publication belongs.
5512 group-position
5514 The group-position field indicates the numeric position in which
5515 the EPUB Publication belongs relative to other works belonging
5516 to the same belongs-to-collection field.
5517 cover-image
5519 A string value (path to cover image).
5520 css (or legacy: stylesheet)
5522 A string value (path to CSS stylesheet).
5523 page-progression-direction
5525 Either ltr or rtl. Specifies the page-progression-direction at‐
5526 tribute for the spine element.
5527 ibooks iBooks-specific metadata, with the following fields:
5529 • version: (string)
5531 • specified-fonts: true|false (default false)
5533 • ipad-orientation-lock: portrait-only|landscape-only
5535 • iphone-orientation-lock: portrait-only|landscape-only
5537 • binding: true|false (default true)
5539 • scroll-axis: vertical|horizontal|default
5541 The epub:type attribute
5543 For epub3 output, you can mark up the heading that corresponds to an
5544 EPUB chapter using the epub:type attribute. For example, to set the
5545 attribute to the value prologue, use this markdown:
5546 # My chapter {epub:type=prologue}
5548 Which will result in:
5550 <body epub:type="frontmatter">
5552 <section epub:type="prologue">
5553 <h1>My chapter</h1>
5554 Pandoc will output <body epub:type="bodymatter">, unless you use one of
5556 the following values, in which case either frontmatter or backmatter
5557 will be output.
5558 epub:type of first section epub:type of body
5560 ───────────────────────────────────────────────
5561 prologue frontmatter
5562 abstract frontmatter
5563 acknowledgments frontmatter
5564 copyright-page frontmatter
5565 dedication frontmatter
5566 credits frontmatter
5567 keywords frontmatter
5568 imprint frontmatter
5569 contributors frontmatter
5570 other-credits frontmatter
5571 errata frontmatter
5572 revision-history frontmatter
5573 titlepage frontmatter
5574 halftitlepage frontmatter
5575 seriespage frontmatter
5576 foreword frontmatter
5577 preface frontmatter
5578 appendix backmatter
5579 colophon backmatter
5580 bibliography backmatter
5581 index backmatter
5582 Linked media
5584 By default, pandoc will download media referenced from any <img>, <au‐
5585 dio>, <video> or <source> element present in the generated EPUB, and
5586 include it in the EPUB container, yielding a completely self-contained
5587 EPUB. If you want to link to external media resources instead, use raw
5588 HTML in your source and add data-external="1" to the tag with the src
5589 attribute. For example:
5590 <audio controls="1">
5592 <source src="https://example.com/music/toccata.mp3"
5593 data-external="1" type="audio/mpeg">
5594 </source>
5595 </audio>
5596
5598 When creating a Jupyter notebook, pandoc will try to infer the notebook
5599 structure. Code blocks with the class code will be taken as code
5600 cells, and intervening content will be taken as Markdown cells. At‐
5601 tachments will automatically be created for images in Markdown cells.
5602 Metadata will be taken from the jupyter metadata field. For example:
5603 ---
5605 title: My notebook
5606 jupyter:
5607 nbformat: 4
5608 nbformat_minor: 5
5609 kernelspec:
5610 display_name: Python 2
5611 language: python
5612 name: python2
5613 language_info:
5614 codemirror_mode:
5615 name: ipython
5616 version: 2
5617 file_extension: ".py"
5618 mimetype: "text/x-python"
5619 name: "python"
5620 nbconvert_exporter: "python"
5621 pygments_lexer: "ipython2"
5622 version: "2.7.15"
5623 ---
5624 # Lorem ipsum
5626 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5628 bibendum felis dictum sodales.
5629 ``` code
5631 print("hello")
5632 ```
5633 ## Pyout
5635 ``` code
5637 from IPython.display import HTML
5638 HTML("""
5639 <script>
5640 console.log("hello");
5641 </script>
5642 <b>HTML</b>
5643 """)
5644 ```
5645 ## Image
5647 This image  will be
5649 included as a cell attachment.
5650 If you want to add cell attributes, group cells differently, or add
5652 output to code cells, then you need to include divs to indicate the
5653 structure. You can use either fenced divs or native divs for this.
5654 Here is an example:
5655 :::::: {.cell .markdown}
5657 # Lorem
5658 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5660 bibendum felis dictum sodales.
5661 ::::::
5662 :::::: {.cell .code execution_count=1}
5664 ``` {.python}
5665 print("hello")
5666 ```
5667 ::: {.output .stream .stdout}
5669 ```
5670 hello
5671 ```
5672 :::
5673 ::::::
5674 :::::: {.cell .code execution_count=2}
5676 ``` {.python}
5677 from IPython.display import HTML
5678 HTML("""
5679 <script>
5680 console.log("hello");
5681 </script>
5682 <b>HTML</b>
5683 """)
5684 ```
5685 ::: {.output .execute_result execution_count=2}
5687 ```{=html}
5688 <script>
5689 console.log("hello");
5690 </script>
5691 <b>HTML</b>
5692 hello
5693 ```
5694 :::
5695 ::::::
5696 If you include raw HTML or TeX in an output cell, use the [raw attri‐
5698 bute][Extension: fenced_attribute], as shown in the last cell of the
5699 example above. Although pandoc can process “bare” raw HTML and TeX,
5700 the result is often interspersed raw elements and normal textual ele‐
5701 ments, and in an output cell pandoc expects a single, connected raw
5702 block. To avoid using raw HTML or TeX except when marked explicitly
5703 using raw attributes, we recommend specifying the extensions -raw_html-
5704 raw_tex+raw_attribute when translating between Markdown and ipynb note‐
5705 books.
5706 Note that options and extensions that affect reading and writing of
5708 Markdown will also affect Markdown cells in ipynb notebooks. For exam‐
5709 ple, --wrap=preserve will preserve soft line breaks in Markdown cells;
5710 --atx-headers will cause ATX-style headings to be used; and --preserve-
5711 tabs will prevent tabs from being turned to spaces.
5712
5714 Pandoc will automatically highlight syntax in fenced code blocks that
5715 are marked with a language name. The Haskell library skylighting is
5716 used for highlighting. Currently highlighting is supported only for
5717 HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language
5718 names that pandoc will recognize, type pandoc --list-highlight-lan‐
5719 guages.
5720 The color scheme can be selected using the --highlight-style option.
5722 The default color scheme is pygments, which imitates the default color
5723 scheme used by the Python library pygments (though pygments is not ac‐
5724 tually used to do the highlighting). To see a list of highlight
5725 styles, type pandoc --list-highlight-styles.
5726 If you are not satisfied with the predefined styles, you can use
5728 --print-highlight-style to generate a JSON .theme file which can be
5729 modified and used as the argument to --highlight-style. To get a JSON
5730 version of the pygments style, for example:
5731 pandoc --print-highlight-style pygments > my.theme
5733 Then edit my.theme and use it like this:
5735 pandoc --highlight-style my.theme
5737 If you are not satisfied with the built-in highlighting, or you want
5739 highlight a language that isn’t supported, you can use the --syntax-
5740 definition option to load a KDE-style XML syntax definition file. Be‐
5741 fore writing your own, have a look at KDE’s repository of syntax defi‐
5742 nitions.
5743 To disable highlighting, use the --no-highlight option.
5745
5747 Custom styles can be used in the docx and ICML formats.
5748 Output
5750 By default, pandoc’s docx and ICML output applies a predefined set of
5751 styles for blocks such as paragraphs and block quotes, and uses largely
5752 default formatting (italics, bold) for inlines. This will work for
5753 most purposes, especially alongside a reference.docx file. However, if
5754 you need to apply your own styles to blocks, or match a preexisting set
5755 of styles, pandoc allows you to define custom styles for blocks and
5756 text using divs and spans, respectively.
5757 If you define a div or span with the attribute custom-style, pandoc
5759 will apply your specified style to the contained elements (with the ex‐
5760 ception of elements whose function depends on a style, like headings,
5761 code blocks, block quotes, or links). So, for example, using the
5762 bracketed_spans syntax,
5763 [Get out]{custom-style="Emphatically"}, he said.
5765 would produce a docx file with “Get out” styled with character style
5767 Emphatically. Similarly, using the fenced_divs syntax,
5768 Dickinson starts the poem simply:
5770 ::: {custom-style="Poetry"}
5772 | A Bird came down the Walk---
5773 | He did not know I saw---
5774 :::
5775 would style the two contained lines with the Poetry paragraph style.
5777 For docx output, styles will be defined in the output file as inherit‐
5779 ing from normal text, if the styles are not yet in your reference.docx.
5780 If they are already defined, pandoc will not alter the definition.
5781 This feature allows for greatest customization in conjunction with pan‐
5783 doc filters. If you want all paragraphs after block quotes to be in‐
5784 dented, you can write a filter to apply the styles necessary. If you
5785 want all italics to be transformed to the Emphasis character style
5786 (perhaps to change their color), you can write a filter which will
5787 transform all italicized inlines to inlines within an Emphasis custom-
5788 style span.
5789 For docx output, you don’t need to enable any extensions for custom
5791 styles to work.
5792 Input
5794 The docx reader, by default, only reads those styles that it can con‐
5795 vert into pandoc elements, either by direct conversion or interpreting
5796 the derivation of the input document’s styles.
5797 By enabling the styles extension in the docx reader (-f docx+styles),
5799 you can produce output that maintains the styles of the input document,
5800 using the custom-style class. Paragraph styles are interpreted as di‐
5801 vs, while character styles are interpreted as spans.
5802 For example, using the custom-style-reference.docx file in the test di‐
5804 rectory, we have the following different outputs:
5805 Without the +styles extension:
5807 $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
5809 This is some text.
5810 This is text with an *emphasized* text style. And this is text with a
5812 **strengthened** text style.
5813 > Here is a styled paragraph that inherits from Block Text.
5815 And with the extension:
5817 $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
5819 ::: {custom-style="First Paragraph"}
5821 This is some text.
5822 :::
5823 ::: {custom-style="Body Text"}
5825 This is text with an [emphasized]{custom-style="Emphatic"} text style.
5826 And this is text with a [strengthened]{custom-style="Strengthened"}
5827 text style.
5828 :::
5829 ::: {custom-style="My Block Style"}
5831 > Here is a styled paragraph that inherits from Block Text.
5832 :::
5833 With these custom styles, you can use your input document as a refer‐
5835 ence-doc while creating docx output (see below), and maintain the same
5836 styles in your input and output files.
5837
5839 Pandoc can be extended with custom writers written in Lua. (Pandoc in‐
5840 cludes a Lua interpreter, so Lua need not be installed separately.)
5841 To use a custom writer, simply specify the path to the Lua script in
5843 place of the output format. For example:
5844 pandoc -t data/sample.lua
5846 Creating a custom writer requires writing a Lua function for each pos‐
5848 sible element in a pandoc document. To get a documented example which
5849 you can modify according to your needs, do
5850 pandoc --print-default-data-file sample.lua
5852 Note that custom writers have no default template. If you want to use
5854 --standalone with a custom writer, you will need to specify a template
5855 manually using --template or add a new default template with the name
5856 default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your
5857 user data directory (see Templates).
5858
5860 Some of the document formats pandoc targets (such as EPUB, docx, and
5861 ODT) include build timestamps in the generated document. That means
5862 that the files generated on successive builds will differ, even if the
5863 source does not. To avoid this, set the SOURCE_DATE_EPOCH environment
5864 variable, and the timestamp will be taken from it instead of the cur‐
5865 rent time. SOURCE_DATE_EPOCH should contain an integer unix timestamp
5866 (specifying the number of second since midnight UTC January 1, 1970).
5867 Some document formats also include a unique identifier. For EPUB, this
5869 can be set explicitly by setting the identifier metadata field (see
5870 EPUB Metadata, above).
5871
5873 If you use pandoc to convert user-contributed content in a web applica‐
5874 tion, here are some things to keep in mind:
5875 1. Although pandoc itself will not create or modify any files other
5877 than those you explicitly ask it create (with the exception of tem‐
5878 porary files used in producing PDFs), a filter or custom writer
5879 could in principle do anything on your file system. Please audit
5880 filters and custom writers very carefully before using them.
5881 2. If your application uses pandoc as a Haskell library (rather than
5883 shelling out to the executable), it is possible to use it in a mode
5884 that fully isolates pandoc from your file system, by running the
5885 pandoc operations in the PandocPure monad. See the document Using
5886 the pandoc API for more details.
5887 3. Pandoc’s parsers can exhibit pathological performance on some corner
5889 cases. It is wise to put any pandoc operations under a timeout, to
5890 avoid DOS attacks that exploit these issues. If you are using the
5891 pandoc executable, you can add the command line options +RTS -M512M
5892 -RTS (for example) to limit the heap size to 512MB.
5893 4. The HTML generated by pandoc is not guaranteed to be safe. If
5895 raw_html is enabled for the Markdown input, users can inject arbi‐
5896 trary HTML. Even if raw_html is disabled, users can include danger‐
5897 ous content in URLs and attributes. To be safe, you should run all
5898 the generated HTML through an HTML sanitizer.
5899
5901 Copyright 2006–2021 John MacFarlane (jgm@berkeley.edu). Released under
5902 the GPL, version 2 or greater. This software carries no warranty of
5903 any kind. (See COPYRIGHT for full copyright and warranty notices.) For
5904 a full list of contributors, see the file AUTHORS.md in the pandoc
5905 source code.
5906 The Pandoc source code and all documentation may be downloaded from
5908 <https://pandoc.org>.
5909pandoc 2.14.0.3 June 20, 2021 Pandoc User’s Guide()