1PANDOC(1)                   General Commands Manual                  PANDOC(1)
2
3
4

NAME

6       pandoc - general markup converter
7

SYNOPSIS

9       pandoc [options] [input-file]...
10

DESCRIPTION

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 convert between numerous markup and word processing formats,
16       including, but not limited to, various flavors of Markdown, HTML, LaTeX
17       and Word docx.  For the full lists of input and output formats, see the
18       --from and --to options below.  Pandoc can also produce PDF output: see
19       creating a PDF, below.
20
21       Pandoc's enhanced version of Markdown includes syntax for tables, defi‐
22       nition  lists,  metadata  blocks,  footnotes, citations, math, and much
23       more.  See below under Pandoc's Markdown.
24
25       Pandoc has a modular design: it consists of a  set  of  readers,  which
26       parse text in a given format and produce a native representation of the
27       document (an abstract syntax tree or AST), and a set of writers,  which
28       convert  this native representation into a target format.  Thus, adding
29       an input or output format requires only  adding  a  reader  or  writer.
30       Users  can  also  run  custom pandoc filters to modify the intermediate
31       AST.
32
33       Because pandoc's intermediate representation  of  a  document  is  less
34       expressive than many of the formats it converts between, one should not
35       expect perfect conversions between every format and every other.   Pan‐
36       doc attempts to preserve the structural elements of a document, but not
37       formatting details such as margin size.  And  some  document  elements,
38       such  as  complex  tables,  may  not  fit into pandoc's simple document
39       model.  While conversions from pandoc's Markdown to all formats  aspire
40       to  be  perfect, conversions from formats more expressive than pandoc's
41       Markdown can be expected to be lossy.
42
43   Using pandoc
44       If no input-files are specified, input is read from stdin.  Output goes
45       to stdout by default.  For output to a file, use the -o option:
46
47              pandoc -o output.html input.txt
48
49       By  default,  pandoc produces a document fragment.  To produce a stand‐
50       alone document (e.g.  a valid HTML file including <head>  and  <body>),
51       use the -s or --standalone flag:
52
53              pandoc -s -o output.html input.txt
54
55       For more information on how standalone documents are produced, see Tem‐
56       plates below.
57
58       If multiple input files are given, pandoc  will  concatenate  them  all
59       (with  blank  lines between them) before parsing.  (Use --file-scope to
60       parse files individually.)
61
62   Specifying formats
63       The format of the input and output can be  specified  explicitly  using
64       command-line  options.   The  input  format  can be specified using the
65       -f/--from option, the output format using the -t/--to option.  Thus, to
66       convert hello.txt from Markdown to LaTeX, you could type:
67
68              pandoc -f markdown -t latex hello.txt
69
70       To convert hello.html from HTML to Markdown:
71
72              pandoc -f html -t markdown hello.html
73
74       Supported  input and output formats are listed below under Options (see
75       -f for input formats and -t for output formats).  You can also use pan‐
76       doc  --list-input-formats  and  pandoc  --list-output-formats  to print
77       lists of supported formats.
78
79       If the input or output format is not specified explicitly, pandoc  will
80       attempt  to  guess  it from the extensions of the filenames.  Thus, for
81       example,
82
83              pandoc -o hello.tex hello.txt
84
85       will convert hello.txt from Markdown to LaTeX.  If no  output  file  is
86       specified  (so  that  output  goes  to stdout), or if the output file's
87       extension is unknown, the output format will default to  HTML.   If  no
88       input  file  is  specified  (so that input comes from stdin), or if the
89       input files' extensions are unknown, the input format will  be  assumed
90       to be Markdown.
91
92   Character encoding
93       Pandoc uses the UTF-8 character encoding for both input and output.  If
94       your local character encoding is not UTF-8, you should pipe  input  and
95       output through iconv:
96
97              iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
98
99       Note  that  in  some output formats (such as HTML, LaTeX, ConTeXt, RTF,
100       OPML, DocBook, and Texinfo), information about the  character  encoding
101       is  included in the document header, which will only be included if you
102       use the -s/--standalone option.
103
104   Creating a PDF
105       To produce a PDF, specify an output file with a .pdf extension:
106
107              pandoc test.txt -o test.pdf
108
109       By default, pandoc will use LaTeX to create  the  PDF,  which  requires
110       that a LaTeX engine be installed (see --pdf-engine below).
111
112       Alternatively, pandoc can use ConTeXt, pdfroff, or any of the following
113       HTML/CSS-to-PDF-engines, to create a PDF:  wkhtmltopdf,  weasyprint  or
114       prince.   To  do this, specify an output file with a .pdf extension, as
115       before, but add the --pdf-engine option or -t context, -t html,  or  -t
116       ms to the command line (-t html defaults to --pdf-engine=wkhtmltopdf).
117
118       PDF  output  can  be  controlled using variables for LaTeX (if LaTeX is
119       used) and variables for ConTeXt (if ConTeXt is used).   When  using  an
120       HTML/CSS-to-PDF-engine,  --css  affects  the output.  If wkhtmltopdf is
121       used, then the variables margin-left,  margin-right,  margin-top,  mar‐
122       gin-bottom, footer-html, header-html and papersize will affect the out‐
123       put.
124
125       To debug the PDF creation, it can be useful to look at the intermediate
126       representation:  instead of -o test.pdf, use for example -s -o test.tex
127       to output the generated LaTeX.  You can  then  test  it  with  pdflatex
128       test.tex.
129
130       When using LaTeX, the following packages need to be available (they are
131       included with all recent versions of TeX Live): amsfonts, amsmath,  lm,
132       unicode-math,  ifxetex, ifluatex, listings (if the --listings option is
133       used), fancyvrb, longtable, booktabs, graphicx and grffile (if the doc‐
134       ument contains images), hyperref, xcolor (with colorlinks), ulem, geom‐
135       etry (with the geometry variable set), setspace (with linestretch), and
136       babel  (with lang).  The use of xelatex or lualatex as the LaTeX engine
137       requires fontspec.  xelatex uses polyglossia (with  lang),  xecjk,  and
138       bidi  (with  the  dir  variable set).  If the mathspec variable is set,
139       xelatex will use mathspec instead of  unicode-math.   The  upquote  and
140       microtype packages are used if available, and csquotes will be used for
141       typography if \usepackage{csquotes}  is  present  in  the  template  or
142       included via /H/--include-in-header.  The natbib, biblatex, bibtex, and
143       biber packages can optionally be used for citation rendering.
144
145   Reading from the Web
146       Instead of an input file, an absolute URI may be given.  In  this  case
147       pandoc will fetch the content using HTTP:
148
149              pandoc -f html -t markdown http://www.fsf.org
150
151       It  is  possible  to  supply a custom User-Agent string or other header
152       when requesting a document from a URL:
153
154              pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
155                http://www.fsf.org
156

OPTIONS

