"Fossies" - the Fresh Open Source Software Archive

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


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

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