## "Fossies" - the Fresh Open Source Software Archive

### Member "pandoc-2.18/MANUAL.txt" (4 Apr 2022, 261274 Bytes) of package /linux/www/pandoc-2.18.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "MANUAL.txt": 2.17.1.1_vs_2.18.

    1 ---
2 title: Pandoc User's Guide
3 author: John MacFarlane
4 date: April 4, 2022
5 ---
6
7 # Synopsis
8
9 pandoc [*options*] [*input-file*]...
10
11 # Description
12
13 Pandoc is a [Haskell] library for converting from one markup format to
14 another, and a command-line tool that uses this library.
15
16 Pandoc can convert between numerous markup and word processing formats,
17 including, but not limited to, various flavors of [Markdown], [HTML],
18 [LaTeX] and [Word docx]. For the full lists of input and output formats,
19 see the --from and --to [options below][General options].
20 Pandoc can also produce [PDF] output: see [creating a PDF], below.
21
22 Pandoc's enhanced version of Markdown includes syntax for [tables],
23 [definition lists], [metadata blocks], [footnotes], [citations], [math],
24 and much more.  See below under [Pandoc's Markdown].
25
26 Pandoc has a modular design: it consists of a set of readers, which parse
27 text in a given format and produce a native representation of the document
28 (an _abstract syntax tree_ or AST), and a set of writers, which convert
29 this native representation into a target format. Thus, adding an input
30 or output format requires only adding a reader or writer. Users can also
31 run custom [pandoc filters] to modify the intermediate AST.
32
33 Because pandoc's intermediate representation of a document is less
34 expressive than many of the formats it converts between, one should
35 not expect perfect conversions between every format and every other.
36 Pandoc attempts to preserve the structural elements of a document, but
37 not formatting details such as margin size.  And some document elements,
38 such as complex tables, may not fit into pandoc's simple document
39 model.  While conversions from pandoc's Markdown to all formats aspire
40 to be perfect, conversions from formats more expressive than pandoc's
41 Markdown can be expected to be lossy.
42
43 ## Using pandoc
44
45 If no *input-files* are specified, input is read from *stdin*.
46 Output goes to *stdout* by default. For output to a file,
47 use the -o option:
48
49     pandoc -o output.html input.txt
50
51 By default, pandoc produces a document fragment. To produce a standalone
52 document (e.g. a valid HTML file including <head> and <body>),
53 use the -s or --standalone flag:
54
55     pandoc -s -o output.html input.txt
56
58 [Templates] below.
59
60 If multiple input files are given, pandoc will concatenate them all (with
61 blank lines between them) before parsing. (Use --file-scope to parse files
62 individually.)
63
64 ## Specifying formats
65
66 The format of the input and output can be specified explicitly using
67 command-line options.  The input format can be specified using the
68 -f/--from option, the output format using the -t/--to option.
69 Thus, to convert hello.txt from Markdown to LaTeX, you could type:
70
71     pandoc -f markdown -t latex hello.txt
72
73 To convert hello.html from HTML to Markdown:
74
75     pandoc -f html -t markdown hello.html
76
77 Supported input and output formats are listed below under [Options]
78 (see -f for input formats and -t for output formats).  You
79 can also use pandoc --list-input-formats and
80 pandoc --list-output-formats to print lists of supported
81 formats.
82
83 If the input or output format is not specified explicitly, pandoc
84 will attempt to guess it from the extensions of the filenames.
85 Thus, for example,
86
87     pandoc -o hello.tex hello.txt
88
89 will convert hello.txt from Markdown to LaTeX.  If no output file
90 is specified (so that output goes to *stdout*), or if the output file's
91 extension is unknown, the output format will default to HTML.
92 If no input file is specified (so that input comes from *stdin*), or
93 if the input files' extensions are unknown, the input format will
94 be assumed to be Markdown.
95
96 ## Character encoding
97
98 Pandoc uses the UTF-8 character encoding for both input and output.
99 If your local character encoding is not UTF-8, you
100 should pipe input and output through [iconv]:
101
102     iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
103
104 Note that in some output formats (such as HTML, LaTeX, ConTeXt,
105 RTF, OPML, DocBook, and Texinfo), information about
106 the character encoding is included in the document header, which
107 will only be included if you use the -s/--standalone option.
108
109 [iconv]: https://www.gnu.org/software/libiconv/
110
111 ## Creating a PDF
112
113 To produce a PDF, specify an output file with a .pdf extension:
114
115     pandoc test.txt -o test.pdf
116
117 By default, pandoc will use LaTeX to create the PDF, which requires
118 that a LaTeX engine be installed (see --pdf-engine below).
119 Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an
120 intermediate format.  To do this, specify an output file with a
121 .pdf extension, as before, but add the --pdf-engine option
122 or -t context, -t html, or -t ms to the command line.
123 The tool used to generate the PDF from the intermediate format
124 may be specified using --pdf-engine.
125
126 You can control the PDF style using variables, depending on
127 the intermediate format used: see [variables for LaTeX],
128 [variables for ConTeXt], [variables for wkhtmltopdf],
129 [variables for ms].  When HTML is used as an intermediate
130 format, the output can be styled using --css.
131
132 To debug the PDF creation, it can be useful to look at the intermediate
133 representation: instead of -o test.pdf, use for example -s -o test.tex
134 to output the generated LaTeX. You can then test it with pdflatex test.tex.
135
136 When using LaTeX, the following packages need to be available
138 [amsfonts], [amsmath], [lm], [unicode-math],
139 [iftex], [listings] (if the
140 --listings option is used), [fancyvrb], [longtable],
141 [booktabs], [graphicx] (if the document
142 contains images), [hyperref], [xcolor],
143 [ulem], [geometry] (with the geometry variable set),
144 [setspace] (with linestretch), and
145 [babel] (with lang).  If CJKmainfont is set, [xeCJK]
146 is needed.  The use of xelatex or lualatex as
147 the PDF engine requires [fontspec].  lualatex uses
148 [selnolig]. xelatex uses [bidi] (with the dir variable set).
149 If the mathspec variable is set, xelatex will use [mathspec]
150 instead of [unicode-math].  The [upquote] and [microtype]
151 packages are used if available, and [csquotes] will be used
152 for [typography] if the csquotes variable or metadata field is
153 set to a true value.  The [natbib], [biblatex], [bibtex],
154 and [biber] packages can optionally be used for [citation
155 rendering].  The following packages will be used to improve
156 output quality if present, but pandoc does not require them to
157 be present: [upquote] (for straight quotes in verbatim
158 environments), [microtype] (for better spacing adjustments),
159 [parskip] (for better inter-paragraph spaces), [xurl] (for
160 better line breaks in URLs), [bookmark] (for better PDF
161 bookmarks), and [footnotehyper] or [footnote] (to allow
162 footnotes in tables).
163
164 [TeX Live]: https://www.tug.org/texlive/
165 [amsfonts]: https://ctan.org/pkg/amsfonts
166 [amsmath]: https://ctan.org/pkg/amsmath
167 [babel]: https://ctan.org/pkg/babel
168 [biber]: https://ctan.org/pkg/biber
169 [biblatex]: https://ctan.org/pkg/biblatex
170 [bibtex]: https://ctan.org/pkg/bibtex
171 [bidi]: https://ctan.org/pkg/bidi
172 [bookmark]: https://ctan.org/pkg/bookmark
173 [booktabs]: https://ctan.org/pkg/booktabs
174 [csquotes]: https://ctan.org/pkg/csquotes
175 [fancyvrb]: https://ctan.org/pkg/fancyvrb
176 [fontspec]: https://ctan.org/pkg/fontspec
177 [footnote]: https://ctan.org/pkg/footnote
178 [footnotehyper]: https://ctan.org/pkg/footnotehyper
179 [geometry]: https://ctan.org/pkg/geometry
180 [graphicx]: https://ctan.org/pkg/graphicx
181 [grffile]: https://ctan.org/pkg/grffile
182 [hyperref]: https://ctan.org/pkg/hyperref
183 [iftex]: https://ctan.org/pkg/iftex
184 [listings]: https://ctan.org/pkg/listings
185 [lm]: https://ctan.org/pkg/lm
186 [longtable]: https://ctan.org/pkg/longtable
187 [mathspec]: https://ctan.org/pkg/mathspec
188 [microtype]: https://ctan.org/pkg/microtype
189 [natbib]: https://ctan.org/pkg/natbib
190 [parskip]: https://ctan.org/pkg/parskip
191 [polyglossia]: https://ctan.org/pkg/polyglossia
192 [prince]: https://www.princexml.com/
193 [setspace]: https://ctan.org/pkg/setspace
194 [ulem]: https://ctan.org/pkg/ulem
195 [unicode-math]: https://ctan.org/pkg/unicode-math
196 [upquote]: https://ctan.org/pkg/upquote
197 [weasyprint]: https://weasyprint.org
198 [wkhtmltopdf]: https://wkhtmltopdf.org
199 [xcolor]: https://ctan.org/pkg/xcolor
200 [xeCJK]: https://ctan.org/pkg/xecjk
201 [xurl]: https://ctan.org/pkg/xurl
202 [selnolig]: https://ctan.org/pkg/selnolig
203
204
205
206 ## Reading from the Web
207
208 Instead of an input file, an absolute URI may be given. In this case
209 pandoc will fetch the content using HTTP:
210
211     pandoc -f html -t markdown https://www.fsf.org
212
213 It is possible to supply a custom User-Agent string or other
214 header when requesting a document from a URL:
215
216     pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
217       https://www.fsf.org
218
219 # Options
220
221 ## General options {.options}
222
223 -f *FORMAT*, -r *FORMAT*, --from=*FORMAT*, --read=*FORMAT*
224
225 :   Specify input format.  *FORMAT* can be:
226
227     ::: {#input-formats}
228     - bibtex ([BibTeX] bibliography)
229     - biblatex ([BibLaTeX] bibliography)
230     - commonmark ([CommonMark] Markdown)
231     - commonmark_x ([CommonMark] Markdown with extensions)
232     - creole ([Creole 1.0])
233     - csljson ([CSL JSON] bibliography)
234     - csv ([CSV] table)
235     - docbook ([DocBook])
236     - docx ([Word docx])
237     - dokuwiki ([DokuWiki markup])
238     - endnotexml ([EndNote XML bibliography])
239     - epub ([EPUB])
240     - fb2 ([FictionBook2] e-book)
241     - gfm ([GitHub-Flavored Markdown]),
242       or the deprecated and less accurate markdown_github;
243       use [markdown_github](#markdown-variants) only
244       if you need extensions not supported in [gfm](#markdown-variants).
245     - haddock ([Haddock markup])
246     - html ([HTML])
247     - ipynb ([Jupyter notebook])
248     - jats ([JATS] XML)
249     - jira ([Jira]/Confluence wiki markup)
250     - json (JSON version of native AST)
251     - latex ([LaTeX])
252     - markdown ([Pandoc's Markdown])
253     - markdown_mmd ([MultiMarkdown])
254     - markdown_phpextra ([PHP Markdown Extra])
255     - markdown_strict (original unextended [Markdown])
256     - mediawiki ([MediaWiki markup])
257     - man ([roff man])
258     - muse ([Muse])
259     - native (native Haskell)
260     - odt ([ODT])
261     - opml ([OPML])
262     - org ([Emacs Org mode])
263     - ris ([RIS] bibliography)
264     - rtf ([Rich Text Format])
265     - rst ([reStructuredText])
266     - t2t ([txt2tags])
267     - textile ([Textile])
268     - tikiwiki ([TikiWiki markup])
269     - twiki ([TWiki markup])
270     - vimwiki ([Vimwiki])
271     - the path of a custom Lua reader, see [Custom readers and writers] below
272     :::
273
274     Extensions can be individually enabled or disabled by
275     appending +EXTENSION or -EXTENSION to the format name.
276     See [Extensions] below, for a list of extensions and
277     their names.  See --list-input-formats and --list-extensions,
278     below.
279
280 -t *FORMAT*, -w *FORMAT*, --to=*FORMAT*, --write=*FORMAT*
281
282 :   Specify output format.  *FORMAT* can be:
283
284     ::: {#output-formats}
285     - asciidoc ([AsciiDoc]) or asciidoctor ([AsciiDoctor])
286     - beamer ([LaTeX beamer][beamer] slide show)
287     - bibtex ([BibTeX] bibliography)
288     - biblatex ([BibLaTeX] bibliography)
289     - commonmark ([CommonMark] Markdown)
290     - commonmark_x ([CommonMark] Markdown with extensions)
291     - context ([ConTeXt])
292     - csljson ([CSL JSON] bibliography)
293     - docbook or docbook4 ([DocBook] 4)
294     - docbook5 (DocBook 5)
295     - docx ([Word docx])
296     - dokuwiki ([DokuWiki markup])
297     - epub or epub3 ([EPUB] v3 book)
298     - epub2 (EPUB v2)
299     - fb2 ([FictionBook2] e-book)
300     - gfm ([GitHub-Flavored Markdown]),
301       or the deprecated and less accurate markdown_github;
302       use [markdown_github](#markdown-variants) only
303       if you need extensions not supported in [gfm](#markdown-variants).
304     - haddock ([Haddock markup])
305     - html or html5 ([HTML], i.e. [HTML5]/XHTML [polyglot markup])
306     - html4 ([XHTML] 1.0 Transitional)
307     - icml ([InDesign ICML])
308     - ipynb ([Jupyter notebook])
309     - jats_archiving ([JATS] XML, Archiving and Interchange Tag Set)
310     - jats_articleauthoring ([JATS] XML, Article Authoring Tag Set)
311     - jats_publishing ([JATS] XML, Journal Publishing Tag Set)
312     - jats (alias for jats_archiving)
313     - jira ([Jira]/Confluence wiki markup)
314     - json (JSON version of native AST)
315     - latex ([LaTeX])
316     - man ([roff man])
317     - markdown ([Pandoc's Markdown])
318     - markdown_mmd ([MultiMarkdown])
319     - markdown_phpextra ([PHP Markdown Extra])
320     - markdown_strict (original unextended [Markdown])
321     - markua ([Markua])
322     - mediawiki ([MediaWiki markup])
323     - ms ([roff ms])
324     - muse ([Muse]),
325     - native (native Haskell),
326     - odt ([OpenOffice text document][ODT])
327     - opml ([OPML])
328     - opendocument ([OpenDocument])
329     - org ([Emacs Org mode])
330     - pdf ([PDF])
331     - plain (plain text),
332     - pptx ([PowerPoint] slide show)
333     - rst ([reStructuredText])
334     - rtf ([Rich Text Format])
335     - texinfo ([GNU Texinfo])
336     - textile ([Textile])
337     - slideous ([Slideous] HTML and JavaScript slide show)
338     - slidy ([Slidy] HTML and JavaScript slide show)
339     - dzslides ([DZSlides] HTML5 + JavaScript slide show),
340     - revealjs ([reveal.js] HTML5 + JavaScript slide show)
341     - s5 ([S5] HTML and JavaScript slide show)
342     - tei ([TEI Simple])
343     - xwiki ([XWiki markup])
344     - zimwiki ([ZimWiki markup])
345     - the path of a custom Lua writer, see [Custom readers and writers] below
346     :::
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
352     disabled by appending +EXTENSION or -EXTENSION to the format
353     name.  See [Extensions] below, for a list of extensions and their
354     names.  See --list-output-formats and --list-extensions, below.
355
356 -o *FILE*, --output=*FILE*
357
358 :   Write output to *FILE* instead of *stdout*.  If *FILE* is
359     -, output will go to *stdout*, even if a non-textual format
360     (docx, odt, epub2, epub3) is specified.
361
362 --data-dir=*DIRECTORY*
363
364 :   Specify the user data directory to search for pandoc data files.
365     If this option is not specified, the default user data directory
366     will be used.  On \*nix and macOS systems this will be the pandoc
367     subdirectory of the XDG data directory (by default,
368     $HOME/.local/share, overridable by setting the XDG_DATA_HOME 369 environment variable). If that directory does not exist and 370 $HOME/.pandoc exists, it will be used (for backwards compatibility).
371     On Windows the default user data directory is
372     C:\Users\USERNAME\AppData\Roaming\pandoc.
373     You can find the default user data directory on your system by
374     looking at the output of pandoc --version.
375     Data files placed in this directory (for example, reference.odt,
376     reference.docx, epub.css, templates) will override
377     pandoc's normal defaults.
378
379 -d *FILE*, --defaults=*FILE*
380
381 :   Specify a set of default option settings.  *FILE* is a YAML
382     file whose fields correspond to command-line option
383     settings.  All options for document conversion, including input
384     and output files, can be set using a defaults file.  The file will
385     be searched for first in the working directory, and then in
386     the defaults subdirectory of the user data directory
387     (see --data-dir).  The .yaml extension may be omitted.
389     file format.  Settings from the defaults file may be
390     overridden or extended by subsequent options on the command
391     line.
392
393 --bash-completion
394
395 :   Generate a bash completion script.  To enable bash completion
396     with pandoc, add this to your .bashrc:
397
398         eval "$(pandoc --bash-completion)" 399 400 --verbose 401 402 : Give verbose debugging output. 403 404 --quiet 405 406 : Suppress warning messages. 407 408 --fail-if-warnings 409 410 : Exit with error status if there are any warnings. 411 412 --log=*FILE* 413 414 : Write log messages in machine-readable JSON format to 415 *FILE*. All messages above DEBUG level will be written, 416 regardless of verbosity settings (--verbose, --quiet). 417 418 --list-input-formats 419 420 : List supported input formats, one per line. 421 422 --list-output-formats 423 424 : List supported output formats, one per line. 425 426 --list-extensions[=*FORMAT*] 427 428 : List supported extensions for *FORMAT*, one per line, preceded 429 by a + or - indicating whether it is enabled by default 430 in *FORMAT*. If *FORMAT* is not specified, defaults for 431 pandoc's Markdown are given. 432 433 --list-highlight-languages 434 435 : List supported languages for syntax highlighting, one per 436 line. 437 438 --list-highlight-styles 439 440 : List supported styles for syntax highlighting, one per line. 441 See --highlight-style. 442 443 -v, --version 444 445 : Print version. 446 447 -h, --help 448 449 : Show usage message. 450 451 [Markdown]: https://daringfireball.net/projects/markdown/ 452 [CommonMark]: https://commonmark.org 453 [PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/ 454 [GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/ 455 [MultiMarkdown]: https://fletcherpenney.net/multimarkdown/ 456 [reStructuredText]: https://docutils.sourceforge.io/docs/ref/rst/introduction.html 457 [S5]: https://meyerweb.com/eric/tools/s5/ 458 [Slidy]: https://www.w3.org/Talks/Tools/Slidy2/ 459 [Slideous]: https://goessner.net/articles/slideous/ 460 [HTML]: https://www.w3.org/html/ 461 [HTML5]: https://html.spec.whatwg.org/ 462 [polyglot markup]: https://www.w3.org/TR/html-polyglot/ 463 [XHTML]: https://www.w3.org/TR/xhtml1/ 464 [LaTeX]: https://www.latex-project.org/ 465 [beamer]: https://ctan.org/pkg/beamer 466 [Beamer User's Guide]: http://mirrors.ctan.org/macros/latex/contrib/beamer/doc/beameruserguide.pdf 467 [ConTeXt]: https://www.contextgarden.net/ 468 [Rich Text Format]: https://en.wikipedia.org/wiki/Rich_Text_Format 469 [DocBook]: https://docbook.org 470 [JATS]: https://jats.nlm.nih.gov 471 [Jira]: https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all 472 [txt2tags]: https://txt2tags.org 473 [EPUB]: http://idpf.org/epub 474 [OPML]: http://dev.opml.org/spec2.html 475 [OpenDocument]: http://opendocument.xml.org 476 [ODT]: https://en.wikipedia.org/wiki/OpenDocument 477 [Textile]: https://www.promptworks.com/textile 478 [MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting 479 [DokuWiki markup]: https://www.dokuwiki.org/dokuwiki 480 [ZimWiki markup]: https://zim-wiki.org/manual/Help/Wiki_Syntax.html 481 [XWiki markup]: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/ 482 [TWiki markup]: https://twiki.org/cgi-bin/view/TWiki/TextFormattingRules 483 [TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax 484 [Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html 485 [Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0 486 [CSV]: https://tools.ietf.org/html/rfc4180 487 [roff man]: https://man.cx/groff_man(7) 488 [roff ms]: https://man.cx/groff_ms(7) 489 [Haskell]: https://www.haskell.org 490 [GNU Texinfo]: https://www.gnu.org/software/texinfo/ 491 [RIS]: https://en.wikipedia.org/wiki/RIS_(file_format) 492 [Emacs Org mode]: https://orgmode.org 493 [AsciiDoc]: https://www.methods.co.nz/asciidoc/ 494 [AsciiDoctor]: https://asciidoctor.org/ 495 [DZSlides]: https://paulrouget.com/dzslides/ 496 [Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML 497 [PDF]: https://www.adobe.com/pdf/ 498 [reveal.js]: https://revealjs.com/ 499 [FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1 500 [Jupyter notebook]: https://nbformat.readthedocs.io/en/latest/ 501 [InDesign ICML]: https://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf 502 [TEI Simple]: https://github.com/TEIC/TEI-Simple 503 [Muse]: https://amusewiki.org/library/manual 504 [PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint 505 [Vimwiki]: https://vimwiki.github.io 506 [CSL JSON]: https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html 507 [BibTeX]: https://ctan.org/pkg/bibtex 508 [BibLaTeX]: https://ctan.org/pkg/biblatex 509 [Markua]: https://leanpub.com/markua/read 510 [EndNote XML bibliography]: https://support.clarivate.com/Endnote/s/article/EndNote-XML-Document-Type-Definition 511 512 ## Reader options {.options} 513 514 --shift-heading-level-by=*NUMBER* 515 516 : Shift heading levels by a positive or negative integer. 517 For example, with --shift-heading-level-by=-1, level 2 518 headings become level 1 headings, and level 3 headings 519 become level 2 headings. Headings cannot have a level 520 less than 1, so a heading that would be shifted below level 1 521 becomes a regular paragraph. Exception: with a shift of -N, 522 a level-N heading at the beginning of the document 523 replaces the metadata title. --shift-heading-level-by=-1 524 is a good choice when converting HTML or Markdown documents that 525 use an initial level-1 heading for the document title and 526 level-2+ headings for sections. --shift-heading-level-by=1 527 may be a good choice for converting Markdown documents that 528 use level-1 headings for sections to HTML, since pandoc uses 529 a level-1 heading to render the document title. 530 531 --base-header-level=*NUMBER* 532 533 : *Deprecated. Use --shift-heading-level-by=X instead, 534 where X = NUMBER - 1.* Specify the base level for headings 535 (defaults to 1). 536 537 --strip-empty-paragraphs 538 539 : *Deprecated. Use the +empty_paragraphs extension instead.* 540 Ignore paragraphs with no content. This option is useful 541 for converting word processing documents where users have 542 used empty paragraphs to create inter-paragraph space. 543 544 --indented-code-classes=*CLASSES* 545 546 : Specify classes to use for indented code blocks--for example, 547 perl,numberLines or haskell. Multiple classes may be separated 548 by spaces or commas. 549 550 --default-image-extension=*EXTENSION* 551 552 : Specify a default extension to use when image paths/URLs have no 553 extension. This allows you to use the same source for formats that 554 require different kinds of images. Currently this option only affects 555 the Markdown and LaTeX readers. 556 557 --file-scope 558 559 : Parse each file individually before combining for multifile 560 documents. This will allow footnotes in different files with the 561 same identifiers to work as expected. If this option is set, 562 footnotes and links will not work across files. Reading binary 563 files (docx, odt, epub) implies --file-scope. 564 565 -F *PROGRAM*, --filter=*PROGRAM* 566 567 : Specify an executable to be used as a filter transforming the 568 pandoc AST after the input is parsed and before the output is 569 written. The executable should read JSON from stdin and write 570 JSON to stdout. The JSON must be formatted like pandoc's own 571 JSON input and output. The name of the output format will be 572 passed to the filter as the first argument. Hence, 573 574 pandoc --filter ./caps.py -t latex 575 576 is equivalent to 577 578 pandoc -t json | ./caps.py latex | pandoc -f json -t latex 579 580 The latter form may be useful for debugging filters. 581 582 Filters may be written in any language. Text.Pandoc.JSON 583 exports toJSONFilter to facilitate writing filters in Haskell. 584 Those who would prefer to write filters in python can use the 585 module [pandocfilters], installable from PyPI. There are also 586 pandoc filter libraries in [PHP], [perl], and 587 [JavaScript/node.js]. 588 589 In order of preference, pandoc will look for filters in 590 591 1. a specified full or relative path (executable or 592 non-executable) 593 594 2. $DATADIR/filters (executable or non-executable)
595      where $DATADIR is the user data directory (see 596 --data-dir, above). 597 598 3. $PATH (executable only)
599
600     Filters, Lua-filters, and citeproc processing are applied in
601     the order specified on the command line.
602
603 -L *SCRIPT*, --lua-filter=*SCRIPT*
604
605 :   Transform the document in a similar fashion as JSON filters (see
606     --filter), but use pandoc's built-in Lua filtering system.  The given
607     Lua script is expected to return a list of Lua filters which will be
608     applied in order.  Each Lua filter must contain element-transforming
609     functions indexed by the name of the AST element on which the filter
610     function should be applied.
611
612     The pandoc Lua module provides helper functions for element
613     creation.  It is always loaded into the script's Lua environment.
614
615     See the [Lua filters documentation] for further details.
616
617     In order of preference, pandoc will look for Lua filters in
618
619      1. a specified full or relative path
620
621      2. $DATADIR/filters where $DATADIR is the user data
622      directory (see --data-dir, above).
623
624     Filters, Lua filters, and citeproc processing are applied in
625     the order specified on the command line.
626
627 -M *KEY*[=*VAL*], --metadata=*KEY*[:*VAL*]
628
629 :   Set the metadata field *KEY* to the value *VAL*.  A value specified
630     on the command line overrides a value specified in the document
631     using [YAML metadata blocks][Extension: yaml_metadata_block].
632     Values will be parsed as YAML boolean or string values. If no value is
633     specified, the value will be treated as Boolean true.  Like
634     --variable, --metadata causes template variables to be set.
635     But unlike --variable, --metadata affects the metadata of the
636     underlying document (which is accessible from filters and may be
637     printed in some output formats) and metadata values will be escaped
638     when inserted into the template.
639
640 --metadata-file=*FILE*
641
642 :   Read metadata from the supplied YAML (or JSON) file. This
643     option can be used with every input format, but string scalars
644     in the YAML file will always be parsed as Markdown. (If the
645     input format is Markdown or a Markdown variant, then the
646     same variant will be used to parse the metadata file;
647     if it is a non-Markdown format, pandoc's default Markdown
648     extensions will be used.) This option can be used
649     repeatedly to include multiple metadata files; values in
650     files specified later on the command line will be preferred
651     over those specified in earlier files. Metadata values
652     specified inside the document, or by using -M, overwrite
653     values specified with this option. The file will be searched
654     for first in the working directory, and then in the metadata
655     subdirectory of the user data directory (see --data-dir).
656
657 -p, --preserve-tabs
658
659 :   Preserve tabs instead of converting them to spaces. (By default, pandoc
660     converts tabs to spaces before parsing its input.)  Note that this will
661     only affect tabs in literal code spans and code blocks. Tabs in regular
662     text are always treated as spaces.
663
664 --tab-stop=*NUMBER*
665
666 :   Specify the number of spaces per tab (default is 4).
667
668 --track-changes=accept|reject|all
669
670 :   Specifies what to do with insertions, deletions, and comments
671     produced by the MS Word "Track Changes" feature.  accept (the
672     default) processes all the insertions and deletions.
673     reject ignores them.  Both accept and reject ignore comments.
674     all includes all insertions, deletions, and comments, wrapped
675     in spans with insertion, deletion, comment-start, and
676     comment-end classes, respectively. The author and time of
677     change is included. all is useful for scripting: only
678     accepting changes from a certain reviewer, say, or before a
679     certain date. If a paragraph is inserted or deleted,
680     track-changes=all produces a span with the class
681     paragraph-insertion/paragraph-deletion before the
682     affected paragraph break. This option only affects the docx
684
685 --extract-media=*DIR*
686
687 :   Extract images and other media contained in or linked from
688     the source document to the path *DIR*, creating it if
689     necessary, and adjust the images references in the document
691     read from the file system, or extracted from a binary
692     container (e.g. docx), as needed.  The original file paths
693     are used if they are relative paths not containing ...
694     Otherwise filenames are constructed from the SHA1 hash of
695     the contents.
696
697 --abbreviations=*FILE*
698
699 :   Specifies a custom abbreviations file, with abbreviations
700     one to a line.  If this option is not specified, pandoc will
701     read the data file abbreviations from the user data
702     directory or fall back on a system default.  To see the
703     system default, use
704     pandoc --print-default-data-file=abbreviations.  The only
705     use pandoc makes of this list is in the Markdown reader.
706     Strings found in this list will be followed by a nonbreaking
707     space, and the period will not produce sentence-ending space
708     in formats like LaTeX.  The strings may not contain spaces.
709
710 --trace
711
712 :   Print diagnostic output tracing parser progress to stderr.
713     This option is intended for use by developers in diagnosing
714     performance issues.
715
716 [pandocfilters]: https://github.com/jgm/pandocfilters
717 [PHP]: https://github.com/vinai/pandocfilters-php
718 [perl]: https://metacpan.org/pod/Pandoc::Filter
719 [JavaScript/node.js]: https://github.com/mvhenderson/pandoc-filter-node
720 [Lua filters documentation]: https://pandoc.org/lua-filters.html
721
722 ## General writer options {.options}
723
724 -s, --standalone
725
726 :   Produce output with an appropriate header and footer (e.g. a
727     standalone HTML, LaTeX, TEI, or RTF file, not a fragment).  This option
728     is set automatically for pdf, epub, epub3, fb2, docx, and odt
729     output.  For native output, this option causes metadata to
730     be included; otherwise, metadata is suppressed.
731
732 --template=*FILE*|*URL*
733
734 :   Use the specified file as a custom template for the generated document.
735     Implies --standalone. See [Templates], below, for a description
736     of template syntax. If no extension is specified, an extension
737     corresponding to the writer will be added, so that --template=special
738     looks for special.html for HTML output.  If the template is not
739     found, pandoc will search for it in the templates subdirectory of
740     the user data directory (see --data-dir). If this option is not used,
741     a default template appropriate for the output format will be used (see
742     -D/--print-default-template).
743
744 -V *KEY*[=*VAL*], --variable=*KEY*[:*VAL*]
745
746 :   Set the template variable *KEY* to the value *VAL* when rendering the
747     document in standalone mode. If no *VAL* is specified, the
748     key will be given the value true.
749
750 --sandbox
751
752 :   Run pandoc in a sandbox, limiting IO operations in readers
753     and writers to reading the files specified on the command line.
754     Note that this option does not limit IO operations by
755     filters or in the production of PDF documents.  But it does
756     offer security against, for example, disclosure of files
757     through the use of include directives.  Anyone using
758     pandoc on untrusted user input should use this option.
759
760 -D *FORMAT*, --print-default-template=*FORMAT*
761
762 :   Print the system default template for an output *FORMAT*. (See -t
763     for a list of possible *FORMAT*s.)  Templates in the user data
764     directory are ignored.  This option may be used with
765     -o/--output to redirect output to a file, but
766     -o/--output must come before --print-default-template
767     on the command line.
768
769     Note that some of the default templates use partials, for
770     example styles.html.  To print the partials, use
771     --print-default-data-file: for example,
772     --print-default-data-file=templates/styles.html.
773
774 --print-default-data-file=*FILE*
775
776 :   Print a system default data file.  Files in the user data directory
777     are ignored.  This option may be used with -o/--output to
778     redirect output to a file, but -o/--output must come before
779     --print-default-data-file on the command line.
780
781 --eol=crlf|lf|native
782
783 :   Manually specify line endings: crlf (Windows), lf
784     (macOS/Linux/UNIX), or native (line endings appropriate
785     to the OS on which pandoc is being run).  The default is
786     native.
787
788 --dpi=*NUMBER*
789
790 :   Specify the default dpi (dots per inch) value for conversion
791     from pixels to inch/centimeters and vice versa. (Technically,
792     the correct term would be ppi: pixels per inch.) The default
793     is 96dpi.   When images contain information about dpi
794     internally, the encoded value is used instead of the default
795     specified by this option.
796
797 --wrap=auto|none|preserve
798
799 :   Determine how text is wrapped in the output (the source
800     code, not the rendered version).  With auto (the default),
801     pandoc will attempt to wrap lines to the column width specified by
802     --columns (default 72).  With none, pandoc will not wrap
803     lines at all.  With preserve, pandoc will attempt to
804     preserve the wrapping from the source document (that is,
805     where there are nonsemantic newlines in the source, there
806     will be nonsemantic newlines in the output as well).
807     In ipynb output, this option affects wrapping of the
808     contents of markdown cells.
809
810 --columns=*NUMBER*
811
812 :   Specify length of lines in characters.  This affects text wrapping
813     in the generated source code (see --wrap).  It also affects
814     calculation of column widths for plain text tables (see [Tables] below).
815
816 --toc, --table-of-contents
817
819     the case of latex, context, docx, odt,
820     opendocument, rst, or ms, an instruction to create
821     one) in the output document. This option has no effect
822     unless -s/--standalone is used, and it has no effect
823     on man, docbook4, docbook5, or jats output.
824
825     Note that if you are producing a PDF via ms, the table
826     of contents will appear at the beginning of the
827     document, before the title.  If you would prefer it to
828     be at the end of the document, use the option
829     --pdf-engine-opt=--no-toc-relocation.
830
831 --toc-depth=*NUMBER*
832
833 :   Specify the number of section levels to include in the table
834     of contents.  The default is 3 (which means that level-1, 2, and 3
835     headings will be listed in the contents).
836
837 --strip-comments
838
839 :   Strip out HTML comments in the Markdown or Textile source,
840     rather than passing them on to Markdown, Textile or HTML
841     output as raw HTML.  This does not apply to HTML comments
842     inside raw HTML blocks when the markdown_in_html_blocks
843     extension is not set.
844
845 --no-highlight
846
847 :   Disables syntax highlighting for code blocks and inlines, even when
848     a language attribute is given.
849
850 --highlight-style=*STYLE*|*FILE*
851
852 :   Specifies the coloring style to be used in highlighted source code.
853     Options are pygments (the default), kate, monochrome,
854     breezeDark, espresso, zenburn, haddock, and tango.
857     --list-highlight-styles.
858
859     Instead of a *STYLE* name, a JSON file with extension
860     .theme may be supplied.  This will be parsed as a KDE
861     syntax highlighting theme and (if valid) used as the
862     highlighting style.
863
864     To generate the JSON version of an existing style,
865     use --print-highlight-style.
866
867 --print-highlight-style=*STYLE*|*FILE*
868
869 :   Prints a JSON version of a highlighting style, which can
870     be modified, saved with a .theme extension, and used
871     with --highlight-style.  This option may be used with
872     -o/--output to redirect output to a file, but
873     -o/--output must come before --print-highlight-style
874     on the command line.
875
876 --syntax-definition=*FILE*
877
878 :   Instructs pandoc to load a KDE XML syntax definition file,
879     which will be used for syntax highlighting of appropriately
880     marked code blocks.  This can be used to add support for
881     new languages or to use altered syntax definitions for
882     existing languages.  This option may be repeated to add
883     multiple syntax definitions.
884
885 -H *FILE*, --include-in-header=*FILE*|*URL*
886
887 :   Include contents of *FILE*, verbatim, at the end of the header.
888     This can be used, for example, to include special
889     CSS or JavaScript in HTML documents.  This option can be used
890     repeatedly to include multiple files in the header.  They will be
891     included in the order specified.  Implies --standalone.
892
893 -B *FILE*, --include-before-body=*FILE*|*URL*
894
895 :   Include contents of *FILE*, verbatim, at the beginning of the
896     document body (e.g. after the <body> tag in HTML, or the
897     \begin{document} command in LaTeX). This can be used to include
898     navigation bars or banners in HTML documents. This option can be
899     used repeatedly to include multiple files. They will be included in
900     the order specified.  Implies --standalone.
901
902 -A *FILE*, --include-after-body=*FILE*|*URL*
903
904 :   Include contents of *FILE*, verbatim, at the end of the document
905     body (before the </body> tag in HTML, or the
906     \end{document} command in LaTeX). This option can be used
907     repeatedly to include multiple files. They will be included in the
908     order specified.  Implies --standalone.
909
910 --resource-path=*SEARCHPATH*
911
912 :   List of paths to search for images and other resources.
913     The paths should be separated by : on Linux, UNIX, and
914     macOS systems, and by ; on Windows.  If --resource-path
915     is not specified, the default resource path is the working
916     directory. Note that, if --resource-path is specified,
917     the working directory must be explicitly listed or it
918     will not be searched.  For example:
919     --resource-path=.:test will search the working directory
920     and the test subdirectory, in that order.
921     This option can be used repeatedly. Search path components
922     that come later on the command line will be searched before
923     those that come earlier, so
924     --resource-path foo:bar --resource-path baz:bim is
925     equivalent to --resource-path baz:bim:foo:bar.
926
927 --request-header=*NAME*:*VAL*
928
929 :   Set the request header *NAME* to the value *VAL* when making
930     HTTP requests (for example, when a URL is given on the
931     command line, or when resources used in a document must be
932     downloaded). If you're behind a proxy, you also need to set
933     the environment variable http_proxy to http://....
934
935 --no-check-certificate
936
938     unsecure HTTP resources (for example when the certificate
939     is no longer valid or self signed).
940
941 ## Options affecting specific writers {.options}
942
943 --self-contained
944
945 :   Produce a standalone HTML file with no external dependencies, using
946     data: URIs to incorporate the contents of linked scripts, stylesheets,
947     images, and videos. Implies --standalone. The resulting file should be
948     "self-contained," in the sense that it needs no external files and no net
949     access to be displayed properly by a browser. This option works only with
950     HTML output formats, including html4, html5, html+lhs, html5+lhs,
951     s5, slidy, slideous, dzslides, and revealjs. Scripts, images,
952     and stylesheets at absolute URLs will be downloaded; those at relative
953     URLs will be sought relative to the working directory (if the first source
954     file is local) or relative to the base URL (if the first source
955     file is remote).  Elements with the attribute
956     data-external="1" will be left alone; the documents they
957     link to will not be incorporated in the document.
958     Limitation: resources that are loaded dynamically through
959     JavaScript cannot be incorporated; as a result, some
960     advanced features (e.g.  zoom or speaker notes) may not work
961     in an offline "self-contained" reveal.js slide show.
962
963 --html-q-tags
964
965 :   Use <q> tags for quotes in HTML.  (This option only has an
966     effect if the smart extension is enabled for the input
967     format used.)
968
969 --ascii
970
971 :   Use only ASCII characters in output. Currently supported for XML
972     and HTML formats (which use entities instead of UTF-8 when this
973     option is selected), CommonMark, gfm, and Markdown (which use
974     entities), roff ms (which use hexadecimal escapes), and to a
975     limited degree LaTeX (which uses standard commands for accented
976     characters when possible). roff man output uses ASCII by default.
977
978 --reference-links
979
980 :   Use reference-style links, rather than inline links, in writing Markdown
981     or reStructuredText.  By default inline links are used.  The
982     placement of link references is affected by the
983     --reference-location option.
984
985 --reference-location=block|section|document
986
987 :   Specify whether footnotes (and references, if reference-links is
988     set) are placed at the end of the current (top-level) block, the
989     current section, or the document. The default is
990     document. Currently this option only affects the
991     markdown, muse, html, epub, slidy, s5, slideous,
992     dzslides, and revealjs writers.
993
994 --markdown-headings=setext|atx
995
996 :   Specify whether to use ATX-style (#-prefixed) or
997     Setext-style (underlined) headings for level 1 and 2
998     headings in Markdown output.  (The default is atx.)
999     ATX-style headings are always used for levels 3+.
1000     This option also affects Markdown cells in ipynb output.
1001
1002 --atx-headers
1003
1004 :   *Deprecated synonym for --markdown-headings=atx.*
1005
1006 --top-level-division=default|section|chapter|part
1007
1008 :   Treat top-level headings as the given division type in
1009     LaTeX, ConTeXt, DocBook, and  TEI output. The hierarchy
1010     order is part, chapter, then section; all headings are
1011     shifted such that the top-level heading becomes the
1012     specified type. The default behavior is to determine the
1013     best division type via heuristics: unless other conditions
1014     apply, section is chosen. When the documentclass
1015     variable is set to report, book, or memoir (unless the
1016     article option is specified), chapter is implied as the
1017     setting for this option. If beamer is the output format,
1018     specifying either chapter or part will cause top-level
1019     headings to become \part{..}, while second-level headings
1020     remain as their default type.
1021
1022 -N, --number-sections
1023
1024 :   Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB
1025     output.  By default, sections are not numbered.  Sections with class
1026     unnumbered will never be numbered, even if --number-sections
1027     is specified.
1028
1029 --number-offset=*NUMBER*[,*NUMBER*,*...*]
1030
1031 :   Offset for section headings in HTML output (ignored in other
1032     output formats).  The first number is added to the section number for
1034     So, for example, if you want the first top-level heading in your
1035     document to be numbered "6", specify --number-offset=5.
1036     If your document starts with a level-2 heading which you want to
1037     be numbered "1.5", specify --number-offset=1,4.
1038     Offsets are 0 by default.  Implies --number-sections.
1039
1040 --listings
1041
1042 :   Use the [listings] package for LaTeX code blocks. The package
1043     does not support multi-byte encoding for source code. To handle UTF-8
1044     you would need to use a custom template. This issue is fully
1045     documented here: [Encoding issue with the listings package].
1046
1047 -i, --incremental
1048
1049 :   Make list items in slide shows display incrementally (one by one).
1050     The default is for lists to be displayed all at once.
1051
1052 --slide-level=*NUMBER*
1053
1054 :   Specifies that headings with the specified level create
1055     slides (for beamer, s5, slidy, slideous, dzslides).  Headings
1056     above this level in the hierarchy are used to divide the slide show
1057     into sections; headings below this level create subheads within a slide.
1058     Valid values are 0-6.  If a slide level of 0 is specified, slides will
1059     not be split automatically on headings, and horizontal rules must be used
1060     to indicate slide boundaries.  If a slide level is not specified
1061     explicitly, the slide level will be set automatically based on
1062     the contents of the document; see [Structuring the slide show].
1063
1064 --section-divs
1065
1066 :   Wrap sections in <section> tags (or <div> tags for html4),
1067     and attach identifiers to the enclosing <section> (or <div>)
1068     rather than the heading itself. See
1070
1071 --email-obfuscation=none|javascript|references
1072
1073 :   Specify a method for obfuscating mailto: links in HTML documents.
1074     none leaves mailto: links as they are.  javascript obfuscates
1075     them using JavaScript. references obfuscates them by printing their
1076     letters as decimal or hexadecimal character references.  The default
1077     is none.
1078
1079 --id-prefix=*STRING*
1080
1081 :   Specify a prefix to be added to all identifiers and internal links
1082     in HTML and DocBook output, and to footnote numbers in Markdown
1083     and Haddock output. This is useful for preventing duplicate
1084     identifiers when generating fragments to be included in other pages.
1085
1086 -T *STRING*, --title-prefix=*STRING*
1087
1088 :   Specify *STRING* as a prefix at the beginning of the title
1089     that appears in the HTML header (but not in the title as it
1090     appears at the beginning of the HTML body).  Implies --standalone.
1091
1092 -c *URL*, --css=*URL*
1093
1094 :   Link to a CSS style sheet. This option can be used repeatedly to
1095     include multiple files. They will be included in the order specified.
1096
1097     A stylesheet is required for generating EPUB.  If none is
1098     provided using this option (or the css or stylesheet
1099     metadata fields), pandoc will look for a file epub.css in the
1100     user data directory (see --data-dir).  If it is not
1101     found there, sensible defaults will be used.
1102
1103 --reference-doc=*FILE*
1104
1105 :   Use the specified file as a style reference in producing a
1106     docx or ODT file.
1107
1108     Docx
1109
1110     :   For best results, the reference docx should be a modified
1111         version of a docx file produced using pandoc.  The contents
1112         of the reference docx are ignored, but its stylesheets and
1113         document properties (including margins, page size, header,
1114         and footer) are used in the new docx. If no reference docx
1115         is specified on the command line, pandoc will look for a
1116         file reference.docx in the user data directory (see
1117         --data-dir). If this is not found either, sensible
1118         defaults will be used.
1119
1120         To produce a custom reference.docx, first get a copy of
1121         the default reference.docx: pandoc
1122         -o custom-reference.docx --print-default-data-file reference.docx.
1123         Then open custom-reference.docx in Word, modify the
1124         styles as you wish, and save the file.  For best
1125         results, do not make changes to this file other than
1126         modifying the styles used by pandoc:
1127
1128         Paragraph styles:
1129
1130         - Normal
1131         - Body Text
1132         - First Paragraph
1133         - Compact
1134         - Title
1135         - Subtitle
1136         - Author
1137         - Date
1138         - Abstract
1139         - Bibliography
1149         - Block Text
1150         - Footnote Text
1151         - Definition Term
1152         - Definition
1153         - Caption
1154         - Table Caption
1155         - Image Caption
1156         - Figure
1157         - Captioned Figure
1159
1160         Character styles:
1161
1162         - Default Paragraph Font
1163         - Body Text Char
1164         - Verbatim Char
1165         - Footnote Reference
1167         - Section Number
1168
1169         Table style:
1170
1171         - Table
1172
1173     ODT
1174
1175     :   For best results, the reference ODT should be a modified
1176         version of an ODT produced using pandoc.  The contents of
1177         the reference ODT are ignored, but its stylesheets are used
1178         in the new ODT. If no reference ODT is specified on the
1179         command line, pandoc will look for a file reference.odt in
1180         the user data directory (see --data-dir). If this is not
1181         found either, sensible defaults will be used.
1182
1183         To produce a custom reference.odt, first get a copy of
1184         the default reference.odt: pandoc
1185         -o custom-reference.odt --print-default-data-file reference.odt.
1186         Then open custom-reference.odt in LibreOffice, modify
1187         the styles as you wish, and save the file.
1188
1189     PowerPoint
1190
1191     :   Templates included with Microsoft PowerPoint 2013 (either with
1192         .pptx or .potx extension) are known to work, as are most
1193         templates derived from these.
1194
1195         The specific requirement is that the template should contain layouts
1196         with the following names (as seen within PowerPoint):
1197
1198         - Title Slide
1199         - Title and Content
1201         - Two Content
1202         - Comparison
1203         - Content with Caption
1204         - Blank
1205
1206         For each name, the first layout found with that name will be used.
1207         If no layout is found with one of the names, pandoc will output a
1208         warning and use the layout with that name from the default reference
1209         doc instead. (How these layouts are used is described in [PowerPoint
1210         layout choice](#powerpoint-layout-choice).)
1211
1213         will fit these criteria. (You can click on Layout under the
1214         Home menu to check.)
1215
1216         You can also modify the default reference.pptx: first run
1217         pandoc -o custom-reference.pptx --print-default-data-file
1218         reference.pptx, and then modify custom-reference.pptx
1219         in MS PowerPoint (pandoc will use the layouts with the names
1220         listed above).
1221
1222 --epub-cover-image=*FILE*
1223
1224 :   Use the specified image as the EPUB cover.  It is recommended
1225     that the image be less than 1000px in width and height. Note that
1226     in a Markdown source document you can also specify cover-image
1228
1229 --epub-metadata=*FILE*
1230
1231 :   Look in the specified XML file for metadata for the EPUB.
1232     The file should contain a series of [Dublin Core elements].
1233     For example:
1234
1235          <dc:rights>Creative Commons</dc:rights>
1236          <dc:language>es-AR</dc:language>
1237
1238     By default, pandoc will include the following metadata elements:
1239     <dc:title> (from the document title), <dc:creator> (from the
1240     document authors), <dc:date> (from the document date, which should
1241     be in [ISO 8601 format]), <dc:language> (from the lang
1242     variable, or, if is not set, the locale), and <dc:identifier
1243     id="BookId"> (a randomly generated UUID). Any of these may be
1244     overridden by elements in the metadata file.
1245
1246     Note: if the source document is Markdown, a YAML metadata block
1247     in the document can be used instead.  See below under
1249
1250 --epub-embed-font=*FILE*
1251
1252 :   Embed the specified font in the EPUB. This option can be repeated
1253     to embed multiple fonts.  Wildcards can also be used: for example,
1254     DejaVuSans-*.ttf.  However, if you use wildcards on the command
1255     line, be sure to escape them or put the whole filename in single quotes,
1256     to prevent them from being interpreted by the shell. To use the
1257     embedded fonts, you will need to add declarations like the following
1258     to your CSS (see --css):
1259
1260         @font-face {
1261         font-family: DejaVuSans;
1262         font-style: normal;
1263         font-weight: normal;
1264         src:url("DejaVuSans-Regular.ttf");
1265         }
1266         @font-face {
1267         font-family: DejaVuSans;
1268         font-style: normal;
1269         font-weight: bold;
1270         src:url("DejaVuSans-Bold.ttf");
1271         }
1272         @font-face {
1273         font-family: DejaVuSans;
1274         font-style: italic;
1275         font-weight: normal;
1276         src:url("DejaVuSans-Oblique.ttf");
1277         }
1278         @font-face {
1279         font-family: DejaVuSans;
1280         font-style: italic;
1281         font-weight: bold;
1282         src:url("DejaVuSans-BoldOblique.ttf");
1283         }
1284         body { font-family: "DejaVuSans"; }
1285
1286 --epub-chapter-level=*NUMBER*
1287
1288 :   Specify the heading level at which to split the EPUB into separate
1289     "chapter" files. The default is to split into chapters at level-1
1290     headings. This option only affects the internal composition of the
1291     EPUB, not the way chapters and sections are displayed to users. Some
1292     readers may be slow if the chapter files are too large, so for large
1293     documents with few level-1 headings, one might want to use a chapter
1294     level of 2 or 3.
1295
1296 --epub-subdirectory=*DIRNAME*
1297
1298 :   Specify the subdirectory in the OCF container that is to hold
1299     the EPUB-specific contents.  The default is EPUB.  To put
1300     the EPUB contents in the top level, use an empty string.
1301
1302 --ipynb-output=all|none|best
1303
1304 :   Determines how ipynb output cells are treated. all means
1305     that all of the data formats included in the original are
1306     preserved.  none means that the contents of data cells
1307     are omitted.  best causes pandoc to try to pick the
1308     richest data block in each output cell that is compatible
1309     with the output format.  The default is best.
1310
1311 --pdf-engine=*PROGRAM*
1312
1313 :   Use the specified engine when producing PDF output.
1314     Valid values are pdflatex, lualatex, xelatex, latexmk,
1315     tectonic, wkhtmltopdf, weasyprint, pagedjs-cli,
1316     prince, context, and pdfroff. If the engine is not in
1317     your PATH, the full path of the engine may be specified here.
1318     If this option is not specified, pandoc uses the following
1319     defaults depending on the output format specified using
1320     -t/--to:
1321
1322     - -t latex or none: pdflatex (other options: xelatex, lualatex,
1323         tectonic, latexmk)
1324     - -t context: context
1325     - -t html:  wkhtmltopdf (other options: prince, weasyprint,
1326         pagedjs-cli;
1327         see [print-css.rocks](https://print-css.rocks) for a good
1328         introduction to PDF generation from HTML/CSS.)
1329     - -t ms:  pdfroff
1330
1331 --pdf-engine-opt=*STRING*
1332
1333 :   Use the given string as a command-line argument to the pdf-engine.
1334     For example, to use a persistent directory foo for latexmk's
1335     auxiliary files, use --pdf-engine-opt=-outdir=foo.
1336     Note that no check for duplicate options is done.
1337
1338 [Dublin Core elements]: https://www.dublincore.org/specifications/dublin-core/dces/
1339 [ISO 8601 format]: https://www.w3.org/TR/NOTE-datetime
1340 [Encoding issue with the listings package]:
1341   https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings#Encoding_issue
1342
1343 ## Citation rendering {.options}
1344
1345 -C, --citeproc
1346
1347 :   Process the citations in the file, replacing them with
1348     rendered citations and adding a bibliography.
1349     Citation processing will not take place unless bibliographic
1350     data is supplied, either through an external file specified
1351     using the --bibliography option or the bibliography
1352     field in metadata, or via a references section in metadata
1353     containing a list of citations in CSL YAML format with
1354     Markdown formatting.  The style is controlled by a [CSL]
1355     stylesheet specified using the --csl option or the csl
1356     field in metadata. (If no stylesheet is specified,
1357     the chicago-author-date style will be used by default.)
1358     The citation processing transformation may be applied before
1359     or after filters or Lua filters (see --filter,
1360     --lua-filter): these transformations are applied in the
1361     order they appear on the command line.  For more
1362     information, see the section on [Citations].
1363
1364 --bibliography=*FILE*
1365
1366 :   Set the bibliography field in the document's metadata to *FILE*,
1367     overriding any value set in the metadata.  If you supply
1368     this argument multiple times, each *FILE* will be added to
1369     bibliography.  If *FILE* is a URL, it will be fetched
1371     working directory, it will be sought in the resource path
1372     (see --resource-path).
1373
1374 --csl=*FILE*
1375
1376 :   Set the csl field in the document's metadata to *FILE*,
1377     overriding any value set in the metadata.  (This is equivalent to
1378     --metadata csl=FILE.)  If *FILE* is a URL, it will be
1379     fetched via HTTP.  If *FILE* is not found relative to the
1380     working directory, it will be sought in the resource path
1381     (see --resource-path) and finally in the csl
1382     subdirectory of the pandoc user data directory.
1383
1384 --citation-abbreviations=*FILE*
1385
1386 :   Set the citation-abbreviations field in the document's metadata to
1387     *FILE*, overriding any value set in the metadata.  (This is equivalent to
1388     --metadata citation-abbreviations=FILE.)
1389     If *FILE* is a URL, it will be fetched via HTTP.  If *FILE* is not
1390     found relative to the working directory, it will be sought
1391     in the resource path (see --resource-path) and finally in
1392     the csl subdirectory of the pandoc user data directory.
1393
1394 --natbib
1395
1396 :   Use [natbib] for citations in LaTeX output.  This option
1397     is not for use with the --citeproc option or with PDF
1398     output.  It is intended for use in producing a LaTeX file
1399     that can be processed with [bibtex].
1400
1401 --biblatex
1402
1403 :   Use [biblatex] for citations in LaTeX output.  This option
1404     is not for use with the --citeproc option or with PDF
1405     output. It is intended for use in producing a LaTeX file
1406     that can be processed with [bibtex] or [biber].
1407
1408 ## Math rendering in HTML {.options}
1409
1410 The default is to render TeX math as far as possible using
1411 Unicode characters.  Formulas are put inside a span with
1412 class="math", so that they may be styled differently from the
1413 surrounding text if needed. However, this gives acceptable
1414 results only for basic math, usually you will want to use
1415 --mathjax or another of the following options.
1416
1417 --mathjax[=*URL*]
1418
1419 :   Use [MathJax] to display embedded TeX math in HTML output.
1420     TeX math will be put between $$...$$ (for inline math)
1421     or $...$ (for display math) and wrapped in <span> tags
1422     with class math. Then the MathJax JavaScript will render it.
1423     The *URL* should point to the MathJax.js load script.
1424     If a *URL* is not provided, a link to the Cloudflare CDN will
1425     be inserted.
1426
1427 --mathml
1428
1429 :   Convert TeX math to [MathML] (in epub3, docbook4,
1430     docbook5, jats, html4 and html5).  This is the
1431     default in odt output. Note that currently only Firefox
1432     and Safari (and select e-book readers) natively support
1433     MathML.
1434
1435 --webtex[=*URL*]
1436
1437 :   Convert TeX formulas to <img> tags that link to an external script
1438     that converts formulas to images. The formula will be URL-encoded
1439     and concatenated with the URL provided. For SVG images you can for
1440     example use --webtex https://latex.codecogs.com/svg.latex?.
1441     If no URL is specified, the CodeCogs URL generating PNGs
1442     will be used (https://latex.codecogs.com/png.latex?).
1443     Note:  the --webtex option will affect Markdown output
1444     as well as HTML, which is useful if you're targeting a
1445     version of Markdown without native math support.
1446
1447 --katex[=*URL*]
1448
1449 :   Use [KaTeX] to display embedded TeX math in HTML output.
1450     The *URL* is the base URL for the KaTeX library. That directory
1451     should contain a katex.min.js and a katex.min.css file.
1452     If a *URL* is not provided, a link to the KaTeX CDN will be inserted.
1453
1454 --gladtex
1455
1456 :   Enclose TeX math in <eq> tags in HTML output.  The resulting HTML
1457     can then be processed by [GladTeX] to produce SVG images of the typeset
1458     formulas and an HTML file with these images embedded.
1459
1460         pandoc -s --gladtex input.md -o myfile.htex
1462         # produces myfile.html and images in image_dir
1463
1464 [MathML]: https://www.w3.org/Math/
1465 [MathJax]: https://www.mathjax.org
1466 [KaTeX]: https://github.com/Khan/KaTeX
1468
1469 ## Options for wrapper scripts {.options}
1470
1471 --dump-args
1472
1473 :   Print information about command-line arguments to *stdout*, then exit.
1474     This option is intended primarily for use in wrapper scripts.
1475     The first line of output contains the name of the output file specified
1476     with the -o option, or - (for *stdout*) if no output file was
1477     specified.  The remaining lines contain the command-line arguments,
1478     one per line, in the order they appear.  These do not include regular
1479     pandoc options and their arguments, but do include any options appearing
1480     after a -- separator at the end of the line.
1481
1482 --ignore-args
1483
1484 :   Ignore command-line arguments (for use in wrapper scripts).
1485     Regular pandoc options are not ignored.  Thus, for example,
1486
1487         pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1488
1489     is equivalent to
1490
1491         pandoc -o foo.html -s
1492
1493 # Exit codes
1494
1495 If pandoc completes successfully, it will return exit code 0.
1496 Nonzero exit codes have the following meanings:
1497
1498  Code Error
1499 ----- ------------------------------------
1500     1 PandocIOError
1501     3 PandocFailOnWarningError
1502     4 PandocAppError
1503     5 PandocTemplateError
1504     6 PandocOptionError
1506    22 PandocUnknownWriterError
1507    23 PandocUnsupportedExtensionError
1508    24 PandocCiteprocError
1509    25 PandocBibliographyError
1510    31 PandocEpubSubdirectoryError
1511    43 PandocPDFError
1512    44 PandocXMLError
1513    47 PandocPDFProgramNotFoundError
1514    61 PandocHttpError
1515    62 PandocShouldNeverHappenError
1516    63 PandocSomeError
1517    64 PandocParseError
1518    65 PandocParsecError
1519    66 PandocMakePDFError
1520    67 PandocSyntaxMapError
1521    83 PandocFilterError
1522    84 PandocLuaError
1523    91 PandocMacroLoop
1524    92 PandocUTF8DecodingError
1525    93 PandocIpynbDecodingError
1526    94 PandocUnsupportedCharsetError
1527    97 PandocCouldNotFindDataFileError
1529    99 PandocResourceNotFound
1530 ----- ------------------------------------
1531
1532 # Defaults files
1533
1534 The --defaults option may be used to specify a package
1535 of options, in the form of a YAML file.
1536
1537 Fields that are omitted will just have their regular
1538 default values.  So a defaults file can be as simple as
1539 one line:
1540
1541  yaml
1542 verbosity: INFO
1543 
1544
1545 In fields that expect a file path (or list of file paths), the
1546 following syntax may be used to interpolate environment variables:
1547
1548  yaml
1549 csl:  ${HOME}/mycsldir/special.csl 1550  1551 1552 ${USERDATA} may also be used; this will always resolve to the
1553 user data directory that is current when the defaults file is
1554 parsed, regardless of the setting of the environment
1555 variable USERDATA.
1556
1557 ${.} will resolve to the directory containing the defaults 1558 file itself. This allows you to refer to resources contained 1559 in that directory: 1560 1561  yaml 1562 epub-cover-image:${.}/cover.jpg
1563 epub-metadata: ${.}/meta.xml 1564 resource-path: 1565 - . # the working directory from which pandoc is run 1566 -${.}/images   # the images subdirectory of the directory
1567                 # containing this defaults file
1568 
1569
1570 This environment variable interpolation syntax *only* works in
1571 fields that expect file paths.
1572
1573 Defaults files can be placed in the defaults subdirectory of
1574 the user data directory and used from any directory.  For
1575 example, one could create a file specifying defaults for writing
1576 letters, save it as letter.yaml in the defaults subdirectory
1577 of the user data directory, and then invoke these defaults
1578 from any directory using pandoc --defaults letter
1579 or pandoc -dletter.
1580
1581 When multiple defaults are used, their contents will be combined.
1582
1583 Note that, where command-line arguments may be repeated
1584 (--metadata-file, --css, --include-in-header,
1585 --include-before-body, --include-after-body, --variable,
1586 --metadata, --syntax-definition), the values specified on
1587 the command line will combine with values specified in the
1588 defaults file, rather than replacing them.
1589
1590 The following tables show the mapping between the command line and
1591 defaults file entries.
1592
1593 +----------------------------------+-----------------------------------+
1594 | command line                     | defaults file                     |
1595 +:=================================+:==================================+
1596 |                               |  yaml                          |
1597 | foo.md                           | input-file: foo.md                |
1598 |                               |                                |
1599 +----------------------------------+-----------------------------------+
1600 |                               |  yaml                          |
1601 | foo.md bar.md                    | input-files:                      |
1602 |                                  |   - foo.md                        |
1603 |                                  |   - bar.md                        |
1604 |                               |                                |
1605 +----------------------------------+-----------------------------------+
1606
1607 The value of input-files may be left empty to indicate input from
1608 stdin, and it can be an empty sequence [] for no input.
1609
1610 ## General options
1611
1612 +----------------------------------+-----------------------------------+
1613 | command line                     | defaults file                     |
1614 +:=================================+:==================================+
1615 |                               |  yaml                          |
1616 | --from markdown+emoji            | from: markdown+emoji              |
1617 |                               |                                |
1618 |                                  |  yaml                          |
1619 |                                  | reader: markdown+emoji            |
1620 |                                  |                                |
1621 +----------------------------------+-----------------------------------+
1622 |                               |  yaml                          |
1623 | --to markdown+hard_line_breaks   | to: markdown+hard_line_breaks     |
1624 |                               |                                |
1625 |                                  |  yaml                          |
1626 |                                  | writer: markdown+hard_line_breaks |
1627 |                                  |                                |
1628 +----------------------------------+-----------------------------------+
1629 |                               |  yaml                          |
1630 | --output foo.pdf                 | output-file: foo.pdf              |
1631 |                               |                                |
1632 +----------------------------------+-----------------------------------+
1633 |                               |  yaml                          |
1634 | --output -                       | output-file:                      |
1635 |                               |                                |
1636 +----------------------------------+-----------------------------------+
1637 |                               |  yaml                          |
1638 | --data-dir dir                   | data-dir: dir                     |
1639 |                               |                                |
1640 +----------------------------------+-----------------------------------+
1641 |                               |  yaml                          |
1642 | --defaults file                  | defaults:                         |
1643 |                               | - file                            |
1644 |                                  |                                |
1645 +----------------------------------+-----------------------------------+
1646 |                               |  yaml                          |
1647 | --verbose                        | verbosity: INFO                   |
1648 |                               |                                |
1649 +----------------------------------+-----------------------------------+
1650 |                               |  yaml                          |
1651 | --quiet                          | verbosity: ERROR                  |
1652 |                               |                                |
1653 +----------------------------------+-----------------------------------+
1654 |                               |  yaml                          |
1655 | --fail-if-warnings               | fail-if-warnings: true            |
1656 |                               |                                |
1657 +----------------------------------+-----------------------------------+
1658 |                               |  yaml                          |
1659 | --sandbox                        | sandbox: true                     |
1660 |                               |                                |
1661 +----------------------------------+-----------------------------------+
1662 |                               |  yaml                          |
1663 | --log=FILE                       | log-file: FILE                    |
1664 |                               |                                |
1665 +----------------------------------+-----------------------------------+
1666
1667 Options specified in a defaults file itself always have priority over
1668 those in another file included with a defaults: entry.
1669
1670 verbosity can have the values ERROR, WARNING, or INFO.
1671
1673
1674 +----------------------------------+-----------------------------------+
1675 | command line                     | defaults file                     |
1676 +:=================================+:==================================+
1677 |                               |  yaml                          |
1679 |                               |                                |
1680 +----------------------------------+-----------------------------------+
1681 |                               |  yaml                          |
1682 | --indented-code-classes python   | indented-code-classes:            |
1683 |                                  |   - python                        |
1684 |                               |                                |
1685 +----------------------------------+-----------------------------------+
1686 |                               |  yaml                          |
1687 | --default-image-extension ".jpg" | default-image-extension: '.jpg'   |
1688 |                               |                                |
1689 +----------------------------------+-----------------------------------+
1690 |                               |  yaml                          |
1691 | --file-scope                     | file-scope: true                  |
1692 |                               |                                |
1693 +----------------------------------+-----------------------------------+
1694 |                               |  yaml                          |
1695 | --filter pandoc-citeproc \       | filters:                          |
1696 |  --lua-filter count-words.lua \  |   - pandoc-citeproc               |
1697 |  --filter special.lua            |   - count-words.lua               |
1698 |                                  |   - type: json                    |
1699 |                                  |     path: special.lua             |
1700 |                               |                                |
1701 +----------------------------------+-----------------------------------+
1702 |                               |  yaml                          |
1704 |  --metadata key2                 |   key: value                      |
1705 |                                  |   key2: true                      |
1706 |                               |                                |
1707 +----------------------------------+-----------------------------------+
1708 |                               |  yaml                          |
1710 |                                  |   - meta.yaml                     |
1711 |                               |                                |
1712 |                                  |  yaml                          |
1713 |                                  | metadata-file: meta.yaml          |
1714 |                                  |                                |
1715 +----------------------------------+-----------------------------------+
1716 |                               |  yaml                          |
1717 | --preserve-tabs                  | preserve-tabs: true               |
1718 |                               |                                |
1719 +----------------------------------+-----------------------------------+
1720 |                               |  yaml                          |
1721 | --tab-stop 8                     | tab-stop: 8                       |
1722 |                               |                                |
1723 +----------------------------------+-----------------------------------+
1724 |                               |  yaml                          |
1725 | --track-changes accept           | track-changes: accept             |
1726 |                               |                                |
1727 +----------------------------------+-----------------------------------+
1728 |                               |  yaml                          |
1729 | --extract-media dir              | extract-media: dir                |
1730 |                               |                                |
1731 +----------------------------------+-----------------------------------+
1732 |                               |  yaml                          |
1733 | --abbreviations abbrevs.txt      | abbreviations: abbrevs.txt        |
1734 |                               |                                |
1735 +----------------------------------+-----------------------------------+
1736 |                               |  yaml                          |
1737 | --trace                          | trace: true                       |
1738 |                               |                                |
1739 +----------------------------------+-----------------------------------+
1740
1741 Metadata values specified in a defaults file are parsed as literal
1742 string text, not Markdown.
1743
1744 Filters will be assumed to be Lua filters if they have the .lua
1745 extension, and JSON filters otherwise.  But the filter type can also be
1746 specified explicitly, as shown.  Filters are run in the order specified.
1747 To include the built-in citeproc filter, use either citeproc or
1748 {type: citeproc}.
1749
1750 ## General writer options
1751
1752 +----------------------------------+-----------------------------------+
1753 | command line                     | defaults file                     |
1754 +:=================================+:==================================+
1755 |                               |  yaml                          |
1756 | --standalone                     | standalone: true                  |
1757 |                               |                                |
1758 +----------------------------------+-----------------------------------+
1759 |                               |  yaml                          |
1760 | --template letter                | template: letter                  |
1761 |                               |                                |
1762 +----------------------------------+-----------------------------------+
1763 |                               |  yaml                          |
1764 | --variable key=val \             | variables:                        |
1765 |   --variable key2                |   key: val                        |
1766 |                                  |   key2: true                      |
1767 |                               |                                |
1768 +----------------------------------+-----------------------------------+
1769 |                               |  yaml                          |
1770 | --eol nl                         | eol: nl                           |
1771 |                               |                                |
1772 +----------------------------------+-----------------------------------+
1773 |                               |  yaml                          |
1774 | --dpi 300                        | dpi: 300                          |
1775 |                               |                                |
1776 +----------------------------------+-----------------------------------+
1777 |                               |  yaml                          |
1778 | --wrap 60                        | wrap: 60                          |
1779 |                               |                                |
1780 +----------------------------------+-----------------------------------+
1781 |                               |  yaml                          |
1782 | --columns 72                     | columns: 72                       |
1783 |                               |                                |
1784 +----------------------------------+-----------------------------------+
1785 |                               |  yaml                          |
1786 | --table-of-contents              | table-of-contents: true           |
1787 |                               |                                |
1788 +----------------------------------+-----------------------------------+
1789 |                               |  yaml                          |
1790 | --toc                            | toc: true                         |
1791 |                               |                                |
1792 +----------------------------------+-----------------------------------+
1793 |                               |  yaml                          |
1794 | --toc-depth 3                    | toc-depth: 3                      |
1795 |                               |                                |
1796 +----------------------------------+-----------------------------------+
1797 |                               |  yaml                          |
1799 |                               |                                |
1800 +----------------------------------+-----------------------------------+
1801 |                               |  yaml                          |
1802 | --no-highlight                   | highlight-style: null             |
1803 |                               |                                |
1804 +----------------------------------+-----------------------------------+
1805 |                               |  yaml                          |
1806 | --highlight-style kate           | highlight-style: kate             |
1807 |                               |                                |
1808 +----------------------------------+-----------------------------------+
1809 |                               |  yaml                          |
1810 | --syntax-definition mylang.xml   | syntax-definitions:               |
1811 |                                  |   - mylang.xml                    |
1812 |                               |                                |
1813 |                                  |  yaml                          |
1814 |                                  | syntax-definition: mylang.xml     |
1815 |                                  |                                |
1816 +----------------------------------+-----------------------------------+
1817 |                               |  yaml                          |
1819 |                                  |   - inc.tex                       |
1820 |                               |                                |
1821 +----------------------------------+-----------------------------------+
1822 |                               |  yaml                          |
1823 | --include-before-body inc.tex    | include-before-body:              |
1824 |                                  |   - inc.tex                       |
1825 |                               |                                |
1826 +----------------------------------+-----------------------------------+
1827 |                               |  yaml                          |
1828 | --include-after-body inc.tex     | include-after-body:               |
1829 |                                  |   - inc.tex                       |
1830 |                               |                                |
1831 +----------------------------------+-----------------------------------+
1832 |                               |  yaml                          |
1833 | --resource-path .:foo            | resource-path: ['.','foo']        |
1834 |                               |                                |
1835 +----------------------------------+-----------------------------------+
1836 |                               |  yaml                          |
1838 |                                  |   - ["User-Agent", "Mozilla/5.0"] |
1839 |                               |                                |
1840 +----------------------------------+-----------------------------------+
1841 |                               |  yaml                          |
1842 | --no-check-certificate           | no-check-certificate: true        |
1843 |                               |                                |
1844 +----------------------------------+-----------------------------------+
1845
1846
1847 ## Options affecting specific writers
1848
1849 +----------------------------------+-----------------------------------+
1850 | command line                     | defaults file                     |
1851 +:=================================+:==================================+
1852 |                               |  yaml                          |
1853 | --self-contained                 | self-contained: true              |
1854 |                               |                                |
1855 +----------------------------------+-----------------------------------+
1856 |                               |  yaml                          |
1857 | --html-q-tags                    | html-q-tags: true                 |
1858 |                               |                                |
1859 +----------------------------------+-----------------------------------+
1860 |                               |  yaml                          |
1861 | --ascii                          | ascii: true                       |
1862 |                               |                                |
1863 +----------------------------------+-----------------------------------+
1864 |                               |  yaml                          |
1866 |                               |                                |
1867 +----------------------------------+-----------------------------------+
1868 |                               |  yaml                          |
1869 | --reference-location block       | reference-location: block         |
1870 |                               |                                |
1871 +----------------------------------+-----------------------------------+
1872 |                               |  yaml                          |
1874 |                               |                                |
1875 +----------------------------------+-----------------------------------+
1876 |                               |  yaml                          |
1877 | --top-level-division chapter     | top-level-division: chapter       |
1878 |                               |                                |
1879 +----------------------------------+-----------------------------------+
1880 |                               |  yaml                          |
1881 | --number-sections                | number-sections: true             |
1882 |                               |                                |
1883 +----------------------------------+-----------------------------------+
1884 |                               |  yaml                          |
1885 | --number-offset=1,4              | number-offset: $1,4$            |
1886 |                               |                                |
1887 +----------------------------------+-----------------------------------+
1888 |                               |  yaml                          |
1889 | --listings                       | listings: true                    |
1890 |                               |                                |
1891 +----------------------------------+-----------------------------------+
1892 |                               |  yaml                          |
1893 | --incremental                    | incremental: true                 |
1894 |                               |                                |
1895 +----------------------------------+-----------------------------------+
1896 |                               |  yaml                          |
1897 | --slide-level 2                  | slide-level: 2                    |
1898 |                               |                                |
1899 +----------------------------------+-----------------------------------+
1900 |                               |  yaml                          |
1901 | --section-divs                   | section-divs: true                |
1902 |                               |                                |
1903 +----------------------------------+-----------------------------------+
1904 |                               |  yaml                          |
1905 | --email-obfuscation references   | email-obfuscation: references     |
1906 |                               |                                |
1907 +----------------------------------+-----------------------------------+
1908 |                               |  yaml                          |
1909 | --id-prefix ch1                  | identifier-prefix: ch1            |
1910 |                               |                                |
1911 +----------------------------------+-----------------------------------+
1912 |                               |  yaml                          |
1913 | --title-prefix MySite            | title-prefix: MySite              |
1914 |                               |                                |
1915 +----------------------------------+-----------------------------------+
1916 |                               |  yaml                          |
1917 | --css styles/screen.css  \       | css:                              |
1918 |   --css styles/special.css       |   - styles/screen.css             |
1919 |                                  |   - styles/special.css            |
1920 |                               |                                |
1921 +----------------------------------+-----------------------------------+
1922 |                               |  yaml                          |
1923 | --reference-doc my.docx          | reference-doc: my.docx            |
1924 |                               |                                |
1925 +----------------------------------+-----------------------------------+
1926 |                               |  yaml                          |
1927 | --epub-cover-image cover.jpg     | epub-cover-image: cover.jpg       |
1928 |                               |                                |
1929 +----------------------------------+-----------------------------------+
1930 |                               |  yaml                          |
1932 |                               |                                |
1933 +----------------------------------+-----------------------------------+
1934 |                               |  yaml                          |
1935 | --epub-embed-font special.otf \  | epub-fonts:                       |
1936 |   --epub-embed-font headline.otf |   - special.otf                   |
1937 |                                  |   - headline.otf                  |
1938 |                               |                                |
1939 +----------------------------------+-----------------------------------+
1940 |                               |  yaml                          |
1941 | --epub-chapter-level 2           | epub-chapter-level: 2             |
1942 |                               |                                |
1943 +----------------------------------+-----------------------------------+
1944 |                               |  yaml                          |
1945 | --epub-subdirectory=""           | epub-subdirectory: ''             |
1946 |                               |                                |
1947 +----------------------------------+-----------------------------------+
1948 |                               |  yaml                          |
1949 | --ipynb-output best              | ipynb-output: best                |
1950 |                               |                                |
1951 +----------------------------------+-----------------------------------+
1952 |                               |  yaml                          |
1953 | --pdf-engine xelatex             | pdf-engine: xelatex               |
1954 |                               |                                |
1955 +----------------------------------+-----------------------------------+
1956 |                               |  yaml                          |
1957 | --pdf-engine-opt=--shell-escape  | pdf-engine-opts:                  |
1958 |                                  |   - '-shell-escape'               |
1959 |                               |                                |
1960 |                                  |  yaml                          |
1961 |                                  | pdf-engine-opt: '-shell-escape'   |
1962 |                                  |                                |
1963 +----------------------------------+-----------------------------------+
1964
1965 ## Citation rendering
1966
1967 +----------------------------------+-----------------------------------+
1968 | command line                     | defaults file                     |
1969 +:=================================+:==================================+
1970 |                               |  yaml                          |
1971 | --citeproc                       | citeproc: true                    |
1972 |                               |                                |
1973 +----------------------------------+-----------------------------------+
1974 |                               |  yaml                          |
1975 | --bibliography logic.bib         | metadata:                         |
1976 |                                  |   bibliography: logic.bib         |
1977 |                               |                                |
1978 +----------------------------------+-----------------------------------+
1979 |                               |  yaml                          |
1980 | --csl ieee.csl                   | metadata:                         |
1981 |                                  |   csl: ieee.csl                   |
1982 |                               |                                |
1983 +----------------------------------+-----------------------------------+
1984 |                               |  yaml                          |
1985 | --citation-abbreviations ab.json | metadata:                         |
1986 |                                  |   citation-abbreviations: ab.json |
1987 |                               |                                |
1988 +----------------------------------+-----------------------------------+
1989 |                               |  yaml                          |
1990 | --natbib                         | cite-method: natbib               |
1991 |                               |                                |
1992 +----------------------------------+-----------------------------------+
1993 |                               |  yaml                          |
1994 | --biblatex                       | cite-method: biblatex             |
1995 |                               |                                |
1996 +----------------------------------+-----------------------------------+
1997
1998 cite-method can be citeproc, natbib, or biblatex. This only
1999 affects LaTeX output.  If you want to use citeproc to format citations,
2000 you should also set 'citeproc: true'.
2001
2002 If you need control over when the citeproc processing is done relative
2003 to other filters, you should instead use citeproc in the list
2004 of filters (see above).
2005
2006 ## Math rendering in HTML
2007
2008 +----------------------------------+-----------------------------------+
2009 | command line                     | defaults file                     |
2010 +:=================================+:==================================+
2011 |                               |  yaml                          |
2012 | --mathjax                        | html-math-method:                 |
2013 |                                  |   method: mathjax                 |
2014 |                               |                                |
2015 +----------------------------------+-----------------------------------+
2016 |                               |  yaml                          |
2017 | --mathml                         | html-math-method:                 |
2018 |                                  |   method: mathml                  |
2019 |                               |                                |
2020 +----------------------------------+-----------------------------------+
2021 |                               |  yaml                          |
2022 | --webtex                         | html-math-method:                 |
2023 |                                  |   method: webtex                  |
2024 |                               |                                |
2025 +----------------------------------+-----------------------------------+
2026 |                               |  yaml                          |
2027 | --katex                          | html-math-method:                 |
2028 |                                  |   method: katex                   |
2029 |                               |                                |
2030 +----------------------------------+-----------------------------------+
2031 |                               |  yaml                          |
2032 | --gladtex                        | html-math-method:                 |
2033 |                                  |   method: gladtex                 |
2034 |                               |                                |
2035 +----------------------------------+-----------------------------------+
2036
2037 In addition to the values listed above, method can have the
2038 value plain.
2039
2040 If the command line option accepts a URL argument, an url: field can
2041 be added to html-math-method:.
2042
2043 ## Options for wrapper scripts
2044
2045 +----------------------------------+-----------------------------------+
2046 | command line                     | defaults file                     |
2047 +:=================================+:==================================+
2048 |                               |  yaml                          |
2049 | --dump-args                      | dump-args: true                   |
2050 |                               |                                |
2051 +----------------------------------+-----------------------------------+
2052 |                               |  yaml                          |
2053 | --ignore-args                    | ignore-args: true                 |
2054 |                               |                                |
2055 +----------------------------------+-----------------------------------+
2056
2057 # Templates
2058
2059 When the -s/--standalone option is used, pandoc uses a template to
2060 add header and footer material that is needed for a self-standing
2061 document.  To see the default template that is used, just type
2062
2063     pandoc -D *FORMAT*
2064
2065 where *FORMAT* is the name of the output format. A custom template
2066 can be specified using the --template option.  You can also override
2067 the system default templates for a given output format *FORMAT*
2068 by putting a file templates/default.*FORMAT* in the user data
2069 directory (see --data-dir, above). *Exceptions:*
2070
2071 - For odt output, customize the default.opendocument
2072   template.
2073 - For pdf output, customize the default.latex template
2074   (or the default.context template, if you use -t context,
2075   or the default.ms template, if you use -t ms, or the
2076   default.html template, if you use -t html).
2077 - docx and pptx have no template (however, you can use
2078   --reference-doc to customize the output).
2079
2080 Templates contain *variables*, which allow for the inclusion of
2081 arbitrary information at any point in the file. They may be set at the
2082 command line using the -V/--variable option. If a variable is not set,
2083 pandoc will look for the key in the document's metadata, which can be set
2084 using either [YAML metadata blocks][Extension: yaml_metadata_block]
2085 or with the -M/--metadata option.  In addition, some variables
2086 are given default values by pandoc.  See [Variables] below for
2087 a list of variables used in pandoc's default templates.
2088
2089 If you use custom templates, you may need to revise them as pandoc
2090 changes.  We recommend tracking the changes in the default templates,
2091 and modifying your custom templates accordingly. An easy way to do this
2092 is to fork the [pandoc-templates] repository and merge in
2093 changes after each pandoc release.
2094
2095   [pandoc-templates]: https://github.com/jgm/pandoc-templates
2096
2097 ## Template syntax
2098
2100
2101 Anything between the sequence $-- and the end of the 2102 line will be treated as a comment and omitted from the output. 2103 2104 ### Delimiters 2105 2106 To mark variables and control structures in the template, 2107 either $...$ or ${...} may be used as delimiters.
2108 The styles may also be mixed in the same template, but the
2109 opening and closing delimiter must match in each case.  The
2110 opening delimiter may be followed by one or more spaces
2111 or tabs, which will be ignored. The closing delimiter may
2112 be followed by one or more spaces or tabs, which will be
2113 ignored.
2114
2115 To include a literal $ in the document, use $$. 2116 2117 ### Interpolated variables 2118 2119 A slot for an interpolated variable is a variable name surrounded 2120 by matched delimiters. Variable names must begin with a letter 2121 and can contain letters, numbers, _, -, and .. The 2122 keywords it, if, else, endif, for, sep, and endfor may 2123 not be used as variable names. Examples: 2124 2125  2126 foo 2127 foo.bar.baz 2128 foo_bar.baz-bim 2129 foo 2130 {foo} 2131 {foo.bar.baz} 2132 {foo_bar.baz-bim} 2133 { foo } 2134  2135 2136 Variable names with periods are used to get at structured 2137 variable values. So, for example, employee.salary will return the 2138 value of the salary field of the object that is the value of 2139 the employee field. 2140 2141 - If the value of the variable is simple value, it will be 2142 rendered verbatim. (Note that no escaping is done; 2143 the assumption is that the calling program will escape 2144 the strings appropriately for the output format.) 2145 - If the value is a list, the values will be concatenated. 2146 - If the value is a map, the string true will be rendered. 2147 - Every other value will be rendered as the empty string. 2148 2149 ### Conditionals 2150 2151 A conditional begins with if(variable) (enclosed in 2152 matched delimiters) and ends with endif (enclosed in matched 2153 delimiters). It may optionally contain an else (enclosed in 2154 matched delimiters). The if section is used if 2155 variable has a non-empty value, otherwise the else 2156 section is used (if present). Examples: 2157 2158  2159 if(foo)barendif 2160 2161 if(foo) 2162 foo 2163 endif 2164 2165 if(foo) 2166 part one 2167 else 2168 part two 2169 endif 2170 2171 {if(foo)}bar{endif} 2172 2173 {if(foo)} 2174 {foo} 2175 {endif} 2176 2177 {if(foo)} 2178 { foo.bar } 2179 {else} 2180 no foo! 2181 {endif} 2182  2183 2184 The keyword elseif may be used to simplify complex nested 2185 conditionals: 2186 2187  2188 if(foo) 2189 XXX 2190 elseif(bar) 2191 YYY 2192 else 2193 ZZZ 2194 endif 2195  2196 2197 ### For loops 2198 2199 A for loop begins with for(variable) (enclosed in 2200 matched delimiters) and ends with endfor (enclosed in matched 2201 delimiters. 2202 2203 - If variable is an array, the material inside the loop will 2204 be evaluated repeatedly, with variable being set to each 2205 value of the array in turn, and concatenated. 2206 - If variable is a map, the material inside will be set to 2207 the map. 2208 - If the value of the associated variable is not an array or 2209 a map, a single iteration will be performed on its value. 2210 2211 Examples: 2212 2213  2214 for(foo)$$foo$$sep, endfor 2215 2216 for(foo) 2217 - foo.last, foo.first 2218 endfor 2219 2220 { for(foo.bar) } 2221 - { foo.bar.last }, { foo.bar.first } 2222 { endfor } 2223 2224 for(mymap) 2225 it.name: it.office 2226 endfor 2227  2228 2229 You may optionally specify a separator between consecutive 2230 values using sep (enclosed in matched delimiters). The 2231 material between sep and the endfor is the separator. 2232 2233  2234 { for(foo) }{ foo }{ sep }, { endfor } 2235  2236 2237 Instead of using variable inside the loop, the special 2238 anaphoric keyword it may be used. 2239 2240  2241 { for(foo.bar) } 2242 - { it.last }, { it.first } 2243 { endfor } 2244  2245 2246 ### Partials 2247 2248 Partials (subtemplates stored in different files) may be 2249 included by using the name of the partial, followed 2250 by (), for example: 2251 2252  2253 { styles() } 2254  2255 2256 Partials will be sought in the directory containing 2257 the main template. The file name will be assumed to 2258 have the same extension as the main template if it 2259 lacks an extension. When calling the partial, the 2260 full name including file extension can also be used: 2261 2262  2263 { styles.html() } 2264  2265 2266 (If a partial is not found in the directory of the 2267 template and the template path is given as a relative 2268 path, it will also be sought in the templates 2269 subdirectory of the user data directory.) 2270 2271 Partials may optionally be applied to variables using 2272 a colon: 2273 2274  2275 { date:fancy() } 2276 2277 { articles:bibentry() } 2278  2279 2280 If articles is an array, this will iterate over its 2281 values, applying the partial bibentry() to each one. So the 2282 second example above is equivalent to 2283 2284  2285 { for(articles) } 2286 { it:bibentry() } 2287 { endfor } 2288  2289 2290 Note that the anaphoric keyword it must be used when 2291 iterating over partials. In the above examples, 2292 the bibentry partial should contain it.title 2293 (and so on) instead of articles.title. 2294 2295 Final newlines are omitted from included partials. 2296 2297 Partials may include other partials. 2298 2299 A separator between values of an array may be specified 2300 in square brackets, immediately after the variable name 2301 or partial: 2302 2303  2304 {months[, ]} 2305 2306 {articles:bibentry()[; ] 2307  2308 2309 The separator in this case is literal and (unlike with sep 2310 in an explicit for loop) cannot contain interpolated 2311 variables or other template directives. 2312 2313 ### Nesting 2314 2315 To ensure that content is "nested," that is, subsequent lines 2316 indented, use the ^ directive: 2317 2318  2319 item.number ^$$item.description$ ($item.price$)
2320 
2321
2322 In this example, if item.description has multiple lines,
2323 they will all be indented to line up with the first line:
2324
2325 
2326 00123  A fine bottle of 18-year old
2327        Oban whiskey. (148) 2328  2329 2330 To nest multiple lines to the same level, align them 2331 with the ^ directive in the template. For example: 2332 2333  2334item.number^$$item.description (item.price) 2335 (Available til item.sellby.) 2336  2337 2338 will produce 2339 2340  2341 00123 A fine bottle of 18-year old 2342 Oban whiskey. (148) 2343 (Available til March 30, 2020.) 2344  2345 2346 If a variable occurs by itself on a line, preceded by whitespace 2347 and not followed by further text or directives on the same line, 2348 and the variable's value contains multiple lines, it will be 2349 nested automatically. 2350 2351 ### Breakable spaces 2352 2353 Normally, spaces in the template itself (as opposed to values of 2354 the interpolated variables) are not breakable, but they can be 2355 made breakable in part of the template by using the ~ keyword 2356 (ended with another ~). 2357 2358  2359 ~This long line may break if the document is rendered 2360 with a short line length.~ 2361  2362 2363 ### Pipes 2364 2365 A pipe transforms the value of a variable or partial. Pipes are 2366 specified using a slash (/) between the variable name (or partial) 2367 and the pipe name. Example: 2368 2369  2370 for(name) 2371 name/uppercase 2372 endfor 2373 2374 for(metadata/pairs) 2375 - it.key: it.value 2376 endfor 2377 2378 employee:name()/uppercase 2379  2380 2381 Pipes may be chained: 2382 2383  2384 for(employees/pairs) 2385 it.key/alpha/uppercase. it.name 2386 endfor 2387  2388 2389 Some pipes take parameters: 2390 2391  2392 |----------------------|------------| 2393 for(employee) 2394 it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$2395$endfor2396 |----------------------|------------| 2397  2398 2399 Currently the following pipes are predefined: 2400 2401 - pairs: Converts a map or array to an array of maps, 2402 each with key and value fields. If the original 2403 value was an array, the key will be the array index, 2404 starting with 1. 2405 2406 - uppercase: Converts text to uppercase. 2407 2408 - lowercase: Converts text to lowercase. 2409 2410 - length: Returns the length of the value: number 2411 of characters for a textual value, number of elements 2412 for a map or array. 2413 2414 - reverse: Reverses a textual value or array, 2415 and has no effect on other values. 2416 2417 - first: Returns the first value of an array, if 2418 applied to a non-empty array; otherwise returns 2419 the original value. 2420 2421 - last: Returns the last value of an array, if 2422 applied to a non-empty array; otherwise returns 2423 the original value. 2424 2425 - rest: Returns all but the first value of an array, if 2426 applied to a non-empty array; otherwise returns 2427 the original value. 2428 2429 - allbutlast: Returns all but the last value of an array, if 2430 applied to a non-empty array; otherwise returns 2431 the original value. 2432 2433 - chomp: Removes trailing newlines (and breakable space). 2434 2435 - nowrap: Disables line wrapping on breakable spaces. 2436 2437 - alpha: Converts textual values that can be 2438 read as an integer into lowercase alphabetic 2439 characters a..z (mod 26). This can be used to get lettered 2440 enumeration from array indices. To get uppercase 2441 letters, chain with uppercase. 2442 2443 - roman: Converts textual values that can be 2444 read as an integer into lowercase roman numerials. 2445 This can be used to get lettered enumeration from array indices. 2446 To get uppercase roman, chain with uppercase. 2447 2448 - left n "leftborder" "rightborder": Renders a textual value 2449 in a block of width n, aligned to the left, with an optional 2450 left and right border. Has no effect on other values. This 2451 can be used to align material in tables. Widths are positive 2452 integers indicating the number of characters. Borders 2453 are strings inside double quotes; literal " and \ characters 2454 must be backslash-escaped. 2455 2456 - right n "leftborder" "rightborder": Renders a textual value 2457 in a block of width n, aligned to the right, and has no 2458 effect on other values. 2459 2460 - center n "leftborder" "rightborder": Renders a textual 2461 value in a block of width n, aligned to the center, and has 2462 no effect on other values. 2463 2464 2465 ## Variables 2466 2467 ### Metadata variables 2468 2469 title, author, date 2470 : allow identification of basic aspects of the document. Included 2471 in PDF metadata through LaTeX and ConTeXt. These can be set 2472 through a [pandoc title block][Extension: pandoc_title_block], 2473 which allows for multiple authors, or through a 2474 [YAML metadata block][Extension: yaml_metadata_block]: 2475 2476 --- 2477 author: 2478 - Aristotle 2479 - Peter Abelard 2480 ... 2481 2482 Note that if you just want to set PDF or HTML metadata, without 2483 including a title block in the document itself, you can 2484 set the title-meta, author-meta, and date-meta 2485 variables. (By default these are set automatically, based 2486 on title, author, and date.) The page title in HTML 2487 is set by pagetitle, which is equal to title by default. 2488 2489 subtitle 2490 : document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx 2491 documents 2492 2493 abstract 2494 : document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx 2495 documents 2496 2497 abstract-title 2498 : title of abstract, currently used only in HTML and EPUB. 2499 This will be set automatically to a localized value, 2500 depending on lang, but can be manually overridden. 2501 2502 keywords 2503 : list of keywords to be included in HTML, PDF, ODT, pptx, docx 2504 and AsciiDoc metadata; repeat as for author, above 2505 2506 subject 2507 : document subject, included in ODT, PDF, docx, EPUB, and pptx metadata 2508 2509 description 2510 : document description, included in ODT, docx and pptx metadata. Some 2511 applications show this as Comments metadata. 2512 2513 category 2514 : document category, included in docx and pptx metadata 2515 2516 Additionally, 2517 any root-level string metadata, not included in ODT, docx 2518 or pptx metadata is added as a *custom property*. 2519 The following [YAML] metadata block for instance: 2520 2521 --- 2522 title: 'This is the title' 2523 subtitle: "This is the subtitle" 2524 author: 2525 - Author One 2526 - Author Two 2527 description: | 2528 This is a long 2529 description. 2530 2531 It consists of two paragraphs 2532 ... 2533 2534 will include title, author and description as standard document 2535 properties and subtitle as a custom property when converting to docx, 2536 ODT or pptx. 2537 2538 ### Language variables 2539 2540 lang 2541 : identifies the main language of the document using IETF language 2542 tags (following the [BCP 47] standard), such as en or en-GB. 2543 The [Language subtag lookup] tool can look up or verify these tags. 2544 This affects most formats, and controls hyphenation in PDF output 2545 when using LaTeX (through [babel] and [polyglossia]) or ConTeXt. 2546 2547 Use native pandoc [Divs and Spans] with the lang attribute to 2548 switch the language: 2549 2550 --- 2551 lang: en-GB 2552 ... 2553 2554 Text in the main document language (British English). 2555 2556 ::: {lang=fr-CA} 2557 > Cette citation est écrite en français canadien. 2558 ::: 2559 2560 More text in English. ['Zitat auf Deutsch.']{lang=de} 2561 2562 dir 2563 : the base script direction, either rtl (right-to-left) 2564 or ltr (left-to-right). 2565 2566 For bidirectional documents, native pandoc spans and 2567 divs with the dir attribute (value rtl or ltr) can 2568 be used to override the base direction in some output 2569 formats. This may not always be necessary if the final 2570 renderer (e.g. the browser, when generating HTML) supports 2571 the [Unicode Bidirectional Algorithm]. 2572 2573 When using LaTeX for bidirectional documents, only the 2574 xelatex engine is fully supported (use 2575 --pdf-engine=xelatex). 2576 2577 [BCP 47]: https://tools.ietf.org/html/bcp47 2578 [Unicode Bidirectional Algorithm]: https://www.w3.org/International/articles/inline-bidi-markup/uba-basics 2579 [Language subtag lookup]: https://r12a.github.io/app-subtags/ 2580 2581 ### Variables for HTML 2582 2583 document-css 2584 : Enables inclusion of most of the [CSS] in the styles.html 2585 [partial](#partials) (have a look with 2586 pandoc --print-default-data-file=templates/styles.html). 2587 Unless you use [--css](#option--css), this variable 2588 is set to true by default. You can disable it with 2589 e.g. pandoc -M document-css=false. 2590 2591 mainfont 2592 : sets the CSS font-family property on the html element. 2593 2594 fontsize 2595 : sets the base CSS font-size, which you'd usually set 2596 to e.g. 20px, but it also accepts pt 2597 (12pt = 16px in most browsers). 2598 2599 fontcolor 2600 : sets the CSS color property on the html element. 2601 2602 linkcolor 2603 : sets the CSS color property on all links. 2604 2605 monofont 2606 : sets the CSS font-family property on code elements. 2607 2608 monobackgroundcolor 2609 : sets the CSS background-color property on code elements 2610 and adds extra padding. 2611 2612 linestretch 2613 : sets the CSS line-height property on the html element, 2614 which is preferred to be unitless. 2615 2616 backgroundcolor 2617 : sets the CSS background-color property on the html element. 2618 2619 margin-left, margin-right, margin-top, margin-bottom 2620 : sets the corresponding CSS padding properties on the body element. 2621 2622 To override or extend some [CSS] for just one document, include for example: 2623 2624 --- 2625 header-includes: | 2626 <style> 2627 blockquote { 2628 font-style: italic; 2629 } 2630 tr.even { 2631 background-color: #f0f0f0; 2632 } 2633 td, th { 2634 padding: 0.5em 2em 0.5em 0.5em; 2635 } 2636 tbody { 2637 border-bottom: none; 2638 } 2639 </style> 2640 --- 2641 2642 [CSS]: https://developer.mozilla.org/en-US/docs/Learn/CSS 2643 2644 ### Variables for HTML math 2645 2646 classoption 2647 : when using [KaTeX](#option--katex), you can render display 2648 math equations flush left using [YAML metadata](#layout) or with 2649 -M classoption=fleqn. 2650 2651 ### Variables for HTML slides 2652 2653 These affect HTML output when [producing slide shows with pandoc]. 2654 2655 institute 2656 : author affiliations: can be a list when there are multiple authors 2657 2658 revealjs-url 2659 : base URL for reveal.js documents (defaults to 2660 https://unpkg.com/reveal.js@^4/) 2661 2662 s5-url 2663 : base URL for S5 documents (defaults to s5/default) 2664 2665 slidy-url 2666 : base URL for Slidy documents (defaults to 2667 https://www.w3.org/Talks/Tools/Slidy2) 2668 2669 slideous-url 2670 : base URL for Slideous documents (defaults to slideous) 2671 2672 title-slide-attributes 2673 : additional attributes for the title slide of reveal.js slide shows. 2674 See [background in reveal.js and beamer] for an example. 2675 2676 All [reveal.js configuration options] are available as variables. 2677 To turn off boolean flags that default to true in reveal.js, use 0. 2678 2679 [reveal.js configuration options]: https://revealjs.com/config/ 2680 2681 ### Variables for Beamer slides 2682 2683 These variables change the appearance of PDF slides using [beamer]. 2684 2685 aspectratio 2686 : slide aspect ratio (43 for 4:3 [default], 169 for 16:9, 2687 1610 for 16:10, 149 for 14:9, 141 for 1.41:1, 54 for 5:4, 2688 32 for 3:2) 2689 2690 beameroption 2691 : add extra beamer option with \setbeameroption{} 2692 2693 institute 2694 : author affiliations: can be a list when there are multiple authors 2695 2696 logo 2697 : logo image for slides 2698 2699 navigation 2700 : controls navigation symbols (default is empty for no navigation 2701 symbols; other valid values are frame, vertical, and horizontal) 2702 2703 section-titles 2704 : enables "title pages" for new sections (default is true) 2705 2706 theme, colortheme, fonttheme, innertheme, outertheme 2707 : beamer themes 2708 2709 themeoptions 2710 : options for LaTeX beamer themes (a list). 2711 2712 titlegraphic 2713 : image for title slide 2714 2715 ### Variables for PowerPoint 2716 2717 These variables control the visual aspects of a slide show that 2718 are not easily controlled via templates. 2719 2720 monofont 2721 : font to use for code. 2722 2723 ### Variables for LaTeX 2724 2725 Pandoc uses these variables when [creating a PDF] with a LaTeX engine. 2726 2727 #### Layout 2728 2729 block-headings 2730 : make \paragraph and \subparagraph (fourth- and 2731 fifth-level headings, or fifth- and sixth-level with book 2732 classes) free-standing rather than run-in; requires further 2733 formatting to distinguish from \subsubsection (third- or 2734 fourth-level headings). Instead of using this option, 2735 [KOMA-Script] can adjust headings more extensively: 2736 2737 --- 2738 documentclass: scrartcl 2739 header-includes: | 2740 \RedeclareSectionCommand[ 2741 beforeskip=-10pt plus -2pt minus -1pt, 2742 afterskip=1sp plus -1sp minus 1sp, 2743 font=\normalfont\itshape]{paragraph} 2744 \RedeclareSectionCommand[ 2745 beforeskip=-10pt plus -2pt minus -1pt, 2746 afterskip=1sp plus -1sp minus 1sp, 2747 font=\normalfont\scshape, 2748 indent=0pt]{subparagraph} 2749 ... 2750 2751 classoption 2752 : option for document class, e.g. oneside; repeat for multiple options: 2753 2754 --- 2755 classoption: 2756 - twocolumn 2757 - landscape 2758 ... 2759 2760 documentclass 2761 : document class: usually one of the standard classes, 2762 [article], [book], and [report]; the [KOMA-Script] 2763 equivalents, scrartcl, scrbook, and scrreprt, which 2764 default to smaller margins; or [memoir] 2765 2766 geometry 2767 : option for [geometry] package, e.g. margin=1in; 2768 repeat for multiple options: 2769 2770 --- 2771 geometry: 2772 - top=30mm 2773 - left=20mm 2774 - heightrounded 2775 ... 2776 2777 hyperrefoptions 2778 : option for [hyperref] package, e.g. linktoc=all; 2779 repeat for multiple options: 2780 2781 --- 2782 hyperrefoptions: 2783 - linktoc=all 2784 - pdfwindowui 2785 - pdfpagemode=FullScreen 2786 ... 2787 2788 indent 2789 : if true, pandoc will use document class settings for 2790 indentation (the default LaTeX template otherwise removes 2791 indentation and adds space between paragraphs) 2792 2793 linestretch 2794 : adjusts line spacing using the [setspace] 2795 package, e.g. 1.25, 1.5 2796 2797 margin-left, margin-right, margin-top, margin-bottom 2798 : sets margins if geometry is not used (otherwise geometry 2799 overrides these) 2800 2801 pagestyle 2802 : control \pagestyle{}: the default article class 2803 supports plain (default), empty (no running heads or page numbers), 2804 and headings (section titles in running heads) 2805 2806 papersize 2807 : paper size, e.g. letter, a4 2808 2809 secnumdepth 2810 : numbering depth for sections (with --number-sections option 2811 or numbersections variable) 2812 2813 beamerarticle 2814 : produce an article from Beamer slides 2815 2816 #### Fonts 2817 2818 fontenc 2819 : allows font encoding to be specified through fontenc package (with 2820 pdflatex); default is T1 (see [LaTeX font encodings guide]) 2821 2822 fontfamily 2823 : font package for use with pdflatex: 2824 [TeX Live] includes many options, documented in the [LaTeX Font Catalogue]. 2825 The default is [Latin Modern][lm]. 2826 2827 fontfamilyoptions 2828 : options for package used as fontfamily; repeat for multiple options. 2829 For example, to use the Libertine font with proportional lowercase 2830 (old-style) figures through the [libertinus] package: 2831 2832 --- 2833 fontfamily: libertinus 2834 fontfamilyoptions: 2835 - osf 2836 - p 2837 ... 2838 2839 fontsize 2840 : font size for body text. The standard classes allow 10pt, 11pt, and 2841 12pt. To use another size, set documentclass to one of 2842 the [KOMA-Script] classes, such as scrartcl or scrbook. 2843 2844 mainfont, sansfont, monofont, mathfont, CJKmainfont 2845 : font families for use with xelatex or 2846 lualatex: take the name of any system font, using the 2847 [fontspec] package. CJKmainfont uses the [xecjk] package. 2848 2849 mainfontoptions, sansfontoptions, monofontoptions, mathfontoptions, CJKoptions 2850 : options to use with mainfont, sansfont, monofont, mathfont, 2851 CJKmainfont in xelatex and lualatex. Allow for any 2852 choices available through [fontspec]; repeat for multiple 2853 options. For example, to use the [TeX Gyre] version of 2854 Palatino with lowercase figures: 2855 2856 --- 2857 mainfont: TeX Gyre Pagella 2858 mainfontoptions: 2859 - Numbers=Lowercase 2860 - Numbers=Proportional 2861 ... 2862 2863 microtypeoptions 2864 : options to pass to the microtype package 2865 2866 #### Links 2867 2868 colorlinks 2869 : add color to link text; automatically enabled if any of 2870 linkcolor, filecolor, citecolor, urlcolor, or toccolor are set 2871 2872 linkcolor, filecolor, citecolor, urlcolor, toccolor 2873 : color for internal links, external links, citation links, linked 2874 URLs, and links in table of contents, respectively: uses options 2875 allowed by [xcolor], including the dvipsnames, svgnames, and 2876 x11names lists 2877 2878 links-as-notes 2879 : causes links to be printed as footnotes 2880 2881 #### Front matter 2882 2883 lof, lot 2884 : include list of figures, list of tables 2885 2886 thanks 2887 : contents of acknowledgments footnote after document title 2888 2889 toc 2890 : include table of contents (can also be set using 2891 --toc/--table-of-contents) 2892 2893 toc-depth 2894 : level of section to include in table of contents 2895 2896 #### BibLaTeX Bibliographies 2897 2898 These variables function when using BibLaTeX for [citation rendering]. 2899 2900 biblatexoptions 2901 : list of options for biblatex 2902 2903 biblio-style 2904 : bibliography style, when used with --natbib and --biblatex. 2905 2906 biblio-title 2907 : bibliography title, when used with --natbib and --biblatex. 2908 2909 bibliography 2910 : bibliography to use for resolving references 2911 2912 natbiboptions 2913 : list of options for natbib 2914 2915 [KOMA-Script]: https://ctan.org/pkg/koma-script 2916 [LaTeX Font Catalogue]: https://tug.org/FontCatalogue/ 2917 [LaTeX font encodings guide]: https://ctan.org/pkg/encguide 2918 [TeX Gyre]: http://www.gust.org.pl/projects/e-foundry/tex-gyre 2919 [article]: https://ctan.org/pkg/article 2920 [book]: https://ctan.org/pkg/book 2921 [libertinus]: https://ctan.org/pkg/libertinus 2922 [memoir]: https://ctan.org/pkg/memoir 2923 [report]: https://ctan.org/pkg/report 2924 2925 ### Variables for ConTeXt 2926 2927 Pandoc uses these variables when [creating a PDF] with ConTeXt. 2928 2929 fontsize 2930 : font size for body text (e.g. 10pt, 12pt) 2931 2932 headertext, footertext 2933 : text to be placed in running header or footer (see [ConTeXt Headers and 2934 Footers]); repeat up to four times for different placement 2935 2936 indenting 2937 : controls indentation of paragraphs, e.g. yes,small,next (see 2938 [ConTeXt Indentation]); repeat for multiple options 2939 2940 interlinespace 2941 : adjusts line spacing, e.g. 4ex (using [setupinterlinespace]); 2942 repeat for multiple options 2943 2944 layout 2945 : options for page margins and text arrangement (see [ConTeXt Layout]); 2946 repeat for multiple options 2947 2948 linkcolor, contrastcolor 2949 : color for links outside and inside a page, e.g. red, blue (see 2950 [ConTeXt Color]) 2951 2952 linkstyle 2953 : typeface style for links, e.g. normal, bold, slanted, boldslanted, 2954 type, cap, small 2955 2956 lof, lot 2957 : include list of figures, list of tables 2958 2959 mainfont, sansfont, monofont, mathfont 2960 : font families: take the name of any system font (see 2961 [ConTeXt Font Switching]) 2962 2963 margin-left, margin-right, margin-top, margin-bottom 2964 : sets margins, if layout is not used (otherwise layout 2965 overrides these) 2966 2967 pagenumbering 2968 : page number style and location (using [setuppagenumbering]); 2969 repeat for multiple options 2970 2971 papersize 2972 : paper size, e.g. letter, A4, landscape (see [ConTeXt Paper Setup]); 2973 repeat for multiple options 2974 2975 pdfa 2976 : adds to the preamble the setup necessary to generate PDF/A 2977 of the type specified, e.g. 1a:2005, 2a. If no type is 2978 specified (i.e. the value is set to True, by e.g. 2979 --metadata=pdfa or pdfa: true in a YAML metadata block), 2980 1b:2005 will be used as default, for reasons of backwards 2981 compatibility. Using --variable=pdfa without specified value 2982 is not supported. To successfully generate PDF/A the required 2983 ICC color profiles have to be available and the content and all 2984 included files (such as images) have to be standard conforming. 2985 The ICC profiles and output intent may be specified using the 2986 variables pdfaiccprofile and pdfaintent. See also [ConTeXt 2987 PDFA] for more details. 2988 2989 pdfaiccprofile 2990 : when used in conjunction with pdfa, specifies the ICC profile to use 2991 in the PDF, e.g. default.cmyk. If left unspecified, sRGB.icc is 2992 used as default. May be repeated to include multiple profiles. Note that 2993 the profiles have to be available on the system. They can be obtained 2994 from [ConTeXt ICC Profiles]. 2995 2996 pdfaintent 2997 : when used in conjunction with pdfa, specifies the output intent for 2998 the colors, e.g. ISO coated v2 300\letterpercent\space (ECI) 2999 If left unspecified, sRGB IEC61966-2.1 is used as default. 3000 3001 toc 3002 : include table of contents (can also be set using 3003 --toc/--table-of-contents) 3004 3005 whitespace 3006 : spacing between paragraphs, e.g. none, small (using 3007 [setupwhitespace]) 3008 3009 includesource 3010 : include all source documents as file attachments in the PDF file 3011 3012 [ConTeXt Paper Setup]: https://wiki.contextgarden.net/PaperSetup 3013 [ConTeXt Layout]: https://wiki.contextgarden.net/Layout 3014 [ConTeXt Font Switching]: https://wiki.contextgarden.net/Font_Switching 3015 [ConTeXt Color]: https://wiki.contextgarden.net/Color 3016 [ConTeXt Headers and Footers]: https://wiki.contextgarden.net/Headers_and_Footers 3017 [ConTeXt Indentation]: https://wiki.contextgarden.net/Indentation 3018 [ConTeXt ICC Profiles]: https://wiki.contextgarden.net/PDFX#ICC_profiles 3019 [ConTeXt PDFA]: https://wiki.contextgarden.net/PDF/A 3020 [setupwhitespace]: https://wiki.contextgarden.net/Command/setupwhitespace 3021 [setupinterlinespace]: https://wiki.contextgarden.net/Command/setupinterlinespace 3022 [setuppagenumbering]: https://wiki.contextgarden.net/Command/setuppagenumbering 3023 3024 ### Variables for wkhtmltopdf 3025 3026 Pandoc uses these variables when [creating a PDF] with [wkhtmltopdf]. 3027 The --css option also affects the output. 3028 3029 footer-html, header-html 3030 : add information to the header and footer 3031 3032 margin-left, margin-right, margin-top, margin-bottom 3033 : set the page margins 3034 3035 papersize 3036 : sets the PDF paper size 3037 3038 ### Variables for man pages 3039 3040 adjusting 3041 : adjusts text to left (l), right (r), center (c), 3042 or both (b) margins 3043 3044 footer 3045 : footer in man pages 3046 3047 header 3048 : header in man pages 3049 3050 hyphenate 3051 : if true (the default), hyphenation will be used 3052 3053 section 3054 : section number in man pages 3055 3056 ### Variables for ms 3057 3058 fontfamily 3059 : font family (e.g. T or P) 3060 3061 indent 3062 : paragraph indent (e.g. 2m) 3063 3064 lineheight 3065 : line height (e.g. 12p) 3066 3067 pointsize 3068 : point size (e.g. 10p) 3069 3070 ### Variables set automatically 3071 3072 Pandoc sets these variables automatically in response to [options] or 3073 document contents; users can also modify them. These vary depending 3074 on the output format, and include the following: 3075 3076 body 3077 : body of document 3078 3079 date-meta 3080 : the date variable converted to ISO 8601 YYYY-MM-DD, 3081 included in all HTML based formats (dzslides, epub, 3082 html, html4, html5, revealjs, s5, slideous, slidy). 3083 The recognized formats for date are: mm/dd/yyyy, 3084 mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy 3085 (e.g. either 02 Apr 2018 or 02 April 2018), 3086 MM dd, yyyy (e.g. Apr. 02, 2018 or April 02, 2018), 3087 yyyy[mm[dd]]] (e.g. 20180402, 201804 or 2018). 3088 3089 header-includes 3090 : contents specified by -H/--include-in-header (may have multiple 3091 values) 3092 3093 include-before 3094 : contents specified by -B/--include-before-body (may have 3095 multiple values) 3096 3097 include-after 3098 : contents specified by -A/--include-after-body (may have 3099 multiple values) 3100 3101 meta-json 3102 : JSON representation of all of the document's metadata. Field 3103 values are transformed to the selected output format. 3104 3105 numbersections 3106 : non-null value if -N/--number-sections was specified 3107 3108 sourcefile, outputfile 3109 : source and destination filenames, as given on the command line. 3110 sourcefile can also be a list if input comes from multiple files, 3111 or empty if input is from stdin. You can use the following snippet in 3112 your template to distinguish them: 3113 3114if(sourcefile)$3115$for(sourcefile)$3116$sourcefile$3117$endfor$3118$else$3119 (stdin) 3120$endif$3121 3122 Similarly, outputfile can be - if output goes to the terminal. 3123 3124 If you need absolute paths, use e.g. $curdir$/$sourcefile. 3125 3126 curdir 3127 : working directory from which pandoc is run. 3128 3129 toc 3130 : non-null value if --toc/--table-of-contents was specified 3131 3132 toc-title 3133 : title of table of contents (works only with EPUB, 3134 HTML, revealjs, opendocument, odt, docx, pptx, beamer, LaTeX) 3135 3136 [pandoc-templates]: https://github.com/jgm/pandoc-templates 3137 3138 # Extensions 3139 3140 The behavior of some of the readers and writers can be adjusted by 3141 enabling or disabling various extensions. 3142 3143 An extension can be enabled by adding +EXTENSION 3144 to the format name and disabled by adding -EXTENSION. For example, 3145 --from markdown_strict+footnotes is strict Markdown with footnotes 3146 enabled, while --from markdown-footnotes-pipe_tables is pandoc's 3147 Markdown without footnotes or pipe tables. 3148 3149 The markdown reader and writer make by far the most use of extensions. 3150 Extensions only used by them are therefore covered in the 3151 section [Pandoc's Markdown] below (See [Markdown variants] for 3152 commonmark and gfm.) In the following, extensions that also work 3153 for other formats are covered. 3154 3155 Note that markdown extensions added to the ipynb format 3156 affect Markdown cells in Jupyter notebooks (as do command-line 3157 options like --atx-headers). 3158 3159 ## Typography 3160 3161 #### Extension: smart #### 3162 3163 Interpret straight quotes as curly quotes, --- as em-dashes, 3164 -- as en-dashes, and ... as ellipses. Nonbreaking spaces are 3165 inserted after certain abbreviations, such as "Mr." 3166 3167 This extension can be enabled/disabled for the following formats: 3168 3169 input formats 3170 : markdown, commonmark, latex, mediawiki, org, rst, twiki, 3171 html 3172 3173 output formats 3174 : markdown, latex, context, rst 3175 3176 enabled by default in 3177 : markdown, latex, context (both input and output) 3178 3179 Note: If you are *writing* Markdown, then the smart extension 3180 has the reverse effect: what would have been curly quotes comes 3181 out straight. 3182 3183 In LaTeX, smart means to use the standard TeX ligatures 3184 for quotation marks (   and  ''  for double quotes, 3185    and  '  for single quotes) and dashes (-- for 3186 en-dash and --- for em-dash). If smart is disabled, 3187 then in reading LaTeX pandoc will parse these characters 3188 literally. In writing LaTeX, enabling smart tells pandoc 3189 to use the ligatures when possible; if smart is disabled 3190 pandoc will use unicode quotation mark and dash characters. 3191 3192 ## Headings and sections 3193 3194 #### Extension: auto_identifiers #### 3195 3196 A heading without an explicitly specified identifier will be 3197 automatically assigned a unique identifier based on the heading text. 3198 3199 This extension can be enabled/disabled for the following formats: 3200 3201 input formats 3202 : markdown, latex, rst, mediawiki, textile 3203 3204 output formats 3205 : markdown, muse 3206 3207 enabled by default in 3208 : markdown, muse 3209 3210 The default algorithm used to derive the identifier from the 3211 heading text is: 3212 3213 - Remove all formatting, links, etc. 3214 - Remove all footnotes. 3215 - Remove all non-alphanumeric characters, 3216 except underscores, hyphens, and periods. 3217 - Replace all spaces and newlines with hyphens. 3218 - Convert all alphabetic characters to lowercase. 3219 - Remove everything up to the first letter (identifiers may 3220 not begin with a number or punctuation mark). 3221 - If nothing is left after this, use the identifier section. 3222 3223 Thus, for example, 3224 3225 Heading Identifier 3226 ------------------------------- ---------------------------- 3227 Heading identifiers in HTML heading-identifiers-in-html 3228 Maître d'hôtel maître-dhôtel 3229 *Dogs*?--in *my* house? dogs--in-my-house 3230 [HTML], [S5], or [RTF]? html-s5-or-rtf 3231 3. Applications applications 3232 33 section 3233 3234 These rules should, in most cases, allow one to determine the identifier 3235 from the heading text. The exception is when several headings have the 3236 same text; in this case, the first will get an identifier as described 3237 above; the second will get the same identifier with -1 appended; the 3238 third with -2; and so on. 3239 3240 (However, a different algorithm is used if 3241 gfm_auto_identifiers is enabled; see below.) 3242 3243 These identifiers are used to provide link targets in the table of 3244 contents generated by the --toc|--table-of-contents option. They 3245 also make it easy to provide links from one section of a document to 3246 another. A link to this section, for example, might look like this: 3247 3248 See the section on 3249 [heading identifiers](#heading-identifiers-in-html-latex-and-context). 3250 3251 Note, however, that this method of providing links to sections works 3252 only in HTML, LaTeX, and ConTeXt formats. 3253 3254 If the --section-divs option is specified, then each section will 3255 be wrapped in a section (or a div, if html4 was specified), 3256 and the identifier will be attached to the enclosing <section> 3257 (or <div>) tag rather than the heading itself. This allows entire 3258 sections to be manipulated using JavaScript or treated differently in 3259 CSS. 3260 3261 #### Extension: ascii_identifiers #### 3262 3263 Causes the identifiers produced by auto_identifiers to be pure ASCII. 3264 Accents are stripped off of accented Latin letters, and non-Latin 3265 letters are omitted. 3266 3267 #### Extension: gfm_auto_identifiers #### 3268 3269 Changes the algorithm used by auto_identifiers to conform to 3270 GitHub's method. Spaces are converted to dashes (-), 3271 uppercase characters to lowercase characters, and punctuation 3272 characters other than - and _ are removed. 3273 Emojis are replaced by their names. 3274 3275 ## Math Input 3276 3277 The extensions [tex_math_dollars](#extension-tex_math_dollars), 3278 [tex_math_single_backslash](#extension-tex_math_single_backslash), and 3279 [tex_math_double_backslash](#extension-tex_math_double_backslash) 3280 are described in the section about Pandoc's Markdown. 3281 3282 However, they can also be used with HTML input. This is handy for 3283 reading web pages formatted using MathJax, for example. 3284 3285 ## Raw HTML/TeX 3286 3287 The following extensions are described in more detail in 3288 their respective sections of [Pandoc's Markdown]: 3289 3290 - [raw_html](#extension-raw_html) allows HTML elements which 3291 are not representable in pandoc's AST to be parsed as raw HTML. 3292 By default, this is disabled for HTML input. 3293 3294 - [raw_tex](#extension-raw_tex) allows raw LaTeX, TeX, and ConTeXt 3295 to be included in a document. This extension can be enabled/disabled 3296 for the following formats (in addition to markdown): 3297 3298 input formats 3299 : latex, textile, html (environments, \ref, and 3300 \eqref only), ipynb 3301 3302 output formats 3303 : textile, commonmark 3304 3305 Note: as applied to ipynb, raw_html and raw_tex affect not 3306 only raw TeX in markdown cells, but data with mime type 3307 text/html in output cells. Since the ipynb reader attempts 3308 to preserve the richest possible outputs when several options 3309 are given, you will get best results if you disable raw_html 3310 and raw_tex when converting to formats like docx which don't 3311 allow raw html or tex. 3312 3313 - [native_divs](#extension-native_divs) causes HTML div 3314 elements to be parsed as native pandoc Div blocks. 3315 If you want them to be parsed as raw HTML, use 3316 -f html-native_divs+raw_html. 3317 3318 - [native_spans](#extension-native_spans) causes HTML span 3319 elements to be parsed as native pandoc Span inlines. 3320 If you want them to be parsed as raw HTML, use 3321 -f html-native_spans+raw_html. If you want to drop all 3322 divs and spans when converting HTML to Markdown, you 3323 can use pandoc -f html-native_divs-native_spans -t markdown. 3324 3325 ## Literate Haskell support 3326 3327 #### Extension: literate_haskell #### 3328 3329 Treat the document as literate Haskell source. 3330 3331 This extension can be enabled/disabled for the following formats: 3332 3333 input formats 3334 : markdown, rst, latex 3335 3336 output formats 3337 : markdown, rst, latex, html 3338 3339 If you append +lhs (or +literate_haskell) to one of the formats 3340 above, pandoc will treat the document as literate Haskell source. 3341 This means that 3342 3343 - In Markdown input, "bird track" sections will be parsed as Haskell 3344 code rather than block quotations. Text between \begin{code} 3345 and \end{code} will also be treated as Haskell code. For 3346 ATX-style headings the character '=' will be used instead of '#'. 3347 3348 - In Markdown output, code blocks with classes haskell and literate 3349 will be rendered using bird tracks, and block quotations will be 3350 indented one space, so they will not be treated as Haskell code. 3351 In addition, headings will be rendered setext-style (with underlines) 3352 rather than ATX-style (with '#' characters). (This is because ghc 3353 treats '#' characters in column 1 as introducing line numbers.) 3354 3355 - In restructured text input, "bird track" sections will be parsed 3356 as Haskell code. 3357 3358 - In restructured text output, code blocks with class haskell will 3359 be rendered using bird tracks. 3360 3361 - In LaTeX input, text in code environments will be parsed as 3362 Haskell code. 3363 3364 - In LaTeX output, code blocks with class haskell will be rendered 3365 inside code environments. 3366 3367 - In HTML output, code blocks with class haskell will be rendered 3368 with class literatehaskell and bird tracks. 3369 3370 Examples: 3371 3372 pandoc -f markdown+lhs -t html 3373 3374 reads literate Haskell source formatted with Markdown conventions and writes 3375 ordinary HTML (without bird tracks). 3376 3377 pandoc -f markdown+lhs -t html+lhs 3378 3379 writes HTML with the Haskell code in bird tracks, so it can be copied 3380 and pasted as literate Haskell source. 3381 3382 Note that GHC expects the bird tracks in the first column, so indented 3383 literate code blocks (e.g. inside an itemized environment) will not be 3384 picked up by the Haskell compiler. 3385 3386 ## Other extensions 3387 3388 #### Extension: empty_paragraphs #### 3389 3390 Allows empty paragraphs. By default empty paragraphs are 3391 omitted. 3392 3393 This extension can be enabled/disabled for the following formats: 3394 3395 input formats 3396 : docx, html 3397 3398 output formats 3399 : docx, odt, opendocument, html 3400 3401 #### Extension: native_numbering #### 3402 3403 Enables native numbering of figures and tables. Enumeration 3404 starts at 1. 3405 3406 This extension can be enabled/disabled for the following formats: 3407 3408 output formats 3409 : odt, opendocument, docx 3410 3411 #### Extension: xrefs_name #### 3412 3413 Links to headings, figures and tables inside the document are 3414 substituted with cross-references that will use the name or caption 3415 of the referenced item. The original link text is replaced once 3416 the generated document is refreshed. This extension can be combined 3417 with xrefs_number in which case numbers will appear before the 3418 name. 3419 3420 Text in cross-references is only made consistent with the referenced 3421 item once the document has been refreshed. 3422 3423 This extension can be enabled/disabled for the following formats: 3424 3425 output formats 3426 : odt, opendocument 3427 3428 #### Extension: xrefs_number #### 3429 3430 Links to headings, figures and tables inside the document are 3431 substituted with cross-references that will use the number 3432 of the referenced item. The original link text is discarded. 3433 This extension can be combined with xrefs_name in which case 3434 the name or caption numbers will appear after the number. 3435 3436 For the xrefs_number to be useful heading numbers must be enabled 3437 in the generated document, also table and figure captions must be enabled 3438 using for example the native_numbering extension. 3439 3440 Numbers in cross-references are only visible in the final document once 3441 it has been refreshed. 3442 3443 This extension can be enabled/disabled for the following formats: 3444 3445 output formats 3446 : odt, opendocument 3447 3448 #### Extension: styles #### {#ext-styles} 3449 3450 When converting from docx, read all docx styles as divs (for 3451 paragraph styles) and spans (for character styles) regardless 3452 of whether pandoc understands the meaning of these styles. 3453 This can be used with [docx custom styles](#custom-styles). 3454 Disabled by default. 3455 3456 input formats 3457 : docx 3458 3459 #### Extension: amuse #### 3460 3461 In the muse input format, this enables Text::Amuse 3462 extensions to Emacs Muse markup. 3463 3464 #### Extension: raw_markdown #### 3465 3466 In the ipynb input format, this causes Markdown cells 3467 to be included as raw Markdown blocks (allowing lossless 3468 round-tripping) rather than being parsed. Use this only 3469 when you are targeting ipynb or a markdown-based 3470 output format. 3471 3472 #### Extension: citations {#org-citations} 3473 3474 When the citations extension is enabled in org, 3475 org-cite and org-ref style citations will be parsed as 3476 native pandoc citations. 3477 3478 [org-cite]: https://orgmode.org/manual/Citations.html 3479 [org-ref]: https://github.com/jkitchin/org-ref 3480 3481 When citations is enabled in docx, citations inserted 3482 by Zotero or Mendeley or EndNote plugins will be parsed as native 3483 pandoc citations. (Otherwise, the formatted citations generated 3484 by the bibliographic software will be parsed as regular text.) 3485 3486 #### Extension: fancy_lists {#org-fancy-lists} 3487 3488 Some aspects of [Pandoc's Markdown fancy lists](#extension-fancy_lists) are also 3489 accepted in org input, mimicking the option org-list-allow-alphabetical in 3490 Emacs. As in Org Mode, enabling this extension allows lowercase and uppercase 3491 alphabetical markers for ordered lists to be parsed in addition to arabic ones. 3492 Note that for Org, this does not include roman numerals or the # placeholder 3493 that are enabled by the extension in Pandoc's Markdown. 3494 3495 #### Extension: element_citations #### 3496 3497 In the jats output formats, this causes reference items to 3498 be replaced with <element-citation> elements. These 3499 elements are not influenced by CSL styles, but all information 3500 on the item is included in tags. 3501 3502 #### Extension: ntb #### 3503 3504 In the context output format this enables the use of [Natural Tables 3505 (TABLE)](https://wiki.contextgarden.net/TABLE) instead of the default 3506 [Extreme Tables (xtables)](https://wiki.contextgarden.net/xtables). 3507 Natural tables allow more fine-grained global customization but come 3508 at a performance penalty compared to extreme tables. 3509 3510 3511 # Pandoc's Markdown 3512 3513 Pandoc understands an extended and slightly revised version of 3514 John Gruber's [Markdown] syntax. This document explains the syntax, 3515 noting differences from original Markdown. Except where noted, these 3516 differences can be suppressed by using the markdown_strict format instead 3517 of markdown. Extensions can be enabled or disabled to specify the 3518 behavior more granularly. They are described in the following. See also 3519 [Extensions] above, for extensions that work also on other formats. 3520 3521 ## Philosophy 3522 3523 Markdown is designed to be easy to write, and, even more importantly, 3524 easy to read: 3525 3526 > A Markdown-formatted document should be publishable as-is, as plain 3527 > text, without looking like it's been marked up with tags or formatting 3528 > instructions. 3529 > -- [John Gruber](https://daringfireball.net/projects/markdown/syntax#philosophy) 3530 3531 This principle has guided pandoc's decisions in finding syntax for 3532 tables, footnotes, and other extensions. 3533 3534 There is, however, one respect in which pandoc's aims are different 3535 from the original aims of Markdown. Whereas Markdown was originally 3536 designed with HTML generation in mind, pandoc is designed for multiple 3537 output formats. Thus, while pandoc allows the embedding of raw HTML, 3538 it discourages it, and provides other, non-HTMLish ways of representing 3539 important document elements like definition lists, tables, mathematics, and 3540 footnotes. 3541 3542 ## Paragraphs 3543 3544 A paragraph is one or more lines of text followed by one or more blank lines. 3545 Newlines are treated as spaces, so you can reflow your paragraphs as you like. 3546 If you need a hard line break, put two or more spaces at the end of a line. 3547 3548 #### Extension: escaped_line_breaks #### 3549 3550 A backslash followed by a newline is also a hard line break. 3551 Note: in multiline and grid table cells, this is the only way 3552 to create a hard line break, since trailing spaces in the cells 3553 are ignored. 3554 3555 ## Headings 3556 3557 There are two kinds of headings: Setext and ATX. 3558 3559 ### Setext-style headings ### 3560 3561 A setext-style heading is a line of text "underlined" with a row of = signs 3562 (for a level-one heading) or - signs (for a level-two heading): 3563 3564 A level-one heading 3565 =================== 3566 3567 A level-two heading 3568 ------------------- 3569 3570 The heading text can contain inline formatting, such as emphasis (see 3571 [Inline formatting], below). 3572 3573 3574 ### ATX-style headings ### 3575 3576 An ATX-style heading consists of one to six # signs and a line of 3577 text, optionally followed by any number of # signs. The number of 3578 # signs at the beginning of the line is the heading level: 3579 3580 ## A level-two heading 3581 3582 ### A level-three heading ### 3583 3584 As with setext-style headings, the heading text can contain formatting: 3585 3586 # A level-one heading with a [link](/url) and *emphasis* 3587 3588 #### Extension: blank_before_header #### 3589 3590 Original Markdown syntax does not require a blank line before a heading. 3591 Pandoc does require this (except, of course, at the beginning of the 3592 document). The reason for the requirement is that it is all too easy for a 3593 # to end up at the beginning of a line by accident (perhaps through line 3594 wrapping). Consider, for example: 3595 3596 I like several of their flavors of ice cream: 3597 #22, for example, and #5. 3598 3599 #### Extension: space_in_atx_header #### 3600 3601 Many Markdown implementations do not require a space between the 3602 opening #s of an ATX heading and the heading text, so that 3603 #5 bolt and #hashtag count as headings. With this extension, 3604 pandoc does require the space. 3605 3606 ### Heading identifiers ### 3607 3608 See also the [auto_identifiers 3609 extension](#extension-auto_identifiers) above. 3610 3611 #### Extension: header_attributes #### 3612 3613 Headings can be assigned attributes using this syntax at the end 3614 of the line containing the heading text: 3615 3616 {#identifier .class .class key=value key=value} 3617 3618 Thus, for example, the following headings will all be assigned the identifier 3619 foo: 3620 3621 # My heading {#foo} 3622 3623 ## My heading ## {#foo} 3624 3625 My other heading {#foo} 3626 --------------- 3627 3628 (This syntax is compatible with [PHP Markdown Extra].) 3629 3630 Note that although this syntax allows assignment of classes and key/value 3631 attributes, writers generally don't use all of this information. Identifiers, 3632 classes, and key/value attributes are used in HTML and HTML-based formats such 3633 as EPUB and slidy. Identifiers are used for labels and link anchors in the 3634 LaTeX, ConTeXt, Textile, Jira markup, and AsciiDoc writers. 3635 3636 Headings with the class unnumbered will not be numbered, even if 3637 --number-sections is specified. A single hyphen (-) in an attribute 3638 context is equivalent to .unnumbered, and preferable in non-English 3639 documents. So, 3640 3641 # My heading {-} 3642 3643 is just the same as 3644 3645 # My heading {.unnumbered} 3646 3647 If the unlisted class is present in addition to unnumbered, 3648 the heading will not be included in a table of contents. 3649 (Currently this feature is only implemented for certain 3650 formats: those based on LaTeX and HTML, PowerPoint, and RTF.) 3651 3652 #### Extension: implicit_header_references #### 3653 3654 Pandoc behaves as if reference links have been defined for each heading. 3655 So, to link to a heading 3656 3657 # Heading identifiers in HTML 3658 3659 you can simply write 3660 3661 [Heading identifiers in HTML] 3662 3663 or 3664 3665 [Heading identifiers in HTML][] 3666 3667 or 3668 3669 [the section on heading identifiers][heading identifiers in 3670 HTML] 3671 3672 instead of giving the identifier explicitly: 3673 3674 [Heading identifiers in HTML](#heading-identifiers-in-html) 3675 3676 If there are multiple headings with identical text, the corresponding 3677 reference will link to the first one only, and you will need to use explicit 3678 links to link to the others, as described above. 3679 3680 Like regular reference links, these references are case-insensitive. 3681 3682 Explicit link reference definitions always take priority over 3683 implicit heading references. So, in the following example, the 3684 link will point to bar, not to #foo: 3685 3686 # Foo 3687 3688 [foo]: bar 3689 3690 See [foo] 3691 3692 ## Block quotations 3693 3694 Markdown uses email conventions for quoting blocks of text. 3695 A block quotation is one or more paragraphs or other block elements 3696 (such as lists or headings), with each line preceded by a > character 3697 and an optional space. (The > need not start at the left margin, but 3698 it should not be indented more than three spaces.) 3699 3700 > This is a block quote. This 3701 > paragraph has two lines. 3702 > 3703 > 1. This is a list inside a block quote. 3704 > 2. Second item. 3705 3706 A "lazy" form, which requires the > character only on the first 3707 line of each block, is also allowed: 3708 3709 > This is a block quote. This 3710 paragraph has two lines. 3711 3712 > 1. This is a list inside a block quote. 3713 2. Second item. 3714 3715 Among the block elements that can be contained in a block quote are 3716 other block quotes. That is, block quotes can be nested: 3717 3718 > This is a block quote. 3719 > 3720 > > A block quote within a block quote. 3721 3722 If the > character is followed by an optional space, that space 3723 will be considered part of the block quote marker and not part of 3724 the indentation of the contents. Thus, to put an indented code 3725 block in a block quote, you need five spaces after the >: 3726 3727 > code 3728 3729 #### Extension: blank_before_blockquote #### 3730 3731 Original Markdown syntax does not require a blank line before a 3732 block quote. Pandoc does require this (except, of course, at 3733 the beginning of the document). The reason for the requirement 3734 is that it is all too easy for a > to end up at the beginning 3735 of a line by accident (perhaps through line wrapping). So, 3736 unless the markdown_strict format is used, the following does 3737 not produce a nested block quote in pandoc: 3738 3739 > This is a block quote. 3740 >> Nested. 3741 3742 3743 ## Verbatim (code) blocks 3744 3745 ### Indented code blocks ### 3746 3747 A block of text indented four spaces (or one tab) is treated as verbatim 3748 text: that is, special characters do not trigger special formatting, 3749 and all spaces and line breaks are preserved. For example, 3750 3751 if (a > 3) { 3752 moveShip(5 * gravity, DOWN); 3753 } 3754 3755 The initial (four space or one tab) indentation is not considered part 3756 of the verbatim text, and is removed in the output. 3757 3758 Note: blank lines in the verbatim text need not begin with four spaces. 3759 3760 3761 ### Fenced code blocks ### 3762 3763 #### Extension: fenced_code_blocks #### 3764 3765 In addition to standard indented code blocks, pandoc supports 3766 *fenced* code blocks. These begin with a row of three or more 3767 tildes (~) and end with a row of tildes that must be at least as long as 3768 the starting row. Everything between these lines is treated as code. No 3769 indentation is necessary: 3770 3771 ~~~~~~~ 3772 if (a > 3) { 3773 moveShip(5 * gravity, DOWN); 3774 } 3775 ~~~~~~~ 3776 3777 Like regular code blocks, fenced code blocks must be separated 3778 from surrounding text by blank lines. 3779 3780 If the code itself contains a row of tildes or backticks, just use a longer 3781 row of tildes or backticks at the start and end: 3782 3783 ~~~~~~~~~~~~~~~~ 3784 ~~~~~~~~~~ 3785 code including tildes 3786 ~~~~~~~~~~ 3787 ~~~~~~~~~~~~~~~~ 3788 3789 #### Extension: backtick_code_blocks #### 3790 3791 Same as fenced_code_blocks, but uses backticks (  ) instead of tildes 3792 (~). 3793 3794 #### Extension: fenced_code_attributes #### 3795 3796 Optionally, you may attach attributes to fenced or backtick code block using 3797 this syntax: 3798 3799 ~~~~ {#mycode .haskell .numberLines startFrom="100"} 3800 qsort [] = [] 3801 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ 3802 qsort (filter (>= x) xs) 3803 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3804 3805 Here mycode is an identifier, haskell and numberLines are 3806 classes, and startFrom is an attribute with value 100. Some 3807 output formats can use this information to do syntax 3808 highlighting. Currently, the only output formats that uses this 3809 information are HTML, LaTeX, Docx, Ms, and PowerPoint. If 3810 highlighting is supported for your output format and language, 3811 then the code block above will appear highlighted, with numbered 3812 lines. (To see which languages are supported, type pandoc 3813 --list-highlight-languages.) Otherwise, the code block above 3814 will appear as follows: 3815 3816 <pre id="mycode" class="haskell numberLines" startFrom="100"> 3817 <code> 3818 ... 3819 </code> 3820 </pre> 3821 3822 The numberLines (or number-lines) class will cause the lines 3823 of the code block to be numbered, starting with 1 or the value 3824 of the startFrom attribute. The lineAnchors (or 3825 line-anchors) class will cause the lines to be clickable 3826 anchors in HTML output. 3827 3828 A shortcut form can also be used for specifying the language of 3829 the code block: 3830 3831 haskell 3832 qsort [] = [] 3833  3834 3835 This is equivalent to: 3836 3837  {.haskell} 3838 qsort [] = [] 3839  3840 3841 If the fenced_code_attributes extension is disabled, but 3842 input contains class attribute(s) for the code block, the first 3843 class attribute will be printed after the opening fence as a bare 3844 word. 3845 3846 To prevent all highlighting, use the --no-highlight flag. 3847 To set the highlighting style, use --highlight-style. 3848 For more information on highlighting, see [Syntax highlighting], 3849 below. 3850 3851 ## Line blocks 3852 3853 #### Extension: line_blocks #### 3854 3855 A line block is a sequence of lines beginning with a vertical bar (|) 3856 followed by a space. The division into lines will be preserved in 3857 the output, as will any leading spaces; otherwise, the lines will 3858 be formatted as Markdown. This is useful for verse and addresses: 3859 3860 | The limerick packs laughs anatomical 3861 | In space that is quite economical. 3862 | But the good ones I've seen 3863 | So seldom are clean 3864 | And the clean ones so seldom are comical 3865 3866 | 200 Main St. 3867 | Berkeley, CA 94718 3868 3869 The lines can be hard-wrapped if needed, but the continuation 3870 line must begin with a space. 3871 3872 | The Right Honorable Most Venerable and Righteous Samuel L. 3873 Constable, Jr. 3874 | 200 Main St. 3875 | Berkeley, CA 94718 3876 3877 Inline formatting (such as emphasis) is allowed in the content, 3878 but not block-level formatting (such as block quotes or lists). 3879 3880 This syntax is borrowed from [reStructuredText]. 3881 3882 ## Lists 3883 3884 ### Bullet lists ### 3885 3886 A bullet list is a list of bulleted list items. A bulleted list 3887 item begins with a bullet (*, +, or -). Here is a simple 3888 example: 3889 3890 * one 3891 * two 3892 * three 3893 3894 This will produce a "compact" list. If you want a "loose" list, in which 3895 each item is formatted as a paragraph, put spaces between the items: 3896 3897 * one 3898 3899 * two 3900 3901 * three 3902 3903 The bullets need not be flush with the left margin; they may be 3904 indented one, two, or three spaces. The bullet must be followed 3905 by whitespace. 3906 3907 List items look best if subsequent lines are flush with the first 3908 line (after the bullet): 3909 3910 * here is my first 3911 list item. 3912 * and my second. 3913 3914 But Markdown also allows a "lazy" format: 3915 3916 * here is my first 3917 list item. 3918 * and my second. 3919 3920 ### Block content in list items ### 3921 3922 A list item may contain multiple paragraphs and other block-level 3923 content. However, subsequent paragraphs must be preceded by a blank line 3924 and indented to line up with the first non-space content after 3925 the list marker. 3926 3927 * First paragraph. 3928 3929 Continued. 3930 3931 * Second paragraph. With a code block, which must be indented 3932 eight spaces: 3933 3934 { code } 3935 3936 Exception: if the list marker is followed by an indented code 3937 block, which must begin 5 spaces after the list marker, then 3938 subsequent paragraphs must begin two columns after the last 3939 character of the list marker: 3940 3941 * code 3942 3943 continuation paragraph 3944 3945 List items may include other lists. In this case the preceding blank 3946 line is optional. The nested list must be indented to line up with 3947 the first non-space character after the list marker of the 3948 containing list item. 3949 3950 * fruits 3951 + apples 3952 - macintosh 3953 - red delicious 3954 + pears 3955 + peaches 3956 * vegetables 3957 + broccoli 3958 + chard 3959 3960 As noted above, Markdown allows you to write list items "lazily," instead of 3961 indenting continuation lines. However, if there are multiple paragraphs or 3962 other blocks in a list item, the first line of each must be indented. 3963 3964 + A lazy, lazy, list 3965 item. 3966 3967 + Another one; this looks 3968 bad but is legal. 3969 3970 Second paragraph of second 3971 list item. 3972 3973 ### Ordered lists ### 3974 3975 Ordered lists work just like bulleted lists, except that the items 3976 begin with enumerators rather than bullets. 3977 3978 In original Markdown, enumerators are decimal numbers followed 3979 by a period and a space. The numbers themselves are ignored, so 3980 there is no difference between this list: 3981 3982 1. one 3983 2. two 3984 3. three 3985 3986 and this one: 3987 3988 5. one 3989 7. two 3990 1. three 3991 3992 #### Extension: fancy_lists #### 3993 3994 Unlike original Markdown, pandoc allows ordered list items to be marked 3995 with uppercase and lowercase letters and roman numerals, in addition to 3996 Arabic numerals. List markers may be enclosed in parentheses or followed by a 3997 single right-parentheses or period. They must be separated from the 3998 text that follows by at least one space, and, if the list marker is a 3999 capital letter with a period, by at least two spaces.[^2] 4000 4001 [^2]: The point of this rule is to ensure that normal paragraphs 4002 starting with people's initials, like 4003 4004 B. Russell was an English philosopher. 4005 4006 do not get treated as list items. 4007 4008 This rule will not prevent 4009 4010 (C) 2007 Joe Smith 4011 4012 from being interpreted as a list item. In this case, a backslash 4013 escape can be used: 4014 4015 (C\) 2007 Joe Smith 4016 4017 The fancy_lists extension also allows '#' to be used as an 4018 ordered list marker in place of a numeral: 4019 4020 #. one 4021 #. two 4022 4023 #### Extension: startnum #### 4024 4025 Pandoc also pays attention to the type of list marker used, and to the 4026 starting number, and both of these are preserved where possible in the 4027 output format. Thus, the following yields a list with numbers followed 4028 by a single parenthesis, starting with 9, and a sublist with lowercase 4029 roman numerals: 4030 4031 9) Ninth 4032 10) Tenth 4033 11) Eleventh 4034 i. subone 4035 ii. subtwo 4036 iii. subthree 4037 4038 Pandoc will start a new list each time a different type of list 4039 marker is used. So, the following will create three lists: 4040 4041 (2) Two 4042 (5) Three 4043 1. Four 4044 * Five 4045 4046 If default list markers are desired, use #.: 4047 4048 #. one 4049 #. two 4050 #. three 4051 4052 #### Extension: task_lists #### 4053 4054 Pandoc supports task lists, using the syntax of GitHub-Flavored Markdown. 4055 4056 - [ ] an unchecked task list item 4057 - [x] checked item 4058 4059 ### Definition lists ### 4060 4061 #### Extension: definition_lists #### 4062 4063 Pandoc supports definition lists, using the syntax of 4064 [PHP Markdown Extra] with some extensions.[^3] 4065 4066 Term 1 4067 4068 : Definition 1 4069 4070 Term 2 with *inline markup* 4071 4072 : Definition 2 4073 4074 { some code, part of Definition 2 } 4075 4076 Third paragraph of definition 2. 4077 4078 Each term must fit on one line, which may optionally be followed by 4079 a blank line, and must be followed by one or more definitions. 4080 A definition begins with a colon or tilde, which may be indented one 4081 or two spaces. 4082 4083 A term may have multiple definitions, and each definition may 4084 consist of one or more block elements (paragraph, code block, 4085 list, etc.), each indented four spaces or one tab stop. The 4086 body of the definition (not including the first line) 4087 should be indented four spaces. However, as with 4088 other Markdown lists, you can "lazily" omit indentation except 4089 at the beginning of a paragraph or other block element: 4090 4091 Term 1 4092 4093 : Definition 4094 with lazy continuation. 4095 4096 Second paragraph of the definition. 4097 4098 If you leave space before the definition (as in the example above), 4099 the text of the definition will be treated as a paragraph. In some 4100 output formats, this will mean greater spacing between term/definition 4101 pairs. For a more compact definition list, omit the space before the 4102 definition: 4103 4104 Term 1 4105 ~ Definition 1 4106 4107 Term 2 4108 ~ Definition 2a 4109 ~ Definition 2b 4110 4111 Note that space between items in a definition list is required. 4112 (A variant that loosens this requirement, but disallows "lazy" 4113 hard wrapping, can be activated with compact_definition_lists: see 4114 [Non-default extensions], below.) 4115 4116 [^3]: I have been influenced by the suggestions of [David 4117 Wheeler](https://justatheory.com/2009/02/modest-markdown-proposal/). 4118 4119 ### Numbered example lists ### 4120 4121 #### Extension: example_lists #### 4122 4123 The special list marker @ can be used for sequentially numbered 4124 examples. The first list item with a @ marker will be numbered '1', 4125 the next '2', and so on, throughout the document. The numbered examples 4126 need not occur in a single list; each new list using @ will take up 4127 where the last stopped. So, for example: 4128 4129 (@) My first example will be numbered (1). 4130 (@) My second example will be numbered (2). 4131 4132 Explanation of examples. 4133 4134 (@) My third example will be numbered (3). 4135 4136 Numbered examples can be labeled and referred to elsewhere in the 4137 document: 4138 4139 (@good) This is a good example. 4140 4141 As (@good) illustrates, ... 4142 4143 The label can be any string of alphanumeric characters, underscores, 4144 or hyphens. 4145 4146 Note: continuation paragraphs in example lists must always 4147 be indented four spaces, regardless of the length of the 4148 list marker. That is, example lists always behave as if the 4149 four_space_rule extension is set. This is because example 4150 labels tend to be long, and indenting content to the 4151 first non-space character after the label would be awkward. 4152 4153 4154 ### Ending a list ### 4155 4156 What if you want to put an indented code block after a list? 4157 4158 - item one 4159 - item two 4160 4161 { my code block } 4162 4163 Trouble! Here pandoc (like other Markdown implementations) will treat 4164 { my code block } as the second paragraph of item two, and not as 4165 a code block. 4166 4167 To "cut off" the list after item two, you can insert some non-indented 4168 content, like an HTML comment, which won't produce visible output in 4169 any format: 4170 4171 - item one 4172 - item two 4173 4174 <!-- end of list --> 4175 4176 { my code block } 4177 4178 You can use the same trick if you want two consecutive lists instead 4179 of one big list: 4180 4181 1. one 4182 2. two 4183 3. three 4184 4185 <!-- --> 4186 4187 1. uno 4188 2. dos 4189 3. tres 4190 4191 ## Horizontal rules 4192 4193 A line containing a row of three or more *, -, or _ characters 4194 (optionally separated by spaces) produces a horizontal rule: 4195 4196 * * * * 4197 4198 --------------- 4199 4200 4201 ## Tables 4202 4203 Four kinds of tables may be used. The first three kinds presuppose the use of 4204 a fixed-width font, such as Courier. The fourth kind can be used with 4205 proportionally spaced fonts, as it does not require lining up columns. 4206 4207 #### Extension: table_captions #### 4208 4209 A caption may optionally be provided with all 4 kinds of tables (as 4210 illustrated in the examples below). A caption is a paragraph beginning 4211 with the string Table: (or just :), which will be stripped off. 4212 It may appear either before or after the table. 4213 4214 #### Extension: simple_tables #### 4215 4216 Simple tables look like this: 4217 4218 Right Left Center Default 4219 ------- ------ ---------- ------- 4220 12 12 12 12 4221 123 123 123 123 4222 1 1 1 1 4223 4224 Table: Demonstration of simple table syntax. 4225 4226 The header and table rows must each fit on one line. Column 4227 alignments are determined by the position of the header text relative 4228 to the dashed line below it:[^4] 4229 4230 - If the dashed line is flush with the header text on the right side 4231 but extends beyond it on the left, the column is right-aligned. 4232 - If the dashed line is flush with the header text on the left side 4233 but extends beyond it on the right, the column is left-aligned. 4234 - If the dashed line extends beyond the header text on both sides, 4235 the column is centered. 4236 - If the dashed line is flush with the header text on both sides, 4237 the default alignment is used (in most cases, this will be left). 4238 4239 [^4]: This scheme is due to Michel Fortin, who proposed it on the 4240 [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html). 4241 4242 The table must end with a blank line, or a line of dashes followed by 4243 a blank line. 4244 4245 The column header row may be omitted, provided a dashed line is used 4246 to end the table. For example: 4247 4248 ------- ------ ---------- ------- 4249 12 12 12 12 4250 123 123 123 123 4251 1 1 1 1 4252 ------- ------ ---------- ------- 4253 4254 When the header row is omitted, column alignments are determined on the basis 4255 of the first line of the table body. So, in the tables above, the columns 4256 would be right, left, center, and right aligned, respectively. 4257 4258 #### Extension: multiline_tables #### 4259 4260 Multiline tables allow header and table rows to span multiple lines 4261 of text (but cells that span multiple columns or rows of the table are 4262 not supported). Here is an example: 4263 4264 ------------------------------------------------------------- 4265 Centered Default Right Left 4266 Header Aligned Aligned Aligned 4267 ----------- ------- --------------- ------------------------- 4268 First row 12.0 Example of a row that 4269 spans multiple lines. 4270 4271 Second row 5.0 Here's another one. Note 4272 the blank line between 4273 rows. 4274 ------------------------------------------------------------- 4275 4276 Table: Here's the caption. It, too, may span 4277 multiple lines. 4278 4279 These work like simple tables, but with the following differences: 4280 4281 - They must begin with a row of dashes, before the header text 4282 (unless the header row is omitted). 4283 - They must end with a row of dashes, then a blank line. 4284 - The rows must be separated by blank lines. 4285 4286 In multiline tables, the table parser pays attention to the widths of 4287 the columns, and the writers try to reproduce these relative widths in 4288 the output. So, if you find that one of the columns is too narrow in the 4289 output, try widening it in the Markdown source. 4290 4291 The header may be omitted in multiline tables as well as simple tables: 4292 4293 ----------- ------- --------------- ------------------------- 4294 First row 12.0 Example of a row that 4295 spans multiple lines. 4296 4297 Second row 5.0 Here's another one. Note 4298 the blank line between 4299 rows. 4300 ----------- ------- --------------- ------------------------- 4301 4302 : Here's a multiline table without a header. 4303 4304 It is possible for a multiline table to have just one row, but the row 4305 should be followed by a blank line (and then the row of dashes that ends 4306 the table), or the table may be interpreted as a simple table. 4307 4308 #### Extension: grid_tables #### 4309 4310 Grid tables look like this: 4311 4312 : Sample grid table. 4313 4314 +---------------+---------------+--------------------+ 4315 | Fruit | Price | Advantages | 4316 +===============+===============+====================+ 4317 | Bananas |1.34         | - built-in wrapper |
4318     |               |               | - bright color     |
4319     +---------------+---------------+--------------------+
4320     | Oranges       | $2.10 | - cures scurvy | 4321 | | | - tasty | 4322 +---------------+---------------+--------------------+ 4323 4324 The row of =s separates the header from the table body, and can be 4325 omitted for a headerless table. The cells of grid tables may contain 4326 arbitrary block elements (multiple paragraphs, code blocks, lists, 4327 etc.). Cells that span multiple columns or rows are not 4328 supported. Grid tables can be created easily using Emacs' table-mode 4329 (M-x table-insert). 4330 4331 Alignments can be specified as with pipe tables, by putting 4332 colons at the boundaries of the separator line after the 4333 header: 4334 4335 +---------------+---------------+--------------------+ 4336 | Right | Left | Centered | 4337 +==============:+:==============+:==================:+ 4338 | Bananas |$1.34         | built-in wrapper   |
4339     +---------------+---------------+--------------------+
4340
4341 For headerless tables, the colons go on the top line instead:
4342
4343     +--------------:+:--------------+:------------------:+
4344     | Right         | Left          | Centered           |
4345     +---------------+---------------+--------------------+
4346
4347 ##### Grid Table Limitations #####
4348
4349 Pandoc does not support grid tables with row spans or column spans.
4350 This means that neither variable numbers of columns across rows nor
4351 variable numbers of rows across columns are supported by Pandoc.
4352 All grid tables must have the same number of columns in each row,
4353 and the same number of rows in each column.  For example, the
4354 Docutils [sample grid tables] will not render as expected with
4355 Pandoc.
4356
4357 [sample grid tables]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables
4358
4359
4360 #### Extension: pipe_tables ####
4361
4362 Pipe tables look like this:
4363
4364     | Right | Left | Default | Center |
4365     |------:|:-----|---------|:------:|
4366     |   12  |  12  |    12   |    12  |
4367     |  123  |  123 |   123   |   123  |
4368     |    1  |    1 |     1   |     1  |
4369
4370       : Demonstration of pipe table syntax.
4371
4372 The syntax is identical to [PHP Markdown Extra tables].  The beginning and
4373 ending pipe characters are optional, but pipes are required between all
4374 columns.  The colons indicate column alignment as shown.  The header
4375 cannot be omitted.  To simulate a headerless table, include a header
4376 with blank cells.
4377
4378 Since the pipes indicate column boundaries, columns need not be vertically
4379 aligned, as they are in the above example.  So, this is a perfectly
4380 legal (though ugly) pipe table:
4381
4382     fruit| price
4383     -----|-----:
4384     apple|2.05
4385     pear|1.37
4386     orange|3.09
4387
4388 The cells of pipe tables cannot contain block elements like paragraphs
4389 and lists, and cannot span multiple lines.  If any line of the
4390 markdown source is longer than the column width (see --columns),
4391 then the table will take up the full text width and the cell
4392 contents will wrap, with the relative cell widths determined by
4393 the number of dashes in the line separating the table header
4394 from the table body. (For example ---|- would make the first column 3/4
4395 and the second column 1/4 of the full text width.)
4396 On the other hand, if no lines are wider than column width, then
4397 cell contents will not be wrapped, and the cells will be sized
4398 to their contents.
4399
4400 Note:  pandoc also recognizes pipe tables of the following
4401 form, as can be produced by Emacs' orgtbl-mode:
4402
4403     | One | Two   |
4404     |-----+-------|
4405     | my  | table |
4406     | is  | nice  |
4407
4408 The difference is that + is used instead of |. Other orgtbl features
4409 are not supported. In particular, to get non-default column alignment,
4410 you'll need to add colons as above.
4411
4412 [PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table
4413
4415
4416 #### Extension: pandoc_title_block ####
4417
4418 If the file begins with a title block
4419
4420     % title
4421     % author(s) (separated by semicolons)
4422     % date
4423
4424 it will be parsed as bibliographic information, not regular text.  (It
4425 will be used, for example, in the title of standalone LaTeX or HTML
4426 output.)  The block may contain just a title, a title and an author,
4427 or all three elements. If you want to include an author but no
4428 title, or a title and a date but no author, you need a blank line:
4429
4430 
4431 %
4432 % Author
4433 
4434
4435 
4436 % My title
4437 %
4438 % June 15, 2006
4439 
4440
4441 The title may occupy multiple lines, but continuation lines must
4442 begin with leading space, thus:
4443
4444 
4445 % My title
4446   on multiple lines
4447 
4448
4449 If a document has multiple authors, the authors may be put on
4450 separate lines with leading space, or separated by semicolons, or
4451 both.  So, all of the following are equivalent:
4452
4453 
4454 % Author One
4455   Author Two
4456 
4457
4458 
4459 % Author One; Author Two
4460 
4461
4462 
4463 % Author One;
4464   Author Two
4465 
4466
4467 The date must fit on one line.
4468
4469 All three metadata fields may contain standard inline formatting
4471
4472 Title blocks will always be parsed, but they will affect the output only
4473 when the --standalone (-s) option is chosen. In HTML output, titles
4474 will appear twice: once in the document head -- this is the title that
4475 will appear at the top of the window in a browser -- and once at the
4476 beginning of the document body. The title in the document head can have
4477 an optional prefix attached (--title-prefix or -T option). The title
4478 in the body appears as an H1 element with class "title", so it can be
4479 suppressed or reformatted with CSS. If a title prefix is specified with
4480 -T and no title block appears in the document, the title prefix will
4481 be used by itself as the HTML title.
4482
4483 The man page writer extracts a title, man page section number, and
4484 other header and footer information from the title line. The title
4485 is assumed to be the first word on the title line, which may optionally
4486 end with a (single-digit) section number in parentheses. (There should
4487 be no space between the title and the parentheses.)  Anything after
4488 this is assumed to be additional footer and header text. A single pipe
4489 character (|) should be used to separate the footer text from the header
4490 text.  Thus,
4491
4492     % PANDOC(1)
4493
4494 will yield a man page with the title PANDOC and section 1.
4495
4496     % PANDOC(1) Pandoc User Manuals
4497
4498 will also have "Pandoc User Manuals" in the footer.
4499
4500     % PANDOC(1) Pandoc User Manuals | Version 4.0
4501
4502 will also have "Version 4.0" in the header.
4503
4504 #### Extension: yaml_metadata_block ####
4505
4506 A [YAML] metadata block is a valid YAML object, delimited by a line of three
4507 hyphens (---) at the top and a line of three hyphens (---) or three dots
4508 (...) at the bottom.  A YAML metadata block may occur anywhere in the
4509 document, but if it is not at the beginning, it must be preceded by a blank
4510 line.  (Note that, because of the way pandoc concatenates input files when
4511 several are provided, you may also keep the metadata in a separate YAML file
4512 and pass it to pandoc as an argument, along with your Markdown files:
4513
4514     pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
4515
4516 Just be sure that the YAML file begins with --- and ends with --- or
4517 ....) Alternatively, you can use the --metadata-file option. Using
4518 that approach however, you cannot reference content (like footnotes)
4519 from the main markdown input document.
4520
4521 Metadata will be taken from the fields of the YAML object and added to any
4523 arbitrarily), but all string scalars will be interpreted as Markdown.  Fields
4524 with names ending in an underscore will be ignored by pandoc.  (They may be
4525 given a role by external processors.)  Field names must not be
4526 interpretable as YAML numbers or boolean values (so, for
4527 example, yes, True, and 15 cannot be used as field names).
4528
4529 A document may contain multiple metadata blocks.  If two
4530 metadata blocks attempt to set the same field, the value from
4531 the second block will be taken.
4532
4533 Each metadata block is handled internally as an independent YAML document.
4534 This means, for example, that any YAML anchors defined in a block cannot be
4535 referenced in another block.
4536
4537 When pandoc is used with -t markdown to create a Markdown document,
4538 a YAML metadata block will be produced only if the -s/--standalone
4539 option is used.  All of the metadata will appear in a single block
4540 at the beginning of the document.
4541
4542 Note that [YAML] escaping rules must be followed. Thus, for example,
4543 if a title contains a colon, it must be quoted, and if it contains a
4544 backslash escape, then it must be ensured that it is not treated as a
4545 [YAML escape sequence]. The pipe character (|) can be used to begin
4546 an indented block that will be interpreted literally, without need for
4547 escaping. This form is necessary when the field contains blank lines
4548 or block-level formatting:
4549
4550     ---
4551     title:  'This is the title: it contains a colon'
4552     author:
4553     - Author One
4554     - Author Two
4555     keywords: [nothing, nothingness]
4556     abstract: |
4557       This is the abstract.
4558
4559       It consists of two paragraphs.
4560     ...
4561
4562 The literal block after the | must be indented relative to the
4563 line containing the |.  If it is not, the YAML will be invalid
4564 and pandoc will not interpret it as metadata.  For an overview
4565 of the complex rules governing YAML, see the [Wikipedia entry on
4566 YAML syntax].
4567
4568 Template variables will be set automatically from the metadata.  Thus, for
4569 example, in writing HTML, the variable abstract will be set to the HTML
4570 equivalent of the Markdown in the abstract field:
4571
4572     <p>This is the abstract.</p>
4573     <p>It consists of two paragraphs.</p>
4574
4575 Variables can contain arbitrary YAML structures, but the template must match
4576 this structure.  The author variable in the default templates expects a
4577 simple list or string, but can be changed to support more complicated
4578 structures.  The following combination, for example, would add an affiliation
4579 to the author if one is given:
4580
4581     ---
4582     title: The document title
4583     author:
4584     - name: Author One
4585       affiliation: University of Somewhere
4586     - name: Author Two
4587       affiliation: University of Nowhere
4588     ...
4589
4590 To use the structured authors in the example above, you would need a custom
4591 template:
4592
4593     $for(author)$
4594     $if(author.name)$
4595     $author.name$$if(author.affiliation) (author.affiliation)endif 4596 else 4597 author 4598 endif 4599 endfor 4600 4601 Raw content to include in the document's header may be specified 4602 using header-includes; however, it is important to mark up 4603 this content as raw code for a particular output format, using 4604 the [raw_attribute extension](#extension-raw_attribute)), or it 4605 will be interpreted as markdown. For example: 4606 4607 header-includes: 4608 - | 4609 {=latex} 4610 \let\oldsection\section 4611 \renewcommand{\section}[1]{\clearpage\oldsection{#1}} 4612  4613 4614 Note: the yaml_metadata_block extension works with 4615 commonmark as well as markdown (and it is enabled by default 4616 in gfm and commonmark_x). However, in these formats the 4617 following restrictions apply: 4618 4619 - The YAML metadata block must occur at the beginning of the 4620 document (and there can be only one). If multiple files are 4621 given as arguments to pandoc, only the first can be a YAML 4622 metadata block. 4623 4624 - The leaf nodes of the YAML structure are parsed in isolation from 4625 each other and from the rest of the document. So, for 4626 example, you can't use a reference link in these contexts 4627 if the link definition is somewhere else in the document. 4628 4629 [YAML escape sequence]: https://yaml.org/spec/1.2/spec.html#id2776092 4630 [Wikipedia entry on YAML syntax]: https://en.m.wikipedia.org/wiki/YAML#Syntax 4631 4632 ## Backslash escapes 4633 4634 #### Extension: all_symbols_escapable #### 4635 4636 Except inside a code block or inline code, any punctuation or space 4637 character preceded by a backslash will be treated literally, even if it 4638 would normally indicate formatting. Thus, for example, if one writes 4639 4640 *\*hello\** 4641 4642 one will get 4643 4644 <em>*hello*</em> 4645 4646 instead of 4647 4648 <strong>hello</strong> 4649 4650 This rule is easier to remember than original Markdown's rule, 4651 which allows only the following characters to be backslash-escaped: 4652 4653 \*_{}[]()>#+-.! 4654 4655 (However, if the markdown_strict format is used, the original Markdown rule 4656 will be used.) 4657 4658 A backslash-escaped space is parsed as a nonbreaking space. In TeX output, 4659 it will appear as ~. In HTML and XML output, it will appear as a 4660 literal unicode nonbreaking space character (note that it will thus 4661 actually look "invisible" in the generated HTML source; you can still 4662 use the --ascii command-line option to make it appear as an explicit 4663 entity). 4664 4665 A backslash-escaped newline (i.e. a backslash occurring at the end of 4666 a line) is parsed as a hard line break. It will appear in TeX output as 4667 \\ and in HTML as <br />. This is a nice alternative to 4668 Markdown's "invisible" way of indicating hard line breaks using 4669 two trailing spaces on a line. 4670 4671 Backslash escapes do not work in verbatim contexts. 4672 4673 ## Inline formatting 4674 4675 ### Emphasis ### 4676 4677 To *emphasize* some text, surround it with *s or _, like this: 4678 4679 This text is _emphasized with underscores_, and this 4680 is *emphasized with asterisks*. 4681 4682 Double * or _ produces **strong emphasis**: 4683 4684 This is **strong emphasis** and __with underscores__. 4685 4686 A * or _ character surrounded by spaces, or backslash-escaped, 4687 will not trigger emphasis: 4688 4689 This is * not emphasized *, and \*neither is this\*. 4690 4691 #### Extension: intraword_underscores #### 4692 4693 Because _ is sometimes used inside words and identifiers, 4694 pandoc does not interpret a _ surrounded by alphanumeric 4695 characters as an emphasis marker. If you want to emphasize 4696 just part of a word, use *: 4697 4698 feas*ible*, not feas*able*. 4699 4700 4701 ### Strikeout ### 4702 4703 #### Extension: strikeout #### 4704 4705 To strikeout a section of text with a horizontal line, begin and end it 4706 with ~~. Thus, for example, 4707 4708 This ~~is deleted text.~~ 4709 4710 4711 ### Superscripts and subscripts ### 4712 4713 #### Extension: superscript, subscript #### 4714 4715 Superscripts may be written by surrounding the superscripted text by ^ 4716 characters; subscripts may be written by surrounding the subscripted 4717 text by ~ characters. Thus, for example, 4718 4719 H~2~O is a liquid. 2^10^ is 1024. 4720 4721 The text between ^...^ or ~...~ may not contain spaces or 4722 newlines. If the superscripted or subscripted text contains 4723 spaces, these spaces must be escaped with backslashes. (This is 4724 to prevent accidental superscripting and subscripting through 4725 the ordinary use of ~ and ^, and also bad interactions with 4726 footnotes.) Thus, if you want the letter P with 'a cat' in 4727 subscripts, use P~a\ cat~, not P~a cat~. 4728 4729 ### Verbatim ### 4730 4731 To make a short span of text verbatim, put it inside backticks: 4732 4733 What is the difference between >>= and >>? 4734 4735 If the verbatim text includes a backtick, use double backticks: 4736 4737 Here is a literal backtick   . 4738 4739 (The spaces after the opening backticks and before the closing 4740 backticks will be ignored.) 4741 4742 The general rule is that a verbatim span starts with a string 4743 of consecutive backticks (optionally followed by a space) 4744 and ends with a string of the same number of backticks (optionally 4745 preceded by a space). 4746 4747 Note that backslash-escapes (and other Markdown constructs) do not 4748 work in verbatim contexts: 4749 4750 This is a backslash followed by an asterisk: \*. 4751 4752 #### Extension: inline_code_attributes #### 4753 4754 Attributes can be attached to verbatim text, just as with 4755 [fenced code blocks]: 4756 4757 <>{.haskell} 4758 4759 ### Underline ### 4760 4761 To underline text, use the underline class: 4762 4763 [Underline]{.underline} 4764 4765 Or, without the bracketed_spans extension (but with native_spans): 4766 4767 <span class="underline">Underline</span> 4768 4769 This will work in all output formats that support underline. 4770 4771 ### Small caps ### 4772 4773 To write small caps, use the smallcaps class: 4774 4775 [Small caps]{.smallcaps} 4776 4777 Or, without the bracketed_spans extension: 4778 4779 <span class="smallcaps">Small caps</span> 4780 4781 For compatibility with other Markdown flavors, CSS is also supported: 4782 4783 <span style="font-variant:small-caps;">Small caps</span> 4784 4785 This will work in all output formats that support small caps. 4786 4787 4788 ## Math 4789 4790 #### Extension: tex_math_dollars #### 4791 4792 Anything between two  characters will be treated as TeX math. The 4793 opening  must have a non-space character immediately to its right, 4794 while the closing  must have a non-space character immediately to its 4795 left, and must not be followed immediately by a digit. Thus, 4796 20,000 and 30,000 won't parse as math. If for some reason 4797 you need to enclose text in literal  characters, backslash-escape 4798 them and they won't be treated as math delimiters. 4799 4800 For display math, use $$ delimiters. (In this case, the delimiters 4801 may be separated from the formula by whitespace. However, there can be 4802 no blank lines between the opening and closing $$ delimiters.) 4803 4804 TeX math will be printed in all output formats. How it is rendered 4805 depends on the output format: 4806 4807 LaTeX 4808 ~ It will appear verbatim surrounded by $$...$$ (for inline 4809 math) or $...$ (for display math). 4810 4811 Markdown, Emacs Org mode, ConTeXt, ZimWiki 4812 ~ It will appear verbatim surrounded by ... (for inline 4813 math) or $$...$$ (for display math). 4814 4815 XWiki 4816 ~ It will appear verbatim surrounded by {{formula}}..{{/formula}}. 4817 4818 reStructuredText 4819 ~ It will be rendered using an [interpreted text role :math:]. 4820 4821 AsciiDoc 4822 ~ For AsciiDoc output format (-t asciidoc) it will appear verbatim 4823 surrounded by latexmath:[$...$] (for inline math) or 4824 [latexmath]++++$...$+++ (for display math). 4825 For AsciiDoctor output format (-t asciidoctor) the LaTex delimiters 4826 ($..$ and $..$) are omitted. 4827 4828 Texinfo 4829 ~ It will be rendered inside a @math command. 4830 4831 roff man, Jira markup 4832 ~ It will be rendered verbatim without $'s.
4833
4834 MediaWiki, DokuWiki
4835   ~ It will be rendered inside [itex] tags.
4836
4837 Textile
4838   ~ It will be rendered inside <span class="math"> tags.
4839
4840 RTF, OpenDocument
4841   ~ It will be rendered, if possible, using Unicode characters,
4842     and will otherwise appear verbatim.
4843
4844 ODT
4845   ~ It will be rendered, if possible, using MathML.
4846
4847 DocBook
4848   ~ If the --mathml flag is used, it will be rendered using MathML
4849     in an inlineequation or informalequation tag.  Otherwise it
4850     will be rendered, if possible, using Unicode characters.
4851
4852 Docx
4853   ~ It will be rendered using OMML math markup.
4854
4855 FictionBook2
4856   ~ If the --webtex option is used, formulas are rendered as images
4858     and embedded in the e-book. Otherwise, they will appear verbatim.
4859
4860 HTML, Slidy, DZSlides, S5, EPUB
4861   ~ The way math is rendered in HTML will depend on the
4862     command-line options selected. Therefore see [Math rendering in HTML]
4863     above.
4864
4865 [interpreted text role :math:]: https://docutils.sourceforge.io/docs/ref/rst/roles.html#math
4866
4867 ## Raw HTML
4868
4869 #### Extension: raw_html ####
4870
4871 Markdown allows you to insert raw HTML (or DocBook) anywhere in a document
4872 (except verbatim contexts, where <, >, and & are interpreted
4873 literally).  (Technically this is not an extension, since standard
4874 Markdown allows it, but it has been made an extension so that it can
4875 be disabled if desired.)
4876
4877 The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
4878 DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile
4879 output, and suppressed in other formats.
4880
4881 For a more explicit way of including raw HTML in a Markdown
4882 document, see the [raw_attribute extension][Extension: raw_attribute].
4883
4884 In the CommonMark format, if raw_html is enabled, superscripts,
4885 subscripts, strikeouts and small capitals will be represented as HTML.
4886 Otherwise, plain-text fallbacks will be used. Note that even if
4887 raw_html is disabled, tables will be rendered with HTML syntax if
4888 they cannot use pipe syntax.
4889
4890 #### Extension: markdown_in_html_blocks ####
4891
4892 Original Markdown allows you to include HTML "blocks":  blocks
4893 of HTML between balanced tags that are separated from the surrounding text
4894 with blank lines, and start and end at the left margin.  Within
4895 these blocks, everything is interpreted as HTML, not Markdown;
4896 so (for example), * does not signify emphasis.
4897
4898 Pandoc behaves this way when the markdown_strict format is used; but
4899 by default, pandoc interprets material between HTML block tags as Markdown.
4900 Thus, for example, pandoc will turn
4901
4902     <table>
4903     <tr>
4904     <td>*one*</td>
4906     </tr>
4907     </table>
4908
4909 into
4910
4911     <table>
4912     <tr>
4913     <td><em>one</em></td>
4915     </tr>
4916     </table>
4917
4918 whereas Markdown.pl will preserve it as is.
4919
4920 There is one exception to this rule:  text between <script>,
4921 <style>, and <textarea> tags is not interpreted as Markdown.
4922
4923 This departure from original Markdown should make it easier to mix
4924 Markdown with HTML block elements.  For example, one can surround
4925 a block of Markdown text with <div> tags without preventing it
4926 from being interpreted as Markdown.
4927
4928 #### Extension: native_divs ####
4929
4930 Use native pandoc Div blocks for content inside <div> tags.
4931 For the most part this should give the same output as
4932 markdown_in_html_blocks, but it makes it easier to write pandoc
4933 filters to manipulate groups of blocks.
4934
4935 #### Extension: native_spans ####
4936
4937 Use native pandoc Span blocks for content inside <span> tags.
4938 For the most part this should give the same output as raw_html,
4939 but it makes it easier to write pandoc filters to manipulate groups
4940 of inlines.
4941
4942 #### Extension: raw_tex ####
4943
4944 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
4945 included in a document. Inline TeX commands will be preserved and passed
4946 unchanged to the LaTeX and ConTeXt writers. Thus, for example, you can use
4947 LaTeX to include BibTeX citations:
4948
4949     This result was proved in \cite{jones.1967}.
4950
4951 Note that in LaTeX environments, like
4952
4953     \begin{tabular}{|l|l|}\hline
4954     Age & Frequency \\ \hline
4955     18--25  & 15 \\
4956     26--35  & 33 \\
4957     36--45  & 22 \\ \hline
4958     \end{tabular}
4959
4960 the material between the begin and end tags will be interpreted as raw
4961 LaTeX, not as Markdown.
4962
4963 For a more explicit and flexible way of including raw TeX in a
4964 Markdown document, see the [raw_attribute
4965 extension][Extension: raw_attribute].
4966
4967 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
4968 Emacs Org mode, and ConTeXt.
4969
4970 ### Generic raw attribute ###
4971
4972 #### Extension: raw_attribute ####
4973
4974 Inline spans and fenced code blocks with a special
4975 kind of attribute will be parsed as raw content with the
4976 designated format.  For example, the following produces a raw
4977 roff ms block:
4978
4979     {=ms}
4980     .MYMACRO
4981     blah blah
4982     
4983 And the following produces a raw html inline element:
4984
4985     This is <a>html</a>{=html}
4986
4987 This can be useful to insert raw xml into docx documents, e.g.
4988 a pagebreak:
4989
4990     {=openxml}
4991     <w:p>
4992       <w:r>
4993         <w:br w:type="page"/>
4994       </w:r>
4995     </w:p>
4996     
4997
4998 The format name should match the target format name (see
4999 -t/--to, above, for a list, or use pandoc
5000 --list-output-formats). Use openxml for docx output,
5001 opendocument for odt output, html5 for epub3 output,
5002 html4 for epub2 output, and latex, beamer,
5003 ms, or html5 for pdf output (depending on what you
5004 use for --pdf-engine).
5005
5006 This extension presupposes that the relevant kind of
5007 inline code or fenced code block is enabled.  Thus, for
5008 example, to use a raw attribute with a backtick code block,
5009 backtick_code_blocks must be enabled.
5010
5011 The raw attribute cannot be combined with regular attributes.
5012
5013 ## LaTeX macros
5014
5015 #### Extension: latex_macros ####
5016
5017 When this extension is enabled, pandoc will parse LaTeX
5018 macro definitions and apply the resulting macros to all LaTeX
5019 math and raw LaTeX.  So, for example, the following will work in
5020 all output formats, not just LaTeX:
5021
5022     \newcommand{\tuple}[1]{\langle #1 \rangle}
5023
5024     $\tuple{a, b, c}$
5025
5026 Note that LaTeX macros will not be applied if they occur
5027 inside a raw span or block marked with the
5028 [raw_attribute extension](#extension-raw_attribute).
5029
5030 When latex_macros is disabled, the raw LaTeX and math will
5031 not have macros applied. This is usually a better approach when
5032 you are targeting LaTeX or PDF.
5033
5034 Macro definitions in LaTeX will be passed through as raw LaTeX
5035 only if latex_macros is not enabled.  Macro definitions in
5036 Markdown source (or other formats allowing raw_tex) will
5037 be passed through regardless of whether latex_macros is
5038 enabled.
5039
5041
5042 Markdown allows links to be specified in several ways.
5043
5045
5046 If you enclose a URL or email address in pointy brackets, it
5048
5050     <sam@green.eggs.ham>
5051
5053
5054 An inline link consists of the link text in square brackets,
5055 followed by the URL in parentheses. (Optionally, the URL can
5056 be followed by a link title, in quotes.)
5057
5058     This is an [inline link](/url), and here's [one with
5060
5061 There can be no space between the bracketed part and the parenthesized part.
5062 The link text can contain formatting (such as emphasis), but the title cannot.
5063
5064 Email addresses in inline links are not autodetected, so they have to be
5065 prefixed with mailto:
5066
5067     [Write me!](mailto:sam@green.eggs.ham)
5068
5070
5072 definition, which may occur elsewhere in the document (either
5073 before or after the link).
5074
5075 The link consists of link text in square brackets, followed by a label in
5076 square brackets. (There cannot be space between the two unless the
5077 spaced_reference_links extension is enabled.) The link definition
5078 consists of the bracketed label, followed by a colon and a space, followed by
5079 the URL, and optionally (after a space) a link title either in quotes or in
5080 parentheses.  The label must not be parseable as a citation (assuming
5081 the citations extension is enabled):  citations take precedence over
5083
5084 Here are some examples:
5085
5086     [my label 1]: /foo/bar.html  "My title, optional"
5087     [my label 2]: /foo
5088     [my label 3]: https://fsf.org (The free software foundation)
5089     [my label 4]: /bar#special  'A title in single quotes'
5090
5091 The URL may optionally be surrounded by angle brackets:
5092
5093     [my label 5]: <http://foo.bar.baz>
5094
5095 The title may go on the next line:
5096
5097     [my label 3]: https://fsf.org
5098       "The free software foundation"
5099
5100 Note that link labels are not case sensitive.  So, this will work:
5101
5103
5104     [Foo]: /bar/baz
5105
5106 In an *implicit* reference link, the second pair of brackets is
5107 empty:
5108
5109     See [my website][].
5110
5111     [my website]: http://foo.bar.baz
5112
5113 Note:  In Markdown.pl and most other Markdown implementations,
5114 reference link definitions cannot occur in nested constructions
5115 such as list items or block quotes.  Pandoc lifts this arbitrary
5116 seeming restriction.  So the following is fine in pandoc, though
5117 not in most other implementations:
5118
5119     > My block [quote].
5120     >
5121     > [quote]: /foo
5122
5123 #### Extension: shortcut_reference_links ####
5124
5125 In a *shortcut* reference link, the second pair of brackets may
5126 be omitted entirely:
5127
5128     See [my website].
5129
5130     [my website]: http://foo.bar.baz
5131
5133
5134 To link to another section of the same document, use the automatically
5135 generated identifier (see [Heading identifiers]). For example:
5136
5137     See the [Introduction](#introduction).
5138
5139 or
5140
5141     See the [Introduction].
5142
5143     [Introduction]: #introduction
5144
5145 Internal links are currently supported for HTML formats (including
5146 HTML slide shows and EPUB), LaTeX, and ConTeXt.
5147
5148 ## Images
5149
5150 A link immediately preceded by a ! will be treated as an image.
5151 The link text will be used as the image's alt text:
5152
5153     ![la lune](lalune.jpg "Voyage to the moon")
5154
5155     ![movie reel]
5156
5157     [movie reel]: movie.gif
5158
5159 #### Extension: implicit_figures ####
5160
5161 An image with nonempty alt text, occurring by itself in a
5162 paragraph, will be rendered as a figure with a caption.  The
5163 image's alt text will be used as the caption.
5164
5165     ![This is the caption](/url/of/image.png)
5166
5167 How this is rendered depends on the output format. Some output
5168 formats (e.g. RTF) do not yet support figures.  In those
5169 formats, you'll just get an image in a paragraph by itself, with
5170 no caption.
5171
5172 If you just want a regular inline image, just make sure it is not
5173 the only thing in the paragraph. One way to do this is to insert a
5174 nonbreaking space after the image:
5175
5176     ![This image won't be a figure](/url/of/image.png)\
5177
5178 Note that in reveal.js slide shows, an image in a paragraph
5179 by itself that has the r-stretch class will fill the screen,
5180 and the caption and figure tags will be omitted.
5181
5182 #### Extension: link_attributes ####
5183
5184 Attributes can be set on links and images:
5185
5186     An inline ![image](foo.jpg){#id .class width=30 height=20px}
5187     and a reference ![image][ref] with attributes.
5188
5189     [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
5190
5191 (This syntax is compatible with [PHP Markdown Extra] when only #id
5192 and .class are used.)
5193
5194 For HTML and EPUB, all known HTML5 attributes except width and
5195 height (but including srcset and sizes) are passed through
5196 as is. Unknown attributes are passed through as custom
5197 attributes, with data- prepended. The other writers ignore
5198 attributes that are not specifically supported by their output format.
5199
5200 The width and height attributes on images are treated specially. When
5201 used without a unit, the unit is assumed to be pixels. However, any of
5202 the following unit identifiers can be used: px, cm, mm, in, inch
5203 and %. There must not be any spaces between the number and the unit.
5204 For example:
5205
5206 
5207 ![](file.jpg){ width=50% }
5208 
5209
5210 - Dimensions may be converted to a form that is compatible with
5211   the output format (for example, dimensions given in pixels will
5212   be converted to inches when converting HTML to LaTeX). Conversion
5213   between pixels and physical measurements is affected by the
5214   --dpi option (by default, 96 dpi is assumed, unless the image
5215   itself contains dpi information).
5216 - The % unit is generally relative to some available space.
5217   For example the above example will render to the following.
5218   - HTML: <img href="file.jpg" style="width: 50%;" />
5219   - LaTeX: \includegraphics[width=0.5\textwidth,height=\textheight]{file.jpg}
5220     (If you're using a custom template, you need to configure graphicx
5221     as in the default template.)
5222   - ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
5223 - Some output formats have a notion of a class
5224   ([ConTeXt](https://wiki.contextgarden.net/Using_Graphics#Multiple_Image_Settings))
5225   or a unique identifier (LaTeX \caption), or both (HTML).
5226 - When no width or height attributes are specified, the fallback
5227   is to look at the image resolution and the dpi metadata embedded in
5228   the image file.
5229
5230 ## Divs and Spans
5231
5232 Using the native_divs and native_spans extensions
5233 (see [above][Extension: native_divs]), HTML syntax can
5234 be used as part of markdown to create native Div and Span
5235 elements in the pandoc AST (as opposed to raw HTML).
5236 However, there is also nicer syntax available:
5237
5238 #### Extension: fenced_divs ####
5239
5240 Allow special fenced syntax for native Div blocks.  A Div
5241 starts with a fence containing at least three consecutive
5242 colons plus some attributes. The attributes may optionally
5243 be followed by another string of consecutive colons.
5244 The attribute syntax is exactly as in fenced code blocks (see
5245 [Extension: fenced_code_attributes]).  As with fenced
5246 code blocks, one can use either attributes in curly braces
5247 or a single unbraced word, which will be treated as a class
5248 name.  The Div ends with another line containing a string of at
5249 least three consecutive colons.  The fenced Div should be
5250 separated by blank lines from preceding and following blocks.
5251
5252 Example:
5253
5254     ::::: {#special .sidebar}
5255     Here is a paragraph.
5256
5257     And another.
5258     :::::
5259
5260 Fenced divs can be nested.  Opening fences are distinguished
5261 because they *must* have attributes:
5262
5263     ::: Warning ::::::
5264     This is a warning.
5265
5266     ::: Danger
5267     This is a warning within a warning.
5268     :::
5269     ::::::::::::::::::
5270
5271 Fences without attributes are always closing fences.  Unlike
5272 with fenced code blocks, the number of colons in the closing
5273 fence need not match the number in the opening fence.  However,
5274 it can be helpful for visual clarity to use fences of different
5275 lengths to distinguish nested divs from their parents.
5276
5277
5278 #### Extension: bracketed_spans ####
5279
5280 A bracketed sequence of inlines, as one would use to begin
5281 a link, will be treated as a Span with attributes if it is
5282 followed immediately by attributes:
5283
5284     [This is *some text*]{.class key="val"}
5285
5286 ## Footnotes
5287
5288 #### Extension: footnotes ####
5289
5290 Pandoc's Markdown allows footnotes, using the following syntax:
5291
5292     Here is a footnote reference,[^1] and another.[^longnote]
5293
5294     [^1]: Here is the footnote.
5295
5296     [^longnote]: Here's one with multiple blocks.
5297
5298         Subsequent paragraphs are indented to show that they
5299     belong to the previous footnote.
5300
5301             { some.code }
5302
5303         The whole paragraph can be indented, or just the first
5304         line.  In this way, multi-paragraph footnotes work like
5305         multi-paragraph list items.
5306
5307     This paragraph won't be part of the note, because it
5308     isn't indented.
5309
5310 The identifiers in footnote references may not contain spaces, tabs,
5311 or newlines.  These identifiers are used only to correlate the
5312 footnote reference with the note itself; in the output, footnotes
5313 will be numbered sequentially.
5314
5315 The footnotes themselves need not be placed at the end of the
5316 document.  They may appear anywhere except inside other block elements
5317 (lists, block quotes, tables, etc.).  Each footnote should be
5318 separated from surrounding content (including other footnotes)
5319 by blank lines.
5320
5321 #### Extension: inline_notes ####
5322
5323 Inline footnotes are also allowed (though, unlike regular notes,
5324 they cannot contain multiple paragraphs).  The syntax is as follows:
5325
5326     Here is an inline note.^[Inlines notes are easier to write, since
5327     you don't have to pick an identifier and move down to type the
5328     note.]
5329
5330 Inline and regular footnotes may be mixed freely.
5331
5332 ## Citation syntax
5333
5334 #### Extension: citations ####
5335
5336 To cite a bibliographic item with an identifier foo, use the
5337 syntax @foo.  Normal citations should be included in square
5338 brackets, with semicolons separating distinct items:
5339
5340     Blah blah [@doe99; @smith2000; @smith2004].
5341
5342 How this is rendered depends on the citation style.  In an
5343 author-date style, it might render as
5344
5345     Blah blah (Doe 1999, Smith 2000, 2004).
5346
5347 In a footnote style, it might render as
5348
5349     Blah blah.[^1]
5350
5351     [^1]:  John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
5352     Susan Smith, "Flies," *Journal of Insects* (2000);
5353     Susan Smith, "Bees," *Journal of Insects* (2004).
5354
5356 styles and how they affect rendering.
5357
5358 Unless a citation key start with a letter, digit, or _,
5359 and contains only alphanumerics and single internal punctuation
5360 characters (:.#$%&-+?<>~/), it must be surrounded 5361 by curly braces, which are not considered part of the key. 5362 In @Foo_bar.baz., the key is Foo_bar.baz because the final 5363 period is not *internal* punctuation, so it is not included in 5364 the key. In @{Foo_bar.baz.}, the key is Foo_bar.baz., including 5365 the final period. 5366 In @Foo_bar--baz, the key is Foo_bar because the repeated internal 5367 punctuation characters terminate the key. 5368 The curly braces are recommended if you use URLs as 5369 keys: [@{https://example.com/bib?name=foobar&date=2000}, p. 33]. 5370 5371 Citation items may optionally include a prefix, a locator, and 5372 a suffix. In 5373 5374 Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1]. 5375 5376 The first item (doe99) has prefix see , locator pp. 33-35, 5377 and suffix and *passim*. The second item (smith04) has 5378 locator chap. 1 and no prefix or suffix. 5379 5380 Pandoc uses some heuristics to separate the locator from the 5381 rest of the subject. It is sensitive to the locator terms 5382 defined in the [CSL locale files]. Either abbreviated or 5383 unabbreviated forms are accepted. In the en-US locale, locator 5384 terms can be written in either singular or plural forms, as 5385 book, bk./bks.; chapter, chap./chaps.; column, 5386 col./cols.; figure, fig./figs.; folio, 5387 fol./fols.; number, no./nos.; line, l./ll.; 5388 note, n./nn.; opus, op./opp.; page, p./pp.; 5389 paragraph, para./paras.; part, pt./pts.; section, 5390 sec./secs.; sub verbo, s.v./s.vv.; verse, 5391 v./vv.; volume, vol./vols.; ¶/¶¶; §/§§. If no 5392 locator term is used, "page" is assumed. 5393 5394 In complex cases, you can force something to be treated as 5395 a locator by enclosing it in curly braces or prevent parsing 5396 the suffix as locator by prepending curly braces: 5397 5398 [@smith{ii, A, D-Z}, with a suffix] 5399 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here] 5400 [@smith{}, 99 years later] 5401 5402 A minus sign (-) before the @ will suppress mention of 5403 the author in the citation. This can be useful when the 5404 author is already mentioned in the text: 5405 5406 Smith says blah [-@smith04]. 5407 5408 You can also write an author-in-text citation, by omitting the 5409 square brackets: 5410 5411 @smith04 says blah. 5412 5413 @smith04 [p. 33] says blah. 5414 5415 This will cause the author's name to be rendered, followed by 5416 the bibliographical details. Use this form when you want to 5417 make the citation the subject of a sentence. 5418 5419 When you are using a note style, it is usually better to let 5420 citeproc create the footnotes from citations rather than writing 5421 an explicit note. If you do write an explicit note that 5422 contains a citation, note that normal citations will be put in 5423 parentheses, while author-in-text citations will not. For 5424 this reason, it is sometimes preferable to use the 5425 author-in-text style inside notes when using a note style. 5426 5427 [CSL user documentation]: https://citationstyles.org/authors/ 5428 [CSL]: https://docs.citationstyles.org/en/stable/specification.html 5429 [CSL markup specs]: https://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields 5430 [Chicago Manual of Style]: https://chicagomanualofstyle.org 5431 [Citation Style Language]: https://citationstyles.org 5432 [Zotero Style Repository]: https://www.zotero.org/styles 5433 [finding and editing styles]: https://citationstyles.org/authors/ 5434 [CSL locale files]: https://github.com/citation-style-language/locales 5435 5436 ## Non-default extensions 5437 5438 The following Markdown syntax extensions are not enabled by default 5439 in pandoc, but may be enabled by adding +EXTENSION to the format 5440 name, where EXTENSION is the name of the extension. Thus, for 5441 example, markdown+hard_line_breaks is Markdown with hard line breaks. 5442 5443 #### Extension: rebase_relative_paths #### 5444 5445 Rewrite relative paths for Markdown links and images, depending 5446 on the path of the file containing the link or image link. For 5447 each link or image, pandoc will compute the directory of the 5448 containing file, relative to the working directory, and prepend 5449 the resulting path to the link or image path. 5450 5451 The use of this extension is best understood by example. 5452 Suppose you have a a subdirectory for each chapter of a book, 5453 chap1, chap2, chap3. Each contains a file text.md and a 5454 number of images used in the chapter. You would like to have 5455 ![image](spider.jpg) in chap1/text.md refer to 5456 chap1/spider.jpg and ![image](spider.jpg) in chap2/text.md 5457 refer to chap2/spider.jpg. To do this, use 5458 5459 pandoc chap*/*.md -f markdown+rebase_relative_paths 5460 5461 Without this extension, you would have to use 5462 ![image](chap1/spider.jpg) in chap1/text.md and 5463 ![image](chap2/spider.jpg) in chap2/text.md. Links with 5464 relative paths will be rewritten in the same way as images. 5465 5466 Absolute paths and URLs are not changed. Neither are empty 5467 paths or paths consisting entirely of a fragment, e.g., #foo. 5468 5469 Note that relative paths in reference links and images will 5470 be rewritten relative to the file containing the link 5471 reference definition, not the file containing the reference link 5472 or image itself, if these differ. 5473 5474 #### Extension: attributes #### 5475 5476 Allows attributes to be attached to any inline or block-level 5477 element when parsing commonmark. 5478 The syntax for the attributes is the same as that 5479 used in [header_attributes][Extension: header_attributes]. 5480 5481 - Attributes that occur immediately after an inline 5482 element affect that element. If they follow a space, then they 5483 belong to the space. (Hence, this option subsumes 5484 inline_code_attributes and link_attributes.) 5485 - Attributes that occur immediately before a block 5486 element, on a line by themselves, affect that 5487 element. 5488 - Consecutive attribute specifiers may be used, 5489 either for blocks or for inlines. Their attributes 5490 will be combined. 5491 - Attributes that occur at the end of the text of 5492 a Setext or ATX heading (separated by whitespace 5493 from the text) affect the heading element. (Hence, this 5494 option subsumes header_attributes.) 5495 - Attributes that occur after the opening fence 5496 in a fenced code block affect the code block element. (Hence, 5497 this option subsumes fenced_code_attributes.) 5498 - Attributes that occur at the end of a reference 5499 link definition affect links that refer to that 5500 definition. 5501 5502 Note that pandoc's AST does not currently allow attributes 5503 to be attached to arbitrary elements. Hence a Span or Div 5504 container will be added if needed. 5505 5506 #### Extension: old_dashes #### 5507 5508 Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: 5509 - before a numeral is an en-dash, and -- is an em-dash. 5510 This option only has an effect if smart is enabled. It is 5511 selected automatically for textile input. 5512 5513 #### Extension: angle_brackets_escapable #### 5514 5515 Allow < and > to be backslash-escaped, as they can be in 5516 GitHub flavored Markdown but not original Markdown. This is 5517 implied by pandoc's default all_symbols_escapable. 5518 5519 #### Extension: lists_without_preceding_blankline #### 5520 5521 Allow a list to occur right after a paragraph, with no intervening 5522 blank space. 5523 5524 #### Extension: four_space_rule #### 5525 5526 Selects the pandoc <= 2.0 behavior for parsing lists, so that 5527 four spaces indent are needed for list item continuation 5528 paragraphs. 5529 5530 #### Extension: spaced_reference_links #### 5531 5532 Allow whitespace between the two components of a reference link, 5533 for example, 5534 5535 [foo] [bar]. 5536 5537 #### Extension: hard_line_breaks #### 5538 5539 Causes all newlines within a paragraph to be interpreted as hard line 5540 breaks instead of spaces. 5541 5542 #### Extension: ignore_line_breaks #### 5543 5544 Causes newlines within a paragraph to be ignored, rather than being 5545 treated as spaces or as hard line breaks. This option is intended for 5546 use with East Asian languages where spaces are not used between words, 5547 but text is divided into lines for readability. 5548 5549 #### Extension: east_asian_line_breaks #### 5550 5551 Causes newlines within a paragraph to be ignored, rather than 5552 being treated as spaces or as hard line breaks, when they occur 5553 between two East Asian wide characters. This is a better choice 5554 than ignore_line_breaks for texts that include a mix of East 5555 Asian wide characters and other characters. 5556 5557 #### Extension: emoji #### 5558 5559 Parses textual emojis like :smile: as Unicode emoticons. 5560 5561 #### Extension: tex_math_single_backslash #### 5562 5563 Causes anything between $$ and $$ to be interpreted as inline 5564 TeX math, and anything between $ and $ to be interpreted 5565 as display TeX math. Note: a drawback of this extension is that 5566 it precludes escaping ( and [. 5567 5568 #### Extension: tex_math_double_backslash #### 5569 5570 Causes anything between \$$ and \$$ to be interpreted as inline 5571 TeX math, and anything between \$ and \$ to be interpreted 5572 as display TeX math. 5573 5574 #### Extension: markdown_attribute #### 5575 5576 By default, pandoc interprets material inside block-level tags as Markdown. 5577 This extension changes the behavior so that Markdown is only parsed 5578 inside block-level tags if the tags have the attribute markdown=1. 5579 5580 #### Extension: mmd_title_block #### 5581 5582 Enables a [MultiMarkdown] style title block at the top of 5583 the document, for example: 5584 5585 Title: My title 5586 Author: John Doe 5587 Date: September 1, 2008 5588 Comment: This is a sample mmd title block, with 5589 a field spanning multiple lines. 5590 5591 See the MultiMarkdown documentation for details. If pandoc_title_block or 5592 yaml_metadata_block is enabled, it will take precedence over 5593 mmd_title_block. 5594 5595 #### Extension: abbreviations #### 5596 5597 Parses PHP Markdown Extra abbreviation keys, like 5598 5599 *[HTML]: Hypertext Markup Language 5600 5601 Note that the pandoc document model does not support 5602 abbreviations, so if this extension is enabled, abbreviation keys are 5603 simply skipped (as opposed to being parsed as paragraphs). 5604 5605 #### Extension: autolink_bare_uris #### 5606 5607 Makes all absolute URIs into links, even when not surrounded by 5608 pointy braces <...>. 5609 5610 #### Extension: mmd_link_attributes #### 5611 5612 Parses multimarkdown style key-value attributes on link 5613 and image references. This extension should not be confused with the 5614 [link_attributes](#extension-link_attributes) extension. 5615 5616 This is a reference ![image][ref] with multimarkdown attributes. 5617 5618 [ref]: https://path.to/image "Image title" width=20px height=30px 5619 id=myId class="myClass1 myClass2" 5620 5621 #### Extension: mmd_header_identifiers #### 5622 5623 Parses multimarkdown style heading identifiers (in square brackets, 5624 after the heading but before any trailing #s in an ATX heading). 5625 5626 #### Extension: compact_definition_lists #### 5627 5628 Activates the definition list syntax of pandoc 1.12.x and earlier. 5629 This syntax differs from the one described above under [Definition lists] 5630 in several respects: 5631 5632 - No blank line is required between consecutive items of the 5633 definition list. 5634 - To get a "tight" or "compact" list, omit space between consecutive 5635 items; the space between a term and its definition does not affect 5636 anything. 5637 - Lazy wrapping of paragraphs is not allowed: the entire definition must 5638 be indented four spaces.[^6] 5639 5640 [^6]: To see why laziness is incompatible with relaxing the requirement 5641 of a blank line between items, consider the following example: 5642 5643 bar 5644 : definition 5645 foo 5646 : definition 5647 5648 Is this a single list item with two definitions of "bar," the first of 5649 which is lazily wrapped, or two list items? To remove the ambiguity 5650 we must either disallow lazy wrapping or require a blank line between 5651 list items. 5652 5653 #### Extension: gutenberg #### 5654 5655 Use [Project Gutenberg] conventions for plain output: 5656 all-caps for strong emphasis, surround by underscores 5657 for regular emphasis, add extra blank space around headings. 5658 5659 [Project Gutenberg]: https://www.gutenberg.org 5660 5661 #### Extension: sourcepos #### 5662 5663 Include source position attributes when parsing commonmark. 5664 For elements that accept attributes, a data-pos attribute 5665 is added; other elements are placed in a surrounding 5666 Div or Span element with a data-pos attribute. 5667 5668 #### Extension: short_subsuperscripts #### 5669 5670 Parse multimarkdown style subscripts and superscripts, which start with 5671 a '~' or '^' character, respectively, and include the alphanumeric sequence 5672 that follows. For example: 5673 5674 x^2 = 4 5675 5676 or 5677 5678 Oxygen is O~2. 5679 5680 ## Markdown variants 5681 5682 In addition to pandoc's extended Markdown, the following Markdown 5683 variants are supported: 5684 5685 - markdown_phpextra (PHP Markdown Extra) 5686 - markdown_github (deprecated GitHub-Flavored Markdown) 5687 - markdown_mmd (MultiMarkdown) 5688 - markdown_strict (Markdown.pl) 5689 - commonmark (CommonMark) 5690 - gfm (Github-Flavored Markdown) 5691 - commonmark_x (CommonMark with many pandoc extensions) 5692 5693 To see which extensions are supported for a given format, 5694 and which are enabled by default, you can use the command 5695 5696 pandoc --list-extensions=FORMAT 5697 5698 where FORMAT is replaced with the name of the format. 5699 5700 Note that the list of extensions for commonmark, 5701 gfm, and commonmark_x are defined relative to default 5702 commonmark. So, for example, backtick_code_blocks 5703 does not appear as an extension, since it is enabled by 5704 default and cannot be disabled. 5705 5706 # Citations 5707 5708 When the --citeproc option is used, pandoc can automatically generate 5709 citations and a bibliography in a number of styles. Basic usage is 5710 5711 pandoc --citeproc myinput.txt 5712 5713 To use this feature, you will need to have 5714 5715 - a document containing citations (see [Extension: citations]); 5716 - a source of bibliographic data: either an external bibliography 5717 file or a list of references in the document's YAML metadata 5718 - optionally, a [CSL] citation style. 5719 5720 ## Specifying bibliographic data 5721 5722 You can specify an external bibliography using the 5723 bibliography metadata field in a YAML metadata section or the 5724 --bibliography command line argument. If you want to use 5725 multiple bibliography files, you can supply multiple 5726 --bibliography arguments or set bibliography metadata field 5727 to YAML array. A bibliography may have any of these formats: 5728 5729 Format File extension 5730 ------------ -------------- 5731 BibLaTeX .bib 5732 BibTeX .bibtex 5733 CSL JSON .json 5734 CSL YAML .yaml 5735 RIS .ris 5736 5737 Note that .bib can be used with both BibTeX and BibLaTeX files; 5738 use the extension .bibtex to force interpretation as BibTeX. 5739 5740 In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup 5741 inside fields such as title; in CSL YAML databases, pandoc 5742 Markdown; and in CSL JSON databases, an [HTML-like markup][CSL 5743 markup specs]: 5744 5745 <i>...</i> 5746 : italics 5747 5748 <b>...</b> 5749 : bold 5750 5751 <span style="font-variant:small-caps;">...</span> or <sc>...</sc> 5752 : small capitals 5753 5754 <sub>...</sub> 5755 : subscript 5756 5757 <sup>...</sup> 5758 : superscript 5759 5760 <span class="nocase">...</span> 5761 : prevent a phrase from being capitalized as title case 5762 5763 As an alternative to specifying a bibliography file using 5764 --bibliography or the YAML metadata field bibliography, you 5765 can include the citation data directly in the references field 5766 of the document's YAML metadata. The field should contain an 5767 array of YAML-encoded references, for example: 5768 5769 --- 5770 references: 5771 - type: article-journal 5772 id: WatsonCrick1953 5773 author: 5774 - family: Watson 5775 given: J. D. 5776 - family: Crick 5777 given: F. H. C. 5778 issued: 5779 date-parts: 5780 - - 1953 5781 - 4 5782 - 25 5783 title: 'Molecular structure of nucleic acids: a structure for 5784 deoxyribose nucleic acid' 5785 title-short: Molecular structure of nucleic acids 5786 container-title: Nature 5787 volume: 171 5788 issue: 4356 5789 page: 737-738 5790 DOI: 10.1038/171737a0 5791 URL: https://www.nature.com/articles/171737a0 5792 language: en-GB 5793 ... 5794 5795 If both an external bibliography and inline (YAML metadata) 5796 references are provided, both will be used. In case of 5797 conflicting ids, the inline references will take precedence. 5798 5799 Note that pandoc can be used to produce such a YAML metadata 5800 section from a BibTeX, BibLaTeX, or CSL JSON bibliography: 5801 5802 pandoc chem.bib -s -f biblatex -t markdown 5803 pandoc chem.json -s -f csljson -t markdown 5804 5805 Indeed, pandoc can convert between any of these 5806 citation formats: 5807 5808 pandoc chem.bib -s -f biblatex -t csljson 5809 pandoc chem.yaml -s -f markdown -t biblatex 5810 5811 Running pandoc on a bibliography file with the --citeproc 5812 option will create a formatted bibliography in the format 5813 of your choice: 5814 5815 pandoc chem.bib -s --citeproc -o chem.html 5816 pandoc chem.bib -s --citeproc -o chem.pdf 5817 5818 ### Capitalization in titles 5819 5820 If you are using a bibtex or biblatex bibliography, then observe 5821 the following rules: 5822 5823 - English titles should be in title case. Non-English titles should 5824 be in sentence case, and the langid field in biblatex should be 5825 set to the relevant language. (The following values are treated 5826 as English: american, british, canadian, english, 5827 australian, newzealand, USenglish, or UKenglish.) 5828 5829 - As is standard with bibtex/biblatex, proper names should be 5830 protected with curly braces so that they won't be lowercased 5831 in styles that call for sentence case. For example: 5832 5833 title = {My Dinner with {Andre}} 5834 5835 - In addition, words that should remain lowercase (or camelCase) 5836 should be protected: 5837 5838 title = {Spin Wave Dispersion on the {nm} Scale} 5839 5840 Though this is not necessary in bibtex/biblatex, it is necessary 5841 with citeproc, which stores titles internally in sentence case, 5842 and converts to title case in styles that require it. Here we 5843 protect "nm" so that it doesn't get converted to "Nm" at this stage. 5844 5845 If you are using a CSL bibliography (either JSON or YAML), then observe 5846 the following rules: 5847 5848 - All titles should be in sentence case. 5849 5850 - Use the language field for non-English titles to prevent their 5851 conversion to title case in styles that call for this. (Conversion 5852 happens only if language begins with en or is left empty.) 5853 5854 - Protect words that should not be converted to title case using 5855 this syntax: 5856 5857 Spin wave dispersion on the <span class="nocase">nm</span> scale 5858 5859 ### Conference Papers, Published vs. Unpublished 5860 5861 For a formally published conference paper, use the biblatex entry type 5862 inproceedings (which will be mapped to CSL paper-conference). 5863 5864 For an unpublished manuscript, use the biblatex entry type 5865 unpublished without an eventtitle field (this entry type 5866 will be mapped to CSL manuscript). 5867 5868 For a talk, an unpublished conference paper, or a poster 5869 presentation, use the biblatex entry type unpublished with an 5870 eventtitle field (this entry type will be mapped to CSL 5871 speech). Use the biblatex type field to indicate the type, 5872 e.g. "Paper", or "Poster". venue and eventdate may be useful 5873 too, though eventdate will not be rendered by most CSL styles. 5874 Note that venue is for the event's venue, unlike location 5875 which describes the publisher's location; do not use the latter 5876 for an unpublished conference paper. 5877 5878 5879 ## Specifying a citation style 5880 5881 Citations and references can be formatted using any style supported by the 5882 [Citation Style Language], listed in the [Zotero Style Repository]. 5883 These files are specified using the --csl option or the csl 5884 (or citation-style) metadata field. By default, pandoc will 5885 use the [Chicago Manual of Style] author-date format. (You can 5886 override this default by copying a CSL style of your choice 5887 to default.csl in your user data directory.) 5888 The CSL project provides further information on [finding and 5889 editing styles]. 5890 5891 The --citation-abbreviations option (or the 5892 citation-abbreviations metadata field) may be used to specify 5893 a JSON file containing abbreviations of journals that should be 5894 used in formatted bibliographies when form="short" is 5895 specified. The format of the file can be illustrated with an 5896 example: 5897 5898 5899 { "default": { 5900 "container-title": { 5901 "Lloyd's Law Reports": "Lloyd's Rep", 5902 "Estates Gazette": "EG", 5903 "Scots Law Times": "SLT" 5904 } 5905 } 5906 } 5907 5908 5909 ## Citations in note styles 5910 5911 Pandoc's citation processing is designed to allow you to 5912 move between author-date, numerical, and note styles without 5913 modifying the markdown source. When you're using a note 5914 style, avoid inserting footnotes manually. Instead, insert 5915 citations just as you would in an author-date style---for 5916 example, 5917 5918 Blah blah [@foo, p. 33]. 5919 5920 The footnote will be created automatically. Pandoc will take 5921 care of removing the space and moving the note before or 5922 after the period, depending on the setting of 5923 notes-after-punctuation, as described below in [Other relevant 5924 metadata fields]. 5925 5926 In some cases you may need to put a citation inside a regular 5927 footnote. Normal citations in footnotes (such as [@foo, p. 5928 33]) will be rendered in parentheses. In-text citations (such 5929 as @foo [p. 33]) will be rendered without parentheses. (A 5930 comma will be added if appropriate.) Thus: 5931 5932 [^1]: Some studies [@foo; @bar, p. 33] show that 5933 frubulicious zoosnaps are quantical. For a survey 5934 of the literature, see @baz [chap. 1]. 5935 5936 ## Raw content in a style 5937 5938 To include raw content in a prefix, suffix, delimiter, or term, 5939 surround it with these tags indicating the format: 5940 5941 {{jats}}&lt;ref&gt;{{/jats}} 5942 5943 Without the tags, the string will be interpreted as a string 5944 and escaped in the output, rather than being passed through raw. 5945 5946 This feature allows stylesheets to be customized to give 5947 different output for different output formats. However, 5948 stylesheets customized in this way will not be usable 5949 by other CSL implementations. 5950 5951 5952 5953 ## Placement of the bibliography 5954 5955 If the style calls for a list of works cited, it will be placed 5956 in a div with id refs, if one exists: 5957 5958 ::: {#refs} 5959 ::: 5960 5961 Otherwise, it will be placed at the end of the document. 5962 Generation of the bibliography can be suppressed by setting 5963 suppress-bibliography: true in the YAML metadata. 5964 5965 If you wish the bibliography to have a section heading, you can 5966 set reference-section-title in the metadata, or put the heading 5967 at the beginning of the div with id refs (if you are using it) 5968 or at the end of your document: 5969 5970 last paragraph... 5971 5972 # References 5973 5974 The bibliography will be inserted after this heading. Note that 5975 the unnumbered class will be added to this heading, so that the 5976 section will not be numbered. 5977 5978 If you want to put the bibliography into a variable in your 5979 template, one way to do that is to put the div with id refs 5980 into a metadata field, e.g. 5981 5982 --- 5983 refs: | 5984 ::: {#refs} 5985 ::: 5986 ... 5987 5988 You can then put the variable $refs$ into your template where 5989 you want the bibliography to be placed. 5990 5991 ## Including uncited items in the bibliography 5992 5993 If you want to include items in the bibliography without actually 5994 citing them in the body text, you can define a dummy nocite metadata 5995 field and put the citations there: 5996 5997 --- 5998 nocite: | 5999 @item1, @item2 6000 ... 6001 6002 @item3 6003 6004 In this example, the document will contain a citation for item3 6005 only, but the bibliography will contain entries for item1, item2, and 6006 item3. 6007 6008 It is possible to create a bibliography with all the citations, 6009 whether or not they appear in the document, by using a wildcard: 6010 6011 --- 6012 nocite: | 6013 @* 6014 ... 6015 6016 For LaTeX output, you can also use [natbib] or [biblatex] to 6017 render the bibliography. In order to do so, specify bibliography 6018 files as outlined above, and add --natbib or --biblatex 6019 argument to pandoc invocation. Bear in mind that bibliography 6020 files have to be in either BibTeX (for --natbib) 6021 or BibLaTeX (for --biblatex) format. 6022 6023 ## Other relevant metadata fields 6024 6025 A few other metadata fields affect bibliography formatting: 6026 6027 link-citations 6028 : If true, citations will be hyperlinked to the 6029 corresponding bibliography entries (for author-date and 6030 numerical styles only). Defaults to false. 6031 6032 link-bibliography 6033 : If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will 6034 be rendered as hyperlinks. (If an entry contains a DOI, PMCID, 6035 PMID, or URL, but none of these fields are rendered by the style, 6036 then the title, or in the absence of a title the whole entry, will 6037 be hyperlinked.) Defaults to true. 6038 6039 lang 6040 : The lang field will affect how the style is localized, 6041 for example in the translation of labels, the use 6042 of quotation marks, and the way items are sorted. 6043 (For backwards compatibility, locale may be used instead 6044 of lang, but this use is deprecated.) 6045 6046 A BCP 47 language tag is expected: for example, en, 6047 de, en-US, fr-CA, ug-Cyrl. The unicode extension 6048 syntax (after -u-) may be used to specify options for 6049 collation (sorting) more precisely. Here are some examples: 6050 6051 - zh-u-co-pinyin -- Chinese with the Pinyin collation. 6052 - es-u-co-trad -- Spanish with the traditional collation 6053 (with Ch sorting after C). 6054 - fr-u-kb -- French with "backwards" accent sorting 6055 (with coté sorting after côte). 6056 - en-US-u-kf-upper -- English with uppercase letters sorting 6057 before lower (default is lower before upper). 6058 6059 notes-after-punctuation 6060 : If true (the default for note styles), pandoc will put 6061 footnote references or superscripted numerical citations 6062 after following punctuation. For example, if the source 6063 contains blah blah [@jones99]., the result will look like 6064 blah blah.[^1], with the note moved after the period and 6065 the space collapsed. If false, the space will still be 6066 collapsed, but the footnote will not be moved after the 6067 punctuation. The option may also be used in numerical styles 6068 that use superscripts for citation numbers (but for these 6069 styles the default is not to move the citation). 6070 6071 6072 # Slide shows 6073 6074 You can use pandoc to produce an HTML + JavaScript slide presentation 6075 that can be viewed via a web browser. There are five ways to do this, 6076 using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js]. 6077 You can also produce a PDF slide show using LaTeX [beamer], or 6078 slides shows in Microsoft [PowerPoint] format. 6079 6080 Here's the Markdown source for a simple slide show, habits.txt: 6081 6082 % Habits 6083 % John Doe 6084 % March 22, 2005 6085 6086 # In the morning 6087 6088 ## Getting up 6089 6090 - Turn off alarm 6091 - Get out of bed 6092 6093 ## Breakfast 6094 6095 - Eat eggs 6096 - Drink coffee 6097 6098 # In the evening 6099 6100 ## Dinner 6101 6102 - Eat spaghetti 6103 - Drink wine 6104 6105 ------------------ 6106 6107 ![picture of spaghetti](images/spaghetti.jpg) 6108 6109 ## Going to sleep 6110 6111 - Get in bed 6112 - Count sheep 6113 6114 To produce an HTML/JavaScript slide show, simply type 6115 6116 pandoc -t FORMAT -s habits.txt -o habits.html 6117 6118 where FORMAT is either s5, slidy, slideous, dzslides, or revealjs. 6119 6120 For Slidy, Slideous, reveal.js, and S5, the file produced by 6121 pandoc with the -s/--standalone option embeds a link to 6122 JavaScript and CSS files, which are assumed to be available at 6123 the relative path s5/default (for S5), slideous (for 6124 Slideous), reveal.js (for reveal.js), or at the Slidy website 6125 at w3.org (for Slidy). (These paths can be changed by setting 6126 the slidy-url, slideous-url, revealjs-url, or s5-url 6127 variables; see [Variables for HTML slides], above.) For 6128 DZSlides, the (relatively short) JavaScript and CSS are included 6129 in the file by default. 6130 6131 With all HTML slide formats, the --self-contained option can 6132 be used to produce a single file that contains all of the data 6133 necessary to display the slide show, including linked scripts, 6134 stylesheets, images, and videos. 6135 6136 To produce a PDF slide show using beamer, type 6137 6138 pandoc -t beamer habits.txt -o habits.pdf 6139 6140 Note that a reveal.js slide show can also be converted to a PDF 6141 by printing it to a file from the browser. 6142 6143 To produce a Powerpoint slide show, type 6144 6145 pandoc habits.txt -o habits.pptx 6146 6147 ## Structuring the slide show 6148 6149 By default, the *slide level* is the highest heading level in 6150 the hierarchy that is followed immediately by content, and not another 6151 heading, somewhere in the document. In the example above, level-1 headings 6152 are always followed by level-2 headings, which are followed by content, 6153 so the slide level is 2. This default can be overridden using the 6154 --slide-level option. 6155 6156 The document is carved up into slides according to the following 6157 rules: 6158 6159 * A horizontal rule always starts a new slide. 6160 6161 * A heading at the slide level always starts a new slide. 6162 6163 * Headings *below* the slide level in the hierarchy create 6164 headings *within* a slide. (In beamer, a "block" will be 6165 created. If the heading has the class example, an 6166 exampleblock environment will be used; if it has the class 6167 alert, an alertblock will be used; otherwise a regular 6168 block will be used.) 6169 6170 * Headings *above* the slide level in the hierarchy create 6171 "title slides," which just contain the section title 6172 and help to break the slide show into sections. 6173 Non-slide content under these headings will be included 6174 on the title slide (for HTML slide shows) or in a 6175 subsequent slide with the same title (for beamer). 6176 6177 * A title page is constructed automatically from the document's title 6178 block, if present. (In the case of beamer, this can be disabled 6179 by commenting out some lines in the default template.) 6180 6181 These rules are designed to support many different styles of slide show. If 6182 you don't care about structuring your slides into sections and subsections, 6183 you can either just use level-1 headings for all slides (in that case, level 1 6184 will be the slide level) or you can set --slide-level=0. 6185 6186 Note: in reveal.js slide shows, if slide level is 2, a two-dimensional 6187 layout will be produced, with level-1 headings building horizontally 6188 and level-2 headings building vertically. It is not recommended that 6189 you use deeper nesting of section levels with reveal.js unless you set 6190 --slide-level=0 (which lets reveal.js produce a one-dimensional layout 6191 and only interprets horizontal rules as slide boundaries). 6192 6193 ### PowerPoint layout choice 6194 6195 When creating slides, the pptx writer chooses from a number of pre-defined 6196 layouts, based on the content of the slide: 6197 6198 Title Slide 6199 : This layout is used for the initial slide, which is generated and 6200 filled from the metadata fields date, author, and title, if 6201 they are present. 6202 6203 Section Header 6204 : This layout is used for what pandoc calls “title slides”, i.e. 6205 slides which start with a header which is above the slide level in 6206 the hierarchy. 6207 6208 Two Content 6209 : This layout is used for two-column slides, i.e. slides containing a 6210 div with class columns which contains at least two divs with class 6211 column. 6212 6213 Comparison 6214 : This layout is used instead of “Two Content” for any two-column 6215 slides in which at least one column contains text followed by 6216 non-text (e.g. an image or a table). 6217 6218 Content with Caption 6219 : This layout is used for any non-two-column slides which contain text 6220 followed by non-text (e.g. an image or a table). 6221 6222 Blank 6223 : This layout is used for any slides which only contain blank content, 6224 e.g. a slide containing only speaker notes, or a slide containing 6225 only a non-breaking space. 6226 6227 Title and Content 6228 : This layout is used for all slides which do not match the criteria 6229 for another layout. 6230 6231 These layouts are chosen from the default pptx reference doc included with 6232 pandoc, unless an alternative reference doc is specified using 6233 --reference-doc. 6234 6235 ## Incremental lists 6236 6237 By default, these writers produce lists that display "all at once." 6238 If you want your lists to display incrementally (one item at a time), 6239 use the -i option. If you want a particular list to depart from the 6240 default, put it in a div block with class incremental or 6241 nonincremental. So, for example, using the fenced div syntax, the 6242 following would be incremental regardless of the document default: 6243 6244 ::: incremental 6245 6246 - Eat spaghetti 6247 - Drink wine 6248 6249 ::: 6250 6251 or 6252 6253 ::: nonincremental 6254 6255 - Eat spaghetti 6256 - Drink wine 6257 6258 ::: 6259 6260 While using incremental and nonincremental divs are the 6261 recommended method of setting incremental lists on a per-case basis, 6262 an older method is also supported: putting lists inside a blockquote 6263 will depart from the document default (that is, it will display 6264 incrementally without the -i option and all at once with the -i 6265 option): 6266 6267 > - Eat spaghetti 6268 > - Drink wine 6269 6270 Both methods allow incremental and nonincremental lists to be mixed 6271 in a single document. 6272 6273 If you want to include a block-quoted list, you can work around 6274 this behavior by putting the list inside a fenced div, so that 6275 it is not the direct child of the block quote: 6276 6277 > ::: wrapper 6278 > - a 6279 > - list in a quote 6280 > ::: 6281 6282 ## Inserting pauses 6283 6284 You can add "pauses" within a slide by including a paragraph containing 6285 three dots, separated by spaces: 6286 6287 # Slide with a pause 6288 6289 content before the pause 6290 6291 . . . 6292 6293 content after the pause 6294 6295 Note: this feature is not yet implemented for PowerPoint output. 6296 6297 ## Styling the slides 6298 6299 You can change the style of HTML slides by putting customized CSS files 6300 in $DATADIR/s5/default (for S5), $DATADIR/slidy (for Slidy), 6301 or $DATADIR/slideous (for Slideous),
6302 where $DATADIR is the user data directory (see --data-dir, above). 6303 The originals may be found in pandoc's system data directory (generally 6304 $CABALDIR/pandoc-VERSION/s5/default). Pandoc will look there for any
6305 files it does not find in the user data directory.
6306
6307 For dzslides, the CSS is included in the HTML file itself, and may
6308 be modified there.
6309
6310 All [reveal.js configuration options] can be set through variables.
6311 For example, themes can be used by setting the theme variable:
6312
6313     -V theme=moon
6314
6315 Or you can specify a custom stylesheet using the --css option.
6316
6317 To style beamer slides, you can specify a theme, colortheme,
6318 fonttheme, innertheme, and outertheme, using the -V option:
6319
6320     pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
6321
6322 Note that heading attributes will turn into slide attributes
6323 (on a <div> or <section>) in HTML slide formats, allowing you
6324 to style individual slides.  In beamer, a number of heading
6325 classes and attributes are recognized as frame options and
6326 will be passed through as options to the frame: see
6327 [Frame attributes in beamer], below.
6328
6329 ## Speaker notes
6330
6331 Speaker notes are supported in reveal.js, PowerPoint (pptx),
6332 and beamer output. You can add notes to your Markdown document thus:
6333
6334     ::: notes
6335
6336     This is my note.
6337
6338     - It can contain Markdown
6339     - like this list
6340
6341     :::
6342
6343 To show the notes window in reveal.js, press s while viewing the
6344 presentation. Speaker notes in PowerPoint will be available, as usual,
6345 in handouts and presenter view.
6346
6347 Notes are not yet supported for other slide formats, but the notes
6348 will not appear on the slides themselves.
6349
6350 ## Columns
6351
6352 To put material in side by side columns, you can use a native
6353 div container with class columns, containing two or more div
6354 containers with class column and a width attribute:
6355
6356     :::::::::::::: {.columns}
6357     ::: {.column width="40%"}
6358     contents...
6359     :::
6360     ::: {.column width="60%"}
6361     contents...
6362     :::
6363     ::::::::::::::
6364
6365 ### Additional columns attributes in beamer
6366
6367 The div containers with classes columns and column can optionally have
6368 an align attribute.
6369 The class columns can optionally have a totalwidth attribute or an
6370 onlytextwidth class.
6371
6372     :::::::::::::: {.columns align=center totalwidth=8em}
6373     ::: {.column width="40%"}
6374     contents...
6375     :::
6376     ::: {.column width="60%" align=bottom}
6377     contents...
6378     :::
6379     ::::::::::::::
6380
6381 The align attributes on columns and column can be used with the
6382 values top, top-baseline, center and bottom to vertically align
6383 the columns. It defaults to top in columns.
6384
6385 The totalwidth attribute limits the width of the columns to the given value.
6386
6387     :::::::::::::: {.columns align=top .onlytextwidth}
6388     ::: {.column width="40%" align=center}
6389     contents...
6390     :::
6391     ::: {.column width="60%"}
6392     contents...
6393     :::
6394     ::::::::::::::
6395
6396 The class onlytextwidth sets the totalwidth to \textwidth.
6397
6398 See Section 12.7 of the [Beamer User's Guide] for more details.
6399
6400 ## Frame attributes in beamer
6401
6402 Sometimes it is necessary to add the LaTeX [fragile] option to
6403 a frame in beamer (for example, when using the minted environment).
6404 This can be forced by adding the fragile class to the heading
6405 introducing the slide:
6406
6407     # Fragile slide {.fragile}
6408
6409 All of the other frame attributes described in Section 8.1 of
6410 the [Beamer User's Guide] may also be used: allowdisplaybreaks,
6411 allowframebreaks, b, c, s, t, environment, label, plain,
6412 shrink, standout, noframenumbering, squeeze.
6413 allowframebreaks is recommended especially for bibliographies, as
6414 it allows multiple slides to be created if the content overfills the
6415 frame:
6416
6417     # References {.allowframebreaks}
6418
6419 In addition, the frameoptions attribute may be used to
6420 pass arbitrary frame options to a beamer slide:
6421
6423
6424 ## Background in reveal.js, beamer, and pptx
6425
6426 Background images can be added to self-contained reveal.js slide shows,
6427 beamer slide shows, and pptx slide shows.
6428
6429 ### On all slides (beamer, reveal.js, pptx)
6430
6431 With beamer and reveal.js, the configuration option background-image can be
6432 used either in the YAML metadata block or as a command-line variable to get the
6433 same image on every slide.
6434
6435 For pptx, you can use a [reference doc](#option--reference-doc) in which
6436 background images have been set on the [relevant
6437 layouts](#powerpoint-layout-choice).
6438
6439 #### parallaxBackgroundImage (reveal.js)
6440
6441 For reveal.js, there is also the reveal.js-native option
6442 parallaxBackgroundImage, which can be used instead of background-image to
6443 produce a parallax scrolling background. You must also set
6444 parallaxBackgroundSize, and can optionally set parallaxBackgroundHorizontal
6445 and parallaxBackgroundVertical to configure the scrolling behaviour. See the
6446 [reveal.js documentation](https://revealjs.com/backgrounds/#parallax-background)
6447 for more details about the meaning of these options.
6448
6449 In reveal.js's overview mode, the parallaxBackgroundImage will show up
6450 only on the first slide.
6451
6452 ### On individual slides (reveal.js, pptx)
6453
6454 To set an image for a particular reveal.js or pptx slide, add
6455 {background-image="/path/to/image"} to the first slide-level heading on the
6456 slide (which may even be empty).
6457
6458 As the [HTML writers pass unknown attributes
6459 through](#extension-link_attributes), other reveal.js background settings also
6460 work on individual slides, including background-size, background-repeat,
6461 background-color, transition, and transition-speed. (The data- prefix
6463
6464 Note: data-background-image is also supported in pptx for consistency with
6465 reveal.js – if background-image isn’t found, data-background-image will be
6466 checked.
6467
6468 ### On the title slide (reveal.js, pptx)
6469
6470 To add a background image to the automatically generated title slide for
6471 reveal.js, use the title-slide-attributes variable in the YAML metadata block.
6472 It must contain a map of attribute names and values. (Note that the data-
6473 prefix is required here, as it isn’t added automatically.)
6474
6475 For pptx, pass a [reference doc](#option--reference-doc) with the background
6476 image set on the “Title Slide” layout.
6477
6478 ### Example (reveal.js)
6479
6480 
6481 ---
6482 title: My Slide Show
6483 parallaxBackgroundImage: /path/to/my/background_image.png
6484 title-slide-attributes:
6485     data-background-image: /path/to/title_image.png
6486     data-background-size: contain
6487 ---
6488
6489 ## Slide One
6490
6491 Slide 1 has background_image.png as its background.
6492
6493 ## {background-image="/path/to/special_image.jpg"}
6494
6495 Slide 2 has a special image for its background, even though the heading has no content.
6496 
6497
6498 # EPUBs
6499
6501
6502 EPUB metadata may be specified using the --epub-metadata option, but
6503 if the source document is Markdown, it is better to use a [YAML metadata
6504 block][Extension: yaml_metadata_block].  Here is an example:
6505
6506     ---
6507     title:
6508     - type: main
6509       text: My Book
6510     - type: subtitle
6511       text: An investigation of metadata
6512     creator:
6513     - role: author
6514       text: John Smith
6515     - role: editor
6516       text: Sarah Jones
6517     identifier:
6518     - scheme: DOI
6519       text: doi:10.234234.234/33
6520     publisher:  My Press
6521     rights: © 2007 John Smith, CC BY-NC
6522     ibooks:
6523       version: 1.3.4
6524     ...
6525
6526 The following fields are recognized:
6527
6528 identifier
6529   ~ Either a string value or an object with fields text and
6530     scheme.  Valid values for scheme are ISBN-10,
6531     GTIN-13, UPC, ISMN-10, DOI, LCCN, GTIN-14,
6532     ISBN-13, Legal deposit number, URN, OCLC,
6533     ISMN-13, ISBN-A, JP, OLCC.
6534
6535 title
6536   ~ Either a string value, or an object with fields file-as and
6537     type, or a list of such objects.  Valid values for type are
6538     main, subtitle, short, collection, edition, extended.
6539
6540 creator
6541   ~ Either a string value, or an object with fields role, file-as,
6542     and text, or a list of such objects.  Valid values for role are
6543     [MARC relators], but
6544     pandoc will attempt to translate the human-readable versions
6545     (like "author" and "editor") to the appropriate marc relators.
6546
6547 contributor
6548   ~ Same format as creator.
6549
6550 date
6551   ~ A string value in YYYY-MM-DD format.  (Only the year is necessary.)
6552     Pandoc will attempt to convert other common date formats.
6553
6554 lang (or legacy: language)
6555   ~ A string value in [BCP 47] format.  Pandoc will default to the local
6556     language if nothing is specified.
6557
6558 subject
6559   ~ Either a string value, or an object with fields text, authority,
6560     and term, or a list of such objects. Valid values for authority
6561     are either a [reserved authority value] (currently AAT, BIC,
6562     BISAC, CLC, DDC, CLIL, EuroVoc, MEDTOP, LCSH, NDC,
6563     Thema, UDC, and WGS) or an absolute IRI identifying a custom
6564     scheme. Valid values for term are defined by the scheme.
6565
6566 description
6567   ~ A string value.
6568
6569 type
6570   ~ A string value.
6571
6572 format
6573   ~ A string value.
6574
6575 relation
6576   ~ A string value.
6577
6578 coverage
6579   ~ A string value.
6580
6581 rights
6582   ~ A string value.
6583
6584 belongs-to-collection
6585   ~ A string value.  identifies the name of a collection to which
6586     the EPUB Publication belongs.
6587
6588 group-position
6589   ~ The group-position field indicates the numeric position in which
6590     the EPUB Publication belongs relative to other works belonging to
6591     the same belongs-to-collection field.
6592
6593 cover-image
6594   ~ A string value (path to cover image).
6595
6596 css (or legacy: stylesheet)
6597   ~ A string value (path to CSS stylesheet).
6598
6599 page-progression-direction
6600   ~ Either ltr or rtl. Specifies the page-progression-direction
6601     attribute for the [spine element].
6602
6603 ibooks
6604   ~ iBooks-specific metadata, with the following fields:
6605
6606     - version: (string)
6607     - specified-fonts: true|false (default false)
6608     - ipad-orientation-lock: portrait-only|landscape-only
6609     - iphone-orientation-lock: portrait-only|landscape-only
6610     - binding: true|false (default true)
6611     - scroll-axis: vertical|horizontal|default
6612
6613 [MARC relators]: https://loc.gov/marc/relators/relaterm.html
6614 [reserved authority value]: https://idpf.github.io/epub-registries/authorities/
6615 [spine element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
6616
6617 ## The epub:type attribute
6618
6619 For epub3 output, you can mark up the heading that corresponds to an EPUB
6620 chapter using the [epub:type attribute][epub-type]. For example, to set
6621 the attribute to the value prologue, use this markdown:
6622
6623     # My chapter {epub:type=prologue}
6624
6625 Which will result in:
6626
6627     <body epub:type="frontmatter">
6628       <section epub:type="prologue">
6629         <h1>My chapter</h1>
6630
6631 Pandoc will output <body epub:type="bodymatter">, unless
6632 you use one of the following values, in which case either
6633 frontmatter or backmatter will be output.
6634
6635 epub:type of first section      epub:type of body
6636 ----------------------------      ------------------
6637 prologue                          frontmatter
6638 abstract                          frontmatter
6639 acknowledgments                   frontmatter
6641 dedication                        frontmatter
6642 credits                           frontmatter
6643 keywords                          frontmatter
6644 imprint                           frontmatter
6645 contributors                      frontmatter
6646 other-credits                     frontmatter
6647 errata                            frontmatter
6648 revision-history                  frontmatter
6649 titlepage                         frontmatter
6650 halftitlepage                     frontmatter
6651 seriespage                        frontmatter
6652 foreword                          frontmatter
6653 preface                           frontmatter
6654 frontispiece                      frontmatter
6655 appendix                          backmatter
6656 colophon                          backmatter
6657 bibliography                      backmatter
6658 index                             backmatter
6659
6660 [epub-type]: http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-epub-type-attribute
6661
6663
6664 By default, pandoc will download media referenced from any <img>, <audio>,
6665 <video> or <source> element present in the generated EPUB,
6666 and include it in the EPUB container, yielding a completely
6667 self-contained EPUB.  If you want to link to external media resources
6668 instead, use raw HTML in your source and add data-external="1" to the tag
6669 with the src attribute.  For example:
6670
6671     <audio controls="1">
6672       <source src="https://example.com/music/toccata.mp3"
6673               data-external="1" type="audio/mpeg">
6674       </source>
6675     </audio>
6676
6677 If the input format already is HTML then data-external="1" will work
6678 as expected for <img> elements. Similarly, for Markdown, external
6679 images can be declared with ![img](url){external=1}. Note that this
6680 only works for images; the other media elements have no native
6681 representation in pandoc's AST and requires the use of raw HTML.
6682
6683 ## EPUB styling
6684
6685 By default, pandoc will include some basic styling
6686 contained in its epub.css data file.  (To see this,
6687 use pandoc --print-default-data-file epub.css.)
6688 To use a different CSS file, just use the --css command
6689 line option.  A few inline styles are defined in addition; these
6690 are essential for correct formatting of pandoc's HTML output.
6691
6692 The document-css variable may be set if the more opinionated
6693 styling of pandoc's default HTML templates is desired (and
6694 in that case the variables defined in [Variables for HTML] may
6695 be used to fine-tune the style).
6696
6697 # Jupyter notebooks
6698
6699 When creating a [Jupyter notebook], pandoc will try to infer the
6700 notebook structure.  Code blocks with the class code will be
6701 taken as code cells, and intervening content will be taken as
6702 Markdown cells.  Attachments will automatically be created for
6703 images in Markdown cells. Metadata will be taken from the
6704 jupyter metadata field.  For example:
6705
6706 
6707 ---
6708 title: My notebook
6709 jupyter:
6710   nbformat: 4
6711   nbformat_minor: 5
6712   kernelspec:
6713      display_name: Python 2
6714      language: python
6715      name: python2
6716   language_info:
6717      codemirror_mode:
6718        name: ipython
6719        version: 2
6720      file_extension: ".py"
6721      mimetype: "text/x-python"
6722      name: "python"
6723      nbconvert_exporter: "python"
6724      pygments_lexer: "ipython2"
6725      version: "2.7.15"
6726 ---
6727
6728 # Lorem ipsum
6729
6730 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6731 bibendum felis dictum sodales.
6732
6733  code
6734 print("hello")
6735 
6736
6737 ## Pyout
6738
6739  code
6740 from IPython.display import HTML
6741 HTML("""
6742 <script>
6743 console.log("hello");
6744 </script>
6745 <b>HTML</b>
6746 """)
6747 
6748
6749 ## Image
6750
6751 This image ![image](myimage.png) will be
6752 included as a cell attachment.
6753 
6754
6755 If you want to add cell attributes, group cells differently, or
6756 add output to code cells, then you need to include divs to
6757 indicate the structure. You can use either [fenced
6758 divs][Extension: fenced_divs] or [native divs][Extension:
6759 native_divs] for this.  Here is an example:
6760
6761 
6762 :::::: {.cell .markdown}
6763 # Lorem
6764
6765 **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6766 bibendum felis dictum sodales.
6767 ::::::
6768
6769 :::::: {.cell .code execution_count=1}
6770  {.python}
6771 print("hello")
6772 
6773
6774 ::: {.output .stream .stdout}
6775 
6776 hello
6777 
6778 :::
6779 ::::::
6780
6781 :::::: {.cell .code execution_count=2}
6782  {.python}
6783 from IPython.display import HTML
6784 HTML("""
6785 <script>
6786 console.log("hello");
6787 </script>
6788 <b>HTML</b>
6789 """)
6790 
6791
6792 ::: {.output .execute_result execution_count=2}
6793 {=html}
6794 <script>
6795 console.log("hello");
6796 </script>
6797 <b>HTML</b>
6798 hello
6799 
6800 :::
6801 ::::::
6802 
6803
6804 If you include raw HTML or TeX in an output cell, use the
6805 [raw attribute][Extension: fenced_attribute], as shown
6806 in the last cell of the example above.  Although pandoc can
6807 process "bare" raw HTML and TeX, the result is often
6808 interspersed raw elements and normal textual elements, and
6809 in an output cell pandoc expects a single, connected raw
6810 block.  To avoid using raw HTML or TeX except when
6811 marked explicitly using raw attributes, we recommend
6812 specifying the extensions -raw_html-raw_tex+raw_attribute when
6813 translating between Markdown and ipynb notebooks.
6814
6815 Note that options and extensions that affect reading and
6816 writing of Markdown will also affect Markdown cells in ipynb
6817 notebooks.  For example, --wrap=preserve will preserve
6818 soft line breaks in Markdown cells; --atx-headers will
6819 cause ATX-style headings to be used; and --preserve-tabs will
6820 prevent tabs from being turned to spaces.
6821
6822 # Syntax highlighting
6823
6824 Pandoc will automatically highlight syntax in [fenced code blocks] that
6825 are marked with a language name.  The Haskell library [skylighting] is
6826 used for highlighting. Currently highlighting is supported only for
6827 HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language names
6828 that pandoc will recognize, type pandoc --list-highlight-languages.
6829
6830 The color scheme can be selected using the --highlight-style option.
6831 The default color scheme is pygments, which imitates the default color
6832 scheme used by the Python library pygments (though pygments is not actually
6833 used to do the highlighting).  To see a list of highlight styles,
6834 type pandoc --list-highlight-styles.
6835
6836 If you are not satisfied with the predefined styles, you can
6837 use --print-highlight-style to generate a JSON .theme file which
6838 can be modified and used as the argument to --highlight-style. To
6839 get a JSON version of the pygments style, for example:
6840
6841     pandoc --print-highlight-style pygments > my.theme
6842
6843 Then edit my.theme and use it like this:
6844
6845     pandoc --highlight-style my.theme
6846
6847 If you are not satisfied with the built-in highlighting, or you
6848 want highlight a language that isn't supported, you can use the
6849 --syntax-definition option to load a [KDE-style XML syntax definition
6850 file](https://docs.kde.org/stable5/en/kate/katepart/highlight.html).
6851 Before writing your own, have a look at KDE's [repository of syntax
6852 definitions](https://github.com/KDE/syntax-highlighting/tree/master/data/syntax).
6853
6854 To disable highlighting, use the --no-highlight option.
6855
6856 [skylighting]: https://github.com/jgm/skylighting
6857
6858 # Custom Styles
6859
6860 Custom styles can be used in the docx and ICML formats.
6861
6862 ## Output
6863
6864 By default, pandoc's docx and ICML output applies a predefined set of styles
6865 for blocks such as paragraphs and block quotes, and uses largely default
6866 formatting (italics, bold) for inlines. This will work for most
6867 purposes, especially alongside a reference.docx file. However, if you
6868 need to apply your own styles to blocks, or match a preexisting set of
6869 styles, pandoc allows you to define custom styles for blocks and text
6870 using divs and spans, respectively.
6871
6872 If you define a div or span with the attribute custom-style,
6873 pandoc will apply your specified style to the contained elements (with
6874 the exception of elements whose function depends on a style, like
6875 headings, code blocks, block quotes, or links). So, for example, using
6876 the bracketed_spans syntax,
6877
6878     [Get out]{custom-style="Emphatically"}, he said.
6879
6880 would produce a docx file with "Get out" styled with character
6881 style Emphatically. Similarly, using the fenced_divs syntax,
6882
6883     Dickinson starts the poem simply:
6884
6885     ::: {custom-style="Poetry"}
6886     | A Bird came down the Walk---
6887     | He did not know I saw---
6888     :::
6889
6890 would style the two contained lines with the Poetry paragraph style.
6891
6892 For docx output, styles will be defined in the output file as inheriting
6893 from normal text, if the styles are not yet in your reference.docx.
6894 If they are already defined, pandoc will not alter the definition.
6895
6896 This feature allows for greatest customization in conjunction with
6897 [pandoc filters]. If you want all paragraphs after block quotes to be
6898 indented, you can write a filter to apply the styles necessary. If you
6899 want all italics to be transformed to the Emphasis character style
6900 (perhaps to change their color), you can write a filter which will
6901 transform all italicized inlines to inlines within an Emphasis
6902 custom-style span.
6903
6904 For docx output, you don't need to enable any extensions for
6905 custom styles to work.
6906
6907 [pandoc filters]: https://pandoc.org/filters.html
6908
6909 ## Input
6910
6911 The docx reader, by default, only reads those styles that it can
6912 convert into pandoc elements, either by direct conversion or
6913 interpreting the derivation of the input document's styles.
6914
6915 By enabling the [styles extension](#ext-styles) in the docx reader
6916 (-f docx+styles), you can produce output that maintains the styles
6917 of the input document, using the custom-style class. Paragraph
6918 styles are interpreted as divs, while character styles are interpreted
6919 as spans.
6920
6921 For example, using the custom-style-reference.docx file in the test
6922 directory, we have the following different outputs:
6923
6924 Without the +styles extension:
6925
6926     $pandoc test/docx/custom-style-reference.docx -f docx -t markdown 6927 This is some text. 6928 6929 This is text with an *emphasized* text style. And this is text with a 6930 **strengthened** text style. 6931 6932 > Here is a styled paragraph that inherits from Block Text. 6933 6934 And with the extension: 6935 6936$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
6937
6938     ::: {custom-style="First Paragraph"}
6939     This is some text.
6940     :::
6941
6942     ::: {custom-style="Body Text"}
6943     This is text with an [emphasized]{custom-style="Emphatic"} text style.
6944     And this is text with a [strengthened]{custom-style="Strengthened"}
6945     text style.
6946     :::
6947
6948     ::: {custom-style="My Block Style"}
6949     > Here is a styled paragraph that inherits from Block Text.
6950     :::
6951
6952 With these custom styles, you can use your input document as a
6953 reference-doc while creating docx output (see below), and maintain the
6954 same styles in your input and output files.
6955
6956 # Custom readers and writers
6957
6958 Pandoc can be extended with custom readers and writers written
6959 in [Lua].  (Pandoc includes a Lua interpreter, so Lua need not
6960 be installed separately.)
6961
6962 To use a custom reader or writer, simply specify the path to the
6963 Lua script in place of the input or output format. For example:
6964
6965     pandoc -t data/sample.lua
6966     pandoc -f my_custom_markup_language.lua -t latex -s
6967
6968 A custom reader is a Lua script that defines one function,
6969 Reader, which takes a string as input and returns a Pandoc
6970 AST.  See the [Lua filters documentation] for documentation
6971 of the functions that are available for creating pandoc
6972 AST elements.  For parsing, the [lpeg] parsing library
6973 is available by default. To see a sample custom reader:
6974
6975     pandoc --print-default-data-file creole.lua
6976
6978 (e.g. the tab stop setting), you give your Reader function a
6979 second options parameter.
6980
6981 A custom writer is a Lua script that defines a function
6982 that specifies how to render each element in a Pandoc AST.
6983 To see a documented example which you can modify according
6985
6986     pandoc --print-default-data-file sample.lua
6987
6988 Note that custom writers have no default template.  If you want
6989 to use --standalone with a custom writer, you will need to
6990 specify a template manually using --template or add a new
6991 default template with the name
6992 default.NAME_OF_CUSTOM_WRITER.lua to the templates
6993 subdirectory of your user data directory (see [Templates]).
6994
6995 [Lua]: https://www.lua.org
6996 [lpeg]:  http://www.inf.puc-rio.br/~roberto/lpeg/
6997
6998 # Reproducible builds
6999
7000 Some of the document formats pandoc targets (such as EPUB,
7001 docx, and ODT) include build timestamps in the generated document.
7002 That means that the files generated on successive builds will
7003 differ, even if the source does not.  To avoid this, set the
7004 SOURCE_DATE_EPOCH environment variable, and the timestamp will
7005 be taken from it instead of the current time.
7006 SOURCE_DATE_EPOCH should contain an integer unix timestamp
7007 (specifying the number of second since midnight UTC January 1, 1970).
7008
7009 Some document formats also include a unique identifier.  For
7010 EPUB, this can be set explicitly by setting the identifier
7012
7013 # A note on security
7014
7015 1. Although pandoc itself will not create or modify any files other
7016    than those you explicitly ask it create (with the exception
7017    of temporary files used in producing PDFs), a filter or custom
7018    writer could in principle do anything on your file system. Please
7019    audit filters and custom writers very carefully before using them.
7020
7021 2. Several input formats (including HTML, Org, and RST) support include
7022    directives that allow the contents of a file to be included in the
7023    output. An untrusted attacker could use these to view the contents of
7024    files on the file system.  (Using the --sandbox option can
7025    protect against this threat.)
7026
7027 3. Several output formats (including RTF, FB2, HTML with
7028    --self-contained, EPUB, Docx, and ODT) will embed encoded
7029    or raw images into the output file.  An untrusted attacker
7030    could exploit this to view the contents of non-image files on the
7031    file system.  (Using the --sandbox option can protect
7032    against this threat, but will also prevent including images in
7033    these formats.)
7034
7035 4. If your application uses pandoc as a Haskell library (rather than
7036    shelling out to the executable), it is possible to use it in a mode
7037    that fully isolates pandoc from your file system, by running the
7038    pandoc operations in the PandocPure monad. See the document
7039    [Using the pandoc API](https://pandoc.org/using-the-pandoc-api.html)
7040    for more details. (This corresponds to the use of the --sandbox
7041    option on the command line.)
7042
7043 5. Pandoc's parsers can exhibit pathological performance on some
7044    corner cases.  It is wise to put any pandoc operations under
7045    a timeout, to avoid DOS attacks that exploit these issues.
7046    If you are using the pandoc executable, you can add the
7047    command line options +RTS -M512M -RTS (for example) to limit
7048    the heap size to 512MB.  Note that the commonmark parser
7049    (including commonmark_x and gfm) is much less vulnerable
7050    to pathological performance than the markdown parser, so
7051    it is a better choice when processing untrusted input.
7052
7053 6. The HTML generated by pandoc is not guaranteed to be safe.
7054    If raw_html is enabled for the Markdown input, users can
7055    inject arbitrary HTML.  Even if raw_html is disabled,
7056    users can include dangerous content in URLs and attributes.
7057    To be safe, you should run all HTML generated from untrusted
7058    user input through an HTML sanitizer.
7059
7060 # Authors
7061
7062 Copyright 2006--2022 John MacFarlane (jgm@berkeley.edu). Released
7063 under the [GPL], version 2 or greater.  This software carries no
`