1Pandoc User's Guide()                                    Pandoc User's Guide()
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  ex‐
34       pressive  than  many of the formats it converts between, one should not
35       expect perfect conversions between every format and every other.   Pan‐
36       doc attempts to preserve the structural elements of a document, but not
37       formatting details such as margin size.  And  some  document  elements,
38       such  as complex tables, may not fit into pandoc's simple document mod‐
39       el.  While conversions from pandoc's Markdown to all formats aspire  to
40       be  perfect,  conversions  from  formats  more expressive than pandoc's
41       Markdown can be expected to be lossy.
42
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 ex‐
87       tension is unknown, the output format will default to HTML.  If no  in‐
88       put file is specified (so that input comes from stdin), or if the input
89       files' extensions are unknown, the input format will be assumed  to  be
90       Markdown.
91
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).  Alterna‐
111       tively, pandoc can use ConTeXt, roff ms, or  HTML  as  an  intermediate
112       format.   To  do this, specify an output file with a .pdf extension, as
113       before, but add the --pdf-engine option or -t context, -t html,  or  -t
114       ms to the command line.  The tool used to generate the PDF from the in‐
115       termediate format may be specified using --pdf-engine.
116
117       You can control the PDF style using variables, depending on the  inter‐
118       mediate  format  used:  see variables for LaTeX, variables for ConTeXt,
119       variables for wkhtmltopdf, variables for ms.  When HTML is used  as  an
120       intermediate format, the output can be styled using --css.
121
122       To debug the PDF creation, it can be useful to look at the intermediate
123       representation: instead of -o test.pdf, use for example -s -o  test.tex
124       to  output  the  generated  LaTeX.   You can then test it with pdflatex
125       test.tex.
126
127       When using LaTeX, the following packages need to be available (they are
128       included  with all recent versions of TeX Live): amsfonts, amsmath, lm,
129       unicode-math, ifxetex, ifluatex, listings (if the --listings option  is
130       used),  fancyvrb,  longtable,  booktabs, graphicx (if the document con‐
131       tains images), hyperref, xcolor,  ulem,  geometry  (with  the  geometry
132       variable set), setspace (with linestretch), and babel (with lang).  The
133       use of xelatex or lualatex as the PDF engine requires fontspec.   xela‐
134       tex  uses  polyglossia (with lang), xecjk, and bidi (with the dir vari‐
135       able set).  If the mathspec variable is set, xelatex will use  mathspec
136       instead  of  unicode-math.  The upquote and microtype packages are used
137       if available, and csquotes will be used for typography if the  csquotes
138       variable  or metadata field is set to a true value.  The natbib, bibla‐
139       tex, bibtex, and biber packages can optionally  be  used  for  citation
140       rendering.  The following packages will be used to improve output qual‐
141       ity if present, but pandoc does not require them to be present: upquote
142       (for  straight  quotes in verbatim environments), microtype (for better
143       spacing adjustments), parskip (for better inter-paragraph spaces), xurl
144       (for  better line breaks in URLs), bookmark (for better PDF bookmarks),
145       and footnotehyper or footnote (to allow footnotes in tables).
146
147   Reading from the Web
148       Instead of an input file, an absolute URI may be given.  In  this  case
149       pandoc will fetch the content using HTTP:
150
151              pandoc -f html -t markdown https://www.fsf.org
152
153       It  is  possible  to  supply a custom User-Agent string or other header
154       when requesting a document from a URL:
155
156              pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
157                https://www.fsf.org
158

OPTIONS

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

EXIT CODES

1273       If pandoc completes successfully, it will return exit code 0.   Nonzero
1274       exit codes have the following meanings:
1275
1276       Code   Error
1277       ─────────────────────────────────
1278          3   PandocFailOnWarningError
1279          4   PandocAppError
1280          5   PandocTemplateError
1281          6   PandocOptionError
1282         21   PandocUnknownReaderError
1283         22   PandocUnknownWriterError
1284         23   PandocUnsupportedExten‐
1285              sionError
1286
1287
1288         31   PandocEpubSubdirectoryEr‐
1289              ror
1290         43   PandocPDFError
1291         47   PandocPDFProgramNot‐
1292              FoundError
1293         61   PandocHttpError
1294         62   PandocShouldNeverHappen‐
1295              Error
1296         63   PandocSomeError
1297         64   PandocParseError
1298         65   PandocParsecError
1299         66   PandocMakePDFError
1300         67   PandocSyntaxMapError
1301         83   PandocFilterError
1302         91   PandocMacroLoop
1303         92   PandocUTF8DecodingError
1304         93   PandocIpynbDecodingError
1305         97   PandocCouldNotFind‐
1306              DataFileError
1307         99   PandocResourceNotFound
1308

DEFAULT FILES

1310       The --defaults option may be used to  specify  a  package  of  options.
1311       Here is a sample defaults file demonstrating all of the fields that may
1312       be used:
1313
1314              from: markdown+emoji
1315              # reader: may be used instead of from:
1316              to: html5
1317              # writer: may be used instead of to:
1318
1319              # leave blank for output to stdout:
1320              output-file:
1321              # leave blank for input from stdin, use [] for no input:
1322              input-files:
1323              - preface.md
1324              - content.md
1325              # or you may use input-file: with a single value
1326
1327              template: letter
1328              standalone: true
1329              self-contained: false
1330
1331              # note that structured variables may be specified:
1332              variables:
1333                documentclass: book
1334                classoption:
1335                  - twosides
1336                  - draft
1337
1338              # metadata values specified here are parsed as literal
1339              # string text, not markdown:
1340              metadata:
1341                author:
1342                - Sam Smith
1343                - Julie Liu
1344              metadata-files:
1345              - boilerplate.yaml
1346              # or you may use metadata-file: with a single value
1347
1348              # Note that these take files, not their contents:
1349              include-before-body: []
1350              include-after-body: []
1351              include-in-header: []
1352              resource-path: ["."]
1353
1354              # filters will be assumed to be Lua filters if they have
1355              # the .lua extension, and json filters otherwise.  But
1356              # the filter type can also be specified explicitly, as shown:
1357              filters:
1358              - pandoc-citeproc
1359              - wordcount.lua
1360              - type: json
1361                path: foo.lua
1362
1363              file-scope: false
1364
1365              data-dir:
1366
1367              # ERROR, WARNING, or INFO
1368              verbosity: INFO
1369              log-file: log.json
1370
1371              # citeproc, natbib, or biblatex
1372              cite-method: citeproc
1373              # part, chapter, section, or default:
1374              top-level-division: chapter
1375              abbreviations:
1376
1377              pdf-engine: pdflatex
1378              pdf-engine-opts:
1379              - "-shell-escape"
1380              # you may also use pdf-engine-opt: with a single option
1381              # pdf-engine-opt: "-shell-escape"
1382
1383              # auto, preserve, or none
1384              wrap: auto
1385              columns: 78
1386              dpi: 72
1387
1388              extract-media: mediadir
1389
1390              table-of-contents: true
1391              toc-depth: 2
1392              number-sections: false
1393              # a list of offsets at each heading level
1394              number-offset: [0,0,0,0,0,0]
1395              # toc: may also be used instead of table-of-contents:
1396              shift-heading-level-by: 1
1397              section-divs: true
1398              identifier-prefix: foo
1399              title-prefix: ""
1400              strip-empty-paragraphs: true
1401              # lf, crlf, or native
1402              eol: lf
1403              strip-comments: false
1404              indented-code-classes: []
1405              ascii: true
1406              default-image-extension: ".jpg"
1407
1408              # either a style name of a style definition file:
1409              highlight-style: pygments
1410              syntax-definitions:
1411              - c.xml
1412              # or you may use syntax-definition: with a single value
1413              listings: false
1414
1415              reference-doc: myref.docx
1416
1417              # method is plain, webtex, gladtex, mathml, mathjax, katex
1418              # you may specify a url with webtex, mathjax, katex
1419              html-math-method:
1420                method: mathjax
1421                url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
1422              # none, references, or javascript
1423              email-obfuscation: javascript
1424
1425              tab-stop: 8
1426              preserve-tabs: true
1427
1428              incremental: false
1429              slide-level: 2
1430
1431              epub-subdirectory: EPUB
1432              epub-metadata: meta.xml
1433              epub-fonts:
1434              - foobar.otf
1435              epub-chapter-level: 1
1436              epub-cover-image: cover.jpg
1437
1438              reference-links: true
1439              # block, section, or document
1440              reference-location: block
1441              atx-headers: false
1442
1443              # accept, reject, or all
1444              track-changes: accept
1445
1446              html-q-tags: false
1447              css:
1448              - site.css
1449
1450              # none, all, or best
1451              ipynb-output: best
1452
1453              # A list of two-element lists
1454              request-headers:
1455              - ["User-Agent", "Mozilla/5.0"]
1456
1457              fail-if-warnings: false
1458              dump-args: false
1459              ignore-args: false
1460              trace: false
1461
1462       Fields that are omitted will just have their  regular  default  values.
1463       So a defaults file can be as simple as one line:
1464
1465              verbosity: INFO
1466
1467       Default  files  can  be placed in the defaults subdirectory of the user
1468       data directory and used from any directory.   For  example,  one  could
1469       create  a file specifying defaults for writing letters, save it as let‐
1470       ter.yaml in the defaults subdirectory of the user data  directory,  and
1471       then  invoke  these defaults from any directory using pandoc --defaults
1472       letter or pandoc -dletter.
1473
1474       When multiple defaults are used, their contents will be combined.
1475
1476       Note that, where command-line arguments may  be  repeated  (--metadata-
1477       file,  --css, --include-in-header, --include-before-body, --include-af‐
1478       ter-body,  --variable,  --metadata,  --syntax-definition),  the  values
1479       specified on the command line will combine with values specified in the
1480       defaults file, rather than replacing them.
1481

TEMPLATES