158   General options
159       -f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
160              Specify input format.  FORMAT can be:
161
162              · commonmark (CommonMark Markdown)
163
164              · creole (Creole 1.0)
165
166              · docbook (DocBook)
167
168              · docx (Word docx)
169
170              · epub (EPUB)
171
172              · fb2 (FictionBook2 e-book)
173
174              · gfm (GitHub-Flavored Markdown), or  the  deprecated  and  less
175                accurate markdown_github; use markdown_github only if you need
176                extensions not supported in gfm.
177
178              · haddock (Haddock markup)
179
180              · html (HTML)
181
182              · jats (JATS XML)
183
184              · json (JSON version of native AST)
185
186              · latex (LaTeX)
187
188              · markdown (Pandoc's Markdown)
189
190              · markdown_mmd (MultiMarkdown)
191
192              · markdown_phpextra (PHP Markdown Extra)
193
194              · markdown_strict (original unextended Markdown)
195
196              · mediawiki (MediaWiki markup)
197
198              · man (roff man)
199
200              · muse (Muse)
201
202              · native (native Haskell)
203
204              · odt (ODT)
205
206              · opml (OPML)
207
208              · org (Emacs Org mode)
209
210              · rst (reStructuredText)
211
212              · t2t (txt2tags)
213
214              · textile (Textile)
215
216              · tikiwiki (TikiWiki markup)
217
218              · twiki (TWiki markup)
219
220              · vimwiki (Vimwiki)
221
222              Extensions can be individually enabled or disabled by  appending
223              +EXTENSION  or  -EXTENSION  to  the format name.  See Extensions
224              below,  for  a  list  of  extensions  and  their   names.    See
225              --list-input-formats and --list-extensions, below.
226
227       -t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
228              Specify output format.  FORMAT can be:
229
230              · asciidoc (AsciiDoc)
231
232              · beamer (LaTeX beamer slide show)
233
234              · commonmark (CommonMark Markdown)
235
236              · context (ConTeXt)
237
238              · docbook or docbook4 (DocBook 4)
239
240              · docbook5 (DocBook 5)
241
242              · docx (Word docx)
243
244              · dokuwiki (DokuWiki markup)
245
246              · epub or epub3 (EPUB v3 book)
247
248              · epub2 (EPUB v2)
249
250              · fb2 (FictionBook2 e-book)
251
252              · gfm  (GitHub-Flavored  Markdown),  or  the deprecated and less
253                accurate markdown_github; use markdown_github only if you need
254                extensions not supported in gfm.
255
256              · haddock (Haddock markup)
257
258              · html or html5 (HTML, i.e.  HTML5/XHTML polyglot markup)
259
260              · html4 (XHTML 1.0 Transitional)
261
262              · icml (InDesign ICML)
263
264              · jats (JATS XML)
265
266              · json (JSON version of native AST)
267
268              · latex (LaTeX)
269
270              · man (roff man)
271
272              · markdown (Pandoc's Markdown)
273
274              · markdown_mmd (MultiMarkdown)
275
276              · markdown_phpextra (PHP Markdown Extra)
277
278              · markdown_strict (original unextended Markdown)
279
280              · mediawiki (MediaWiki markup)
281
282              · ms (roff ms)
283
284              · muse (Muse),
285
286              · native (native Haskell),
287
288              · odt (OpenOffice text document)
289
290              · opml (OPML)
291
292              · opendocument (OpenDocument)
293
294              · org (Emacs Org mode)
295
296              · plain (plain text),
297
298              · pptx (PowerPoint slide show)
299
300              · rst (reStructuredText)
301
302              · rtf (Rich Text Format)
303
304              · texinfo (GNU Texinfo)
305
306              · textile (Textile)
307
308              · slideous (Slideous HTML and JavaScript slide show)
309
310              · slidy (Slidy HTML and JavaScript slide show)
311
312              · dzslides (DZSlides HTML5 + JavaScript slide show),
313
314              · revealjs (reveal.js HTML5 + JavaScript slide show)
315
316              · s5 (S5 HTML and JavaScript slide show)
317
318              · tei (TEI Simple)
319
320              · zimwiki (ZimWiki markup)
321
322              · the path of a custom lua writer, see Custom writers below
323
324              Note  that  odt,  docx,  and epub output will not be directed to
325              stdout unless forced with -o -.
326
327              Extensions can be individually enabled or disabled by  appending
328              +EXTENSION  or  -EXTENSION  to  the format name.  See Extensions
329              below,  for  a  list  of  extensions  and  their   names.    See
330              --list-output-formats and --list-extensions, below.
331
332       -o FILE, --output=FILE
333              Write  output  to  FILE instead of stdout.  If FILE is -, output
334              will go to stdout, even if  a  non-textual  format  (docx,  odt,
335              epub2, epub3) is specified.
336
337       --data-dir=DIRECTORY
338              Specify the user data directory to search for pandoc data files.
339              If this option is not specified, the default user data directory
340              will be used.  This is, in UNIX:
341
342                     $HOME/.pandoc
343
344              in Windows XP:
345
346                     C:\Documents And Settings\USERNAME\Application Data\pandoc
347
348              and in Windows Vista or later:
349
350                     C:\Users\USERNAME\AppData\Roaming\pandoc
351
352              You  can  find the default user data directory on your system by
353              looking at the output of  pandoc  --version.   A  reference.odt,
354              reference.docx,  epub.css,  templates,  slidy,  slideous,  or s5
355              directory placed in this directory will override pandoc's normal
356              defaults.
357
358       --bash-completion
359              Generate  a  bash  completion script.  To enable bash completion
360              with pandoc, add this to your .bashrc:
361
362                     eval "$(pandoc --bash-completion)"
363
364       --verbose
365              Give verbose debugging  output.   Currently  this  only  has  an
366              effect with PDF output.
367
368       --quiet
369              Suppress warning messages.
370
371       --fail-if-warnings
372              Exit with error status if there are any warnings.
373
374       --log=FILE
375              Write log messages in machine-readable JSON format to FILE.  All
376              messages above DEBUG level will be written, regardless  of  ver‐
377              bosity settings (--verbose, --quiet).
378
379       --list-input-formats
380              List supported input formats, one per line.
381
382       --list-output-formats
383              List supported output formats, one per line.
384
385       --list-extensions[=FORMAT]
386              List  supported  extensions,  one per line, preceded by a + or -
387              indicating whether it is enabled by default in FORMAT.  If  FOR‐
388              MAT is not specified, defaults for pandoc's Markdown are given.
389
390       --list-highlight-languages
391              List supported languages for syntax highlighting, one per line.
392
393       --list-highlight-styles
394              List  supported  styles  for  syntax highlighting, one per line.
395              See --highlight-style.
396
397       -v, --version
398              Print version.
399
400       -h, --help
401              Show usage message.
402
403   Reader options
404       --base-header-level=NUMBER
405              Specify the base level for headers (defaults to 1).
406
407       --strip-empty-paragraphs
408              Deprecated. Use the +empty_paragraphs extension instead.  Ignore
409              paragraphs  with no content.  This option is useful for convert‐
410              ing word processing documents where users have used empty  para‐
411              graphs to create inter-paragraph space.
412
413       --indented-code-classes=CLASSES
414              Specify  classes  to  use for indented code blocks--for example,
415              perl,numberLines or haskell.  Multiple classes may be  separated
416              by spaces or commas.
417
418       --default-image-extension=EXTENSION
419              Specify a default extension to use when image paths/URLs have no
420              extension.  This allows you to use the same source  for  formats
421              that  require  different kinds of images.  Currently this option
422              only affects the Markdown and LaTeX readers.
423
424       --file-scope
425              Parse each file individually before combining for multifile doc‐
426              uments.   This  will allow footnotes in different files with the
427              same identifiers to work as expected.  If this  option  is  set,
428              footnotes  and links will not work across files.  Reading binary
429              files (docx, odt, epub) implies --file-scope.
430
431       -F PROGRAM, --filter=PROGRAM
432              Specify an executable to be used as a  filter  transforming  the
433              pandoc  AST  after  the input is parsed and before the output is
434              written.  The executable should read JSON from stdin  and  write
435              JSON  to  stdout.   The JSON must be formatted like pandoc's own
436              JSON input and output.  The name of the output  format  will  be
437              passed to the filter as the first argument.  Hence,
438
439                     pandoc --filter ./caps.py -t latex
440
441              is equivalent to
442
443                     pandoc -t json | ./caps.py latex | pandoc -f json -t latex
444
445              The latter form may be useful for debugging filters.
446
447              Filters  may  be  written  in  any  language.   Text.Pandoc.JSON
448              exports toJSONFilter to facilitate writing filters  in  Haskell.
449              Those  who  would  prefer to write filters in python can use the
450              module pandocfilters, installable from  PyPI.   There  are  also
451              pandoc filter libraries in PHP, perl, and JavaScript/node.js.
452
453              In order of preference, pandoc will look for filters in
454
455              1. a  specified  full  or  relative path (executable or non-exe‐
456                 cutable)
457
458              2. $DATADIR/filters   (executable   or   non-executable)   where
459                 $DATADIR is the user data directory (see --data-dir, above).
460
461              3. $PATH (executable only)
462
463              Filters  and  lua-filters  are applied in the order specified on
464              the command line.
465
466       --lua-filter=SCRIPT
467              Transform the document in a similar fashion as JSON filters (see
468              --filter),  but use pandoc's build-in lua filtering system.  The
469              given lua script is expected to return a  list  of  lua  filters
470              which  will  be  applied in order.  Each lua filter must contain
471              element-transforming functions indexed by the name  of  the  AST
472              element on which the filter function should be applied.
473
474              The pandoc lua module provides helper functions for element cre‐
475              ation.  It is always loaded into the script's lua environment.
476
477              The following is an example lua script for macro-expansion:
478
479                     function expand_hello_world(inline)
480                       if inline.c == '{{helloworld}}' then
481                         return pandoc.Emph{ pandoc.Str "Hello, World" }
482                       else
483                         return inline
484                       end
485                     end
486
487                     return {{Str = expand_hello_world}}
488
489              In order of preference, pandoc will look for lua filters in
490
491              1. a specified full or relative  path  (executable  or  non-exe‐
492                 cutable)
493
494              2. $DATADIR/filters   (executable   or   non-executable)   where
495                 $DATADIR is the user data directory (see --data-dir, above).
496
497       -M KEY[=VAL], --metadata=KEY[:VAL]
498              Set the metadata field KEY to the value VAL.  A value  specified
499              on  the command line overrides a value specified in the document
500              using YAML metadata blocks.  Values will be parsed as YAML bool‐
501              ean  or string values.  If no value is specified, the value will
502              be treated as Boolean true.  Like --variable, --metadata  causes
503              template variables to be set.  But unlike --variable, --metadata
504              affects the metadata of the underlying document (which is acces‐
505              sible  from  filters  and may be printed in some output formats)
506              and metadata values will be escaped when inserted into the  tem‐
507              plate.
508
509       --metadata-file=FILE
510              Read  metadata  from  the  supplied  YAML  (or JSON) file.  This
511              option can be used with every input format, but  string  scalars
512              in  the YAML file will always be parsed as Markdown.  Generally,
513              the input will be handled the same as in YAML  metadata  blocks.
514              Metadata  values  specified inside the document, or by using -M,
515              overwrite values specified with this option.
516
517       -p, --preserve-tabs
518              Preserve  tabs  instead  of  converting  them  to  spaces   (the
519              default).   Note that this will only affect tabs in literal code
520              spans and code blocks; tabs in regular text will be  treated  as
521              spaces.
522
523       --tab-stop=NUMBER
524              Specify the number of spaces per tab (default is 4).
525
526       --track-changes=accept|reject|all
527              Specifies  what  to  do with insertions, deletions, and comments
528              produced by the MS Word "Track Changes"  feature.   accept  (the
529              default),  inserts  all  insertions,  and ignores all deletions.
530              reject inserts  all  deletions  and  ignores  insertions.   Both
531              accept  and  reject  ignore  comments.   all puts in insertions,
532              deletions, and comments, wrapped in spans with insertion,  dele‐
533              tion, comment-start, and comment-end classes, respectively.  The
534              author and time of  change  is  included.   all  is  useful  for
535              scripting:  only accepting changes from a certain reviewer, say,
536              or before a  certain  date.   If  a  paragraph  is  inserted  or
537              deleted,  track-changes=all produces a span with the class para‐
538              graph-insertion/paragraph-deletion before the affected paragraph
539              break.  This option only affects the docx reader.
540
541       --extract-media=DIR
542              Extract  images  and other media contained in or linked from the
543              source document to the path DIR, creating it if  necessary,  and
544              adjust  the  images  references in the document so they point to
545              the extracted files.  If the source format is a binary container
546              (docx,  epub, or odt), the media is extracted from the container
547              and the original filenames are used.   Otherwise  the  media  is
548              read  from  the file system or downloaded, and new filenames are
549              constructed based on SHA1 hashes of the contents.
550
551       --abbreviations=FILE
552              Specifies a custom abbreviations file, with abbreviations one to
553              a  line.   If this option is not specified, pandoc will read the
554              data file abbreviations from the user  data  directory  or  fall
555              back on a system default.  To see the system default, use pandoc
556              --print-default-data-file=abbreviations.  The  only  use  pandoc
557              makes of this list is in the Markdown reader.  Strings ending in
558              a period that are found in this list will be followed by a  non‐
559              breaking  space,  so  that  the  period  will  not  produce sen‐
560              tence-ending space in formats like LaTeX.
561
562   General writer options
563       -s, --standalone
564              Produce output with an appropriate header and  footer  (e.g.   a
565              standalone HTML, LaTeX, TEI, or RTF file, not a fragment).  This
566              option is set automatically for pdf, epub, epub3, fb2, docx, and
567              odt  output.   For native output, this option causes metadata to
568              be included; otherwise, metadata is suppressed.
569
570       --template=FILE|URL
571              Use the specified file as a custom template  for  the  generated
572              document.   Implies  --standalone.   See Templates, below, for a
573              description of template syntax.  If no extension  is  specified,
574              an  extension corresponding to the writer will be added, so that
575              --template=special looks for special.html for HTML  output.   If
576              the template is not found, pandoc will search for it in the tem‐
577              plates subdirectory of the user data directory (see --data-dir).
578              If  this  option is not used, a default template appropriate for
579              the output format  will  be  used  (see  -D/--print-default-tem‐
580              plate).
581
582       -V KEY[=VAL], --variable=KEY[:VAL]
583              Set  the  template  variable KEY to the value VAL when rendering
584              the document in standalone mode.  This is generally only  useful
585              when the --template option is used to specify a custom template,
586              since pandoc  automatically  sets  the  variables  used  in  the
587              default  templates.   If  no  VAL  is specified, the key will be
588              given the value true.
589
590       -D FORMAT, --print-default-template=FORMAT
591              Print the system default template for an output FORMAT.  (See -t
592              for  a  list  of  possible  FORMATs.) Templates in the user data
593              directory are ignored.
594
595       --print-default-data-file=FILE
596              Print a system default data file.  Files in the user data direc‐
597              tory are ignored.
598
599       --eol=crlf|lf|native
600              Manually   specify   line  endings:  crlf  (Windows),  lf  (mac‐
601              OS/Linux/UNIX), or native (line endings appropriate to the OS on
602              which pandoc is being run).  The default is native.
603
604       --dpi=NUMBER
605              Specify the dpi (dots per inch) value for conversion from pixels
606              to inch/centimeters and  vice  versa.   The  default  is  96dpi.
607              Technically, the correct term would be ppi (pixels per inch).
608
609       --wrap=auto|none|preserve
610              Determine  how  text  is wrapped in the output (the source code,
611              not the rendered version).  With auto (the default), pandoc will
612              attempt to wrap lines to the column width specified by --columns
613              (default 72).  With none, pandoc will not  wrap  lines  at  all.
614              With preserve, pandoc will attempt to preserve the wrapping from
615              the source document (that is, where there are  nonsemantic  new‐
616              lines  in  the source, there will be nonsemantic newlines in the
617              output as well).  Automatic wrapping does not currently work  in
618              HTML output.
619
620       --columns=NUMBER
621              Specify  length of lines in characters.  This affects text wrap‐
622              ping in the generated source code (see --wrap).  It also affects
623              calculation  of  column widths for plain text tables (see Tables
624              below).
625
626       --toc, --table-of-contents
627              Include an automatically generated table of contents (or, in the
628              case  of latex, context, docx, odt, opendocument, rst, or ms, an
629              instruction to create one) in the output document.  This  option
630              has  no  effect  unless  -s/--standalone  is used, and it has no
631              effect on man, docbook4, docbook5, or jats output.
632
633       --toc-depth=NUMBER
634              Specify the number of section levels to include in the table  of
635              contents.   The default is 3 (which means that level 1, 2, and 3
636              headers will be listed in the contents).
637
638       --strip-comments
639              Strip out HTML comments  in  the  Markdown  or  Textile  source,
640              rather  than passing them on to Markdown, Textile or HTML output
641              as raw HTML.  This does not apply to HTML  comments  inside  raw
642              HTML  blocks  when  the markdown_in_html_blocks extension is not
643              set.
644
645       --no-highlight
646              Disables syntax highlighting for code blocks and  inlines,  even
647              when a language attribute is given.
648
649       --highlight-style=STYLE|FILE
650              Specifies  the  coloring  style to be used in highlighted source
651              code.  Options are pygments  (the  default),  kate,  monochrome,
652              breezeDark,  espresso,  zenburn,  haddock,  and tango.  For more
653              information on syntax highlighting in pandoc, see  Syntax  high‐
654              lighting, below.  See also --list-highlight-styles.
655
656              Instead  of  a STYLE name, a JSON file with extension .theme may
657              be supplied.  This will be parsed as a KDE  syntax  highlighting
658              theme and (if valid) used as the highlighting style.
659
660              To   generate  the  JSON  version  of  an  existing  style,  use
661              --print-highlight-style.
662
663       --print-highlight-style=STYLE|FILE
664              Prints a JSON version of a highlighting style, which can be mod‐
665              ified,  saved  with  a  .theme  extension, and used with --high‐
666              light-style.
667
668       --syntax-definition=FILE
669              Instructs pandoc to load a KDE XML syntax definition file, which
670              will  be  used  for  syntax highlighting of appropriately marked
671              code blocks.  This can be used to add support for new  languages
672              or to use altered syntax definitions for existing languages.
673
674       -H FILE, --include-in-header=FILE
675              Include  contents  of  FILE, verbatim, at the end of the header.
676              This can be  used,  for  example,  to  include  special  CSS  or
677              JavaScript  in  HTML documents.  This option can be used repeat‐
678              edly to include multiple files in  the  header.   They  will  be
679              included in the order specified.  Implies --standalone.
680
681       -B FILE, --include-before-body=FILE
682              Include contents of FILE, verbatim, at the beginning of the doc‐
683              ument  body  (e.g.   after  the  <body>  tag  in  HTML,  or  the
684              \begin{document} command in LaTeX).  This can be used to include
685              navigation bars or banners in HTML documents.  This  option  can
686              be  used  repeatedly  to  include  multiple files.  They will be
687              included in the order specified.  Implies --standalone.
688
689       -A FILE, --include-after-body=FILE
690              Include contents of FILE, verbatim, at the end of  the  document
691              body (before the </body> tag in HTML, or the \end{document} com‐
692              mand in LaTeX).  This option can be used repeatedly  to  include
693              multiple  files.   They will be included in the order specified.
694              Implies --standalone.
695
696       --resource-path=SEARCHPATH
697              List of paths to search for images  and  other  resources.   The
698              paths  should  be  separated by : on Linux, UNIX, and macOS sys‐
699              tems, and by ; on Windows.  If --resource-path is not specified,
700              the  default resource path is the working directory.  Note that,
701              if --resource-path is specified, the working directory  must  be
702              explicitly  listed  or  it  will  not be searched.  For example:
703              --resource-path=.:test will search the working directory and the
704              test subdirectory, in that order.
705
706              --resource-path  only  has  an  effect  if (a) the output format
707              embeds images (for example, docx, pdf, or html with  --self-con‐
708              tained) or (b) it is used together with --extract-media.
709
710       --request-header=NAME:VAL
711              Set  the  request  header NAME to the value VAL when making HTTP
712              requests (for example, when a URL is given on the command  line,
713              or  when  resources  used in a document must be downloaded).  If
714              you're behind a proxy, you also  need  to  set  the  environment
715              variable http_proxy to http://....
716
717   Options affecting specific writers
718       --self-contained
719              Produce  a  standalone  HTML file with no external dependencies,
720              using data: URIs to incorporate the contents of linked  scripts,
721              stylesheets,  images,  and  videos.   Implies --standalone.  The
722              resulting file should be "self-contained," in the sense that  it
723              needs  no external files and no net access to be displayed prop‐
724              erly by a browser.  This option works only with HTML output for‐
725              mats,  including  html4,  html5, html+lhs, html5+lhs, s5, slidy,
726              slideous,  dzslides,  and  revealjs.    Scripts,   images,   and
727              stylesheets  at absolute URLs will be downloaded; those at rela‐
728              tive URLs will be sought relative to the working  directory  (if
729              the  first source file is local) or relative to the base URL (if
730              the first source file is remote).  Elements with  the  attribute
731              data-external="1" will be left alone; the documents they link to
732              will not be incorporated in the document.  Limitation: resources
733              that  are loaded dynamically through JavaScript cannot be incor‐
734              porated; as  a  result,  --self-contained  does  not  work  with
735              --mathjax,  and  some  advanced  features (e.g.  zoom or speaker
736              notes) may not work in  an  offline  "self-contained"  reveal.js
737              slide show.
738
739       --html-q-tags
740              Use <q> tags for quotes in HTML.
741
742       --ascii
743              Use  only  ASCII  characters in output.  Currently supported for
744              XML and HTML formats (which use entities instead of  UTF-8  when
745              this  option  is selected), CommonMark, gfm, and Markdown (which
746              use entities), roff ms (which use hexadecimal escapes), and to a
747              limited  degree LaTeX (which uses standard commands for accented
748              characters when  possible).   roff  man  output  uses  ASCII  by
749              default.
750
751       --reference-links
752              Use  reference-style links, rather than inline links, in writing
753              Markdown or reStructuredText.  By default inline links are used.
754              The  placement  of  link  references is affected by the --refer‐
755              ence-location option.
756
757       --reference-location = block|section|document
758              Specify whether footnotes (and references, if reference-links is
759              set) are placed at the end of the current (top-level) block, the
760              current section, or the  document.   The  default  is  document.
761              Currently only affects the markdown writer.
762
763       --atx-headers
764              Use ATX-style headers in Markdown output.  The default is to use
765              setext-style headers for  levels  1-2,  and  then  ATX  headers.
766              (Note: for gfm output, ATX headers are always used.)
767
768       --top-level-division=[default|section|chapter|part]
769              Treat  top-level  headers  as  the given division type in LaTeX,
770              ConTeXt, DocBook, and TEI output.  The hierarchy order is  part,
771              chapter,  then  section;  all  headers are shifted such that the
772              top-level header becomes the specified type.  The default behav‐
773              ior  is  to  determine  the  best  division type via heuristics:
774              unless other conditions apply,  section  is  chosen.   When  the
775              LaTeX  document  class is set to report, book, or memoir (unless
776              the article option is specified), chapter is implied as the set‐
777              ting  for this option.  If beamer is the output format, specify‐
778              ing either chapter or  part  will  cause  top-level  headers  to
779              become  \part{..},  while  second-level  headers remain as their
780              default type.
781
782       -N, --number-sections
783              Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
784              By  default,  sections  are  not  numbered.  Sections with class
785              unnumbered will never be numbered, even if --number-sections  is
786              specified.
787
788       --number-offset=NUMBER[,NUMBER,...]
789              Offset  for  section  headings  in HTML output (ignored in other
790              output formats).  The first number is added to the section  num‐
791              ber  for top-level headers, the second for second-level headers,
792              and so on.  So, for example, if you  want  the  first  top-level
793              header  in  your  document  to  be  numbered "6", specify --num‐
794              ber-offset=5.  If your document starts  with  a  level-2  header
795              which  you  want  to  be  numbered  "1.5", specify --number-off‐
796              set=1,4.  Offsets are 0 by default.  Implies --number-sections.
797
798       --listings
799              Use the listings package for LaTeX  code  blocks.   The  package
800              does not support multi-byte encoding for source code.  To handle
801              UTF-8 you would need to use a custom template.   This  issue  is
802              fully documented here: Encoding issue with the listings package.
803
804       -i, --incremental
805              Make  list  items  in  slide shows display incrementally (one by
806              one).  The default is for lists to be displayed all at once.
807
808       --slide-level=NUMBER
809              Specifies that headers with the specified  level  create  slides
810              (for beamer, s5, slidy, slideous, dzslides).  Headers above this
811              level in the hierarchy are used to divide the  slide  show  into
812              sections;  headers  below  this  level  create subheads within a
813              slide.   Note  that  content  that  is   not   contained   under
814              slide-level  headers  will  not  appear  in the slide show.  The
815              default is to set the slide level based on the contents  of  the
816              document; see Structuring the slide show.
817
818       --section-divs
819              Wrap  sections  in <section> tags (or <div> tags for html4), and
820              attach identifiers to the enclosing <section> (or <div>)  rather
821              than the header itself.  See Header identifiers, below.
822
823       --email-obfuscation=none|javascript|references
824              Specify  a  method  for  obfuscating mailto: links in HTML docu‐
825              ments.  none leaves  mailto:  links  as  they  are.   javascript
826              obfuscates them using JavaScript.  references obfuscates them by
827              printing their letters as decimal or hexadecimal character  ref‐
828              erences.  The default is none.
829
830       --id-prefix=STRING
831              Specify  a  prefix  to  be added to all identifiers and internal
832              links in HTML and DocBook output, and  to  footnote  numbers  in
833              Markdown  and  Haddock  output.   This  is useful for preventing
834              duplicate identifiers when generating fragments to  be  included
835              in other pages.
836
837       -T STRING, --title-prefix=STRING
838              Specify  STRING  as  a prefix at the beginning of the title that
839              appears in the HTML header (but not in the title as  it  appears
840              at the beginning of the HTML body).  Implies --standalone.
841
842       -c URL, --css=URL
843              Link  to  a CSS style sheet.  This option can be used repeatedly
844              to include multiple files.  They will be included in  the  order
845              specified.
846
847              A  stylesheet  is required for generating EPUB.  If none is pro‐
848              vided using this option  (or  the  css  or  stylesheet  metadata
849              fields),  pandoc  will look for a file epub.css in the user data
850              directory (see --data-dir).  If it is not found there,  sensible
851              defaults will be used.
852
853       --reference-doc=FILE
854              Use  the specified file as a style reference in producing a docx
855              or ODT file.
856
857              Docx   For best results, the reference docx should be a modified
858                     version  of  a docx file produced using pandoc.  The con‐
859                     tents  of  the  reference  docx  are  ignored,  but   its
860                     stylesheets  and  document properties (including margins,
861                     page size, header, and footer) are used in the new  docx.
862                     If  no  reference  docx is specified on the command line,
863                     pandoc will look for a file reference.docx  in  the  user
864                     data  directory  (see  --data-dir).  If this is not found
865                     either, sensible defaults will be used.
866
867                     To produce a custom reference.docx, first get a  copy  of
868                     the         default         reference.docx:        pandoc
869                     --print-default-data-file reference.docx >  custom-refer‐
870                     ence.docx.  Then open custom-reference.docx in Word, mod‐
871                     ify the styles as you wish, and save the file.  For  best
872                     results, do not make changes to this file other than mod‐
873                     ifying the styles used  by  pandoc:  [paragraph]  Normal,
874                     Body  Text,  First  Paragraph,  Compact, Title, Subtitle,
875                     Author, Date, Abstract, Bibliography, Heading 1,  Heading
876                     2, Heading 3, Heading 4, Heading 5, Heading 6, Heading 7,
877                     Heading 8, Heading 9, Block Text, Footnote Text,  Defini‐
878                     tion Term, Definition, Caption, Table Caption, Image Cap‐
879                     tion, Figure, Captioned Figure, TOC Heading;  [character]
880                     Default  Paragraph  Font,  Body Text Char, Verbatim Char,
881                     Footnote Reference, Hyperlink; [table] Table.
882
883              ODT    For best results, the reference ODT should be a  modified
884                     version of an ODT produced using pandoc.  The contents of
885                     the reference ODT are ignored, but  its  stylesheets  are
886                     used in the new ODT.  If no reference ODT is specified on
887                     the command line, pandoc will  look  for  a  file  refer‐
888                     ence.odt in the user data directory (see --data-dir).  If
889                     this is not found either, sensible defaults will be used.
890
891                     To produce a custom reference.odt, first get  a  copy  of
892                     the         default         reference.odt:         pandoc
893                     --print-default-data-file reference.odt  >  custom-refer‐
894                     ence.odt.  Then open custom-reference.odt in LibreOffice,
895                     modify the styles as you wish, and save the file.
896
897              PowerPoint
898                     Any template included with a recent install of  Microsoft
899                     PowerPoint  (either with .pptx or .potx extension) should
900                     work, as will most templates derived from these.
901
902                     The specific requirement is that the template should con‐
903                     tain  the  following  four layouts as its first four lay‐
904                     outs:
905
906                     1. Title Slide
907
908                     2. Title and Content
909
910                     3. Section Header
911
912                     4. Two Content
913
914                     All templates included with a recent version of MS Power‐
915                     Point  will fit these criteria.  (You can click on Layout
916                     under the Home menu to check.)
917
918                     You can also modify the default reference.pptx: first run
919                     pandoc  --print-default-data-file  reference.pptx  > cus‐
920                     tom-reference.pptx, and then modify custom-reference.pptx
921                     in  MS  PowerPoint (pandoc will use the first four layout
922                     slides, as mentioned above).
923
924       --epub-cover-image=FILE
925              Use the specified image as the EPUB cover.   It  is  recommended
926              that  the  image  be less than 1000px in width and height.  Note
927              that  in  a  Markdown  source  document  you  can  also  specify
928              cover-image in a YAML metadata block (see EPUB Metadata, below).
929
930       --epub-metadata=FILE
931              Look  in  the specified XML file for metadata for the EPUB.  The
932              file should contain a series of Dublin Core elements.  For exam‐
933              ple:
934
935                      <dc:rights>Creative Commons</dc:rights>
936                      <dc:language>es-AR</dc:language>
937
938              By default, pandoc will include the following metadata elements:
939              <dc:title> (from the document  title),  <dc:creator>  (from  the
940              document  authors),  <dc:date>  (from  the  document date, which
941              should be in ISO 8601  format),  <dc:language>  (from  the  lang
942              variable,  or,  if  is  not set, the locale), and <dc:identifier
943              id="BookId"> (a randomly generated UUID).  Any of these  may  be
944              overridden by elements in the metadata file.
945
946              Note:  if the source document is Markdown, a YAML metadata block
947              in the document can be used instead.  See below under EPUB Meta‐
948              data.
949
950       --epub-embed-font=FILE
951              Embed  the  specified  font  in  the  EPUB.   This option can be
952              repeated to embed multiple fonts.  Wildcards can also  be  used:
953              for example, DejaVuSans-*.ttf.  However, if you use wildcards on
954              the command line, be sure to escape them or put the whole  file‐
955              name in single quotes, to prevent them from being interpreted by
956              the shell.  To use the embedded fonts, you will need to add dec‐
957              larations like the following to your CSS (see --css):
958
959                     @font-face {
960                     font-family: DejaVuSans;
961                     font-style: normal;
962                     font-weight: normal;
963                     src:url("DejaVuSans-Regular.ttf");
964                     }
965                     @font-face {
966                     font-family: DejaVuSans;
967                     font-style: normal;
968                     font-weight: bold;
969                     src:url("DejaVuSans-Bold.ttf");
970                     }
971                     @font-face {
972                     font-family: DejaVuSans;
973                     font-style: italic;
974                     font-weight: normal;
975                     src:url("DejaVuSans-Oblique.ttf");
976                     }
977                     @font-face {
978                     font-family: DejaVuSans;
979                     font-style: italic;
980                     font-weight: bold;
981                     src:url("DejaVuSans-BoldOblique.ttf");
982                     }
983                     body { font-family: "DejaVuSans"; }
984
985       --epub-chapter-level=NUMBER
986              Specify  the  header level at which to split the EPUB into sepa‐
987              rate "chapter" files.  The default is to split into chapters  at
988              level 1 headers.  This option only affects the internal composi‐
989              tion of the EPUB, not the way chapters  and  sections  are  dis‐
990              played  to users.  Some readers may be slow if the chapter files
991              are too large, so for large documents with few level 1  headers,
992              one might want to use a chapter level of 2 or 3.
993
994       --epub-subdirectory=DIRNAME
995              Specify  the  subdirectory  in the OCF container that is to hold
996              the EPUB-specific contents.  The default is EPUB.   To  put  the
997              EPUB contents in the top level, use an empty string.
998
999       --pdf-engine=pdflatex|lualatex|xelatex|wkhtml‐
1000       topdf|weasyprint|prince|context|pdfroff
1001              Use the specified engine when producing PDF output.  The default
1002              is  pdflatex.   If the engine is not in your PATH, the full path
1003              of the engine may be specified here.
1004
1005       --pdf-engine-opt=STRING
1006              Use  the  given  string  as  a  command-line  argument  to   the
1007              pdf-engine.   If used multiple times, the arguments are provided
1008              with spaces between them.  Note  that  no  check  for  duplicate
1009              options is done.
1010
1011   Citation rendering
1012       --bibliography=FILE
1013              Set  the  bibliography field in the document's metadata to FILE,
1014              overriding any value set in the metadata, and process  citations
1015              using pandoc-citeproc.  (This is equivalent to --metadata bibli‐
1016              ography=FILE --filter pandoc-citeproc.)  If --natbib or --bibla‐
1017              tex  is  also supplied, pandoc-citeproc is not used, making this
1018              equivalent to --metadata bibliography=FILE.  If you supply  this
1019              argument  multiple  times, each FILE will be added to bibliogra‐
1020              phy.
1021
1022       --csl=FILE
1023              Set the csl field in the document's metadata to FILE, overriding
1024              any  value  set in the metadata.  (This is equivalent to --meta‐
1025              data  csl=FILE.)  This  option  is  only  relevant   with   pan‐
1026              doc-citeproc.
1027
1028       --citation-abbreviations=FILE
1029              Set  the citation-abbreviations field in the document's metadata
1030              to FILE, overriding any value set in  the  metadata.   (This  is
1031              equivalent   to  --metadata  citation-abbreviations=FILE.)  This
1032              option is only relevant with pandoc-citeproc.
1033
1034       --natbib
1035              Use natbib for citations in LaTeX output.  This  option  is  not
1036              for  use with the pandoc-citeproc filter or with PDF output.  It
1037              is intended for use in producing a LaTeX file that can  be  pro‐
1038              cessed with bibtex.
1039
1040       --biblatex
1041              Use  biblatex for citations in LaTeX output.  This option is not
1042              for use with the pandoc-citeproc filter or with PDF output.   It
1043              is  intended  for use in producing a LaTeX file that can be pro‐
1044              cessed with bibtex or biber.
1045
1046   Math rendering in HTML
1047       The default is to render TeX math as  far  as  possible  using  Unicode
1048       characters.   Formulas are put inside a span with class="math", so that
1049       they may be styled differently from the  surrounding  text  if  needed.
1050       However, this gives acceptable results only for basic math, usually you
1051       will want to use --mathjax or another of the following options.
1052
1053       --mathjax[=URL]
1054              Use MathJax to display embedded TeX math in  HTML  output.   TeX
1055              math  will  be  put between \(...\) (for inline math) or \[...\]
1056              (for display math) and wrapped in <span> tags with  class  math.
1057              Then  the  MathJax  JavaScript  will  render it.  The URL should
1058              point to the MathJax.js load script.  If a URL is not  provided,
1059              a link to the Cloudflare CDN will be inserted.
1060
1061       --mathml
1062              Convert  TeX math to MathML (in epub3, docbook4, docbook5, jats,
1063              html4 and html5).  This is the default in odt output.  Note that
1064              currently  only  Firefox  and Safari (and select e-book readers)
1065              natively support MathML.
1066
1067       --webtex[=URL]
1068              Convert TeX formulas to <img> tags  that  link  to  an  external
1069              script  that  converts  formulas to images.  The formula will be
1070              URL-encoded and concatenated with the  URL  provided.   For  SVG
1071              images      you     can     for     example     use     --webtex
1072              https://latex.codecogs.com/svg.latex?.  If no URL is  specified,
1073              the    CodeCogs    URL    generating    PNGs    will   be   used
1074              (https://latex.codecogs.com/png.latex?).   Note:  the   --webtex
1075              option  will  affect  Markdown  output as well as HTML, which is
1076              useful if you're targeting a version of Markdown without  native
1077              math support.
1078
1079       --katex[=URL]
1080              Use  KaTeX to display embedded TeX math in HTML output.  The URL
1081              is the base URL for the KaTeX library.   That  directory  should
1082              contain  a  katex.min.js  and a katex.min.css file.  If a URL is
1083              not provided, a link to the KaTeX CDN will be inserted.
1084
1085       --gladtex
1086              Enclose TeX math in <eq> tags in  HTML  output.   The  resulting
1087              HTML  can  then be processed by GladTeX to produce images of the
1088              typeset formulas and an HTML file with links  to  these  images.
1089              So, the procedure is:
1090
1091                     pandoc -s --gladtex input.md -o myfile.htex
1092                     gladtex -d myfile-images myfile.htex
1093                     # produces myfile.html and images in myfile-images
1094
1095   Options for wrapper scripts
1096       --dump-args
1097              Print  information  about command-line arguments to stdout, then
1098              exit.  This option is intended  primarily  for  use  in  wrapper
1099              scripts.  The first line of output contains the name of the out‐
1100              put file specified with the -o option, or - (for stdout)  if  no
1101              output file was specified.  The remaining lines contain the com‐
1102              mand-line arguments, one per line, in  the  order  they  appear.
1103              These do not include regular pandoc options and their arguments,
1104              but do include any options appearing after a -- separator at the
1105              end of the line.
1106
1107       --ignore-args
1108              Ignore  command-line  arguments  (for  use  in wrapper scripts).
1109              Regular pandoc options are not ignored.  Thus, for example,
1110
1111                     pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1112
1113              is equivalent to
1114
1115                     pandoc -o foo.html -s
1116

TEMPLATES

1118       When the -s/--standalone option is used, pandoc uses a template to  add
1119       header and footer material that is needed for a self-standing document.
1120       To see the default template that is used, just type
1121
1122              pandoc -D *FORMAT*
1123
1124       where FORMAT is the name of the output format.  A custom  template  can
1125       be  specified  using  the --template option.  You can also override the
1126       system default templates for a given output format FORMAT by putting  a
1127       file   templates/default.*FORMAT*  in  the  user  data  directory  (see
1128       --data-dir, above).  Exceptions:
1129
1130       · For odt output, customize the default.opendocument template.
1131
1132       · For  pdf  output,  customize  the  default.latex  template  (or   the
1133         default.context  template,  if  you use -t context, or the default.ms
1134         template, if you use -t ms, or the default.html template, if you  use
1135         -t html).
1136
1137       · docx has no template (however, you can use --reference-doc to custom‐
1138         ize the output).
1139
1140       Templates contain variables, which allow for the inclusion of arbitrary
1141       information  at  any point in the file.  They may be set at the command
1142       line using the -V/--variable option.  If a variable is not set,  pandoc
1143       will  look  for  the  key in the document's metadata – which can be set
1144       using either YAML metadata blocks or with the --metadata option.
1145
1146   Variables set by pandoc
1147       Some variables are set automatically by pandoc.   These  vary  somewhat
1148       depending on the output format, but include the following:
1149
1150       sourcefile, outputfile
1151              source  and destination filenames, as given on the command line.
1152              sourcefile can also be a  list  if  input  comes  from  multiple
1153              files, or empty if input is from stdin.  You can use the follow‐
1154              ing snippet in your template to distinguish them:
1155
1156                     $if(sourcefile)$
1157                     $for(sourcefile)$
1158                     $sourcefile$
1159                     $endfor$
1160                     $else$
1161                     (stdin)
1162                     $endif$
1163
1164              Similarly, outputfile can be - if output goes to the terminal.
1165
1166       title, author, date
1167              allow identification of basic aspects of the document.  Included
1168              in  PDF  metadata  through  LaTeX and ConTeXt.  These can be set
1169              through a pandoc title block, which allows for multiple authors,
1170              or through a YAML metadata block:
1171
1172                     ---
1173                     author:
1174                     - Aristotle
1175                     - Peter Abelard
1176                     ...
1177
1178       subtitle
1179              document  subtitle,  included in HTML, EPUB, LaTeX, ConTeXt, and
1180              Word docx; renders in LaTeX only when  using  a  document  class
1181              that  supports  \subtitle,  such  as  beamer  or the KOMA-Script
1182              series (scrartcl, scrreprt, scrbook).
1183
1184       institute
1185              author affiliations (in LaTeX and Beamer only).  Can be a  list,
1186              when there are multiple authors.
1187
1188       abstract
1189              document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word
1190              docx
1191
1192       keywords
1193              list of keywords to be included in HTML, PDF, and AsciiDoc meta‐
1194              data; may be repeated as for author, above
1195
1196       header-includes
1197              contents  specified by -H/--include-in-header (may have multiple
1198              values)
1199
1200       toc    non-null value if --toc/--table-of-contents was specified
1201
1202       toc-title
1203              title of table of contents (works only with EPUB,  opendocument,
1204              odt, docx, pptx, beamer, LaTeX)
1205
1206       include-before
1207              contents  specified by -B/--include-before-body (may have multi‐
1208              ple values)
1209
1210       include-after
1211              contents specified by -A/--include-after-body (may have multiple
1212              values)
1213
1214       body   body of document
1215
1216       meta-json
1217              JSON  representation  of  all of the document's metadata.  Field
1218              values are transformed to the selected output format.
1219
1220   Language variables
1221       lang   identifies the main language  of  the  document,  using  a  code
1222              according  to  BCP 47 (e.g.  en or en-GB).  For some output for‐
1223              mats, pandoc will convert it to an appropriate format stored  in
1224              the  additional  variables  babel-lang, polyglossia-lang (LaTeX)
1225              and context-lang (ConTeXt).
1226
1227              Native pandoc Spans and Divs with the lang attribute  (value  in
1228              BCP  47)  can  be used to switch the language in that range.  In
1229              LaTeX output, babel-otherlangs and polyglossia-otherlangs  vari‐
1230              ables   will  be  generated  automatically  based  on  the  lang
1231              attributes of Spans and Divs in the document.
1232
1233       dir    the base direction of the document, either  rtl  (right-to-left)
1234              or ltr (left-to-right).
1235
1236              For  bidirectional  documents, native pandoc spans and divs with
1237              the dir attribute (value rtl or ltr) can be used to override the
1238              base  direction  in some output formats.  This may not always be
1239              necessary if the final renderer (e.g.  the browser, when  gener‐
1240              ating HTML) supports the Unicode Bidirectional Algorithm.
1241
1242              When  using  LaTeX for bidirectional documents, only the xelatex
1243              engine is fully supported (use --pdf-engine=xelatex).
1244
1245   Variables for slides
1246       Variables are available for producing slide shows with pandoc,  includ‐
1247       ing all reveal.js configuration options.
1248
1249       titlegraphic
1250              title graphic for Beamer documents
1251
1252       logo   logo for Beamer documents
1253
1254       slidy-url
1255              base     URL     for     Slidy     documents     (defaults    to
1256              https://www.w3.org/Talks/Tools/Slidy2)
1257
1258       slideous-url
1259              base URL for Slideous documents (defaults to slideous)
1260
1261       s5-url base URL for S5 documents (defaults to s5/default)
1262
1263       revealjs-url
1264              base URL for reveal.js documents (defaults to reveal.js)
1265
1266       theme, colortheme, fonttheme, innertheme, outertheme
1267              themes for LaTeX beamer documents
1268
1269       themeoptions
1270              options for LaTeX beamer themes (a list).
1271
1272       navigation
1273              controls navigation symbols  in  beamer  documents  (default  is
1274              empty  for  no navigation symbols; other valid values are frame,
1275              vertical, and horizontal).
1276
1277       section-titles
1278              enables on "title pages" for new sections  in  beamer  documents
1279              (default = true).
1280
1281       beamerarticle
1282              when true, the beamerarticle package is loaded (for producing an
1283              article from beamer slides).
1284
1285       aspectratio
1286              aspect ratio of slides (for beamer only, 1610 for 16:10, 169 for
1287              16:9, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 43 for 4:3 which
1288              is the default, and 32 for 3:2).
1289
1290   Variables for LaTeX
1291       LaTeX variables are used when creating a PDF.
1292
1293       papersize
1294              paper size, e.g.  letter, a4
1295
1296       fontsize
1297              font size for body text (e.g.  10pt, 12pt)
1298
1299       documentclass
1300              document class, e.g.  article, report, book, memoir
1301
1302       classoption
1303              option for document class, e.g.  oneside; may  be  repeated  for
1304              multiple options
1305
1306       beameroption
1307              In beamer, add extra beamer option with \setbeameroption{}
1308
1309       geometry
1310              option  for  geometry package, e.g.  margin=1in; may be repeated
1311              for multiple options
1312
1313       margin-left, margin-right, margin-top, margin-bottom
1314              sets margins, if geometry is not used (otherwise geometry  over‐
1315              rides these)
1316
1317       linestretch
1318              adjusts line spacing using the setspace package, e.g.  1.25, 1.5
1319
1320       fontfamily
1321              font  package  for  use  with  pdflatex:  TeX Live includes many
1322              options, documented in the LaTeX Font Catalogue.  The default is
1323              Latin Modern.
1324
1325       fontfamilyoptions
1326              options  for package used as fontfamily: e.g.  osf,sc with font‐
1327              family set to mathpazo provides Palatino with old-style  figures
1328              and true small caps; may be repeated for multiple options
1329
1330       mainfont, romanfont, sansfont, monofont, mathfont, CJKmainfont
1331              font families for use with xelatex or lualatex: take the name of
1332              any system font, using the fontspec package.  Note that if  CJK‐
1333              mainfont is used, the xecjk package must be available.
1334
1335       mainfontoptions,  romanfontoptions,  sansfontoptions,  monofontoptions,
1336       mathfontoptions, CJKoptions
1337              options to use with mainfont, sansfont, monofont, mathfont, CJK‐
1338              mainfont  in xelatex and lualatex.  Allow for any choices avail‐
1339              able through  fontspec,  such  as  the  OpenType  features  Num‐
1340              bers=OldStyle,Numbers=Proportional.   May be repeated for multi‐
1341              ple options.
1342
1343       fontenc
1344              allows font encoding to be  specified  through  fontenc  package
1345              (with  pdflatex);  default is T1 (see guide to LaTeX font encod‐
1346              ings)
1347
1348       microtypeoptions
1349              options to pass to the microtype package
1350
1351       colorlinks
1352              add color to link text; automatically enabled if  any  of  link‐
1353              color, filecolor, citecolor, urlcolor, or toccolor are set
1354
1355       linkcolor, filecolor, citecolor, urlcolor, toccolor
1356              color for internal links, external links, citation links, linked
1357              URLs, and links in table of contents, respectively: uses options
1358              allowed  by  xcolor,  including  the  dvipsnames,  svgnames, and
1359              x11names lists
1360
1361       links-as-notes
1362              causes links to be printed as footnotes
1363
1364       indent uses document class settings for indentation (the default  LaTeX
1365              template  otherwise  removes  indentation and adds space between
1366              paragraphs)
1367
1368       subparagraph
1369              disables default  behavior  of  LaTeX  template  that  redefines
1370              (sub)paragraphs  as  sections, changing the appearance of nested
1371              headings in some classes
1372
1373       thanks specifies contents of acknowledgments  footnote  after  document
1374              title.
1375
1376       toc    include  table  of  contents  (can also be set using --toc/--ta‐
1377              ble-of-contents)
1378
1379       toc-depth
1380              level of section to include in table of contents
1381
1382       secnumdepth
1383              numbering depth for sections, if sections are numbered
1384
1385       lof, lot
1386              include list of figures, list of tables
1387
1388       bibliography
1389              bibliography to use for resolving references
1390
1391       biblio-style
1392              bibliography style, when used with --natbib and --biblatex.
1393
1394       biblio-title
1395              bibliography title, when used with --natbib and --biblatex.
1396
1397       biblatexoptions
1398              list of options for biblatex.
1399
1400       natbiboptions
1401              list of options for natbib.
1402
1403       pagestyle
1404              An option for LaTeX's \pagestyle{}.  The default  article  class
1405              supports  'plain'  (default),  'empty', and 'headings'; headings
1406              puts section titles in the header.
1407
1408   Variables for ConTeXt
1409       papersize
1410              paper size, e.g.  letter, A4, landscape (see ConTeXt Paper  Set‐
1411              up); may be repeated for multiple options
1412
1413       layout options  for page margins and text arrangement (see ConTeXt Lay‐
1414              out); may be repeated for multiple options
1415
1416       margin-left, margin-right, margin-top, margin-bottom
1417              sets margins, if layout is not used (otherwise layout  overrides
1418              these)
1419
1420       fontsize
1421              font size for body text (e.g.  10pt, 12pt)
1422
1423       mainfont, sansfont, monofont, mathfont
1424              font  families:  take  the  name of any system font (see ConTeXt
1425              Font Switching)
1426
1427       linkcolor, contrastcolor
1428              color for links outside and inside a page, e.g.  red, blue  (see
1429              ConTeXt Color)
1430
1431       linkstyle
1432              typeface  style  for  links,  e.g.  normal, bold, slanted, bold‐
1433              slanted, type, cap, small
1434
1435       indenting
1436              controls indentation of paragraphs,  e.g.   yes,small,next  (see
1437              ConTeXt Indentation); may be repeated for multiple options
1438
1439       whitespace
1440              spacing  between  paragraphs,  e.g.   none,  small (using setup‐
1441              whitespace)
1442
1443       interlinespace
1444              adjusts line spacing, e.g.  4ex (using setupinterlinespace); may
1445              be repeated for multiple options
1446
1447       headertext, footertext
1448              text to be placed in running header or footer (see ConTeXt Head‐
1449              ers and Footers); may be repeated up to four times for different
1450              placement
1451
1452       pagenumbering
1453              page  number  style and location (using setuppagenumbering); may
1454              be repeated for multiple options
1455
1456       toc    include table of contents (can also  be  set  using  --toc/--ta‐
1457              ble-of-contents)
1458
1459       lof, lot
1460              include list of figures, list of tables
1461
1462       pdfa   adds   to   the   preamble   the  setup  necessary  to  generate
1463              PDF/A-1b:2005.  To successfully generate PDF/A the required  ICC
1464              color  profiles  have  to  be  available and the content and all
1465              included files (such as images) have to be standard  conforming.
1466              The ICC profiles can be obtained from ConTeXt ICC Profiles.  See
1467              also ConTeXt PDFA for more details.
1468
1469   Variables for man pages
1470       section
1471              section number in man pages
1472
1473       header header in man pages
1474
1475       footer footer in man pages
1476
1477       adjusting
1478              adjusts text to left (l), right (r), center  (c),  or  both  (b)
1479              margins
1480
1481       hyphenate
1482              if true (the default), hyphenation will be used
1483
1484   Variables for ms
1485       pointsize
1486              point size (e.g.  10p)
1487
1488       lineheight
1489              line height (e.g.  12p)
1490
1491       fontfamily
1492              font family (e.g.  T or P)
1493
1494       indent paragraph indent (e.g.  2m)
1495
1496   Using variables in templates
1497       Variable  names are sequences of alphanumerics, -, and _, starting with
1498       a letter.  A variable name surrounded by $ signs will  be  replaced  by
1499       its value.  For example, the string $title$ in
1500
1501              <title>$title$</title>
1502
1503       will be replaced by the document title.
1504
1505       To write a literal $ in a template, use $$.
1506
1507       Templates may contain conditionals.  The syntax is as follows:
1508
1509              $if(variable)$
1510              X
1511              $else$
1512              Y
1513              $endif$
1514
1515       This  will  include  X  in the template if variable has a truthy value;
1516       otherwise it will include Y.  Here a truthy value is any of the follow‐
1517       ing:
1518
1519       · a string that is not entirely white space,
1520
1521       · a non-empty array where the first value is truthy,
1522
1523       · any number (including zero),
1524
1525       · any object,
1526
1527       · the  boolean true (to specify the boolean true value using YAML meta‐
1528         data or the --metadata flag,  use  true,  True,  or  TRUE;  with  the
1529         --variable  flag, simply omit a value for the variable, e.g.  --vari‐
1530         able draft).
1531
1532       X and Y are placeholders for any valid template text, and  may  include
1533       interpolated  variables  or other conditionals.  The $else$ section may
1534       be omitted.
1535
1536       When variables can have multiple  values  (for  example,  author  in  a
1537       multi-author document), you can use the $for$ keyword:
1538
1539              $for(author)$
1540              <meta name="author" content="$author$" />
1541              $endfor$
1542
1543       You  can  optionally specify a separator to be used between consecutive
1544       items:
1545
1546              $for(author)$$author$$sep$, $endfor$
1547
1548       A dot can be used to select a field of a variable that takes an  object
1549       as its value.  So, for example:
1550
1551              $author.name$ ($author.affiliation$)
1552
1553       If  you  use  custom  templates,  you may need to revise them as pandoc
1554       changes.  We recommend tracking the changes in the  default  templates,
1555       and  modifying  your  custom  templates accordingly.  An easy way to do
1556       this is to fork the pandoc-templates repository and  merge  in  changes
1557       after each pandoc release.
1558
1559       Templates  may  contain  comments: anything on a line after $-- will be
1560       treated as a comment and ignored.
1561

EXTENSIONS

1563       The behavior of some of the readers and  writers  can  be  adjusted  by
1564       enabling or disabling various extensions.
1565
1566       An extension can be enabled by adding +EXTENSION to the format name and
1567       disabled   by   adding   -EXTENSION.    For   example,   --from   mark‐
1568       down_strict+footnotes  is strict Markdown with footnotes enabled, while
1569       --from  markdown-footnotes-pipe_tables  is  pandoc's  Markdown  without
1570       footnotes or pipe tables.
1571
1572       The  markdown reader and writer make by far the most use of extensions.
1573       Extensions only used by them are therefore covered in the section  Pan‐
1574       doc's Markdown below (See Markdown variants for commonmark and gfm.) In
1575       the following, extensions that also work for other formats are covered.
1576
1577   Typography
1578   Extension: smart
1579       Interpret straight quotes as curly quotes,  ---  as  em-dashes,  --  as
1580       en-dashes,  and ... as ellipses.  Nonbreaking spaces are inserted after
1581       certain abbreviations, such as "Mr."
1582
1583       This extension can be enabled/disabled for the following formats:
1584
1585       input formats
1586              markdown, commonmark, latex, mediawiki, org, rst, twiki
1587
1588       output formats
1589              markdown, latex, context, rst
1590
1591       enabled by default in
1592              markdown, latex, context (both input and output)
1593
1594       Note: If you are writing Markdown, then the  smart  extension  has  the
1595       reverse effect: what would have been curly quotes comes out straight.
1596
1597       In  LaTeX,  smart means to use the standard TeX ligatures for quotation
1598       marks (`` and '' for double quotes, ` and  '  for  single  quotes)  and
1599       dashes  (--  for  en-dash  and --- for em-dash).  If smart is disabled,
1600       then in reading LaTeX pandoc will parse these characters literally.  In
1601       writing  LaTeX,  enabling  smart tells pandoc to use the ligatures when
1602       possible; if smart is disabled pandoc will use unicode  quotation  mark
1603       and dash characters.
1604
1605   Headers and sections
1606   Extension: auto_identifiers
1607       A  header  without an explicitly specified identifier will be automati‐
1608       cally assigned a unique identifier based on the header text.
1609
1610       This extension can be enabled/disabled for the following formats:
1611
1612       input formats
1613              markdown, latex, rst, mediawiki, textile
1614
1615       output formats
1616              markdown, muse
1617
1618       enabled by default in
1619              markdown, muse
1620
1621       The default algorithm used to derive the  identifier  from  the  header
1622       text is:
1623
1624       · Remove all formatting, links, etc.
1625
1626       · Remove all footnotes.
1627
1628       · Remove all punctuation, except underscores, hyphens, and periods.
1629
1630       · Replace all spaces and newlines with hyphens.
1631
1632       · Convert all alphabetic characters to lowercase.
1633
1634       · Remove  everything  up to the first letter (identifiers may not begin
1635         with a number or punctuation mark).
1636
1637       · If nothing is left after this, use the identifier section.
1638
1639       Thus, for example,
1640
1641       Header                       Identifier
1642       ────────────────────────────────────────────────────────
1643       Header identifiers in HTML   header-identifiers-in-html
1644       *Dogs*?--in *my* house?      dogs--in-my-house
1645       [HTML], [S5], or [RTF]?      html-s5-or-rtf
1646       3. Applications              applications
1647       33                           section
1648
1649       These rules should, in most cases, allow one to determine  the  identi‐
1650       fier  from the header text.  The exception is when several headers have
1651       the same text; in this case,  the  first  will  get  an  identifier  as
1652       described  above;  the  second  will  get  the  same identifier with -1
1653       appended; the third with -2; and so on.
1654
1655       (However, a different algorithm  is  used  if  gfm_auto_identifiers  is
1656       enabled; see below.)
1657
1658       These identifiers are used to provide link targets in the table of con‐
1659       tents generated by the  --toc|--table-of-contents  option.   They  also
1660       make  it  easy  to  provide  links  from  one  section of a document to
1661       another.  A link to this section, for example, might look like this:
1662
1663              See the section on
1664              [header identifiers](#header-identifiers-in-html-latex-and-context).
1665
1666       Note, however, that this method of providing links  to  sections  works
1667       only in HTML, LaTeX, and ConTeXt formats.
1668
1669       If  the  --section-divs  option is specified, then each section will be
1670       wrapped in a section (or a div, if html4 was specified), and the  iden‐
1671       tifier  will  be  attached  to  the  enclosing <section> (or <div>) tag
1672       rather than the header itself.   This  allows  entire  sections  to  be
1673       manipulated using JavaScript or treated differently in CSS.
1674
1675   Extension: ascii_identifiers
1676       Causes  the  identifiers produced by auto_identifiers to be pure ASCII.
1677       Accents are stripped off of accented Latin letters, and non-Latin  let‐
1678       ters are omitted.
1679
1680   Extension: gfm_auto_identifiers
1681       Changes  the  algorithm used by auto_identifiers to conform to GitHub's
1682       method.  Spaces are converted to dashes (-),  uppercase  characters  to
1683       lowercase characters, and punctuation characters other than - and _ are
1684       removed.
1685
1686   Math Input
1687       The   extensions   tex_math_dollars,   tex_math_single_backslash,   and
1688       tex_math_double_backslash  are  described in the section about Pandoc's
1689       Markdown.
1690
1691       However, they can also be used with HTML  input.   This  is  handy  for
1692       reading web pages formatted using MathJax, for example.
1693
1694   Raw HTML/TeX
1695       The   following   extensions   (especially  how  they  affect  Markdown
1696       input/output) are also described in more  detail  in  their  respective
1697       sections of Pandoc's Markdown.
1698
1699   Extension: raw_html
1700       When  converting  from  HTML,  parse elements to raw HTML which are not
1701       representable in pandoc's AST.  By default, this is disabled  for  HTML
1702       input.
1703
1704   Extension: raw_tex
1705       Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
1706
1707       This  extension  can  be enabled/disabled for the following formats (in
1708       addition to markdown):
1709
1710       input formats
1711              latex, org, textile, html (environments, \ref, and \eqref only)
1712
1713       output formats
1714              textile, commonmark
1715
1716   Extension: native_divs
1717       This extension is enabled by default for HTML input.  This  means  that
1718       divs  are  parsed  to  pandoc native elements.  (Alternatively, you can
1719       parse them to raw HTML using -f html-native_divs+raw_html.)
1720
1721       When converting HTML to Markdown, for example, you may want to drop all
1722       divs and spans:
1723
1724              pandoc -f html-native_divs-native_spans -t markdown
1725
1726   Extension: native_spans
1727       Analogous to native_divs above.
1728
1729   Literate Haskell support
1730   Extension: literate_haskell
1731       Treat the document as literate Haskell source.
1732
1733       This extension can be enabled/disabled for the following formats:
1734
1735       input formats
1736              markdown, rst, latex
1737
1738       output formats
1739              markdown, rst, latex, html
1740
1741       If  you append +lhs (or +literate_haskell) to one of the formats above,
1742       pandoc will treat the document as literate Haskell source.  This  means
1743       that
1744
1745       · In  Markdown  input,  "bird track" sections will be parsed as Haskell
1746         code rather than block quotations.   Text  between  \begin{code}  and
1747         \end{code} will also be treated as Haskell code.  For ATX-style head‐
1748         ers the character '=' will be used instead of '#'.
1749
1750       · In Markdown output, code blocks with  classes  haskell  and  literate
1751         will  be  rendered  using  bird  tracks, and block quotations will be
1752         indented one space, so they will not be treated as Haskell code.   In
1753         addition,  headers  will  be  rendered setext-style (with underlines)
1754         rather than ATX-style (with '#' characters).  (This  is  because  ghc
1755         treats '#' characters in column 1 as introducing line numbers.)
1756
1757       · In  restructured  text input, "bird track" sections will be parsed as
1758         Haskell code.
1759
1760       · In restructured text output, code blocks with class haskell  will  be
1761         rendered using bird tracks.
1762
1763       · In  LaTeX  input, text in code environments will be parsed as Haskell
1764         code.
1765
1766       · In LaTeX output, code blocks with  class  haskell  will  be  rendered
1767         inside code environments.
1768
1769       · In  HTML output, code blocks with class haskell will be rendered with
1770         class literatehaskell and bird tracks.
1771
1772       Examples:
1773
1774              pandoc -f markdown+lhs -t html
1775
1776       reads literate Haskell source formatted with Markdown  conventions  and
1777       writes ordinary HTML (without bird tracks).
1778
1779              pandoc -f markdown+lhs -t html+lhs
1780
1781       writes  HTML  with the Haskell code in bird tracks, so it can be copied
1782       and pasted as literate Haskell source.
1783
1784       Note that GHC expects the bird tracks in the first column, so  indented
1785       literate code blocks (e.g.  inside an itemized environment) will not be
1786       picked up by the Haskell compiler.
1787
1788   Other extensions
1789   Extension: empty_paragraphs
1790       Allows empty paragraphs.  By default empty paragraphs are omitted.
1791
1792       This extension can be enabled/disabled for the following formats:
1793
1794       input formats
1795              docx, html
1796
1797       output formats
1798              docx, odt, opendocument, html
1799
1800   Extension: styles
1801       Read all docx styles as divs (for  paragraph  styles)  and  spans  (for
1802       character  styles) regardless of whether pandoc understands the meaning
1803       of these styles.  This can be used with docx custom  styles.   Disabled
1804       by default.
1805
1806       input formats
1807              docx
1808
1809   Extension: amuse
1810       In  the muse input format, this enables Text::Amuse extensions to Emacs
1811       Muse markup.
1812
1813   Extension: citations
1814       Some aspects of Pandoc's Markdown citation syntax are also accepted  in
1815       org input.
1816
1817   Extension: ntb
1818       In  the  context  output  format this enables the use of Natural Tables
1819       (TABLE) instead of  the  default  Extreme  Tables  (xtables).   Natural
1820       tables  allow more fine-grained global customization but come at a per‐
1821       formance penalty compared to extreme tables.
1822

PANDOC'S MARKDOWN

1824       Pandoc understands an extended and slightly  revised  version  of  John
1825       Gruber's  Markdown  syntax.   This document explains the syntax, noting
1826       differences from standard Markdown.  Except where noted, these  differ‐
1827       ences  can be suppressed by using the markdown_strict format instead of
1828       markdown.  Extensions can be enabled or disabled to specify the  behav‐
1829       ior  more  granularly.   They are described in the following.  See also
1830       Extensions above, for extensions that work also on other formats.
1831
1832   Philosophy
1833       Markdown is designed to be easy to write, and, even  more  importantly,
1834       easy to read:
1835
1836              A  Markdown-formatted  document  should be publishable as-is, as
1837              plain text, without looking like it's been marked up  with  tags
1838              or formatting instructions.  -- John Gruber
1839
1840       This  principle  has  guided  pandoc's  decisions in finding syntax for
1841       tables, footnotes, and other extensions.
1842
1843       There is, however, one respect in which  pandoc's  aims  are  different
1844       from  the  original  aims of Markdown.  Whereas Markdown was originally
1845       designed with HTML generation in mind, pandoc is designed for  multiple
1846       output  formats.   Thus, while pandoc allows the embedding of raw HTML,
1847       it discourages it, and provides other, non-HTMLish ways of representing
1848       important document elements like definition lists, tables, mathematics,
1849       and footnotes.
1850
1851   Paragraphs
1852       A paragraph is one or more lines of text followed by one or more  blank
1853       lines.   Newlines  are  treated as spaces, so you can reflow your para‐
1854       graphs as you like.  If you need a hard line break,  put  two  or  more
1855       spaces at the end of a line.
1856
1857   Extension: escaped_line_breaks
1858       A  backslash followed by a newline is also a hard line break.  Note: in
1859       multiline and grid table cells, this is the only way to create  a  hard
1860       line break, since trailing spaces in the cells are ignored.
1861
1862   Headers
1863       There are two kinds of headers: Setext and ATX.
1864
1865   Setext-style headers
1866       A  setext-style  header  is a line of text "underlined" with a row of =
1867       signs (for a level one header) or - signs (for a level two header):
1868
1869              A level-one header
1870              ==================
1871
1872              A level-two header
1873              ------------------
1874
1875       The header text can contain inline formatting, such  as  emphasis  (see
1876       Inline formatting, below).
1877
1878   ATX-style headers
1879       An  ATX-style header consists of one to six # signs and a line of text,
1880       optionally followed by any number of # signs.  The number of # signs at
1881       the beginning of the line is the header level:
1882
1883              ## A level-two header
1884
1885              ### A level-three header ###
1886
1887       As with setext-style headers, the header text can contain formatting:
1888
1889              # A level-one header with a [link](/url) and *emphasis*
1890
1891   Extension: blank_before_header
1892       Standard Markdown syntax does not require a blank line before a header.
1893       Pandoc does require this (except, of course, at the  beginning  of  the
1894       document).   The  reason for the requirement is that it is all too easy
1895       for a # to end up at the beginning  of  a  line  by  accident  (perhaps
1896       through line wrapping).  Consider, for example:
1897
1898              I like several of their flavors of ice cream:
1899              #22, for example, and #5.
1900
1901   Extension: space_in_atx_header
1902       Many  Markdown implementations do not require a space between the open‐
1903       ing #s of an ATX header and the header text, so that #5 bolt and #hash‐
1904       tag  count  as  headers.   With this extension, pandoc does require the
1905       space.
1906
1907   Header identifiers
1908       See also the auto_identifiers extension above.
1909
1910   Extension: header_attributes
1911       Headers can be assigned attributes using this syntax at the end of  the
1912       line containing the header text:
1913
1914              {#identifier .class .class key=value key=value}
1915
1916       Thus, for example, the following headers will all be assigned the iden‐
1917       tifier foo:
1918
1919              # My header {#foo}
1920
1921              ## My header ##    {#foo}
1922
1923              My other header   {#foo}
1924              ---------------
1925
1926       (This syntax is compatible with PHP Markdown Extra.)
1927
1928       Note that  although  this  syntax  allows  assignment  of  classes  and
1929       key/value  attributes, writers generally don't use all of this informa‐
1930       tion.  Identifiers, classes, and key/value attributes are used in  HTML
1931       and  HTML-based  formats  such as EPUB and slidy.  Identifiers are used
1932       for labels and link anchors in the LaTeX, ConTeXt, Textile,  and  Asci‐
1933       iDoc writers.
1934
1935       Headers  with the class unnumbered will not be numbered, even if --num‐
1936       ber-sections is specified.  A single hyphen (-) in an attribute context
1937       is  equivalent to .unnumbered, and preferable in non-English documents.
1938       So,
1939
1940              # My header {-}
1941
1942       is just the same as
1943
1944              # My header {.unnumbered}
1945
1946   Extension: implicit_header_references
1947       Pandoc behaves as if reference links have been defined for each header.
1948       So, to link to a header
1949
1950              # Header identifiers in HTML
1951
1952       you can simply write
1953
1954              [Header identifiers in HTML]
1955
1956       or
1957
1958              [Header identifiers in HTML][]
1959
1960       or
1961
1962              [the section on header identifiers][header identifiers in
1963              HTML]
1964
1965       instead of giving the identifier explicitly:
1966
1967              [Header identifiers in HTML](#header-identifiers-in-html)
1968
1969       If  there  are  multiple headers with identical text, the corresponding
1970       reference will link to the first one only, and you  will  need  to  use
1971       explicit links to link to the others, as described above.
1972
1973       Like regular reference links, these references are case-insensitive.
1974
1975       Explicit  link reference definitions always take priority over implicit
1976       header references.  So, in the following example, the link  will  point
1977       to bar, not to #foo:
1978
1979              # Foo
1980
1981              [foo]: bar
1982
1983              See [foo]
1984
1985   Block quotations
1986       Markdown  uses  email  conventions for quoting blocks of text.  A block
1987       quotation is one or more paragraphs or other block  elements  (such  as
1988       lists  or  headers),  with  each  line preceded by a > character and an
1989       optional space.  (The > need not start  at  the  left  margin,  but  it
1990       should not be indented more than three spaces.)
1991
1992              > This is a block quote. This
1993              > paragraph has two lines.
1994              >
1995              > 1. This is a list inside a block quote.
1996              > 2. Second item.
1997
1998       A "lazy" form, which requires the > character only on the first line of
1999       each block, is also allowed:
2000
2001              > This is a block quote. This
2002              paragraph has two lines.
2003
2004              > 1. This is a list inside a block quote.
2005              2. Second item.
2006
2007       Among the block elements that can be contained in  a  block  quote  are
2008       other block quotes.  That is, block quotes can be nested:
2009
2010              > This is a block quote.
2011              >
2012              > > A block quote within a block quote.
2013
2014       If the > character is followed by an optional space, that space will be
2015       considered part of the block quote marker and not part of the  indenta‐
2016       tion  of  the contents.  Thus, to put an indented code block in a block
2017       quote, you need five spaces after the >:
2018
2019              >     code
2020
2021   Extension: blank_before_blockquote
2022       Standard Markdown syntax does not require a blank line before  a  block
2023       quote.   Pandoc  does require this (except, of course, at the beginning
2024       of the document).  The reason for the requirement is that it is all too
2025       easy  for a > to end up at the beginning of a line by accident (perhaps
2026       through line wrapping).  So, unless the markdown_strict format is used,
2027       the following does not produce a nested block quote in pandoc:
2028
2029              > This is a block quote.
2030              >> Nested.
2031
2032   Verbatim (code) blocks
2033   Indented code blocks
2034       A  block of text indented four spaces (or one tab) is treated as verba‐
2035       tim text: that is, special characters do not  trigger  special  format‐
2036       ting, and all spaces and line breaks are preserved.  For example,
2037
2038                  if (a > 3) {
2039                    moveShip(5 * gravity, DOWN);
2040                  }
2041
2042       The  initial (four space or one tab) indentation is not considered part
2043       of the verbatim text, and is removed in the output.
2044
2045       Note: blank lines in the verbatim text need not begin with four spaces.
2046
2047   Fenced code blocks
2048   Extension: fenced_code_blocks
2049       In addition to standard indented code blocks,  pandoc  supports  fenced
2050       code  blocks.   These  begin with a row of three or more tildes (~) and
2051       end with a row of tildes that must be at least as long as the  starting
2052       row.   Everything  between these lines is treated as code.  No indenta‐
2053       tion is necessary:
2054
2055              ~~~~~~~
2056              if (a > 3) {
2057                moveShip(5 * gravity, DOWN);
2058              }
2059              ~~~~~~~
2060
2061       Like regular code blocks, fenced code blocks  must  be  separated  from
2062       surrounding text by blank lines.
2063
2064       If  the  code  itself contains a row of tildes or backticks, just use a
2065       longer row of tildes or backticks at the start and end:
2066
2067              ~~~~~~~~~~~~~~~~
2068              ~~~~~~~~~~
2069              code including tildes
2070              ~~~~~~~~~~
2071              ~~~~~~~~~~~~~~~~
2072
2073   Extension: backtick_code_blocks
2074       Same as fenced_code_blocks, but uses backticks (`)  instead  of  tildes
2075       (~).
2076
2077   Extension: fenced_code_attributes
2078       Optionally,  you may attach attributes to fenced or backtick code block
2079       using this syntax:
2080
2081              ~~~~ {#mycode .haskell .numberLines startFrom="100"}
2082              qsort []     = []
2083              qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
2084                             qsort (filter (>= x) xs)
2085              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2086
2087       Here mycode is an identifier, haskell and numberLines are classes,  and
2088       startFrom  is an attribute with value 100.  Some output formats can use
2089       this information to do syntax highlighting.  Currently, the only output
2090       formats  that uses this information are HTML, LaTeX, Docx, Ms, and Pow‐
2091       erPoint.  If highlighting is supported for your output format and  lan‐
2092       guage, then the code block above will appear highlighted, with numbered
2093       lines.  (To see which languages are supported, type pandoc --list-high‐
2094       light-languages.)  Otherwise,  the code block above will appear as fol‐
2095       lows:
2096
2097              <pre id="mycode" class="haskell numberLines" startFrom="100">
2098                <code>
2099                ...
2100                </code>
2101              </pre>
2102
2103       The numberLines (or number-lines) class will cause  the  lines  of  the
2104       code  block  to be numbered, starting with 1 or the value of the start‐
2105       From attribute.  The lineAnchors (or line-anchors) class will cause the
2106       lines to be clickable anchors in HTML output.
2107
2108       A  shortcut  form  can  also be used for specifying the language of the
2109       code block:
2110
2111              ```haskell
2112              qsort [] = []
2113              ```
2114
2115       This is equivalent to:
2116
2117              ``` {.haskell}
2118              qsort [] = []
2119              ```
2120
2121       If the fenced_code_attributes extension is disabled, but input contains
2122       class  attribute(s)  for the code block, the first class attribute will
2123       be printed after the opening fence as a bare word.
2124
2125       To prevent all highlighting, use the --no-highlight flag.  To  set  the
2126       highlighting  style,  use  --highlight-style.   For more information on
2127       highlighting, see Syntax highlighting, below.
2128
2129   Line blocks
2130   Extension: line_blocks
2131       A line block is a sequence of lines beginning with a vertical  bar  (|)
2132       followed  by a space.  The division into lines will be preserved in the
2133       output, as will any leading spaces; otherwise, the lines will  be  for‐
2134       matted as Markdown.  This is useful for verse and addresses:
2135
2136              | The limerick packs laughs anatomical
2137              | In space that is quite economical.
2138              |    But the good ones I've seen
2139              |    So seldom are clean
2140              | And the clean ones so seldom are comical
2141
2142              | 200 Main St.
2143              | Berkeley, CA 94718
2144
2145       The lines can be hard-wrapped if needed, but the continuation line must
2146       begin with a space.
2147
2148              | The Right Honorable Most Venerable and Righteous Samuel L.
2149                Constable, Jr.
2150              | 200 Main St.
2151              | Berkeley, CA 94718
2152
2153       This syntax is borrowed from reStructuredText.
2154
2155   Lists
2156   Bullet lists
2157       A bullet list is a list of bulleted list items.  A bulleted  list  item
2158       begins with a bullet (*, +, or -).  Here is a simple example:
2159
2160              * one
2161              * two
2162              * three
2163
2164       This  will  produce  a  "compact" list.  If you want a "loose" list, in
2165       which each item is formatted as a paragraph,  put  spaces  between  the
2166       items:
2167
2168              * one
2169
2170              * two
2171
2172              * three
2173
2174       The  bullets  need  not  be  flush  with  the  left margin; they may be
2175       indented one, two, or three spaces.  The bullet  must  be  followed  by
2176       whitespace.
2177
2178       List  items look best if subsequent lines are flush with the first line
2179       (after the bullet):
2180
2181              * here is my first
2182                list item.
2183              * and my second.
2184
2185       But Markdown also allows a "lazy" format:
2186
2187              * here is my first
2188              list item.
2189              * and my second.
2190
2191   Block content in list items
2192       A list item may contain multiple paragraphs and other block-level  con‐
2193       tent.   However, subsequent paragraphs must be preceded by a blank line
2194       and indented to line up with the first non-space content after the list
2195       marker.
2196
2197                * First paragraph.
2198
2199                  Continued.
2200
2201                * Second paragraph. With a code block, which must be indented
2202                  eight spaces:
2203
2204                      { code }
2205
2206       Exception:  if  the  list marker is followed by an indented code block,
2207       which must begin 5 spaces after the list marker, then subsequent  para‐
2208       graphs  must  begin  two  columns  after the last character of the list
2209       marker:
2210
2211              *     code
2212
2213                continuation paragraph
2214
2215       List items may include other lists.  In this case the  preceding  blank
2216       line is optional.  The nested list must be indented to line up with the
2217       first non-space character after the list marker of the containing  list
2218       item.
2219
2220              * fruits
2221                + apples
2222                  - macintosh
2223                  - red delicious
2224                + pears
2225                + peaches
2226              * vegetables
2227                + broccoli
2228                + chard
2229
2230       As  noted  above,  Markdown  allows  you  to write list items "lazily,"
2231       instead of indenting continuation lines.  However, if there are  multi‐
2232       ple  paragraphs  or other blocks in a list item, the first line of each
2233       must be indented.
2234
2235              + A lazy, lazy, list
2236              item.
2237
2238              + Another one; this looks
2239              bad but is legal.
2240
2241                  Second paragraph of second
2242              list item.
2243
2244   Ordered lists
2245       Ordered lists work just like bulleted  lists,  except  that  the  items
2246       begin with enumerators rather than bullets.
2247
2248       In  standard  Markdown,  enumerators  are decimal numbers followed by a
2249       period and a space.  The numbers themselves are ignored, so there is no
2250       difference between this list:
2251
2252              1.  one
2253              2.  two
2254              3.  three
2255
2256       and this one:
2257
2258              5.  one
2259              7.  two
2260              1.  three
2261
2262   Extension: fancy_lists
2263       Unlike standard Markdown, pandoc allows ordered list items to be marked
2264       with uppercase and lowercase letters and roman numerals, in addition to
2265       Arabic  numerals.   List markers may be enclosed in parentheses or fol‐
2266       lowed by a single right-parentheses or period.  They must be  separated
2267       from  the  text  that  follows  by at least one space, and, if the list
2268       marker is a capital letter with a period, by at least two spaces.
2269
2270       The fancy_lists extension also allows '#' to be used as an ordered list
2271       marker in place of a numeral:
2272
2273              #. one
2274              #. two
2275
2276   Extension: startnum
2277       Pandoc  also pays attention to the type of list marker used, and to the
2278       starting number, and both of these are preserved where possible in  the
2279       output format.  Thus, the following yields a list with numbers followed
2280       by a single parenthesis, starting with 9, and a sublist with  lowercase
2281       roman numerals:
2282
2283               9)  Ninth
2284              10)  Tenth
2285              11)  Eleventh
2286                     i. subone
2287                    ii. subtwo
2288                   iii. subthree
2289
2290       Pandoc  will start a new list each time a different type of list marker
2291       is used.  So, the following will create three lists:
2292
2293              (2) Two
2294              (5) Three
2295              1.  Four
2296              *   Five
2297
2298       If default list markers are desired, use #.:
2299
2300              #.  one
2301              #.  two
2302              #.  three
2303
2304   Definition lists
2305   Extension: definition_lists
2306       Pandoc supports definition lists, using  the  syntax  of  PHP  Markdown
2307       Extra with some extensions.
2308
2309              Term 1
2310
2311              :   Definition 1
2312
2313              Term 2 with *inline markup*
2314
2315              :   Definition 2
2316
2317                      { some code, part of Definition 2 }
2318
2319                  Third paragraph of definition 2.
2320
2321       Each  term  must fit on one line, which may optionally be followed by a
2322       blank line, and must be followed by one or more definitions.  A defini‐
2323       tion  begins  with  a  colon or tilde, which may be indented one or two
2324       spaces.
2325
2326       A term may have multiple definitions, and each definition  may  consist
2327       of one or more block elements (paragraph, code block, list, etc.), each
2328       indented four spaces or one tab  stop.   The  body  of  the  definition
2329       (including  the  first  line,  aside from the colon or tilde) should be
2330       indented four spaces.  However, as with other Markdown lists,  you  can
2331       "lazily"  omit  indentation  except  at the beginning of a paragraph or
2332       other block element:
2333
2334              Term 1
2335
2336              :   Definition
2337              with lazy continuation.
2338
2339                  Second paragraph of the definition.
2340
2341       If you leave space before the definition (as in the example above), the
2342       text  of the definition will be treated as a paragraph.  In some output
2343       formats, this will mean greater spacing between term/definition  pairs.
2344       For  a  more compact definition list, omit the space before the defini‐
2345       tion:
2346
2347              Term 1
2348                ~ Definition 1
2349
2350              Term 2
2351                ~ Definition 2a
2352                ~ Definition 2b
2353
2354       Note that space between items in a definition  list  is  required.   (A
2355       variant  that loosens this requirement, but disallows "lazy" hard wrap‐
2356       ping, can be activated with  compact_definition_lists:  see  Non-pandoc
2357       extensions, below.)
2358
2359   Numbered example lists
2360   Extension: example_lists
2361       The  special  list marker @ can be used for sequentially numbered exam‐
2362       ples.  The first list item with a @ marker will be  numbered  '1',  the
2363       next  '2',  and  so on, throughout the document.  The numbered examples
2364       need not occur in a single list; each new list using  @  will  take  up
2365       where the last stopped.  So, for example:
2366
2367              (@)  My first example will be numbered (1).
2368              (@)  My second example will be numbered (2).
2369
2370              Explanation of examples.
2371
2372              (@)  My third example will be numbered (3).
2373
2374       Numbered examples can be labeled and referred to elsewhere in the docu‐
2375       ment:
2376
2377              (@good)  This is a good example.
2378
2379              As (@good) illustrates, ...
2380
2381       The label can be any string of alphanumeric characters, underscores, or
2382       hyphens.
2383
2384       Note:  continuation paragraphs in example lists must always be indented
2385       four spaces, regardless of the length of the  list  marker.   That  is,
2386       example lists always behave as if the four_space_rule extension is set.
2387       This is because example labels tend to be long, and  indenting  content
2388       to the first non-space character after the label would be awkward.
2389
2390   Compact and loose lists
2391       Pandoc  behaves  differently  from  Markdown.pl  on  some  "edge cases"
2392       involving lists.  Consider this source:
2393
2394              +   First
2395              +   Second:
2396                  -   Fee
2397                  -   Fie
2398                  -   Foe
2399
2400              +   Third
2401
2402       Pandoc transforms this into a "compact list" (with no <p>  tags  around
2403       "First",  "Second",  or  "Third"),  while Markdown puts <p> tags around
2404       "Second" and "Third" (but not "First"),  because  of  the  blank  space
2405       around  "Third".  Pandoc follows a simple rule: if the text is followed
2406       by a blank line, it is treated as a paragraph.  Since "Second" is  fol‐
2407       lowed by a list, and not a blank line, it isn't treated as a paragraph.
2408       The fact that the list is followed  by  a  blank  line  is  irrelevant.
2409       (Note:  Pandoc  works  this way even when the markdown_strict format is
2410       specified.  This behavior is consistent with the official Markdown syn‐
2411       tax description, even though it is different from that of Markdown.pl.)
2412
2413   Ending a list
2414       What if you want to put an indented code block after a list?
2415
2416              -   item one
2417              -   item two
2418
2419                  { my code block }
2420
2421       Trouble! Here pandoc (like other Markdown implementations) will treat {
2422       my code block } as the second paragraph of item two, and not as a  code
2423       block.
2424
2425       To  "cut off" the list after item two, you can insert some non-indented
2426       content, like an HTML comment, which won't produce  visible  output  in
2427       any format:
2428
2429              -   item one
2430              -   item two
2431
2432              <!-- end of list -->
2433
2434                  { my code block }
2435
2436       You can use the same trick if you want two consecutive lists instead of
2437       one big list:
2438
2439              1.  one
2440              2.  two
2441              3.  three
2442
2443              <!-- -->
2444
2445              1.  uno
2446              2.  dos
2447              3.  tres
2448
2449   Horizontal rules
2450       A line containing a row of three or more *, -, or _ characters (option‐
2451       ally separated by spaces) produces a horizontal rule:
2452
2453              *  *  *  *
2454
2455              ---------------
2456
2457   Tables
2458       Four kinds of tables may be used.  The first three kinds presuppose the
2459       use of a fixed-width font, such as Courier.  The  fourth  kind  can  be
2460       used with proportionally spaced fonts, as it does not require lining up
2461       columns.
2462
2463   Extension: table_captions
2464       A caption may optionally be provided with all 4  kinds  of  tables  (as
2465       illustrated in the examples below).  A caption is a paragraph beginning
2466       with the string Table: (or just :), which will be stripped off.  It may
2467       appear either before or after the table.
2468
2469   Extension: simple_tables
2470       Simple tables look like this:
2471
2472                Right     Left     Center     Default
2473              -------     ------ ----------   -------
2474                   12     12        12            12
2475                  123     123       123          123
2476                    1     1          1             1
2477
2478              Table:  Demonstration of simple table syntax.
2479
2480       The  headers  and  table rows must each fit on one line.  Column align‐
2481       ments are determined by the position of the header text relative to the
2482       dashed line below it:
2483
2484       · If  the  dashed  line is flush with the header text on the right side
2485         but extends beyond it on the left, the column is right-aligned.
2486
2487       · If the dashed line is flush with the header text on the left side but
2488         extends beyond it on the right, the column is left-aligned.
2489
2490       · If  the dashed line extends beyond the header text on both sides, the
2491         column is centered.
2492
2493       · If the dashed line is flush with the header text on both  sides,  the
2494         default alignment is used (in most cases, this will be left).
2495
2496       The table must end with a blank line, or a line of dashes followed by a
2497       blank line.
2498
2499       The column headers may be omitted, provided a dashed line  is  used  to
2500       end the table.  For example:
2501
2502              -------     ------ ----------   -------
2503                   12     12        12             12
2504                  123     123       123           123
2505                    1     1          1              1
2506              -------     ------ ----------   -------
2507
2508       When headers are omitted, column alignments are determined on the basis
2509       of the first line of the table body.  So, in the tables above, the col‐
2510       umns would be right, left, center, and right aligned, respectively.
2511
2512   Extension: multiline_tables
2513       Multiline tables allow headers and table rows to span multiple lines of
2514       text (but cells that span multiple columns or rows of the table are not
2515       supported).  Here is an example:
2516
2517              -------------------------------------------------------------
2518               Centered   Default           Right Left
2519                Header    Aligned         Aligned Aligned
2520              ----------- ------- --------------- -------------------------
2521                 First    row                12.0 Example of a row that
2522                                                  spans multiple lines.
2523
2524                Second    row                 5.0 Here's another one. Note
2525                                                  the blank line between
2526                                                  rows.
2527              -------------------------------------------------------------
2528
2529              Table: Here's the caption. It, too, may span
2530              multiple lines.
2531
2532       These work like simple tables, but with the following differences:
2533
2534       · They  must begin with a row of dashes, before the header text (unless
2535         the headers are omitted).
2536
2537       · They must end with a row of dashes, then a blank line.
2538
2539       · The rows must be separated by blank lines.
2540
2541       In multiline tables, the table parser pays attention to the  widths  of
2542       the  columns, and the writers try to reproduce these relative widths in
2543       the output.  So, if you find that one of the columns is too  narrow  in
2544       the output, try widening it in the Markdown source.
2545
2546       Headers may be omitted in multiline tables as well as simple tables:
2547
2548              ----------- ------- --------------- -------------------------
2549                 First    row                12.0 Example of a row that
2550                                                  spans multiple lines.
2551
2552                Second    row                 5.0 Here's another one. Note
2553                                                  the blank line between
2554                                                  rows.
2555              ----------- ------- --------------- -------------------------
2556
2557              : Here's a multiline table without headers.
2558
2559       It  is possible for a multiline table to have just one row, but the row
2560       should be followed by a blank line (and then the  row  of  dashes  that
2561       ends the table), or the table may be interpreted as a simple table.
2562
2563   Extension: grid_tables
2564       Grid tables look like this:
2565
2566              : Sample grid table.
2567
2568              +---------------+---------------+--------------------+
2569              | Fruit         | Price         | Advantages         |
2570              +===============+===============+====================+
2571              | Bananas       | $1.34         | - built-in wrapper |
2572              |               |               | - bright color     |
2573              +---------------+---------------+--------------------+
2574              | Oranges       | $2.10         | - cures scurvy     |
2575              |               |               | - tasty            |
2576              +---------------+---------------+--------------------+
2577
2578       The  row  of  =s  separates  the header from the table body, and can be
2579       omitted for a headerless table.  The cells of grid tables  may  contain
2580       arbitrary  block  elements  (multiple  paragraphs,  code blocks, lists,
2581       etc.).  Cells that span multiple columns or  rows  are  not  supported.
2582       Grid tables can be created easily using Emacs table mode.
2583
2584       Alignments  can  be specified as with pipe tables, by putting colons at
2585       the boundaries of the separator line after the header:
2586
2587              +---------------+---------------+--------------------+
2588              | Right         | Left          | Centered           |
2589              +==============:+:==============+:==================:+
2590              | Bananas       | $1.34         | built-in wrapper   |
2591              +---------------+---------------+--------------------+
2592
2593       For headerless tables, the colons go on the top line instead:
2594
2595              +--------------:+:--------------+:------------------:+
2596              | Right         | Left          | Centered           |
2597              +---------------+---------------+--------------------+
2598
2599   Grid Table Limitations
2600       Pandoc does not support grid tables with row  spans  or  column  spans.
2601       This  means  that  neither  variable numbers of columns across rows nor
2602       variable numbers of rows across columns are supported by  Pandoc.   All
2603       grid  tables  must have the same number of columns in each row, and the
2604       same number of rows in each column.  For example, the  Docutils  sample
2605       grid tables will not render as expected with Pandoc.
2606
2607   Extension: pipe_tables
2608       Pipe tables look like this:
2609
2610              | Right | Left | Default | Center |
2611              |------:|:-----|---------|:------:|
2612              |   12  |  12  |    12   |    12  |
2613              |  123  |  123 |   123   |   123  |
2614              |    1  |    1 |     1   |     1  |
2615
2616                : Demonstration of pipe table syntax.
2617
2618       The  syntax  is  identical to PHP Markdown Extra tables.  The beginning
2619       and ending pipe characters are optional, but pipes are required between
2620       all  columns.   The  colons  indicate  column  alignment as shown.  The
2621       header cannot be omitted.  To simulate a headerless  table,  include  a
2622       header with blank cells.
2623
2624       Since  the pipes indicate column boundaries, columns need not be verti‐
2625       cally aligned, as they are in the above example.  So, this  is  a  per‐
2626       fectly legal (though ugly) pipe table:
2627
2628              fruit| price
2629              -----|-----:
2630              apple|2.05
2631              pear|1.37
2632              orange|3.09
2633
2634       The  cells of pipe tables cannot contain block elements like paragraphs
2635       and lists, and cannot span multiple lines.  If a pipe table contains  a
2636       row  whose printable content is wider than the column width (see --col‐
2637       umns), then the table will take up the full text  width  and  the  cell
2638       contents  will  wrap,  with  the relative cell widths determined by the
2639       number of dashes in the line separating the table header from the table
2640       body.   (For example ---|- would make the first column 3/4 and the sec‐
2641       ond column 1/4 of the full text width.) On the other hand, if no  lines
2642       are  wider  than  column width, then cell contents will not be wrapped,
2643       and the cells will be sized to their contents.
2644
2645       Note: pandoc also recognizes pipe tables of the following form, as  can
2646       be produced by Emacs' orgtbl-mode:
2647
2648              | One | Two   |
2649              |-----+-------|
2650              | my  | table |
2651              | is  | nice  |
2652
2653       The  difference  is that + is used instead of |.  Other orgtbl features
2654       are not supported.  In particular, to get non-default column alignment,
2655       you'll need to add colons as above.
2656
2657   Metadata blocks
2658   Extension: pandoc_title_block
2659       If the file begins with a title block
2660
2661              % title
2662              % author(s) (separated by semicolons)
2663              % date
2664
2665       it  will be parsed as bibliographic information, not regular text.  (It
2666       will be used, for example, in the title of  standalone  LaTeX  or  HTML
2667       output.)  The block may contain just a title, a title and an author, or
2668       all three elements.  If you want to include an author but no title,  or
2669       a title and a date but no author, you need a blank line:
2670
2671              %
2672              % Author
2673
2674              % My title
2675              %
2676              % June 15, 2006
2677
2678       The  title may occupy multiple lines, but continuation lines must begin
2679       with leading space, thus:
2680
2681              % My title
2682                on multiple lines
2683
2684       If a document has multiple authors, the authors may be put on  separate
2685       lines with leading space, or separated by semicolons, or both.  So, all
2686       of the following are equivalent:
2687
2688              % Author One
2689                Author Two
2690
2691              % Author One; Author Two
2692
2693              % Author One;
2694                Author Two
2695
2696       The date must fit on one line.
2697
2698       All three metadata fields may contain standard inline formatting (ital‐
2699       ics, links, footnotes, etc.).
2700
2701       Title  blocks  will  always  be parsed, but they will affect the output
2702       only when the --standalone (-s) option  is  chosen.   In  HTML  output,
2703       titles  will  appear  twice:  once  in the document head -- this is the
2704       title that will appear at the top of the window in  a  browser  --  and
2705       once  at the beginning of the document body.  The title in the document
2706       head can  have  an  optional  prefix  attached  (--title-prefix  or  -T
2707       option).   The  title  in  the body appears as an H1 element with class
2708       "title", so it can be suppressed or reformatted with CSS.  If  a  title
2709       prefix is specified with -T and no title block appears in the document,
2710       the title prefix will be used by itself as the HTML title.
2711
2712       The man page writer extracts a title,  man  page  section  number,  and
2713       other  header and footer information from the title line.  The title is
2714       assumed to be the first word on the title line,  which  may  optionally
2715       end with a (single-digit) section number in parentheses.  (There should
2716       be no space between the title and  the  parentheses.)   Anything  after
2717       this is assumed to be additional footer and header text.  A single pipe
2718       character (|) should be used to  separate  the  footer  text  from  the
2719       header text.  Thus,
2720
2721              % PANDOC(1)
2722
2723       will yield a man page with the title PANDOC and section 1.
2724
2725              % PANDOC(1) Pandoc User Manuals
2726
2727       will also have "Pandoc User Manuals" in the footer.
2728
2729              % PANDOC(1) Pandoc User Manuals | Version 4.0
2730
2731       will also have "Version 4.0" in the header.
2732
2733   Extension: yaml_metadata_block
2734       A  YAML  metadata  block is a valid YAML object, delimited by a line of
2735       three hyphens (---) at the top and a line of  three  hyphens  (---)  or
2736       three  dots  (...) at the bottom.  A YAML metadata block may occur any‐
2737       where in the document, but if it is not at the beginning,  it  must  be
2738       preceded  by  a blank line.  (Note that, because of the way pandoc con‐
2739       catenates input files when several are provided, you may also keep  the
2740       metadata  in a separate YAML file and pass it to pandoc as an argument,
2741       along with your Markdown files:
2742
2743              pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
2744
2745       Just be sure that the YAML file begins with --- and ends  with  ---  or
2746       ....)  Alternatively,  you  can  use the --metadata-file option.  Using
2747       that approach however, you cannot reference  content  (like  footnotes)
2748       from the main markdown input document.
2749
2750       Metadata  will be taken from the fields of the YAML object and added to
2751       any existing document metadata.  Metadata can contain lists and objects
2752       (nested  arbitrarily),  but  all  string scalars will be interpreted as
2753       Markdown.  Fields with names ending in an underscore will be ignored by
2754       pandoc.  (They may be given a role by external processors.) Field names
2755       must not be interpretable as YAML numbers or boolean  values  (so,  for
2756       example, yes, True, and 15 cannot be used as field names).
2757
2758       A  document  may contain multiple metadata blocks.  The metadata fields
2759       will be combined through a left-biased union: if  two  metadata  blocks
2760       attempt  to  set the same field, the value from the first block will be
2761       taken.
2762
2763       When pandoc is used with -t markdown to create a Markdown  document,  a
2764       YAML metadata block will be produced only if the -s/--standalone option
2765       is used.  All of the metadata will appear in  a  single  block  at  the
2766       beginning of the document.
2767
2768       Note  that YAML escaping rules must be followed.  Thus, for example, if
2769       a title contains a colon, it must be quoted.  The  pipe  character  (|)
2770       can  be used to begin an indented block that will be interpreted liter‐
2771       ally, without need for escaping.  This form is necessary when the field
2772       contains blank lines or block-level formatting:
2773
2774              ---
2775              title:  'This is the title: it contains a colon'
2776              author:
2777              - Author One
2778              - Author Two
2779              keywords: [nothing, nothingness]
2780              abstract: |
2781                This is the abstract.
2782
2783                It consists of two paragraphs.
2784              ...
2785
2786       Template  variables will be set automatically from the metadata.  Thus,
2787       for example, in writing HTML, the variable abstract will be set to  the
2788       HTML equivalent of the Markdown in the abstract field:
2789
2790              <p>This is the abstract.</p>
2791              <p>It consists of two paragraphs.</p>
2792
2793       Variables  can contain arbitrary YAML structures, but the template must
2794       match this structure.  The author variable  in  the  default  templates
2795       expects  a  simple  list  or string, but can be changed to support more
2796       complicated structures.  The following combination, for example,  would
2797       add an affiliation to the author if one is given:
2798
2799              ---
2800              title: The document title
2801              author:
2802              - name: Author One
2803                affiliation: University of Somewhere
2804              - name: Author Two
2805                affiliation: University of Nowhere
2806              ...
2807
2808       To  use  the  structured authors in the example above, you would need a
2809       custom template:
2810
2811              $for(author)$
2812              $if(author.name)$
2813              $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
2814              $else$
2815              $author$
2816              $endif$
2817              $endfor$
2818
2819       Raw content to include in the document's header may be specified  using
2820       header-includes;  however,  it  is important to mark up this content as
2821       raw code for a particular output format, using the raw_attribute exten‐
2822       sion), or it will be interpreted as markdown.  For example:
2823
2824              header-includes:
2825              - |
2826                ```{=latex}
2827                \let\oldsection\section
2828                \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
2829                ```
2830
2831   Backslash escapes
2832   Extension: all_symbols_escapable
2833       Except  inside  a  code  block or inline code, any punctuation or space
2834       character preceded by a backslash will be treated literally, even if it
2835       would normally indicate formatting.  Thus, for example, if one writes
2836
2837              *\*hello\**
2838
2839       one will get
2840
2841              <em>*hello*</em>
2842
2843       instead of
2844
2845              <strong>hello</strong>
2846
2847       This  rule  is  easier to remember than standard Markdown's rule, which
2848       allows only the following characters to be backslash-escaped:
2849
2850              \`*_{}[]()>#+-.!
2851
2852       (However, if the markdown_strict format is used, the standard  Markdown
2853       rule will be used.)
2854
2855       A  backslash-escaped  space  is parsed as a nonbreaking space.  It will
2856       appear in TeX output as ~ and in HTML and XML as \&#160; or \&nbsp;.
2857
2858       A backslash-escaped newline (i.e.  a backslash occurring at the end  of
2859       a  line)  is parsed as a hard line break.  It will appear in TeX output
2860       as \\ and in HTML as <br />.  This is a nice alternative to  Markdown's
2861       "invisible"  way of indicating hard line breaks using two trailing spa‐
2862       ces on a line.
2863
2864       Backslash escapes do not work in verbatim contexts.
2865
2866   Inline formatting
2867   Emphasis
2868       To emphasize some text, surround it with *s or _, like this:
2869
2870              This text is _emphasized with underscores_, and this
2871              is *emphasized with asterisks*.
2872
2873       Double * or _ produces strong emphasis:
2874
2875              This is **strong emphasis** and __with underscores__.
2876
2877       A * or _ character surrounded by spaces, or backslash-escaped, will not
2878       trigger emphasis:
2879
2880              This is * not emphasized *, and \*neither is this\*.
2881
2882   Extension: intraword_underscores
2883       Because  _  is sometimes used inside words and identifiers, pandoc does
2884       not interpret a _ surrounded by alphanumeric characters as an  emphasis
2885       marker.  If you want to emphasize just part of a word, use *:
2886
2887              feas*ible*, not feas*able*.
2888
2889   Strikeout
2890   Extension: strikeout
2891       To strikeout a section of text with a horizontal line, begin and end it
2892       with ~~.  Thus, for example,
2893
2894              This ~~is deleted text.~~
2895
2896   Superscripts and subscripts
2897   Extension: superscript, subscript
2898       Superscripts may be written by surrounding the superscripted text by  ^
2899       characters;  subscripts  may  be written by surrounding the subscripted
2900       text by ~ characters.  Thus, for example,
2901
2902              H~2~O is a liquid.  2^10^ is 1024.
2903
2904       If the superscripted or subscripted text contains spaces, these  spaces
2905       must  be  escaped  with  backslashes.   (This  is to prevent accidental
2906       superscripting and subscripting through the ordinary use of ~  and  ^.)
2907       Thus,  if  you  want  the letter P with 'a cat' in subscripts, use P~a\
2908       cat~, not P~a cat~.
2909
2910   Verbatim
2911       To make a short span of text verbatim, put it inside backticks:
2912
2913              What is the difference between `>>=` and `>>`?
2914
2915       If the verbatim text includes a backtick, use double backticks:
2916
2917              Here is a literal backtick `` ` ``.
2918
2919       (The spaces after the opening backticks and before  the  closing  back‐
2920       ticks will be ignored.)
2921
2922       The  general  rule is that a verbatim span starts with a string of con‐
2923       secutive backticks (optionally followed by a space)  and  ends  with  a
2924       string  of  the  same  number  of  backticks  (optionally preceded by a
2925       space).
2926
2927       Note that backslash-escapes (and other Markdown constructs) do not work
2928       in verbatim contexts:
2929
2930              This is a backslash followed by an asterisk: `\*`.
2931
2932   Extension: inline_code_attributes
2933       Attributes  can  be attached to verbatim text, just as with fenced code
2934       blocks:
2935
2936              `<$>`{.haskell}
2937
2938   Small caps
2939       To write small caps, use the smallcaps class:
2940
2941              [Small caps]{.smallcaps}
2942
2943       Or, without the bracketed_spans extension:
2944
2945              <span class="smallcaps">Small caps</span>
2946
2947       For compatibility with other Markdown flavors, CSS is also supported:
2948
2949              <span style="font-variant:small-caps;">Small caps</span>
2950
2951       This will work in all output formats that support small caps.
2952
2953   Math
2954   Extension: tex_math_dollars
2955       Anything between two $ characters will be treated  as  TeX  math.   The
2956       opening  $  must  have  a non-space character immediately to its right,
2957       while the closing $ must have a non-space character immediately to  its
2958       left,  and  must not be followed immediately by a digit.  Thus, $20,000
2959       and $30,000 won't parse as math.   If  for  some  reason  you  need  to
2960       enclose  text  in  literal $ characters, backslash-escape them and they
2961       won't be treated as math delimiters.
2962
2963       TeX math will be printed in all output formats.   How  it  is  rendered
2964       depends on the output format:
2965
2966       LaTeX  It  will appear verbatim surrounded by \(...\) (for inline math)
2967              or \[...\] (for display math).
2968
2969       Markdown, Emacs Org mode, ConTeXt, ZimWiki
2970              It will appear verbatim surrounded by $...$ (for inline math) or
2971              $$...$$ (for display math).
2972
2973       reStructuredText
2974              It will be rendered using an interpreted text role :math:.
2975
2976       AsciiDoc
2977              It will be rendered as latexmath:[...].
2978
2979       Texinfo
2980              It will be rendered inside a @math command.
2981
2982       roff man
2983              It will be rendered verbatim without $'s.
2984
2985       MediaWiki, DokuWiki
2986              It will be rendered inside <math> tags.
2987
2988       Textile
2989              It will be rendered inside <span class="math"> tags.
2990
2991       RTF, OpenDocument
2992              It  will be rendered, if possible, using Unicode characters, and
2993              will otherwise appear verbatim.
2994
2995       ODT    It will be rendered, if possible, using MathML.
2996
2997       DocBook
2998              If the --mathml flag is used, it will be rendered  using  MathML
2999              in an inlineequation or informalequation tag.  Otherwise it will
3000              be rendered, if possible, using Unicode characters.
3001
3002       Docx   It will be rendered using OMML math markup.
3003
3004       FictionBook2
3005              If the --webtex option is used, formulas are rendered as  images
3006              using  CodeCogs  or other compatible web service, downloaded and
3007              embedded in the e-book.  Otherwise, they will appear verbatim.
3008
3009       HTML, Slidy, DZSlides, S5, EPUB
3010              The way math is rendered in HTML will depend on the command-line
3011              options selected.  Therefore see Math rendering in HTML above.
3012
3013   Raw HTML
3014   Extension: raw_html
3015       Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
3016       ment (except verbatim contexts, where <, >, and & are interpreted  lit‐
3017       erally).   (Technically  this is not an extension, since standard Mark‐
3018       down allows it, but it has been made an extension so  that  it  can  be
3019       disabled if desired.)
3020
3021       The  raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
3022       DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile  out‐
3023       put, and suppressed in other formats.
3024
3025       In  the  CommonMark  format, if raw_html is enabled, superscripts, sub‐
3026       scripts, strikeouts and small capitals will  be  represented  as  HTML.
3027       Otherwise,  plain-text  fallbacks  will  be  used.   Note  that even if
3028       raw_html is disabled, tables will be rendered with HTML syntax if  they
3029       cannot use pipe syntax.
3030
3031   Extension: markdown_in_html_blocks
3032       Standard  Markdown  allows you to include HTML "blocks": blocks of HTML
3033       between balanced tags that are separated from the surrounding text with
3034       blank  lines,  and  start  and  end  at  the left margin.  Within these
3035       blocks, everything is interpreted as HTML, not Markdown; so (for  exam‐
3036       ple), * does not signify emphasis.
3037
3038       Pandoc behaves this way when the markdown_strict format is used; but by
3039       default, pandoc interprets material between HTML block  tags  as  Mark‐
3040       down.  Thus, for example, pandoc will turn
3041
3042              <table>
3043              <tr>
3044              <td>*one*</td>
3045              <td>[a link](http://google.com)</td>
3046              </tr>
3047              </table>
3048
3049       into
3050
3051              <table>
3052              <tr>
3053              <td><em>one</em></td>
3054              <td><a href="http://google.com">a link</a></td>
3055              </tr>
3056              </table>
3057
3058       whereas Markdown.pl will preserve it as is.
3059
3060       There  is one exception to this rule: text between <script> and <style>
3061       tags is not interpreted as Markdown.
3062
3063       This departure from standard Markdown should  make  it  easier  to  mix
3064       Markdown  with  HTML  block  elements.  For example, one can surround a
3065       block of Markdown text with <div> tags without preventing it from being
3066       interpreted as Markdown.
3067
3068   Extension: native_divs
3069       Use  native  pandoc  Div blocks for content inside <div> tags.  For the
3070       most part this should give the same output as  markdown_in_html_blocks,
3071       but  it makes it easier to write pandoc filters to manipulate groups of
3072       blocks.
3073
3074   Extension: native_spans
3075       Use native pandoc Span blocks for content inside <span> tags.  For  the
3076       most part this should give the same output as raw_html, but it makes it
3077       easier to write pandoc filters to manipulate groups of inlines.
3078
3079   Extension: raw_tex
3080       In addition to raw HTML, pandoc allows raw LaTeX, TeX, and  ConTeXt  to
3081       be  included  in a document.  Inline TeX commands will be preserved and
3082       passed unchanged to the LaTeX and ConTeXt writers.  Thus, for  example,
3083       you can use LaTeX to include BibTeX citations:
3084
3085              This result was proved in \cite{jones.1967}.
3086
3087       Note that in LaTeX environments, like
3088
3089              \begin{tabular}{|l|l|}\hline
3090              Age & Frequency \\ \hline
3091              18--25  & 15 \\
3092              26--35  & 33 \\
3093              36--45  & 22 \\ \hline
3094              \end{tabular}
3095
3096       the  material between the begin and end tags will be interpreted as raw
3097       LaTeX, not as Markdown.
3098
3099       Inline LaTeX is ignored in output formats other than  Markdown,  LaTeX,
3100       Emacs Org mode, and ConTeXt.
3101
3102   Generic raw attribute
3103   Extension: raw_attribute
3104       Inline  spans  and  fenced code blocks with a special kind of attribute
3105       will be parsed as raw content with the designated format.  For example,
3106       the following produces a raw roff ms block:
3107
3108              ```{=ms}
3109              .MYMACRO
3110              blah blah
3111              ```
3112
3113       And the following produces a raw html inline element:
3114
3115              This is `<a>html</a>`{=html}
3116
3117       This can be useful to insert raw xml into docx documents, e.g.  a page‐
3118       break:
3119
3120              ```{=openxml}
3121              <w:p>
3122                <w:r>
3123                  <w:br w:type="page"/>
3124                </w:r>
3125              </w:p>
3126              ```
3127
3128       The format name should match  the  target  format  name  (see  -t/--to,
3129       above,  for  a list, or use pandoc --list-output-formats).  Use openxml
3130       for docx output, opendocument for odt output, html5 for  epub3  output,
3131       html4  for epub2 output, and latex, beamer, ms, or html5 for pdf output
3132       (depending on what you use for --pdf-engine).
3133
3134       This extension presupposes that the relevant kind  of  inline  code  or
3135       fenced  code  block  is  enabled.   Thus,  for  example,  to  use a raw
3136       attribute with a backtick  code  block,  backtick_code_blocks  must  be
3137       enabled.
3138
3139       The raw attribute cannot be combined with regular attributes.
3140
3141   LaTeX macros
3142   Extension: latex_macros
3143       When  this  extension is enabled, pandoc will parse LaTeX macro defini‐
3144       tions and apply the resulting macros to all LaTeX math and  raw  LaTeX.
3145       So,  for  example,  the  following will work in all output formats, not
3146       just LaTeX:
3147
3148              \newcommand{\tuple}[1]{\langle #1 \rangle}
3149
3150              $\tuple{a, b, c}$
3151
3152       Note that LaTeX macros will not be applied if they occur inside  inside
3153       a raw span or block marked with the raw_attribute extension.
3154
3155       When  latex_macros  is  disabled,  the raw LaTeX and math will not have
3156       macros applied.  This is usually a better approach when you are target‐
3157       ing LaTeX or PDF.
3158
3159       Whether  or  not  latex_macros  is  enabled, the macro definitions will
3160       still be passed through as raw LaTeX.
3161
3162   Links
3163       Markdown allows links to be specified in several ways.
3164
3165   Automatic links
3166       If you enclose a URL or email  address  in  pointy  brackets,  it  will
3167       become a link:
3168
3169              <http://google.com>
3170              <sam@green.eggs.ham>
3171
3172   Inline links
3173       An  inline  link consists of the link text in square brackets, followed
3174       by the URL in parentheses.  (Optionally, the URL can be followed  by  a
3175       link title, in quotes.)
3176
3177              This is an [inline link](/url), and here's [one with
3178              a title](http://fsf.org "click here for a good time!").
3179
3180       There  can be no space between the bracketed part and the parenthesized
3181       part.  The link text can contain formatting (such as emphasis), but the
3182       title cannot.
3183
3184       Email  addresses  in inline links are not autodetected, so they have to
3185       be prefixed with mailto:
3186
3187              [Write me!](mailto:sam@green.eggs.ham)
3188
3189   Reference links
3190       An explicit reference link has two parts, the link itself and the  link
3191       definition, which may occur elsewhere in the document (either before or
3192       after the link).
3193
3194       The link consists of link text in square brackets, followed by a  label
3195       in  square brackets.  (There cannot be space between the two unless the
3196       spaced_reference_links extension is enabled.) The link definition  con‐
3197       sists of the bracketed label, followed by a colon and a space, followed
3198       by the URL, and optionally (after a  space)  a  link  title  either  in
3199       quotes  or  in parentheses.  The label must not be parseable as a cita‐
3200       tion (assuming the citations  extension  is  enabled):  citations  take
3201       precedence over link labels.
3202
3203       Here are some examples:
3204
3205              [my label 1]: /foo/bar.html  "My title, optional"
3206              [my label 2]: /foo
3207              [my label 3]: http://fsf.org (The free software foundation)
3208              [my label 4]: /bar#special  'A title in single quotes'
3209
3210       The URL may optionally be surrounded by angle brackets:
3211
3212              [my label 5]: <http://foo.bar.baz>
3213
3214       The title may go on the next line:
3215
3216              [my label 3]: http://fsf.org
3217                "The free software foundation"
3218
3219       Note that link labels are not case sensitive.  So, this will work:
3220
3221              Here is [my link][FOO]
3222
3223              [Foo]: /bar/baz
3224
3225       In an implicit reference link, the second pair of brackets is empty:
3226
3227              See [my website][].
3228
3229              [my website]: http://foo.bar.baz
3230
3231       Note: In Markdown.pl and most other Markdown implementations, reference
3232       link definitions cannot occur in  nested  constructions  such  as  list
3233       items  or  block  quotes.  Pandoc lifts this arbitrary seeming restric‐
3234       tion.  So the following is fine in pandoc, though  not  in  most  other
3235       implementations:
3236
3237              > My block [quote].
3238              >
3239              > [quote]: /foo
3240
3241   Extension: shortcut_reference_links
3242       In  a shortcut reference link, the second pair of brackets may be omit‐
3243       ted entirely:
3244
3245              See [my website].
3246
3247              [my website]: http://foo.bar.baz
3248
3249   Internal links
3250       To link to another section of the same document, use the  automatically
3251       generated identifier (see Header identifiers).  For example:
3252
3253              See the [Introduction](#introduction).
3254
3255       or
3256
3257              See the [Introduction].
3258
3259              [Introduction]: #introduction
3260
3261       Internal links are currently supported for HTML formats (including HTML
3262       slide shows and EPUB), LaTeX, and ConTeXt.
3263
3264   Images
3265       A link immediately preceded by a ! will be treated as  an  image.   The
3266       link text will be used as the image's alt text:
3267
3268              ![la lune](lalune.jpg "Voyage to the moon")
3269
3270              ![movie reel]
3271
3272              [movie reel]: movie.gif
3273
3274   Extension: implicit_figures
3275       An  image  with  nonempty alt text, occurring by itself in a paragraph,
3276       will be rendered as a figure with a caption.  The image's alt text will
3277       be used as the caption.
3278
3279              ![This is the caption](/url/of/image.png)
3280
3281       How this is rendered depends on the output format.  Some output formats
3282       (e.g.  RTF) do not yet support figures.  In those formats, you'll  just
3283       get an image in a paragraph by itself, with no caption.
3284
3285       If  you  just want a regular inline image, just make sure it is not the
3286       only thing in the paragraph.  One way to do this is to  insert  a  non‐
3287       breaking space after the image:
3288
3289              ![This image won't be a figure](/url/of/image.png)\
3290
3291       Note  that  in reveal.js slide shows, an image in a paragraph by itself
3292       that has the stretch class will fill the screen, and  the  caption  and
3293       figure tags will be omitted.
3294
3295   Extension: link_attributes
3296       Attributes can be set on links and images:
3297
3298              An inline ![image](foo.jpg){#id .class width=30 height=20px}
3299              and a reference ![image][ref] with attributes.
3300
3301              [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
3302
3303       (This  syntax  is  compatible with PHP Markdown Extra when only #id and
3304       .class are used.)
3305
3306       For HTML and EPUB, all attributes except width and height (but  includ‐
3307       ing  srcset  and  sizes)  are  passed through as is.  The other writers
3308       ignore attributes that are not supported by their output format.
3309
3310       The width and height attributes on images are treated specially.   When
3311       used without a unit, the unit is assumed to be pixels.  However, any of
3312       the following unit identifiers can be used: px, cm, mm, in, inch and %.
3313       There  must  not  be  any  spaces between the number and the unit.  For
3314       example:
3315
3316              ![](file.jpg){ width=50% }
3317
3318       · Dimensions are converted to inches for output in  page-based  formats
3319         like  LaTeX.   Dimensions  are  converted  to  pixels  for  output in
3320         HTML-like formats.  Use the --dpi option to  specify  the  number  of
3321         pixels per inch.  The default is 96dpi.
3322
3323       · The  % unit is generally relative to some available space.  For exam‐
3324         ple the above example will render to the following.
3325
3326         · HTML: <img href="file.jpg" style="width: 50%;" />
3327
3328         · LaTeX:            \includegraphics[width=0.5\textwidth,height=\tex‐
3329           theight]{file.jpg}  (If you're using a custom template, you need to
3330           configure graphicx as in the default template.)
3331
3332         · ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
3333
3334       · Some output formats have a notion of a class (ConTeXt)  or  a  unique
3335         identifier (LaTeX \caption), or both (HTML).
3336
3337       · When  no width or height attributes are specified, the fallback is to
3338         look at the image resolution and the dpi  metadata  embedded  in  the
3339         image file.
3340
3341   Divs and Spans
3342       Using  the  native_divs  and  native_spans extensions (see above), HTML
3343       syntax can be used as part of markdown to create native  Div  and  Span
3344       elements in the pandoc AST (as opposed to raw HTML).  However, there is
3345       also nicer syntax available:
3346
3347   Extension: fenced_divs
3348       Allow special fenced syntax for native Div blocks.  A Div starts with a
3349       fence   containing   at   least  three  consecutive  colons  plus  some
3350       attributes.  The attributes  may  optionally  be  followed  by  another
3351       string  of  consecutive  colons.  The attribute syntax is exactly as in
3352       fenced code blocks (see Extension:  fenced_code_attributes).   As  with
3353       fenced  code blocks, one can use either attributes in curly braces or a
3354       single unbraced word, which will be treated as a class name.   The  Div
3355       ends  with  another line containing a string of at least three consecu‐
3356       tive colons.  The fenced Div should be separated by  blank  lines  from
3357       preceding and following blocks.
3358
3359       Example:
3360
3361              ::::: {#special .sidebar}
3362              Here is a paragraph.
3363
3364              And another.
3365              :::::
3366
3367       Fenced  divs  can  be nested.  Opening fences are distinguished because
3368       they must have attributes:
3369
3370              ::: Warning ::::::
3371              This is a warning.
3372
3373              ::: Danger
3374              This is a warning within a warning.
3375              :::
3376              ::::::::::::::::::
3377
3378       Fences without attributes  are  always  closing  fences.   Unlike  with
3379       fenced  code blocks, the number of colons in the closing fence need not
3380       match the number in the opening fence.  However, it can be helpful  for
3381       visual clarity to use fences of different lengths to distinguish nested
3382       divs from their parents.
3383
3384   Extension: bracketed_spans
3385       A bracketed sequence of inlines, as one would use to begin a link, will
3386       be  treated  as a Span with attributes if it is followed immediately by
3387       attributes:
3388
3389              [This is *some text*]{.class key="val"}
3390
3391   Footnotes
3392   Extension: footnotes
3393       Pandoc's Markdown allows footnotes, using the following syntax:
3394
3395              Here is a footnote reference,[^1] and another.[^longnote]
3396
3397              [^1]: Here is the footnote.
3398
3399              [^longnote]: Here's one with multiple blocks.
3400
3401                  Subsequent paragraphs are indented to show that they
3402              belong to the previous footnote.
3403
3404                      { some.code }
3405
3406                  The whole paragraph can be indented, or just the first
3407                  line.  In this way, multi-paragraph footnotes work like
3408                  multi-paragraph list items.
3409
3410              This paragraph won't be part of the note, because it
3411              isn't indented.
3412
3413       The identifiers in footnote references may not contain spaces, tabs, or
3414       newlines.   These  identifiers  are used only to correlate the footnote
3415       reference with the note itself; in the output, footnotes will  be  num‐
3416       bered sequentially.
3417
3418       The footnotes themselves need not be placed at the end of the document.
3419       They may appear anywhere except inside  other  block  elements  (lists,
3420       block  quotes,  tables,  etc.).  Each footnote should be separated from
3421       surrounding content (including other footnotes) by blank lines.
3422
3423   Extension: inline_notes
3424       Inline footnotes are also allowed (though, unlike regular  notes,  they
3425       cannot contain multiple paragraphs).  The syntax is as follows:
3426
3427              Here is an inline note.^[Inlines notes are easier to write, since
3428              you don't have to pick an identifier and move down to type the
3429              note.]
3430
3431       Inline and regular footnotes may be mixed freely.
3432
3433   Citations
3434   Extension: citations
3435       Using  an  external  filter,  pandoc-citeproc, pandoc can automatically
3436       generate citations and a bibliography in a  number  of  styles.   Basic
3437       usage is
3438
3439              pandoc --filter pandoc-citeproc myinput.txt
3440
3441       In  order  to use this feature, you will need to specify a bibliography
3442       file using the bibliography metadata field in a YAML metadata  section,
3443       or  --bibliography  command  line  argument.   You  can supply multiple
3444       --bibliography arguments or set bibliography  metadata  field  to  YAML
3445       array,  if you want to use multiple bibliography files.  The bibliogra‐
3446       phy may have any of these formats:
3447
3448       Format        File extension
3449       ─────────────────────────────
3450       BibLaTeX      .bib
3451       BibTeX        .bibtex
3452       Copac         .copac
3453       CSL JSON      .json
3454       CSL YAML      .yaml
3455       EndNote       .enl
3456       EndNote XML   .xml
3457       ISI           .wos
3458       MEDLINE       .medline
3459       MODS          .mods
3460       RIS           .ris
3461
3462       Note that .bib can be used with both BibTeX  and  BibLaTeX  files;  use
3463       .bibtex to force BibTeX.
3464
3465       Note that pandoc-citeproc --bib2json and pandoc-citeproc --bib2yaml can
3466       produce .json and .yaml files from any of the supported formats.
3467
3468       In-field markup: In  BibTeX  and  BibLaTeX  databases,  pandoc-citeproc
3469       parses  a  subset  of LaTeX markup; in CSL YAML databases, pandoc Mark‐
3470       down; and in CSL JSON databases, an HTML-like markup:
3471
3472       <i>...</i>
3473              italics
3474
3475       <b>...</b>
3476              bold
3477
3478       <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
3479              small capitals
3480
3481       <sub>...</sub>
3482              subscript
3483
3484       <sup>...</sup>
3485              superscript
3486
3487       <span class="nocase">...</span>
3488              prevent a phrase from being capitalized as title case
3489
3490       pandoc-citeproc -j and -y interconvert the CSL JSON and CSL  YAML  for‐
3491       mats as far as possible.
3492
3493       As  an alternative to specifying a bibliography file using --bibliogra‐
3494       phy or the YAML metadata field bibliography, you can include the  cita‐
3495       tion data directly in the references field of the document's YAML meta‐
3496       data.  The field should contain an array  of  YAML-encoded  references,
3497       for example:
3498
3499              ---
3500              references:
3501              - type: article-journal
3502                id: WatsonCrick1953
3503                author:
3504                - family: Watson
3505                  given: J. D.
3506                - family: Crick
3507                  given: F. H. C.
3508                issued:
3509                  date-parts:
3510                  - - 1953
3511                    - 4
3512                    - 25
3513                title: 'Molecular structure of nucleic acids: a structure for deoxyribose
3514                  nucleic acid'
3515                title-short: Molecular structure of nucleic acids
3516                container-title: Nature
3517                volume: 171
3518                issue: 4356
3519                page: 737-738
3520                DOI: 10.1038/171737a0
3521                URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
3522                language: en-GB
3523              ...
3524
3525       (pandoc-citeproc  --bib2yaml can produce these from a bibliography file
3526       in one of the supported formats.)
3527
3528       Citations and references can be formatted using any style supported  by
3529       the  Citation  Style  Language,  listed in the Zotero Style Repository.
3530       These files are specified using the --csl option or  the  csl  metadata
3531       field.   By  default,  pandoc-citeproc  will  use the Chicago Manual of
3532       Style author-date format.  The CSL project provides further information
3533       on finding and editing styles.
3534
3535       To  make  your  citations  hyperlinks to the corresponding bibliography
3536       entries, add link-citations: true to your YAML metadata.
3537
3538       Citations go inside square brackets and are  separated  by  semicolons.
3539       Each  citation  must have a key, composed of '@' + the citation identi‐
3540       fier from the database, and may optionally have a  prefix,  a  locator,
3541       and  a suffix.  The citation key must begin with a letter, digit, or _,
3542       and may contain alphanumerics, _, and internal  punctuation  characters
3543       (:.#$%&-+?<>~/).  Here are some examples:
3544
3545              Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
3546
3547              Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
3548
3549              Blah blah [@smith04; @doe99].
3550
3551       pandoc-citeproc  detects locator terms in the CSL locale files.  Either
3552       abbreviated or unabbreviated forms are accepted.  In the en-US  locale,
3553       locator  terms  can  be  written in either singular or plural forms, as
3554       book, bk./bks.;  chapter,  chap./chaps.;  column,  col./cols.;  figure,
3555       fig./figs.;  folio,  fol./fols.;  number, no./nos.; line, l./ll.; note,
3556       n./nn.; opus, op./opp.; page, p./pp.;  paragraph,  para./paras.;  part,
3557       pt./pts.;  section,  sec./secs.;  sub verbo, s.v./s.vv.; verse, v./vv.;
3558       volume, vol./vols.; ¶/¶¶; §/§§.  If no locator term is used, "page"  is
3559       assumed.
3560
3561       pandoc-citeproc will use heuristics to distinguish the locator from the
3562       suffix.  In complex cases, the locator can be enclosed in curly  braces
3563       (using pandoc-citeproc 0.15 and higher only):
3564
3565              [@smith{ii, A, D-Z}, with a suffix]
3566              [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
3567
3568       A  minus  sign  (-) before the @ will suppress mention of the author in
3569       the citation.  This can be useful when the author is already  mentioned
3570       in the text:
3571
3572              Smith says blah [-@smith04].
3573
3574       You can also write an in-text citation, as follows:
3575
3576              @smith04 says blah.
3577
3578              @smith04 [p. 33] says blah.
3579
3580       If  the  style  calls for a list of works cited, it will be placed in a
3581       div with id refs, if one exists:
3582
3583              ::: #refs
3584              :::
3585
3586       Otherwise, it will be placed at the end of the document.  Generation of
3587       the  bibliography  can  be suppressed by setting suppress-bibliography:
3588       true in the YAML metadata.
3589
3590       If you wish the bibliography to have a section header, you can set ref‐
3591       erence-section-title  in  the metadata, or put the header at the begin‐
3592       ning of the div with id refs (if you are using it) or  at  the  end  of
3593       your document:
3594
3595              last paragraph...
3596
3597              # References
3598
3599       The  bibliography  will  be  inserted after this header.  Note that the
3600       unnumbered class will be added to this header, so that the section will
3601       not be numbered.
3602
3603       If  you want to include items in the bibliography without actually cit‐
3604       ing them in the body text, you can define a dummy nocite metadata field
3605       and put the citations there:
3606
3607              ---
3608              nocite: |
3609                @item1, @item2
3610              ...
3611
3612              @item3
3613
3614       In  this  example, the document will contain a citation for item3 only,
3615       but the bibliography will contain entries for item1, item2, and item3.
3616
3617       It is possible to create a bibliography with all the citations, whether
3618       or not they appear in the document, by using a wildcard:
3619
3620              ---
3621              nocite: |
3622                @*
3623              ...
3624
3625       For  LaTeX  output,  you  can also use natbib or biblatex to render the
3626       bibliography.  In order to do so, specify bibliography  files  as  out‐
3627       lined  above, and add --natbib or --biblatex argument to pandoc invoca‐
3628       tion.  Bear in mind that bibliography files have to  be  in  respective
3629       format (either BibTeX or BibLaTeX).
3630
3631       For more information, see the pandoc-citeproc man page.
3632
3633   Non-pandoc extensions
3634       The  following Markdown syntax extensions are not enabled by default in
3635       pandoc, but may be enabled by adding +EXTENSION  to  the  format  name,
3636       where EXTENSION is the name of the extension.  Thus, for example, mark‐
3637       down+hard_line_breaks is Markdown with hard line breaks.
3638
3639   Extension: old_dashes
3640       Selects the pandoc <= 1.8.2.1 behavior  for  parsing  smart  dashes:  -
3641       before a numeral is an en-dash, and -- is an em-dash.  This option only
3642       has an effect if smart is enabled.  It is  selected  automatically  for
3643       textile input.
3644
3645   Extension: angle_brackets_escapable
3646       Allow  <  and  > to be backslash-escaped, as they can be in GitHub fla‐
3647       vored Markdown but not original Markdown.  This is implied by  pandoc's
3648       default all_symbols_escapable.
3649
3650   Extension: lists_without_preceding_blankline
3651       Allow  a  list  to  occur  right after a paragraph, with no intervening
3652       blank space.
3653
3654   Extension: four_space_rule
3655       Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
3656       ces indent are needed for list item continuation paragraphs.
3657
3658   Extension: spaced_reference_links
3659       Allow  whitespace  between  the two components of a reference link, for
3660       example,
3661
3662              [foo] [bar].
3663
3664   Extension: hard_line_breaks
3665       Causes all newlines within a paragraph to be interpreted as  hard  line
3666       breaks instead of spaces.
3667
3668   Extension: ignore_line_breaks
3669       Causes  newlines  within  a  paragraph to be ignored, rather than being
3670       treated as spaces or as hard line breaks.  This option is intended  for
3671       use  with East Asian languages where spaces are not used between words,
3672       but text is divided into lines for readability.
3673
3674   Extension: east_asian_line_breaks
3675       Causes newlines within a paragraph to be  ignored,  rather  than  being
3676       treated  as  spaces or as hard line breaks, when they occur between two
3677       East  Asian  wide  characters.   This   is   a   better   choice   than
3678       ignore_line_breaks  for  texts  that  include  a mix of East Asian wide
3679       characters and other characters.
3680
3681   Extension: emoji
3682       Parses textual emojis like :smile: as Unicode emoticons.
3683
3684   Extension: tex_math_single_backslash
3685       Causes anything between \( and \) to be interpreted as inline TeX math,
3686       and  anything  between \[ and \] to be interpreted as display TeX math.
3687       Note: a drawback of this extension is that it precludes escaping (  and
3688       [.
3689
3690   Extension: tex_math_double_backslash
3691       Causes  anything  between  \\(  and \\) to be interpreted as inline TeX
3692       math, and anything between \\[ and \\] to be interpreted as display TeX
3693       math.
3694
3695   Extension: markdown_attribute
3696       By default, pandoc interprets material inside block-level tags as Mark‐
3697       down.  This extension changes the behavior so  that  Markdown  is  only
3698       parsed  inside  block-level  tags  if the tags have the attribute mark‐
3699       down=1.
3700
3701   Extension: mmd_title_block
3702       Enables a MultiMarkdown style title block at the top of  the  document,
3703       for example:
3704
3705              Title:   My title
3706              Author:  John Doe
3707              Date:    September 1, 2008
3708              Comment: This is a sample mmd title block, with
3709                       a field spanning multiple lines.
3710
3711       See the MultiMarkdown documentation for details.  If pandoc_title_block
3712       or  yaml_metadata_block  is  enabled,  it  will  take  precedence  over
3713       mmd_title_block.
3714
3715   Extension: abbreviations
3716       Parses PHP Markdown Extra abbreviation keys, like
3717
3718              *[HTML]: Hypertext Markup Language
3719
3720       Note  that the pandoc document model does not support abbreviations, so
3721       if this extension is enabled, abbreviation keys are simply skipped  (as
3722       opposed to being parsed as paragraphs).
3723
3724   Extension: autolink_bare_uris
3725       Makes  all absolute URIs into links, even when not surrounded by pointy
3726       braces <...>.
3727
3728   Extension: mmd_link_attributes
3729       Parses multimarkdown style key-value attributes on link and image  ref‐
3730       erences.    This   extension   should   not   be   confused   with  the
3731       link_attributes extension.
3732
3733              This is a reference ![image][ref] with multimarkdown attributes.
3734
3735              [ref]: http://path.to/image "Image title" width=20px height=30px
3736                     id=myId class="myClass1 myClass2"
3737
3738   Extension: mmd_header_identifiers
3739       Parses multimarkdown style  header  identifiers  (in  square  brackets,
3740       after the header but before any trailing #s in an ATX header).
3741
3742   Extension: compact_definition_lists
3743       Activates  the  definition  list  syntax  of pandoc 1.12.x and earlier.
3744       This syntax differs from the one described above under Definition lists
3745       in several respects:
3746
3747       · No blank line is required between consecutive items of the definition
3748         list.
3749
3750       · To get a "tight" or "compact" list, omit  space  between  consecutive
3751         items;  the  space  between a term and its definition does not affect
3752         anything.
3753
3754       · Lazy wrapping of paragraphs is not  allowed:  the  entire  definition
3755         must be indented four spaces.
3756
3757   Markdown variants
3758       In addition to pandoc's extended Markdown, the following Markdown vari‐
3759       ants are supported:
3760
3761       markdown_phpextra (PHP Markdown Extra)
3762              footnotes,    pipe_tables,     raw_html,     markdown_attribute,
3763              fenced_code_blocks,   definition_lists,   intraword_underscores,
3764              header_attributes, link_attributes, abbreviations, shortcut_ref‐
3765              erence_links, spaced_reference_links.
3766
3767       markdown_github (deprecated GitHub-Flavored Markdown)
3768              pipe_tables,   raw_html,  fenced_code_blocks,  auto_identifiers,
3769              gfm_auto_identifiers, backtick_code_blocks,  autolink_bare_uris,
3770              space_in_atx_header,  intraword_underscores,  strikeout,  emoji,
3771              shortcut_reference_links, angle_brackets_escapable,  lists_with‐
3772              out_preceding_blankline.
3773
3774       markdown_mmd (MultiMarkdown)
3775              pipe_tables,  raw_html, markdown_attribute, mmd_link_attributes,
3776              tex_math_double_backslash,                intraword_underscores,
3777              mmd_title_block,     footnotes,    definition_lists,    all_sym‐
3778              bols_escapable,  implicit_header_references,   auto_identifiers,
3779              mmd_header_identifiers,  shortcut_reference_links, implicit_fig‐
3780              ures, superscript, subscript, backtick_code_blocks,  spaced_ref‐
3781              erence_links, raw_attribute.
3782
3783       markdown_strict (Markdown.pl)
3784              raw_html, shortcut_reference_links, spaced_reference_links.
3785
3786       We  also support commonmark and gfm (GitHub-Flavored Markdown, which is
3787       implemented as a set of extensions on commonmark).
3788
3789       Note, however, that commonmark and gfm have limited support for  exten‐
3790       sions.  Only those listed below (and smart and raw_tex) will work.  The
3791       extensions can, however, all be individually disabled.   Also,  raw_tex
3792       only affects gfm output, not input.
3793
3794       gfm (GitHub-Flavored Markdown)
3795              pipe_tables,   raw_html,  fenced_code_blocks,  auto_identifiers,
3796              gfm_auto_identifiers, backtick_code_blocks,  autolink_bare_uris,
3797              space_in_atx_header,  intraword_underscores,  strikeout,  emoji,
3798              shortcut_reference_links, angle_brackets_escapable,  lists_with‐
3799              out_preceding_blankline.
3800

PRODUCING SLIDE SHOWS WITH PANDOC

3802       You  can  use pandoc to produce an HTML + JavaScript slide presentation
3803       that can be viewed via a web browser.  There are five ways to do  this,
3804       using  S5,  DZSlides, Slidy, Slideous, or reveal.js.  You can also pro‐
3805       duce a PDF slide show using LaTeX beamer, or slides shows in  Microsoft
3806       PowerPoint format.
3807
3808       Here's the Markdown source for a simple slide show, habits.txt:
3809
3810              % Habits
3811              % John Doe
3812              % March 22, 2005
3813
3814              # In the morning
3815
3816              ## Getting up
3817
3818              - Turn off alarm
3819              - Get out of bed
3820
3821              ## Breakfast
3822
3823              - Eat eggs
3824              - Drink coffee
3825
3826              # In the evening
3827
3828              ## Dinner
3829
3830              - Eat spaghetti
3831              - Drink wine
3832
3833              ------------------
3834
3835              ![picture of spaghetti](images/spaghetti.jpg)
3836
3837              ## Going to sleep
3838
3839              - Get in bed
3840              - Count sheep
3841
3842       To produce an HTML/JavaScript slide show, simply type
3843
3844              pandoc -t FORMAT -s habits.txt -o habits.html
3845
3846       where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
3847
3848       For  Slidy,  Slideous,  reveal.js,  and S5, the file produced by pandoc
3849       with the -s/--standalone option embeds a link  to  JavaScript  and  CSS
3850       files,  which  are  assumed  to  be  available  at  the  relative  path
3851       s5/default  (for  S5),  slideous   (for   Slideous),   reveal.js   (for
3852       reveal.js),  or  at  the  Slidy  website at w3.org (for Slidy).  (These
3853       paths  can  be  changed  by  setting   the   slidy-url,   slideous-url,
3854       revealjs-url,  or  s5-url  variables; see Variables for slides, above.)
3855       For DZSlides, the (relatively short) JavaScript and CSS are included in
3856       the file by default.
3857
3858       With all HTML slide formats, the --self-contained option can be used to
3859       produce a single file that contains all of the data necessary  to  dis‐
3860       play the slide show, including linked scripts, stylesheets, images, and
3861       videos.
3862
3863       To produce a PDF slide show using beamer, type
3864
3865              pandoc -t beamer habits.txt -o habits.pdf
3866
3867       Note that a reveal.js slide show can also be  converted  to  a  PDF  by
3868       printing it to a file from the browser.
3869
3870       To produce a Powerpoint slide show, type
3871
3872              pandoc habits.txt -o habits.pptx
3873
3874   Structuring the slide show
3875       By  default, the slide level is the highest header level in the hierar‐
3876       chy that is followed immediately by content, and  not  another  header,
3877       somewhere  in  the document.  In the example above, level 1 headers are
3878       always followed by level 2 headers, which are followed by content, so 2
3879       is  the  slide  level.   This  default  can  be  overridden  using  the
3880       --slide-level option.
3881
3882       The document is carved up into slides according to the following rules:
3883
3884       · A horizontal rule always starts a new slide.
3885
3886       · A header at the slide level always starts a new slide.
3887
3888       · Headers below the slide level in the hierarchy create headers  within
3889         a slide.
3890
3891       · Headers above the slide level in the hierarchy create "title slides,"
3892         which just contain the section title and help to break the slide show
3893         into sections.
3894
3895       · Content above the slide level will not appear in the slide show.
3896
3897       · A  title  page is constructed automatically from the document's title
3898         block, if present.  (In the case of beamer, this can be  disabled  by
3899         commenting out some lines in the default template.)
3900
3901       These  rules  are  designed  to  support many different styles of slide
3902       show.  If you don't care about structuring your  slides  into  sections
3903       and  subsections,  you can just use level 1 headers for all each slide.
3904       (In that case, level 1 will be the  slide  level.)  But  you  can  also
3905       structure the slide show into sections, as in the example above.
3906
3907       Note:  in reveal.js slide shows, if slide level is 2, a two-dimensional
3908       layout will be produced, with level 1 headers building horizontally and
3909       level  2  headers  building vertically.  It is not recommended that you
3910       use deeper nesting of section levels with reveal.js.
3911
3912   Incremental lists
3913       By default, these writers produce lists that display "all at once."  If
3914       you  want your lists to display incrementally (one item at a time), use
3915       the -i option.  If you want  a  particular  list  to  depart  from  the
3916       default,  put  it in a div block with class incremental or nonincremen‐
3917       tal.  So, for example, using the fenced div syntax, the following would
3918       be incremental regardless of the document default:
3919
3920              ::: incremental
3921
3922              - Eat spaghetti
3923              - Drink wine
3924
3925              :::
3926
3927       or
3928
3929              ::: nonincremental
3930
3931              - Eat spaghetti
3932              - Drink wine
3933
3934              :::
3935
3936       While  using  incremental  and  nonincremental divs are the recommended
3937       method of setting incremental lists  on  a  per-case  basis,  an  older
3938       method is also supported: putting lists inside a blockquote will depart
3939       from the document default (that is, it will display incrementally with‐
3940       out the -i option and all at once with the -i option):
3941
3942              > - Eat spaghetti
3943              > - Drink wine
3944
3945       Both  methods allow incremental and nonincremental lists to be mixed in
3946       a single document.
3947
3948   Inserting pauses
3949       You can add "pauses" within a slide by including a paragraph containing
3950       three dots, separated by spaces:
3951
3952              # Slide with a pause
3953
3954              content before the pause
3955
3956              . . .
3957
3958              content after the pause
3959
3960   Styling the slides
3961       You can change the style of HTML slides by putting customized CSS files
3962       in  $DATADIR/s5/default  (for  S5),  $DATADIR/slidy  (for  Slidy),   or
3963       $DATADIR/slideous  (for  Slideous),  where  $DATADIR  is  the user data
3964       directory (see --data-dir, above).  The originals may be found in  pan‐
3965       doc's    system   data   directory   (generally   $CABALDIR/pandoc-VER‐
3966       SION/s5/default).  Pandoc will look there for any  files  it  does  not
3967       find in the user data directory.
3968
3969       For  dzslides,  the CSS is included in the HTML file itself, and may be
3970       modified there.
3971
3972       All reveal.js configuration options can be set through variables.   For
3973       example, themes can be used by setting the theme variable:
3974
3975              -V theme=moon
3976
3977       Or you can specify a custom stylesheet using the --css option.
3978
3979       To style beamer slides, you can specify a theme, colortheme, fonttheme,
3980       innertheme, and outertheme, using the -V option:
3981
3982              pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
3983
3984       Note that header attributes will turn into slide attributes (on a <div>
3985       or  <section>)  in HTML slide formats, allowing you to style individual
3986       slides.  In beamer, the only header attribute that  affects  slides  is
3987       the  allowframebreaks  class,  which  sets the allowframebreaks option,
3988       causing multiple slides to be created  if  the  content  overfills  the
3989       frame.  This is recommended especially for bibliographies:
3990
3991              # References {.allowframebreaks}
3992
3993   Speaker notes
3994       Speaker  notes are supported in reveal.js and PowerPoint (pptx) output.
3995       You can add notes to your Markdown document thus:
3996
3997              ::: notes
3998
3999              This is my note.
4000
4001              - It can contain Markdown
4002              - like this list
4003
4004              :::
4005
4006       To show the notes window in reveal.js, press s while viewing  the  pre‐
4007       sentation.  Speaker notes in PowerPoint will be available, as usual, in
4008       handouts and presenter view.
4009
4010       Notes are not yet supported for other slide formats, but the notes will
4011       not appear on the slides themselves.
4012
4013   Columns
4014       To  put material in side by side columns, you can use a native div con‐
4015       tainer with class columns, containing two or more div  containers  with
4016       class column and a width attribute:
4017
4018              :::::::::::::: {.columns}
4019              ::: {.column width="40%"}
4020              contents...
4021              :::
4022              ::: {.column width="60%"}
4023              contents...
4024              :::
4025              ::::::::::::::
4026
4027   Frame attributes in beamer
4028       Sometimes  it is necessary to add the LaTeX [fragile] option to a frame
4029       in beamer (for example, when using the minted environment).   This  can
4030       be  forced  by  adding  the fragile class to the header introducing the
4031       slide:
4032
4033              # Fragile slide {.fragile}
4034
4035       All of the other frame attributes  described  in  Section  8.1  of  the
4036       Beamer  User's  Guide may also be used: allowdisplaybreaks, allowframe‐
4037       breaks, b, c, t, environment, label, plain,  shrink,  standout,  nofra‐
4038       menumbering.
4039
4040   Background in reveal.js and beamer
4041       Background  images  can be added to self-contained reveal.js slideshows
4042       and to beamer slideshows.
4043
4044       For the same image on every slide, use the configuration  option  back‐
4045       ground-image  either  in  the  YAML metadata block or as a command-line
4046       variable.  (There are no other options in beamer and the rest  of  this
4047       section concerns reveal.js slideshows.)
4048
4049       For  reveal.js,  you can instead use the reveal.js-native option paral‐
4050       laxBackgroundImage.  You can also set parallaxBackgroundHorizontal  and
4051       parallaxBackgroundVertical the same way and must also set parallaxBack‐
4052       groundSize to have your values take effect.
4053
4054       To set an image for  a  particular  reveal.js  slide,  add  {data-back‐
4055       ground-image="/path/to/image"}  to  the first slide-level header on the
4056       slide (which may even be empty).
4057
4058       In reveal.js's overview mode, the parallaxBackgroundImage will show  up
4059       only on the first slide.
4060
4061       Other  reveal.js  background  settings  also work on individual slides,
4062       including  data-background-size,   data-background-repeat,   data-back‐
4063       ground-color, data-transition, and data-transition-speed.
4064
4065       See the reveal.js documentation for more details.
4066
4067       For example in reveal.js:
4068
4069              ---
4070              title: My Slideshow
4071              parallaxBackgroundImage: /path/to/my/background_image.png
4072              ---
4073
4074              ## Slide One
4075
4076              Slide 1 has background_image.png as its background.
4077
4078              ## {data-background-image="/path/to/special_image.jpg"}
4079
4080              Slide 2 has a special image for its background, even though the header has no content.
4081

CREATING EPUBS WITH PANDOC

4083   EPUB Metadata
4084       EPUB metadata may be specified using the --epub-metadata option, but if
4085       the source document is Markdown, it is better to use  a  YAML  metadata
4086       block.  Here is an example:
4087
4088              ---
4089              title:
4090              - type: main
4091                text: My Book
4092              - type: subtitle
4093                text: An investigation of metadata
4094              creator:
4095              - role: author
4096                text: John Smith
4097              - role: editor
4098                text: Sarah Jones
4099              identifier:
4100              - scheme: DOI
4101                text: doi:10.234234.234/33
4102              publisher:  My Press
4103              rights: © 2007 John Smith, CC BY-NC
4104              ibooks:
4105                version: 1.3.4
4106              ...
4107
4108       The following fields are recognized:
4109
4110       identifier
4111              Either  a string value or an object with fields text and scheme.
4112              Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
4113              LCCN,   GTIN-14,  ISBN-13,  Legal  deposit  number,  URN,  OCLC,
4114              ISMN-13, ISBN-A, JP, OLCC.
4115
4116       title  Either a string value, or an  object  with  fields  file-as  and
4117              type,  or  a  list  of  such objects.  Valid values for type are
4118              main, subtitle, short, collection, edition, extended.
4119
4120       creator
4121              Either a string value, or an object with fields  role,  file-as,
4122              and  text, or a list of such objects.  Valid values for role are
4123              MARC  relators,  but  pandoc  will  attempt  to  translate   the
4124              human-readable  versions  (like  "author"  and  "editor") to the
4125              appropriate marc relators.
4126
4127       contributor
4128              Same format as creator.
4129
4130       date   A string value in YYYY-MM-DD format.  (Only the year  is  neces‐
4131              sary.) Pandoc will attempt to convert other common date formats.
4132
4133       lang (or legacy: language)
4134              A  string  value  in  BCP 47 format.  Pandoc will default to the
4135              local language if nothing is specified.
4136
4137       subject
4138              A string value or a list of such values.
4139
4140       description
4141              A string value.
4142
4143       type   A string value.
4144
4145       format A string value.
4146
4147       relation
4148              A string value.
4149
4150       coverage
4151              A string value.
4152
4153       rights A string value.
4154
4155       cover-image
4156              A string value (path to cover image).
4157
4158       css (or legacy: stylesheet)
4159              A string value (path to CSS stylesheet).
4160
4161       page-progression-direction
4162              Either ltr or  rtl.   Specifies  the  page-progression-direction
4163              attribute for the spine element.
4164
4165       ibooks iBooks-specific metadata, with the following fields:
4166
4167              · version: (string)
4168
4169              · specified-fonts: true|false (default false)
4170
4171              · ipad-orientation-lock: portrait-only|landscape-only
4172
4173              · iphone-orientation-lock: portrait-only|landscape-only
4174
4175              · binding: true|false (default true)
4176
4177              · scroll-axis: vertical|horizontal|default
4178
4179   The epub:type attribute
4180       For  epub3  output,  you  can mark up the header that corresponds to an
4181       EPUB chapter using the epub:type attribute.  For example,  to  set  the
4182       attribute to the value prologue, use this markdown:
4183
4184              # My chapter {epub:type=prologue}
4185
4186       Which will result in:
4187
4188              <body epub:type="frontmatter">
4189                <section epub:type="prologue">
4190                  <h1>My chapter</h1>
4191
4192       Pandoc will output <body epub:type="bodymatter">, unless you use one of
4193       the following values, in which case either  frontmatter  or  backmatter
4194       will be output.
4195
4196       epub:type of first section   epub:type of body
4197       ───────────────────────────────────────────────
4198       prologue                     frontmatter
4199       abstract                     frontmatter
4200       acknowledgments              frontmatter
4201       copyright-page               frontmatter
4202       dedication                   frontmatter
4203       foreword                     frontmatter
4204       halftitle,                   frontmatter
4205       introduction                 frontmatter
4206       preface                      frontmatter
4207       seriespage                   frontmatter
4208       titlepage                    frontmatter
4209       afterword                    backmatter
4210       appendix                     backmatter
4211       colophon                     backmatter
4212       conclusion                   backmatter
4213       epigraph                     backmatter
4214
4215   Linked media
4216       By  default,  pandoc  will  download  media  referenced from any <img>,
4217       <audio>, <video> or <source> element present in the generated EPUB, and
4218       include  it in the EPUB container, yielding a completely self-contained
4219       EPUB.  If you want to link to external media resources instead, use raw
4220       HTML  in  your source and add data-external="1" to the tag with the src
4221       attribute.  For example:
4222
4223              <audio controls="1">
4224                <source src="http://example.com/music/toccata.mp3"
4225                        data-external="1" type="audio/mpeg">
4226                </source>
4227              </audio>
4228

SYNTAX HIGHLIGHTING

4230       Pandoc will automatically highlight syntax in fenced code  blocks  that
4231       are  marked  with  a language name.  The Haskell library skylighting is
4232       used for highlighting.  Currently highlighting is  supported  only  for
4233       HTML,  EPUB, Docx, Ms, and LaTeX/PDF output.  To see a list of language
4234       names that pandoc will  recognize,  type  pandoc  --list-highlight-lan‐
4235       guages.
4236
4237       The  color  scheme  can be selected using the --highlight-style option.
4238       The default color scheme is pygments, which imitates the default  color
4239       scheme  used  by  the  Python  library pygments (though pygments is not
4240       actually used to do the highlighting).  To  see  a  list  of  highlight
4241       styles, type pandoc --list-highlight-styles.
4242
4243       If  you  are  not  satisfied  with  the  predefined styles, you can use
4244       --print-highlight-style to generate a JSON .theme  file  which  can  be
4245       modified  and used as the argument to --highlight-style.  To get a JSON
4246       version of the pygments style, for example:
4247
4248              pandoc --print-highlight-style pygments > my.theme
4249
4250       Then edit my.theme and use it like this:
4251
4252              pandoc --highlight-style my.theme
4253
4254       If you are not satisfied with the built-in highlighting,  or  you  want
4255       highlight  a  language  that  isn't  supported,  you can use the --syn‐
4256       tax-definition option to load a KDE-style XML syntax  definition  file.
4257       Before writing your own, have a look at KDE's repository of syntax def‐
4258       initions.
4259
4260       To disable highlighting, use the --no-highlight option.
4261

CUSTOM STYLES IN DOCX

4263   Input
4264       The docx reader, by default, only reads those styles that it  can  con‐
4265       vert  into pandoc elements, either by direct conversion or interpreting
4266       the derivation of the input document's styles.
4267
4268       By enabling the styles extension in the docx reader  (-f  docx+styles),
4269       you can produce output that maintains the styles of the input document,
4270       using the custom-style class.   Paragraph  styles  are  interpreted  as
4271       divs, while character styles are interpreted as spans.
4272
4273       For  example,  using  the  custom-style-reference.docx file in the test
4274       directory, we have the following different outputs:
4275
4276       Without the +styles extension:
4277
4278              $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
4279              This is some text.
4280
4281              This is text with an *emphasized* text style. And this is text with a
4282              **strengthened** text style.
4283
4284              > Here is a styled paragraph that inherits from Block Text.
4285
4286       And with the extension:
4287
4288              $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
4289
4290              ::: {custom-style="FirstParagraph"}
4291              This is some text.
4292              :::
4293
4294              ::: {custom-style="BodyText"}
4295              This is text with an [emphasized]{custom-style="Emphatic"} text style.
4296              And this is text with a [strengthened]{custom-style="Strengthened"}
4297              text style.
4298              :::
4299
4300              ::: {custom-style="MyBlockStyle"}
4301              > Here is a styled paragraph that inherits from Block Text.
4302              :::
4303
4304       With these custom styles, you can use your input document as  a  refer‐
4305       ence-doc  while creating docx output (see below), and maintain the same
4306       styles in your input and output files.
4307
4308   Output
4309       By default, pandoc's docx output applies a predefined set of styles for
4310       blocks  such  as  paragraphs and block quotes, and uses largely default
4311       formatting (italics, bold) for inlines.  This will work for  most  pur‐
4312       poses,  especially  alongside  a  reference.docx file.  However, if you
4313       need to apply your own styles to blocks, or match a preexisting set  of
4314       styles,  pandoc  allows you to define custom styles for blocks and text
4315       using divs and spans, respectively.
4316
4317       If you define a div or span with  the  attribute  custom-style,  pandoc
4318       will  apply  your  specified  style to the contained elements.  So, for
4319       example using the bracketed_spans syntax,
4320
4321              [Get out]{custom-style="Emphatically"}, he said.
4322
4323       would produce a docx file with "Get out" styled  with  character  style
4324       Emphatically.  Similarly, using the fenced_divs syntax,
4325
4326              Dickinson starts the poem simply:
4327
4328              ::: {custom-style="Poetry"}
4329              | A Bird came down the Walk---
4330              | He did not know I saw---
4331              :::
4332
4333       would style the two contained lines with the Poetry paragraph style.
4334
4335       If  the styles are not yet in your reference.docx, they will be defined
4336       in the output file as inheriting from normal text.  If they are already
4337       defined, pandoc will not alter the definition.
4338
4339       This feature allows for greatest customization in conjunction with pan‐
4340       doc filters.  If you want all  paragraphs  after  block  quotes  to  be
4341       indented, you can write a filter to apply the styles necessary.  If you
4342       want all italics to be transformed  to  the  Emphasis  character  style
4343       (perhaps  to  change  their  color),  you can write a filter which will
4344       transform all italicized inlines to inlines  within  an  Emphasis  cus‐
4345       tom-style span.
4346

CUSTOM WRITERS

4348       Pandoc  can  be  extended  with custom writers written in lua.  (Pandoc
4349       includes a lua interpreter, so lua need not be installed separately.)
4350
4351       To use a custom writer, simply specify the path to the  lua  script  in
4352       place of the output format.  For example:
4353
4354              pandoc -t data/sample.lua
4355
4356       Creating  a custom writer requires writing a lua function for each pos‐
4357       sible element in a pandoc document.  To get a documented example  which
4358       you can modify according to your needs, do
4359
4360              pandoc --print-default-data-file sample.lua
4361

A NOTE ON SECURITY

4363       If you use pandoc to convert user-contributed content in a web applica‐
4364       tion, here are some things to keep in mind:
4365
4366       1. Although pandoc itself will not create or  modify  any  files  other
4367          than  those you explicitly ask it create (with the exception of tem‐
4368          porary files used in producing PDFs),  a  filter  or  custom  writer
4369          could  in  principle  do anything on your file system.  Please audit
4370          filters and custom writers very carefully before using them.
4371
4372       2. If your application uses pandoc as a Haskell  library  (rather  than
4373          shelling  out to the executable), it is possible to use it in a mode
4374          that fully isolates pandoc from your file  system,  by  running  the
4375          pandoc  operations  in the PandocPure monad.  See the document Using
4376          the pandoc API for more details.
4377
4378       3. Pandoc's parsers can exhibit pathological performance on some corner
4379          cases.   It is wise to put any pandoc operations under a timeout, to
4380          avoid DOS attacks that exploit these issues.  If you are  using  the
4381          pandoc  executable, you can add the command line options +RTS -M512M
4382          -RTS (for example) to limit the heap size to 512MB.
4383
4384       4. The HTML generated by pandoc is  not  guaranteed  to  be  safe.   If
4385          raw_html  is  enabled for the Markdown input, users can inject arbi‐
4386          trary HTML.  Even if raw_html is disabled, users can include danger‐
4387          ous  content  in attributes for headers, spans, and code blocks.  To
4388          be safe, you should run all the generated HTML through an HTML sani‐
4389          tizer.
4390

AUTHORS

4392       Copyright 2006-2017 John MacFarlane (jgm@berkeley.edu).  Released under
4393       the GPL, version 2 or greater.  This software carries  no  warranty  of
4394       any kind.  (See COPYRIGHT for full copyright and warranty notices.) For
4395       a full list of contributors, see the  file  AUTHORS.md  in  the  pandoc
4396       source code.
4397
4398       The  Pandoc  source  code  and all documentation may be downloaded from
4399       <http://pandoc.org>.
4400
4401
4402
4403pandoc 2.5                     November 25, 2018                     PANDOC(1)
Impressum