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