1483       When the -s/--standalone option is used, pandoc uses a template to  add
1484       header and footer material that is needed for a self-standing document.
1485       To see the default template that is used, just type
1486
1487              pandoc -D *FORMAT*
1488
1489       where FORMAT is the name of the output format.  A custom  template  can
1490       be  specified  using  the --template option.  You can also override the
1491       system default templates for a given output format FORMAT by putting  a
1492       file templates/default.*FORMAT* in the user data directory (see --data-
1493       dir, above).  Exceptions:
1494
1495       · For odt output, customize the default.opendocument template.
1496
1497       · For pdf output, customize the  default.latex  template  (or  the  de‐
1498         fault.context template, if you use -t context, or the default.ms tem‐
1499         plate, if you use -t ms, or the default.html template, if you use  -t
1500         html).
1501
1502       · docx  and pptx have no template (however, you can use --reference-doc
1503         to customize the output).
1504
1505       Templates contain variables, which allow for the inclusion of arbitrary
1506       information  at  any point in the file.  They may be set at the command
1507       line using the -V/--variable option.  If a variable is not set,  pandoc
1508       will  look for the key in the document's metadata, which can be set us‐
1509       ing either YAML metadata blocks or with the -M/--metadata  option.   In
1510       addition, some variables are given default values by pandoc.  See Vari‐
1511       ables below for a list of variables used in pandoc's default templates.
1512
1513       If you use custom templates, you may need  to  revise  them  as  pandoc
1514       changes.   We  recommend tracking the changes in the default templates,
1515       and modifying your custom templates accordingly.  An  easy  way  to  do
1516       this  is  to  fork the pandoc-templates repository and merge in changes
1517       after each pandoc release.
1518
1519   Template syntax
1520   Comments
1521       Anything between the sequence $-- and the  end  of  the  line  will  be
1522       treated as a comment and omitted from the output.
1523
1524   Delimiters
1525       To  mark variables and control structures in the template, either $...$
1526       or ${...} may be used as delimiters.  The styles may also be  mixed  in
1527       the  same template, but the opening and closing delimiter must match in
1528       each case.  The opening delimiter may be followed by one or more spaces
1529       or  tabs, which will be ignored.  The closing delimiter may be followed
1530       by one or more spaces or tabs, which will be ignored.
1531
1532       To include a literal $ in the document, use $$.
1533
1534   Interpolated variables
1535       A slot for an interpolated variable is a variable  name  surrounded  by
1536       matched  delimiters.   Variable  names must begin with a letter and can
1537       contain letters, numbers, _, -, and ..  The keywords it, if, else,  en‐
1538       dif, for, sep, and endfor may not be used as variable names.  Examples:
1539
1540              $foo$
1541              $foo.bar.baz$
1542              $foo_bar.baz-bim$
1543              $ foo $
1544              ${foo}
1545              ${foo.bar.baz}
1546              ${foo_bar.baz-bim}
1547              ${ foo }
1548
1549       Variable names with periods are used to get at structured variable val‐
1550       ues.  So, for example, employee.salary will return  the  value  of  the
1551       salary field of the object that is the value of the employee field.
1552
1553       · If  the  value  of  the variable is simple value, it will be rendered
1554         verbatim.  (Note that no escaping is done; the assumption is that the
1555         calling  program will escape the strings appropriately for the output
1556         format.)
1557
1558       · If the value is a list, the values will be concatenated.
1559
1560       · If the value is a map, the string true will be rendered.
1561
1562       · Every other value will be rendered as the empty string.
1563
1564   Conditionals
1565       A conditional begins with if(variable) (enclosed in matched delimiters)
1566       and ends with endif (enclosed in matched delimiters).  It may optional‐
1567       ly contain an else (enclosed in matched delimiters).  The if section is
1568       used  if  variable has a non-empty value, otherwise the else section is
1569       used (if present).  Examples:
1570
1571              $if(foo)$bar$endif$
1572
1573              $if(foo)$
1574                $foo$
1575              $endif$
1576
1577              $if(foo)$
1578              part one
1579              $else$
1580              part two
1581              $endif$
1582
1583              ${if(foo)}bar${endif}
1584
1585              ${if(foo)}
1586                ${foo}
1587              ${endif}
1588
1589              ${if(foo)}
1590              ${ foo.bar }
1591              ${else}
1592              no foo!
1593              ${endif}
1594
1595       The keyword elseif may be used to simplify complex nested conditionals:
1596
1597              $if(foo)$
1598              XXX
1599              $elseif(bar)$
1600              YYY
1601              $else$
1602              ZZZ
1603              $endif$
1604
1605   For loops
1606       A for loop begins with for(variable) (enclosed in  matched  delimiters)
1607       and ends with endfor (enclosed in matched delimiters.
1608
1609       · If  variable is an array, the material inside the loop will be evalu‐
1610         ated repeatedly, with variable being set to each value of  the  array
1611         in turn, and concatenated.
1612
1613       · If variable is a map, the material inside will be set to the map.
1614
1615       · If  the  value of the associated variable is not an array or a map, a
1616         single iteration will be performed on its value.
1617
1618       Examples:
1619
1620              $for(foo)$$foo$$sep$, $endfor$
1621
1622              $for(foo)$
1623                - $foo.last$, $foo.first$
1624              $endfor$
1625
1626              ${ for(foo.bar) }
1627                - ${ foo.bar.last }, ${ foo.bar.first }
1628              ${ endfor }
1629
1630              $for(mymap)$
1631              $it.name$: $it.office$
1632              $endfor$
1633
1634       You may optionally specify a separator between consecutive values using
1635       sep (enclosed in matched delimiters).  The material between sep and the
1636       endfor is the separator.
1637
1638              ${ for(foo) }${ foo }${ sep }, ${ endfor }
1639
1640       Instead of using variable inside the loop, the special  anaphoric  key‐
1641       word it may be used.
1642
1643              ${ for(foo.bar) }
1644                - ${ it.last }, ${ it.first }
1645              ${ endfor }
1646
1647   Partials
1648       Partials (subtemplates stored in different files) may be included using
1649       the syntax
1650
1651              ${ boilerplate() }
1652
1653       Partials will be sought in the directory containing the main  template,
1654       and  will be assumed to have the same extension as the main template if
1655       they lack an explicit extension.  (If the partials are not found  here,
1656       they will also be sought in the templates subdirectory of the user data
1657       directory.)
1658
1659       Partials may optionally be applied to variables using a colon:
1660
1661              ${ date:fancy() }
1662
1663              ${ articles:bibentry() }
1664
1665       If articles is an array, this will iterate over  its  values,  applying
1666       the  partial  bibentry()  to  each one.  So the second example above is
1667       equivalent to
1668
1669              ${ for(articles) }
1670              ${ it:bibentry() }
1671              ${ endfor }
1672
1673       Note that the anaphoric keyword it must be  used  when  iterating  over
1674       partials.   In  the above examples, the bibentry partial should contain
1675       it.title (and so on) instead of articles.title.
1676
1677       Final newlines are omitted from included partials.
1678
1679       Partials may include other partials.
1680
1681       A separator between values of an  array  may  be  specified  in  square
1682       brackets, immediately after the variable name or partial:
1683
1684              ${months[, ]}$
1685
1686              ${articles:bibentry()[; ]$
1687
1688       The  separator  in  this case is literal and (unlike with sep in an ex‐
1689       plicit for loop) cannot contain interpolated variables  or  other  tem‐
1690       plate directives.
1691
1692   Nesting
1693       To ensure that content is "nested," that is, subsequent lines indented,
1694       use the ^ directive:
1695
1696              $item.number$  $^$$item.description$ ($item.price$)
1697
1698       In this example, if item.description has multiple lines, they will  all
1699       be indented to line up with the first line:
1700
1701              00123  A fine bottle of 18-year old
1702                     Oban whiskey. ($148)
1703
1704       To  nest multiple lines to the same level, align them with the ^ direc‐
1705       tive in the template.  For example:
1706
1707              $item.number$  $^$$item.description$ ($item.price$)
1708                             (Available til $item.sellby$.)
1709
1710       will produce
1711
1712              00123  A fine bottle of 18-year old
1713                     Oban whiskey. ($148)
1714                     (Available til March 30, 2020.)
1715
1716       If a variable occurs by itself on a line, preceded  by  whitespace  and
1717       not  followed  by  further text or directives on the same line, and the
1718       variable's value contains multiple lines, it will be  nested  automati‐
1719       cally.
1720
1721   Breakable spaces
1722       Normally,  spaces  in  the template itself (as opposed to values of the
1723       interpolated variables) are not breakable, but they can be made  break‐
1724       able in part of the template by using the ~ keyword (ended with another
1725       ~).
1726
1727              $~$This long line may break if the document is rendered
1728              with a short line length.$~$
1729
1730   Pipes
1731       A pipe transforms the value of a variable or partial.  Pipes are speci‐
1732       fied  using  a slash (/) between the variable name (or partial) and the
1733       pipe name.  Example:
1734
1735              $for(name)$
1736              $name/uppercase$
1737              $endfor$
1738
1739              $for(metadata/pairs)$
1740              - $it.key$: $it.value$
1741              $endfor$
1742
1743              $employee:name()/uppercase$
1744
1745       Pipes may be chained:
1746
1747              $for(employees/pairs)$
1748              $it.key/alpha/uppercase$. $it.name$
1749              $endfor$
1750
1751       Some pipes take parameters:
1752
1753              |----------------------|------------|
1754              $for(employee)$
1755              $it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
1756              $endfor$
1757              |----------------------|------------|
1758
1759       Currently the following pipes are predefined:
1760
1761       · pairs: Converts a map or array to an array of maps, each with key and
1762         value  fields.   If  the original value was an array, the key will be
1763         the array index, starting with 1.
1764
1765       · uppercase: Converts text to uppercase.
1766
1767       · lowercase: Converts text to lowercase.
1768
1769       · length: Returns the length of the value: number of characters  for  a
1770         textual value, number of elements for a map or array.
1771
1772       · reverse: Reverses a textual value or array, and has no effect on oth‐
1773         er values.
1774
1775       · chomp: Removes trailing newlines (and breakable space).
1776
1777       · nowrap: Disables line wrapping on breakable spaces.
1778
1779       · alpha: Converts textual values that can be read as  an  integer  into
1780         lowercase  alphabetic  characters a..z (mod 26).  This can be used to
1781         get lettered enumeration from array indices.  To get  uppercase  let‐
1782         ters, chain with uppercase.
1783
1784       · roman:  Converts  textual  values that can be read as an integer into
1785         lowercase roman numerials.  This can be used to get lettered enumera‐
1786         tion  from  array indices.  To get uppercase roman, chain with upper‐
1787         case.
1788
1789       · left n "leftborder" "rightborder": Renders a textual value in a block
1790         of width n, aligned to the left, with an optional left and right bor‐
1791         der.  Has no effect on other values.  This can be used to align mate‐
1792         rial  in  tables.  Widths are positive integers indicating the number
1793         of characters.  Borders are strings inside double quotes;  literal  "
1794         and \ characters must be backslash-escaped.
1795
1796       · right  n  "leftborder"  "rightborder":  Renders  a textual value in a
1797         block of width n, aligned to the right, and has no  effect  on  other
1798         values.
1799
1800       · center  n  "leftborder"  "rightborder":  Renders a textual value in a
1801         block of width n, aligned to the center, and has no effect  on  other
1802         values.
1803
1804   Variables
1805   Metadata variables
1806       title, author, date
1807              allow identification of basic aspects of the document.  Included
1808              in PDF metadata through LaTeX and ConTeXt.   These  can  be  set
1809              through a pandoc title block, which allows for multiple authors,
1810              or through a YAML metadata block:
1811
1812                     ---
1813                     author:
1814                     - Aristotle
1815                     - Peter Abelard
1816                     ...
1817
1818              Note that if you just want to set PDF or HTML metadata,  without
1819              including  a title block in the document itself, you can set the
1820              title-meta, author-meta, and date-meta variables.   (By  default
1821              these are set automatically, based on title, author, and date.)
1822
1823       subtitle
1824              document  subtitle,  included in HTML, EPUB, LaTeX, ConTeXt, and
1825              docx documents
1826
1827       abstract
1828              document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
1829              documents
1830
1831       keywords
1832              list  of  keywords  to be included in HTML, PDF, ODT, pptx, docx
1833              and AsciiDoc metadata; repeat as for author, above
1834
1835       subject
1836              document subject, included in ODT, PDF, docx and pptx metadata
1837
1838       description
1839              document description, included in ODT, docx and  pptx  metadata.
1840              Some applications show this as Comments metadata.
1841
1842       category
1843              document category, included in docx and pptx metadata
1844
1845       Additionally, any root-level string metadata, not included in ODT, docx
1846       or pptx metadata is added as a custom  property.   The  following  YAML
1847       metadata block for instance:
1848
1849              ---
1850              title:  'This is the title'
1851              subtitle: "This is the subtitle"
1852              author:
1853              - Author One
1854              - Author Two
1855              description: |
1856                  This is a long
1857                  description.
1858
1859                  It consists of two paragraphs
1860              ...
1861
1862       will include title, author and description as standard document proper‐
1863       ties and subtitle as a custom property when converting to docx, ODT  or
1864       pptx.
1865
1866   Language variables
1867       lang   identifies the main language of the document using IETF language
1868              tags (following the BCP 47 standard), such as en or en-GB.   The
1869              Language  subtag  lookup  tool can look up or verify these tags.
1870              This affects most formats, and controls hyphenation in PDF  out‐
1871              put when using LaTeX (through babel and polyglossia) or ConTeXt.
1872
1873              Use  native  pandoc  Divs  and  Spans with the lang attribute to
1874              switch the language:
1875
1876                     ---
1877                     lang: en-GB
1878                     ...
1879
1880                     Text in the main document language (British English).
1881
1882                     ::: {lang=fr-CA}
1883                     > Cette citation est écrite en français canadien.
1884                     :::
1885
1886                     More text in English. ['Zitat auf Deutsch.']{lang=de}
1887
1888       dir    the base script direction, either  rtl  (right-to-left)  or  ltr
1889              (left-to-right).
1890
1891              For  bidirectional  documents, native pandoc spans and divs with
1892              the dir attribute (value rtl or ltr) can be used to override the
1893              base  direction  in some output formats.  This may not always be
1894              necessary if the final renderer (e.g.  the browser, when  gener‐
1895              ating HTML) supports the Unicode Bidirectional Algorithm.
1896
1897              When  using  LaTeX for bidirectional documents, only the xelatex
1898              engine is fully supported (use --pdf-engine=xelatex).
1899
1900   Variables for HTML math
1901       classoption
1902              when using KaTeX, you can render display  math  equations  flush
1903              left using YAML metadata or with -M classoption=fleqn.
1904
1905   Variables for HTML slides
1906       These affect HTML output when producing slide shows with pandoc.
1907
1908       All  reveal.js  configuration  options  are available as variables.  To
1909       turn off boolean flags that default to true in reveal.js, use 0.
1910
1911       revealjs-url
1912              base URL for reveal.js documents (defaults to reveal.js)
1913
1914       s5-url base URL for S5 documents (defaults to s5/default)
1915
1916       slidy-url
1917              base    URL     for     Slidy     documents     (defaults     to
1918              https://www.w3.org/Talks/Tools/Slidy2)
1919
1920       slideous-url
1921              base URL for Slideous documents (defaults to slideous)
1922
1923       title-slide-attributes
1924              additional  attributes  for  the  title slide of reveal.js slide
1925              shows.  See background in reveal.js and beamer for an example.
1926
1927   Variables for Beamer slides
1928       These variables change the appearance of PDF slides using beamer.
1929
1930       aspectratio
1931              slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 1610 for
1932              16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 32 for 3:2)
1933
1934       beamerarticle
1935              produce an article from Beamer slides
1936
1937       beameroption
1938              add extra beamer option with \setbeameroption{}
1939
1940       institute
1941              author  affiliations:  can be a list when there are multiple au‐
1942              thors
1943
1944       logo   logo image for slides
1945
1946       navigation
1947              controls navigation symbols (default is empty for no  navigation
1948              symbols; other valid values are frame, vertical, and horizontal)
1949
1950       section-titles
1951              enables "title pages" for new sections (default is true)
1952
1953       theme, colortheme, fonttheme, innertheme, outertheme
1954              beamer themes
1955
1956       themeoptions
1957              options for LaTeX beamer themes (a list).
1958
1959       titlegraphic
1960              image for title slide
1961
1962   Variables for PowerPoint
1963       These variables control the visual aspects of a slide show that are not
1964       easily controlled via templates.
1965
1966       monofont
1967              font to use for code.
1968
1969   Variables for LaTeX
1970       Pandoc uses these variables when creating a PDF with a LaTeX engine.
1971
1972   Layout
1973       block-headings
1974              make \paragraph and \subparagraph (fourth- and fifth-level head‐
1975              ings, or fifth- and sixth-level with book classes) free-standing
1976              rather than run-in; requires further formatting  to  distinguish
1977              from  \subsubsection (third- or fourth-level headings).  Instead
1978              of using this option, KOMA-Script can adjust headings  more  ex‐
1979              tensively:
1980
1981                     ---
1982                     documentclass: scrartcl
1983                     header-includes: |
1984                       \RedeclareSectionCommand[
1985                         beforeskip=-10pt plus -2pt minus -1pt,
1986                         afterskip=1sp plus -1sp minus 1sp,
1987                         font=\normalfont\itshape]{paragraph}
1988                       \RedeclareSectionCommand[
1989                         beforeskip=-10pt plus -2pt minus -1pt,
1990                         afterskip=1sp plus -1sp minus 1sp,
1991                         font=\normalfont\scshape,
1992                         indent=0pt]{subparagraph}
1993                     ...
1994
1995       classoption
1996              option  for  document  class, e.g.  oneside; repeat for multiple
1997              options:
1998
1999                     ---
2000                     classoption:
2001                     - twocolumn
2002                     - landscape
2003                     ...
2004
2005       documentclass
2006              document class: usually one of the  standard  classes,  article,
2007              book,  and  report;  the KOMA-Script equivalents, scrartcl, scr‐
2008              book, and scrreprt, which default to smaller margins; or memoir
2009
2010       geometry
2011              option for geometry package, e.g.  margin=1in; repeat for multi‐
2012              ple options:
2013
2014                     ---
2015                     geometry:
2016                     - top=30mm
2017                     - left=20mm
2018                     - heightrounded
2019                     ...
2020
2021       hyperrefoptions
2022              option  for hyperref package, e.g.  linktoc=all; repeat for mul‐
2023              tiple options:
2024
2025                     ---
2026                     hyperrefoptions:
2027                     - linktoc=all
2028                     - pdfwindowui
2029                     - pdfpagemode=FullScreen
2030                     ...
2031
2032       indent uses document class settings for indentation (the default  LaTeX
2033              template  otherwise  removes  indentation and adds space between
2034              paragraphs)
2035
2036       linestretch
2037              adjusts line spacing using the setspace package, e.g.  1.25, 1.5
2038
2039       margin-left, margin-right, margin-top, margin-bottom
2040              sets margins if geometry is not used (otherwise  geometry  over‐
2041              rides these)
2042
2043       pagestyle
2044              control  \pagestyle{}:  the default article class supports plain
2045              (default), empty (no running heads or page numbers),  and  head‐
2046              ings (section titles in running heads)
2047
2048       papersize
2049              paper size, e.g.  letter, a4
2050
2051       secnumdepth
2052              numbering  depth  for sections (with --number-sections option or
2053              numbersections variable)
2054
2055   Fonts
2056       fontenc
2057              allows font encoding to be  specified  through  fontenc  package
2058              (with pdflatex); default is T1 (see LaTeX font encodings guide)
2059
2060       fontfamily
2061              font  package  for use with pdflatex: TeX Live includes many op‐
2062              tions, documented in the LaTeX Font Catalogue.  The  default  is
2063              Latin Modern.
2064
2065       fontfamilyoptions
2066              options  for package used as fontfamily; repeat for multiple op‐
2067              tions.  For example, to use the Libertine font with proportional
2068              lowercase (old-style) figures through the libertinus package:
2069
2070                     ---
2071                     fontfamily: libertinus
2072                     fontfamilyoptions:
2073                     - osf
2074                     - p
2075                     ...
2076
2077       fontsize
2078              font size for body text.  The standard classes allow 10pt, 11pt,
2079              and 12pt.  To use another size, set documentclass to one of  the
2080              KOMA-Script classes, such as scrartcl or scrbook.
2081
2082       mainfont, sansfont, monofont, mathfont, CJKmainfont
2083              font families for use with xelatex or lualatex: take the name of
2084              any system font, using the fontspec package.   CJKmainfont  uses
2085              the xecjk package.
2086
2087       mainfontoptions,   sansfontoptions,  monofontoptions,  mathfontoptions,
2088       CJKoptions
2089              options to use with mainfont, sansfont, monofont, mathfont, CJK‐
2090              mainfont  in xelatex and lualatex.  Allow for any choices avail‐
2091              able through fontspec; repeat for multiple options.   For  exam‐
2092              ple, to use the TeX Gyre version of Palatino with lowercase fig‐
2093              ures:
2094
2095                     ---
2096                     mainfont: TeX Gyre Pagella
2097                     mainfontoptions:
2098                     - Numbers=Lowercase
2099                     - Numbers=Proportional
2100                     ...
2101
2102       microtypeoptions
2103              options to pass to the microtype package
2104
2105   Links
2106       colorlinks
2107              add color to link text; automatically enabled if any of linkcol‐
2108              or, filecolor, citecolor, urlcolor, or toccolor are set
2109
2110       linkcolor, filecolor, citecolor, urlcolor, toccolor
2111              color for internal links, external links, citation links, linked
2112              URLs, and links in table of contents, respectively: uses options
2113              allowed  by  xcolor,  including  the  dvipsnames,  svgnames, and
2114              x11names lists
2115
2116       links-as-notes
2117              causes links to be printed as footnotes
2118
2119   Front matter
2120       lof, lot
2121              include list of figures, list of tables
2122
2123       thanks contents of acknowledgments footnote after document title
2124
2125       toc    include table of contents (can also be set using  --toc/--table-
2126              of-contents)
2127
2128       toc-depth
2129              level of section to include in table of contents
2130
2131   BibLaTeX Bibliographies
2132       These variables function when using BibLaTeX for citation rendering.
2133
2134       biblatexoptions
2135              list of options for biblatex
2136
2137       biblio-style
2138              bibliography style, when used with --natbib and --biblatex.
2139
2140       biblio-title
2141              bibliography title, when used with --natbib and --biblatex.
2142
2143       bibliography
2144              bibliography to use for resolving references
2145
2146       natbiboptions
2147              list of options for natbib
2148
2149   Variables for ConTeXt
2150       Pandoc uses these variables when creating a PDF with ConTeXt.
2151
2152       fontsize
2153              font size for body text (e.g.  10pt, 12pt)
2154
2155       headertext, footertext
2156              text to be placed in running header or footer (see ConTeXt Head‐
2157              ers and Footers); repeat up to four times for  different  place‐
2158              ment
2159
2160       indenting
2161              controls  indentation  of  paragraphs, e.g.  yes,small,next (see
2162              ConTeXt Indentation); repeat for multiple options
2163
2164       interlinespace
2165              adjusts line spacing, e.g.  4ex (using setupinterlinespace); re‐
2166              peat for multiple options
2167
2168       layout options  for page margins and text arrangement (see ConTeXt Lay‐
2169              out); repeat for multiple options
2170
2171       linkcolor, contrastcolor
2172              color for links outside and inside a page, e.g.  red, blue  (see
2173              ConTeXt Color)
2174
2175       linkstyle
2176              typeface  style  for  links,  e.g.  normal, bold, slanted, bold‐
2177              slanted, type, cap, small
2178
2179       lof, lot
2180              include list of figures, list of tables
2181
2182       mainfont, sansfont, monofont, mathfont
2183              font families: take the name of any  system  font  (see  ConTeXt
2184              Font Switching)
2185
2186       margin-left, margin-right, margin-top, margin-bottom
2187              sets  margins, if layout is not used (otherwise layout overrides
2188              these)
2189
2190       pagenumbering
2191              page number style and location (using  setuppagenumbering);  re‐
2192              peat for multiple options
2193
2194       papersize
2195              paper  size, e.g.  letter, A4, landscape (see ConTeXt Paper Set‐
2196              up); repeat for multiple options
2197
2198       pdfa   adds to the preamble the setup necessary to  generate  PDF/A  of
2199              the  type specified, e.g.  1a:2005, 2a.  If no type is specified
2200              (i.e.  the value is set to True,  by  e.g.   --metadata=pdfa  or
2201              pdfa:  true  in  a YAML metadata block), 1b:2005 will be used as
2202              default, for reasons of backwards compatibility.  Using  --vari‐
2203              able=pdfa without specified value is not supported.  To success‐
2204              fully generate PDF/A the required ICC color profiles have to  be
2205              available  and  the  content and all included files (such as im‐
2206              ages) have to be standard conforming.  The ICC profiles and out‐
2207              put  intent  may be specified using the variables pdfaiccprofile
2208              and pdfaintent.  See also ConTeXt PDFA for more details.
2209
2210       pdfaiccprofile
2211              when used in conjunction with pdfa, specifies the ICC profile to
2212              use  in  the  PDF,  e.g.   default.cmyk.   If  left unspecified,
2213              sRGB.icc is used as default.  May be repeated to include  multi‐
2214              ple  profiles.   Note  that the profiles have to be available on
2215              the system.  They can be obtained from ConTeXt ICC Profiles.
2216
2217       pdfaintent
2218              when used in conjunction with pdfa, specifies the output  intent
2219              for  the  colors,  e.g.   ISO  coated v2 300\letterpercent\space
2220              (ECI) If left unspecified, sRGB IEC61966-2.1 is used as default.
2221
2222       toc    include table of contents (can also be set using  --toc/--table-
2223              of-contents)
2224
2225       whitespace
2226              spacing  between  paragraphs,  e.g.   none,  small (using setup‐
2227              whitespace)
2228
2229       includesource
2230              include all source documents as file attachments in the PDF file
2231
2232   Variables for wkhtmltopdf
2233       Pandoc uses these variables when creating a PDF with wkhtmltopdf.   The
2234       --css option also affects the output.
2235
2236       footer-html, header-html
2237              add information to the header and footer
2238
2239       margin-left, margin-right, margin-top, margin-bottom
2240              set the page margins
2241
2242       papersize
2243              sets the PDF paper size
2244
2245   Variables for man pages
2246       adjusting
2247              adjusts  text  to  left  (l), right (r), center (c), or both (b)
2248              margins
2249
2250       footer footer in man pages
2251
2252       header header in man pages
2253
2254       hyphenate
2255              if true (the default), hyphenation will be used
2256
2257       section
2258              section number in man pages
2259
2260   Variables for ms
2261       fontfamily
2262              font family (e.g.  T or P)
2263
2264       indent paragraph indent (e.g.  2m)
2265
2266       lineheight
2267              line height (e.g.  12p)
2268
2269       pointsize
2270              point size (e.g.  10p)
2271
2272   Variables set automatically
2273       Pandoc sets these variables automatically in  response  to  options  or
2274       document contents; users can also modify them.  These vary depending on
2275       the output format, and include the following:
2276
2277       body   body of document
2278
2279       date-meta
2280              the date variable converted to ISO 8601 YYYY-MM-DD, included  in
2281              all  HTML based formats (dzslides, epub, html, html4, html5, re‐
2282              vealjs, s5, slideous, slidy).  The recognized formats  for  date
2283              are:  mm/dd/yyyy,  mm/dd/yy,  yyyy-mm-dd  (ISO 8601), dd MM yyyy
2284              (e.g.  either 02 Apr 2018 or 02 April 2018), MM dd,  yyyy  (e.g.
2285              Apr.  02,  2018  or  April 02, 2018),yyyy[mm[dd]]](e.g.20180402,
2286              201804 or 2018).
2287
2288       header-includes
2289              contents specified by -H/--include-in-header (may have  multiple
2290              values)
2291
2292       include-before
2293              contents  specified by -B/--include-before-body (may have multi‐
2294              ple values)
2295
2296       include-after
2297              contents specified by -A/--include-after-body (may have multiple
2298              values)
2299
2300       meta-json
2301              JSON  representation  of  all of the document's metadata.  Field
2302              values are transformed to the selected output format.
2303
2304       numbersections
2305              non-null value if -N/--number-sections was specified
2306
2307       sourcefile, outputfile
2308              source and destination filenames, as given on the command  line.
2309              sourcefile  can  also  be  a  list  if input comes from multiple
2310              files, or empty if input is from stdin.  You can use the follow‐
2311              ing snippet in your template to distinguish them:
2312
2313                     $if(sourcefile)$
2314                     $for(sourcefile)$
2315                     $sourcefile$
2316                     $endfor$
2317                     $else$
2318                     (stdin)
2319                     $endif$
2320
2321              Similarly, outputfile can be - if output goes to the terminal.
2322
2323              If you need absolute paths, use e.g.  $curdir$/$sourcefile$.
2324
2325       curdir working directory from which pandoc is run.
2326
2327       toc    non-null value if --toc/--table-of-contents was specified
2328
2329       toc-title
2330              title of table of contents (works only with EPUB, HTML, opendoc‐
2331              ument, odt, docx, pptx, beamer, LaTeX)
2332

EXTENSIONS

2334       The behavior of some of the readers and writers can be adjusted by  en‐
2335       abling or disabling various extensions.
2336
2337       An extension can be enabled by adding +EXTENSION to the format name and
2338       disabled   by   adding   -EXTENSION.    For   example,   --from   mark‐
2339       down_strict+footnotes  is strict Markdown with footnotes enabled, while
2340       --from  markdown-footnotes-pipe_tables  is  pandoc's  Markdown  without
2341       footnotes or pipe tables.
2342
2343       The  markdown reader and writer make by far the most use of extensions.
2344       Extensions only used by them are therefore covered in the section  Pan‐
2345       doc's Markdown below (See Markdown variants for commonmark and gfm.) In
2346       the following, extensions that also work for other formats are covered.
2347
2348       Note that markdown extensions added to the ipynb format affect Markdown
2349       cells in Jupyter notebooks (as do command-line options like --atx-head‐
2350       ers).
2351
2352   Typography
2353   Extension: smart
2354       Interpret straight quotes as curly quotes, --- as em-dashes, -- as  en-
2355       dashes,  and  ...  as  ellipses.  Nonbreaking spaces are inserted after
2356       certain abbreviations, such as "Mr."
2357
2358       This extension can be enabled/disabled for the following formats:
2359
2360       input formats
2361              markdown, commonmark, latex, mediawiki, org, rst, twiki
2362
2363       output formats
2364              markdown, latex, context, rst
2365
2366       enabled by default in
2367              markdown, latex, context (both input and output)
2368
2369       Note: If you are writing Markdown, then the smart extension has the re‐
2370       verse effect: what would have been curly quotes comes out straight.
2371
2372       In  LaTeX,  smart means to use the standard TeX ligatures for quotation
2373       marks (`` and '' for double quotes, ` and  '  for  single  quotes)  and
2374       dashes  (--  for  en-dash  and --- for em-dash).  If smart is disabled,
2375       then in reading LaTeX pandoc will parse these characters literally.  In
2376       writing  LaTeX,  enabling  smart tells pandoc to use the ligatures when
2377       possible; if smart is disabled pandoc will use unicode  quotation  mark
2378       and dash characters.
2379
2380   Headings and sections
2381   Extension: auto_identifiers
2382       A  heading without an explicitly specified identifier will be automati‐
2383       cally assigned a unique identifier based on the heading text.
2384
2385       This extension can be enabled/disabled for the following formats:
2386
2387       input formats
2388              markdown, latex, rst, mediawiki, textile
2389
2390       output formats
2391              markdown, muse
2392
2393       enabled by default in
2394              markdown, muse
2395
2396       The default algorithm used to derive the identifier  from  the  heading
2397       text is:
2398
2399       · Remove all formatting, links, etc.
2400
2401       · Remove all footnotes.
2402
2403       · Remove  all non-alphanumeric characters, except underscores, hyphens,
2404         and periods.
2405
2406       · Replace all spaces and newlines with hyphens.
2407
2408       · Convert all alphabetic characters to lowercase.
2409
2410       · Remove everything up to the first letter (identifiers may  not  begin
2411         with a number or punctuation mark).
2412
2413       · If nothing is left after this, use the identifier section.
2414
2415       Thus, for example,
2416
2417       Heading                      Identifier
2418       ─────────────────────────────────────────────────────
2419       Heading   identifiers   in   heading-identifiers-in-
2420       HTML                         html
2421       Maître d'hôtel               maître-dhôtel
2422       *Dogs*?--in *my* house?      dogs--in-my-house
2423       [HTML], [S5], or [RTF]?      html-s5-or-rtf
2424       3. Applications              applications
2425       33                           section
2426
2427       These rules should, in most cases, allow one to determine the identifi‐
2428       er from the heading text.  The exception is when several headings  have
2429       the  same  text;  in this case, the first will get an identifier as de‐
2430       scribed above; the second will get the same identifier with -1  append‐
2431       ed; the third with -2; and so on.
2432
2433       (However,  a different algorithm is used if gfm_auto_identifiers is en‐
2434       abled; see below.)
2435
2436       These identifiers are used to provide link targets in the table of con‐
2437       tents  generated  by  the  --toc|--table-of-contents option.  They also
2438       make it easy to provide links from one section of a document to  anoth‐
2439       er.  A link to this section, for example, might look like this:
2440
2441              See the section on
2442              [heading identifiers](#heading-identifiers-in-html-latex-and-context).
2443
2444       Note,  however,  that  this method of providing links to sections works
2445       only in HTML, LaTeX, and ConTeXt formats.
2446
2447       If the --section-divs option is specified, then each  section  will  be
2448       wrapped  in a section (or a div, if html4 was specified), and the iden‐
2449       tifier will be attached to  the  enclosing  <section>  (or  <div>)  tag
2450       rather  than the heading itself.  This allows entire sections to be ma‐
2451       nipulated using JavaScript or treated differently in CSS.
2452
2453   Extension: ascii_identifiers
2454       Causes the identifiers produced by auto_identifiers to be  pure  ASCII.
2455       Accents  are stripped off of accented Latin letters, and non-Latin let‐
2456       ters are omitted.
2457
2458   Extension: gfm_auto_identifiers
2459       Changes the algorithm used by auto_identifiers to conform  to  GitHub's
2460       method.   Spaces  are  converted to dashes (-), uppercase characters to
2461       lowercase characters, and punctuation characters other than - and _ are
2462       removed.  Emojis are replaced by their names.
2463
2464   Math Input
2465       The   extensions   tex_math_dollars,   tex_math_single_backslash,   and
2466       tex_math_double_backslash are described in the section  about  Pandoc's
2467       Markdown.
2468
2469       However,  they  can  also  be  used with HTML input.  This is handy for
2470       reading web pages formatted using MathJax, for example.
2471
2472   Raw HTML/TeX
2473       The following extensions  (especially  how  they  affect  Markdown  in‐
2474       put/output)  are also described in more detail in their respective sec‐
2475       tions of Pandoc's Markdown.
2476
2477   Extension: raw_html
2478       When converting from HTML, parse elements to raw  HTML  which  are  not
2479       representable  in  pandoc's AST.  By default, this is disabled for HTML
2480       input.
2481
2482   Extension: raw_tex
2483       Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
2484
2485       This extension can be enabled/disabled for the  following  formats  (in
2486       addition to markdown):
2487
2488       input formats
2489              latex, org, textile, html (environments, \ref, and \eqref only),
2490              ipynb
2491
2492       output formats
2493              textile, commonmark
2494
2495       Note: as applied to ipynb, raw_html and raw_tex affect not only raw TeX
2496       in  markdown  cells, but data with mime type text/html in output cells.
2497       Since the ipynb reader attempts to preserve the richest  possible  out‐
2498       puts  when  several options are given, you will get best results if you
2499       disable raw_html and raw_tex when converting to formats like docx which
2500       don't allow raw html or tex.
2501
2502   Extension: native_divs
2503       This  extension  is enabled by default for HTML input.  This means that
2504       divs are parsed to pandoc native  elements.   (Alternatively,  you  can
2505       parse them to raw HTML using -f html-native_divs+raw_html.)
2506
2507       When converting HTML to Markdown, for example, you may want to drop all
2508       divs and spans:
2509
2510              pandoc -f html-native_divs-native_spans -t markdown
2511
2512   Extension: native_spans
2513       Analogous to native_divs above.
2514
2515   Literate Haskell support
2516   Extension: literate_haskell
2517       Treat the document as literate Haskell source.
2518
2519       This extension can be enabled/disabled for the following formats:
2520
2521       input formats
2522              markdown, rst, latex
2523
2524       output formats
2525              markdown, rst, latex, html
2526
2527       If you append +lhs (or +literate_haskell) to one of the formats  above,
2528       pandoc  will treat the document as literate Haskell source.  This means
2529       that
2530
2531       · In Markdown input, "bird track" sections will be  parsed  as  Haskell
2532         code  rather  than  block  quotations.  Text between \begin{code} and
2533         \end{code} will also be treated as Haskell code.  For ATX-style head‐
2534         ings the character '=' will be used instead of '#'.
2535
2536       · In  Markdown  output,  code  blocks with classes haskell and literate
2537         will be rendered using bird tracks, and block quotations will be  in‐
2538         dented  one  space,  so they will not be treated as Haskell code.  In
2539         addition, headings will be rendered  setext-style  (with  underlines)
2540         rather  than  ATX-style  (with '#' characters).  (This is because ghc
2541         treats '#' characters in column 1 as introducing line numbers.)
2542
2543       · In restructured text input, "bird track" sections will be  parsed  as
2544         Haskell code.
2545
2546       · In  restructured  text output, code blocks with class haskell will be
2547         rendered using bird tracks.
2548
2549       · In LaTeX input, text in code environments will be parsed  as  Haskell
2550         code.
2551
2552       · In  LaTeX output, code blocks with class haskell will be rendered in‐
2553         side code environments.
2554
2555       · In HTML output, code blocks with class haskell will be rendered  with
2556         class literatehaskell and bird tracks.
2557
2558       Examples:
2559
2560              pandoc -f markdown+lhs -t html
2561
2562       reads  literate  Haskell source formatted with Markdown conventions and
2563       writes ordinary HTML (without bird tracks).
2564
2565              pandoc -f markdown+lhs -t html+lhs
2566
2567       writes HTML with the Haskell code in bird tracks, so it can  be  copied
2568       and pasted as literate Haskell source.
2569
2570       Note  that GHC expects the bird tracks in the first column, so indented
2571       literate code blocks (e.g.  inside an itemized environment) will not be
2572       picked up by the Haskell compiler.
2573
2574   Other extensions
2575   Extension: empty_paragraphs
2576       Allows empty paragraphs.  By default empty paragraphs are omitted.
2577
2578       This extension can be enabled/disabled for the following formats:
2579
2580       input formats
2581              docx, html
2582
2583       output formats
2584              docx, odt, opendocument, html
2585
2586   Extension: native_numbering
2587       Enables  native numbering of figures and tables.  Enumeration starts at
2588       1.
2589
2590       This extension can be enabled/disabled for the following formats:
2591
2592       output formats
2593              odt, opendocument
2594
2595   Extension: styles
2596       When converting from docx, read all docx styles as divs (for  paragraph
2597       styles)  and  spans (for character styles) regardless of whether pandoc
2598       understands the meaning of these styles.  This can be  used  with  docx
2599       custom styles.  Disabled by default.
2600
2601       input formats
2602              docx
2603
2604   Extension: amuse
2605       In  the muse input format, this enables Text::Amuse extensions to Emacs
2606       Muse markup.
2607
2608   Extension: citations
2609       Some aspects of Pandoc's Markdown citation syntax are also accepted  in
2610       org input.
2611
2612   Extension: ntb
2613       In  the  context  output  format this enables the use of Natural Tables
2614       (TABLE) instead of the default Extreme Tables (xtables).   Natural  ta‐
2615       bles allow more fine-grained global customization but come at a perfor‐
2616       mance penalty compared to extreme tables.
2617

PANDOC'S MARKDOWN

2619       Pandoc understands an extended and slightly  revised  version  of  John
2620       Gruber's  Markdown  syntax.   This document explains the syntax, noting
2621       differences from standard Markdown.  Except where noted, these  differ‐
2622       ences  can be suppressed by using the markdown_strict format instead of
2623       markdown.  Extensions can be enabled or disabled to specify the  behav‐
2624       ior  more  granularly.   They are described in the following.  See also
2625       Extensions above, for extensions that work also on other formats.
2626
2627   Philosophy
2628       Markdown is designed to be easy to write, and, even  more  importantly,
2629       easy to read:
2630
2631              A  Markdown-formatted  document  should be publishable as-is, as
2632              plain text, without looking like it's been marked up  with  tags
2633              or formatting instructions.  -- John Gruber
2634
2635       This  principle has guided pandoc's decisions in finding syntax for ta‐
2636       bles, footnotes, and other extensions.
2637
2638       There is, however, one respect in which  pandoc's  aims  are  different
2639       from  the  original  aims of Markdown.  Whereas Markdown was originally
2640       designed with HTML generation in mind, pandoc is designed for  multiple
2641       output  formats.   Thus, while pandoc allows the embedding of raw HTML,
2642       it discourages it, and provides other, non-HTMLish ways of representing
2643       important document elements like definition lists, tables, mathematics,
2644       and footnotes.
2645
2646   Paragraphs
2647       A paragraph is one or more lines of text followed by one or more  blank
2648       lines.   Newlines  are  treated as spaces, so you can reflow your para‐
2649       graphs as you like.  If you need a hard line break,  put  two  or  more
2650       spaces at the end of a line.
2651
2652   Extension: escaped_line_breaks
2653       A  backslash followed by a newline is also a hard line break.  Note: in
2654       multiline and grid table cells, this is the only way to create  a  hard
2655       line break, since trailing spaces in the cells are ignored.
2656
2657   Headings
2658       There are two kinds of headings: Setext and ATX.
2659
2660   Setext-style headings
2661       A  setext-style  heading is a line of text "underlined" with a row of =
2662       signs (for a level-one heading) or - signs (for a level-two heading):
2663
2664              A level-one heading
2665              ===================
2666
2667              A level-two heading
2668              -------------------
2669
2670       The heading text can contain inline formatting, such as  emphasis  (see
2671       Inline formatting, below).
2672
2673   ATX-style headings
2674       An ATX-style heading consists of one to six # signs and a line of text,
2675       optionally followed by any number of # signs.  The number of # signs at
2676       the beginning of the line is the heading level:
2677
2678              ## A level-two heading
2679
2680              ### A level-three heading ###
2681
2682       As with setext-style headings, the heading text can contain formatting:
2683
2684              # A level-one heading with a [link](/url) and *emphasis*
2685
2686   Extension: blank_before_header
2687       Standard  Markdown  syntax does not require a blank line before a head‐
2688       ing.  Pandoc does require this (except, of course, at the beginning  of
2689       the  document).   The  reason for the requirement is that it is all too
2690       easy for a # to end up at the beginning of a line by accident  (perhaps
2691       through line wrapping).  Consider, for example:
2692
2693              I like several of their flavors of ice cream:
2694              #22, for example, and #5.
2695
2696   Extension: space_in_atx_header
2697       Many  Markdown implementations do not require a space between the open‐
2698       ing #s of an ATX heading and the heading text,  so  that  #5  bolt  and
2699       #hashtag  count  as headings.  With this extension, pandoc does require
2700       the space.
2701
2702   Heading identifiers
2703       See also the auto_identifiers extension above.
2704
2705   Extension: header_attributes
2706       Headings can be assigned attributes using this syntax at the end of the
2707       line containing the heading text:
2708
2709              {#identifier .class .class key=value key=value}
2710
2711       Thus,  for  example,  the  following  headings will all be assigned the
2712       identifier foo:
2713
2714              # My heading {#foo}
2715
2716              ## My heading ##    {#foo}
2717
2718              My other heading   {#foo}
2719              ---------------
2720
2721       (This syntax is compatible with PHP Markdown Extra.)
2722
2723       Note that  although  this  syntax  allows  assignment  of  classes  and
2724       key/value  attributes, writers generally don't use all of this informa‐
2725       tion.  Identifiers, classes, and key/value attributes are used in  HTML
2726       and  HTML-based  formats  such as EPUB and slidy.  Identifiers are used
2727       for labels and link  anchors  in  the  LaTeX,  ConTeXt,  Textile,  Jira
2728       markup, and AsciiDoc writers.
2729
2730       Headings with the class unnumbered will not be numbered, even if --num‐
2731       ber-sections is specified.  A single hyphen (-) in an attribute context
2732       is  equivalent to .unnumbered, and preferable in non-English documents.
2733       So,
2734
2735              # My heading {-}
2736
2737       is just the same as
2738
2739              # My heading {.unnumbered}
2740
2741       If the unlisted class is present in addition to unnumbered, the heading
2742       will  not  be included in a table of contents.  (Currently this feature
2743       is only implemented for certain formats: those based on LaTeX and HTML,
2744       PowerPoint, and RTF.)
2745
2746   Extension: implicit_header_references
2747       Pandoc  behaves  as if reference links have been defined for each head‐
2748       ing.  So, to link to a heading
2749
2750              # Heading identifiers in HTML
2751
2752       you can simply write
2753
2754              [Heading identifiers in HTML]
2755
2756       or
2757
2758              [Heading identifiers in HTML][]
2759
2760       or
2761
2762              [the section on heading identifiers][heading identifiers in
2763              HTML]
2764
2765       instead of giving the identifier explicitly:
2766
2767              [Heading identifiers in HTML](#heading-identifiers-in-html)
2768
2769       If there are multiple headings with identical text,  the  corresponding
2770       reference will link to the first one only, and you will need to use ex‐
2771       plicit links to link to the others, as described above.
2772
2773       Like regular reference links, these references are case-insensitive.
2774
2775       Explicit link reference definitions always take priority over  implicit
2776       heading  references.  So, in the following example, the link will point
2777       to bar, not to #foo:
2778
2779              # Foo
2780
2781              [foo]: bar
2782
2783              See [foo]
2784
2785   Block quotations
2786       Markdown uses email conventions for quoting blocks of  text.   A  block
2787       quotation  is  one  or more paragraphs or other block elements (such as
2788       lists or headings), with each line preceded by a > character and an op‐
2789       tional  space.  (The > need not start at the left margin, but it should
2790       not be indented more than three spaces.)
2791
2792              > This is a block quote. This
2793              > paragraph has two lines.
2794              >
2795              > 1. This is a list inside a block quote.
2796              > 2. Second item.
2797
2798       A "lazy" form, which requires the > character only on the first line of
2799       each block, is also allowed:
2800
2801              > This is a block quote. This
2802              paragraph has two lines.
2803
2804              > 1. This is a list inside a block quote.
2805              2. Second item.
2806
2807       Among  the  block  elements  that can be contained in a block quote are
2808       other block quotes.  That is, block quotes can be nested:
2809
2810              > This is a block quote.
2811              >
2812              > > A block quote within a block quote.
2813
2814       If the > character is followed by an optional space, that space will be
2815       considered  part of the block quote marker and not part of the indenta‐
2816       tion of the contents.  Thus, to put an indented code block in  a  block
2817       quote, you need five spaces after the >:
2818
2819              >     code
2820
2821   Extension: blank_before_blockquote
2822       Standard  Markdown  syntax does not require a blank line before a block
2823       quote.  Pandoc does require this (except, of course, at  the  beginning
2824       of the document).  The reason for the requirement is that it is all too
2825       easy for a > to end up at the beginning of a line by accident  (perhaps
2826       through line wrapping).  So, unless the markdown_strict format is used,
2827       the following does not produce a nested block quote in pandoc:
2828
2829              > This is a block quote.
2830              >> Nested.
2831
2832   Verbatim (code) blocks
2833   Indented code blocks
2834       A block of text indented four spaces (or one tab) is treated as  verba‐
2835       tim  text:  that  is, special characters do not trigger special format‐
2836       ting, and all spaces and line breaks are preserved.  For example,
2837
2838                  if (a > 3) {
2839                    moveShip(5 * gravity, DOWN);
2840                  }
2841
2842       The initial (four space or one tab) indentation is not considered  part
2843       of the verbatim text, and is removed in the output.
2844
2845       Note: blank lines in the verbatim text need not begin with four spaces.
2846
2847   Fenced code blocks
2848   Extension: fenced_code_blocks
2849       In  addition  to  standard indented code blocks, pandoc supports fenced
2850       code blocks.  These begin with a row of three or more  tildes  (~)  and
2851       end  with a row of tildes that must be at least as long as the starting
2852       row.  Everything between these lines is treated as code.   No  indenta‐
2853       tion is necessary:
2854
2855              ~~~~~~~
2856              if (a > 3) {
2857                moveShip(5 * gravity, DOWN);
2858              }
2859              ~~~~~~~
2860
2861       Like  regular  code  blocks,  fenced code blocks must be separated from
2862       surrounding text by blank lines.
2863
2864       If the code itself contains a row of tildes or backticks,  just  use  a
2865       longer row of tildes or backticks at the start and end:
2866
2867              ~~~~~~~~~~~~~~~~
2868              ~~~~~~~~~~
2869              code including tildes
2870              ~~~~~~~~~~
2871              ~~~~~~~~~~~~~~~~
2872
2873   Extension: backtick_code_blocks
2874       Same  as  fenced_code_blocks,  but uses backticks (`) instead of tildes
2875       (~).
2876
2877   Extension: fenced_code_attributes
2878       Optionally, you may attach attributes to fenced or backtick code  block
2879       using this syntax:
2880
2881              ~~~~ {#mycode .haskell .numberLines startFrom="100"}
2882              qsort []     = []
2883              qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
2884                             qsort (filter (>= x) xs)
2885              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2886
2887       Here  mycode is an identifier, haskell and numberLines are classes, and
2888       startFrom is an attribute with value 100.  Some output formats can  use
2889       this information to do syntax highlighting.  Currently, the only output
2890       formats that uses this information are HTML, LaTeX, Docx, Ms, and  Pow‐
2891       erPoint.   If highlighting is supported for your output format and lan‐
2892       guage, then the code block above will appear highlighted, with numbered
2893       lines.  (To see which languages are supported, type pandoc --list-high‐
2894       light-languages.) Otherwise, the code block above will appear  as  fol‐
2895       lows:
2896
2897              <pre id="mycode" class="haskell numberLines" startFrom="100">
2898                <code>
2899                ...
2900                </code>
2901              </pre>
2902
2903       The  numberLines  (or  number-lines)  class will cause the lines of the
2904       code block to be numbered, starting with 1 or the value of  the  start‐
2905       From attribute.  The lineAnchors (or line-anchors) class will cause the
2906       lines to be clickable anchors in HTML output.
2907
2908       A shortcut form can also be used for specifying  the  language  of  the
2909       code block:
2910
2911              ```haskell
2912              qsort [] = []
2913              ```
2914
2915       This is equivalent to:
2916
2917              ``` {.haskell}
2918              qsort [] = []
2919              ```
2920
2921       If the fenced_code_attributes extension is disabled, but input contains
2922       class attribute(s) for the code block, the first class  attribute  will
2923       be printed after the opening fence as a bare word.
2924
2925       To  prevent  all highlighting, use the --no-highlight flag.  To set the
2926       highlighting style, use --highlight-style.   For  more  information  on
2927       highlighting, see Syntax highlighting, below.
2928
2929   Line blocks
2930   Extension: line_blocks
2931       A  line  block is a sequence of lines beginning with a vertical bar (|)
2932       followed by a space.  The division into lines will be preserved in  the
2933       output,  as  will any leading spaces; otherwise, the lines will be for‐
2934       matted as Markdown.  This is useful for verse and addresses:
2935
2936              | The limerick packs laughs anatomical
2937              | In space that is quite economical.
2938              |    But the good ones I've seen
2939              |    So seldom are clean
2940              | And the clean ones so seldom are comical
2941
2942              | 200 Main St.
2943              | Berkeley, CA 94718
2944
2945       The lines can be hard-wrapped if needed, but the continuation line must
2946       begin with a space.
2947
2948              | The Right Honorable Most Venerable and Righteous Samuel L.
2949                Constable, Jr.
2950              | 200 Main St.
2951              | Berkeley, CA 94718
2952
2953       This syntax is borrowed from reStructuredText.
2954
2955   Lists
2956   Bullet lists
2957       A  bullet  list is a list of bulleted list items.  A bulleted list item
2958       begins with a bullet (*, +, or -).  Here is a simple example:
2959
2960              * one
2961              * two
2962              * three
2963
2964       This will produce a "compact" list.  If you want  a  "loose"  list,  in
2965       which  each  item  is  formatted as a paragraph, put spaces between the
2966       items:
2967
2968              * one
2969
2970              * two
2971
2972              * three
2973
2974       The bullets need not be flush with the left margin; they may be indent‐
2975       ed  one,  two,  or three spaces.  The bullet must be followed by white‐
2976       space.
2977
2978       List items look best if subsequent lines are flush with the first  line
2979       (after the bullet):
2980
2981              * here is my first
2982                list item.
2983              * and my second.
2984
2985       But Markdown also allows a "lazy" format:
2986
2987              * here is my first
2988              list item.
2989              * and my second.
2990
2991   Block content in list items
2992       A  list item may contain multiple paragraphs and other block-level con‐
2993       tent.  However, subsequent paragraphs must be preceded by a blank  line
2994       and indented to line up with the first non-space content after the list
2995       marker.
2996
2997                * First paragraph.
2998
2999                  Continued.
3000
3001                * Second paragraph. With a code block, which must be indented
3002                  eight spaces:
3003
3004                      { code }
3005
3006       Exception: if the list marker is followed by an  indented  code  block,
3007       which  must begin 5 spaces after the list marker, then subsequent para‐
3008       graphs must begin two columns after the  last  character  of  the  list
3009       marker:
3010
3011              *     code
3012
3013                continuation paragraph
3014
3015       List  items  may include other lists.  In this case the preceding blank
3016       line is optional.  The nested list must be indented to line up with the
3017       first  non-space character after the list marker of the containing list
3018       item.
3019
3020              * fruits
3021                + apples
3022                  - macintosh
3023                  - red delicious
3024                + pears
3025                + peaches
3026              * vegetables
3027                + broccoli
3028                + chard
3029
3030       As noted above, Markdown allows you to write list items  "lazily,"  in‐
3031       stead  of indenting continuation lines.  However, if there are multiple
3032       paragraphs or other blocks in a list item, the first line of each  must
3033       be indented.
3034
3035              + A lazy, lazy, list
3036              item.
3037
3038              + Another one; this looks
3039              bad but is legal.
3040
3041                  Second paragraph of second
3042              list item.
3043
3044   Ordered lists
3045       Ordered  lists work just like bulleted lists, except that the items be‐
3046       gin with enumerators rather than bullets.
3047
3048       In standard Markdown, enumerators are decimal numbers followed by a pe‐
3049       riod  and  a space.  The numbers themselves are ignored, so there is no
3050       difference between this list:
3051
3052              1.  one
3053              2.  two
3054              3.  three
3055
3056       and this one:
3057
3058              5.  one
3059              7.  two
3060              1.  three
3061
3062   Extension: fancy_lists
3063       Unlike standard Markdown, pandoc allows ordered list items to be marked
3064       with uppercase and lowercase letters and roman numerals, in addition to
3065       Arabic numerals.  List markers may be enclosed in parentheses  or  fol‐
3066       lowed  by a single right-parentheses or period.  They must be separated
3067       from the text that follows by at least one  space,  and,  if  the  list
3068       marker is a capital letter with a period, by at least two spaces.
3069
3070       The fancy_lists extension also allows '#' to be used as an ordered list
3071       marker in place of a numeral:
3072
3073              #. one
3074              #. two
3075
3076   Extension: startnum
3077       Pandoc also pays attention to the type of list marker used, and to  the
3078       starting  number, and both of these are preserved where possible in the
3079       output format.  Thus, the following yields a list with numbers followed
3080       by  a single parenthesis, starting with 9, and a sublist with lowercase
3081       roman numerals:
3082
3083               9)  Ninth
3084              10)  Tenth
3085              11)  Eleventh
3086                     i. subone
3087                    ii. subtwo
3088                   iii. subthree
3089
3090       Pandoc will start a new list each time a different type of list  marker
3091       is used.  So, the following will create three lists:
3092
3093              (2) Two
3094              (5) Three
3095              1.  Four
3096              *   Five
3097
3098       If default list markers are desired, use #.:
3099
3100              #.  one
3101              #.  two
3102              #.  three
3103
3104   Extension: task_lists
3105       Pandoc  supports  task lists, using the syntax of GitHub-Flavored Mark‐
3106       down.
3107
3108              - [ ] an unchecked task list item
3109              - [x] checked item
3110
3111   Definition lists
3112   Extension: definition_lists
3113       Pandoc supports definition lists, using the syntax of PHP Markdown  Ex‐
3114       tra with some extensions.
3115
3116              Term 1
3117
3118              :   Definition 1
3119
3120              Term 2 with *inline markup*
3121
3122              :   Definition 2
3123
3124                      { some code, part of Definition 2 }
3125
3126                  Third paragraph of definition 2.
3127
3128       Each  term  must fit on one line, which may optionally be followed by a
3129       blank line, and must be followed by one or more definitions.  A defini‐
3130       tion  begins  with  a  colon or tilde, which may be indented one or two
3131       spaces.
3132
3133       A term may have multiple definitions, and each definition  may  consist
3134       of one or more block elements (paragraph, code block, list, etc.), each
3135       indented four spaces or one tab stop.  The body of the definition  (in‐
3136       cluding  the  first  line, aside from the colon or tilde) should be in‐
3137       dented four spaces.  However, as with other  Markdown  lists,  you  can
3138       "lazily"  omit  indentation  except  at the beginning of a paragraph or
3139       other block element:
3140
3141              Term 1
3142
3143              :   Definition
3144              with lazy continuation.
3145
3146                  Second paragraph of the definition.
3147
3148       If you leave space before the definition (as in the example above), the
3149       text  of the definition will be treated as a paragraph.  In some output
3150       formats, this will mean greater spacing between term/definition  pairs.
3151       For  a  more compact definition list, omit the space before the defini‐
3152       tion:
3153
3154              Term 1
3155                ~ Definition 1
3156
3157              Term 2
3158                ~ Definition 2a
3159                ~ Definition 2b
3160
3161       Note that space between items in a definition  list  is  required.   (A
3162       variant  that loosens this requirement, but disallows "lazy" hard wrap‐
3163       ping, can be activated with  compact_definition_lists:  see  Non-pandoc
3164       extensions, below.)
3165
3166   Numbered example lists
3167   Extension: example_lists
3168       The  special  list marker @ can be used for sequentially numbered exam‐
3169       ples.  The first list item with a @ marker will be  numbered  '1',  the
3170       next  '2',  and  so on, throughout the document.  The numbered examples
3171       need not occur in a single list; each new list using  @  will  take  up
3172       where the last stopped.  So, for example:
3173
3174              (@)  My first example will be numbered (1).
3175              (@)  My second example will be numbered (2).
3176
3177              Explanation of examples.
3178
3179              (@)  My third example will be numbered (3).
3180
3181       Numbered examples can be labeled and referred to elsewhere in the docu‐
3182       ment:
3183
3184              (@good)  This is a good example.
3185
3186              As (@good) illustrates, ...
3187
3188       The label can be any string of alphanumeric characters, underscores, or
3189       hyphens.
3190
3191       Note:  continuation paragraphs in example lists must always be indented
3192       four spaces, regardless of the length of the list marker.  That is, ex‐
3193       ample  lists  always behave as if the four_space_rule extension is set.
3194       This is because example labels tend to be long, and  indenting  content
3195       to the first non-space character after the label would be awkward.
3196
3197   Compact and loose lists
3198       Pandoc  behaves  differently  from Markdown.pl on some "edge cases" in‐
3199       volving lists.  Consider this source:
3200
3201              +   First
3202              +   Second:
3203                  -   Fee
3204                  -   Fie
3205                  -   Foe
3206
3207              +   Third
3208
3209       Pandoc transforms this into a "compact list" (with no <p>  tags  around
3210       "First",  "Second",  or  "Third"),  while Markdown puts <p> tags around
3211       "Second" and "Third" (but not "First"),  because  of  the  blank  space
3212       around  "Third".  Pandoc follows a simple rule: if the text is followed
3213       by a blank line, it is treated as a paragraph.  Since "Second" is  fol‐
3214       lowed by a list, and not a blank line, it isn't treated as a paragraph.
3215       The fact that the list is followed  by  a  blank  line  is  irrelevant.
3216       (Note:  Pandoc  works  this way even when the markdown_strict format is
3217       specified.  This behavior is consistent with the official Markdown syn‐
3218       tax description, even though it is different from that of Markdown.pl.)
3219
3220   Ending a list
3221       What if you want to put an indented code block after a list?
3222
3223              -   item one
3224              -   item two
3225
3226                  { my code block }
3227
3228       Trouble! Here pandoc (like other Markdown implementations) will treat {
3229       my code block } as the second paragraph of item two, and not as a  code
3230       block.
3231
3232       To  "cut off" the list after item two, you can insert some non-indented
3233       content, like an HTML comment, which won't produce  visible  output  in
3234       any format:
3235
3236              -   item one
3237              -   item two
3238
3239              <!-- end of list -->
3240
3241                  { my code block }
3242
3243       You can use the same trick if you want two consecutive lists instead of
3244       one big list:
3245
3246              1.  one
3247              2.  two
3248              3.  three
3249
3250              <!-- -->
3251
3252              1.  uno
3253              2.  dos
3254              3.  tres
3255
3256   Horizontal rules
3257       A line containing a row of three or more *, -, or _ characters (option‐
3258       ally separated by spaces) produces a horizontal rule:
3259
3260              *  *  *  *
3261
3262              ---------------
3263
3264   Tables
3265       Four kinds of tables may be used.  The first three kinds presuppose the
3266       use of a fixed-width font, such as Courier.  The  fourth  kind  can  be
3267       used with proportionally spaced fonts, as it does not require lining up
3268       columns.
3269
3270   Extension: table_captions
3271       A caption may optionally be provided with all 4 kinds of tables (as il‐
3272       lustrated  in  the examples below).  A caption is a paragraph beginning
3273       with the string Table: (or just :), which will be stripped off.  It may
3274       appear either before or after the table.
3275
3276   Extension: simple_tables
3277       Simple tables look like this:
3278
3279                Right     Left     Center     Default
3280              -------     ------ ----------   -------
3281                   12     12        12            12
3282                  123     123       123          123
3283                    1     1          1             1
3284
3285              Table:  Demonstration of simple table syntax.
3286
3287       The header and table rows must each fit on one line.  Column alignments
3288       are determined by the position of  the  header  text  relative  to  the
3289       dashed line below it:
3290
3291       · If  the  dashed  line is flush with the header text on the right side
3292         but extends beyond it on the left, the column is right-aligned.
3293
3294       · If the dashed line is flush with the header text on the left side but
3295         extends beyond it on the right, the column is left-aligned.
3296
3297       · If  the dashed line extends beyond the header text on both sides, the
3298         column is centered.
3299
3300       · If the dashed line is flush with the header text on both  sides,  the
3301         default alignment is used (in most cases, this will be left).
3302
3303       The table must end with a blank line, or a line of dashes followed by a
3304       blank line.
3305
3306       The column header row may be omitted, provided a dashed line is used to
3307       end the table.  For example:
3308
3309              -------     ------ ----------   -------
3310                   12     12        12             12
3311                  123     123       123           123
3312                    1     1          1              1
3313              -------     ------ ----------   -------
3314
3315       When the header row is omitted, column alignments are determined on the
3316       basis of the first line of the table body.  So, in  the  tables  above,
3317       the  columns  would  be right, left, center, and right aligned, respec‐
3318       tively.
3319
3320   Extension: multiline_tables
3321       Multiline tables allow header and table rows to span multiple lines  of
3322       text (but cells that span multiple columns or rows of the table are not
3323       supported).  Here is an example:
3324
3325              -------------------------------------------------------------
3326               Centered   Default           Right Left
3327                Header    Aligned         Aligned Aligned
3328              ----------- ------- --------------- -------------------------
3329                 First    row                12.0 Example of a row that
3330                                                  spans multiple lines.
3331
3332                Second    row                 5.0 Here's another one. Note
3333                                                  the blank line between
3334                                                  rows.
3335              -------------------------------------------------------------
3336
3337              Table: Here's the caption. It, too, may span
3338              multiple lines.
3339
3340       These work like simple tables, but with the following differences:
3341
3342       · They must begin with a row of dashes, before the header text  (unless
3343         the header row is omitted).
3344
3345       · They must end with a row of dashes, then a blank line.
3346
3347       · The rows must be separated by blank lines.
3348
3349       In  multiline  tables, the table parser pays attention to the widths of
3350       the columns, and the writers try to reproduce these relative widths  in
3351       the  output.   So, if you find that one of the columns is too narrow in
3352       the output, try widening it in the Markdown source.
3353
3354       The header may be omitted in multiline tables as well as simple tables:
3355
3356              ----------- ------- --------------- -------------------------
3357                 First    row                12.0 Example of a row that
3358                                                  spans multiple lines.
3359
3360                Second    row                 5.0 Here's another one. Note
3361                                                  the blank line between
3362                                                  rows.
3363              ----------- ------- --------------- -------------------------
3364
3365              : Here's a multiline table without a header.
3366
3367       It is possible for a multiline table to have just one row, but the  row
3368       should  be  followed  by  a blank line (and then the row of dashes that
3369       ends the table), or the table may be interpreted as a simple table.
3370
3371   Extension: grid_tables
3372       Grid tables look like this:
3373
3374              : Sample grid table.
3375
3376              +---------------+---------------+--------------------+
3377              | Fruit         | Price         | Advantages         |
3378              +===============+===============+====================+
3379              | Bananas       | $1.34         | - built-in wrapper |
3380              |               |               | - bright color     |
3381              +---------------+---------------+--------------------+
3382              | Oranges       | $2.10         | - cures scurvy     |
3383              |               |               | - tasty            |
3384              +---------------+---------------+--------------------+
3385
3386       The row of =s separates the header from the  table  body,  and  can  be
3387       omitted  for  a headerless table.  The cells of grid tables may contain
3388       arbitrary block elements  (multiple  paragraphs,  code  blocks,  lists,
3389       etc.).   Cells  that  span  multiple columns or rows are not supported.
3390       Grid tables can be created easily using Emacs' table-mode  (M-x  table-
3391       insert).
3392
3393       Alignments  can  be specified as with pipe tables, by putting colons at
3394       the boundaries of the separator line after the header:
3395
3396              +---------------+---------------+--------------------+
3397              | Right         | Left          | Centered           |
3398              +==============:+:==============+:==================:+
3399              | Bananas       | $1.34         | built-in wrapper   |
3400              +---------------+---------------+--------------------+
3401
3402       For headerless tables, the colons go on the top line instead:
3403
3404              +--------------:+:--------------+:------------------:+
3405              | Right         | Left          | Centered           |
3406              +---------------+---------------+--------------------+
3407
3408   Grid Table Limitations
3409       Pandoc does not support grid tables with row  spans  or  column  spans.
3410       This  means  that  neither  variable numbers of columns across rows nor
3411       variable numbers of rows across columns are supported by  Pandoc.   All
3412       grid  tables  must have the same number of columns in each row, and the
3413       same number of rows in each column.  For example, the  Docutils  sample
3414       grid tables will not render as expected with Pandoc.
3415
3416   Extension: pipe_tables
3417       Pipe tables look like this:
3418
3419              | Right | Left | Default | Center |
3420              |------:|:-----|---------|:------:|
3421              |   12  |  12  |    12   |    12  |
3422              |  123  |  123 |   123   |   123  |
3423              |    1  |    1 |     1   |     1  |
3424
3425                : Demonstration of pipe table syntax.
3426
3427       The  syntax  is  identical to PHP Markdown Extra tables.  The beginning
3428       and ending pipe characters are optional, but pipes are required between
3429       all columns.  The colons indicate column alignment as shown.  The head‐
3430       er cannot be omitted.  To simulate a headerless table, include a header
3431       with blank cells.
3432
3433       Since  the pipes indicate column boundaries, columns need not be verti‐
3434       cally aligned, as they are in the above example.  So, this  is  a  per‐
3435       fectly legal (though ugly) pipe table:
3436
3437              fruit| price
3438              -----|-----:
3439              apple|2.05
3440              pear|1.37
3441              orange|3.09
3442
3443       The  cells of pipe tables cannot contain block elements like paragraphs
3444       and lists, and cannot span multiple lines.  If a pipe table contains  a
3445       row  whose printable content is wider than the column width (see --col‐
3446       umns), then the table will take up the full text  width  and  the  cell
3447       contents  will  wrap,  with  the relative cell widths determined by the
3448       number of dashes in the line separating the table header from the table
3449       body.   (For example ---|- would make the first column 3/4 and the sec‐
3450       ond column 1/4 of the full text width.) On the other hand, if no  lines
3451       are  wider  than  column width, then cell contents will not be wrapped,
3452       and the cells will be sized to their contents.
3453
3454       Note: pandoc also recognizes pipe tables of the following form, as  can
3455       be produced by Emacs' orgtbl-mode:
3456
3457              | One | Two   |
3458              |-----+-------|
3459              | my  | table |
3460              | is  | nice  |
3461
3462       The  difference  is that + is used instead of |.  Other orgtbl features
3463       are not supported.  In particular, to get non-default column alignment,
3464       you'll need to add colons as above.
3465
3466   Metadata blocks
3467   Extension: pandoc_title_block
3468       If the file begins with a title block
3469
3470              % title
3471              % author(s) (separated by semicolons)
3472              % date
3473
3474       it  will be parsed as bibliographic information, not regular text.  (It
3475       will be used, for example, in the title of  standalone  LaTeX  or  HTML
3476       output.)  The block may contain just a title, a title and an author, or
3477       all three elements.  If you want to include an author but no title,  or
3478       a title and a date but no author, you need a blank line:
3479
3480              %
3481              % Author
3482
3483              % My title
3484              %
3485              % June 15, 2006
3486
3487       The  title may occupy multiple lines, but continuation lines must begin
3488       with leading space, thus:
3489
3490              % My title
3491                on multiple lines
3492
3493       If a document has multiple authors, the authors may be put on  separate
3494       lines with leading space, or separated by semicolons, or both.  So, all
3495       of the following are equivalent:
3496
3497              % Author One
3498                Author Two
3499
3500              % Author One; Author Two
3501
3502              % Author One;
3503                Author Two
3504
3505       The date must fit on one line.
3506
3507       All three metadata fields may contain standard inline formatting (ital‐
3508       ics, links, footnotes, etc.).
3509
3510       Title blocks will always be parsed, but they will affect the output on‐
3511       ly when the --standalone (-s) option is chosen.  In HTML output, titles
3512       will  appear twice: once in the document head -- this is the title that
3513       will appear at the top of the window in a browser -- and  once  at  the
3514       beginning  of  the  document  body.  The title in the document head can
3515       have an optional prefix attached (--title-prefix or  -T  option).   The
3516       title  in  the  body appears as an H1 element with class "title", so it
3517       can be suppressed or reformatted with CSS.  If a title prefix is speci‐
3518       fied with -T and no title block appears in the document, the title pre‐
3519       fix will be used by itself as the HTML title.
3520
3521       The man page writer extracts a title, man page section number, and oth‐
3522       er header and footer information from the title line.  The title is as‐
3523       sumed to be the first word on the title line, which may optionally  end
3524       with  a (single-digit) section number in parentheses.  (There should be
3525       no space between the title and the parentheses.)  Anything  after  this
3526       is  assumed  to  be  additional  footer and header text.  A single pipe
3527       character (|) should be used to separate the footer text from the head‐
3528       er text.  Thus,
3529
3530              % PANDOC(1)
3531
3532       will yield a man page with the title PANDOC and section 1.
3533
3534              % PANDOC(1) Pandoc User Manuals
3535
3536       will also have "Pandoc User Manuals" in the footer.
3537
3538              % PANDOC(1) Pandoc User Manuals | Version 4.0
3539
3540       will also have "Version 4.0" in the header.
3541
3542   Extension: yaml_metadata_block
3543       A  YAML  metadata  block is a valid YAML object, delimited by a line of
3544       three hyphens (---) at the top and a line of  three  hyphens  (---)  or
3545       three  dots  (...) at the bottom.  A YAML metadata block may occur any‐
3546       where in the document, but if it is not at the beginning,  it  must  be
3547       preceded  by  a blank line.  (Note that, because of the way pandoc con‐
3548       catenates input files when several are provided, you may also keep  the
3549       metadata  in a separate YAML file and pass it to pandoc as an argument,
3550       along with your Markdown files:
3551
3552              pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
3553
3554       Just be sure that the YAML file begins with --- and ends  with  ---  or
3555       ....)  Alternatively,  you  can  use the --metadata-file option.  Using
3556       that approach however, you cannot reference  content  (like  footnotes)
3557       from the main markdown input document.
3558
3559       Metadata  will be taken from the fields of the YAML object and added to
3560       any existing document metadata.  Metadata can contain lists and objects
3561       (nested  arbitrarily),  but  all  string scalars will be interpreted as
3562       Markdown.  Fields with names ending in an underscore will be ignored by
3563       pandoc.  (They may be given a role by external processors.) Field names
3564       must not be interpretable as YAML numbers or boolean  values  (so,  for
3565       example, yes, True, and 15 cannot be used as field names).
3566
3567       A  document  may  contain  multiple  metadata  blocks.  If two metadata
3568       blocks attempt to set the same field, the value from the  second  block
3569       will be taken.
3570
3571       When  pandoc  is used with -t markdown to create a Markdown document, a
3572       YAML metadata block will be produced only if the -s/--standalone option
3573       is  used.  All of the metadata will appear in a single block at the be‐
3574       ginning of the document.
3575
3576       Note that YAML escaping rules must be followed.  Thus, for example,  if
3577       a  title  contains  a colon, it must be quoted.  The pipe character (|)
3578       can be used to begin an indented block that will be interpreted  liter‐
3579       ally, without need for escaping.  This form is necessary when the field
3580       contains blank lines or block-level formatting:
3581
3582              ---
3583              title:  'This is the title: it contains a colon'
3584              author:
3585              - Author One
3586              - Author Two
3587              keywords: [nothing, nothingness]
3588              abstract: |
3589                This is the abstract.
3590
3591                It consists of two paragraphs.
3592              ...
3593
3594       Template variables will be set automatically from the metadata.   Thus,
3595       for  example, in writing HTML, the variable abstract will be set to the
3596       HTML equivalent of the Markdown in the abstract field:
3597
3598              <p>This is the abstract.</p>
3599              <p>It consists of two paragraphs.</p>
3600
3601       Variables can contain arbitrary YAML structures, but the template  must
3602       match this structure.  The author variable in the default templates ex‐
3603       pects a simple list or string, but can be changed to support more  com‐
3604       plicated structures.  The following combination, for example, would add
3605       an affiliation to the author if one is given:
3606
3607              ---
3608              title: The document title
3609              author:
3610              - name: Author One
3611                affiliation: University of Somewhere
3612              - name: Author Two
3613                affiliation: University of Nowhere
3614              ...
3615
3616       To use the structured authors in the example above, you  would  need  a
3617       custom template:
3618
3619              $for(author)$
3620              $if(author.name)$
3621              $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
3622              $else$
3623              $author$
3624              $endif$
3625              $endfor$
3626
3627       Raw  content to include in the document's header may be specified using
3628       header-includes; however, it is important to mark up  this  content  as
3629       raw code for a particular output format, using the raw_attribute exten‐
3630       sion), or it will be interpreted as markdown.  For example:
3631
3632              header-includes:
3633              - |
3634                ```{=latex}
3635                \let\oldsection\section
3636                \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
3637                ```
3638
3639   Backslash escapes
3640   Extension: all_symbols_escapable
3641       Except inside a code block or inline code,  any  punctuation  or  space
3642       character preceded by a backslash will be treated literally, even if it
3643       would normally indicate formatting.  Thus, for example, if one writes
3644
3645              *\*hello\**
3646
3647       one will get
3648
3649              <em>*hello*</em>
3650
3651       instead of
3652
3653              <strong>hello</strong>
3654
3655       This rule is easier to remember than standard  Markdown's  rule,  which
3656       allows only the following characters to be backslash-escaped:
3657
3658              \`*_{}[]()>#+-.!
3659
3660       (However,  if the markdown_strict format is used, the standard Markdown
3661       rule will be used.)
3662
3663       A backslash-escaped space is parsed as a  nonbreaking  space.   In  TeX
3664       output, it will appear as ~.  In HTML and XML output, it will appear as
3665       a literal unicode nonbreaking space character (note that it  will  thus
3666       actually  look  "invisible" in the generated HTML source; you can still
3667       use the --ascii command-line option to make it appear  as  an  explicit
3668       entity).
3669
3670       A  backslash-escaped newline (i.e.  a backslash occurring at the end of
3671       a line) is parsed as a hard line break.  It will appear in  TeX  output
3672       as  \\ and in HTML as <br />.  This is a nice alternative to Markdown's
3673       "invisible" way of indicating hard line breaks using two trailing  spa‐
3674       ces on a line.
3675
3676       Backslash escapes do not work in verbatim contexts.
3677
3678   Inline formatting
3679   Emphasis
3680       To emphasize some text, surround it with *s or _, like this:
3681
3682              This text is _emphasized with underscores_, and this
3683              is *emphasized with asterisks*.
3684
3685       Double * or _ produces strong emphasis:
3686
3687              This is **strong emphasis** and __with underscores__.
3688
3689       A * or _ character surrounded by spaces, or backslash-escaped, will not
3690       trigger emphasis:
3691
3692              This is * not emphasized *, and \*neither is this\*.
3693
3694   Extension: intraword_underscores
3695       Because _ is sometimes used inside words and identifiers,  pandoc  does
3696       not  interpret a _ surrounded by alphanumeric characters as an emphasis
3697       marker.  If you want to emphasize just part of a word, use *:
3698
3699              feas*ible*, not feas*able*.
3700
3701   Strikeout
3702   Extension: strikeout
3703       To strikeout a section of text with a horizontal line, begin and end it
3704       with ~~.  Thus, for example,
3705
3706              This ~~is deleted text.~~
3707
3708   Superscripts and subscripts
3709   Extension: superscript, subscript
3710       Superscripts  may be written by surrounding the superscripted text by ^
3711       characters; subscripts may be written by  surrounding  the  subscripted
3712       text by ~ characters.  Thus, for example,
3713
3714              H~2~O is a liquid.  2^10^ is 1024.
3715
3716       The text between ^...^ or ~...~ may not contain spaces or newlines.  If
3717       the superscripted or subscripted text  contains  spaces,  these  spaces
3718       must  be  escaped with backslashes.  (This is to prevent accidental su‐
3719       perscripting and subscripting through the ordinary use of ~ and ^,  and
3720       also  bad  interactions with footnotes.) Thus, if you want the letter P
3721       with 'a cat' in subscripts, use P~a\ cat~, not P~a cat~.
3722
3723   Verbatim
3724       To make a short span of text verbatim, put it inside backticks:
3725
3726              What is the difference between `>>=` and `>>`?
3727
3728       If the verbatim text includes a backtick, use double backticks:
3729
3730              Here is a literal backtick `` ` ``.
3731
3732       (The spaces after the opening backticks and before  the  closing  back‐
3733       ticks will be ignored.)
3734
3735       The  general  rule is that a verbatim span starts with a string of con‐
3736       secutive backticks (optionally followed by a space)  and  ends  with  a
3737       string  of  the  same  number  of  backticks  (optionally preceded by a
3738       space).
3739
3740       Note that backslash-escapes (and other Markdown constructs) do not work
3741       in verbatim contexts:
3742
3743              This is a backslash followed by an asterisk: `\*`.
3744
3745   Extension: inline_code_attributes
3746       Attributes  can  be attached to verbatim text, just as with fenced code
3747       blocks:
3748
3749              `<$>`{.haskell}
3750
3751   Small caps
3752       To write small caps, use the smallcaps class:
3753
3754              [Small caps]{.smallcaps}
3755
3756       Or, without the bracketed_spans extension:
3757
3758              <span class="smallcaps">Small caps</span>
3759
3760       For compatibility with other Markdown flavors, CSS is also supported:
3761
3762              <span style="font-variant:small-caps;">Small caps</span>
3763
3764       This will work in all output formats that support small caps.
3765
3766   Math
3767   Extension: tex_math_dollars
3768       Anything between two $ characters will be treated  as  TeX  math.   The
3769       opening  $  must  have  a non-space character immediately to its right,
3770       while the closing $ must have a non-space character immediately to  its
3771       left,  and  must not be followed immediately by a digit.  Thus, $20,000
3772       and $30,000 won't parse as math.  If for some reason you  need  to  en‐
3773       close  text  in  literal  $  characters, backslash-escape them and they
3774       won't be treated as math delimiters.
3775
3776       For display math, use $$ delimiters.  (In this case, the delimiters may
3777       be separated from the formula by whitespace.)
3778
3779       TeX math will be printed in all output formats.  How it is rendered de‐
3780       pends on the output format:
3781
3782       LaTeX  It will appear verbatim surrounded by \(...\) (for inline  math)
3783              or \[...\] (for display math).
3784
3785       Markdown, Emacs Org mode, ConTeXt, ZimWiki
3786              It will appear verbatim surrounded by $...$ (for inline math) or
3787              $$...$$ (for display math).
3788
3789       XWiki  It will appear verbatim surrounded by {{formula}}..{{/formula}}.
3790
3791       reStructuredText
3792              It will be rendered using an interpreted text role :math:.
3793
3794       AsciiDoc
3795              For AsciiDoc output format (-t asciidoc) it will appear verbatim
3796              surrounded  by  latexmath:[$...$]  (for  inline math) or [latex‐
3797              math]++++\[...\]+++ (for display math).  For AsciiDoctor  output
3798              format  (-t  asciidoctor) the LaTex delimiters ($..$ and \[..\])
3799              are omitted.
3800
3801       Texinfo
3802              It will be rendered inside a @math command.
3803
3804       roff man, Jira markup
3805              It will be rendered verbatim without $'s.
3806
3807       MediaWiki, DokuWiki
3808              It will be rendered inside <math> tags.
3809
3810       Textile
3811              It will be rendered inside <span class="math"> tags.
3812
3813       RTF, OpenDocument
3814              It will be rendered, if possible, using Unicode characters,  and
3815              will otherwise appear verbatim.
3816
3817       ODT    It will be rendered, if possible, using MathML.
3818
3819       DocBook
3820              If  the  --mathml flag is used, it will be rendered using MathML
3821              in an inlineequation or informalequation tag.  Otherwise it will
3822              be rendered, if possible, using Unicode characters.
3823
3824       Docx   It will be rendered using OMML math markup.
3825
3826       FictionBook2
3827              If  the --webtex option is used, formulas are rendered as images
3828              using CodeCogs or other compatible web service,  downloaded  and
3829              embedded in the e-book.  Otherwise, they will appear verbatim.
3830
3831       HTML, Slidy, DZSlides, S5, EPUB
3832              The way math is rendered in HTML will depend on the command-line
3833              options selected.  Therefore see Math rendering in HTML above.
3834
3835   Raw HTML
3836   Extension: raw_html
3837       Markdown allows you to insert raw HTML (or DocBook) anywhere in a docu‐
3838       ment  (except verbatim contexts, where <, >, and & are interpreted lit‐
3839       erally).  (Technically this is not an extension, since  standard  Mark‐
3840       down  allows  it,  but  it has been made an extension so that it can be
3841       disabled if desired.)
3842
3843       The raw HTML is passed through unchanged in HTML, S5, Slidy,  Slideous,
3844       DZSlides,  EPUB, Markdown, CommonMark, Emacs Org mode, and Textile out‐
3845       put, and suppressed in other formats.
3846
3847       For a more explicit way of including raw HTML in a  Markdown  document,
3848       see the raw_attribute extension.
3849
3850       In  the  CommonMark  format, if raw_html is enabled, superscripts, sub‐
3851       scripts, strikeouts and small capitals will  be  represented  as  HTML.
3852       Otherwise,  plain-text  fallbacks  will  be  used.   Note  that even if
3853       raw_html is disabled, tables will be rendered with HTML syntax if  they
3854       cannot use pipe syntax.
3855
3856   Extension: markdown_in_html_blocks
3857       Standard  Markdown  allows you to include HTML "blocks": blocks of HTML
3858       between balanced tags that are separated from the surrounding text with
3859       blank  lines,  and  start  and  end  at  the left margin.  Within these
3860       blocks, everything is interpreted as HTML, not Markdown; so (for  exam‐
3861       ple), * does not signify emphasis.
3862
3863       Pandoc behaves this way when the markdown_strict format is used; but by
3864       default, pandoc interprets material between HTML block  tags  as  Mark‐
3865       down.  Thus, for example, pandoc will turn
3866
3867              <table>
3868              <tr>
3869              <td>*one*</td>
3870              <td>[a link](https://google.com)</td>
3871              </tr>
3872              </table>
3873
3874       into
3875
3876              <table>
3877              <tr>
3878              <td><em>one</em></td>
3879              <td><a href="https://google.com">a link</a></td>
3880              </tr>
3881              </table>
3882
3883       whereas Markdown.pl will preserve it as is.
3884
3885       There  is one exception to this rule: text between <script> and <style>
3886       tags is not interpreted as Markdown.
3887
3888       This departure from standard Markdown should  make  it  easier  to  mix
3889       Markdown  with  HTML  block  elements.  For example, one can surround a
3890       block of Markdown text with <div> tags without preventing it from being
3891       interpreted as Markdown.
3892
3893   Extension: native_divs
3894       Use  native  pandoc  Div blocks for content inside <div> tags.  For the
3895       most part this should give the same output as  markdown_in_html_blocks,
3896       but  it makes it easier to write pandoc filters to manipulate groups of
3897       blocks.
3898
3899   Extension: native_spans
3900       Use native pandoc Span blocks for content inside <span> tags.  For  the
3901       most part this should give the same output as raw_html, but it makes it
3902       easier to write pandoc filters to manipulate groups of inlines.
3903
3904   Extension: raw_tex
3905       In addition to raw HTML, pandoc allows raw LaTeX, TeX, and  ConTeXt  to
3906       be  included  in a document.  Inline TeX commands will be preserved and
3907       passed unchanged to the LaTeX and ConTeXt writers.  Thus, for  example,
3908       you can use LaTeX to include BibTeX citations:
3909
3910              This result was proved in \cite{jones.1967}.
3911
3912       Note that in LaTeX environments, like
3913
3914              \begin{tabular}{|l|l|}\hline
3915              Age & Frequency \\ \hline
3916              18--25  & 15 \\
3917              26--35  & 33 \\
3918              36--45  & 22 \\ \hline
3919              \end{tabular}
3920
3921       the  material between the begin and end tags will be interpreted as raw
3922       LaTeX, not as Markdown.
3923
3924       For a more explicit and flexible way of including raw TeX in a Markdown
3925       document, see the raw_attribute extension.
3926
3927       Inline  LaTeX  is ignored in output formats other than Markdown, LaTeX,
3928       Emacs Org mode, and ConTeXt.
3929
3930   Generic raw attribute
3931   Extension: raw_attribute
3932       Inline spans and fenced code blocks with a special  kind  of  attribute
3933       will be parsed as raw content with the designated format.  For example,
3934       the following produces a raw roff ms block:
3935
3936              ```{=ms}
3937              .MYMACRO
3938              blah blah
3939              ```
3940
3941       And the following produces a raw html inline element:
3942
3943              This is `<a>html</a>`{=html}
3944
3945       This can be useful to insert raw xml into docx documents, e.g.  a page‐
3946       break:
3947
3948              ```{=openxml}
3949              <w:p>
3950                <w:r>
3951                  <w:br w:type="page"/>
3952                </w:r>
3953              </w:p>
3954              ```
3955
3956       The  format  name  should  match  the  target format name (see -t/--to,
3957       above, for a list, or use pandoc --list-output-formats).   Use  openxml
3958       for  docx  output, opendocument for odt output, html5 for epub3 output,
3959       html4 for epub2 output, and latex, beamer, ms, or html5 for pdf  output
3960       (depending on what you use for --pdf-engine).
3961
3962       This  extension  presupposes  that  the relevant kind of inline code or
3963       fenced code block is enabled.  Thus, for example,  to  use  a  raw  at‐
3964       tribute  with  a  backtick code block, backtick_code_blocks must be en‐
3965       abled.
3966
3967       The raw attribute cannot be combined with regular attributes.
3968
3969   LaTeX macros
3970   Extension: latex_macros
3971       When this extension is enabled, pandoc will parse LaTeX  macro  defini‐
3972       tions  and  apply the resulting macros to all LaTeX math and raw LaTeX.
3973       So, for example, the following will work in  all  output  formats,  not
3974       just LaTeX:
3975
3976              \newcommand{\tuple}[1]{\langle #1 \rangle}
3977
3978              $\tuple{a, b, c}$
3979
3980       Note  that  LaTeX macros will not be applied if they occur inside a raw
3981       span or block marked with the raw_attribute extension.
3982
3983       When latex_macros is disabled, the raw LaTeX and  math  will  not  have
3984       macros applied.  This is usually a better approach when you are target‐
3985       ing LaTeX or PDF.
3986
3987       Macro definitions in LaTeX will be passed through as raw LaTeX only  if
3988       latex_macros  is not enabled.  Macro definitions in Markdown source (or
3989       other formats allowing raw_tex) will be passed  through  regardless  of
3990       whether latex_macros is enabled.
3991
3992   Links
3993       Markdown allows links to be specified in several ways.
3994
3995   Automatic links
3996       If  you  enclose a URL or email address in pointy brackets, it will be‐
3997       come a link:
3998
3999              <https://google.com>
4000              <sam@green.eggs.ham>
4001
4002   Inline links
4003       An inline link consists of the link text in square  brackets,  followed
4004       by  the  URL in parentheses.  (Optionally, the URL can be followed by a
4005       link title, in quotes.)
4006
4007              This is an [inline link](/url), and here's [one with
4008              a title](https://fsf.org "click here for a good time!").
4009
4010       There can be no space between the bracketed part and the  parenthesized
4011       part.  The link text can contain formatting (such as emphasis), but the
4012       title cannot.
4013
4014       Email addresses in inline links are not autodetected, so they  have  to
4015       be prefixed with mailto:
4016
4017              [Write me!](mailto:sam@green.eggs.ham)
4018
4019   Reference links
4020       An  explicit reference link has two parts, the link itself and the link
4021       definition, which may occur elsewhere in the document (either before or
4022       after the link).
4023
4024       The  link consists of link text in square brackets, followed by a label
4025       in square brackets.  (There cannot be space between the two unless  the
4026       spaced_reference_links  extension is enabled.) The link definition con‐
4027       sists of the bracketed label, followed by a colon and a space, followed
4028       by  the  URL,  and  optionally  (after  a space) a link title either in
4029       quotes or in parentheses.  The label must not be parseable as  a  cita‐
4030       tion  (assuming  the  citations  extension  is enabled): citations take
4031       precedence over link labels.
4032
4033       Here are some examples:
4034
4035              [my label 1]: /foo/bar.html  "My title, optional"
4036              [my label 2]: /foo
4037              [my label 3]: https://fsf.org (The free software foundation)
4038              [my label 4]: /bar#special  'A title in single quotes'
4039
4040       The URL may optionally be surrounded by angle brackets:
4041
4042              [my label 5]: <http://foo.bar.baz>
4043
4044       The title may go on the next line:
4045
4046              [my label 3]: https://fsf.org
4047                "The free software foundation"
4048
4049       Note that link labels are not case sensitive.  So, this will work:
4050
4051              Here is [my link][FOO]
4052
4053              [Foo]: /bar/baz
4054
4055       In an implicit reference link, the second pair of brackets is empty:
4056
4057              See [my website][].
4058
4059              [my website]: http://foo.bar.baz
4060
4061       Note: In Markdown.pl and most other Markdown implementations, reference
4062       link  definitions  cannot  occur  in  nested constructions such as list
4063       items or block quotes.  Pandoc lifts this  arbitrary  seeming  restric‐
4064       tion.  So the following is fine in pandoc, though not in most other im‐
4065       plementations:
4066
4067              > My block [quote].
4068              >
4069              > [quote]: /foo
4070
4071   Extension: shortcut_reference_links
4072       In a shortcut reference link, the second pair of brackets may be  omit‐
4073       ted entirely:
4074
4075              See [my website].
4076
4077              [my website]: http://foo.bar.baz
4078
4079   Internal links
4080       To  link to another section of the same document, use the automatically
4081       generated identifier (see Heading identifiers).  For example:
4082
4083              See the [Introduction](#introduction).
4084
4085       or
4086
4087              See the [Introduction].
4088
4089              [Introduction]: #introduction
4090
4091       Internal links are currently supported for HTML formats (including HTML
4092       slide shows and EPUB), LaTeX, and ConTeXt.
4093
4094   Images
4095       A  link  immediately  preceded by a ! will be treated as an image.  The
4096       link text will be used as the image's alt text:
4097
4098              ![la lune](lalune.jpg "Voyage to the moon")
4099
4100              ![movie reel]
4101
4102              [movie reel]: movie.gif
4103
4104   Extension: implicit_figures
4105       An image with nonempty alt text, occurring by itself  in  a  paragraph,
4106       will be rendered as a figure with a caption.  The image's alt text will
4107       be used as the caption.
4108
4109              ![This is the caption](/url/of/image.png)
4110
4111       How this is rendered depends on the output format.  Some output formats
4112       (e.g.   RTF) do not yet support figures.  In those formats, you'll just
4113       get an image in a paragraph by itself, with no caption.
4114
4115       If you just want a regular inline image, just make sure it is  not  the
4116       only  thing  in  the paragraph.  One way to do this is to insert a non‐
4117       breaking space after the image:
4118
4119              ![This image won't be a figure](/url/of/image.png)\
4120
4121       Note that in reveal.js slide shows, an image in a paragraph  by  itself
4122       that  has  the  stretch class will fill the screen, and the caption and
4123       figure tags will be omitted.
4124
4125   Extension: link_attributes
4126       Attributes can be set on links and images:
4127
4128              An inline ![image](foo.jpg){#id .class width=30 height=20px}
4129              and a reference ![image][ref] with attributes.
4130
4131              [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
4132
4133       (This syntax is compatible with PHP Markdown Extra when  only  #id  and
4134       .class are used.)
4135
4136       For  HTML  and EPUB, all known HTML5 attributes except width and height
4137       (but including srcset and sizes) are passed through as is.  Unknown at‐
4138       tributes are passed through as custom attributes, with data- prepended.
4139       The other writers ignore attributes that are not specifically supported
4140       by their output format.
4141
4142       The  width and height attributes on images are treated specially.  When
4143       used without a unit, the unit is assumed to be pixels.  However, any of
4144       the following unit identifiers can be used: px, cm, mm, in, inch and %.
4145       There must not be any spaces between the number and the unit.  For  ex‐
4146       ample:
4147
4148              ![](file.jpg){ width=50% }
4149
4150       · Dimensions  are  converted to inches for output in page-based formats
4151         like LaTeX.  Dimensions are converted to pixels for output  in  HTML-
4152         like  formats.   Use the --dpi option to specify the number of pixels
4153         per inch.  The default is 96dpi.
4154
4155       · The % unit is generally relative to some available space.  For  exam‐
4156         ple the above example will render to the following.
4157
4158         · HTML: <img href="file.jpg" style="width: 50%;" />
4159
4160         · LaTeX:            \includegraphics[width=0.5\textwidth,height=\tex‐
4161           theight]{file.jpg} (If you're using a custom template, you need  to
4162           configure graphicx as in the default template.)
4163
4164         · ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
4165
4166       · Some  output  formats  have a notion of a class (ConTeXt) or a unique
4167         identifier (LaTeX \caption), or both (HTML).
4168
4169       · When no width or height attributes are specified, the fallback is  to
4170         look at the image resolution and the dpi metadata embedded in the im‐
4171         age file.
4172
4173   Divs and Spans
4174       Using the native_divs and native_spans  extensions  (see  above),  HTML
4175       syntax  can  be  used as part of markdown to create native Div and Span
4176       elements in the pandoc AST (as opposed to raw HTML).  However, there is
4177       also nicer syntax available:
4178
4179   Extension: fenced_divs
4180       Allow special fenced syntax for native Div blocks.  A Div starts with a
4181       fence containing at  least  three  consecutive  colons  plus  some  at‐
4182       tributes.   The attributes may optionally be followed by another string
4183       of consecutive colons.  The attribute syntax is exactly  as  in  fenced
4184       code  blocks  (see  Extension: fenced_code_attributes).  As with fenced
4185       code blocks, one can use either attributes in curly braces or a  single
4186       unbraced  word,  which  will  be treated as a class name.  The Div ends
4187       with another line containing a string of  at  least  three  consecutive
4188       colons.  The fenced Div should be separated by blank lines from preced‐
4189       ing and following blocks.
4190
4191       Example:
4192
4193              ::::: {#special .sidebar}
4194              Here is a paragraph.
4195
4196              And another.
4197              :::::
4198
4199       Fenced divs can be nested.  Opening fences  are  distinguished  because
4200       they must have attributes:
4201
4202              ::: Warning ::::::
4203              This is a warning.
4204
4205              ::: Danger
4206              This is a warning within a warning.
4207              :::
4208              ::::::::::::::::::
4209
4210       Fences  without  attributes  are  always  closing  fences.  Unlike with
4211       fenced code blocks, the number of colons in the closing fence need  not
4212       match  the number in the opening fence.  However, it can be helpful for
4213       visual clarity to use fences of different lengths to distinguish nested
4214       divs from their parents.
4215
4216   Extension: bracketed_spans
4217       A bracketed sequence of inlines, as one would use to begin a link, will
4218       be treated as a Span with attributes if it is followed  immediately  by
4219       attributes:
4220
4221              [This is *some text*]{.class key="val"}
4222
4223   Footnotes
4224   Extension: footnotes
4225       Pandoc's Markdown allows footnotes, using the following syntax:
4226
4227              Here is a footnote reference,[^1] and another.[^longnote]
4228
4229              [^1]: Here is the footnote.
4230
4231              [^longnote]: Here's one with multiple blocks.
4232
4233                  Subsequent paragraphs are indented to show that they
4234              belong to the previous footnote.
4235
4236                      { some.code }
4237
4238                  The whole paragraph can be indented, or just the first
4239                  line.  In this way, multi-paragraph footnotes work like
4240                  multi-paragraph list items.
4241
4242              This paragraph won't be part of the note, because it
4243              isn't indented.
4244
4245       The identifiers in footnote references may not contain spaces, tabs, or
4246       newlines.  These identifiers are used only to  correlate  the  footnote
4247       reference  with  the note itself; in the output, footnotes will be num‐
4248       bered sequentially.
4249
4250       The footnotes themselves need not be placed at the end of the document.
4251       They  may  appear  anywhere  except inside other block elements (lists,
4252       block quotes, tables, etc.).  Each footnote should  be  separated  from
4253       surrounding content (including other footnotes) by blank lines.
4254
4255   Extension: inline_notes
4256       Inline  footnotes  are also allowed (though, unlike regular notes, they
4257       cannot contain multiple paragraphs).  The syntax is as follows:
4258
4259              Here is an inline note.^[Inlines notes are easier to write, since
4260              you don't have to pick an identifier and move down to type the
4261              note.]
4262
4263       Inline and regular footnotes may be mixed freely.
4264
4265   Citations
4266   Extension: citations
4267       Using an external filter,  pandoc-citeproc,  pandoc  can  automatically
4268       generate citations and a bibliography in a number of styles.  Basic us‐
4269       age is
4270
4271              pandoc --filter pandoc-citeproc myinput.txt
4272
4273       In order to use this feature, you will need to specify  a  bibliography
4274       file  using the bibliography metadata field in a YAML metadata section,
4275       or --bibliography command  line  argument.   You  can  supply  multiple
4276       --bibliography arguments or set bibliography metadata field to YAML ar‐
4277       ray, if you want to use multiple bibliography files.  The  bibliography
4278       may have any of these formats:
4279
4280       Format        File extension
4281       ─────────────────────────────
4282       BibLaTeX      .bib
4283       BibTeX        .bibtex
4284       Copac         .copac
4285       CSL JSON      .json
4286       CSL YAML      .yaml
4287       EndNote       .enl
4288       EndNote XML   .xml
4289       ISI           .wos
4290       MEDLINE       .medline
4291       MODS          .mods
4292       RIS           .ris
4293
4294       Note  that  .bib  can  be used with both BibTeX and BibLaTeX files; use
4295       .bibtex to force BibTeX.
4296
4297       Note that pandoc-citeproc --bib2json and pandoc-citeproc --bib2yaml can
4298       produce .json and .yaml files from any of the supported formats.
4299
4300       In-field  markup:  In  BibTeX  and  BibLaTeX databases, pandoc-citeproc
4301       parses a subset of LaTeX markup; in CSL YAML  databases,  pandoc  Mark‐
4302       down; and in CSL JSON databases, an HTML-like markup:
4303
4304       <i>...</i>
4305              italics
4306
4307       <b>...</b>
4308              bold
4309
4310       <span style="font-variant:small-caps;">...</span> or <sc>...</sc>
4311              small capitals
4312
4313       <sub>...</sub>
4314              subscript
4315
4316       <sup>...</sup>
4317              superscript
4318
4319       <span class="nocase">...</span>
4320              prevent a phrase from being capitalized as title case
4321
4322       pandoc-citeproc  -j  and -y interconvert the CSL JSON and CSL YAML for‐
4323       mats as far as possible.
4324
4325       As an alternative to specifying a bibliography file using  --bibliogra‐
4326       phy  or the YAML metadata field bibliography, you can include the cita‐
4327       tion data directly in the references field of the document's YAML meta‐
4328       data.   The  field  should contain an array of YAML-encoded references,
4329       for example:
4330
4331              ---
4332              references:
4333              - type: article-journal
4334                id: WatsonCrick1953
4335                author:
4336                - family: Watson
4337                  given: J. D.
4338                - family: Crick
4339                  given: F. H. C.
4340                issued:
4341                  date-parts:
4342                  - - 1953
4343                    - 4
4344                    - 25
4345                title: 'Molecular structure of nucleic acids: a structure for deoxyribose
4346                  nucleic acid'
4347                title-short: Molecular structure of nucleic acids
4348                container-title: Nature
4349                volume: 171
4350                issue: 4356
4351                page: 737-738
4352                DOI: 10.1038/171737a0
4353                URL: https://www.nature.com/articles/171737a0
4354                language: en-GB
4355              ...
4356
4357       (pandoc-citeproc --bib2yaml can produce these from a bibliography  file
4358       in one of the supported formats.)
4359
4360       Citations  and references can be formatted using any style supported by
4361       the Citation Style Language, listed in  the  Zotero  Style  Repository.
4362       These  files  are  specified using the --csl option or the csl metadata
4363       field.  By default, pandoc-citeproc will  use  the  Chicago  Manual  of
4364       Style author-date format.  The CSL project provides further information
4365       on finding and editing styles.
4366
4367       To make your citations hyperlinks to the corresponding bibliography en‐
4368       tries, add link-citations: true to your YAML metadata.
4369
4370       Citations  go  inside  square brackets and are separated by semicolons.
4371       Each citation must have a key, composed of '@' + the citation identifi‐
4372       er  from the database, and may optionally have a prefix, a locator, and
4373       a suffix.  The citation key must begin with a letter, digit, or _,  and
4374       may  contain  alphanumerics,  _,  and  internal  punctuation characters
4375       (:.#$%&-+?<>~/).  Here are some examples:
4376
4377              Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
4378
4379              Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
4380
4381              Blah blah [@smith04; @doe99].
4382
4383       pandoc-citeproc detects locator terms in the CSL locale files.   Either
4384       abbreviated  or unabbreviated forms are accepted.  In the en-US locale,
4385       locator terms can be written in either singular  or  plural  forms,  as
4386       book,  bk./bks.;  chapter,  chap./chaps.;  column,  col./cols.; figure,
4387       fig./figs.; folio, fol./fols.; number, no./nos.;  line,  l./ll.;  note,
4388       n./nn.;  opus,  op./opp.;  page, p./pp.; paragraph, para./paras.; part,
4389       pt./pts.; section, sec./secs.; sub verbo,  s.v./s.vv.;  verse,  v./vv.;
4390       volume,  vol./vols.; ¶/¶¶; §/§§.  If no locator term is used, "page" is
4391       assumed.
4392
4393       pandoc-citeproc will use heuristics to distinguish the locator from the
4394       suffix.   In complex cases, the locator can be enclosed in curly braces
4395       (using pandoc-citeproc 0.15 and higher only):
4396
4397              [@smith{ii, A, D-Z}, with a suffix]
4398              [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
4399
4400       A minus sign (-) before the @ will suppress mention of  the  author  in
4401       the  citation.  This can be useful when the author is already mentioned
4402       in the text:
4403
4404              Smith says blah [-@smith04].
4405
4406       You can also write an in-text citation, as follows:
4407
4408              @smith04 says blah.
4409
4410              @smith04 [p. 33] says blah.
4411
4412       If the style calls for a list of works cited, it will be  placed  in  a
4413       div with id refs, if one exists:
4414
4415              ::: {#refs}
4416              :::
4417
4418       Otherwise, it will be placed at the end of the document.  Generation of
4419       the bibliography can be suppressed  by  setting  suppress-bibliography:
4420       true in the YAML metadata.
4421
4422       If  you  wish  the  bibliography to have a section heading, you can set
4423       reference-section-title in the metadata, or put the heading at the  be‐
4424       ginning  of the div with id refs (if you are using it) or at the end of
4425       your document:
4426
4427              last paragraph...
4428
4429              # References
4430
4431       The bibliography will be inserted after this heading.   Note  that  the
4432       unnumbered  class  will  be  added to this heading, so that the section
4433       will not be numbered.
4434
4435       If you want to include items in the bibliography without actually  cit‐
4436       ing them in the body text, you can define a dummy nocite metadata field
4437       and put the citations there:
4438
4439              ---
4440              nocite: |
4441                @item1, @item2
4442              ...
4443
4444              @item3
4445
4446       In this example, the document will contain a citation for  item3  only,
4447       but the bibliography will contain entries for item1, item2, and item3.
4448
4449       It is possible to create a bibliography with all the citations, whether
4450       or not they appear in the document, by using a wildcard:
4451
4452              ---
4453              nocite: |
4454                @*
4455              ...
4456
4457       For LaTeX output, you can also use natbib or  biblatex  to  render  the
4458       bibliography.   In  order  to do so, specify bibliography files as out‐
4459       lined above, and add --natbib or --biblatex argument to pandoc  invoca‐
4460       tion.   Bear  in  mind that bibliography files have to be in respective
4461       format (either BibTeX or BibLaTeX).
4462
4463       For more information, see the pandoc-citeproc man page.
4464
4465   Non-pandoc extensions
4466       The following Markdown syntax extensions are not enabled by default  in
4467       pandoc,  but  may  be  enabled by adding +EXTENSION to the format name,
4468       where EXTENSION is the name of the extension.  Thus, for example, mark‐
4469       down+hard_line_breaks is Markdown with hard line breaks.
4470
4471   Extension: old_dashes
4472       Selects  the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - be‐
4473       fore a numeral is an en-dash, and -- is an em-dash.  This  option  only
4474       has  an  effect  if smart is enabled.  It is selected automatically for
4475       textile input.
4476
4477   Extension: angle_brackets_escapable
4478       Allow < and > to be backslash-escaped, as they can be  in  GitHub  fla‐
4479       vored  Markdown but not original Markdown.  This is implied by pandoc's
4480       default all_symbols_escapable.
4481
4482   Extension: lists_without_preceding_blankline
4483       Allow a list to occur right after  a  paragraph,  with  no  intervening
4484       blank space.
4485
4486   Extension: four_space_rule
4487       Selects the pandoc <= 2.0 behavior for parsing lists, so that four spa‐
4488       ces indent are needed for list item continuation paragraphs.
4489
4490   Extension: spaced_reference_links
4491       Allow whitespace between the two components of a  reference  link,  for
4492       example,
4493
4494              [foo] [bar].
4495
4496   Extension: hard_line_breaks
4497       Causes  all  newlines within a paragraph to be interpreted as hard line
4498       breaks instead of spaces.
4499
4500   Extension: ignore_line_breaks
4501       Causes newlines within a paragraph to be  ignored,  rather  than  being
4502       treated  as spaces or as hard line breaks.  This option is intended for
4503       use with East Asian languages where spaces are not used between  words,
4504       but text is divided into lines for readability.
4505
4506   Extension: east_asian_line_breaks
4507       Causes  newlines  within  a  paragraph to be ignored, rather than being
4508       treated as spaces or as hard line breaks, when they occur  between  two
4509       East  Asian  wide  characters.   This  is  a  better  choice  than  ig‐
4510       nore_line_breaks for texts that include a mix of East Asian wide  char‐
4511       acters and other characters.
4512
4513   Extension: emoji
4514       Parses textual emojis like :smile: as Unicode emoticons.
4515
4516   Extension: tex_math_single_backslash
4517       Causes anything between \( and \) to be interpreted as inline TeX math,
4518       and anything between \[ and \] to be interpreted as display  TeX  math.
4519       Note:  a drawback of this extension is that it precludes escaping ( and
4520       [.
4521
4522   Extension: tex_math_double_backslash
4523       Causes anything between \\( and \\) to be  interpreted  as  inline  TeX
4524       math, and anything between \\[ and \\] to be interpreted as display TeX
4525       math.
4526
4527   Extension: markdown_attribute
4528       By default, pandoc interprets material inside block-level tags as Mark‐
4529       down.   This  extension  changes  the behavior so that Markdown is only
4530       parsed inside block-level tags if the tags  have  the  attribute  mark‐
4531       down=1.
4532
4533   Extension: mmd_title_block
4534       Enables  a  MultiMarkdown style title block at the top of the document,
4535       for example:
4536
4537              Title:   My title
4538              Author:  John Doe
4539              Date:    September 1, 2008
4540              Comment: This is a sample mmd title block, with
4541                       a field spanning multiple lines.
4542
4543       See the MultiMarkdown documentation for details.  If pandoc_title_block
4544       or yaml_metadata_block is enabled, it will take precedence over mmd_ti‐
4545       tle_block.
4546
4547   Extension: abbreviations
4548       Parses PHP Markdown Extra abbreviation keys, like
4549
4550              *[HTML]: Hypertext Markup Language
4551
4552       Note that the pandoc document model does not support abbreviations,  so
4553       if  this extension is enabled, abbreviation keys are simply skipped (as
4554       opposed to being parsed as paragraphs).
4555
4556   Extension: autolink_bare_uris
4557       Makes all absolute URIs into links, even when not surrounded by  pointy
4558       braces <...>.
4559
4560   Extension: mmd_link_attributes
4561       Parses  multimarkdown style key-value attributes on link and image ref‐
4562       erences.  This extension should  not  be  confused  with  the  link_at‐
4563       tributes extension.
4564
4565              This is a reference ![image][ref] with multimarkdown attributes.
4566
4567              [ref]: https://path.to/image "Image title" width=20px height=30px
4568                     id=myId class="myClass1 myClass2"
4569
4570   Extension: mmd_header_identifiers
4571       Parses multimarkdown style heading identifiers (in square brackets, af‐
4572       ter the heading but before any trailing #s in an ATX heading).
4573
4574   Extension: compact_definition_lists
4575       Activates the definition list syntax  of  pandoc  1.12.x  and  earlier.
4576       This syntax differs from the one described above under Definition lists
4577       in several respects:
4578
4579       · No blank line is required between consecutive items of the definition
4580         list.
4581
4582       · To  get  a  "tight" or "compact" list, omit space between consecutive
4583         items; the space between a term and its definition  does  not  affect
4584         anything.
4585
4586       · Lazy  wrapping  of  paragraphs  is not allowed: the entire definition
4587         must be indented four spaces.
4588
4589   Extension: gutenberg
4590       Use Project Gutenberg conventions for plain output: all-caps for strong
4591       emphasis, surround by underscores for regular emphasis, add extra blank
4592       space around headings.
4593
4594   Markdown variants
4595       In addition to pandoc's extended Markdown, the following Markdown vari‐
4596       ants are supported:
4597
4598       markdown_phpextra (PHP Markdown Extra)
4599              footnotes,     pipe_tables,     raw_html,    markdown_attribute,
4600              fenced_code_blocks,   definition_lists,   intraword_underscores,
4601              header_attributes, link_attributes, abbreviations, shortcut_ref‐
4602              erence_links, spaced_reference_links.
4603
4604       markdown_github (deprecated GitHub-Flavored Markdown)
4605              pipe_tables,  raw_html,  fenced_code_blocks,   auto_identifiers,
4606              gfm_auto_identifiers,  backtick_code_blocks, autolink_bare_uris,
4607              space_in_atx_header,      intraword_underscores,      strikeout,
4608              task_lists,  emoji, shortcut_reference_links, angle_brackets_es‐
4609              capable, lists_without_preceding_blankline.
4610
4611       markdown_mmd (MultiMarkdown)
4612              pipe_tables, raw_html, markdown_attribute,  mmd_link_attributes,
4613              tex_math_double_backslash,     intraword_underscores,    mmd_ti‐
4614              tle_block, footnotes,  definition_lists,  all_symbols_escapable,
4615              implicit_header_references, auto_identifiers, mmd_header_identi‐
4616              fiers, shortcut_reference_links, implicit_figures,  superscript,
4617              subscript, backtick_code_blocks, spaced_reference_links, raw_at‐
4618              tribute.
4619
4620       markdown_strict (Markdown.pl)
4621              raw_html, shortcut_reference_links, spaced_reference_links.
4622
4623       We also support commonmark and gfm (GitHub-Flavored Markdown, which  is
4624       implemented as a set of extensions on commonmark).
4625
4626       Note,  however, that commonmark and gfm have limited support for exten‐
4627       sions.   Only   those   listed   below   (and   smart,   raw_tex,   and
4628       hard_line_breaks) will work.  The extensions can, however, all be indi‐
4629       vidually disabled.  Also, raw_tex only affects gfm output, not input.
4630
4631       gfm (GitHub-Flavored Markdown)
4632              pipe_tables,  raw_html,  fenced_code_blocks,   auto_identifiers,
4633              gfm_auto_identifiers,  backtick_code_blocks, autolink_bare_uris,
4634              space_in_atx_header,      intraword_underscores,      strikeout,
4635              task_lists,  emoji, shortcut_reference_links, angle_brackets_es‐
4636              capable, lists_without_preceding_blankline.
4637

PRODUCING SLIDE SHOWS WITH PANDOC

4639       You can use pandoc to produce an HTML + JavaScript  slide  presentation
4640       that  can be viewed via a web browser.  There are five ways to do this,
4641       using S5, DZSlides, Slidy, Slideous, or reveal.js.  You can  also  pro‐
4642       duce  a PDF slide show using LaTeX beamer, or slides shows in Microsoft
4643       PowerPoint format.
4644
4645       Here's the Markdown source for a simple slide show, habits.txt:
4646
4647              % Habits
4648              % John Doe
4649              % March 22, 2005
4650
4651              # In the morning
4652
4653              ## Getting up
4654
4655              - Turn off alarm
4656              - Get out of bed
4657
4658              ## Breakfast
4659
4660              - Eat eggs
4661              - Drink coffee
4662
4663              # In the evening
4664
4665              ## Dinner
4666
4667              - Eat spaghetti
4668              - Drink wine
4669
4670              ------------------
4671
4672              ![picture of spaghetti](images/spaghetti.jpg)
4673
4674              ## Going to sleep
4675
4676              - Get in bed
4677              - Count sheep
4678
4679       To produce an HTML/JavaScript slide show, simply type
4680
4681              pandoc -t FORMAT -s habits.txt -o habits.html
4682
4683       where FORMAT is either s5, slidy, slideous, dzslides, or revealjs.
4684
4685       For Slidy, Slideous, reveal.js, and S5, the  file  produced  by  pandoc
4686       with  the  -s/--standalone  option  embeds a link to JavaScript and CSS
4687       files, which are assumed to be available at the  relative  path  s5/de‐
4688       fault  (for S5), slideous (for Slideous), reveal.js (for reveal.js), or
4689       at the Slidy website at  w3.org  (for  Slidy).   (These  paths  can  be
4690       changed by setting the slidy-url, slideous-url, revealjs-url, or s5-url
4691       variables; see Variables for HTML slides,  above.)  For  DZSlides,  the
4692       (relatively  short)  JavaScript and CSS are included in the file by de‐
4693       fault.
4694
4695       With all HTML slide formats, the --self-contained option can be used to
4696       produce  a  single file that contains all of the data necessary to dis‐
4697       play the slide show, including linked scripts, stylesheets, images, and
4698       videos.
4699
4700       To produce a PDF slide show using beamer, type
4701
4702              pandoc -t beamer habits.txt -o habits.pdf
4703
4704       Note  that  a  reveal.js  slide  show can also be converted to a PDF by
4705       printing it to a file from the browser.
4706
4707       To produce a Powerpoint slide show, type
4708
4709              pandoc habits.txt -o habits.pptx
4710
4711   Structuring the slide show
4712       By default, the slide level is the highest heading level in the hierar‐
4713       chy  that  is followed immediately by content, and not another heading,
4714       somewhere in the document.  In the example above, level-1 headings  are
4715       always  followed by level-2 headings, which are followed by content, so
4716       the slide level is  2.   This  default  can  be  overridden  using  the
4717       --slide-level option.
4718
4719       The document is carved up into slides according to the following rules:
4720
4721       · A horizontal rule always starts a new slide.
4722
4723       · A heading at the slide level always starts a new slide.
4724
4725       · Headings below the slide level in the hierarchy create headings with‐
4726         in a slide.
4727
4728       · Headings above  the  slide  level  in  the  hierarchy  create  "title
4729         slides,"  which  just contain the section title and help to break the
4730         slide show into sections.  Non-slide  content  under  these  headings
4731         will  be  included  on the title slide (for HTML slide shows) or in a
4732         subsequent slide with the same title (for beamer).
4733
4734       · A title page is constructed automatically from the  document's  title
4735         block,  if  present.  (In the case of beamer, this can be disabled by
4736         commenting out some lines in the default template.)
4737
4738       These rules are designed to support  many  different  styles  of  slide
4739       show.   If  you  don't care about structuring your slides into sections
4740       and subsections, you can just use level-1 headings for all each  slide.
4741       (In  that  case,  level-1  will  be  the slide level.) But you can also
4742       structure the slide show into sections, as in the example above.
4743
4744       Note: in reveal.js slide shows, if slide level is 2, a  two-dimensional
4745       layout  will  be  produced, with level-1 headings building horizontally
4746       and level-2 headings building vertically.  It is not  recommended  that
4747       you use deeper nesting of section levels with reveal.js.
4748
4749   Incremental lists
4750       By  default, these writers produce lists that display "all at once." If
4751       you want your lists to display incrementally (one item at a time),  use
4752       the  -i  option.   If you want a particular list to depart from the de‐
4753       fault, put it in a div block with class incremental or  nonincremental.
4754       So,  for  example,  using the fenced div syntax, the following would be
4755       incremental regardless of the document default:
4756
4757              ::: incremental
4758
4759              - Eat spaghetti
4760              - Drink wine
4761
4762              :::
4763
4764       or
4765
4766              ::: nonincremental
4767
4768              - Eat spaghetti
4769              - Drink wine
4770
4771              :::
4772
4773       While using incremental and nonincremental  divs  are  the  recommended
4774       method  of  setting  incremental  lists  on  a per-case basis, an older
4775       method is also supported: putting lists inside a blockquote will depart
4776       from the document default (that is, it will display incrementally with‐
4777       out the -i option and all at once with the -i option):
4778
4779              > - Eat spaghetti
4780              > - Drink wine
4781
4782       Both methods allow incremental and nonincremental lists to be mixed  in
4783       a single document.
4784
4785       Note:  Neither  the  -i/--incremental option nor any of the methods de‐
4786       scribed here currently works for PowerPoint output.
4787
4788   Inserting pauses
4789       You can add "pauses" within a slide by including a paragraph containing
4790       three dots, separated by spaces:
4791
4792              # Slide with a pause
4793
4794              content before the pause
4795
4796              . . .
4797
4798              content after the pause
4799
4800       Note: this feature is not yet implemented for PowerPoint output.
4801
4802   Styling the slides
4803       You can change the style of HTML slides by putting customized CSS files
4804       in  $DATADIR/s5/default  (for  S5),  $DATADIR/slidy  (for  Slidy),   or
4805       $DATADIR/slideous  (for  Slideous), where $DATADIR is the user data di‐
4806       rectory (see --data-dir, above).  The originals may be  found  in  pan‐
4807       doc's  system data directory (generally $CABALDIR/pandoc-VERSION/s5/de‐
4808       fault).  Pandoc will look there for any files it does not find  in  the
4809       user data directory.
4810
4811       For  dzslides,  the CSS is included in the HTML file itself, and may be
4812       modified there.
4813
4814       All reveal.js configuration options can be set through variables.   For
4815       example, themes can be used by setting the theme variable:
4816
4817              -V theme=moon
4818
4819       Or you can specify a custom stylesheet using the --css option.
4820
4821       To style beamer slides, you can specify a theme, colortheme, fonttheme,
4822       innertheme, and outertheme, using the -V option:
4823
4824              pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
4825
4826       Note that heading attributes will turn  into  slide  attributes  (on  a
4827       <div>  or <section>) in HTML slide formats, allowing you to style indi‐
4828       vidual slides.  In beamer, the  only  heading  attribute  that  affects
4829       slides  is  the allowframebreaks class, which sets the allowframebreaks
4830       option, causing multiple slides to be created if the content  overfills
4831       the frame.  This is recommended especially for bibliographies:
4832
4833              # References {.allowframebreaks}
4834
4835   Speaker notes
4836       Speaker  notes are supported in reveal.js and PowerPoint (pptx) output.
4837       You can add notes to your Markdown document thus:
4838
4839              ::: notes
4840
4841              This is my note.
4842
4843              - It can contain Markdown
4844              - like this list
4845
4846              :::
4847
4848       To show the notes window in reveal.js, press s while viewing  the  pre‐
4849       sentation.  Speaker notes in PowerPoint will be available, as usual, in
4850       handouts and presenter view.
4851
4852       Notes are not yet supported for other slide formats, but the notes will
4853       not appear on the slides themselves.
4854
4855   Columns
4856       To  put material in side by side columns, you can use a native div con‐
4857       tainer with class columns, containing two or more div  containers  with
4858       class column and a width attribute:
4859
4860              :::::::::::::: {.columns}
4861              ::: {.column width="40%"}
4862              contents...
4863              :::
4864              ::: {.column width="60%"}
4865              contents...
4866              :::
4867              ::::::::::::::
4868
4869   Frame attributes in beamer
4870       Sometimes  it is necessary to add the LaTeX [fragile] option to a frame
4871       in beamer (for example, when using the minted environment).   This  can
4872       be  forced  by  adding the fragile class to the heading introducing the
4873       slide:
4874
4875              # Fragile slide {.fragile}
4876
4877       All of the other frame attributes described in Section 8.1 of the Beam‐
4878       er User's Guide may also be used: allowdisplaybreaks, allowframebreaks,
4879       b, c, t, environment, label, plain, shrink, standout, noframenumbering.
4880
4881   Background in reveal.js and beamer
4882       Background images can be added to self-contained  reveal.js  slideshows
4883       and to beamer slideshows.
4884
4885       For  the  same image on every slide, use the configuration option back‐
4886       ground-image either in the YAML metadata block  or  as  a  command-line
4887       variable.   (There  are no other options in beamer and the rest of this
4888       section concerns reveal.js slideshows.)
4889
4890       For reveal.js, you can instead use the reveal.js-native  option  paral‐
4891       laxBackgroundImage.   You can also set parallaxBackgroundHorizontal and
4892       parallaxBackgroundVertical the same way and must also set parallaxBack‐
4893       groundSize to have your values take effect.
4894
4895       To set an image for a particular reveal.js slide, add {data-background-
4896       image="/path/to/image"} to the first slide-level heading on  the  slide
4897       (which may even be empty).
4898
4899       In  reveal.js's overview mode, the parallaxBackgroundImage will show up
4900       only on the first slide.
4901
4902       Other reveal.js background settings also work on individual slides, in‐
4903       cluding  data-background-size, data-background-repeat, data-background-
4904       color, data-transition, and data-transition-speed.
4905
4906       To add a background image to the automatically generated  title  slide,
4907       use the title-slide-attributes variable in the YAML metadata block.  It
4908       must contain a map of attribute names and values.
4909
4910       See the reveal.js documentation for more details.
4911
4912       For example in reveal.js:
4913
4914              ---
4915              title: My Slideshow
4916              parallaxBackgroundImage: /path/to/my/background_image.png
4917              title-slide-attributes:
4918                  data-background-image: /path/to/title_image.png
4919                  data-background-size: contain
4920              ---
4921
4922              ## Slide One
4923
4924              Slide 1 has background_image.png as its background.
4925
4926              ## {data-background-image="/path/to/special_image.jpg"}
4927
4928              Slide 2 has a special image for its background, even though the heading has no content.
4929

CREATING EPUBS WITH PANDOC

4931   EPUB Metadata
4932       EPUB metadata may be specified using the --epub-metadata option, but if
4933       the  source  document  is Markdown, it is better to use a YAML metadata
4934       block.  Here is an example:
4935
4936              ---
4937              title:
4938              - type: main
4939                text: My Book
4940              - type: subtitle
4941                text: An investigation of metadata
4942              creator:
4943              - role: author
4944                text: John Smith
4945              - role: editor
4946                text: Sarah Jones
4947              identifier:
4948              - scheme: DOI
4949                text: doi:10.234234.234/33
4950              publisher:  My Press
4951              rights: © 2007 John Smith, CC BY-NC
4952              ibooks:
4953                version: 1.3.4
4954              ...
4955
4956       The following fields are recognized:
4957
4958       identifier
4959              Either a string value or an object with fields text and  scheme.
4960              Valid values for scheme are ISBN-10, GTIN-13, UPC, ISMN-10, DOI,
4961              LCCN,  GTIN-14,  ISBN-13,  Legal  deposit  number,  URN,   OCLC,
4962              ISMN-13, ISBN-A, JP, OLCC.
4963
4964       title  Either  a  string  value,  or  an object with fields file-as and
4965              type, or a list of such objects.   Valid  values  for  type  are
4966              main, subtitle, short, collection, edition, extended.
4967
4968       creator
4969              Either  a  string value, or an object with fields role, file-as,
4970              and text, or a list of such objects.  Valid values for role  are
4971              MARC  relators,  but pandoc will attempt to translate the human-
4972              readable versions (like "author" and "editor") to the  appropri‐
4973              ate marc relators.
4974
4975       contributor
4976              Same format as creator.
4977
4978       date   A  string  value in YYYY-MM-DD format.  (Only the year is neces‐
4979              sary.) Pandoc will attempt to convert other common date formats.
4980
4981       lang (or legacy: language)
4982              A string value in BCP 47 format.  Pandoc will default to the lo‐
4983              cal language if nothing is specified.
4984
4985       subject
4986              A string value or a list of such values.
4987
4988       description
4989              A string value.
4990
4991       type   A string value.
4992
4993       format A string value.
4994
4995       relation
4996              A string value.
4997
4998       coverage
4999              A string value.
5000
5001       rights A string value.
5002
5003       cover-image
5004              A string value (path to cover image).
5005
5006       css (or legacy: stylesheet)
5007              A string value (path to CSS stylesheet).
5008
5009       page-progression-direction
5010              Either ltr or rtl.  Specifies the page-progression-direction at‐
5011              tribute for the spine element.
5012
5013       ibooks iBooks-specific metadata, with the following fields:
5014
5015              · version: (string)
5016
5017              · specified-fonts: true|false (default false)
5018
5019              · ipad-orientation-lock: portrait-only|landscape-only
5020
5021              · iphone-orientation-lock: portrait-only|landscape-only
5022
5023              · binding: true|false (default true)
5024
5025              · scroll-axis: vertical|horizontal|default
5026
5027   The epub:type attribute
5028       For epub3 output, you can mark up the heading that  corresponds  to  an
5029       EPUB  chapter  using  the epub:type attribute.  For example, to set the
5030       attribute to the value prologue, use this markdown:
5031
5032              # My chapter {epub:type=prologue}
5033
5034       Which will result in:
5035
5036              <body epub:type="frontmatter">
5037                <section epub:type="prologue">
5038                  <h1>My chapter</h1>
5039
5040       Pandoc will output <body epub:type="bodymatter">, unless you use one of
5041       the  following  values,  in which case either frontmatter or backmatter
5042       will be output.
5043
5044       epub:type of first section   epub:type of body
5045       ───────────────────────────────────────────────
5046       prologue                     frontmatter
5047       abstract                     frontmatter
5048       acknowledgments              frontmatter
5049       copyright-page               frontmatter
5050       dedication                   frontmatter
5051       credits                      frontmatter
5052       keywords                     frontmatter
5053       imprint                      frontmatter
5054       contributors                 frontmatter
5055       other-credits                frontmatter
5056       errata                       frontmatter
5057       revision-history             frontmatter
5058       titlepage                    frontmatter
5059       halftitlepage                frontmatter
5060       seriespage                   frontmatter
5061       foreword                     frontmatter
5062       preface                      frontmatter
5063       seriespage                   frontmatter
5064       titlepage                    frontmatter
5065       appendix                     backmatter
5066       colophon                     backmatter
5067       bibliography                 backmatter
5068       index                        backmatter
5069
5070   Linked media
5071       By default, pandoc will download media referenced from any <img>,  <au‐
5072       dio>,  <video>  or  <source> element present in the generated EPUB, and
5073       include it in the EPUB container, yielding a completely  self-contained
5074       EPUB.  If you want to link to external media resources instead, use raw
5075       HTML in your source and add data-external="1" to the tag with  the  src
5076       attribute.  For example:
5077
5078              <audio controls="1">
5079                <source src="https://example.com/music/toccata.mp3"
5080                        data-external="1" type="audio/mpeg">
5081                </source>
5082              </audio>
5083

CREATING JUPYTER NOTEBOOKS WITH PANDOC

5085       When creating a Jupyter notebook, pandoc will try to infer the notebook
5086       structure.  Code blocks with the class  code  will  be  taken  as  code
5087       cells,  and  intervening  content will be taken as Markdown cells.  At‐
5088       tachments will automatically be created for images in  Markdown  cells.
5089       Metadata will be taken from the jupyter metadata field.  For example:
5090
5091              ---
5092              title: My notebook
5093              jupyter:
5094                nbformat: 4
5095                nbformat_minor: 5
5096                kernelspec:
5097                   display_name: Python 2
5098                   language: python
5099                   name: python2
5100                language_info:
5101                   codemirror_mode:
5102                     name: ipython
5103                     version: 2
5104                   file_extension: ".py"
5105                   mimetype: "text/x-python"
5106                   name: "python"
5107                   nbconvert_exporter: "python"
5108                   pygments_lexer: "ipython2"
5109                   version: "2.7.15"
5110              ---
5111
5112              # Lorem ipsum
5113
5114              **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5115              bibendum felis dictum sodales.
5116
5117              ``` code
5118              print("hello")
5119              ```
5120
5121              ## Pyout
5122
5123              ``` code
5124              from IPython.display import HTML
5125              HTML("""
5126              <script>
5127              console.log("hello");
5128              </script>
5129              <b>HTML</b>
5130              """)
5131              ```
5132
5133              ## Image
5134
5135              This image ![image](myimage.png) will be
5136              included as a cell attachment.
5137
5138       If  you  want  to  add cell attributes, group cells differently, or add
5139       output to code cells, then you need to include  divs  to  indicate  the
5140       structure.   You  can  use  either fenced divs or native divs for this.
5141       Here is an example:
5142
5143              :::::: {.cell .markdown}
5144              # Lorem
5145
5146              **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
5147              bibendum felis dictum sodales.
5148              ::::::
5149
5150              :::::: {.cell .code execution_count=1}
5151              ``` {.python}
5152              print("hello")
5153              ```
5154
5155              ::: {.output .stream .stdout}
5156              ```
5157              hello
5158              ```
5159              :::
5160              ::::::
5161
5162              :::::: {.cell .code execution_count=2}
5163              ``` {.python}
5164              from IPython.display import HTML
5165              HTML("""
5166              <script>
5167              console.log("hello");
5168              </script>
5169              <b>HTML</b>
5170              """)
5171              ```
5172
5173              ::: {.output .execute_result execution_count=2}
5174              ```{=html}
5175              <script>
5176              console.log("hello");
5177              </script>
5178              <b>HTML</b>
5179              hello
5180              ```
5181              :::
5182              ::::::
5183
5184       If you include raw HTML or TeX in an output  cell,  use  the  [raw  at‐
5185       tribute][Extension: fenced_attribute], as shown in the last cell of the
5186       example above.  Although pandoc can process "bare" raw  HTML  and  TeX,
5187       the  result  is often interspersed raw elements and normal textual ele‐
5188       ments, and in an output cell pandoc expects  a  single,  connected  raw
5189       block.   To  avoid  using raw HTML or TeX except when marked explicitly
5190       using raw attributes, we recommend specifying the extensions -raw_html-
5191       raw_tex+raw_attribute when translating between Markdown and ipynb note‐
5192       books.
5193
5194       Note that options and extensions that affect  reading  and  writing  of
5195       Markdown will also affect Markdown cells in ipynb notebooks.  For exam‐
5196       ple, --wrap=preserve will preserve soft line breaks in Markdown  cells;
5197       --atx-headers will cause ATX-style headings to be used; and --preserve-
5198       tabs will prevent tabs from being turned to spaces.
5199

SYNTAX HIGHLIGHTING

5201       Pandoc will automatically highlight syntax in fenced code  blocks  that
5202       are  marked  with  a language name.  The Haskell library skylighting is
5203       used for highlighting.  Currently highlighting is  supported  only  for
5204       HTML,  EPUB, Docx, Ms, and LaTeX/PDF output.  To see a list of language
5205       names that pandoc will  recognize,  type  pandoc  --list-highlight-lan‐
5206       guages.
5207
5208       The  color  scheme  can be selected using the --highlight-style option.
5209       The default color scheme is pygments, which imitates the default  color
5210       scheme  used by the Python library pygments (though pygments is not ac‐
5211       tually used to do the  highlighting).   To  see  a  list  of  highlight
5212       styles, type pandoc --list-highlight-styles.
5213
5214       If  you  are  not  satisfied  with  the  predefined styles, you can use
5215       --print-highlight-style to generate a JSON .theme  file  which  can  be
5216       modified  and used as the argument to --highlight-style.  To get a JSON
5217       version of the pygments style, for example:
5218
5219              pandoc --print-highlight-style pygments > my.theme
5220
5221       Then edit my.theme and use it like this:
5222
5223              pandoc --highlight-style my.theme
5224
5225       If you are not satisfied with the built-in highlighting,  or  you  want
5226       highlight  a  language  that isn't supported, you can use the --syntax-
5227       definition option to load a KDE-style XML syntax definition file.   Be‐
5228       fore  writing your own, have a look at KDE's repository of syntax defi‐
5229       nitions.
5230
5231       To disable highlighting, use the --no-highlight option.
5232

CUSTOM STYLES

5234       Custom styles can be used in the docx and ICML formats.
5235
5236   Output
5237       By default, pandoc's docx and ICML output applies a predefined  set  of
5238       styles for blocks such as paragraphs and block quotes, and uses largely
5239       default formatting (italics, bold) for inlines.   This  will  work  for
5240       most purposes, especially alongside a reference.docx file.  However, if
5241       you need to apply your own styles to blocks, or match a preexisting set
5242       of  styles,  pandoc  allows  you to define custom styles for blocks and
5243       text using divs and spans, respectively.
5244
5245       If you define a div or span with  the  attribute  custom-style,  pandoc
5246       will apply your specified style to the contained elements (with the ex‐
5247       ception of elements whose function depends on a style,  like  headings,
5248       code  blocks,  block  quotes,  or  links).   So, for example, using the
5249       bracketed_spans syntax,
5250
5251              [Get out]{custom-style="Emphatically"}, he said.
5252
5253       would produce a docx file with "Get out" styled  with  character  style
5254       Emphatically.  Similarly, using the fenced_divs syntax,
5255
5256              Dickinson starts the poem simply:
5257
5258              ::: {custom-style="Poetry"}
5259              | A Bird came down the Walk---
5260              | He did not know I saw---
5261              :::
5262
5263       would style the two contained lines with the Poetry paragraph style.
5264
5265       For  docx output, styles will be defined in the output file as inherit‐
5266       ing from normal text, if the styles are not yet in your reference.docx.
5267       If they are already defined, pandoc will not alter the definition.
5268
5269       This feature allows for greatest customization in conjunction with pan‐
5270       doc filters.  If you want all paragraphs after block quotes to  be  in‐
5271       dented,  you  can write a filter to apply the styles necessary.  If you
5272       want all italics to be transformed  to  the  Emphasis  character  style
5273       (perhaps  to  change  their  color),  you can write a filter which will
5274       transform all italicized inlines to inlines within an Emphasis  custom-
5275       style span.
5276
5277       For  docx  output,  you  don't need to enable any extensions for custom
5278       styles to work.
5279
5280   Input
5281       The docx reader, by default, only reads those styles that it  can  con‐
5282       vert  into pandoc elements, either by direct conversion or interpreting
5283       the derivation of the input document's styles.
5284
5285       By enabling the styles extension in the docx reader  (-f  docx+styles),
5286       you can produce output that maintains the styles of the input document,
5287       using the custom-style class.  Paragraph styles are interpreted as  di‐
5288       vs, while character styles are interpreted as spans.
5289
5290       For example, using the custom-style-reference.docx file in the test di‐
5291       rectory, we have the following different outputs:
5292
5293       Without the +styles extension:
5294
5295              $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
5296              This is some text.
5297
5298              This is text with an *emphasized* text style. And this is text with a
5299              **strengthened** text style.
5300
5301              > Here is a styled paragraph that inherits from Block Text.
5302
5303       And with the extension:
5304
5305              $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
5306
5307              ::: {custom-style="First Paragraph"}
5308              This is some text.
5309              :::
5310
5311              ::: {custom-style="Body Text"}
5312              This is text with an [emphasized]{custom-style="Emphatic"} text style.
5313              And this is text with a [strengthened]{custom-style="Strengthened"}
5314              text style.
5315              :::
5316
5317              ::: {custom-style="My Block Style"}
5318              > Here is a styled paragraph that inherits from Block Text.
5319              :::
5320
5321       With these custom styles, you can use your input document as  a  refer‐
5322       ence-doc  while creating docx output (see below), and maintain the same
5323       styles in your input and output files.
5324

CUSTOM WRITERS

5326       Pandoc can be extended with custom writers written in Lua.  (Pandoc in‐
5327       cludes a Lua interpreter, so Lua need not be installed separately.)
5328
5329       To  use  a  custom writer, simply specify the path to the Lua script in
5330       place of the output format.  For example:
5331
5332              pandoc -t data/sample.lua
5333
5334       Creating a custom writer requires writing a Lua function for each  pos‐
5335       sible  element in a pandoc document.  To get a documented example which
5336       you can modify according to your needs, do
5337
5338              pandoc --print-default-data-file sample.lua
5339
5340       Note that custom writers have no default template.  If you want to  use
5341       --standalone  with a custom writer, you will need to specify a template
5342       manually using --template or add a new default template with  the  name
5343       default.NAME_OF_CUSTOM_WRITER.lua to the templates subdirectory of your
5344       user data directory (see Templates).
5345

A NOTE ON SECURITY

5347       If you use pandoc to convert user-contributed content in a web applica‐
5348       tion, here are some things to keep in mind:
5349
5350       1. Although  pandoc  itself  will  not create or modify any files other
5351          than those you explicitly ask it create (with the exception of  tem‐
5352          porary  files  used  in  producing  PDFs), a filter or custom writer
5353          could in principle do anything on your file  system.   Please  audit
5354          filters and custom writers very carefully before using them.
5355
5356       2. If  your  application  uses pandoc as a Haskell library (rather than
5357          shelling out to the executable), it is possible to use it in a  mode
5358          that  fully  isolates  pandoc  from your file system, by running the
5359          pandoc operations in the PandocPure monad.  See the  document  Using
5360          the pandoc API for more details.
5361
5362       3. Pandoc's parsers can exhibit pathological performance on some corner
5363          cases.  It is wise to put any pandoc operations under a timeout,  to
5364          avoid  DOS  attacks that exploit these issues.  If you are using the
5365          pandoc executable, you can add the command line options +RTS  -M512M
5366          -RTS (for example) to limit the heap size to 512MB.
5367
5368       4. The  HTML  generated  by  pandoc  is  not guaranteed to be safe.  If
5369          raw_html is enabled for the Markdown input, users can  inject  arbi‐
5370          trary HTML.  Even if raw_html is disabled, users can include danger‐
5371          ous content in attributes for headings, spans, and code blocks.   To
5372          be safe, you should run all the generated HTML through an HTML sani‐
5373          tizer.
5374

AUTHORS

5376       Copyright 2006--2020 John MacFarlane (jgm@berkeley.edu).  Released  un‐
5377       der  the  GPL, version 2 or greater.  This software carries no warranty
5378       of any kind.  (See COPYRIGHT for full copyright and warranty  notices.)
5379       For  a full list of contributors, see the file AUTHORS.md in the pandoc
5380       source code.
5381
5382       The Pandoc source code and all documentation  may  be  downloaded  from
5383       <http://pandoc.org>.
5384
5385
5386
5387pandoc 2.9.2.1                  March 23, 2020           Pandoc User's Guide()
Impressum