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