packages feed

pandoc 2.17.0.1 → 2.17.1

raw patch · 100 files changed

+11233/−8871 lines, 100 filesdep ~hsluadep ~hslua-aesondep ~hslua-marshallingbinary-addedPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependency ranges changed: hslua, hslua-aeson, hslua-marshalling, skylighting, skylighting-core

API changes (from Hackage documentation)

- Text.Pandoc.Writers.Custom: instance HsLua.Class.Peekable.PeekError e => HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify e Text.Pandoc.Definition.Citation)
- Text.Pandoc.Writers.Custom: instance HsLua.Class.Peekable.PeekError e => HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify e Text.Pandoc.Definition.MetaValue)
- Text.Pandoc.Writers.Custom: instance HsLua.Class.Peekable.PeekError e => HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify e [Text.Pandoc.Definition.Block])
- Text.Pandoc.Writers.Custom: instance HsLua.Class.Peekable.PeekError e => HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify e [Text.Pandoc.Definition.Inline])
- Text.Pandoc.Writers.Custom: instance HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify e Text.Pandoc.Definition.Format)
+ Text.Pandoc.Class: readMetadataFile :: PandocMonad m => FilePath -> m ByteString
+ Text.Pandoc.Error: PandocCouldNotFindMetadataFileError :: Text -> PandocError
+ Text.Pandoc.Writers.Custom: instance HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify Text.Pandoc.Definition.Citation)
+ Text.Pandoc.Writers.Custom: instance HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify Text.Pandoc.Definition.Format)
+ Text.Pandoc.Writers.Custom: instance HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify Text.Pandoc.Definition.MetaValue)
+ Text.Pandoc.Writers.Custom: instance HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify [Text.Pandoc.Definition.Block])
+ Text.Pandoc.Writers.Custom: instance HsLua.Class.Pushable.Pushable (Text.Pandoc.Writers.Custom.Stringify [Text.Pandoc.Definition.Inline])
+ Text.Pandoc.Writers.Custom: instance HsLua.Class.Pushable.Pushable Text.Pandoc.Writers.Custom.AttributeList

Files

AUTHORS.md view
@@ -35,6 +35,7 @@ - Beni Cherniavsky-Paskin - Benjamin Bray - Benoit Schweblin+- Benson Muite - Bjorn Buckwalter - Blake Eryx - Bodigrim@@ -46,6 +47,7 @@ - Caleb Mclennan - Calvin Beck - Carlos Sosa+- Carsten Allefeld - Cécile Chemin - Cédric Couralet - Charanjit Singh@@ -88,6 +90,7 @@ - Erik Rask - Ethan Riley - Étienne Bersac+- Even Brenden - Ezwal - Fabián Heredia Montiel - Félix Baylac-Jacqué@@ -217,6 +220,7 @@ - Nick Berendsen - Nick Fleisher - Nicolas Kaiser+- Nikolai Korobeinikov - Nikolay Yakimov - Nils Carlson - Nixon Enraght-Moony@@ -336,6 +340,7 @@ - oquechy - qerub - quasicomputational+- ricnorr - robabla - roblabla - rodja.trappe
MANUAL.txt view
@@ -1,7 +1,7 @@ --- title: Pandoc User's Guide author: John MacFarlane-date: January 14, 2022+date: January 30, 2022 ---  # Synopsis@@ -57,7 +57,7 @@ For more information on how standalone documents are produced, see [Templates] below. -If multiple input files are given, `pandoc` will concatenate them all (with+If multiple input files are given, pandoc will concatenate them all (with blank lines between them) before parsing. (Use `--file-scope` to parse files individually.) @@ -80,7 +80,7 @@ `pandoc --list-output-formats` to print lists of supported formats. -If the input or output format is not specified explicitly, `pandoc`+If the input or output format is not specified explicitly, pandoc will attempt to guess it from the extensions of the filenames. Thus, for example, @@ -383,7 +383,7 @@     be searched for first in the working directory, and then in     the `defaults` subdirectory of the user data directory     (see `--data-dir`).  The `.yaml` extension may be omitted.-    See the section [Default files] for more information on the+    See the section [Defaults files] for more information on the     file format.  Settings from the defaults file may be     overridden or extended by subsequent options on the command     line.@@ -644,7 +644,9 @@     files specified later on the command line will be preferred     over those specified in earlier files. Metadata values     specified inside the document, or by using `-M`, overwrite-    values specified with this option.+    values specified with this option. The file will be searched+    for first in the working directory, and then in the `metadata`+    subdirectory of the user data directory (see `--data-dir`).  `-p`, `--preserve-tabs` @@ -699,6 +701,12 @@     space, and the period will not produce sentence-ending space     in formats like LaTeX.  The strings may not contain spaces. +`--trace`++:   Print diagnostic output tracing parser progress to stderr.+    This option is intended for use by developers in diagnosing+    performance issues.+ [`pandocfilters`]: https://github.com/jgm/pandocfilters [PHP]: https://github.com/vinai/pandocfilters-php [perl]: https://metacpan.org/pod/Pandoc::Filter@@ -1299,16 +1307,18 @@  :   Use the specified engine when producing PDF output.     Valid values are `pdflatex`, `lualatex`, `xelatex`, `latexmk`,-    `tectonic`, `wkhtmltopdf`, `weasyprint`, `prince`, `context`,-    and `pdfroff`. If the engine is not in your PATH, the full-    path of the engine may be specified here.  If this option-    is not specified, pandoc uses the following defaults-    depending on the output format specified using `-t/--to`:+    `tectonic`, `wkhtmltopdf`, `weasyprint`, `pagedjs-cli`,+    `prince`, `context`, and `pdfroff`. If the engine is not in+    your PATH, the full path of the engine may be specified here.+    If this option is not specified, pandoc uses the following+    defaults depending on the output format specified using+    `-t/--to`:      - `-t latex` or none: `pdflatex` (other options: `xelatex`, `lualatex`,         `tectonic`, `latexmk`)     - `-t context`: `context`-    - `-t html`:  `wkhtmltopdf` (other options: `prince`, `weasyprint`;+    - `-t html`:  `wkhtmltopdf` (other options: `prince`, `weasyprint`,+        `pagedjs-cli`;         see [print-css.rocks](https://print-css.rocks) for a good         introduction to PDF generation from HTML/CSS.)     - `-t ms`:  `pdfroff`@@ -1510,190 +1520,14 @@    93 PandocIpynbDecodingError    94 PandocUnsupportedCharsetError    97 PandocCouldNotFindDataFileError+   98 PandocCouldNotFindMetadataFileError    99 PandocResourceNotFound ----- ------------------------------------ -# Default files+# Defaults files  The `--defaults` option may be used to specify a package-of options.  Here is a sample defaults file demonstrating all of-the fields that may be used:--``` yaml-from: markdown+emoji-# reader: may be used instead of from:-to: html5-# writer: may be used instead of to:--# leave blank for output to stdout:-output-file:-# leave blank for input from stdin, use [] for no input:-input-files:-- preface.md-- content.md-# or you may use input-file: with a single value--# Include options from the specified defaults files.-# The files will be searched for first in the working directory-# and then in the defaults subdirectory of the user data directory.-# The files are included in the same order in which they appear in-# the list. Options specified in this defaults file always have-# priority over the included ones.-defaults:-- defsA-- defsB--template: letter-standalone: true-self-contained: false--# note that structured variables may be specified:-variables:-  documentclass: book-  classoption:-    - twosides-    - draft--# metadata values specified here are parsed as literal-# string text, not markdown:-metadata:-  author:-  - Sam Smith-  - Julie Liu-metadata-files:-- boilerplate.yaml-# or you may use metadata-file: with a single value--# Note that these take files, not their contents:-include-before-body: []-include-after-body: []-include-in-header: []-resource-path: ["."]--# turn on built-in citation processing.  Note that if you need-# control over when the citeproc processing is done relative-# to other filters, you should instead use `citeproc` in the-# list of `filters` (see below).-citeproc: true-csl: ieee-bibliography:-- foobar.bib-- barbaz.json-citation-abbreviations: abbrevs.json--# Filters will be assumed to be Lua filters if they have-# the .lua extension, and json filters otherwise.  But-# the filter type can also be specified explicitly, as shown.-# Filters are run in the order specified.-# To include the built-in citeproc filter, use either `citeproc`-# or `{type: citeproc}`.-filters:-- wordcount.lua-- type: json-  path: foo.lua--file-scope: false--data-dir:--# ERROR, WARNING, or INFO-verbosity: INFO-log-file: log.json--# citeproc, natbib, or biblatex. This only affects LaTeX-# output.  If you want to use citeproc to format citations,-# you should also set 'citeproc: true' (see above).-cite-method: citeproc--# part, chapter, section, or default:-top-level-division: chapter-abbreviations:--pdf-engine: pdflatex-pdf-engine-opts:-- "-shell-escape"-# you may also use pdf-engine-opt: with a single option-# pdf-engine-opt: "-shell-escape"--# auto, preserve, or none-wrap: auto-columns: 78-dpi: 72--extract-media: mediadir--table-of-contents: true-toc-depth: 2-number-sections: false-# a list of offsets at each heading level-number-offset: [0,0,0,0,0,0]-# toc: may also be used instead of table-of-contents:-shift-heading-level-by: 1-section-divs: true-identifier-prefix: foo-title-prefix: ""-strip-empty-paragraphs: true-# lf, crlf, or native-eol: lf-strip-comments: false-indented-code-classes: []-ascii: true-default-image-extension: ".jpg"--# either a style name of a style definition file:-highlight-style: pygments-syntax-definitions:-- c.xml-# or you may use syntax-definition: with a single value-listings: false--reference-doc: myref.docx--# method is plain, webtex, gladtex, mathml, mathjax, katex-# you may specify a url with webtex, mathjax, katex-html-math-method:-  method: mathjax-  url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"-# none, references, or javascript-email-obfuscation: javascript--tab-stop: 8-preserve-tabs: true--incremental: false-slide-level: 2--epub-subdirectory: EPUB-epub-metadata: meta.xml-epub-fonts:-- foobar.otf-epub-chapter-level: 1-epub-cover-image: cover.jpg--reference-links: true-# block, section, or document-reference-location: block-markdown-headings: setext--# accept, reject, or all-track-changes: accept--html-q-tags: false-css:-- site.css--# none, all, or best-ipynb-output: best--# A list of two-element lists-request-headers:-- ["User-Agent", "Mozilla/5.0"]--fail-if-warnings: false-dump-args: false-ignore-args: false-trace: false-```+of options, in the form of a YAML file.  Fields that are omitted will just have their regular default values.  So a defaults file can be as simple as@@ -1715,7 +1549,7 @@ parsed, regardless of the setting of the environment variable `USERDATA`. -`${.}` will resolve to the directory containing the default+`${.}` will resolve to the directory containing the defaults file itself.  This allows you to refer to resources contained in that directory: @@ -1731,7 +1565,7 @@ This environment variable interpolation syntax *only* works in fields that expect file paths. -Default files can be placed in the `defaults` subdirectory of+Defaults files can be placed in the `defaults` subdirectory of the user data directory and used from any directory.  For example, one could create a file specifying defaults for writing letters, save it as `letter.yaml` in the `defaults` subdirectory@@ -1748,6 +1582,473 @@ the command line will combine with values specified in the defaults file, rather than replacing them. +The following tables show the mapping between the command line and+defaults file entries.+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| foo.md                           | input-file: foo.md                |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| foo.md bar.md                    | input-files:                      |+|                                  |   - foo.md                        |+|                                  |   - bar.md                        |+| ```                              | ```                               |++----------------------------------+-----------------------------------+++The value of `input-files` may be left empty to indicate input from+stdin, and it can be an empty sequence `[]` for no input.++## General options+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| --from markdown+emoji            | from: markdown+emoji              |+| ```                              | ```                               |+|                                  | ``` yaml                          |+|                                  | reader: markdown+emoji            |+|                                  | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --to markdown+hard_line_breaks   | to: markdown+hard_line_breaks     |+| ```                              | ```                               |+|                                  | ``` yaml                          |+|                                  | writer: markdown+hard_line_breaks |+|                                  | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --output foo.pdf                 | output-file: foo.pdf              |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --output -                       | output-file:                      |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --data-dir dir                   | data-dir: dir                     |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --defaults file                  | defaults:                         |+| ```                              | - file                            |+|                                  | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --verbose                        | verbosity: INFO                   |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --quiet                          | verbosity: ERROR                  |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --fail-if-warnings               | fail-if-warnings: true            |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --sandbox                        | sandbox: true                     |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --log=FILE                       | log-file: FILE                    |+| ```                              | ```                               |++----------------------------------+-----------------------------------+++Options specified in a defaults file itself always have priority over+those in another file included with a `defaults:` entry.++`verbosity` can have the values `ERROR`, `WARNING`, or `INFO`.++## Reader options+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| --shift-heading-level-by -1      | shift-heading-level-by: -1        |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --indented-code-classes python   | indented-code-classes:            |+|                                  |   - python                        |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --default-image-extension ".jpg" | default-image-extension: '.jpg'   |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --file-scope                     | file-scope: true                  |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --filter pandoc-citeproc \       | filters:                          |+|  --lua-filter count-words.lua \  |   - pandoc-citeproc               |+|  --filter special.lua            |   - count-words.lua               |+|                                  |   - type: json                    |+|                                  |     path: special.lua             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --metadata key=value \           | metadata:                         |+|  --metadata key2                 |   key: value                      |+|                                  |   key2: true                      |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --metadata-file meta.yaml        | metadata-files:                   |+|                                  |   - meta.yaml                     |+| ```                              | ```                               |+|                                  | ``` yaml                          |+|                                  | metadata-file: meta.yaml          |+|                                  | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --preserve-tabs                  | preserve-tabs: true               |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --tab-stop 8                     | tab-stop: 8                       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --track-changes accept           | track-changes: accept             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --extract-media dir              | extract-media: dir                |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --abbreviations abbrevs.txt      | abbreviations: abbrevs.txt        |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --trace                          | trace: true                       |+| ```                              | ```                               |++----------------------------------+-----------------------------------+++Metadata values specified in a defaults file are parsed as literal+string text, not Markdown.++Filters will be assumed to be Lua filters if they have the `.lua`+extension, and JSON filters otherwise.  But the filter type can also be+specified explicitly, as shown.  Filters are run in the order specified.+To include the built-in citeproc filter, use either `citeproc` or+`{type: citeproc}`.++## General writer options+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| --standalone                     | standalone: true                  |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --template letter                | template: letter                  |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --variable key=val \             | variables:                        |+|   --variable key2                |   key: val                        |+|                                  |   key2: true                      |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --eol nl                         | eol: nl                           |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --dpi 300                        | dpi: 300                          |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --wrap 60                        | wrap: 60                          |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --columns 72                     | columns: 72                       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --table-of-contents              | table-of-contents: true           |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --toc                            | toc: true                         |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --toc-depth 3                    | toc-depth: 3                      |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --strip-comments                 | strip-comments: true              |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --no-highlight                   | highlight-style: null             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --highlight-style kate           | highlight-style: kate             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --syntax-definition mylang.xml   | syntax-definitions:               |+|                                  |   - mylang.xml                    |+| ```                              | ```                               |+|                                  | ``` yaml                          |+|                                  | syntax-definition: mylang.xml     |+|                                  | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --include-in-header inc.tex      | include-in-header:                |+|                                  |   - inc.tex                       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --include-before-body inc.tex    | include-before-body:              |+|                                  |   - inc.tex                       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --include-after-body inc.tex     | include-after-body:               |+|                                  |   - inc.tex                       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --resource-path .:foo            | resource-path: ['.','foo']        |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --request-header foo:bar         | request-headers:                  |+|                                  |   - ["User-Agent", "Mozilla/5.0"] |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --no-check-certificate           | no-check-certificate: true        |+| ```                              | ```                               |++----------------------------------+-----------------------------------++++## Options affecting specific writers+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| --self-contained                 | self-contained: true              |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --html-q-tags                    | html-q-tags: true                 |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --ascii                          | ascii: true                       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --reference-links                | reference-links: true             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --reference-location block       | reference-location: block         |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --markdown-headings atx          | markdown-headings: atx            |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --top-level-division chapter     | top-level-division: chapter       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --number-sections                | number-sections: true             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --number-offset=1,4              | number-offset: \[1,4\]            |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --listings                       | listings: true                    |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --incremental                    | incremental: true                 |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --slide-level 2                  | slide-level: 2                    |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --section-divs                   | section-divs: true                |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --email-obfuscation references   | email-obfuscation: references     |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --id-prefix ch1                  | identifier-prefix: ch1            |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --title-prefix MySite            | title-prefix: MySite              |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --css styles/screen.css  \       | css:                              |+|   --css styles/special.css       |   - styles/screen.css             |+|                                  |   - styles/special.css            |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --reference-doc my.docx          | reference-doc: my.docx            |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --epub-cover-image cover.jpg     | epub-cover-image: cover.jpg       |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --epub-metadata meta.xml         | epub-metadata: meta.xml           |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --epub-embed-font special.otf \  | epub-fonts:                       |+|   --epub-embed-font headline.otf |   - special.otf                   |+|                                  |   - headline.otf                  |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --epub-chapter-level 2           | epub-chapter-level: 2             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --epub-subdirectory=""           | epub-subdirectory: ''             |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --ipynb-output best              | ipynb-output: best                |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --pdf-engine xelatex             | pdf-engine: xelatex               |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --pdf-engine-opt=--shell-escape  | pdf-engine-opts:                  |+|                                  |   - '-shell-escape'               |+| ```                              | ```                               |+|                                  | ``` yaml                          |+|                                  | pdf-engine-opt: '-shell-escape'   |+|                                  | ```                               |++----------------------------------+-----------------------------------+++## Citation rendering+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| --citeproc                       | citeproc: true                    |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --bibliography logic.bib         | metadata:                         |+|                                  |   bibliography: logic.bib         |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --csl ieee.csl                   | metadata:                         |+|                                  |   csl: ieee.csl                   |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --citation-abbreviations ab.json | metadata:                         |+|                                  |   citation-abbreviations: ab.json |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --natbib                         | cite-method: natbib               |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --biblatex                       | cite-method: biblatex             |+| ```                              | ```                               |++----------------------------------+-----------------------------------+++`cite-method` can be `citeproc`, `natbib`, or `biblatex`. This only+affects LaTeX output.  If you want to use citeproc to format citations,+you should also set 'citeproc: true'.++If you need control over when the citeproc processing is done relative+to other filters, you should instead use `citeproc` in the list+of `filters` (see above).++## Math rendering in HTML+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| --mathjax                        | html-math-method:                 |+|                                  |   method: mathjax                 |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --mathml                         | html-math-method:                 |+|                                  |   method: mathml                  |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --webtex                         | html-math-method:                 |+|                                  |   method: webtex                  |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --katex                          | html-math-method:                 |+|                                  |   method: katex                   |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --gladtex                        | html-math-method:                 |+|                                  |   method: gladtex                 |+| ```                              | ```                               |++----------------------------------+-----------------------------------+++In addition to the values listed above, `method` can have the+value `plain`.++If the command line option accepts a URL argument, an `url:` field can+be added to `html-math-method:`.++## Options for wrapper scripts+++----------------------------------+-----------------------------------++| command line                     | defaults file                     |++:=================================+:==================================++| ```                              | ``` yaml                          |+| --dump-args                      | dump-args: true                   |+| ```                              | ```                               |++----------------------------------+-----------------------------------++| ```                              | ``` yaml                          |+| --ignore-args                    | ignore-args: true                 |+| ```                              | ```                               |++----------------------------------+-----------------------------------++ # Templates  When the `-s/--standalone` option is used, pandoc uses a template to@@ -2381,10 +2682,7 @@     `1610` for 16:10, `149` for 14:9, `141` for 1.41:1, `54` for 5:4,     `32` for 3:2) -`beamerarticle`-:   produce an article from Beamer slides--`beameroption`+``beameroption` :   add extra beamer option with `\setbeameroption{}`  `institute`@@ -2507,6 +2805,9 @@ :   numbering depth for sections (with `--number-sections` option     or `numbersections` variable) +`beamerarticle`+:   produce an article from Beamer slides+ #### Fonts  `fontenc`@@ -5479,13 +5780,13 @@ references are provided, both will be used. In case of conflicting `id`s, the inline references will take precedence. -Note that `pandoc` can be used to produce such a YAML metadata+Note that pandoc can be used to produce such a YAML metadata section from a BibTeX, BibLaTeX, or CSL JSON bibliography:      pandoc chem.bib -s -f biblatex -t markdown     pandoc chem.json -s -f csljson -t markdown -Indeed, `pandoc` can convert between any of these+Indeed, pandoc can convert between any of these citation formats:      pandoc chem.bib -s -f biblatex -t csljson@@ -5686,7 +5987,7 @@ For LaTeX output, you can also use [`natbib`] or [`biblatex`] to render the bibliography. In order to do so, specify bibliography files as outlined above, and add `--natbib` or `--biblatex`-argument to `pandoc` invocation. Bear in mind that bibliography+argument to pandoc invocation. Bear in mind that bibliography files have to be in either BibTeX (for `--natbib`) or BibLaTeX (for `--biblatex`) format. @@ -5982,18 +6283,15 @@  Note that heading attributes will turn into slide attributes (on a `<div>` or `<section>`) in HTML slide formats, allowing you-to style individual slides.  In beamer, the only heading attribute-that affects slides is the `allowframebreaks` class, which sets the-`allowframebreaks` option, causing multiple slides to be created-if the content overfills the frame.  This is recommended especially for-bibliographies:--    # References {.allowframebreaks}+to style individual slides.  In beamer, a number of heading+classes and attributes are recognized as frame options and+will be passed through as options to the frame: see+[Frame attributes in beamer], below.  ## Speaker notes -Speaker notes are supported in reveal.js and PowerPoint (pptx)-output. You can add notes to your Markdown document thus:+Speaker notes are supported in reveal.js, PowerPoint (pptx),+and beamer output. You can add notes to your Markdown document thus:      ::: notes @@ -6072,8 +6370,18 @@  All of the other frame attributes described in Section 8.1 of the [Beamer User's Guide] may also be used: `allowdisplaybreaks`,-`allowframebreaks`, `b`, `c`, `t`, `environment`, `label`, `plain`,-`shrink`, `standout`, `noframenumbering`.+`allowframebreaks`, `b`, `c`, `s`, `t`, `environment`, `label`, `plain`,+`shrink`, `standout`, `noframenumbering`, `squeeze`.+`allowframebreaks` is recommended especially for bibliographies, as+it allows multiple slides to be created if the content overfills the+frame:++    # References {.allowframebreaks}++In addition, the `frameoptions` attribute may be used to+pass arbitrary frame options to a beamer slide:++    # Heading {frameoptions="squeeze,shrink,customoption=foobar"}  ## Background in reveal.js, beamer, and pptx
changelog.md view
@@ -1,5 +1,164 @@ # Revision history for pandoc +## pandoc 2.17.1 (2022-01-30)++  * Support `pagedjs-cli` as pdf engine (#7838, Albert Krewinkel).+    PagedJS is a polyfill and supports the Paged Media standards by the W3C.+    <https://www.pagedjs.org/>++  * CommonMark reader: fix source position after YAML metadata (#7863).++  * LaTeX reader:++    + Remove retokenizing in `rawLaTeXParser`.+    + Ensure that `\raggedright` doesn't gobble an argument (#7757).+    + Improve `descItem`.  For some reason we were skipping+      arbitrary blocks before `\item`.  This is now changed to "skip+      whitespace and comments."+    + Improve handling of `\newif`.  Adding a pair of braces around the+      second argument of `\def` prevents LaTeX from an emergency stop+      on input like the following (#6096).+      ```+      \newif\ifepub+      \epubtrue+      \ifepub+      hi+      \fi+      ```++  * Docx reader: Parse both Zotero citation and bibliography as+    `FieldInfo` (#7840).++  * LaTeX writer:++    + Allow arbitrary frameoptions to be passed to a beamer+      frame, using the frameoptions attribute (#7869).+    + Add s and squeeze to recognized beamer frameoptions (#7869).++  * Markdown writer: handle explicit column widths with pipe tables (#7847).+    If a table has explicit column width information *and* the content+    extends beyond the `--columns` width, we need to adjust the+    widths of the pipe separators to encode this width information.++  * Docx writer: Separate tables even with RawBlocks between (#7224,+    Michael Hoffmann).  Adjacent docx tables need to be separated by an+    empty paragraph. If there's a RawBlock between tables which renders+    to nothing, be sure to still insert the empty paragraph so that+    they will not collapse together.++  * Man writer: use custom font V for inline code (#7506).+    The V font is defined conditionally, so that it renders+    like CB in output formats that support that, and like B+    in those that don't (e.g. the terminal).+    Aliases also defined for VI, VB, VBI.++  * Asciidoc writer: Support checklists in asciidoctor writer (#7832,+    Nikolai Korobeinikov, ricnorr).  The checklist syntax (similar to+    `task_list` in markdown) seems to be an asciidoctor-only addition.++  * HTML writer:++    + Avoid duplicate "style" attributes on table cells (#7871).+    + Don't break lines inside code elements.  With the new (default)+      line wrapping of HTML, in conjunction with the default CSS which+      includes `code { whitespace: pre-wrap; }`, spurious line+      breaks could be introduced into inline code (#7858).++  * Custom writer: preserve order of element attributes (#7489, Albert+    Krewinkel).  Attribute key-value pairs are marshaled as AttributeList,+    i.e., as a userdata type that behaves both like a list and a map. This+    allows to preserve the order of key-value pairs.++  * Switch to hslua-2.1 (Albert Krewinkel). This allows for some code+    simplification and improves stability.++  * Don't read files outside of user data directory (Even Brenden).+    If a file path does not exist relative to the working directory, and+    it does exist relative to the user data directory, but outside of+    of the user data directory, do not read it. This applies to+    `readDataFile` and `readMetadataFile` in PandocMonad and, by+    extension, any module that uses these by passing them relative paths.++  * Text.Pandoc.Class.`makeCanonical`: Correctly handle consecutive ".."s+    at the beginning of a path (Even Brenden).  Prior to this commit,+    `../../file` would evaluate to `file`, when it should be unchanged.++  * Search for metadata files in `$DATADIR/metadata` (#7851, Even Brenden).+    If files specified with `--metadata-file` are not found in the working+    directory, look in `$DATADIR/metadata` (#5876).++  * Text.Pandoc.Class: export `readMetadataFile` [API change] (#5876).++  * Text.Pandoc.Error: export new `PandocCouldNotFindMetadataFileError`+    constructor for `PandocError` [API change] (#5876).++  * Avoid putting a frame around speaker notes in beamer (#7857).+    If speaker notes (a Div with class 'notes') occur right+    after a section heading, but above slide level, the+    resulting `\note{..}` caommand should not be wrapped in+    a frame, as that will cause a spurious blank slide.++  * CSS in HTML template: adjust #TOC and h1 on mobile (#7835, Mauro Bieg).++  * Text.Pandoc.Readers.LaTeX.Parsing: don't export `totoks`.+    Make the first param of `tokenize` a SourcePos instead of+    SourceName, and use it instead of `totoks`.++  * Text.Pandoc.Shared: Modify `stringify` so it ignores `[Citation]`+    inside `Cite` (#7855).  Otherwise we'll sometimes get two copies of+    things, one from the `citationPrefix` or `citationSuffix` and another+    from the embedded fallback text.  When there is no fallback text,+    we'll get no content.  However, it really isn't an alternative to just+    rely on the result of running `query` on the embedded `Citation`s;+    this will result in a jumble of text rather than anything structured.++  * Omit `--enable-doc` in the cabal haddock invocation in+    `tools/build-and-upload-api-docs.sh`.++  * Text.Pandoc.App.Opt: fix logic bug in `fullDefaultsPath`.+    Previously we would (also) search the default user data directory+    for a defaults file, even if a different user data directory+    was specified using `--data-dir`.  This was a mistake; if+    `--data-dir` is used, the default user data directory should+    not be searched.++  * Text.Pandoc.Shared: `defaultUserDataDir` behavior change (#7842).+    If the XDG data directory is not defined (e.g. because+    it's not supported in the OS or HOME isn't defined), we+    return the empty string instead of raising an exception.++  * Update command tests to distinguish stderr and test exit status.++  * MANUAL: add that speaker notes can be used with beamer (#7856).++  * Update `build-and-upload-api-docs.sh`.++  * Document `--trace` option.+    Document `no-check-certificate` in defaults files.+    Document 'sandbox' option for defaults files.  (#7873).++  * Fix pattern syntax in sample readability custom reader.++  * doc/custom-readers.lua: add example for "readable HTML."++  * Fix message in man page about where code can be found.++  * `manfilter.lua`:  remove extra indent in table cells with code blocks.++  * Fix lua-filters documentation for table column widths (#7864).++  * epub.doc: Update links to KindleGen (#7846, Benson Muite, Mauro Bieg).+    KindleGen has been deprecated and we need to link to archived versions.++  * Use tables in defaults files documentation, so each+    default option is paired with the corresponding command-line+    option (Carsten Allefeld).++  * Use skylighting 0.12.2.++  * Add pandoc-lua-marshal to Nix shell (#7849, Even Brenden).++ ## pandoc 2.17.0.1 (2022-01-14)    * Require pandoc-lua-marshal 0.1.3.1 (#7831, Albert Krewinkel).
data/templates/default.man view
@@ -5,6 +5,20 @@ .\" Automatically generated by Pandoc $pandoc-version$ .\" $endif$+.\" Define V font for inline verbatim, using C font in formats+.\" that render this, and otherwise B font.+.ie "\f[CB]x\f[]"x" \{\+. ftr V B+. ftr VI BI+. ftr VB B+. ftr VBI BI+.\}+.el \{\+. ftr V CR+. ftr VI CI+. ftr VB CB+. ftr VBI CBI+.\} $if(adjusting)$ .ad $adjusting$ $endif$
data/templates/styles.html view
@@ -23,6 +23,9 @@     font-size: 0.9em;     padding: 1em;   }+  h1 {+    font-size: 1.8em;+  } } @media print {   body {@@ -147,6 +150,12 @@ } #TOC li {   list-style: none;+}+#TOC ul {+  padding-left: 1.3em;+}+#TOC > ul {+  padding-left: 0; } #TOC a:not(:hover) {   text-decoration: none;
man/manfilter.lua view
@@ -11,6 +11,30 @@     end end +-- unindent table content+function Table(el)+  for _,body in ipairs(el.bodies) do+    handleTableBody(body)+  end+  return el+end++local function handleCell(el)+  if #el.contents > 0 and el.contents[1].t == "CodeBlock" then+    table.insert(el.contents, 1, pandoc.RawBlock("man", ".RS -14n"))+    table.insert(el.contents, pandoc.RawBlock("man", ".RE"))+  end+end++function handleTableBody(el)+  for _,row in ipairs(el.body) do+    for _,cell in ipairs(row.cells) do+      handleCell(cell)+    end+  end+end++ -- replace links with link text function Link(el)     return el.content
man/pandoc.1 view
@@ -1,7987 +1,9664 @@ '\" t-.\" Automatically generated by Pandoc 2.17-.\"-.TH "Pandoc User\[cq]s Guide" "" "January 14, 2022" "pandoc 2.17.0.1" ""-.hy-.SH NAME-pandoc - general markup converter-.SH SYNOPSIS-.PP-\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]\&...-.SH DESCRIPTION-.PP-Pandoc is a Haskell library for converting from one markup format to-another, and a command-line tool that uses this library.-.PP-Pandoc can convert between numerous markup and word processing formats,-including, but not limited to, various flavors of Markdown, HTML, LaTeX-and Word docx.-For the full lists of input and output formats, see the \f[C]--from\f[R]-and \f[C]--to\f[R] options below.-Pandoc can also produce PDF output: see creating a PDF, below.-.PP-Pandoc\[cq]s enhanced version of Markdown includes syntax for tables,-definition lists, metadata blocks, footnotes, citations, math, and much-more.-See below under Pandoc\[cq]s Markdown.-.PP-Pandoc has a modular design: it consists of a set of readers, which-parse text in a given format and produce a native representation of the-document (an \f[I]abstract syntax tree\f[R] or AST), and a set of-writers, which convert this native representation into a target format.-Thus, adding an input or output format requires only adding a reader or-writer.-Users can also run custom pandoc filters to modify the intermediate AST.-.PP-Because pandoc\[cq]s intermediate representation of a document is less-expressive than many of the formats it converts between, one should not-expect perfect conversions between every format and every other.-Pandoc attempts to preserve the structural elements of a document, but-not formatting details such as margin size.-And some document elements, such as complex tables, may not fit into-pandoc\[cq]s simple document model.-While conversions from pandoc\[cq]s Markdown to all formats aspire to be-perfect, conversions from formats more expressive than pandoc\[cq]s-Markdown can be expected to be lossy.-.SS Using pandoc-.PP-If no \f[I]input-files\f[R] are specified, input is read from-\f[I]stdin\f[R].-Output goes to \f[I]stdout\f[R] by default.-For output to a file, use the \f[C]-o\f[R] option:-.IP-.nf-\f[C]-pandoc -o output.html input.txt-\f[R]-.fi-.PP-By default, pandoc produces a document fragment.-To produce a standalone document (e.g.\ a valid HTML file including-\f[C]<head>\f[R] and \f[C]<body>\f[R]), use the \f[C]-s\f[R] or-\f[C]--standalone\f[R] flag:-.IP-.nf-\f[C]-pandoc -s -o output.html input.txt-\f[R]-.fi-.PP-For more information on how standalone documents are produced, see-Templates below.-.PP-If multiple input files are given, \f[C]pandoc\f[R] will concatenate-them all (with blank lines between them) before parsing.-(Use \f[C]--file-scope\f[R] to parse files individually.)-.SS Specifying formats-.PP-The format of the input and output can be specified explicitly using-command-line options.-The input format can be specified using the \f[C]-f/--from\f[R] option,-the output format using the \f[C]-t/--to\f[R] option.-Thus, to convert \f[C]hello.txt\f[R] from Markdown to LaTeX, you could-type:-.IP-.nf-\f[C]-pandoc -f markdown -t latex hello.txt-\f[R]-.fi-.PP-To convert \f[C]hello.html\f[R] from HTML to Markdown:-.IP-.nf-\f[C]-pandoc -f html -t markdown hello.html-\f[R]-.fi-.PP-Supported input and output formats are listed below under Options (see-\f[C]-f\f[R] for input formats and \f[C]-t\f[R] for output formats).-You can also use \f[C]pandoc --list-input-formats\f[R] and-\f[C]pandoc --list-output-formats\f[R] to print lists of supported-formats.-.PP-If the input or output format is not specified explicitly,-\f[C]pandoc\f[R] will attempt to guess it from the extensions of the-filenames.-Thus, for example,-.IP-.nf-\f[C]-pandoc -o hello.tex hello.txt-\f[R]-.fi-.PP-will convert \f[C]hello.txt\f[R] from Markdown to LaTeX.-If no output file is specified (so that output goes to-\f[I]stdout\f[R]), or if the output file\[cq]s extension is unknown, the-output format will default to HTML.-If no input file is specified (so that input comes from-\f[I]stdin\f[R]), or if the input files\[cq] extensions are unknown, the-input format will be assumed to be Markdown.-.SS Character encoding-.PP-Pandoc uses the UTF-8 character encoding for both input and output.-If your local character encoding is not UTF-8, you should pipe input and-output through \f[C]iconv\f[R]:-.IP-.nf-\f[C]-iconv -t utf-8 input.txt | pandoc | iconv -f utf-8-\f[R]-.fi-.PP-Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,-OPML, DocBook, and Texinfo), information about the character encoding is-included in the document header, which will only be included if you use-the \f[C]-s/--standalone\f[R] option.-.SS Creating a PDF-.PP-To produce a PDF, specify an output file with a \f[C].pdf\f[R]-extension:-.IP-.nf-\f[C]-pandoc test.txt -o test.pdf-\f[R]-.fi-.PP-By default, pandoc will use LaTeX to create the PDF, which requires that-a LaTeX engine be installed (see \f[C]--pdf-engine\f[R] below).-Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an-intermediate format.-To do this, specify an output file with a \f[C].pdf\f[R] extension, as-before, but add the \f[C]--pdf-engine\f[R] option or-\f[C]-t context\f[R], \f[C]-t html\f[R], or \f[C]-t ms\f[R] to the-command line.-The tool used to generate the PDF from the intermediate format may be-specified using \f[C]--pdf-engine\f[R].-.PP-You can control the PDF style using variables, depending on the-intermediate format used: see variables for LaTeX, variables for-ConTeXt, variables for \f[C]wkhtmltopdf\f[R], variables for ms.-When HTML is used as an intermediate format, the output can be styled-using \f[C]--css\f[R].-.PP-To debug the PDF creation, it can be useful to look at the intermediate-representation: instead of \f[C]-o test.pdf\f[R], use for example-\f[C]-s -o test.tex\f[R] to output the generated LaTeX.-You can then test it with \f[C]pdflatex test.tex\f[R].-.PP-When using LaTeX, the following packages need to be available (they are-included with all recent versions of TeX Live): \f[C]amsfonts\f[R],-\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],-\f[C]iftex\f[R], \f[C]listings\f[R] (if the \f[C]--listings\f[R] option-is used), \f[C]fancyvrb\f[R], \f[C]longtable\f[R], \f[C]booktabs\f[R],-\f[C]graphicx\f[R] (if the document contains images),-\f[C]hyperref\f[R], \f[C]xcolor\f[R], \f[C]ulem\f[R], \f[C]geometry\f[R]-(with the \f[C]geometry\f[R] variable set), \f[C]setspace\f[R] (with-\f[C]linestretch\f[R]), and \f[C]babel\f[R] (with \f[C]lang\f[R]).-If \f[C]CJKmainfont\f[R] is set, \f[C]xeCJK\f[R] is needed.-The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine-requires \f[C]fontspec\f[R].-\f[C]lualatex\f[R] uses \f[C]selnolig\f[R].-\f[C]xelatex\f[R] uses \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable-set).-If the \f[C]mathspec\f[R] variable is set, \f[C]xelatex\f[R] will use-\f[C]mathspec\f[R] instead of \f[C]unicode-math\f[R].-The \f[C]upquote\f[R] and \f[C]microtype\f[R] packages are used if-available, and \f[C]csquotes\f[R] will be used for typography if the-\f[C]csquotes\f[R] variable or metadata field is set to a true value.-The \f[C]natbib\f[R], \f[C]biblatex\f[R], \f[C]bibtex\f[R], and-\f[C]biber\f[R] packages can optionally be used for citation rendering.-The following packages will be used to improve output quality if-present, but pandoc does not require them to be present:-\f[C]upquote\f[R] (for straight quotes in verbatim environments),-\f[C]microtype\f[R] (for better spacing adjustments), \f[C]parskip\f[R]-(for better inter-paragraph spaces), \f[C]xurl\f[R] (for better line-breaks in URLs), \f[C]bookmark\f[R] (for better PDF bookmarks), and-\f[C]footnotehyper\f[R] or \f[C]footnote\f[R] (to allow footnotes in-tables).-.SS Reading from the Web-.PP-Instead of an input file, an absolute URI may be given.-In this case pandoc will fetch the content using HTTP:-.IP-.nf-\f[C]-pandoc -f html -t markdown https://www.fsf.org-\f[R]-.fi-.PP-It is possible to supply a custom User-Agent string or other header when-requesting a document from a URL:-.IP-.nf-\f[C]-pandoc -f html -t markdown --request-header User-Agent:\[dq]Mozilla/5.0\[dq] \[rs]-  https://www.fsf.org-\f[R]-.fi-.SH OPTIONS-.SS General options-.TP-\f[B]\f[CB]-f\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]-r\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--from=\f[B]\f[R]\f[I]FORMAT\f[R], \f[B]\f[CB]--read=\f[B]\f[R]\f[I]FORMAT\f[R]-Specify input format.-\f[I]FORMAT\f[R] can be:-.RS-.IP \[bu] 2-\f[C]bibtex\f[R] (BibTeX bibliography)-.IP \[bu] 2-\f[C]biblatex\f[R] (BibLaTeX bibliography)-.IP \[bu] 2-\f[C]commonmark\f[R] (CommonMark Markdown)-.IP \[bu] 2-\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)-.IP \[bu] 2-\f[C]creole\f[R] (Creole 1.0)-.IP \[bu] 2-\f[C]csljson\f[R] (CSL JSON bibliography)-.IP \[bu] 2-\f[C]csv\f[R] (CSV table)-.IP \[bu] 2-\f[C]docbook\f[R] (DocBook)-.IP \[bu] 2-\f[C]docx\f[R] (Word docx)-.IP \[bu] 2-\f[C]dokuwiki\f[R] (DokuWiki markup)-.IP \[bu] 2-\f[C]epub\f[R] (EPUB)-.IP \[bu] 2-\f[C]fb2\f[R] (FictionBook2 e-book)-.IP \[bu] 2-\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less-accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only-if you need extensions not supported in \f[C]gfm\f[R].-.IP \[bu] 2-\f[C]haddock\f[R] (Haddock markup)-.IP \[bu] 2-\f[C]html\f[R] (HTML)-.IP \[bu] 2-\f[C]ipynb\f[R] (Jupyter notebook)-.IP \[bu] 2-\f[C]jats\f[R] (JATS XML)-.IP \[bu] 2-\f[C]jira\f[R] (Jira/Confluence wiki markup)-.IP \[bu] 2-\f[C]json\f[R] (JSON version of native AST)-.IP \[bu] 2-\f[C]latex\f[R] (LaTeX)-.IP \[bu] 2-\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)-.IP \[bu] 2-\f[C]markdown_mmd\f[R] (MultiMarkdown)-.IP \[bu] 2-\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)-.IP \[bu] 2-\f[C]markdown_strict\f[R] (original unextended Markdown)-.IP \[bu] 2-\f[C]mediawiki\f[R] (MediaWiki markup)-.IP \[bu] 2-\f[C]man\f[R] (roff man)-.IP \[bu] 2-\f[C]muse\f[R] (Muse)-.IP \[bu] 2-\f[C]native\f[R] (native Haskell)-.IP \[bu] 2-\f[C]odt\f[R] (ODT)-.IP \[bu] 2-\f[C]opml\f[R] (OPML)-.IP \[bu] 2-\f[C]org\f[R] (Emacs Org mode)-.IP \[bu] 2-\f[C]rtf\f[R] (Rich Text Format)-.IP \[bu] 2-\f[C]rst\f[R] (reStructuredText)-.IP \[bu] 2-\f[C]t2t\f[R] (txt2tags)-.IP \[bu] 2-\f[C]textile\f[R] (Textile)-.IP \[bu] 2-\f[C]tikiwiki\f[R] (TikiWiki markup)-.IP \[bu] 2-\f[C]twiki\f[R] (TWiki markup)-.IP \[bu] 2-\f[C]vimwiki\f[R] (Vimwiki)-.IP \[bu] 2-the path of a custom Lua reader, see Custom readers and writers below-.PP-Extensions can be individually enabled or disabled by appending-\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.-See Extensions below, for a list of extensions and their names.-See \f[C]--list-input-formats\f[R] and \f[C]--list-extensions\f[R],-below.-.RE-.TP-\f[B]\f[CB]-t\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]-w\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--to=\f[B]\f[R]\f[I]FORMAT\f[R], \f[B]\f[CB]--write=\f[B]\f[R]\f[I]FORMAT\f[R]-Specify output format.-\f[I]FORMAT\f[R] can be:-.RS-.IP \[bu] 2-\f[C]asciidoc\f[R] (AsciiDoc) or \f[C]asciidoctor\f[R] (AsciiDoctor)-.IP \[bu] 2-\f[C]beamer\f[R] (LaTeX beamer slide show)-.IP \[bu] 2-\f[C]bibtex\f[R] (BibTeX bibliography)-.IP \[bu] 2-\f[C]biblatex\f[R] (BibLaTeX bibliography)-.IP \[bu] 2-\f[C]commonmark\f[R] (CommonMark Markdown)-.IP \[bu] 2-\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)-.IP \[bu] 2-\f[C]context\f[R] (ConTeXt)-.IP \[bu] 2-\f[C]csljson\f[R] (CSL JSON bibliography)-.IP \[bu] 2-\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)-.IP \[bu] 2-\f[C]docbook5\f[R] (DocBook 5)-.IP \[bu] 2-\f[C]docx\f[R] (Word docx)-.IP \[bu] 2-\f[C]dokuwiki\f[R] (DokuWiki markup)-.IP \[bu] 2-\f[C]epub\f[R] or \f[C]epub3\f[R] (EPUB v3 book)-.IP \[bu] 2-\f[C]epub2\f[R] (EPUB v2)-.IP \[bu] 2-\f[C]fb2\f[R] (FictionBook2 e-book)-.IP \[bu] 2-\f[C]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less-accurate \f[C]markdown_github\f[R]; use \f[C]markdown_github\f[R] only-if you need extensions not supported in \f[C]gfm\f[R].-.IP \[bu] 2-\f[C]haddock\f[R] (Haddock markup)-.IP \[bu] 2-\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot-markup)-.IP \[bu] 2-\f[C]html4\f[R] (XHTML 1.0 Transitional)-.IP \[bu] 2-\f[C]icml\f[R] (InDesign ICML)-.IP \[bu] 2-\f[C]ipynb\f[R] (Jupyter notebook)-.IP \[bu] 2-\f[C]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set)-.IP \[bu] 2-\f[C]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set)-.IP \[bu] 2-\f[C]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set)-.IP \[bu] 2-\f[C]jats\f[R] (alias for \f[C]jats_archiving\f[R])-.IP \[bu] 2-\f[C]jira\f[R] (Jira/Confluence wiki markup)-.IP \[bu] 2-\f[C]json\f[R] (JSON version of native AST)-.IP \[bu] 2-\f[C]latex\f[R] (LaTeX)-.IP \[bu] 2-\f[C]man\f[R] (roff man)-.IP \[bu] 2-\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)-.IP \[bu] 2-\f[C]markdown_mmd\f[R] (MultiMarkdown)-.IP \[bu] 2-\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)-.IP \[bu] 2-\f[C]markdown_strict\f[R] (original unextended Markdown)-.IP \[bu] 2-\f[C]markua\f[R] (Markua)-.IP \[bu] 2-\f[C]mediawiki\f[R] (MediaWiki markup)-.IP \[bu] 2-\f[C]ms\f[R] (roff ms)-.IP \[bu] 2-\f[C]muse\f[R] (Muse),-.IP \[bu] 2-\f[C]native\f[R] (native Haskell),-.IP \[bu] 2-\f[C]odt\f[R] (OpenOffice text document)-.IP \[bu] 2-\f[C]opml\f[R] (OPML)-.IP \[bu] 2-\f[C]opendocument\f[R] (OpenDocument)-.IP \[bu] 2-\f[C]org\f[R] (Emacs Org mode)-.IP \[bu] 2-\f[C]pdf\f[R] (PDF)-.IP \[bu] 2-\f[C]plain\f[R] (plain text),-.IP \[bu] 2-\f[C]pptx\f[R] (PowerPoint slide show)-.IP \[bu] 2-\f[C]rst\f[R] (reStructuredText)-.IP \[bu] 2-\f[C]rtf\f[R] (Rich Text Format)-.IP \[bu] 2-\f[C]texinfo\f[R] (GNU Texinfo)-.IP \[bu] 2-\f[C]textile\f[R] (Textile)-.IP \[bu] 2-\f[C]slideous\f[R] (Slideous HTML and JavaScript slide show)-.IP \[bu] 2-\f[C]slidy\f[R] (Slidy HTML and JavaScript slide show)-.IP \[bu] 2-\f[C]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show),-.IP \[bu] 2-\f[C]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)-.IP \[bu] 2-\f[C]s5\f[R] (S5 HTML and JavaScript slide show)-.IP \[bu] 2-\f[C]tei\f[R] (TEI Simple)-.IP \[bu] 2-\f[C]xwiki\f[R] (XWiki markup)-.IP \[bu] 2-\f[C]zimwiki\f[R] (ZimWiki markup)-.IP \[bu] 2-the path of a custom Lua writer, see Custom readers and writers below-.PP-Note that \f[C]odt\f[R], \f[C]docx\f[R], \f[C]epub\f[R], and-\f[C]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless-forced with \f[C]-o -\f[R].-.PP-Extensions can be individually enabled or disabled by appending-\f[C]+EXTENSION\f[R] or \f[C]-EXTENSION\f[R] to the format name.-See Extensions below, for a list of extensions and their names.-See \f[C]--list-output-formats\f[R] and \f[C]--list-extensions\f[R],-below.-.RE-.TP-\f[B]\f[CB]-o\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--output=\f[B]\f[R]\f[I]FILE\f[R]-Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].-If \f[I]FILE\f[R] is \f[C]-\f[R], output will go to \f[I]stdout\f[R],-even if a non-textual format (\f[C]docx\f[R], \f[C]odt\f[R],-\f[C]epub2\f[R], \f[C]epub3\f[R]) is specified.-.TP-\f[B]\f[CB]--data-dir=\f[B]\f[R]\f[I]DIRECTORY\f[R]-Specify the user data directory to search for pandoc data files.-If this option is not specified, the default user data directory will be-used.-On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory-of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],-overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment-variable).-If that directory does not exist and \f[C]$HOME/.pandoc\f[R] exists, it-will be used (for backwards compatibility).-On Windows the default user data directory is-\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].-You can find the default user data directory on your system by looking-at the output of \f[C]pandoc --version\f[R].-Data files placed in this directory (for example,-\f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],-\f[C]templates\f[R]) will override pandoc\[cq]s normal defaults.-.TP-\f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]-Specify a set of default option settings.-\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line-option settings.-All options for document conversion, including input and output files,-can be set using a defaults file.-The file will be searched for first in the working directory, and then-in the \f[C]defaults\f[R] subdirectory of the user data directory (see-\f[C]--data-dir\f[R]).-The \f[C].yaml\f[R] extension may be omitted.-See the section Default files for more information on the file format.-Settings from the defaults file may be overridden or extended by-subsequent options on the command line.-.TP-\f[B]\f[CB]--bash-completion\f[B]\f[R]-Generate a bash completion script.-To enable bash completion with pandoc, add this to your-\f[C].bashrc\f[R]:-.RS-.IP-.nf-\f[C]-eval \[dq]$(pandoc --bash-completion)\[dq]-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]--verbose\f[B]\f[R]-Give verbose debugging output.-.TP-\f[B]\f[CB]--quiet\f[B]\f[R]-Suppress warning messages.-.TP-\f[B]\f[CB]--fail-if-warnings\f[B]\f[R]-Exit with error status if there are any warnings.-.TP-\f[B]\f[CB]--log=\f[B]\f[R]\f[I]FILE\f[R]-Write log messages in machine-readable JSON format to \f[I]FILE\f[R].-All messages above DEBUG level will be written, regardless of verbosity-settings (\f[C]--verbose\f[R], \f[C]--quiet\f[R]).-.TP-\f[B]\f[CB]--list-input-formats\f[B]\f[R]-List supported input formats, one per line.-.TP-\f[B]\f[CB]--list-output-formats\f[B]\f[R]-List supported output formats, one per line.-.TP-\f[B]\f[CB]--list-extensions\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]FORMAT\f[R]]-List supported extensions for \f[I]FORMAT\f[R], one per line, preceded-by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by-default in \f[I]FORMAT\f[R].-If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown-are given.-.TP-\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]-List supported languages for syntax highlighting, one per line.-.TP-\f[B]\f[CB]--list-highlight-styles\f[B]\f[R]-List supported styles for syntax highlighting, one per line.-See \f[C]--highlight-style\f[R].-.TP-\f[B]\f[CB]-v\f[B]\f[R], \f[B]\f[CB]--version\f[B]\f[R]-Print version.-.TP-\f[B]\f[CB]-h\f[B]\f[R], \f[B]\f[CB]--help\f[B]\f[R]-Show usage message.-.SS Reader options-.TP-\f[B]\f[CB]--shift-heading-level-by=\f[B]\f[R]\f[I]NUMBER\f[R]-Shift heading levels by a positive or negative integer.-For example, with \f[C]--shift-heading-level-by=-1\f[R], level 2-headings become level 1 headings, and level 3 headings become level 2-headings.-Headings cannot have a level less than 1, so a heading that would be-shifted below level 1 becomes a regular paragraph.-Exception: with a shift of -N, a level-N heading at the beginning of the-document replaces the metadata title.-\f[C]--shift-heading-level-by=-1\f[R] is a good choice when converting-HTML or Markdown documents that use an initial level-1 heading for the-document title and level-2+ headings for sections.-\f[C]--shift-heading-level-by=1\f[R] may be a good choice for converting-Markdown documents that use level-1 headings for sections to HTML, since-pandoc uses a level-1 heading to render the document title.-.TP-\f[B]\f[CB]--base-header-level=\f[B]\f[R]\f[I]NUMBER\f[R]-\f[I]Deprecated.-Use \f[CI]--shift-heading-level-by\f[I]=X instead, where X = NUMBER --1.\f[R] Specify the base level for headings (defaults to 1).-.TP-\f[B]\f[CB]--strip-empty-paragraphs\f[B]\f[R]-\f[I]Deprecated.-Use the \f[CI]+empty_paragraphs\f[I] extension instead.\f[R] Ignore-paragraphs with no content.-This option is useful for converting word processing documents where-users have used empty paragraphs to create inter-paragraph space.-.TP-\f[B]\f[CB]--indented-code-classes=\f[B]\f[R]\f[I]CLASSES\f[R]-Specify classes to use for indented code blocks\[en]for example,-\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].-Multiple classes may be separated by spaces or commas.-.TP-\f[B]\f[CB]--default-image-extension=\f[B]\f[R]\f[I]EXTENSION\f[R]-Specify a default extension to use when image paths/URLs have no-extension.-This allows you to use the same source for formats that require-different kinds of images.-Currently this option only affects the Markdown and LaTeX readers.-.TP-\f[B]\f[CB]--file-scope\f[B]\f[R]-Parse each file individually before combining for multifile documents.-This will allow footnotes in different files with the same identifiers-to work as expected.-If this option is set, footnotes and links will not work across files.-Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].-.TP-\f[B]\f[CB]-F\f[B]\f[R] \f[I]PROGRAM\f[R], \f[B]\f[CB]--filter=\f[B]\f[R]\f[I]PROGRAM\f[R]-Specify an executable to be used as a filter transforming the pandoc AST-after the input is parsed and before the output is written.-The executable should read JSON from stdin and write JSON to stdout.-The JSON must be formatted like pandoc\[cq]s own JSON input and output.-The name of the output format will be passed to the filter as the first-argument.-Hence,-.RS-.IP-.nf-\f[C]-pandoc --filter ./caps.py -t latex-\f[R]-.fi-.PP-is equivalent to-.IP-.nf-\f[C]-pandoc -t json | ./caps.py latex | pandoc -f json -t latex-\f[R]-.fi-.PP-The latter form may be useful for debugging filters.-.PP-Filters may be written in any language.-\f[C]Text.Pandoc.JSON\f[R] exports \f[C]toJSONFilter\f[R] to facilitate-writing filters in Haskell.-Those who would prefer to write filters in python can use the module-\f[C]pandocfilters\f[R], installable from PyPI.-There are also pandoc filter libraries in PHP, perl, and-JavaScript/node.js.-.PP-In order of preference, pandoc will look for filters in-.IP "1." 3-a specified full or relative path (executable or non-executable)-.IP "2." 3-\f[C]$DATADIR/filters\f[R] (executable or non-executable) where-\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],-above).-.IP "3." 3-\f[C]$PATH\f[R] (executable only)-.PP-Filters, Lua-filters, and citeproc processing are applied in the order-specified on the command line.-.RE-.TP-\f[B]\f[CB]-L\f[B]\f[R] \f[I]SCRIPT\f[R], \f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]-Transform the document in a similar fashion as JSON filters (see-\f[C]--filter\f[R]), but use pandoc\[cq]s built-in Lua filtering system.-The given Lua script is expected to return a list of Lua filters which-will be applied in order.-Each Lua filter must contain element-transforming functions indexed by-the name of the AST element on which the filter function should be-applied.-.RS-.PP-The \f[C]pandoc\f[R] Lua module provides helper functions for element-creation.-It is always loaded into the script\[cq]s Lua environment.-.PP-See the Lua filters documentation for further details.-.PP-In order of preference, pandoc will look for Lua filters in-.IP "1." 3-a specified full or relative path-.IP "2." 3-\f[C]$DATADIR/filters\f[R] where \f[C]$DATADIR\f[R] is the user data-directory (see \f[C]--data-dir\f[R], above).-.PP-Filters, Lua filters, and citeproc processing are applied in the order-specified on the command line.-.RE-.TP-\f[B]\f[CB]-M\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--metadata=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]-Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].-A value specified on the command line overrides a value specified in the-document using YAML metadata blocks.-Values will be parsed as YAML boolean or string values.-If no value is specified, the value will be treated as Boolean true.-Like \f[C]--variable\f[R], \f[C]--metadata\f[R] causes template-variables to be set.-But unlike \f[C]--variable\f[R], \f[C]--metadata\f[R] affects the-metadata of the underlying document (which is accessible from filters-and may be printed in some output formats) and metadata values will be-escaped when inserted into the template.-.TP-\f[B]\f[CB]--metadata-file=\f[B]\f[R]\f[I]FILE\f[R]-Read metadata from the supplied YAML (or JSON) file.-This option can be used with every input format, but string scalars in-the YAML file will always be parsed as Markdown.-Generally, the input will be handled the same as in YAML metadata-blocks.-This option can be used repeatedly to include multiple metadata files;-values in files specified later on the command line will be preferred-over those specified in earlier files.-Metadata values specified inside the document, or by using \f[C]-M\f[R],-overwrite values specified with this option.-.TP-\f[B]\f[CB]-p\f[B]\f[R], \f[B]\f[CB]--preserve-tabs\f[B]\f[R]-Preserve tabs instead of converting them to spaces.-(By default, pandoc converts tabs to spaces before parsing its input.)-Note that this will only affect tabs in literal code spans and code-blocks.-Tabs in regular text are always treated as spaces.-.TP-\f[B]\f[CB]--tab-stop=\f[B]\f[R]\f[I]NUMBER\f[R]-Specify the number of spaces per tab (default is 4).-.TP-\f[B]\f[CB]--track-changes=accept\f[B]\f[R]|\f[B]\f[CB]reject\f[B]\f[R]|\f[B]\f[CB]all\f[B]\f[R]-Specifies what to do with insertions, deletions, and comments produced-by the MS Word \[lq]Track Changes\[rq] feature.-\f[C]accept\f[R] (the default) processes all the insertions and-deletions.-\f[C]reject\f[R] ignores them.-Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.-\f[C]all\f[R] includes all insertions, deletions, and comments, wrapped-in spans with \f[C]insertion\f[R], \f[C]deletion\f[R],-\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,-respectively.-The author and time of change is included.-\f[C]all\f[R] is useful for scripting: only accepting changes from a-certain reviewer, say, or before a certain date.-If a paragraph is inserted or deleted, \f[C]track-changes=all\f[R]-produces a span with the class-\f[C]paragraph-insertion\f[R]/\f[C]paragraph-deletion\f[R] before the-affected paragraph break.-This option only affects the docx reader.-.TP-\f[B]\f[CB]--extract-media=\f[B]\f[R]\f[I]DIR\f[R]-Extract images and other media contained in or linked from the source-document to the path \f[I]DIR\f[R], creating it if necessary, and adjust-the images references in the document so they point to the extracted-files.-Media are downloaded, read from the file system, or extracted from a-binary container (e.g.\ docx), as needed.-The original file paths are used if they are relative paths not-containing \f[C]..\f[R].-Otherwise filenames are constructed from the SHA1 hash of the contents.-.TP-\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]-Specifies a custom abbreviations file, with abbreviations one to a line.-If this option is not specified, pandoc will read the data file-\f[C]abbreviations\f[R] from the user data directory or fall back on a-system default.-To see the system default, use-\f[C]pandoc --print-default-data-file=abbreviations\f[R].-The only use pandoc makes of this list is in the Markdown reader.-Strings found in this list will be followed by a nonbreaking space, and-the period will not produce sentence-ending space in formats like LaTeX.-The strings may not contain spaces.-.SS General writer options-.TP-\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]-Produce output with an appropriate header and footer (e.g.\ a standalone-HTML, LaTeX, TEI, or RTF file, not a fragment).-This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],-\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]-output.-For \f[C]native\f[R] output, this option causes metadata to be included;-otherwise, metadata is suppressed.-.TP-\f[B]\f[CB]--template=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]-Use the specified file as a custom template for the generated document.-Implies \f[C]--standalone\f[R].-See Templates, below, for a description of template syntax.-If no extension is specified, an extension corresponding to the writer-will be added, so that \f[C]--template=special\f[R] looks for-\f[C]special.html\f[R] for HTML output.-If the template is not found, pandoc will search for it in the-\f[C]templates\f[R] subdirectory of the user data directory (see-\f[C]--data-dir\f[R]).-If this option is not used, a default template appropriate for the-output format will be used (see \f[C]-D/--print-default-template\f[R]).-.TP-\f[B]\f[CB]-V\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--variable=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]-Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when-rendering the document in standalone mode.-If no \f[I]VAL\f[R] is specified, the key will be given the value-\f[C]true\f[R].-.TP-\f[B]\f[CB]--sandbox\f[B]\f[R]-Run pandoc in a sandbox, limiting IO operations in readers and writers-to reading the files specified on the command line.-Note that this option does not limit IO operations by filters or in the-production of PDF documents.-But it does offer security against, for example, disclosure of files-through the use of \f[C]include\f[R] directives.-Anyone using pandoc on untrusted user input should use this option.-.TP-\f[B]\f[CB]-D\f[B]\f[R] \f[I]FORMAT\f[R], \f[B]\f[CB]--print-default-template=\f[B]\f[R]\f[I]FORMAT\f[R]-Print the system default template for an output \f[I]FORMAT\f[R].-(See \f[C]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.)-Templates in the user data directory are ignored.-This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect-output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before-\f[C]--print-default-template\f[R] on the command line.-.RS-.PP-Note that some of the default templates use partials, for example-\f[C]styles.html\f[R].-To print the partials, use \f[C]--print-default-data-file\f[R]: for-example, \f[C]--print-default-data-file=templates/styles.html\f[R].-.RE-.TP-\f[B]\f[CB]--print-default-data-file=\f[B]\f[R]\f[I]FILE\f[R]-Print a system default data file.-Files in the user data directory are ignored.-This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect-output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before-\f[C]--print-default-data-file\f[R] on the command line.-.TP-\f[B]\f[CB]--eol=crlf\f[B]\f[R]|\f[B]\f[CB]lf\f[B]\f[R]|\f[B]\f[CB]native\f[B]\f[R]-Manually specify line endings: \f[C]crlf\f[R] (Windows), \f[C]lf\f[R]-(macOS/Linux/UNIX), or \f[C]native\f[R] (line endings appropriate to the-OS on which pandoc is being run).-The default is \f[C]native\f[R].-.TP-\f[B]\f[CB]--dpi\f[B]\f[R]=\f[I]NUMBER\f[R]-Specify the default dpi (dots per inch) value for conversion from pixels-to inch/centimeters and vice versa.-(Technically, the correct term would be ppi: pixels per inch.)-The default is 96dpi.-When images contain information about dpi internally, the encoded value-is used instead of the default specified by this option.-.TP-\f[B]\f[CB]--wrap=auto\f[B]\f[R]|\f[B]\f[CB]none\f[B]\f[R]|\f[B]\f[CB]preserve\f[B]\f[R]-Determine how text is wrapped in the output (the source code, not the-rendered version).-With \f[C]auto\f[R] (the default), pandoc will attempt to wrap lines to-the column width specified by \f[C]--columns\f[R] (default 72).-With \f[C]none\f[R], pandoc will not wrap lines at all.-With \f[C]preserve\f[R], pandoc will attempt to preserve the wrapping-from the source document (that is, where there are nonsemantic newlines-in the source, there will be nonsemantic newlines in the output as-well).-In \f[C]ipynb\f[R] output, this option affects wrapping of the contents-of markdown cells.-.TP-\f[B]\f[CB]--columns=\f[B]\f[R]\f[I]NUMBER\f[R]-Specify length of lines in characters.-This affects text wrapping in the generated source code (see-\f[C]--wrap\f[R]).-It also affects calculation of column widths for plain text tables (see-Tables below).-.TP-\f[B]\f[CB]--toc\f[B]\f[R], \f[B]\f[CB]--table-of-contents\f[B]\f[R]-Include an automatically generated table of contents (or, in the case of-\f[C]latex\f[R], \f[C]context\f[R], \f[C]docx\f[R], \f[C]odt\f[R],-\f[C]opendocument\f[R], \f[C]rst\f[R], or \f[C]ms\f[R], an instruction-to create one) in the output document.-This option has no effect unless \f[C]-s/--standalone\f[R] is used, and-it has no effect on \f[C]man\f[R], \f[C]docbook4\f[R],-\f[C]docbook5\f[R], or \f[C]jats\f[R] output.-.RS-.PP-Note that if you are producing a PDF via \f[C]ms\f[R], the table of-contents will appear at the beginning of the document, before the title.-If you would prefer it to be at the end of the document, use the option-\f[C]--pdf-engine-opt=--no-toc-relocation\f[R].-.RE-.TP-\f[B]\f[CB]--toc-depth=\f[B]\f[R]\f[I]NUMBER\f[R]-Specify the number of section levels to include in the table of-contents.-The default is 3 (which means that level-1, 2, and 3 headings will be-listed in the contents).-.TP-\f[B]\f[CB]--strip-comments\f[B]\f[R]-Strip out HTML comments in the Markdown or Textile source, rather than-passing them on to Markdown, Textile or HTML output as raw HTML.-This does not apply to HTML comments inside raw HTML blocks when the-\f[C]markdown_in_html_blocks\f[R] extension is not set.-.TP-\f[B]\f[CB]--no-highlight\f[B]\f[R]-Disables syntax highlighting for code blocks and inlines, even when a-language attribute is given.-.TP-\f[B]\f[CB]--highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]-Specifies the coloring style to be used in highlighted source code.-Options are \f[C]pygments\f[R] (the default), \f[C]kate\f[R],-\f[C]monochrome\f[R], \f[C]breezeDark\f[R], \f[C]espresso\f[R],-\f[C]zenburn\f[R], \f[C]haddock\f[R], and \f[C]tango\f[R].-For more information on syntax highlighting in pandoc, see Syntax-highlighting, below.-See also \f[C]--list-highlight-styles\f[R].-.RS-.PP-Instead of a \f[I]STYLE\f[R] name, a JSON file with extension-\f[C].theme\f[R] may be supplied.-This will be parsed as a KDE syntax highlighting theme and (if valid)-used as the highlighting style.-.PP-To generate the JSON version of an existing style, use-\f[C]--print-highlight-style\f[R].-.RE-.TP-\f[B]\f[CB]--print-highlight-style=\f[B]\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]-Prints a JSON version of a highlighting style, which can be modified,-saved with a \f[C].theme\f[R] extension, and used with-\f[C]--highlight-style\f[R].-This option may be used with \f[C]-o\f[R]/\f[C]--output\f[R] to redirect-output to a file, but \f[C]-o\f[R]/\f[C]--output\f[R] must come before-\f[C]--print-highlight-style\f[R] on the command line.-.TP-\f[B]\f[CB]--syntax-definition=\f[B]\f[R]\f[I]FILE\f[R]-Instructs pandoc to load a KDE XML syntax definition file, which will be-used for syntax highlighting of appropriately marked code blocks.-This can be used to add support for new languages or to use altered-syntax definitions for existing languages.-This option may be repeated to add multiple syntax definitions.-.TP-\f[B]\f[CB]-H\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-in-header=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]-Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.-This can be used, for example, to include special CSS or JavaScript in-HTML documents.-This option can be used repeatedly to include multiple files in the-header.-They will be included in the order specified.-Implies \f[C]--standalone\f[R].-.TP-\f[B]\f[CB]-B\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-before-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]-Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the-document body (e.g.\ after the \f[C]<body>\f[R] tag in HTML, or the-\f[C]\[rs]begin{document}\f[R] command in LaTeX).-This can be used to include navigation bars or banners in HTML-documents.-This option can be used repeatedly to include multiple files.-They will be included in the order specified.-Implies \f[C]--standalone\f[R].-.TP-\f[B]\f[CB]-A\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-after-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]-Include contents of \f[I]FILE\f[R], verbatim, at the end of the document-body (before the \f[C]</body>\f[R] tag in HTML, or the-\f[C]\[rs]end{document}\f[R] command in LaTeX).-This option can be used repeatedly to include multiple files.-They will be included in the order specified.-Implies \f[C]--standalone\f[R].-.TP-\f[B]\f[CB]--resource-path=\f[B]\f[R]\f[I]SEARCHPATH\f[R]-List of paths to search for images and other resources.-The paths should be separated by \f[C]:\f[R] on Linux, UNIX, and macOS-systems, and by \f[C];\f[R] on Windows.-If \f[C]--resource-path\f[R] is not specified, the default resource path-is the working directory.-Note that, if \f[C]--resource-path\f[R] is specified, the working-directory must be explicitly listed or it will not be searched.-For example: \f[C]--resource-path=.:test\f[R] will search the working-directory and the \f[C]test\f[R] subdirectory, in that order.-This option can be used repeatedly.-Search path components that come later on the command line will be-searched before those that come earlier, so-\f[C]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent-to \f[C]--resource-path baz:bim:foo:bar\f[R].-.TP-\f[B]\f[CB]--request-header=\f[B]\f[R]\f[I]NAME\f[R]\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]-Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when-making HTTP requests (for example, when a URL is given on the command-line, or when resources used in a document must be downloaded).-If you\[cq]re behind a proxy, you also need to set the environment-variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].-.TP-\f[B]\f[CB]--no-check-certificate\f[B]\f[R]-Disable the certificate verification to allow access to unsecure HTTP-resources (for example when the certificate is no longer valid or self-signed).-.SS Options affecting specific writers-.TP-\f[B]\f[CB]--self-contained\f[B]\f[R]-Produce a standalone HTML file with no external dependencies, using-\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,-stylesheets, images, and videos.-Implies \f[C]--standalone\f[R].-The resulting file should be \[lq]self-contained,\[rq] in the sense that-it needs no external files and no net access to be displayed properly by-a browser.-This option works only with HTML output formats, including-\f[C]html4\f[R], \f[C]html5\f[R], \f[C]html+lhs\f[R],-\f[C]html5+lhs\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],-\f[C]dzslides\f[R], and \f[C]revealjs\f[R].-Scripts, images, and stylesheets at absolute URLs will be downloaded;-those at relative URLs will be sought relative to the working directory-(if the first source file is local) or relative to the base URL (if the-first source file is remote).-Elements with the attribute \f[C]data-external=\[dq]1\[dq]\f[R] will be-left alone; the documents they link to will not be incorporated in the-document.-Limitation: resources that are loaded dynamically through JavaScript-cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not-work with \f[C]--mathjax\f[R], and some advanced features (e.g.\ zoom or-speaker notes) may not work in an offline \[lq]self-contained\[rq]-\f[C]reveal.js\f[R] slide show.-.TP-\f[B]\f[CB]--html-q-tags\f[B]\f[R]-Use \f[C]<q>\f[R] tags for quotes in HTML.-(This option only has an effect if the \f[C]smart\f[R] extension is-enabled for the input format used.)-.TP-\f[B]\f[CB]--ascii\f[B]\f[R]-Use only ASCII characters in output.-Currently supported for XML and HTML formats (which use entities instead-of UTF-8 when this option is selected), CommonMark, gfm, and Markdown-(which use entities), roff ms (which use hexadecimal escapes), and to a-limited degree LaTeX (which uses standard commands for accented-characters when possible).-roff man output uses ASCII by default.-.TP-\f[B]\f[CB]--reference-links\f[B]\f[R]-Use reference-style links, rather than inline links, in writing Markdown-or reStructuredText.-By default inline links are used.-The placement of link references is affected by the-\f[C]--reference-location\f[R] option.-.TP-\f[B]\f[CB]--reference-location=block\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]document\f[B]\f[R]-Specify whether footnotes (and references, if \f[C]reference-links\f[R]-is set) are placed at the end of the current (top-level) block, the-current section, or the document.-The default is \f[C]document\f[R].-Currently this option only affects the \f[C]markdown\f[R],-\f[C]muse\f[R], \f[C]html\f[R], \f[C]epub\f[R], \f[C]slidy\f[R],-\f[C]s5\f[R], \f[C]slideous\f[R], \f[C]dzslides\f[R], and-\f[C]revealjs\f[R] writers.-.TP-\f[B]\f[CB]--markdown-headings=setext\f[B]\f[R]|\f[B]\f[CB]atx\f[B]\f[R]-Specify whether to use ATX-style (\f[C]#\f[R]-prefixed) or Setext-style-(underlined) headings for level 1 and 2 headings in Markdown output.-(The default is \f[C]atx\f[R].)-ATX-style headings are always used for levels 3+.-This option also affects Markdown cells in \f[C]ipynb\f[R] output.-.TP-\f[B]\f[CB]--atx-headers\f[B]\f[R]-\f[I]Deprecated synonym for \f[CI]--markdown-headings=atx\f[I].\f[R]-.TP-\f[B]\f[CB]--top-level-division=default\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]chapter\f[B]\f[R]|\f[B]\f[CB]part\f[B]\f[R]-Treat top-level headings as the given division type in LaTeX, ConTeXt,-DocBook, and TEI output.-The hierarchy order is part, chapter, then section; all headings are-shifted such that the top-level heading becomes the specified type.-The default behavior is to determine the best division type via-heuristics: unless other conditions apply, \f[C]section\f[R] is chosen.-When the \f[C]documentclass\f[R] variable is set to \f[C]report\f[R],-\f[C]book\f[R], or \f[C]memoir\f[R] (unless the \f[C]article\f[R] option-is specified), \f[C]chapter\f[R] is implied as the setting for this-option.-If \f[C]beamer\f[R] is the output format, specifying either-\f[C]chapter\f[R] or \f[C]part\f[R] will cause top-level headings to-become \f[C]\[rs]part{..}\f[R], while second-level headings remain as-their default type.-.TP-\f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]-Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB-output.-By default, sections are not numbered.-Sections with class \f[C]unnumbered\f[R] will never be numbered, even if-\f[C]--number-sections\f[R] is specified.-.TP-\f[B]\f[CB]--number-offset=\f[B]\f[R]\f[I]NUMBER\f[R][\f[B]\f[CB],\f[B]\f[R]\f[I]NUMBER\f[R]\f[B]\f[CB],\f[B]\f[R]\f[I]\&...\f[R]]-Offset for section headings in HTML output (ignored in other output-formats).-The first number is added to the section number for top-level headings,-the second for second-level headings, and so on.-So, for example, if you want the first top-level heading in your-document to be numbered \[lq]6\[rq], specify-\f[C]--number-offset=5\f[R].-If your document starts with a level-2 heading which you want to be-numbered \[lq]1.5\[rq], specify \f[C]--number-offset=1,4\f[R].-Offsets are 0 by default.-Implies \f[C]--number-sections\f[R].-.TP-\f[B]\f[CB]--listings\f[B]\f[R]-Use the \f[C]listings\f[R] package for LaTeX code blocks.-The package does not support multi-byte encoding for source code.-To handle UTF-8 you would need to use a custom template.-This issue is fully documented here: Encoding issue with the listings-package.-.TP-\f[B]\f[CB]-i\f[B]\f[R], \f[B]\f[CB]--incremental\f[B]\f[R]-Make list items in slide shows display incrementally (one by one).-The default is for lists to be displayed all at once.-.TP-\f[B]\f[CB]--slide-level=\f[B]\f[R]\f[I]NUMBER\f[R]-Specifies that headings with the specified level create slides (for-\f[C]beamer\f[R], \f[C]s5\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R],-\f[C]dzslides\f[R]).-Headings above this level in the hierarchy are used to divide the slide-show into sections; headings below this level create subheads within a-slide.-Valid values are 0-6.-If a slide level of 0 is specified, slides will not be split-automatically on headings, and horizontal rules must be used to indicate-slide boundaries.-If a slide level is not specified explicitly, the slide level will be-set automatically based on the contents of the document; see Structuring-the slide show.-.TP-\f[B]\f[CB]--section-divs\f[B]\f[R]-Wrap sections in \f[C]<section>\f[R] tags (or \f[C]<div>\f[R] tags for-\f[C]html4\f[R]), and attach identifiers to the enclosing-\f[C]<section>\f[R] (or \f[C]<div>\f[R]) rather than the heading itself.-See Heading identifiers, below.-.TP-\f[B]\f[CB]--email-obfuscation=none\f[B]\f[R]|\f[B]\f[CB]javascript\f[B]\f[R]|\f[B]\f[CB]references\f[B]\f[R]-Specify a method for obfuscating \f[C]mailto:\f[R] links in HTML-documents.-\f[C]none\f[R] leaves \f[C]mailto:\f[R] links as they are.-\f[C]javascript\f[R] obfuscates them using JavaScript.-\f[C]references\f[R] obfuscates them by printing their letters as-decimal or hexadecimal character references.-The default is \f[C]none\f[R].-.TP-\f[B]\f[CB]--id-prefix=\f[B]\f[R]\f[I]STRING\f[R]-Specify a prefix to be added to all identifiers and internal links in-HTML and DocBook output, and to footnote numbers in Markdown and Haddock-output.-This is useful for preventing duplicate identifiers when generating-fragments to be included in other pages.-.TP-\f[B]\f[CB]-T\f[B]\f[R] \f[I]STRING\f[R], \f[B]\f[CB]--title-prefix=\f[B]\f[R]\f[I]STRING\f[R]-Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that-appears in the HTML header (but not in the title as it appears at the-beginning of the HTML body).-Implies \f[C]--standalone\f[R].-.TP-\f[B]\f[CB]-c\f[B]\f[R] \f[I]URL\f[R], \f[B]\f[CB]--css=\f[B]\f[R]\f[I]URL\f[R]-Link to a CSS style sheet.-This option can be used repeatedly to include multiple files.-They will be included in the order specified.-.RS-.PP-A stylesheet is required for generating EPUB.-If none is provided using this option (or the \f[C]css\f[R] or-\f[C]stylesheet\f[R] metadata fields), pandoc will look for a file-\f[C]epub.css\f[R] in the user data directory (see-\f[C]--data-dir\f[R]).-If it is not found there, sensible defaults will be used.-.RE-.TP-\f[B]\f[CB]--reference-doc=\f[B]\f[R]\f[I]FILE\f[R]-Use the specified file as a style reference in producing a docx or ODT-file.-.RS-.TP-Docx-For best results, the reference docx should be a modified version of a-docx file produced using pandoc.-The contents of the reference docx are ignored, but its stylesheets and-document properties (including margins, page size, header, and footer)-are used in the new docx.-If no reference docx is specified on the command line, pandoc will look-for a file \f[C]reference.docx\f[R] in the user data directory (see-\f[C]--data-dir\f[R]).-If this is not found either, sensible defaults will be used.-.RS-.PP-To produce a custom \f[C]reference.docx\f[R], first get a copy of the-default \f[C]reference.docx\f[R]:-\f[C]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R].-Then open \f[C]custom-reference.docx\f[R] in Word, modify the styles as-you wish, and save the file.-For best results, do not make changes to this file other than modifying-the styles used by pandoc:-.PP-Paragraph styles:-.IP \[bu] 2-Normal-.IP \[bu] 2-Body Text-.IP \[bu] 2-First Paragraph-.IP \[bu] 2-Compact-.IP \[bu] 2-Title-.IP \[bu] 2-Subtitle-.IP \[bu] 2-Author-.IP \[bu] 2-Date-.IP \[bu] 2-Abstract-.IP \[bu] 2-Bibliography-.IP \[bu] 2-Heading 1-.IP \[bu] 2-Heading 2-.IP \[bu] 2-Heading 3-.IP \[bu] 2-Heading 4-.IP \[bu] 2-Heading 5-.IP \[bu] 2-Heading 6-.IP \[bu] 2-Heading 7-.IP \[bu] 2-Heading 8-.IP \[bu] 2-Heading 9-.IP \[bu] 2-Block Text-.IP \[bu] 2-Footnote Text-.IP \[bu] 2-Definition Term-.IP \[bu] 2-Definition-.IP \[bu] 2-Caption-.IP \[bu] 2-Table Caption-.IP \[bu] 2-Image Caption-.IP \[bu] 2-Figure-.IP \[bu] 2-Captioned Figure-.IP \[bu] 2-TOC Heading-.PP-Character styles:-.IP \[bu] 2-Default Paragraph Font-.IP \[bu] 2-Body Text Char-.IP \[bu] 2-Verbatim Char-.IP \[bu] 2-Footnote Reference-.IP \[bu] 2-Hyperlink-.IP \[bu] 2-Section Number-.PP-Table style:-.IP \[bu] 2-Table-.RE-.TP-ODT-For best results, the reference ODT should be a modified version of an-ODT produced using pandoc.-The contents of the reference ODT are ignored, but its stylesheets are-used in the new ODT.-If no reference ODT is specified on the command line, pandoc will look-for a file \f[C]reference.odt\f[R] in the user data directory (see-\f[C]--data-dir\f[R]).-If this is not found either, sensible defaults will be used.-.RS-.PP-To produce a custom \f[C]reference.odt\f[R], first get a copy of the-default \f[C]reference.odt\f[R]:-\f[C]pandoc -o custom-reference.odt --print-default-data-file reference.odt\f[R].-Then open \f[C]custom-reference.odt\f[R] in LibreOffice, modify the-styles as you wish, and save the file.-.RE-.TP-PowerPoint-Templates included with Microsoft PowerPoint 2013 (either with-\f[C].pptx\f[R] or \f[C].potx\f[R] extension) are known to work, as are-most templates derived from these.-.RS-.PP-The specific requirement is that the template should contain layouts-with the following names (as seen within PowerPoint):-.IP \[bu] 2-Title Slide-.IP \[bu] 2-Title and Content-.IP \[bu] 2-Section Header-.IP \[bu] 2-Two Content-.IP \[bu] 2-Comparison-.IP \[bu] 2-Content with Caption-.IP \[bu] 2-Blank-.PP-For each name, the first layout found with that name will be used.-If no layout is found with one of the names, pandoc will output a-warning and use the layout with that name from the default reference doc-instead.-(How these layouts are used is described in PowerPoint layout choice.)-.PP-All templates included with a recent version of MS PowerPoint will fit-these criteria.-(You can click on \f[C]Layout\f[R] under the \f[C]Home\f[R] menu to-check.)-.PP-You can also modify the default \f[C]reference.pptx\f[R]: first run-\f[C]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R],-and then modify \f[C]custom-reference.pptx\f[R] in MS PowerPoint (pandoc-will use the layouts with the names listed above).-.RE-.RE-.TP-\f[B]\f[CB]--epub-cover-image=\f[B]\f[R]\f[I]FILE\f[R]-Use the specified image as the EPUB cover.-It is recommended that the image be less than 1000px in width and-height.-Note that in a Markdown source document you can also specify-\f[C]cover-image\f[R] in a YAML metadata block (see EPUB Metadata,-below).-.TP-\f[B]\f[CB]--epub-metadata=\f[B]\f[R]\f[I]FILE\f[R]-Look in the specified XML file for metadata for the EPUB.-The file should contain a series of Dublin Core elements.-For example:-.RS-.IP-.nf-\f[C]- <dc:rights>Creative Commons</dc:rights>- <dc:language>es-AR</dc:language>-\f[R]-.fi-.PP-By default, pandoc will include the following metadata elements:-\f[C]<dc:title>\f[R] (from the document title), \f[C]<dc:creator>\f[R]-(from the document authors), \f[C]<dc:date>\f[R] (from the document-date, which should be in ISO 8601 format), \f[C]<dc:language>\f[R] (from-the \f[C]lang\f[R] variable, or, if is not set, the locale), and-\f[C]<dc:identifier id=\[dq]BookId\[dq]>\f[R] (a randomly generated-UUID).-Any of these may be overridden by elements in the metadata file.-.PP-Note: if the source document is Markdown, a YAML metadata block in the-document can be used instead.-See below under EPUB Metadata.-.RE-.TP-\f[B]\f[CB]--epub-embed-font=\f[B]\f[R]\f[I]FILE\f[R]-Embed the specified font in the EPUB.-This option can be repeated to embed multiple fonts.-Wildcards can also be used: for example, \f[C]DejaVuSans-*.ttf\f[R].-However, if you use wildcards on the command line, be sure to escape-them or put the whole filename in single quotes, to prevent them from-being interpreted by the shell.-To use the embedded fonts, you will need to add declarations like the-following to your CSS (see \f[C]--css\f[R]):-.RS-.IP-.nf-\f[C]-\[at]font-face {-font-family: DejaVuSans;-font-style: normal;-font-weight: normal;-src:url(\[dq]DejaVuSans-Regular.ttf\[dq]);-}-\[at]font-face {-font-family: DejaVuSans;-font-style: normal;-font-weight: bold;-src:url(\[dq]DejaVuSans-Bold.ttf\[dq]);-}-\[at]font-face {-font-family: DejaVuSans;-font-style: italic;-font-weight: normal;-src:url(\[dq]DejaVuSans-Oblique.ttf\[dq]);-}-\[at]font-face {-font-family: DejaVuSans;-font-style: italic;-font-weight: bold;-src:url(\[dq]DejaVuSans-BoldOblique.ttf\[dq]);-}-body { font-family: \[dq]DejaVuSans\[dq]; }-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]-Specify the heading level at which to split the EPUB into separate-\[lq]chapter\[rq] files.-The default is to split into chapters at level-1 headings.-This option only affects the internal composition of the EPUB, not the-way chapters and sections are displayed to users.-Some readers may be slow if the chapter files are too large, so for-large documents with few level-1 headings, one might want to use a-chapter level of 2 or 3.-.TP-\f[B]\f[CB]--epub-subdirectory=\f[B]\f[R]\f[I]DIRNAME\f[R]-Specify the subdirectory in the OCF container that is to hold the-EPUB-specific contents.-The default is \f[C]EPUB\f[R].-To put the EPUB contents in the top level, use an empty string.-.TP-\f[B]\f[CB]--ipynb-output=all|none|best\f[B]\f[R]-Determines how ipynb output cells are treated.-\f[C]all\f[R] means that all of the data formats included in the-original are preserved.-\f[C]none\f[R] means that the contents of data cells are omitted.-\f[C]best\f[R] causes pandoc to try to pick the richest data block in-each output cell that is compatible with the output format.-The default is \f[C]best\f[R].-.TP-\f[B]\f[CB]--pdf-engine=\f[B]\f[R]\f[I]PROGRAM\f[R]-Use the specified engine when producing PDF output.-Valid values are \f[C]pdflatex\f[R], \f[C]lualatex\f[R],-\f[C]xelatex\f[R], \f[C]latexmk\f[R], \f[C]tectonic\f[R],-\f[C]wkhtmltopdf\f[R], \f[C]weasyprint\f[R], \f[C]prince\f[R],-\f[C]context\f[R], and \f[C]pdfroff\f[R].-If the engine is not in your PATH, the full path of the engine may be-specified here.-If this option is not specified, pandoc uses the following defaults-depending on the output format specified using \f[C]-t/--to\f[R]:-.RS-.IP \[bu] 2-\f[C]-t latex\f[R] or none: \f[C]pdflatex\f[R] (other options:-\f[C]xelatex\f[R], \f[C]lualatex\f[R], \f[C]tectonic\f[R],-\f[C]latexmk\f[R])-.IP \[bu] 2-\f[C]-t context\f[R]: \f[C]context\f[R]-.IP \[bu] 2-\f[C]-t html\f[R]: \f[C]wkhtmltopdf\f[R] (other options:-\f[C]prince\f[R], \f[C]weasyprint\f[R]; see print-css.rocks for a good-introduction to PDF generation from HTML/CSS.)-.IP \[bu] 2-\f[C]-t ms\f[R]: \f[C]pdfroff\f[R]-.RE-.TP-\f[B]\f[CB]--pdf-engine-opt=\f[B]\f[R]\f[I]STRING\f[R]-Use the given string as a command-line argument to the-\f[C]pdf-engine\f[R].-For example, to use a persistent directory \f[C]foo\f[R] for-\f[C]latexmk\f[R]\[cq]s auxiliary files, use-\f[C]--pdf-engine-opt=-outdir=foo\f[R].-Note that no check for duplicate options is done.-.SS Citation rendering-.TP-\f[B]\f[CB]-C\f[B]\f[R], \f[B]\f[CB]--citeproc\f[B]\f[R]-Process the citations in the file, replacing them with rendered-citations and adding a bibliography.-Citation processing will not take place unless bibliographic data is-supplied, either through an external file specified using the-\f[C]--bibliography\f[R] option or the \f[C]bibliography\f[R] field in-metadata, or via a \f[C]references\f[R] section in metadata containing a-list of citations in CSL YAML format with Markdown formatting.-The style is controlled by a CSL stylesheet specified using the-\f[C]--csl\f[R] option or the \f[C]csl\f[R] field in metadata.-(If no stylesheet is specified, the \f[C]chicago-author-date\f[R] style-will be used by default.)-The citation processing transformation may be applied before or after-filters or Lua filters (see \f[C]--filter\f[R], \f[C]--lua-filter\f[R]):-these transformations are applied in the order they appear on the-command line.-For more information, see the section on Citations.-.TP-\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]-Set the \f[C]bibliography\f[R] field in the document\[cq]s metadata to-\f[I]FILE\f[R], overriding any value set in the metadata.-If you supply this argument multiple times, each \f[I]FILE\f[R] will be-added to bibliography.-If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.-If \f[I]FILE\f[R] is not found relative to the working directory, it-will be sought in the resource path (see \f[C]--resource-path\f[R]).-.TP-\f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R]-Set the \f[C]csl\f[R] field in the document\[cq]s metadata to-\f[I]FILE\f[R], overriding any value set in the metadata.-(This is equivalent to \f[C]--metadata csl=FILE\f[R].)-If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.-If \f[I]FILE\f[R] is not found relative to the working directory, it-will be sought in the resource path (see \f[C]--resource-path\f[R]) and-finally in the \f[C]csl\f[R] subdirectory of the pandoc user data-directory.-.TP-\f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]-Set the \f[C]citation-abbreviations\f[R] field in the document\[cq]s-metadata to \f[I]FILE\f[R], overriding any value set in the metadata.-(This is equivalent to-\f[C]--metadata citation-abbreviations=FILE\f[R].)-If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.-If \f[I]FILE\f[R] is not found relative to the working directory, it-will be sought in the resource path (see \f[C]--resource-path\f[R]) and-finally in the \f[C]csl\f[R] subdirectory of the pandoc user data-directory.-.TP-\f[B]\f[CB]--natbib\f[B]\f[R]-Use \f[C]natbib\f[R] for citations in LaTeX output.-This option is not for use with the \f[C]--citeproc\f[R] option or with-PDF output.-It is intended for use in producing a LaTeX file that can be processed-with \f[C]bibtex\f[R].-.TP-\f[B]\f[CB]--biblatex\f[B]\f[R]-Use \f[C]biblatex\f[R] for citations in LaTeX output.-This option is not for use with the \f[C]--citeproc\f[R] option or with-PDF output.-It is intended for use in producing a LaTeX file that can be processed-with \f[C]bibtex\f[R] or \f[C]biber\f[R].-.SS Math rendering in HTML-.PP-The default is to render TeX math as far as possible using Unicode-characters.-Formulas are put inside a \f[C]span\f[R] with-\f[C]class=\[dq]math\[dq]\f[R], so that they may be styled differently-from the surrounding text if needed.-However, this gives acceptable results only for basic math, usually you-will want to use \f[C]--mathjax\f[R] or another of the following-options.-.TP-\f[B]\f[CB]--mathjax\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]-Use MathJax to display embedded TeX math in HTML output.-TeX math will be put between \f[C]\[rs](...\[rs])\f[R] (for inline math)-or \f[C]\[rs][...\[rs]]\f[R] (for display math) and wrapped in-\f[C]<span>\f[R] tags with class \f[C]math\f[R].-Then the MathJax JavaScript will render it.-The \f[I]URL\f[R] should point to the \f[C]MathJax.js\f[R] load script.-If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be-inserted.-.TP-\f[B]\f[CB]--mathml\f[B]\f[R]-Convert TeX math to MathML (in \f[C]epub3\f[R], \f[C]docbook4\f[R],-\f[C]docbook5\f[R], \f[C]jats\f[R], \f[C]html4\f[R] and-\f[C]html5\f[R]).-This is the default in \f[C]odt\f[R] output.-Note that currently only Firefox and Safari (and select e-book readers)-natively support MathML.-.TP-\f[B]\f[CB]--webtex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]-Convert TeX formulas to \f[C]<img>\f[R] tags that link to an external-script that converts formulas to images.-The formula will be URL-encoded and concatenated with the URL provided.-For SVG images you can for example use-\f[C]--webtex https://latex.codecogs.com/svg.latex?\f[R].-If no URL is specified, the CodeCogs URL generating PNGs will be used-(\f[C]https://latex.codecogs.com/png.latex?\f[R]).-Note: the \f[C]--webtex\f[R] option will affect Markdown output as well-as HTML, which is useful if you\[cq]re targeting a version of Markdown-without native math support.-.TP-\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]-Use KaTeX to display embedded TeX math in HTML output.-The \f[I]URL\f[R] is the base URL for the KaTeX library.-That directory should contain a \f[C]katex.min.js\f[R] and a-\f[C]katex.min.css\f[R] file.-If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be-inserted.-.TP-\f[B]\f[CB]--gladtex\f[B]\f[R]-Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.-The resulting HTML can then be processed by GladTeX to produce SVG-images of the typeset formulas and an HTML file with these images-embedded.-.RS-.IP-.nf-\f[C]-pandoc -s --gladtex input.md -o myfile.htex-gladtex -d image_dir myfile.htex-# produces myfile.html and images in image_dir-\f[R]-.fi-.RE-.SS Options for wrapper scripts-.TP-\f[B]\f[CB]--dump-args\f[B]\f[R]-Print information about command-line arguments to \f[I]stdout\f[R], then-exit.-This option is intended primarily for use in wrapper scripts.-The first line of output contains the name of the output file specified-with the \f[C]-o\f[R] option, or \f[C]-\f[R] (for \f[I]stdout\f[R]) if-no output file was specified.-The remaining lines contain the command-line arguments, one per line, in-the order they appear.-These do not include regular pandoc options and their arguments, but do-include any options appearing after a \f[C]--\f[R] separator at the end-of the line.-.TP-\f[B]\f[CB]--ignore-args\f[B]\f[R]-Ignore command-line arguments (for use in wrapper scripts).-Regular pandoc options are not ignored.-Thus, for example,-.RS-.IP-.nf-\f[C]-pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1-\f[R]-.fi-.PP-is equivalent to-.IP-.nf-\f[C]-pandoc -o foo.html -s-\f[R]-.fi-.RE-.SH EXIT CODES-.PP-If pandoc completes successfully, it will return exit code 0.-Nonzero exit codes have the following meanings:-.PP-.TS-tab(@);-r l.-T{-Code-T}@T{-Error-T}-_-T{-1-T}@T{-PandocIOError-T}-T{-3-T}@T{-PandocFailOnWarningError-T}-T{-4-T}@T{-PandocAppError-T}-T{-5-T}@T{-PandocTemplateError-T}-T{-6-T}@T{-PandocOptionError-T}-T{-21-T}@T{-PandocUnknownReaderError-T}-T{-22-T}@T{-PandocUnknownWriterError-T}-T{-23-T}@T{-PandocUnsupportedExtensionError-T}-T{-24-T}@T{-PandocCiteprocError-T}-T{-25-T}@T{-PandocBibliographyError-T}-T{-31-T}@T{-PandocEpubSubdirectoryError-T}-T{-43-T}@T{-PandocPDFError-T}-T{-44-T}@T{-PandocXMLError-T}-T{-47-T}@T{-PandocPDFProgramNotFoundError-T}-T{-61-T}@T{-PandocHttpError-T}-T{-62-T}@T{-PandocShouldNeverHappenError-T}-T{-63-T}@T{-PandocSomeError-T}-T{-64-T}@T{-PandocParseError-T}-T{-65-T}@T{-PandocParsecError-T}-T{-66-T}@T{-PandocMakePDFError-T}-T{-67-T}@T{-PandocSyntaxMapError-T}-T{-83-T}@T{-PandocFilterError-T}-T{-84-T}@T{-PandocLuaError-T}-T{-91-T}@T{-PandocMacroLoop-T}-T{-92-T}@T{-PandocUTF8DecodingError-T}-T{-93-T}@T{-PandocIpynbDecodingError-T}-T{-94-T}@T{-PandocUnsupportedCharsetError-T}-T{-97-T}@T{-PandocCouldNotFindDataFileError-T}-T{-99-T}@T{-PandocResourceNotFound-T}-.TE-.SH DEFAULT FILES-.PP-The \f[C]--defaults\f[R] option may be used to specify a package of-options.-Here is a sample defaults file demonstrating all of the fields that may-be used:-.IP-.nf-\f[C]-from: markdown+emoji-# reader: may be used instead of from:-to: html5-# writer: may be used instead of to:--# leave blank for output to stdout:-output-file:-# leave blank for input from stdin, use [] for no input:-input-files:-- preface.md-- content.md-# or you may use input-file: with a single value--# Include options from the specified defaults files.-# The files will be searched for first in the working directory-# and then in the defaults subdirectory of the user data directory.-# The files are included in the same order in which they appear in-# the list. Options specified in this defaults file always have-# priority over the included ones.-defaults:-- defsA-- defsB--template: letter-standalone: true-self-contained: false--# note that structured variables may be specified:-variables:-  documentclass: book-  classoption:-    - twosides-    - draft--# metadata values specified here are parsed as literal-# string text, not markdown:-metadata:-  author:-  - Sam Smith-  - Julie Liu-metadata-files:-- boilerplate.yaml-# or you may use metadata-file: with a single value--# Note that these take files, not their contents:-include-before-body: []-include-after-body: []-include-in-header: []-resource-path: [\[dq].\[dq]]--# turn on built-in citation processing.  Note that if you need-# control over when the citeproc processing is done relative-# to other filters, you should instead use \[ga]citeproc\[ga] in the-# list of \[ga]filters\[ga] (see below).-citeproc: true-csl: ieee-bibliography:-- foobar.bib-- barbaz.json-citation-abbreviations: abbrevs.json--# Filters will be assumed to be Lua filters if they have-# the .lua extension, and json filters otherwise.  But-# the filter type can also be specified explicitly, as shown.-# Filters are run in the order specified.-# To include the built-in citeproc filter, use either \[ga]citeproc\[ga]-# or \[ga]{type: citeproc}\[ga].-filters:-- wordcount.lua-- type: json-  path: foo.lua--file-scope: false--data-dir:--# ERROR, WARNING, or INFO-verbosity: INFO-log-file: log.json--# citeproc, natbib, or biblatex. This only affects LaTeX-# output.  If you want to use citeproc to format citations,-# you should also set \[aq]citeproc: true\[aq] (see above).-cite-method: citeproc--# part, chapter, section, or default:-top-level-division: chapter-abbreviations:--pdf-engine: pdflatex-pdf-engine-opts:-- \[dq]-shell-escape\[dq]-# you may also use pdf-engine-opt: with a single option-# pdf-engine-opt: \[dq]-shell-escape\[dq]--# auto, preserve, or none-wrap: auto-columns: 78-dpi: 72--extract-media: mediadir--table-of-contents: true-toc-depth: 2-number-sections: false-# a list of offsets at each heading level-number-offset: [0,0,0,0,0,0]-# toc: may also be used instead of table-of-contents:-shift-heading-level-by: 1-section-divs: true-identifier-prefix: foo-title-prefix: \[dq]\[dq]-strip-empty-paragraphs: true-# lf, crlf, or native-eol: lf-strip-comments: false-indented-code-classes: []-ascii: true-default-image-extension: \[dq].jpg\[dq]--# either a style name of a style definition file:-highlight-style: pygments-syntax-definitions:-- c.xml-# or you may use syntax-definition: with a single value-listings: false--reference-doc: myref.docx--# method is plain, webtex, gladtex, mathml, mathjax, katex-# you may specify a url with webtex, mathjax, katex-html-math-method:-  method: mathjax-  url: \[dq]https://cdn.jsdelivr.net/npm/mathjax\[at]3/es5/tex-mml-chtml.js\[dq]-# none, references, or javascript-email-obfuscation: javascript--tab-stop: 8-preserve-tabs: true--incremental: false-slide-level: 2--epub-subdirectory: EPUB-epub-metadata: meta.xml-epub-fonts:-- foobar.otf-epub-chapter-level: 1-epub-cover-image: cover.jpg--reference-links: true-# block, section, or document-reference-location: block-markdown-headings: setext--# accept, reject, or all-track-changes: accept--html-q-tags: false-css:-- site.css--# none, all, or best-ipynb-output: best--# A list of two-element lists-request-headers:-- [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]--fail-if-warnings: false-dump-args: false-ignore-args: false-trace: false-\f[R]-.fi-.PP-Fields that are omitted will just have their regular default values.-So a defaults file can be as simple as one line:-.IP-.nf-\f[C]-verbosity: INFO-\f[R]-.fi-.PP-In fields that expect a file path (or list of file paths), the following-syntax may be used to interpolate environment variables:-.IP-.nf-\f[C]-csl:  ${HOME}/mycsldir/special.csl-\f[R]-.fi-.PP-\f[C]${USERDATA}\f[R] may also be used; this will always resolve to the-user data directory that is current when the defaults file is parsed,-regardless of the setting of the environment variable-\f[C]USERDATA\f[R].-.PP-\f[C]${.}\f[R] will resolve to the directory containing the default file-itself.-This allows you to refer to resources contained in that directory:-.IP-.nf-\f[C]-epub-cover-image: ${.}/cover.jpg-epub-metadata: ${.}/meta.xml-resource-path:-- .             # the working directory from which pandoc is run-- ${.}/images   # the images subdirectory of the directory-                # containing this defaults file-\f[R]-.fi-.PP-This environment variable interpolation syntax \f[I]only\f[R] works in-fields that expect file paths.-.PP-Default files can be placed in the \f[C]defaults\f[R] subdirectory of-the user data directory and used from any directory.-For example, one could create a file specifying defaults for writing-letters, save it as \f[C]letter.yaml\f[R] in the \f[C]defaults\f[R]-subdirectory of the user data directory, and then invoke these defaults-from any directory using \f[C]pandoc --defaults letter\f[R] or-\f[C]pandoc -dletter\f[R].-.PP-When multiple defaults are used, their contents will be combined.-.PP-Note that, where command-line arguments may be repeated-(\f[C]--metadata-file\f[R], \f[C]--css\f[R],-\f[C]--include-in-header\f[R], \f[C]--include-before-body\f[R],-\f[C]--include-after-body\f[R], \f[C]--variable\f[R],-\f[C]--metadata\f[R], \f[C]--syntax-definition\f[R]), the values-specified on the command line will combine with values specified in the-defaults file, rather than replacing them.-.SH TEMPLATES-.PP-When the \f[C]-s/--standalone\f[R] option is used, pandoc uses a-template to add header and footer material that is needed for a-self-standing document.-To see the default template that is used, just type-.IP-.nf-\f[C]-pandoc -D *FORMAT*-\f[R]-.fi-.PP-where \f[I]FORMAT\f[R] is the name of the output format.-A custom template can be specified using the \f[C]--template\f[R]-option.-You can also override the system default templates for a given output-format \f[I]FORMAT\f[R] by putting a file-\f[C]templates/default.*FORMAT*\f[R] in the user data directory (see-\f[C]--data-dir\f[R], above).-\f[I]Exceptions:\f[R]-.IP \[bu] 2-For \f[C]odt\f[R] output, customize the \f[C]default.opendocument\f[R]-template.-.IP \[bu] 2-For \f[C]pdf\f[R] output, customize the \f[C]default.latex\f[R] template-(or the \f[C]default.context\f[R] template, if you use-\f[C]-t context\f[R], or the \f[C]default.ms\f[R] template, if you use-\f[C]-t ms\f[R], or the \f[C]default.html\f[R] template, if you use-\f[C]-t html\f[R]).-.IP \[bu] 2-\f[C]docx\f[R] and \f[C]pptx\f[R] have no template (however, you can use-\f[C]--reference-doc\f[R] to customize the output).-.PP-Templates contain \f[I]variables\f[R], which allow for the inclusion of-arbitrary information at any point in the file.-They may be set at the command line using the \f[C]-V/--variable\f[R]-option.-If a variable is not set, pandoc will look for the key in the-document\[cq]s metadata, which can be set using either YAML metadata-blocks or with the \f[C]-M/--metadata\f[R] option.-In addition, some variables are given default values by pandoc.-See Variables below for a list of variables used in pandoc\[cq]s default-templates.-.PP-If you use custom templates, you may need to revise them as pandoc-changes.-We recommend tracking the changes in the default templates, and-modifying your custom templates accordingly.-An easy way to do this is to fork the pandoc-templates repository and-merge in changes after each pandoc release.-.SS Template syntax-.SS Comments-.PP-Anything between the sequence \f[C]$--\f[R] and the end of the line will-be treated as a comment and omitted from the output.-.SS Delimiters-.PP-To mark variables and control structures in the template, either-\f[C]$\f[R]\&...\f[C]$\f[R] or \f[C]${\f[R]\&...\f[C]}\f[R] may be used-as delimiters.-The styles may also be mixed in the same template, but the opening and-closing delimiter must match in each case.-The opening delimiter may be followed by one or more spaces or tabs,-which will be ignored.-The closing delimiter may be followed by one or more spaces or tabs,-which will be ignored.-.PP-To include a literal \f[C]$\f[R] in the document, use \f[C]$$\f[R].-.SS Interpolated variables-.PP-A slot for an interpolated variable is a variable name surrounded by-matched delimiters.-Variable names must begin with a letter and can contain letters,-numbers, \f[C]_\f[R], \f[C]-\f[R], and \f[C].\f[R].-The keywords \f[C]it\f[R], \f[C]if\f[R], \f[C]else\f[R],-\f[C]endif\f[R], \f[C]for\f[R], \f[C]sep\f[R], and \f[C]endfor\f[R] may-not be used as variable names.-Examples:-.IP-.nf-\f[C]-$foo$-$foo.bar.baz$-$foo_bar.baz-bim$-$ foo $-${foo}-${foo.bar.baz}-${foo_bar.baz-bim}-${ foo }-\f[R]-.fi-.PP-Variable names with periods are used to get at structured variable-values.-So, for example, \f[C]employee.salary\f[R] will return the value of the-\f[C]salary\f[R] field of the object that is the value of the-\f[C]employee\f[R] field.-.IP \[bu] 2-If the value of the variable is simple value, it will be rendered-verbatim.-(Note that no escaping is done; the assumption is that the calling-program will escape the strings appropriately for the output format.)-.IP \[bu] 2-If the value is a list, the values will be concatenated.-.IP \[bu] 2-If the value is a map, the string \f[C]true\f[R] will be rendered.-.IP \[bu] 2-Every other value will be rendered as the empty string.-.SS Conditionals-.PP-A conditional begins with \f[C]if(variable)\f[R] (enclosed in matched-delimiters) and ends with \f[C]endif\f[R] (enclosed in matched-delimiters).-It may optionally contain an \f[C]else\f[R] (enclosed in matched-delimiters).-The \f[C]if\f[R] section is used if \f[C]variable\f[R] has a non-empty-value, otherwise the \f[C]else\f[R] section is used (if present).-Examples:-.IP-.nf-\f[C]-$if(foo)$bar$endif$--$if(foo)$-  $foo$-$endif$--$if(foo)$-part one-$else$-part two-$endif$--${if(foo)}bar${endif}--${if(foo)}-  ${foo}-${endif}--${if(foo)}-${ foo.bar }-${else}-no foo!-${endif}-\f[R]-.fi-.PP-The keyword \f[C]elseif\f[R] may be used to simplify complex nested-conditionals:-.IP-.nf-\f[C]-$if(foo)$-XXX-$elseif(bar)$-YYY-$else$-ZZZ-$endif$-\f[R]-.fi-.SS For loops-.PP-A for loop begins with \f[C]for(variable)\f[R] (enclosed in matched-delimiters) and ends with \f[C]endfor\f[R] (enclosed in matched-delimiters.-.IP \[bu] 2-If \f[C]variable\f[R] is an array, the material inside the loop will be-evaluated repeatedly, with \f[C]variable\f[R] being set to each value of-the array in turn, and concatenated.-.IP \[bu] 2-If \f[C]variable\f[R] is a map, the material inside will be set to the-map.-.IP \[bu] 2-If the value of the associated variable is not an array or a map, a-single iteration will be performed on its value.-.PP-Examples:-.IP-.nf-\f[C]-$for(foo)$$foo$$sep$, $endfor$--$for(foo)$-  - $foo.last$, $foo.first$-$endfor$--${ for(foo.bar) }-  - ${ foo.bar.last }, ${ foo.bar.first }-${ endfor }--$for(mymap)$-$it.name$: $it.office$-$endfor$-\f[R]-.fi-.PP-You may optionally specify a separator between consecutive values using-\f[C]sep\f[R] (enclosed in matched delimiters).-The material between \f[C]sep\f[R] and the \f[C]endfor\f[R] is the-separator.-.IP-.nf-\f[C]-${ for(foo) }${ foo }${ sep }, ${ endfor }-\f[R]-.fi-.PP-Instead of using \f[C]variable\f[R] inside the loop, the special-anaphoric keyword \f[C]it\f[R] may be used.-.IP-.nf-\f[C]-${ for(foo.bar) }-  - ${ it.last }, ${ it.first }-${ endfor }-\f[R]-.fi-.SS Partials-.PP-Partials (subtemplates stored in different files) may be included by-using the name of the partial, followed by \f[C]()\f[R], for example:-.IP-.nf-\f[C]-${ styles() }-\f[R]-.fi-.PP-Partials will be sought in the directory containing the main template.-The file name will be assumed to have the same extension as the main-template if it lacks an extension.-When calling the partial, the full name including file extension can-also be used:-.IP-.nf-\f[C]-${ styles.html() }-\f[R]-.fi-.PP-(If a partial is not found in the directory of the template and the-template path is given as a relative path, it will also be sought in the-\f[C]templates\f[R] subdirectory of the user data directory.)-.PP-Partials may optionally be applied to variables using a colon:-.IP-.nf-\f[C]-${ date:fancy() }--${ articles:bibentry() }-\f[R]-.fi-.PP-If \f[C]articles\f[R] is an array, this will iterate over its values,-applying the partial \f[C]bibentry()\f[R] to each one.-So the second example above is equivalent to-.IP-.nf-\f[C]-${ for(articles) }-${ it:bibentry() }-${ endfor }-\f[R]-.fi-.PP-Note that the anaphoric keyword \f[C]it\f[R] must be used when iterating-over partials.-In the above examples, the \f[C]bibentry\f[R] partial should contain-\f[C]it.title\f[R] (and so on) instead of \f[C]articles.title\f[R].-.PP-Final newlines are omitted from included partials.-.PP-Partials may include other partials.-.PP-A separator between values of an array may be specified in square-brackets, immediately after the variable name or partial:-.IP-.nf-\f[C]-${months[, ]}$--${articles:bibentry()[; ]$-\f[R]-.fi-.PP-The separator in this case is literal and (unlike with \f[C]sep\f[R] in-an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or-other template directives.-.SS Nesting-.PP-To ensure that content is \[lq]nested,\[rq] that is, subsequent lines-indented, use the \f[C]\[ha]\f[R] directive:-.IP-.nf-\f[C]-$item.number$  $\[ha]$$item.description$ ($item.price$)-\f[R]-.fi-.PP-In this example, if \f[C]item.description\f[R] has multiple lines, they-will all be indented to line up with the first line:-.IP-.nf-\f[C]-00123  A fine bottle of 18-year old-       Oban whiskey. ($148)-\f[R]-.fi-.PP-To nest multiple lines to the same level, align them with the-\f[C]\[ha]\f[R] directive in the template.-For example:-.IP-.nf-\f[C]-$item.number$  $\[ha]$$item.description$ ($item.price$)-               (Available til $item.sellby$.)-\f[R]-.fi-.PP-will produce-.IP-.nf-\f[C]-00123  A fine bottle of 18-year old-       Oban whiskey. ($148)-       (Available til March 30, 2020.)-\f[R]-.fi-.PP-If a variable occurs by itself on a line, preceded by whitespace and not-followed by further text or directives on the same line, and the-variable\[cq]s value contains multiple lines, it will be nested-automatically.-.SS Breakable spaces-.PP-Normally, spaces in the template itself (as opposed to values of the-interpolated variables) are not breakable, but they can be made-breakable in part of the template by using the \f[C]\[ti]\f[R] keyword-(ended with another \f[C]\[ti]\f[R]).-.IP-.nf-\f[C]-$\[ti]$This long line may break if the document is rendered-with a short line length.$\[ti]$-\f[R]-.fi-.SS Pipes-.PP-A pipe transforms the value of a variable or partial.-Pipes are specified using a slash (\f[C]/\f[R]) between the variable-name (or partial) and the pipe name.-Example:-.IP-.nf-\f[C]-$for(name)$-$name/uppercase$-$endfor$--$for(metadata/pairs)$-- $it.key$: $it.value$-$endfor$--$employee:name()/uppercase$-\f[R]-.fi-.PP-Pipes may be chained:-.IP-.nf-\f[C]-$for(employees/pairs)$-$it.key/alpha/uppercase$. $it.name$-$endfor$-\f[R]-.fi-.PP-Some pipes take parameters:-.IP-.nf-\f[C]-|----------------------|------------|-$for(employee)$-$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$-$endfor$-|----------------------|------------|-\f[R]-.fi-.PP-Currently the following pipes are predefined:-.IP \[bu] 2-\f[C]pairs\f[R]: Converts a map or array to an array of maps, each with-\f[C]key\f[R] and \f[C]value\f[R] fields.-If the original value was an array, the \f[C]key\f[R] will be the array-index, starting with 1.-.IP \[bu] 2-\f[C]uppercase\f[R]: Converts text to uppercase.-.IP \[bu] 2-\f[C]lowercase\f[R]: Converts text to lowercase.-.IP \[bu] 2-\f[C]length\f[R]: Returns the length of the value: number of characters-for a textual value, number of elements for a map or array.-.IP \[bu] 2-\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect-on other values.-.IP \[bu] 2-\f[C]first\f[R]: Returns the first value of an array, if applied to a-non-empty array; otherwise returns the original value.-.IP \[bu] 2-\f[C]last\f[R]: Returns the last value of an array, if applied to a-non-empty array; otherwise returns the original value.-.IP \[bu] 2-\f[C]rest\f[R]: Returns all but the first value of an array, if applied-to a non-empty array; otherwise returns the original value.-.IP \[bu] 2-\f[C]allbutlast\f[R]: Returns all but the last value of an array, if-applied to a non-empty array; otherwise returns the original value.-.IP \[bu] 2-\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).-.IP \[bu] 2-\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.-.IP \[bu] 2-\f[C]alpha\f[R]: Converts textual values that can be read as an integer-into lowercase alphabetic characters \f[C]a..z\f[R] (mod 26).-This can be used to get lettered enumeration from array indices.-To get uppercase letters, chain with \f[C]uppercase\f[R].-.IP \[bu] 2-\f[C]roman\f[R]: Converts textual values that can be read as an integer-into lowercase roman numerials.-This can be used to get lettered enumeration from array indices.-To get uppercase roman, chain with \f[C]uppercase\f[R].-.IP \[bu] 2-\f[C]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a-textual value in a block of width \f[C]n\f[R], aligned to the left, with-an optional left and right border.-Has no effect on other values.-This can be used to align material in tables.-Widths are positive integers indicating the number of characters.-Borders are strings inside double quotes; literal \f[C]\[dq]\f[R] and-\f[C]\[rs]\f[R] characters must be backslash-escaped.-.IP \[bu] 2-\f[C]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a-textual value in a block of width \f[C]n\f[R], aligned to the right, and-has no effect on other values.-.IP \[bu] 2-\f[C]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a-textual value in a block of width \f[C]n\f[R], aligned to the center,-and has no effect on other values.-.SS Variables-.SS Metadata variables-.TP-\f[B]\f[CB]title\f[B]\f[R], \f[B]\f[CB]author\f[B]\f[R], \f[B]\f[CB]date\f[B]\f[R]-allow identification of basic aspects of the document.-Included in PDF metadata through LaTeX and ConTeXt.-These can be set through a pandoc title block, which allows for multiple-authors, or through a YAML metadata block:-.RS-.IP-.nf-\f[C]-----author:-- Aristotle-- Peter Abelard-\&...-\f[R]-.fi-.PP-Note that if you just want to set PDF or HTML metadata, without-including a title block in the document itself, you can set the-\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]-variables.-(By default these are set automatically, based on \f[C]title\f[R],-\f[C]author\f[R], and \f[C]date\f[R].)-The page title in HTML is set by \f[C]pagetitle\f[R], which is equal to-\f[C]title\f[R] by default.-.RE-.TP-\f[B]\f[CB]subtitle\f[B]\f[R]-document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx-documents-.TP-\f[B]\f[CB]abstract\f[B]\f[R]-document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx-documents-.TP-\f[B]\f[CB]abstract-title\f[B]\f[R]-title of abstract, currently used only in HTML and EPUB.-This will be set automatically to a localized value, depending on-\f[C]lang\f[R], but can be manually overridden.-.TP-\f[B]\f[CB]keywords\f[B]\f[R]-list of keywords to be included in HTML, PDF, ODT, pptx, docx and-AsciiDoc metadata; repeat as for \f[C]author\f[R], above-.TP-\f[B]\f[CB]subject\f[B]\f[R]-document subject, included in ODT, PDF, docx, EPUB, and pptx metadata-.TP-\f[B]\f[CB]description\f[B]\f[R]-document description, included in ODT, docx and pptx metadata.-Some applications show this as \f[C]Comments\f[R] metadata.-.TP-\f[B]\f[CB]category\f[B]\f[R]-document category, included in docx and pptx metadata-.PP-Additionally, any root-level string metadata, not included in ODT, docx-or pptx metadata is added as a \f[I]custom property\f[R].-The following YAML metadata block for instance:-.IP-.nf-\f[C]-----title:  \[aq]This is the title\[aq]-subtitle: \[dq]This is the subtitle\[dq]-author:-- Author One-- Author Two-description: |-    This is a long-    description.--    It consists of two paragraphs-\&...-\f[R]-.fi-.PP-will include \f[C]title\f[R], \f[C]author\f[R] and \f[C]description\f[R]-as standard document properties and \f[C]subtitle\f[R] as a custom-property when converting to docx, ODT or pptx.-.SS Language variables-.TP-\f[B]\f[CB]lang\f[B]\f[R]-identifies the main language of the document using IETF language tags-(following the BCP 47 standard), such as \f[C]en\f[R] or-\f[C]en-GB\f[R].-The Language subtag lookup tool can look up or verify these tags.-This affects most formats, and controls hyphenation in PDF output when-using LaTeX (through \f[C]babel\f[R] and \f[C]polyglossia\f[R]) or-ConTeXt.-.RS-.PP-Use native pandoc Divs and Spans with the \f[C]lang\f[R] attribute to-switch the language:-.IP-.nf-\f[C]-----lang: en-GB-\&...--Text in the main document language (British English).--::: {lang=fr-CA}-> Cette citation est \['e]crite en fran\[,c]ais canadien.-:::--More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]dir\f[B]\f[R]-the base script direction, either \f[C]rtl\f[R] (right-to-left) or-\f[C]ltr\f[R] (left-to-right).-.RS-.PP-For bidirectional documents, native pandoc \f[C]span\f[R]s and-\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or-\f[C]ltr\f[R]) can be used to override the base direction in some output-formats.-This may not always be necessary if the final renderer (e.g.\ the-browser, when generating HTML) supports the Unicode Bidirectional-Algorithm.-.PP-When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]-engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).-.RE-.SS Variables for HTML-.TP-\f[B]\f[CB]document-css\f[B]\f[R]-Enables inclusion of most of the CSS in the \f[C]styles.html\f[R]-partial (have a look with-\f[C]pandoc --print-default-data-file=templates/styles.html\f[R]).-Unless you use \f[C]--css\f[R], this variable is set to \f[C]true\f[R]-by default.-You can disable it with e.g.\ \f[C]pandoc -M document-css=false\f[R].-.TP-\f[B]\f[CB]mainfont\f[B]\f[R]-sets the CSS \f[C]font-family\f[R] property on the \f[C]html\f[R]-element.-.TP-\f[B]\f[CB]fontsize\f[B]\f[R]-sets the base CSS \f[C]font-size\f[R], which you\[cq]d usually set to-e.g.\ \f[C]20px\f[R], but it also accepts \f[C]pt\f[R] (12pt = 16px in-most browsers).-.TP-\f[B]\f[CB]fontcolor\f[B]\f[R]-sets the CSS \f[C]color\f[R] property on the \f[C]html\f[R] element.-.TP-\f[B]\f[CB]linkcolor\f[B]\f[R]-sets the CSS \f[C]color\f[R] property on all links.-.TP-\f[B]\f[CB]monofont\f[B]\f[R]-sets the CSS \f[C]font-family\f[R] property on \f[C]code\f[R] elements.-.TP-\f[B]\f[CB]monobackgroundcolor\f[B]\f[R]-sets the CSS \f[C]background-color\f[R] property on \f[C]code\f[R]-elements and adds extra padding.-.TP-\f[B]\f[CB]linestretch\f[B]\f[R]-sets the CSS \f[C]line-height\f[R] property on the \f[C]html\f[R]-element, which is preferred to be unitless.-.TP-\f[B]\f[CB]backgroundcolor\f[B]\f[R]-sets the CSS \f[C]background-color\f[R] property on the \f[C]html\f[R]-element.-.TP-\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]-sets the corresponding CSS \f[C]padding\f[R] properties on the-\f[C]body\f[R] element.-.PP-To override or extend some CSS for just one document, include for-example:-.IP-.nf-\f[C]-----header-includes: |-  <style>-  blockquote {-    font-style: italic;-  }-  tr.even {-    background-color: #f0f0f0;-  }-  td, th {-    padding: 0.5em 2em 0.5em 0.5em;-  }-  tbody {-    border-bottom: none;-  }-  </style>-----\f[R]-.fi-.SS Variables for HTML math-.TP-\f[B]\f[CB]classoption\f[B]\f[R]-when using KaTeX, you can render display math equations flush left using-YAML metadata or with \f[C]-M classoption=fleqn\f[R].-.SS Variables for HTML slides-.PP-These affect HTML output when [producing slide shows with pandoc].-.TP-\f[B]\f[CB]institute\f[B]\f[R]-author affiliations: can be a list when there are multiple authors-.TP-\f[B]\f[CB]revealjs-url\f[B]\f[R]-base URL for reveal.js documents (defaults to-\f[C]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R])-.TP-\f[B]\f[CB]s5-url\f[B]\f[R]-base URL for S5 documents (defaults to \f[C]s5/default\f[R])-.TP-\f[B]\f[CB]slidy-url\f[B]\f[R]-base URL for Slidy documents (defaults to-\f[C]https://www.w3.org/Talks/Tools/Slidy2\f[R])-.TP-\f[B]\f[CB]slideous-url\f[B]\f[R]-base URL for Slideous documents (defaults to \f[C]slideous\f[R])-.TP-\f[B]\f[CB]title-slide-attributes\f[B]\f[R]-additional attributes for the title slide of reveal.js slide shows.-See [background in reveal.js and beamer] for an example.-.PP-All reveal.js configuration options are available as variables.-To turn off boolean flags that default to true in reveal.js, use-\f[C]0\f[R].-.SS Variables for Beamer slides-.PP-These variables change the appearance of PDF slides using-\f[C]beamer\f[R].-.TP-\f[B]\f[CB]aspectratio\f[B]\f[R]-slide aspect ratio (\f[C]43\f[R] for 4:3 [default], \f[C]169\f[R] for-16:9, \f[C]1610\f[R] for 16:10, \f[C]149\f[R] for 14:9, \f[C]141\f[R]-for 1.41:1, \f[C]54\f[R] for 5:4, \f[C]32\f[R] for 3:2)-.TP-\f[B]\f[CB]beamerarticle\f[B]\f[R]-produce an article from Beamer slides-.TP-\f[B]\f[CB]beameroption\f[B]\f[R]-add extra beamer option with \f[C]\[rs]setbeameroption{}\f[R]-.TP-\f[B]\f[CB]institute\f[B]\f[R]-author affiliations: can be a list when there are multiple authors-.TP-\f[B]\f[CB]logo\f[B]\f[R]-logo image for slides-.TP-\f[B]\f[CB]navigation\f[B]\f[R]-controls navigation symbols (default is \f[C]empty\f[R] for no-navigation symbols; other valid values are \f[C]frame\f[R],-\f[C]vertical\f[R], and \f[C]horizontal\f[R])-.TP-\f[B]\f[CB]section-titles\f[B]\f[R]-enables \[lq]title pages\[rq] for new sections (default is true)-.TP-\f[B]\f[CB]theme\f[B]\f[R], \f[B]\f[CB]colortheme\f[B]\f[R], \f[B]\f[CB]fonttheme\f[B]\f[R], \f[B]\f[CB]innertheme\f[B]\f[R], \f[B]\f[CB]outertheme\f[B]\f[R]-beamer themes-.TP-\f[B]\f[CB]themeoptions\f[B]\f[R]-options for LaTeX beamer themes (a list).-.TP-\f[B]\f[CB]titlegraphic\f[B]\f[R]-image for title slide-.SS Variables for PowerPoint-.PP-These variables control the visual aspects of a slide show that are not-easily controlled via templates.-.TP-\f[B]\f[CB]monofont\f[B]\f[R]-font to use for code.-.SS Variables for LaTeX-.PP-Pandoc uses these variables when creating a PDF with a LaTeX engine.-.SS Layout-.TP-\f[B]\f[CB]block-headings\f[B]\f[R]-make \f[C]\[rs]paragraph\f[R] and \f[C]\[rs]subparagraph\f[R] (fourth--and fifth-level headings, or fifth- and sixth-level with book classes)-free-standing rather than run-in; requires further formatting to-distinguish from \f[C]\[rs]subsubsection\f[R] (third- or fourth-level-headings).-Instead of using this option, KOMA-Script can adjust headings more-extensively:-.RS-.IP-.nf-\f[C]-----documentclass: scrartcl-header-includes: |-  \[rs]RedeclareSectionCommand[-    beforeskip=-10pt plus -2pt minus -1pt,-    afterskip=1sp plus -1sp minus 1sp,-    font=\[rs]normalfont\[rs]itshape]{paragraph}-  \[rs]RedeclareSectionCommand[-    beforeskip=-10pt plus -2pt minus -1pt,-    afterskip=1sp plus -1sp minus 1sp,-    font=\[rs]normalfont\[rs]scshape,-    indent=0pt]{subparagraph}-\&...-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]classoption\f[B]\f[R]-option for document class, e.g.\ \f[C]oneside\f[R]; repeat for multiple-options:-.RS-.IP-.nf-\f[C]-----classoption:-- twocolumn-- landscape-\&...-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]documentclass\f[B]\f[R]-document class: usually one of the standard classes, \f[C]article\f[R],-\f[C]book\f[R], and \f[C]report\f[R]; the KOMA-Script equivalents,-\f[C]scrartcl\f[R], \f[C]scrbook\f[R], and \f[C]scrreprt\f[R], which-default to smaller margins; or \f[C]memoir\f[R]-.TP-\f[B]\f[CB]geometry\f[B]\f[R]-option for \f[C]geometry\f[R] package, e.g.\ \f[C]margin=1in\f[R];-repeat for multiple options:-.RS-.IP-.nf-\f[C]-----geometry:-- top=30mm-- left=20mm-- heightrounded-\&...-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]hyperrefoptions\f[B]\f[R]-option for \f[C]hyperref\f[R] package, e.g.\ \f[C]linktoc=all\f[R];-repeat for multiple options:-.RS-.IP-.nf-\f[C]-----hyperrefoptions:-- linktoc=all-- pdfwindowui-- pdfpagemode=FullScreen-\&...-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]indent\f[B]\f[R]-if true, pandoc will use document class settings for indentation (the-default LaTeX template otherwise removes indentation and adds space-between paragraphs)-.TP-\f[B]\f[CB]linestretch\f[B]\f[R]-adjusts line spacing using the \f[C]setspace\f[R] package,-e.g.\ \f[C]1.25\f[R], \f[C]1.5\f[R]-.TP-\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]-sets margins if \f[C]geometry\f[R] is not used (otherwise-\f[C]geometry\f[R] overrides these)-.TP-\f[B]\f[CB]pagestyle\f[B]\f[R]-control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports-\f[C]plain\f[R] (default), \f[C]empty\f[R] (no running heads or page-numbers), and \f[C]headings\f[R] (section titles in running heads)-.TP-\f[B]\f[CB]papersize\f[B]\f[R]-paper size, e.g.\ \f[C]letter\f[R], \f[C]a4\f[R]-.TP-\f[B]\f[CB]secnumdepth\f[B]\f[R]-numbering depth for sections (with \f[C]--number-sections\f[R] option or-\f[C]numbersections\f[R] variable)-.SS Fonts-.TP-\f[B]\f[CB]fontenc\f[B]\f[R]-allows font encoding to be specified through \f[C]fontenc\f[R] package-(with \f[C]pdflatex\f[R]); default is \f[C]T1\f[R] (see LaTeX font-encodings guide)-.TP-\f[B]\f[CB]fontfamily\f[B]\f[R]-font package for use with \f[C]pdflatex\f[R]: TeX Live includes many-options, documented in the LaTeX Font Catalogue.-The default is Latin Modern.-.TP-\f[B]\f[CB]fontfamilyoptions\f[B]\f[R]-options for package used as \f[C]fontfamily\f[R]; repeat for multiple-options.-For example, to use the Libertine font with proportional lowercase-(old-style) figures through the \f[C]libertinus\f[R] package:-.RS-.IP-.nf-\f[C]-----fontfamily: libertinus-fontfamilyoptions:-- osf-- p-\&...-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]fontsize\f[B]\f[R]-font size for body text.-The standard classes allow 10pt, 11pt, and 12pt.-To use another size, set \f[C]documentclass\f[R] to one of the-KOMA-Script classes, such as \f[C]scrartcl\f[R] or \f[C]scrbook\f[R].-.TP-\f[B]\f[CB]mainfont\f[B]\f[R], \f[B]\f[CB]sansfont\f[B]\f[R], \f[B]\f[CB]monofont\f[B]\f[R], \f[B]\f[CB]mathfont\f[B]\f[R], \f[B]\f[CB]CJKmainfont\f[B]\f[R]-font families for use with \f[C]xelatex\f[R] or \f[C]lualatex\f[R]: take-the name of any system font, using the \f[C]fontspec\f[R] package.-\f[C]CJKmainfont\f[R] uses the \f[C]xecjk\f[R] package.-.TP-\f[B]\f[CB]mainfontoptions\f[B]\f[R], \f[B]\f[CB]sansfontoptions\f[B]\f[R], \f[B]\f[CB]monofontoptions\f[B]\f[R], \f[B]\f[CB]mathfontoptions\f[B]\f[R], \f[B]\f[CB]CJKoptions\f[B]\f[R]-options to use with \f[C]mainfont\f[R], \f[C]sansfont\f[R],-\f[C]monofont\f[R], \f[C]mathfont\f[R], \f[C]CJKmainfont\f[R] in-\f[C]xelatex\f[R] and \f[C]lualatex\f[R].-Allow for any choices available through \f[C]fontspec\f[R]; repeat for-multiple options.-For example, to use the TeX Gyre version of Palatino with lowercase-figures:-.RS-.IP-.nf-\f[C]-----mainfont: TeX Gyre Pagella-mainfontoptions:-- Numbers=Lowercase-- Numbers=Proportional-\&...-\f[R]-.fi-.RE-.TP-\f[B]\f[CB]microtypeoptions\f[B]\f[R]-options to pass to the microtype package-.SS Links-.TP-\f[B]\f[CB]colorlinks\f[B]\f[R]-add color to link text; automatically enabled if any of-\f[C]linkcolor\f[R], \f[C]filecolor\f[R], \f[C]citecolor\f[R],-\f[C]urlcolor\f[R], or \f[C]toccolor\f[R] are set-.TP-\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]filecolor\f[B]\f[R], \f[B]\f[CB]citecolor\f[B]\f[R], \f[B]\f[CB]urlcolor\f[B]\f[R], \f[B]\f[CB]toccolor\f[B]\f[R]-color for internal links, external links, citation links, linked URLs,-and links in table of contents, respectively: uses options allowed by-\f[C]xcolor\f[R], including the \f[C]dvipsnames\f[R],-\f[C]svgnames\f[R], and \f[C]x11names\f[R] lists-.TP-\f[B]\f[CB]links-as-notes\f[B]\f[R]-causes links to be printed as footnotes-.SS Front matter-.TP-\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]-include list of figures, list of tables-.TP-\f[B]\f[CB]thanks\f[B]\f[R]-contents of acknowledgments footnote after document title-.TP-\f[B]\f[CB]toc\f[B]\f[R]-include table of contents (can also be set using-\f[C]--toc/--table-of-contents\f[R])-.TP-\f[B]\f[CB]toc-depth\f[B]\f[R]-level of section to include in table of contents-.SS BibLaTeX Bibliographies-.PP-These variables function when using BibLaTeX for citation rendering.-.TP-\f[B]\f[CB]biblatexoptions\f[B]\f[R]-list of options for biblatex-.TP-\f[B]\f[CB]biblio-style\f[B]\f[R]-bibliography style, when used with \f[C]--natbib\f[R] and-\f[C]--biblatex\f[R].-.TP-\f[B]\f[CB]biblio-title\f[B]\f[R]-bibliography title, when used with \f[C]--natbib\f[R] and-\f[C]--biblatex\f[R].-.TP-\f[B]\f[CB]bibliography\f[B]\f[R]-bibliography to use for resolving references-.TP-\f[B]\f[CB]natbiboptions\f[B]\f[R]-list of options for natbib-.SS Variables for ConTeXt-.PP-Pandoc uses these variables when creating a PDF with ConTeXt.-.TP-\f[B]\f[CB]fontsize\f[B]\f[R]-font size for body text (e.g.\ \f[C]10pt\f[R], \f[C]12pt\f[R])-.TP-\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]-text to be placed in running header or footer (see ConTeXt Headers and-Footers); repeat up to four times for different placement-.TP-\f[B]\f[CB]indenting\f[B]\f[R]-controls indentation of paragraphs, e.g.\ \f[C]yes,small,next\f[R] (see-ConTeXt Indentation); repeat for multiple options-.TP-\f[B]\f[CB]interlinespace\f[B]\f[R]-adjusts line spacing, e.g.\ \f[C]4ex\f[R] (using-\f[C]setupinterlinespace\f[R]); repeat for multiple options-.TP-\f[B]\f[CB]layout\f[B]\f[R]-options for page margins and text arrangement (see ConTeXt Layout);-repeat for multiple options-.TP-\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]-color for links outside and inside a page, e.g.\ \f[C]red\f[R],-\f[C]blue\f[R] (see ConTeXt Color)-.TP-\f[B]\f[CB]linkstyle\f[B]\f[R]-typeface style for links, e.g.\ \f[C]normal\f[R], \f[C]bold\f[R],-\f[C]slanted\f[R], \f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R],-\f[C]small\f[R]-.TP-\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]-include list of figures, list of tables-.TP-\f[B]\f[CB]mainfont\f[B]\f[R], \f[B]\f[CB]sansfont\f[B]\f[R], \f[B]\f[CB]monofont\f[B]\f[R], \f[B]\f[CB]mathfont\f[B]\f[R]-font families: take the name of any system font (see ConTeXt Font-Switching)-.TP-\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]-sets margins, if \f[C]layout\f[R] is not used (otherwise-\f[C]layout\f[R] overrides these)-.TP-\f[B]\f[CB]pagenumbering\f[B]\f[R]-page number style and location (using \f[C]setuppagenumbering\f[R]);-repeat for multiple options-.TP-\f[B]\f[CB]papersize\f[B]\f[R]-paper size, e.g.\ \f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R]-(see ConTeXt Paper Setup); repeat for multiple options-.TP-\f[B]\f[CB]pdfa\f[B]\f[R]-adds to the preamble the setup necessary to generate PDF/A of the type-specified, e.g.\ \f[C]1a:2005\f[R], \f[C]2a\f[R].-If no type is specified (i.e.\ the value is set to True, by e.g.-\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata-block), \f[C]1b:2005\f[R] will be used as default, for reasons of-backwards compatibility.-Using \f[C]--variable=pdfa\f[R] without specified value is not-supported.-To successfully generate PDF/A the required ICC color profiles have to-be available and the content and all included files (such as images)-have to be standard conforming.-The ICC profiles and output intent may be specified using the variables-\f[C]pdfaiccprofile\f[R] and \f[C]pdfaintent\f[R].-See also ConTeXt PDFA for more details.-.TP-\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]-when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile-to use in the PDF, e.g.\ \f[C]default.cmyk\f[R].-If left unspecified, \f[C]sRGB.icc\f[R] is used as default.-May be repeated to include multiple profiles.-Note that the profiles have to be available on the system.-They can be obtained from ConTeXt ICC Profiles.-.TP-\f[B]\f[CB]pdfaintent\f[B]\f[R]-when used in conjunction with \f[C]pdfa\f[R], specifies the output-intent for the colors,-e.g.\ \f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If-left unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.-.TP-\f[B]\f[CB]toc\f[B]\f[R]-include table of contents (can also be set using-\f[C]--toc/--table-of-contents\f[R])-.TP-\f[B]\f[CB]whitespace\f[B]\f[R]-spacing between paragraphs, e.g.\ \f[C]none\f[R], \f[C]small\f[R] (using-\f[C]setupwhitespace\f[R])-.TP-\f[B]\f[CB]includesource\f[B]\f[R]-include all source documents as file attachments in the PDF file-.SS Variables for \f[C]wkhtmltopdf\f[R]-.PP-Pandoc uses these variables when creating a PDF with-\f[C]wkhtmltopdf\f[R].-The \f[C]--css\f[R] option also affects the output.-.TP-\f[B]\f[CB]footer-html\f[B]\f[R], \f[B]\f[CB]header-html\f[B]\f[R]-add information to the header and footer-.TP-\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]-set the page margins-.TP-\f[B]\f[CB]papersize\f[B]\f[R]-sets the PDF paper size-.SS Variables for man pages-.TP-\f[B]\f[CB]adjusting\f[B]\f[R]-adjusts text to left (\f[C]l\f[R]), right (\f[C]r\f[R]), center-(\f[C]c\f[R]), or both (\f[C]b\f[R]) margins-.TP-\f[B]\f[CB]footer\f[B]\f[R]-footer in man pages-.TP-\f[B]\f[CB]header\f[B]\f[R]-header in man pages-.TP-\f[B]\f[CB]hyphenate\f[B]\f[R]-if \f[C]true\f[R] (the default), hyphenation will be used-.TP-\f[B]\f[CB]section\f[B]\f[R]-section number in man pages-.SS Variables for ms-.TP-\f[B]\f[CB]fontfamily\f[B]\f[R]-font family (e.g.\ \f[C]T\f[R] or \f[C]P\f[R])-.TP-\f[B]\f[CB]indent\f[B]\f[R]-paragraph indent (e.g.\ \f[C]2m\f[R])-.TP-\f[B]\f[CB]lineheight\f[B]\f[R]-line height (e.g.\ \f[C]12p\f[R])-.TP-\f[B]\f[CB]pointsize\f[B]\f[R]-point size (e.g.\ \f[C]10p\f[R])-.SS Variables set automatically-.PP-Pandoc sets these variables automatically in response to options or-document contents; users can also modify them.-These vary depending on the output format, and include the following:-.TP-\f[B]\f[CB]body\f[B]\f[R]-body of document-.TP-\f[B]\f[CB]date-meta\f[B]\f[R]-the \f[C]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included-in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,-s5, slideous, slidy).-The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],-\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),-\f[C]dd MM yyyy\f[R] (e.g.\ either \f[C]02 Apr 2018\f[R] or-\f[C]02 April 2018\f[R]), \f[C]MM dd, yyyy\f[R]-(e.g.\ \f[C]Apr. 02, 2018\f[R] or-\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,-\f[C]201804\f[R] or \f[C]2018\f[R]).-.TP-\f[B]\f[CB]header-includes\f[B]\f[R]-contents specified by \f[C]-H/--include-in-header\f[R] (may have-multiple values)-.TP-\f[B]\f[CB]include-before\f[B]\f[R]-contents specified by \f[C]-B/--include-before-body\f[R] (may have-multiple values)-.TP-\f[B]\f[CB]include-after\f[B]\f[R]-contents specified by \f[C]-A/--include-after-body\f[R] (may have-multiple values)-.TP-\f[B]\f[CB]meta-json\f[B]\f[R]-JSON representation of all of the document\[cq]s metadata.-Field values are transformed to the selected output format.-.TP-\f[B]\f[CB]numbersections\f[B]\f[R]-non-null value if \f[C]-N/--number-sections\f[R] was specified-.TP-\f[B]\f[CB]sourcefile\f[B]\f[R], \f[B]\f[CB]outputfile\f[B]\f[R]-source and destination filenames, as given on the command line.-\f[C]sourcefile\f[R] can also be a list if input comes from multiple-files, or empty if input is from stdin.-You can use the following snippet in your template to distinguish them:-.RS-.IP-.nf-\f[C]-$if(sourcefile)$-$for(sourcefile)$-$sourcefile$-$endfor$-$else$-(stdin)-$endif$-\f[R]-.fi-.PP-Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the-terminal.-.PP-If you need absolute paths, use e.g.\ \f[C]$curdir$/$sourcefile$\f[R].-.RE-.TP-\f[B]\f[CB]curdir\f[B]\f[R]-working directory from which pandoc is run.-.TP-\f[B]\f[CB]toc\f[B]\f[R]-non-null value if \f[C]--toc/--table-of-contents\f[R] was specified-.TP-\f[B]\f[CB]toc-title\f[B]\f[R]-title of table of contents (works only with EPUB, HTML, revealjs,-opendocument, odt, docx, pptx, beamer, LaTeX)-.SH EXTENSIONS-.PP-The behavior of some of the readers and writers can be adjusted by-enabling or disabling various extensions.-.PP-An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format-name and disabled by adding \f[C]-EXTENSION\f[R].-For example, \f[C]--from markdown_strict+footnotes\f[R] is strict-Markdown with footnotes enabled, while-\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s Markdown-without footnotes or pipe tables.-.PP-The markdown reader and writer make by far the most use of extensions.-Extensions only used by them are therefore covered in the section-Pandoc\[cq]s Markdown below (See Markdown variants for-\f[C]commonmark\f[R] and \f[C]gfm\f[R].)-In the following, extensions that also work for other formats are-covered.-.PP-Note that markdown extensions added to the \f[C]ipynb\f[R] format affect-Markdown cells in Jupyter notebooks (as do command-line options like-\f[C]--atx-headers\f[R]).-.SS Typography-.SS Extension: \f[C]smart\f[R]-.PP-Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,-\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.-Nonbreaking spaces are inserted after certain abbreviations, such as-\[lq]Mr.\[rq]-.PP-This extension can be enabled/disabled for the following formats:-.TP-input formats-\f[C]markdown\f[R], \f[C]commonmark\f[R], \f[C]latex\f[R],-\f[C]mediawiki\f[R], \f[C]org\f[R], \f[C]rst\f[R], \f[C]twiki\f[R]-.TP-output formats-\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R], \f[C]rst\f[R]-.TP-enabled by default in-\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]context\f[R] (both input and-output)-.PP-Note: If you are \f[I]writing\f[R] Markdown, then the \f[C]smart\f[R]-extension has the reverse effect: what would have been curly quotes-comes out straight.-.PP-In LaTeX, \f[C]smart\f[R] means to use the standard TeX ligatures for-quotation marks (\f[C]\[ga]\[ga]\f[R] and \f[C]\[aq]\[aq]\f[R] for-double quotes, \f[C]\[ga]\f[R] and \f[C]\[aq]\f[R] for single quotes)-and dashes (\f[C]--\f[R] for en-dash and \f[C]---\f[R] for em-dash).-If \f[C]smart\f[R] is disabled, then in reading LaTeX pandoc will parse-these characters literally.-In writing LaTeX, enabling \f[C]smart\f[R] tells pandoc to use the-ligatures when possible; if \f[C]smart\f[R] is disabled pandoc will use-unicode quotation mark and dash characters.-.SS Headings and sections-.SS Extension: \f[C]auto_identifiers\f[R]-.PP-A heading without an explicitly specified identifier will be-automatically assigned a unique identifier based on the heading text.-.PP-This extension can be enabled/disabled for the following formats:-.TP-input formats-\f[C]markdown\f[R], \f[C]latex\f[R], \f[C]rst\f[R], \f[C]mediawiki\f[R],-\f[C]textile\f[R]-.TP-output formats-\f[C]markdown\f[R], \f[C]muse\f[R]-.TP-enabled by default in-\f[C]markdown\f[R], \f[C]muse\f[R]-.PP-The default algorithm used to derive the identifier from the heading-text is:-.IP \[bu] 2-Remove all formatting, links, etc.-.IP \[bu] 2-Remove all footnotes.-.IP \[bu] 2-Remove all non-alphanumeric characters, except underscores, hyphens, and-periods.-.IP \[bu] 2-Replace all spaces and newlines with hyphens.-.IP \[bu] 2-Convert all alphabetic characters to lowercase.-.IP \[bu] 2-Remove everything up to the first letter (identifiers may not begin with-a number or punctuation mark).-.IP \[bu] 2-If nothing is left after this, use the identifier \f[C]section\f[R].-.PP-Thus, for example,-.PP-.TS-tab(@);-l l.-T{-Heading-T}@T{-Identifier-T}-_-T{-\f[C]Heading identifiers in HTML\f[R]-T}@T{-\f[C]heading-identifiers-in-html\f[R]-T}-T{-\f[C]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]-T}@T{-\f[C]ma\[^i]tre-dh\[^o]tel\f[R]-T}-T{-\f[C]*Dogs*?--in *my* house?\f[R]-T}@T{-\f[C]dogs--in-my-house\f[R]-T}-T{-\f[C][HTML], [S5], or [RTF]?\f[R]-T}@T{-\f[C]html-s5-or-rtf\f[R]-T}-T{-\f[C]3. Applications\f[R]-T}@T{-\f[C]applications\f[R]-T}-T{-\f[C]33\f[R]-T}@T{-\f[C]section\f[R]-T}-.TE-.PP-These rules should, in most cases, allow one to determine the identifier-from the heading text.-The exception is when several headings have the same text; in this case,-the first will get an identifier as described above; the second will get-the same identifier with \f[C]-1\f[R] appended; the third with-\f[C]-2\f[R]; and so on.-.PP-(However, a different algorithm is used if-\f[C]gfm_auto_identifiers\f[R] is enabled; see below.)-.PP-These identifiers are used to provide link targets in the table of-contents generated by the \f[C]--toc|--table-of-contents\f[R] option.-They also make it easy to provide links from one section of a document-to another.-A link to this section, for example, might look like this:-.IP-.nf-\f[C]-See the section on-[heading identifiers](#heading-identifiers-in-html-latex-and-context).-\f[R]-.fi-.PP-Note, however, that this method of providing links to sections works-only in HTML, LaTeX, and ConTeXt formats.-.PP-If the \f[C]--section-divs\f[R] option is specified, then each section-will be wrapped in a \f[C]section\f[R] (or a \f[C]div\f[R], if-\f[C]html4\f[R] was specified), and the identifier will be attached to-the enclosing \f[C]<section>\f[R] (or \f[C]<div>\f[R]) tag rather than-the heading itself.-This allows entire sections to be manipulated using JavaScript or-treated differently in CSS.-.SS Extension: \f[C]ascii_identifiers\f[R]-.PP-Causes the identifiers produced by \f[C]auto_identifiers\f[R] to be pure-ASCII.-Accents are stripped off of accented Latin letters, and non-Latin-letters are omitted.-.SS Extension: \f[C]gfm_auto_identifiers\f[R]-.PP-Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to-GitHub\[cq]s method.-Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to-lowercase characters, and punctuation characters other than \f[C]-\f[R]-and \f[C]_\f[R] are removed.-Emojis are replaced by their names.-.SS Math Input-.PP-The extensions \f[C]tex_math_dollars\f[R],-\f[C]tex_math_single_backslash\f[R], and-\f[C]tex_math_double_backslash\f[R] are described in the section about-Pandoc\[cq]s Markdown.-.PP-However, they can also be used with HTML input.-This is handy for reading web pages formatted using MathJax, for-example.-.SS Raw HTML/TeX-.PP-The following extensions are described in more detail in their-respective sections of Pandoc\[cq]s Markdown:-.IP \[bu] 2-\f[C]raw_html\f[R] allows HTML elements which are not representable in-pandoc\[cq]s AST to be parsed as raw HTML.-By default, this is disabled for HTML input.-.IP \[bu] 2-\f[C]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a-document.-This extension can be enabled/disabled for the following formats (in-addition to \f[C]markdown\f[R]):-.RS 2-.TP-input formats-\f[C]latex\f[R], \f[C]textile\f[R], \f[C]html\f[R] (environments,-\f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only), \f[C]ipynb\f[R]-.TP-output formats-\f[C]textile\f[R], \f[C]commonmark\f[R]-.PP-Note: as applied to \f[C]ipynb\f[R], \f[C]raw_html\f[R] and-\f[C]raw_tex\f[R] affect not only raw TeX in markdown cells, but data-with mime type \f[C]text/html\f[R] in output cells.-Since the \f[C]ipynb\f[R] reader attempts to preserve the richest-possible outputs when several options are given, you will get best-results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when-converting to formats like \f[C]docx\f[R] which don\[cq]t allow raw-\f[C]html\f[R] or \f[C]tex\f[R].-.RE-.IP \[bu] 2-\f[C]native_divs\f[R] causes HTML \f[C]div\f[R] elements to be parsed as-native pandoc Div blocks.-If you want them to be parsed as raw HTML, use-\f[C]-f html-native_divs+raw_html\f[R].-.IP \[bu] 2-\f[C]native_spans\f[R] causes HTML \f[C]span\f[R] elements to be parsed-as native pandoc Span inlines.-If you want them to be parsed as raw HTML, use-\f[C]-f html-native_spans+raw_html\f[R].-If you want to drop all \f[C]div\f[R]s and \f[C]span\f[R]s when-converting HTML to Markdown, you can use-\f[C]pandoc -f html-native_divs-native_spans -t markdown\f[R].-.SS Literate Haskell support-.SS Extension: \f[C]literate_haskell\f[R]-.PP-Treat the document as literate Haskell source.-.PP-This extension can be enabled/disabled for the following formats:-.TP-input formats-\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R]-.TP-output formats-\f[C]markdown\f[R], \f[C]rst\f[R], \f[C]latex\f[R], \f[C]html\f[R]-.PP-If you append \f[C]+lhs\f[R] (or \f[C]+literate_haskell\f[R]) to one of-the formats above, pandoc will treat the document as literate Haskell-source.-This means that-.IP \[bu] 2-In Markdown input, \[lq]bird track\[rq] sections will be parsed as-Haskell code rather than block quotations.-Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]-will also be treated as Haskell code.-For ATX-style headings the character `=' will be used instead of `#'.-.IP \[bu] 2-In Markdown output, code blocks with classes \f[C]haskell\f[R] and-\f[C]literate\f[R] will be rendered using bird tracks, and block-quotations will be indented one space, so they will not be treated as-Haskell code.-In addition, headings will be rendered setext-style (with underlines)-rather than ATX-style (with `#' characters).-(This is because ghc treats `#' characters in column 1 as introducing-line numbers.)-.IP \[bu] 2-In restructured text input, \[lq]bird track\[rq] sections will be parsed-as Haskell code.-.IP \[bu] 2-In restructured text output, code blocks with class \f[C]haskell\f[R]-will be rendered using bird tracks.-.IP \[bu] 2-In LaTeX input, text in \f[C]code\f[R] environments will be parsed as-Haskell code.-.IP \[bu] 2-In LaTeX output, code blocks with class \f[C]haskell\f[R] will be-rendered inside \f[C]code\f[R] environments.-.IP \[bu] 2-In HTML output, code blocks with class \f[C]haskell\f[R] will be-rendered with class \f[C]literatehaskell\f[R] and bird tracks.-.PP-Examples:-.IP-.nf-\f[C]-pandoc -f markdown+lhs -t html-\f[R]-.fi-.PP-reads literate Haskell source formatted with Markdown conventions and-writes ordinary HTML (without bird tracks).-.IP-.nf-\f[C]-pandoc -f markdown+lhs -t html+lhs-\f[R]-.fi-.PP-writes HTML with the Haskell code in bird tracks, so it can be copied-and pasted as literate Haskell source.-.PP-Note that GHC expects the bird tracks in the first column, so indented-literate code blocks (e.g.\ inside an itemized environment) will not be-picked up by the Haskell compiler.-.SS Other extensions-.SS Extension: \f[C]empty_paragraphs\f[R]-.PP-Allows empty paragraphs.-By default empty paragraphs are omitted.-.PP-This extension can be enabled/disabled for the following formats:-.TP-input formats-\f[C]docx\f[R], \f[C]html\f[R]-.TP-output formats-\f[C]docx\f[R], \f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]html\f[R]-.SS Extension: \f[C]native_numbering\f[R]-.PP-Enables native numbering of figures and tables.-Enumeration starts at 1.-.PP-This extension can be enabled/disabled for the following formats:-.TP-output formats-\f[C]odt\f[R], \f[C]opendocument\f[R], \f[C]docx\f[R]-.SS Extension: \f[C]xrefs_name\f[R]-.PP-Links to headings, figures and tables inside the document are-substituted with cross-references that will use the name or caption of-the referenced item.-The original link text is replaced once the generated document is-refreshed.-This extension can be combined with \f[C]xrefs_number\f[R] in which case-numbers will appear before the name.-.PP-Text in cross-references is only made consistent with the referenced-item once the document has been refreshed.-.PP-This extension can be enabled/disabled for the following formats:-.TP-output formats-\f[C]odt\f[R], \f[C]opendocument\f[R]-.SS Extension: \f[C]xrefs_number\f[R]-.PP-Links to headings, figures and tables inside the document are-substituted with cross-references that will use the number of the-referenced item.-The original link text is discarded.-This extension can be combined with \f[C]xrefs_name\f[R] in which case-the name or caption numbers will appear after the number.-.PP-For the \f[C]xrefs_number\f[R] to be useful heading numbers must be-enabled in the generated document, also table and figure captions must-be enabled using for example the \f[C]native_numbering\f[R] extension.-.PP-Numbers in cross-references are only visible in the final document once-it has been refreshed.-.PP-This extension can be enabled/disabled for the following formats:-.TP-output formats-\f[C]odt\f[R], \f[C]opendocument\f[R]-.SS Extension: \f[C]styles\f[R]-.PP-When converting from docx, read all docx styles as divs (for paragraph-styles) and spans (for character styles) regardless of whether pandoc-understands the meaning of these styles.-This can be used with docx custom styles.-Disabled by default.-.TP-input formats-\f[C]docx\f[R]-.SS Extension: \f[C]amuse\f[R]-.PP-In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions-to Emacs Muse markup.-.SS Extension: \f[C]raw_markdown\f[R]-.PP-In the \f[C]ipynb\f[R] input format, this causes Markdown cells to be-included as raw Markdown blocks (allowing lossless round-tripping)-rather than being parsed.-Use this only when you are targeting \f[C]ipynb\f[R] or a markdown-based-output format.-.SS Extension: \f[C]citations\f[R]-.PP-Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted-in \f[C]org\f[R] input.-.SS Extension: \f[C]fancy_lists\f[R]-.PP-Some aspects of Pandoc\[cq]s Markdown fancy lists are also accepted in-\f[C]org\f[R] input, mimicking the option-\f[C]org-list-allow-alphabetical\f[R] in Emacs.-As in Org Mode, enabling this extension allows lowercase and uppercase-alphabetical markers for ordered lists to be parsed in addition to-arabic ones.-Note that for Org, this does not include roman numerals or the-\f[C]#\f[R] placeholder that are enabled by the extension in-Pandoc\[cq]s Markdown.-.SS Extension: \f[C]element_citations\f[R]-.PP-In the \f[C]jats\f[R] output formats, this causes reference items to be-replaced with \f[C]<element-citation>\f[R] elements.-These elements are not influenced by CSL styles, but all information on-the item is included in tags.-.SS Extension: \f[C]ntb\f[R]-.PP-In the \f[C]context\f[R] output format this enables the use of Natural-Tables (TABLE) instead of the default Extreme Tables (xtables).-Natural tables allow more fine-grained global customization but come at-a performance penalty compared to extreme tables.-.SH PANDOC\[cq]S MARKDOWN-.PP-Pandoc understands an extended and slightly revised version of John-Gruber\[cq]s Markdown syntax.-This document explains the syntax, noting differences from original-Markdown.-Except where noted, these differences can be suppressed by using the-\f[C]markdown_strict\f[R] format instead of \f[C]markdown\f[R].-Extensions can be enabled or disabled to specify the behavior more-granularly.-They are described in the following.-See also Extensions above, for extensions that work also on other-formats.-.SS Philosophy-.PP-Markdown is designed to be easy to write, and, even more importantly,-easy to read:-.RS-.PP-A Markdown-formatted document should be publishable as-is, as plain-text, without looking like it\[cq]s been marked up with tags or-formatting instructions.-\[en] John Gruber-.RE-.PP-This principle has guided pandoc\[cq]s decisions in finding syntax for-tables, footnotes, and other extensions.-.PP-There is, however, one respect in which pandoc\[cq]s aims are different-from the original aims of Markdown.-Whereas Markdown was originally designed with HTML generation in mind,-pandoc is designed for multiple output formats.-Thus, while pandoc allows the embedding of raw HTML, it discourages it,-and provides other, non-HTMLish ways of representing important document-elements like definition lists, tables, mathematics, and footnotes.-.SS Paragraphs-.PP-A paragraph is one or more lines of text followed by one or more blank-lines.-Newlines are treated as spaces, so you can reflow your paragraphs as you-like.-If you need a hard line break, put two or more spaces at the end of a-line.-.SS Extension: \f[C]escaped_line_breaks\f[R]-.PP-A backslash followed by a newline is also a hard line break.-Note: in multiline and grid table cells, this is the only way to create-a hard line break, since trailing spaces in the cells are ignored.-.SS Headings-.PP-There are two kinds of headings: Setext and ATX.-.SS Setext-style headings-.PP-A setext-style heading is a line of text \[lq]underlined\[rq] with a row-of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for-a level-two heading):-.IP-.nf-\f[C]-A level-one heading-===================--A level-two heading---------------------\f[R]-.fi-.PP-The heading text can contain inline formatting, such as emphasis (see-Inline formatting, below).-.SS ATX-style headings-.PP-An ATX-style heading consists of one to six \f[C]#\f[R] signs and a line-of text, optionally followed by any number of \f[C]#\f[R] signs.-The number of \f[C]#\f[R] signs at the beginning of the line is the-heading level:-.IP-.nf-\f[C]-## A level-two heading--### A level-three heading ###-\f[R]-.fi-.PP-As with setext-style headings, the heading text can contain formatting:-.IP-.nf-\f[C]-# A level-one heading with a [link](/url) and *emphasis*-\f[R]-.fi-.SS Extension: \f[C]blank_before_header\f[R]-.PP-Original Markdown syntax does not require a blank line before a heading.-Pandoc does require this (except, of course, at the beginning of the-document).-The reason for the requirement is that it is all too easy for a-\f[C]#\f[R] to end up at the beginning of a line by accident (perhaps-through line wrapping).-Consider, for example:-.IP-.nf-\f[C]-I like several of their flavors of ice cream:-#22, for example, and #5.-\f[R]-.fi-.SS Extension: \f[C]space_in_atx_header\f[R]-.PP-Many Markdown implementations do not require a space between the opening-\f[C]#\f[R]s of an ATX heading and the heading text, so that-\f[C]#5 bolt\f[R] and \f[C]#hashtag\f[R] count as headings.-With this extension, pandoc does require the space.-.SS Heading identifiers-.PP-See also the \f[C]auto_identifiers\f[R] extension above.-.SS Extension: \f[C]header_attributes\f[R]-.PP-Headings can be assigned attributes using this syntax at the end of the-line containing the heading text:-.IP-.nf-\f[C]-{#identifier .class .class key=value key=value}-\f[R]-.fi-.PP-Thus, for example, the following headings will all be assigned the-identifier \f[C]foo\f[R]:-.IP-.nf-\f[C]-# My heading {#foo}--## My heading ##    {#foo}--My other heading   {#foo}-----------------\f[R]-.fi-.PP-(This syntax is compatible with PHP Markdown Extra.)-.PP-Note that although this syntax allows assignment of classes and-key/value attributes, writers generally don\[cq]t use all of this-information.-Identifiers, classes, and key/value attributes are used in HTML and-HTML-based formats such as EPUB and slidy.-Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,-Textile, Jira markup, and AsciiDoc writers.-.PP-Headings with the class \f[C]unnumbered\f[R] will not be numbered, even-if \f[C]--number-sections\f[R] is specified.-A single hyphen (\f[C]-\f[R]) in an attribute context is equivalent to-\f[C].unnumbered\f[R], and preferable in non-English documents.-So,-.IP-.nf-\f[C]-# My heading {-}-\f[R]-.fi-.PP-is just the same as-.IP-.nf-\f[C]-# My heading {.unnumbered}-\f[R]-.fi-.PP-If the \f[C]unlisted\f[R] class is present in addition to-\f[C]unnumbered\f[R], the heading will not be included in a table of-contents.-(Currently this feature is only implemented for certain formats: those-based on LaTeX and HTML, PowerPoint, and RTF.)-.SS Extension: \f[C]implicit_header_references\f[R]-.PP-Pandoc behaves as if reference links have been defined for each heading.-So, to link to a heading-.IP-.nf-\f[C]-# Heading identifiers in HTML-\f[R]-.fi-.PP-you can simply write-.IP-.nf-\f[C]-[Heading identifiers in HTML]-\f[R]-.fi-.PP-or-.IP-.nf-\f[C]-[Heading identifiers in HTML][]-\f[R]-.fi-.PP-or-.IP-.nf-\f[C]-[the section on heading identifiers][heading identifiers in-HTML]-\f[R]-.fi-.PP-instead of giving the identifier explicitly:-.IP-.nf-\f[C]-[Heading identifiers in HTML](#heading-identifiers-in-html)-\f[R]-.fi-.PP-If there are multiple headings with identical text, the corresponding-reference will link to the first one only, and you will need to use-explicit links to link to the others, as described above.-.PP-Like regular reference links, these references are case-insensitive.-.PP-Explicit link reference definitions always take priority over implicit-heading references.-So, in the following example, the link will point to \f[C]bar\f[R], not-to \f[C]#foo\f[R]:-.IP-.nf-\f[C]-# Foo--[foo]: bar--See [foo]-\f[R]-.fi-.SS Block quotations-.PP-Markdown uses email conventions for quoting blocks of text.-A block quotation is one or more paragraphs or other block elements-(such as lists or headings), with each line preceded by a \f[C]>\f[R]-character and an optional space.-(The \f[C]>\f[R] need not start at the left margin, but it should not be-indented more than three spaces.)-.IP-.nf-\f[C]-> This is a block quote. This-> paragraph has two lines.->-> 1. This is a list inside a block quote.-> 2. Second item.-\f[R]-.fi-.PP-A \[lq]lazy\[rq] form, which requires the \f[C]>\f[R] character only on-the first line of each block, is also allowed:-.IP-.nf-\f[C]-> This is a block quote. This-paragraph has two lines.--> 1. This is a list inside a block quote.-2. Second item.-\f[R]-.fi-.PP-Among the block elements that can be contained in a block quote are-other block quotes.-That is, block quotes can be nested:-.IP-.nf-\f[C]-> This is a block quote.->-> > A block quote within a block quote.-\f[R]-.fi-.PP-If the \f[C]>\f[R] character is followed by an optional space, that-space will be considered part of the block quote marker and not part of-the indentation of the contents.-Thus, to put an indented code block in a block quote, you need five-spaces after the \f[C]>\f[R]:-.IP-.nf-\f[C]->     code-\f[R]-.fi-.SS Extension: \f[C]blank_before_blockquote\f[R]-.PP-Original Markdown syntax does not require a blank line before a block-quote.-Pandoc does require this (except, of course, at the beginning of the-document).-The reason for the requirement is that it is all too easy for a-\f[C]>\f[R] to end up at the beginning of a line by accident (perhaps-through line wrapping).-So, unless the \f[C]markdown_strict\f[R] format is used, the following-does not produce a nested block quote in pandoc:-.IP-.nf-\f[C]-> This is a block quote.->> Nested.-\f[R]-.fi-.SS Verbatim (code) blocks-.SS Indented code blocks-.PP-A block of text indented four spaces (or one tab) is treated as verbatim-text: that is, special characters do not trigger special formatting, and-all spaces and line breaks are preserved.-For example,-.IP-.nf-\f[C]-    if (a > 3) {-      moveShip(5 * gravity, DOWN);-    }-\f[R]-.fi-.PP-The initial (four space or one tab) indentation is not considered part-of the verbatim text, and is removed in the output.-.PP-Note: blank lines in the verbatim text need not begin with four spaces.-.SS Fenced code blocks-.SS Extension: \f[C]fenced_code_blocks\f[R]-.PP-In addition to standard indented code blocks, pandoc supports-\f[I]fenced\f[R] code blocks.-These begin with a row of three or more tildes (\f[C]\[ti]\f[R]) and end-with a row of tildes that must be at least as long as the starting row.-Everything between these lines is treated as code.-No indentation is necessary:-.IP-.nf-\f[C]-\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]-if (a > 3) {-  moveShip(5 * gravity, DOWN);-}-\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]-\f[R]-.fi-.PP-Like regular code blocks, fenced code blocks must be separated from-surrounding text by blank lines.-.PP-If the code itself contains a row of tildes or backticks, just use a-longer row of tildes or backticks at the start and end:-.IP-.nf-\f[C]-\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]-\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]-code including tildes-\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]-\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]-\f[R]-.fi-.SS Extension: \f[C]backtick_code_blocks\f[R]-.PP-Same as \f[C]fenced_code_blocks\f[R], but uses backticks-(\f[C]\[ga]\f[R]) instead of tildes (\f[C]\[ti]\f[R]).-.SS Extension: \f[C]fenced_code_attributes\f[R]-.PP-Optionally, you may attach attributes to fenced or backtick code block-using this syntax:-.IP-.nf-\f[C]-\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}-qsort []     = []-qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++-               qsort (filter (>= x) xs)-\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]-\f[R]-.fi-.PP-Here \f[C]mycode\f[R] is an identifier, \f[C]haskell\f[R] and-\f[C]numberLines\f[R] are classes, and \f[C]startFrom\f[R] is an-attribute with value \f[C]100\f[R].-Some output formats can use this information to do syntax highlighting.-Currently, the only output formats that uses this information are HTML,-LaTeX, Docx, Ms, and PowerPoint.-If highlighting is supported for your output format and language, then-the code block above will appear highlighted, with numbered lines.-(To see which languages are supported, type-\f[C]pandoc --list-highlight-languages\f[R].)-Otherwise, the code block above will appear as follows:-.IP-.nf-\f[C]-<pre id=\[dq]mycode\[dq] class=\[dq]haskell numberLines\[dq] startFrom=\[dq]100\[dq]>-  <code>-  ...-  </code>-</pre>-\f[R]-.fi-.PP-The \f[C]numberLines\f[R] (or \f[C]number-lines\f[R]) class will cause-the lines of the code block to be numbered, starting with \f[C]1\f[R] or-the value of the \f[C]startFrom\f[R] attribute.-The \f[C]lineAnchors\f[R] (or \f[C]line-anchors\f[R]) class will cause-the lines to be clickable anchors in HTML output.-.PP-A shortcut form can also be used for specifying the language of the code-block:-.IP-.nf-\f[C]-\[ga]\[ga]\[ga]haskell-qsort [] = []-\[ga]\[ga]\[ga]-\f[R]-.fi-.PP-This is equivalent to:-.IP-.nf-\f[C]-\[ga]\[ga]\[ga] {.haskell}-qsort [] = []-\[ga]\[ga]\[ga]-\f[R]-.fi-.PP-If the \f[C]fenced_code_attributes\f[R] extension is disabled, but input-contains class attribute(s) for the code block, the first class-attribute will be printed after the opening fence as a bare word.-.PP-To prevent all highlighting, use the \f[C]--no-highlight\f[R] flag.-To set the highlighting style, use \f[C]--highlight-style\f[R].-For more information on highlighting, see Syntax highlighting, below.-.SS Line blocks-.SS Extension: \f[C]line_blocks\f[R]-.PP-A line block is a sequence of lines beginning with a vertical bar-(\f[C]|\f[R]) followed by a space.-The division into lines will be preserved in the output, as will any-leading spaces; otherwise, the lines will be formatted as Markdown.-This is useful for verse and addresses:-.IP-.nf-\f[C]-| The limerick packs laughs anatomical-| In space that is quite economical.-|    But the good ones I\[aq]ve seen-|    So seldom are clean-| And the clean ones so seldom are comical--| 200 Main St.-| Berkeley, CA 94718-\f[R]-.fi-.PP-The lines can be hard-wrapped if needed, but the continuation line must-begin with a space.-.IP-.nf-\f[C]-| The Right Honorable Most Venerable and Righteous Samuel L.-  Constable, Jr.-| 200 Main St.-| Berkeley, CA 94718-\f[R]-.fi-.PP-Inline formatting (such as emphasis) is allowed in the content, but not-block-level formatting (such as block quotes or lists).-.PP-This syntax is borrowed from reStructuredText.-.SS Lists-.SS Bullet lists-.PP-A bullet list is a list of bulleted list items.-A bulleted list item begins with a bullet (\f[C]*\f[R], \f[C]+\f[R], or-\f[C]-\f[R]).-Here is a simple example:-.IP-.nf-\f[C]-* one-* two-* three-\f[R]-.fi-.PP-This will produce a \[lq]compact\[rq] list.-If you want a \[lq]loose\[rq] list, in which each item is formatted as a-paragraph, put spaces between the items:-.IP-.nf-\f[C]-* one--* two--* three-\f[R]-.fi-.PP-The bullets need not be flush with the left margin; they may be indented-one, two, or three spaces.-The bullet must be followed by whitespace.-.PP-List items look best if subsequent lines are flush with the first line-(after the bullet):-.IP-.nf-\f[C]-* here is my first-  list item.-* and my second.-\f[R]-.fi-.PP-But Markdown also allows a \[lq]lazy\[rq] format:-.IP-.nf-\f[C]-* here is my first-list item.-* and my second.-\f[R]-.fi-.SS Block content in list items-.PP-A list item may contain multiple paragraphs and other block-level-content.-However, subsequent paragraphs must be preceded by a blank line and-indented to line up with the first non-space content after the list-marker.-.IP-.nf-\f[C]-  * First paragraph.--    Continued.--  * Second paragraph. With a code block, which must be indented-    eight spaces:--        { code }-\f[R]-.fi-.PP-Exception: if the list marker is followed by an indented code block,-which must begin 5 spaces after the list marker, then subsequent-paragraphs must begin two columns after the last character of the list-marker:-.IP-.nf-\f[C]-*     code--  continuation paragraph-\f[R]-.fi-.PP-List items may include other lists.-In this case the preceding blank line is optional.-The nested list must be indented to line up with the first non-space-character after the list marker of the containing list item.-.IP-.nf-\f[C]-* fruits-  + apples-    - macintosh-    - red delicious-  + pears-  + peaches-* vegetables-  + broccoli-  + chard-\f[R]-.fi-.PP-As noted above, Markdown allows you to write list items-\[lq]lazily,\[rq] instead of indenting continuation lines.-However, if there are multiple paragraphs or other blocks in a list-item, the first line of each must be indented.-.IP-.nf-\f[C]-+ A lazy, lazy, list-item.--+ Another one; this looks-bad but is legal.--    Second paragraph of second-list item.-\f[R]-.fi-.SS Ordered lists-.PP-Ordered lists work just like bulleted lists, except that the items begin-with enumerators rather than bullets.-.PP-In original Markdown, enumerators are decimal numbers followed by a-period and a space.-The numbers themselves are ignored, so there is no difference between-this list:-.IP-.nf-\f[C]-1.  one-2.  two-3.  three-\f[R]-.fi-.PP-and this one:-.IP-.nf-\f[C]-5.  one-7.  two-1.  three-\f[R]-.fi-.SS Extension: \f[C]fancy_lists\f[R]-.PP-Unlike original Markdown, pandoc allows ordered list items to be marked-with uppercase and lowercase letters and roman numerals, in addition to-Arabic numerals.-List markers may be enclosed in parentheses or followed by a single-right-parentheses or period.-They must be separated from the text that follows by at least one space,-and, if the list marker is a capital letter with a period, by at least-two spaces.-.PP-The \f[C]fancy_lists\f[R] extension also allows `\f[C]#\f[R]' to be used-as an ordered list marker in place of a numeral:-.IP-.nf-\f[C]-#. one-#. two-\f[R]-.fi-.SS Extension: \f[C]startnum\f[R]-.PP-Pandoc also pays attention to the type of list marker used, and to the-starting number, and both of these are preserved where possible in the-output format.-Thus, the following yields a list with numbers followed by a single-parenthesis, starting with 9, and a sublist with lowercase roman-numerals:-.IP-.nf-\f[C]- 9)  Ninth-10)  Tenth-11)  Eleventh-       i. subone-      ii. subtwo-     iii. subthree-\f[R]-.fi-.PP-Pandoc will start a new list each time a different type of list marker-is used.-So, the following will create three lists:-.IP-.nf-\f[C]-(2) Two-(5) Three-1.  Four-*   Five-\f[R]-.fi-.PP-If default list markers are desired, use \f[C]#.\f[R]:-.IP-.nf-\f[C]-#.  one-#.  two-#.  three-\f[R]-.fi-.SS Extension: \f[C]task_lists\f[R]-.PP-Pandoc supports task lists, using the syntax of GitHub-Flavored-Markdown.-.IP-.nf-\f[C]-- [ ] an unchecked task list item-- [x] checked item-\f[R]-.fi-.SS Definition lists-.SS Extension: \f[C]definition_lists\f[R]-.PP-Pandoc supports definition lists, using the syntax of PHP Markdown Extra-with some extensions.-.IP-.nf-\f[C]-Term 1--:   Definition 1--Term 2 with *inline markup*--:   Definition 2--        { some code, part of Definition 2 }--    Third paragraph of definition 2.-\f[R]-.fi-.PP-Each term must fit on one line, which may optionally be followed by a-blank line, and must be followed by one or more definitions.-A definition begins with a colon or tilde, which may be indented one or-two spaces.-.PP-A term may have multiple definitions, and each definition may consist of-one or more block elements (paragraph, code block, list, etc.), each-indented four spaces or one tab stop.-The body of the definition (not including the first line) should be-indented four spaces.-However, as with other Markdown lists, you can \[lq]lazily\[rq] omit-indentation except at the beginning of a paragraph or other block-element:-.IP-.nf-\f[C]-Term 1--:   Definition-with lazy continuation.--    Second paragraph of the definition.-\f[R]-.fi-.PP-If you leave space before the definition (as in the example above), the-text of the definition will be treated as a paragraph.-In some output formats, this will mean greater spacing between-term/definition pairs.-For a more compact definition list, omit the space before the-definition:-.IP-.nf-\f[C]-Term 1-  \[ti] Definition 1--Term 2-  \[ti] Definition 2a-  \[ti] Definition 2b-\f[R]-.fi-.PP-Note that space between items in a definition list is required.-(A variant that loosens this requirement, but disallows \[lq]lazy\[rq]-hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:-see Non-default extensions, below.)-.SS Numbered example lists-.SS Extension: \f[C]example_lists\f[R]-.PP-The special list marker \f[C]\[at]\f[R] can be used for sequentially-numbered examples.-The first list item with a \f[C]\[at]\f[R] marker will be numbered `1',-the next `2', and so on, throughout the document.-The numbered examples need not occur in a single list; each new list-using \f[C]\[at]\f[R] will take up where the last stopped.-So, for example:-.IP-.nf-\f[C]-(\[at])  My first example will be numbered (1).-(\[at])  My second example will be numbered (2).--Explanation of examples.--(\[at])  My third example will be numbered (3).-\f[R]-.fi-.PP-Numbered examples can be labeled and referred to elsewhere in the-document:-.IP-.nf-\f[C]-(\[at]good)  This is a good example.--As (\[at]good) illustrates, ...-\f[R]-.fi-.PP-The label can be any string of alphanumeric characters, underscores, or-hyphens.-.PP-Note: continuation paragraphs in example lists must always be indented-four spaces, regardless of the length of the list marker.-That is, example lists always behave as if the \f[C]four_space_rule\f[R]-extension is set.-This is because example labels tend to be long, and indenting content to-the first non-space character after the label would be awkward.-.SS Ending a list-.PP-What if you want to put an indented code block after a list?-.IP-.nf-\f[C]--   item one--   item two--    { my code block }-\f[R]-.fi-.PP-Trouble!-Here pandoc (like other Markdown implementations) will treat-\f[C]{ my code block }\f[R] as the second paragraph of item two, and not-as a code block.-.PP-To \[lq]cut off\[rq] the list after item two, you can insert some-non-indented content, like an HTML comment, which won\[cq]t produce-visible output in any format:-.IP-.nf-\f[C]--   item one--   item two--<!-- end of list -->--    { my code block }-\f[R]-.fi-.PP-You can use the same trick if you want two consecutive lists instead of-one big list:-.IP-.nf-\f[C]-1.  one-2.  two-3.  three--<!-- -->--1.  uno-2.  dos-3.  tres-\f[R]-.fi-.SS Horizontal rules-.PP-A line containing a row of three or more \f[C]*\f[R], \f[C]-\f[R], or-\f[C]_\f[R] characters (optionally separated by spaces) produces a-horizontal rule:-.IP-.nf-\f[C]-*  *  *  *------------------\f[R]-.fi-.SS Tables-.PP-Four kinds of tables may be used.-The first three kinds presuppose the use of a fixed-width font, such as-Courier.-The fourth kind can be used with proportionally spaced fonts, as it does-not require lining up columns.-.SS Extension: \f[C]table_captions\f[R]-.PP-A caption may optionally be provided with all 4 kinds of tables (as-illustrated in the examples below).-A caption is a paragraph beginning with the string \f[C]Table:\f[R] (or-just \f[C]:\f[R]), which will be stripped off.-It may appear either before or after the table.-.SS Extension: \f[C]simple_tables\f[R]-.PP-Simple tables look like this:-.IP-.nf-\f[C]-  Right     Left     Center     Default--------     ------ ----------   --------     12     12        12            12-    123     123       123          123-      1     1          1             1--Table:  Demonstration of simple table syntax.-\f[R]-.fi-.PP-The header and table rows must each fit on one line.-Column alignments are determined by the position of the header text-relative to the dashed line below it:-.IP \[bu] 2-If the dashed line is flush with the header text on the right side but-extends beyond it on the left, the column is right-aligned.-.IP \[bu] 2-If the dashed line is flush with the header text on the left side but-extends beyond it on the right, the column is left-aligned.-.IP \[bu] 2-If the dashed line extends beyond the header text on both sides, the-column is centered.-.IP \[bu] 2-If the dashed line is flush with the header text on both sides, the-default alignment is used (in most cases, this will be left).-.PP-The table must end with a blank line, or a line of dashes followed by a-blank line.-.PP-The column header row may be omitted, provided a dashed line is used to-end the table.-For example:-.IP-.nf-\f[C]--------     ------ ----------   --------     12     12        12             12-    123     123       123           123-      1     1          1              1--------     ------ ----------   --------\f[R]-.fi-.PP-When the header row is omitted, column alignments are determined on the-basis of the first line of the table body.-So, in the tables above, the columns would be right, left, center, and-right aligned, respectively.-.SS Extension: \f[C]multiline_tables\f[R]-.PP-Multiline tables allow header and table rows to span multiple lines of-text (but cells that span multiple columns or rows of the table are not-supported).-Here is an example:-.IP-.nf-\f[C]--------------------------------------------------------------- Centered   Default           Right Left-  Header    Aligned         Aligned Aligned------------ ------- --------------- --------------------------   First    row                12.0 Example of a row that-                                    spans multiple lines.--  Second    row                 5.0 Here\[aq]s another one. Note-                                    the blank line between-                                    rows.----------------------------------------------------------------Table: Here\[aq]s the caption. It, too, may span-multiple lines.-\f[R]-.fi-.PP-These work like simple tables, but with the following differences:-.IP \[bu] 2-They must begin with a row of dashes, before the header text (unless the-header row is omitted).-.IP \[bu] 2-They must end with a row of dashes, then a blank line.-.IP \[bu] 2-The rows must be separated by blank lines.-.PP-In multiline tables, the table parser pays attention to the widths of-the columns, and the writers try to reproduce these relative widths in-the output.-So, if you find that one of the columns is too narrow in the output, try-widening it in the Markdown source.-.PP-The header may be omitted in multiline tables as well as simple tables:-.IP-.nf-\f[C]------------ ------- --------------- --------------------------   First    row                12.0 Example of a row that-                                    spans multiple lines.--  Second    row                 5.0 Here\[aq]s another one. Note-                                    the blank line between-                                    rows.------------ ------- --------------- ---------------------------: Here\[aq]s a multiline table without a header.-\f[R]-.fi-.PP-It is possible for a multiline table to have just one row, but the row-should be followed by a blank line (and then the row of dashes that ends-the table), or the table may be interpreted as a simple table.-.SS Extension: \f[C]grid_tables\f[R]-.PP-Grid tables look like this:-.IP-.nf-\f[C]-: Sample grid table.--+---------------+---------------+--------------------+-| Fruit         | Price         | Advantages         |-+===============+===============+====================+-| Bananas       | $1.34         | - built-in wrapper |-|               |               | - bright color     |-+---------------+---------------+--------------------+-| Oranges       | $2.10         | - cures scurvy     |-|               |               | - tasty            |-+---------------+---------------+--------------------+-\f[R]-.fi-.PP-The row of \f[C]=\f[R]s separates the header from the table body, and-can be omitted for a headerless table.-The cells of grid tables may contain arbitrary block elements (multiple-paragraphs, code blocks, lists, etc.).-Cells that span multiple columns or rows are not supported.-Grid tables can be created easily using Emacs\[cq] table-mode-(\f[C]M-x table-insert\f[R]).-.PP-Alignments can be specified as with pipe tables, by putting colons at-the boundaries of the separator line after the header:-.IP-.nf-\f[C]-+---------------+---------------+--------------------+-| Right         | Left          | Centered           |-+==============:+:==============+:==================:+-| Bananas       | $1.34         | built-in wrapper   |-+---------------+---------------+--------------------+-\f[R]-.fi-.PP-For headerless tables, the colons go on the top line instead:-.IP-.nf-\f[C]-+--------------:+:--------------+:------------------:+-| Right         | Left          | Centered           |-+---------------+---------------+--------------------+-\f[R]-.fi-.SS Grid Table Limitations-.PP-Pandoc does not support grid tables with row spans or column spans.-This means that neither variable numbers of columns across rows nor-variable numbers of rows across columns are supported by Pandoc.-All grid tables must have the same number of columns in each row, and-the same number of rows in each column.-For example, the Docutils sample grid tables will not render as expected-with Pandoc.-.SS Extension: \f[C]pipe_tables\f[R]-.PP-Pipe tables look like this:-.IP-.nf-\f[C]-| Right | Left | Default | Center |-|------:|:-----|---------|:------:|-|   12  |  12  |    12   |    12  |-|  123  |  123 |   123   |   123  |-|    1  |    1 |     1   |     1  |--  : Demonstration of pipe table syntax.-\f[R]-.fi-.PP-The syntax is identical to PHP Markdown Extra tables.-The beginning and ending pipe characters are optional, but pipes are-required between all columns.-The colons indicate column alignment as shown.-The header cannot be omitted.-To simulate a headerless table, include a header with blank cells.-.PP-Since the pipes indicate column boundaries, columns need not be-vertically aligned, as they are in the above example.-So, this is a perfectly legal (though ugly) pipe table:-.IP-.nf-\f[C]-fruit| price------|-----:-apple|2.05-pear|1.37-orange|3.09-\f[R]-.fi-.PP-The cells of pipe tables cannot contain block elements like paragraphs-and lists, and cannot span multiple lines.-If any line of the markdown source is longer than the column width (see-\f[C]--columns\f[R]), then the table will take up the full text width-and the cell contents will wrap, with the relative cell widths-determined by the number of dashes in the line separating the table-header from the table body.-(For example \f[C]---|-\f[R] would make the first column 3/4 and the-second column 1/4 of the full text width.)-On the other hand, if no lines are wider than column width, then cell-contents will not be wrapped, and the cells will be sized to their-contents.-.PP-Note: pandoc also recognizes pipe tables of the following form, as can-be produced by Emacs\[cq] orgtbl-mode:-.IP-.nf-\f[C]-| One | Two   |-|-----+-------|-| my  | table |-| is  | nice  |-\f[R]-.fi-.PP-The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].-Other orgtbl features are not supported.-In particular, to get non-default column alignment, you\[cq]ll need to-add colons as above.-.SS Metadata blocks-.SS Extension: \f[C]pandoc_title_block\f[R]-.PP-If the file begins with a title block-.IP-.nf-\f[C]-% title-% author(s) (separated by semicolons)-% date-\f[R]-.fi-.PP-it will be parsed as bibliographic information, not regular text.-(It will be used, for example, in the title of standalone LaTeX or HTML-output.)-The block may contain just a title, a title and an author, or all three-elements.-If you want to include an author but no title, or a title and a date but-no author, you need a blank line:-.IP-.nf-\f[C]-%-% Author-\f[R]-.fi-.IP-.nf-\f[C]-% My title-%-% June 15, 2006-\f[R]-.fi-.PP-The title may occupy multiple lines, but continuation lines must begin-with leading space, thus:-.IP-.nf-\f[C]-% My title-  on multiple lines-\f[R]-.fi-.PP-If a document has multiple authors, the authors may be put on separate-lines with leading space, or separated by semicolons, or both.-So, all of the following are equivalent:-.IP-.nf-\f[C]-% Author One-  Author Two-\f[R]-.fi-.IP-.nf-\f[C]-% Author One; Author Two-\f[R]-.fi-.IP-.nf-\f[C]-% Author One;-  Author Two-\f[R]-.fi-.PP-The date must fit on one line.-.PP-All three metadata fields may contain standard inline formatting-(italics, links, footnotes, etc.).-.PP-Title blocks will always be parsed, but they will affect the output only-when the \f[C]--standalone\f[R] (\f[C]-s\f[R]) option is chosen.-In HTML output, titles will appear twice: once in the document head-\[en] this is the title that will appear at the top of the window in a-browser \[en] and once at the beginning of the document body.-The title in the document head can have an optional prefix attached-(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).-The title in the body appears as an H1 element with class-\[lq]title\[rq], so it can be suppressed or reformatted with CSS.-If a title prefix is specified with \f[C]-T\f[R] and no title block-appears in the document, the title prefix will be used by itself as the-HTML title.-.PP-The man page writer extracts a title, man page section number, and other-header and footer information from the title line.-The title is assumed to be the first word on the title line, which may-optionally end with a (single-digit) section number in parentheses.-(There should be no space between the title and the parentheses.)-Anything after this is assumed to be additional footer and header text.-A single pipe character (\f[C]|\f[R]) should be used to separate the-footer text from the header text.-Thus,-.IP-.nf-\f[C]-% PANDOC(1)-\f[R]-.fi-.PP-will yield a man page with the title \f[C]PANDOC\f[R] and section 1.-.IP-.nf-\f[C]-% PANDOC(1) Pandoc User Manuals-\f[R]-.fi-.PP-will also have \[lq]Pandoc User Manuals\[rq] in the footer.-.IP-.nf-\f[C]-% PANDOC(1) Pandoc User Manuals | Version 4.0-\f[R]-.fi-.PP-will also have \[lq]Version 4.0\[rq] in the header.-.SS Extension: \f[C]yaml_metadata_block\f[R]-.PP-A YAML metadata block is a valid YAML object, delimited by a line of-three hyphens (\f[C]---\f[R]) at the top and a line of three hyphens-(\f[C]---\f[R]) or three dots (\f[C]...\f[R]) at the bottom.-A YAML metadata block may occur anywhere in the document, but if it is-not at the beginning, it must be preceded by a blank line.-(Note that, because of the way pandoc concatenates input files when-several are provided, you may also keep the metadata in a separate YAML-file and pass it to pandoc as an argument, along with your Markdown-files:-.IP-.nf-\f[C]-pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html-\f[R]-.fi-.PP-Just be sure that the YAML file begins with \f[C]---\f[R] and ends with-\f[C]---\f[R] or \f[C]...\f[R].)-Alternatively, you can use the \f[C]--metadata-file\f[R] option.-Using that approach however, you cannot reference content (like-footnotes) from the main markdown input document.-.PP-Metadata will be taken from the fields of the YAML object and added to-any existing document metadata.-Metadata can contain lists and objects (nested arbitrarily), but all-string scalars will be interpreted as Markdown.-Fields with names ending in an underscore will be ignored by pandoc.-(They may be given a role by external processors.)-Field names must not be interpretable as YAML numbers or boolean values-(so, for example, \f[C]yes\f[R], \f[C]True\f[R], and \f[C]15\f[R] cannot-be used as field names).-.PP-A document may contain multiple metadata blocks.-If two metadata blocks attempt to set the same field, the value from the-second block will be taken.-.PP-Each metadata block is handled internally as an independent YAML-document.-This means, for example, that any YAML anchors defined in a block cannot-be referenced in another block.-.PP-When pandoc is used with \f[C]-t markdown\f[R] to create a Markdown-document, a YAML metadata block will be produced only if the-\f[C]-s/--standalone\f[R] option is used.-All of the metadata will appear in a single block at the beginning of-the document.-.PP-Note that YAML escaping rules must be followed.-Thus, for example, if a title contains a colon, it must be quoted, and-if it contains a backslash escape, then it must be ensured that it is-not treated as a YAML escape sequence.-The pipe character (\f[C]|\f[R]) can be used to begin an indented block-that will be interpreted literally, without need for escaping.-This form is necessary when the field contains blank lines or-block-level formatting:-.IP-.nf-\f[C]-----title:  \[aq]This is the title: it contains a colon\[aq]-author:-- Author One-- Author Two-keywords: [nothing, nothingness]-abstract: |-  This is the abstract.--  It consists of two paragraphs.-\&...-\f[R]-.fi-.PP-The literal block after the \f[C]|\f[R] must be indented relative to the-line containing the \f[C]|\f[R].-If it is not, the YAML will be invalid and pandoc will not interpret it-as metadata.-For an overview of the complex rules governing YAML, see the Wikipedia-entry on YAML syntax.-.PP-Template variables will be set automatically from the metadata.-Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will-be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]-field:-.IP-.nf-\f[C]-<p>This is the abstract.</p>-<p>It consists of two paragraphs.</p>-\f[R]-.fi-.PP-Variables can contain arbitrary YAML structures, but the template must-match this structure.-The \f[C]author\f[R] variable in the default templates expects a simple-list or string, but can be changed to support more complicated-structures.-The following combination, for example, would add an affiliation to the-author if one is given:-.IP-.nf-\f[C]-----title: The document title-author:-- name: Author One-  affiliation: University of Somewhere-- name: Author Two-  affiliation: University of Nowhere-\&...-\f[R]-.fi-.PP-To use the structured authors in the example above, you would need a-custom template:-.IP-.nf-\f[C]-$for(author)$-$if(author.name)$-$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$-$else$-$author$-$endif$-$endfor$-\f[R]-.fi-.PP-Raw content to include in the document\[cq]s header may be specified-using \f[C]header-includes\f[R]; however, it is important to mark up-this content as raw code for a particular output format, using the-\f[C]raw_attribute\f[R] extension), or it will be interpreted as-markdown.-For example:-.IP-.nf-\f[C]-header-includes:-- |-  \[ga]\[ga]\[ga]{=latex}-  \[rs]let\[rs]oldsection\[rs]section-  \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}}-  \[ga]\[ga]\[ga]-\f[R]-.fi-.PP-Note: the \f[C]yaml_metadata_block\f[R] extension works with-\f[C]commonmark\f[R] as well as \f[C]markdown\f[R] (and it is enabled by-default in \f[C]gfm\f[R] and \f[C]commonmark_x\f[R]).-However, in these formats the following restrictions apply:-.IP \[bu] 2-The YAML metadata block must occur at the beginning of the document (and-there can be only one).-If multiple files are given as arguments to pandoc, only the first can-be a YAML metadata block.-.IP \[bu] 2-The leaf nodes of the YAML structure are parsed in isolation from each-other and from the rest of the document.-So, for example, you can\[cq]t use a reference link in these contexts if-the link definition is somewhere else in the document.-.SS Backslash escapes-.SS Extension: \f[C]all_symbols_escapable\f[R]-.PP-Except inside a code block or inline code, any punctuation or space-character preceded by a backslash will be treated literally, even if it-would normally indicate formatting.-Thus, for example, if one writes-.IP-.nf-\f[C]-*\[rs]*hello\[rs]**-\f[R]-.fi-.PP-one will get-.IP-.nf-\f[C]-<em>*hello*</em>-\f[R]-.fi-.PP-instead of-.IP-.nf-\f[C]-<strong>hello</strong>-\f[R]-.fi-.PP-This rule is easier to remember than original Markdown\[cq]s rule, which-allows only the following characters to be backslash-escaped:-.IP-.nf-\f[C]-\[rs]\[ga]*_{}[]()>#+-.!-\f[R]-.fi-.PP-(However, if the \f[C]markdown_strict\f[R] format is used, the original-Markdown rule will be used.)-.PP-A backslash-escaped space is parsed as a nonbreaking space.-In TeX output, it will appear as \f[C]\[ti]\f[R].-In HTML and XML output, it will appear as a literal unicode nonbreaking-space character (note that it will thus actually look-\[lq]invisible\[rq] in the generated HTML source; you can still use the-\f[C]--ascii\f[R] command-line option to make it appear as an explicit-entity).-.PP-A backslash-escaped newline (i.e.\ a backslash occurring at the end of a-line) is parsed as a hard line break.-It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as-\f[C]<br />\f[R].-This is a nice alternative to Markdown\[cq]s \[lq]invisible\[rq] way of-indicating hard line breaks using two trailing spaces on a line.-.PP-Backslash escapes do not work in verbatim contexts.-.SS Inline formatting-.SS Emphasis-.PP-To \f[I]emphasize\f[R] some text, surround it with \f[C]*\f[R]s or-\f[C]_\f[R], like this:-.IP-.nf-\f[C]-This text is _emphasized with underscores_, and this-is *emphasized with asterisks*.-\f[R]-.fi-.PP-Double \f[C]*\f[R] or \f[C]_\f[R] produces \f[B]strong emphasis\f[R]:-.IP-.nf-\f[C]-This is **strong emphasis** and __with underscores__.-\f[R]-.fi-.PP-A \f[C]*\f[R] or \f[C]_\f[R] character surrounded by spaces, or-backslash-escaped, will not trigger emphasis:-.IP-.nf-\f[C]-This is * not emphasized *, and \[rs]*neither is this\[rs]*.-\f[R]-.fi-.SS Extension: \f[C]intraword_underscores\f[R]-.PP-Because \f[C]_\f[R] is sometimes used inside words and identifiers,-pandoc does not interpret a \f[C]_\f[R] surrounded by alphanumeric-characters as an emphasis marker.-If you want to emphasize just part of a word, use \f[C]*\f[R]:-.IP-.nf-\f[C]-feas*ible*, not feas*able*.-\f[R]-.fi-.SS Strikeout-.SS Extension: \f[C]strikeout\f[R]-.PP-To strikeout a section of text with a horizontal line, begin and end it-with \f[C]\[ti]\[ti]\f[R].-Thus, for example,-.IP-.nf-\f[C]-This \[ti]\[ti]is deleted text.\[ti]\[ti]-\f[R]-.fi-.SS Superscripts and subscripts-.SS Extension: \f[C]superscript\f[R], \f[C]subscript\f[R]-.PP-Superscripts may be written by surrounding the superscripted text by-\f[C]\[ha]\f[R] characters; subscripts may be written by surrounding the-subscripted text by \f[C]\[ti]\f[R] characters.-Thus, for example,-.IP-.nf-\f[C]-H\[ti]2\[ti]O is a liquid.  2\[ha]10\[ha] is 1024.-\f[R]-.fi-.PP-The text between \f[C]\[ha]...\[ha]\f[R] or \f[C]\[ti]...\[ti]\f[R] may-not contain spaces or newlines.-If the superscripted or subscripted text contains spaces, these spaces-must be escaped with backslashes.-(This is to prevent accidental superscripting and subscripting through-the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad-interactions with footnotes.)-Thus, if you want the letter P with `a cat' in subscripts, use-\f[C]P\[ti]a\[rs] cat\[ti]\f[R], not \f[C]P\[ti]a cat\[ti]\f[R].-.SS Verbatim-.PP-To make a short span of text verbatim, put it inside backticks:-.IP-.nf-\f[C]-What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]?-\f[R]-.fi-.PP-If the verbatim text includes a backtick, use double backticks:-.IP-.nf-\f[C]-Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga].-\f[R]-.fi-.PP-(The spaces after the opening backticks and before the closing backticks-will be ignored.)-.PP-The general rule is that a verbatim span starts with a string of-consecutive backticks (optionally followed by a space) and ends with a-string of the same number of backticks (optionally preceded by a space).-.PP-Note that backslash-escapes (and other Markdown constructs) do not work-in verbatim contexts:-.IP-.nf-\f[C]-This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga].-\f[R]-.fi-.SS Extension: \f[C]inline_code_attributes\f[R]-.PP-Attributes can be attached to verbatim text, just as with fenced code-blocks:-.IP-.nf-\f[C]-\[ga]<$>\[ga]{.haskell}-\f[R]-.fi-.SS Underline-.PP-To underline text, use the \f[C]underline\f[R] class:-.IP-.nf-\f[C]-[Underline]{.underline}-\f[R]-.fi-.PP-Or, without the \f[C]bracketed_spans\f[R] extension (but with-\f[C]native_spans\f[R]):-.IP-.nf-\f[C]-<span class=\[dq]underline\[dq]>Underline</span>-\f[R]-.fi-.PP-This will work in all output formats that support underline.-.SS Small caps-.PP-To write small caps, use the \f[C]smallcaps\f[R] class:-.IP-.nf-\f[C]-[Small caps]{.smallcaps}-\f[R]-.fi-.PP-Or, without the \f[C]bracketed_spans\f[R] extension:-.IP-.nf-\f[C]-<span class=\[dq]smallcaps\[dq]>Small caps</span>-\f[R]-.fi-.PP-For compatibility with other Markdown flavors, CSS is also supported:-.IP-.nf-\f[C]-<span style=\[dq]font-variant:small-caps;\[dq]>Small caps</span>-\f[R]-.fi-.PP-This will work in all output formats that support small caps.-.SS Math-.SS Extension: \f[C]tex_math_dollars\f[R]-.PP-Anything between two \f[C]$\f[R] characters will be treated as TeX math.-The opening \f[C]$\f[R] must have a non-space character immediately to-its right, while the closing \f[C]$\f[R] must have a non-space character-immediately to its left, and must not be followed immediately by a-digit.-Thus, \f[C]$20,000 and $30,000\f[R] won\[cq]t parse as math.-If for some reason you need to enclose text in literal \f[C]$\f[R]-characters, backslash-escape them and they won\[cq]t be treated as math-delimiters.-.PP-For display math, use \f[C]$$\f[R] delimiters.-(In this case, the delimiters may be separated from the formula by-whitespace.-However, there can be no blank lines betwen the opening and closing-\f[C]$$\f[R] delimiters.)-.PP-TeX math will be printed in all output formats.-How it is rendered depends on the output format:-.TP-LaTeX-It will appear verbatim surrounded by \f[C]\[rs](...\[rs])\f[R] (for-inline math) or \f[C]\[rs][...\[rs]]\f[R] (for display math).-.TP-Markdown, Emacs Org mode, ConTeXt, ZimWiki-It will appear verbatim surrounded by \f[C]$...$\f[R] (for inline math)-or \f[C]$$...$$\f[R] (for display math).-.TP-XWiki-It will appear verbatim surrounded by-\f[C]{{formula}}..{{/formula}}\f[R].-.TP-reStructuredText-It will be rendered using an interpreted text role \f[C]:math:\f[R].-.TP-AsciiDoc-For AsciiDoc output format (\f[C]-t asciidoc\f[R]) it will appear-verbatim surrounded by \f[C]latexmath:[$...$]\f[R] (for inline math) or-\f[C][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math).-For AsciiDoctor output format (\f[C]-t asciidoctor\f[R]) the LaTex-delimiters (\f[C]$..$\f[R] and \f[C]\[rs][..\[rs]]\f[R]) are omitted.-.TP-Texinfo-It will be rendered inside a \f[C]\[at]math\f[R] command.-.TP-roff man, Jira markup-It will be rendered verbatim without \f[C]$\f[R]\[cq]s.-.TP-MediaWiki, DokuWiki-It will be rendered inside \f[C]<math>\f[R] tags.-.TP-Textile-It will be rendered inside \f[C]<span class=\[dq]math\[dq]>\f[R] tags.-.TP-RTF, OpenDocument-It will be rendered, if possible, using Unicode characters, and will-otherwise appear verbatim.-.TP-ODT-It will be rendered, if possible, using MathML.-.TP-DocBook-If the \f[C]--mathml\f[R] flag is used, it will be rendered using MathML-in an \f[C]inlineequation\f[R] or \f[C]informalequation\f[R] tag.-Otherwise it will be rendered, if possible, using Unicode characters.-.TP-Docx-It will be rendered using OMML math markup.-.TP-FictionBook2-If the \f[C]--webtex\f[R] option is used, formulas are rendered as-images using CodeCogs or other compatible web service, downloaded and-embedded in the e-book.-Otherwise, they will appear verbatim.-.TP-HTML, Slidy, DZSlides, S5, EPUB-The way math is rendered in HTML will depend on the command-line options-selected.-Therefore see Math rendering in HTML above.-.SS Raw HTML-.SS Extension: \f[C]raw_html\f[R]-.PP-Markdown allows you to insert raw HTML (or DocBook) anywhere in a-document (except verbatim contexts, where \f[C]<\f[R], \f[C]>\f[R], and-\f[C]&\f[R] are interpreted literally).-(Technically this is not an extension, since standard Markdown allows-it, but it has been made an extension so that it can be disabled if-desired.)-.PP-The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,-DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile-output, and suppressed in other formats.-.PP-For a more explicit way of including raw HTML in a Markdown document,-see the \f[C]raw_attribute\f[R] extension.-.PP-In the CommonMark format, if \f[C]raw_html\f[R] is enabled,-superscripts, subscripts, strikeouts and small capitals will be-represented as HTML.-Otherwise, plain-text fallbacks will be used.-Note that even if \f[C]raw_html\f[R] is disabled, tables will be-rendered with HTML syntax if they cannot use pipe syntax.-.SS Extension: \f[C]markdown_in_html_blocks\f[R]-.PP-Original Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of-HTML between balanced tags that are separated from the surrounding text-with blank lines, and start and end at the left margin.-Within these blocks, everything is interpreted as HTML, not Markdown; so-(for example), \f[C]*\f[R] does not signify emphasis.-.PP-Pandoc behaves this way when the \f[C]markdown_strict\f[R] format is-used; but by default, pandoc interprets material between HTML block tags-as Markdown.-Thus, for example, pandoc will turn-.IP-.nf-\f[C]-<table>-<tr>-<td>*one*</td>-<td>[a link](https://google.com)</td>-</tr>-</table>-\f[R]-.fi-.PP-into-.IP-.nf-\f[C]-<table>-<tr>-<td><em>one</em></td>-<td><a href=\[dq]https://google.com\[dq]>a link</a></td>-</tr>-</table>-\f[R]-.fi-.PP-whereas \f[C]Markdown.pl\f[R] will preserve it as is.-.PP-There is one exception to this rule: text between \f[C]<script>\f[R],-\f[C]<style>\f[R], and \f[C]<textarea>\f[R] tags is not interpreted as-Markdown.-.PP-This departure from original Markdown should make it easier to mix-Markdown with HTML block elements.-For example, one can surround a block of Markdown text with-\f[C]<div>\f[R] tags without preventing it from being interpreted as-Markdown.-.SS Extension: \f[C]native_divs\f[R]-.PP-Use native pandoc \f[C]Div\f[R] blocks for content inside-\f[C]<div>\f[R] tags.-For the most part this should give the same output as-\f[C]markdown_in_html_blocks\f[R], but it makes it easier to write-pandoc filters to manipulate groups of blocks.-.SS Extension: \f[C]native_spans\f[R]-.PP-Use native pandoc \f[C]Span\f[R] blocks for content inside-\f[C]<span>\f[R] tags.-For the most part this should give the same output as-\f[C]raw_html\f[R], but it makes it easier to write pandoc filters to-manipulate groups of inlines.-.SS Extension: \f[C]raw_tex\f[R]-.PP-In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be-included in a document.-Inline TeX commands will be preserved and passed unchanged to the LaTeX-and ConTeXt writers.-Thus, for example, you can use LaTeX to include BibTeX citations:-.IP-.nf-\f[C]-This result was proved in \[rs]cite{jones.1967}.-\f[R]-.fi-.PP-Note that in LaTeX environments, like-.IP-.nf-\f[C]-\[rs]begin{tabular}{|l|l|}\[rs]hline-Age & Frequency \[rs]\[rs] \[rs]hline-18--25  & 15 \[rs]\[rs]-26--35  & 33 \[rs]\[rs]-36--45  & 22 \[rs]\[rs] \[rs]hline-\[rs]end{tabular}-\f[R]-.fi-.PP-the material between the begin and end tags will be interpreted as raw-LaTeX, not as Markdown.-.PP-For a more explicit and flexible way of including raw TeX in a Markdown-document, see the \f[C]raw_attribute\f[R] extension.-.PP-Inline LaTeX is ignored in output formats other than Markdown, LaTeX,-Emacs Org mode, and ConTeXt.-.SS Generic raw attribute-.SS Extension: \f[C]raw_attribute\f[R]-.PP-Inline spans and fenced code blocks with a special kind of attribute-will be parsed as raw content with the designated format.-For example, the following produces a raw roff \f[C]ms\f[R] block:-.IP-.nf-\f[C]-\[ga]\[ga]\[ga]{=ms}-\&.MYMACRO-blah blah-\[ga]\[ga]\[ga]-\f[R]-.fi-.PP-And the following produces a raw \f[C]html\f[R] inline element:-.IP-.nf-\f[C]-This is \[ga]<a>html</a>\[ga]{=html}-\f[R]-.fi-.PP-This can be useful to insert raw xml into \f[C]docx\f[R] documents, e.g.-a pagebreak:-.IP-.nf-\f[C]-\[ga]\[ga]\[ga]{=openxml}-<w:p>-  <w:r>-    <w:br w:type=\[dq]page\[dq]/>-  </w:r>-</w:p>-\[ga]\[ga]\[ga]-\f[R]-.fi-.PP-The format name should match the target format name (see-\f[C]-t/--to\f[R], above, for a list, or use-\f[C]pandoc --list-output-formats\f[R]).-Use \f[C]openxml\f[R] for \f[C]docx\f[R] output, \f[C]opendocument\f[R]-for \f[C]odt\f[R] output, \f[C]html5\f[R] for \f[C]epub3\f[R] output,-\f[C]html4\f[R] for \f[C]epub2\f[R] output, and \f[C]latex\f[R],-\f[C]beamer\f[R], \f[C]ms\f[R], or \f[C]html5\f[R] for \f[C]pdf\f[R]-output (depending on what you use for \f[C]--pdf-engine\f[R]).-.PP-This extension presupposes that the relevant kind of inline code or-fenced code block is enabled.-Thus, for example, to use a raw attribute with a backtick code block,-\f[C]backtick_code_blocks\f[R] must be enabled.-.PP-The raw attribute cannot be combined with regular attributes.-.SS LaTeX macros-.SS Extension: \f[C]latex_macros\f[R]-.PP-When this extension is enabled, pandoc will parse LaTeX macro-definitions and apply the resulting macros to all LaTeX math and raw-LaTeX.-So, for example, the following will work in all output formats, not just-LaTeX:-.IP-.nf-\f[C]-\[rs]newcommand{\[rs]tuple}[1]{\[rs]langle #1 \[rs]rangle}--$\[rs]tuple{a, b, c}$-\f[R]-.fi-.PP-Note that LaTeX macros will not be applied if they occur inside a raw-span or block marked with the \f[C]raw_attribute\f[R] extension.-.PP-When \f[C]latex_macros\f[R] is disabled, the raw LaTeX and math will not-have macros applied.-This is usually a better approach when you are targeting LaTeX or PDF.-.PP-Macro definitions in LaTeX will be passed through as raw LaTeX only if-\f[C]latex_macros\f[R] is not enabled.-Macro definitions in Markdown source (or other formats allowing-\f[C]raw_tex\f[R]) will be passed through regardless of whether-\f[C]latex_macros\f[R] is enabled.-.SS Links-.PP-Markdown allows links to be specified in several ways.-.SS Automatic links-.PP-If you enclose a URL or email address in pointy brackets, it will become-a link:-.IP-.nf-\f[C]-<https://google.com>-<sam\[at]green.eggs.ham>-\f[R]-.fi-.SS Inline links-.PP-An inline link consists of the link text in square brackets, followed by-the URL in parentheses.-(Optionally, the URL can be followed by a link title, in quotes.)-.IP-.nf-\f[C]-This is an [inline link](/url), and here\[aq]s [one with-a title](https://fsf.org \[dq]click here for a good time!\[dq]).-\f[R]-.fi-.PP-There can be no space between the bracketed part and the parenthesized-part.-The link text can contain formatting (such as emphasis), but the title-cannot.-.PP-Email addresses in inline links are not autodetected, so they have to be-prefixed with \f[C]mailto\f[R]:-.IP-.nf-\f[C]-[Write me!](mailto:sam\[at]green.eggs.ham)-\f[R]-.fi-.SS Reference links-.PP-An \f[I]explicit\f[R] reference link has two parts, the link itself and-the link definition, which may occur elsewhere in the document (either-before or after the link).-.PP-The link consists of link text in square brackets, followed by a label-in square brackets.-(There cannot be space between the two unless the-\f[C]spaced_reference_links\f[R] extension is enabled.)-The link definition consists of the bracketed label, followed by a colon-and a space, followed by the URL, and optionally (after a space) a link-title either in quotes or in parentheses.-The label must not be parseable as a citation (assuming the-\f[C]citations\f[R] extension is enabled): citations take precedence-over link labels.-.PP-Here are some examples:-.IP-.nf-\f[C]-[my label 1]: /foo/bar.html  \[dq]My title, optional\[dq]-[my label 2]: /foo-[my label 3]: https://fsf.org (The free software foundation)-[my label 4]: /bar#special  \[aq]A title in single quotes\[aq]-\f[R]-.fi-.PP-The URL may optionally be surrounded by angle brackets:-.IP-.nf-\f[C]-[my label 5]: <http://foo.bar.baz>-\f[R]-.fi-.PP-The title may go on the next line:-.IP-.nf-\f[C]-[my label 3]: https://fsf.org-  \[dq]The free software foundation\[dq]-\f[R]-.fi-.PP-Note that link labels are not case sensitive.-So, this will work:-.IP-.nf-\f[C]-Here is [my link][FOO]--[Foo]: /bar/baz-\f[R]-.fi-.PP-In an \f[I]implicit\f[R] reference link, the second pair of brackets is-empty:-.IP-.nf-\f[C]-See [my website][].--[my website]: http://foo.bar.baz-\f[R]-.fi-.PP-Note: In \f[C]Markdown.pl\f[R] and most other Markdown implementations,-reference link definitions cannot occur in nested constructions such as-list items or block quotes.-Pandoc lifts this arbitrary seeming restriction.-So the following is fine in pandoc, though not in most other-implementations:-.IP-.nf-\f[C]-> My block [quote].->-> [quote]: /foo-\f[R]-.fi-.SS Extension: \f[C]shortcut_reference_links\f[R]-.PP-In a \f[I]shortcut\f[R] reference link, the second pair of brackets may-be omitted entirely:-.IP-.nf-\f[C]-See [my website].--[my website]: http://foo.bar.baz-\f[R]-.fi-.SS Internal links-.PP-To link to another section of the same document, use the automatically-generated identifier (see Heading identifiers).-For example:-.IP-.nf-\f[C]-See the [Introduction](#introduction).-\f[R]-.fi-.PP-or-.IP-.nf-\f[C]-See the [Introduction].--[Introduction]: #introduction-\f[R]-.fi-.PP-Internal links are currently supported for HTML formats (including HTML-slide shows and EPUB), LaTeX, and ConTeXt.-.SS Images-.PP-A link immediately preceded by a \f[C]!\f[R] will be treated as an-image.-The link text will be used as the image\[cq]s alt text:-.IP-.nf-\f[C]-![la lune](lalune.jpg \[dq]Voyage to the moon\[dq])--![movie reel]--[movie reel]: movie.gif-\f[R]-.fi-.SS Extension: \f[C]implicit_figures\f[R]-.PP-An image with nonempty alt text, occurring by itself in a paragraph,-will be rendered as a figure with a caption.-The image\[cq]s alt text will be used as the caption.-.IP-.nf-\f[C]-![This is the caption](/url/of/image.png)-\f[R]-.fi-.PP-How this is rendered depends on the output format.-Some output formats (e.g.\ RTF) do not yet support figures.-In those formats, you\[cq]ll just get an image in a paragraph by itself,-with no caption.-.PP-If you just want a regular inline image, just make sure it is not the-only thing in the paragraph.-One way to do this is to insert a nonbreaking space after the image:-.IP-.nf-\f[C]-![This image won\[aq]t be a figure](/url/of/image.png)\[rs]-\f[R]-.fi-.PP-Note that in reveal.js slide shows, an image in a paragraph by itself-that has the \f[C]r-stretch\f[R] class will fill the screen, and the-caption and figure tags will be omitted.-.SS Extension: \f[C]link_attributes\f[R]-.PP-Attributes can be set on links and images:-.IP-.nf-\f[C]-An inline ![image](foo.jpg){#id .class width=30 height=20px}-and a reference ![image][ref] with attributes.--[ref]: foo.jpg \[dq]optional title\[dq] {#id .class key=val key2=\[dq]val 2\[dq]}-\f[R]-.fi-.PP-(This syntax is compatible with PHP Markdown Extra when only-\f[C]#id\f[R] and \f[C].class\f[R] are used.)-.PP-For HTML and EPUB, all known HTML5 attributes except \f[C]width\f[R] and-\f[C]height\f[R] (but including \f[C]srcset\f[R] and \f[C]sizes\f[R])-are passed through as is.-Unknown attributes are passed through as custom attributes, with-\f[C]data-\f[R] prepended.-The other writers ignore attributes that are not specifically supported-by their output format.-.PP-The \f[C]width\f[R] and \f[C]height\f[R] attributes on images are-treated specially.-When used without a unit, the unit is assumed to be pixels.-However, any of the following unit identifiers can be used:-\f[C]px\f[R], \f[C]cm\f[R], \f[C]mm\f[R], \f[C]in\f[R], \f[C]inch\f[R]-and \f[C]%\f[R].-There must not be any spaces between the number and the unit.-For example:-.IP-.nf-\f[C]-![](file.jpg){ width=50% }-\f[R]-.fi-.IP \[bu] 2-Dimensions may be converted to a form that is compatible with the output-format (for example, dimensions given in pixels will be converted to-inches when converting HTML to LaTeX).-Conversion between pixels and physical measurements is affected by the-\f[C]--dpi\f[R] option (by default, 96 dpi is assumed, unless the image-itself contains dpi information).-.IP \[bu] 2-The \f[C]%\f[R] unit is generally relative to some available space.-For example the above example will render to the following.-.RS 2-.IP \[bu] 2-HTML:-\f[C]<img href=\[dq]file.jpg\[dq] style=\[dq]width: 50%;\[dq] />\f[R]-.IP \[bu] 2-LaTeX:-\f[C]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]-(If you\[cq]re using a custom template, you need to configure-\f[C]graphicx\f[R] as in the default template.)-.IP \[bu] 2-ConTeXt:-\f[C]\[rs]externalfigure[file.jpg][width=0.5\[rs]textwidth]\f[R]-.RE-.IP \[bu] 2-Some output formats have a notion of a class (ConTeXt) or a unique-identifier (LaTeX \f[C]\[rs]caption\f[R]), or both (HTML).-.IP \[bu] 2-When no \f[C]width\f[R] or \f[C]height\f[R] attributes are specified,-the fallback is to look at the image resolution and the dpi metadata-embedded in the image file.-.SS Divs and Spans-.PP-Using the \f[C]native_divs\f[R] and \f[C]native_spans\f[R] extensions-(see above), HTML syntax can be used as part of markdown to create-native \f[C]Div\f[R] and \f[C]Span\f[R] elements in the pandoc AST (as-opposed to raw HTML).-However, there is also nicer syntax available:-.SS Extension: \f[C]fenced_divs\f[R]-.PP-Allow special fenced syntax for native \f[C]Div\f[R] blocks.-A Div starts with a fence containing at least three consecutive colons-plus some attributes.-The attributes may optionally be followed by another string of-consecutive colons.-The attribute syntax is exactly as in fenced code blocks (see Extension:-\f[C]fenced_code_attributes\f[R]).-As with fenced code blocks, one can use either attributes in curly-braces or a single unbraced word, which will be treated as a class name.-The Div ends with another line containing a string of at least three-consecutive colons.-The fenced Div should be separated by blank lines from preceding and-following blocks.-.PP-Example:-.IP-.nf-\f[C]-::::: {#special .sidebar}-Here is a paragraph.--And another.-:::::-\f[R]-.fi-.PP-Fenced divs can be nested.-Opening fences are distinguished because they \f[I]must\f[R] have-attributes:-.IP-.nf-\f[C]-::: Warning ::::::-This is a warning.--::: Danger-This is a warning within a warning.-:::-::::::::::::::::::-\f[R]-.fi-.PP-Fences without attributes are always closing fences.-Unlike with fenced code blocks, the number of colons in the closing-fence need not match the number in the opening fence.-However, it can be helpful for visual clarity to use fences of different-lengths to distinguish nested divs from their parents.-.SS Extension: \f[C]bracketed_spans\f[R]-.PP-A bracketed sequence of inlines, as one would use to begin a link, will-be treated as a \f[C]Span\f[R] with attributes if it is followed-immediately by attributes:-.IP-.nf-\f[C]-[This is *some text*]{.class key=\[dq]val\[dq]}-\f[R]-.fi-.SS Footnotes-.SS Extension: \f[C]footnotes\f[R]-.PP-Pandoc\[cq]s Markdown allows footnotes, using the following syntax:-.IP-.nf-\f[C]-Here is a footnote reference,[\[ha]1] and another.[\[ha]longnote]--[\[ha]1]: Here is the footnote.--[\[ha]longnote]: Here\[aq]s one with multiple blocks.--    Subsequent paragraphs are indented to show that they-belong to the previous footnote.--        { some.code }--    The whole paragraph can be indented, or just the first-    line.  In this way, multi-paragraph footnotes work like-    multi-paragraph list items.--This paragraph won\[aq]t be part of the note, because it-isn\[aq]t indented.-\f[R]-.fi-.PP-The identifiers in footnote references may not contain spaces, tabs, or-newlines.-These identifiers are used only to correlate the footnote reference with-the note itself; in the output, footnotes will be numbered sequentially.-.PP-The footnotes themselves need not be placed at the end of the document.-They may appear anywhere except inside other block elements (lists,-block quotes, tables, etc.).-Each footnote should be separated from surrounding content (including-other footnotes) by blank lines.-.SS Extension: \f[C]inline_notes\f[R]-.PP-Inline footnotes are also allowed (though, unlike regular notes, they-cannot contain multiple paragraphs).-The syntax is as follows:-.IP-.nf-\f[C]-Here is an inline note.\[ha][Inlines notes are easier to write, since-you don\[aq]t have to pick an identifier and move down to type the-note.]-\f[R]-.fi-.PP-Inline and regular footnotes may be mixed freely.-.SS Citation syntax-.SS Extension: \f[C]citations\f[R]-.PP-To cite a bibliographic item with an identifier foo, use the syntax-\f[C]\[at]foo\f[R].-Normal citations should be included in square brackets, with semicolons-separating distinct items:-.IP-.nf-\f[C]-Blah blah [\[at]doe99; \[at]smith2000; \[at]smith2004].-\f[R]-.fi-.PP-How this is rendered depends on the citation style.-In an author-date style, it might render as-.IP-.nf-\f[C]-Blah blah (Doe 1999, Smith 2000, 2004).-\f[R]-.fi-.PP-In a footnote style, it might render as-.IP-.nf-\f[C]-Blah blah.[\[ha]1]--[\[ha]1]:  John Doe, \[dq]Frogs,\[dq] *Journal of Amphibians* 44 (1999);-Susan Smith, \[dq]Flies,\[dq] *Journal of Insects* (2000);-Susan Smith, \[dq]Bees,\[dq] *Journal of Insects* (2004).-\f[R]-.fi-.PP-See the CSL user documentation for more information about CSL styles and-how they affect rendering.-.PP-Unless a citation key start with a letter, digit, or \f[C]_\f[R], and-contains only alphanumerics and single internal punctuation characters-(\f[C]:.#$%&-+?<>\[ti]/\f[R]), it must be surrounded by curly braces,-which are not considered part of the key.-In \f[C]\[at]Foo_bar.baz.\f[R], the key is \f[C]Foo_bar.baz\f[R] because-the final period is not \f[I]internal\f[R] punctuation, so it is not-included in the key.-In \f[C]\[at]{Foo_bar.baz.}\f[R], the key is \f[C]Foo_bar.baz.\f[R],-including the final period.-In \f[C]\[at]Foo_bar--baz\f[R], the key is \f[C]Foo_bar\f[R] because the-repeated internal punctuation characters terminate the key.-The curly braces are recommended if you use URLs as keys:-\f[C][\[at]{https://example.com/bib?name=foobar&date=2000}, p.  33]\f[R].-.PP-Citation items may optionally include a prefix, a locator, and a suffix.-In-.IP-.nf-\f[C]-Blah blah [see \[at]doe99, pp. 33-35 and *passim*; \[at]smith04, chap. 1].-\f[R]-.fi-.PP-The first item (\f[C]doe99\f[R]) has prefix \f[C]see\f[R], locator-\f[C]pp.  33-35\f[R], and suffix \f[C]and *passim*\f[R].-The second item (\f[C]smith04\f[R]) has locator \f[C]chap. 1\f[R] and no-prefix or suffix.-.PP-Pandoc uses some heuristics to separate the locator from the rest of the-subject.-It is sensitive to the locator terms defined in the CSL locale files.-Either abbreviated or unabbreviated forms are accepted.-In the \f[C]en-US\f[R] locale, locator terms can be written in either-singular or plural forms, as \f[C]book\f[R],-\f[C]bk.\f[R]/\f[C]bks.\f[R]; \f[C]chapter\f[R],-\f[C]chap.\f[R]/\f[C]chaps.\f[R]; \f[C]column\f[R],-\f[C]col.\f[R]/\f[C]cols.\f[R]; \f[C]figure\f[R],-\f[C]fig.\f[R]/\f[C]figs.\f[R]; \f[C]folio\f[R],-\f[C]fol.\f[R]/\f[C]fols.\f[R]; \f[C]number\f[R],-\f[C]no.\f[R]/\f[C]nos.\f[R]; \f[C]line\f[R],-\f[C]l.\f[R]/\f[C]ll.\f[R]; \f[C]note\f[R], \f[C]n.\f[R]/\f[C]nn.\f[R];-\f[C]opus\f[R], \f[C]op.\f[R]/\f[C]opp.\f[R]; \f[C]page\f[R],-\f[C]p.\f[R]/\f[C]pp.\f[R]; \f[C]paragraph\f[R],-\f[C]para.\f[R]/\f[C]paras.\f[R]; \f[C]part\f[R],-\f[C]pt.\f[R]/\f[C]pts.\f[R]; \f[C]section\f[R],-\f[C]sec.\f[R]/\f[C]secs.\f[R]; \f[C]sub verbo\f[R],-\f[C]s.v.\f[R]/\f[C]s.vv.\f[R]; \f[C]verse\f[R],-\f[C]v.\f[R]/\f[C]vv.\f[R]; \f[C]volume\f[R],-\f[C]vol.\f[R]/\f[C]vols.\f[R]; \f[C]\[ps]\f[R]/\f[C]\[ps]\[ps]\f[R];-\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].-If no locator term is used, \[lq]page\[rq] is assumed.-.PP-In complex cases, you can force something to be treated as a locator by-enclosing it in curly braces or prevent parsing the suffix as locator by-prepending curly braces:-.IP-.nf-\f[C]-[\[at]smith{ii, A, D-Z}, with a suffix]-[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]-[\[at]smith{}, 99 years later]-\f[R]-.fi-.PP-A minus sign (\f[C]-\f[R]) before the \f[C]\[at]\f[R] will suppress-mention of the author in the citation.-This can be useful when the author is already mentioned in the text:-.IP-.nf-\f[C]-Smith says blah [-\[at]smith04].-\f[R]-.fi-.PP-You can also write an author-in-text citation, by omitting the square-brackets:-.IP-.nf-\f[C]-\[at]smith04 says blah.--\[at]smith04 [p. 33] says blah.-\f[R]-.fi-.PP-This will cause the author\[cq]s name to be rendered, followed by the-bibliographical details.-Use this form when you want to make the citation the subject of a-sentence.-.PP-When you are using a note style, it is usually better to let citeproc-create the footnotes from citations rather than writing an explicit-note.-If you do write an explicit note that contains a citation, note that-normal citations will be put in parentheses, while author-in-text-citations will not.-For this reason, it is sometimes preferable to use the author-in-text-style inside notes when using a note style.-.SS Non-default extensions-.PP-The following Markdown syntax extensions are not enabled by default in-pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format-name, where \f[C]EXTENSION\f[R] is the name of the extension.-Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with-hard line breaks.-.SS Extension: \f[C]rebase_relative_paths\f[R]-.PP-Rewrite relative paths for Markdown links and images, depending on the-path of the file containing the link or image link.-For each link or image, pandoc will compute the directory of the-containing file, relative to the working directory, and prepend the-resulting path to the link or image path.-.PP-The use of this extension is best understood by example.-Suppose you have a a subdirectory for each chapter of a book,-\f[C]chap1\f[R], \f[C]chap2\f[R], \f[C]chap3\f[R].-Each contains a file \f[C]text.md\f[R] and a number of images used in-the chapter.-You would like to have \f[C]![image](spider.jpg)\f[R] in-\f[C]chap1/text.md\f[R] refer to \f[C]chap1/spider.jpg\f[R] and-\f[C]![image](spider.jpg)\f[R] in \f[C]chap2/text.md\f[R] refer to-\f[C]chap2/spider.jpg\f[R].-To do this, use-.IP-.nf-\f[C]-pandoc chap*/*.md -f markdown+rebase_relative_paths-\f[R]-.fi-.PP-Without this extension, you would have to use-\f[C]![image](chap1/spider.jpg)\f[R] in \f[C]chap1/text.md\f[R] and-\f[C]![image](chap2/spider.jpg)\f[R] in \f[C]chap2/text.md\f[R].-Links with relative paths will be rewritten in the same way as images.-.PP-Absolute paths and URLs are not changed.-Neither are empty paths or paths consisting entirely of a fragment,-e.g., \f[C]#foo\f[R].-.PP-Note that relative paths in reference links and images will be rewritten-relative to the file containing the link reference definition, not the-file containing the reference link or image itself, if these differ.-.SS Extension: \f[C]attributes\f[R]-.PP-Allows attributes to be attached to any inline or block-level element-when parsing \f[C]commonmark\f[R].-The syntax for the attributes is the same as that used in-\f[C]header_attributes\f[R].-.IP \[bu] 2-Attributes that occur immediately after an inline element affect that-element.-If they follow a space, then they belong to the space.-(Hence, this option subsumes \f[C]inline_code_attributes\f[R] and-\f[C]link_attributes\f[R].)-.IP \[bu] 2-Attributes that occur immediately before a block element, on a line by-themselves, affect that element.-.IP \[bu] 2-Consecutive attribute specifiers may be used, either for blocks or for-inlines.-Their attributes will be combined.-.IP \[bu] 2-Attributes that occur at the end of the text of a Setext or ATX heading-(separated by whitespace from the text) affect the heading element.-(Hence, this option subsumes \f[C]header_attributes\f[R].)-.IP \[bu] 2-Attributes that occur after the opening fence in a fenced code block-affect the code block element.-(Hence, this option subsumes \f[C]fenced_code_attributes\f[R].)-.IP \[bu] 2-Attributes that occur at the end of a reference link definition affect-links that refer to that definition.-.PP-Note that pandoc\[cq]s AST does not currently allow attributes to be-attached to arbitrary elements.-Hence a Span or Div container will be added if needed.-.SS Extension: \f[C]old_dashes\f[R]-.PP-Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:-\f[C]-\f[R] before a numeral is an en-dash, and \f[C]--\f[R] is an-em-dash.-This option only has an effect if \f[C]smart\f[R] is enabled.-It is selected automatically for \f[C]textile\f[R] input.-.SS Extension: \f[C]angle_brackets_escapable\f[R]-.PP-Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can-be in GitHub flavored Markdown but not original Markdown.-This is implied by pandoc\[cq]s default \f[C]all_symbols_escapable\f[R].-.SS Extension: \f[C]lists_without_preceding_blankline\f[R]-.PP-Allow a list to occur right after a paragraph, with no intervening blank-space.-.SS Extension: \f[C]four_space_rule\f[R]-.PP-Selects the pandoc <= 2.0 behavior for parsing lists, so that four-spaces indent are needed for list item continuation paragraphs.-.SS Extension: \f[C]spaced_reference_links\f[R]-.PP-Allow whitespace between the two components of a reference link, for-example,-.IP-.nf-\f[C]-[foo] [bar].-\f[R]-.fi-.SS Extension: \f[C]hard_line_breaks\f[R]-.PP-Causes all newlines within a paragraph to be interpreted as hard line-breaks instead of spaces.-.SS Extension: \f[C]ignore_line_breaks\f[R]-.PP-Causes newlines within a paragraph to be ignored, rather than being-treated as spaces or as hard line breaks.-This option is intended for use with East Asian languages where spaces-are not used between words, but text is divided into lines for-readability.-.SS Extension: \f[C]east_asian_line_breaks\f[R]-.PP-Causes newlines within a paragraph to be ignored, rather than being-treated as spaces or as hard line breaks, when they occur between two-East Asian wide characters.-This is a better choice than \f[C]ignore_line_breaks\f[R] for texts that-include a mix of East Asian wide characters and other characters.-.SS Extension: \f[C]emoji\f[R]-.PP-Parses textual emojis like \f[C]:smile:\f[R] as Unicode emoticons.-.SS Extension: \f[C]tex_math_single_backslash\f[R]-.PP-Causes anything between \f[C]\[rs](\f[R] and \f[C]\[rs])\f[R] to be-interpreted as inline TeX math, and anything between \f[C]\[rs][\f[R]-and \f[C]\[rs]]\f[R] to be interpreted as display TeX math.-Note: a drawback of this extension is that it precludes escaping-\f[C](\f[R] and \f[C][\f[R].-.SS Extension: \f[C]tex_math_double_backslash\f[R]-.PP-Causes anything between \f[C]\[rs]\[rs](\f[R] and \f[C]\[rs]\[rs])\f[R]-to be interpreted as inline TeX math, and anything between-\f[C]\[rs]\[rs][\f[R] and \f[C]\[rs]\[rs]]\f[R] to be interpreted as-display TeX math.-.SS Extension: \f[C]markdown_attribute\f[R]-.PP-By default, pandoc interprets material inside block-level tags as-Markdown.-This extension changes the behavior so that Markdown is only parsed-inside block-level tags if the tags have the attribute-\f[C]markdown=1\f[R].-.SS Extension: \f[C]mmd_title_block\f[R]-.PP-Enables a MultiMarkdown style title block at the top of the document,-for example:-.IP-.nf-\f[C]-Title:   My title-Author:  John Doe-Date:    September 1, 2008-Comment: This is a sample mmd title block, with-         a field spanning multiple lines.-\f[R]-.fi-.PP-See the MultiMarkdown documentation for details.-If \f[C]pandoc_title_block\f[R] or \f[C]yaml_metadata_block\f[R] is-enabled, it will take precedence over \f[C]mmd_title_block\f[R].-.SS Extension: \f[C]abbreviations\f[R]-.PP-Parses PHP Markdown Extra abbreviation keys, like-.IP-.nf-\f[C]-*[HTML]: Hypertext Markup Language-\f[R]-.fi-.PP-Note that the pandoc document model does not support abbreviations, so-if this extension is enabled, abbreviation keys are simply skipped (as-opposed to being parsed as paragraphs).-.SS Extension: \f[C]autolink_bare_uris\f[R]-.PP-Makes all absolute URIs into links, even when not surrounded by pointy-braces \f[C]<...>\f[R].-.SS Extension: \f[C]mmd_link_attributes\f[R]-.PP-Parses multimarkdown style key-value attributes on link and image-references.-This extension should not be confused with the \f[C]link_attributes\f[R]-extension.-.IP-.nf-\f[C]-This is a reference ![image][ref] with multimarkdown attributes.--[ref]: https://path.to/image \[dq]Image title\[dq] width=20px height=30px-       id=myId class=\[dq]myClass1 myClass2\[dq]-\f[R]-.fi-.SS Extension: \f[C]mmd_header_identifiers\f[R]-.PP-Parses multimarkdown style heading identifiers (in square brackets,-after the heading but before any trailing \f[C]#\f[R]s in an ATX-heading).-.SS Extension: \f[C]compact_definition_lists\f[R]-.PP-Activates the definition list syntax of pandoc 1.12.x and earlier.-This syntax differs from the one described above under Definition lists-in several respects:-.IP \[bu] 2-No blank line is required between consecutive items of the definition-list.-.IP \[bu] 2-To get a \[lq]tight\[rq] or \[lq]compact\[rq] list, omit space between-consecutive items; the space between a term and its definition does not-affect anything.-.IP \[bu] 2-Lazy wrapping of paragraphs is not allowed: the entire definition must-be indented four spaces.-.SS Extension: \f[C]gutenberg\f[R]-.PP-Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps-for strong emphasis, surround by underscores for regular emphasis, add-extra blank space around headings.-.SS Extension: \f[C]sourcepos\f[R]-.PP-Include source position attributes when parsing \f[C]commonmark\f[R].-For elements that accept attributes, a \f[C]data-pos\f[R] attribute is-added; other elements are placed in a surrounding Div or Span element-with a \f[C]data-pos\f[R] attribute.-.SS Extension: \f[C]short_subsuperscripts\f[R]-.PP-Parse multimarkdown style subscripts and superscripts, which start with-a `\[ti]' or `\[ha]' character, respectively, and include the-alphanumeric sequence that follows.-For example:-.IP-.nf-\f[C]-x\[ha]2 = 4-\f[R]-.fi-.PP-or-.IP-.nf-\f[C]-Oxygen is O\[ti]2.-\f[R]-.fi-.SS Markdown variants-.PP-In addition to pandoc\[cq]s extended Markdown, the following Markdown-variants are supported:-.IP \[bu] 2-\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)-.IP \[bu] 2-\f[C]markdown_github\f[R] (deprecated GitHub-Flavored Markdown)-.IP \[bu] 2-\f[C]markdown_mmd\f[R] (MultiMarkdown)-.IP \[bu] 2-\f[C]markdown_strict\f[R] (Markdown.pl)-.IP \[bu] 2-\f[C]commonmark\f[R] (CommonMark)-.IP \[bu] 2-\f[C]gfm\f[R] (Github-Flavored Markdown)-.IP \[bu] 2-\f[C]commonmark_x\f[R] (CommonMark with many pandoc extensions)-.PP-To see which extensions are supported for a given format, and which are-enabled by default, you can use the command-.IP-.nf-\f[C]-pandoc --list-extensions=FORMAT-\f[R]-.fi-.PP-where \f[C]FORMAT\f[R] is replaced with the name of the format.-.PP-Note that the list of extensions for \f[C]commonmark\f[R],-\f[C]gfm\f[R], and \f[C]commonmark_x\f[R] are defined relative to-default commonmark.-So, for example, \f[C]backtick_code_blocks\f[R] does not appear as an-extension, since it is enabled by default and cannot be disabled.-.SH CITATIONS-.PP-When the \f[C]--citeproc\f[R] option is used, pandoc can automatically-generate citations and a bibliography in a number of styles.-Basic usage is-.IP-.nf-\f[C]-pandoc --citeproc myinput.txt-\f[R]-.fi-.PP-To use this feature, you will need to have-.IP \[bu] 2-a document containing citations (see Extension: \f[C]citations\f[R]);-.IP \[bu] 2-a source of bibliographic data: either an external bibliography file or-a list of \f[C]references\f[R] in the document\[cq]s YAML metadata-.IP \[bu] 2-optionally, a CSL citation style.-.SS Specifying bibliographic data-.PP-You can specify an external bibliography using the-\f[C]bibliography\f[R] metadata field in a YAML metadata section or the-\f[C]--bibliography\f[R] command line argument.-If you want to use multiple bibliography files, you can supply multiple-\f[C]--bibliography\f[R] arguments or set \f[C]bibliography\f[R]-metadata field to YAML array.-A bibliography may have any of these formats:-.PP-.TS-tab(@);-l l.-T{-Format-T}@T{-File extension-T}-_-T{-BibLaTeX-T}@T{-\&.bib-T}-T{-BibTeX-T}@T{-\&.bibtex-T}-T{-CSL JSON-T}@T{-\&.json-T}-T{-CSL YAML-T}@T{-\&.yaml-T}-.TE-.PP-Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX-files; use the extension \f[C].bibtex\f[R] to force interpretation as-BibTeX.-.PP-In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside-fields such as \f[C]title\f[R]; in CSL YAML databases, pandoc Markdown;-and in CSL JSON databases, an HTML-like markup:-.TP-\f[B]\f[CB]<i>...</i>\f[B]\f[R]-italics-.TP-\f[B]\f[CB]<b>...</b>\f[B]\f[R]-bold-.TP-\f[B]\f[CB]<span style=\[dq]font-variant:small-caps;\[dq]>...</span>\f[B]\f[R] or \f[B]\f[CB]<sc>...</sc>\f[B]\f[R]-small capitals-.TP-\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]-subscript-.TP-\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]-superscript-.TP-\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]-prevent a phrase from being capitalized as title case-.PP-As an alternative to specifying a bibliography file using-\f[C]--bibliography\f[R] or the YAML metadata field-\f[C]bibliography\f[R], you can include the citation data directly in-the \f[C]references\f[R] field of the document\[cq]s YAML metadata.-The field should contain an array of YAML-encoded references, for-example:-.IP-.nf-\f[C]-----references:-- type: article-journal-  id: WatsonCrick1953-  author:-  - family: Watson-    given: J. D.-  - family: Crick-    given: F. H. C.-  issued:-    date-parts:-    - - 1953-      - 4-      - 25-  title: \[aq]Molecular structure of nucleic acids: a structure for-    deoxyribose nucleic acid\[aq]-  title-short: Molecular structure of nucleic acids-  container-title: Nature-  volume: 171-  issue: 4356-  page: 737-738-  DOI: 10.1038/171737a0-  URL: https://www.nature.com/articles/171737a0-  language: en-GB-\&...-\f[R]-.fi-.PP-If both an external bibliography and inline (YAML metadata) references-are provided, both will be used.-In case of conflicting \f[C]id\f[R]s, the inline references will take-precedence.-.PP-Note that \f[C]pandoc\f[R] can be used to produce such a YAML metadata-section from a BibTeX, BibLaTeX, or CSL JSON bibliography:-.IP-.nf-\f[C]-pandoc chem.bib -s -f biblatex -t markdown-pandoc chem.json -s -f csljson -t markdown-\f[R]-.fi-.PP-Indeed, \f[C]pandoc\f[R] can convert between any of these citation-formats:-.IP-.nf-\f[C]-pandoc chem.bib -s -f biblatex -t csljson-pandoc chem.yaml -s -f markdown -t biblatex-\f[R]-.fi-.PP-Running pandoc on a bibliography file with the \f[C]--citeproc\f[R]-option will create a formatted bibliography in the format of your-choice:-.IP-.nf-\f[C]-pandoc chem.bib -s --citeproc -o chem.html-pandoc chem.bib -s --citeproc -o chem.pdf-\f[R]-.fi-.SS Capitalization in titles-.PP-If you are using a bibtex or biblatex bibliography, then observe the-following rules:-.IP \[bu] 2-English titles should be in title case.-Non-English titles should be in sentence case, and the \f[C]langid\f[R]-field in biblatex should be set to the relevant language.-(The following values are treated as English: \f[C]american\f[R],-\f[C]british\f[R], \f[C]canadian\f[R], \f[C]english\f[R],-\f[C]australian\f[R], \f[C]newzealand\f[R], \f[C]USenglish\f[R], or-\f[C]UKenglish\f[R].)-.IP \[bu] 2-As is standard with bibtex/biblatex, proper names should be protected-with curly braces so that they won\[cq]t be lowercased in styles that-call for sentence case.-For example:-.RS 2-.IP-.nf-\f[C]-title = {My Dinner with {Andre}}-\f[R]-.fi-.RE-.IP \[bu] 2-In addition, words that should remain lowercase (or camelCase) should be-protected:-.RS 2-.IP-.nf-\f[C]-title = {Spin Wave Dispersion on the {nm} Scale}-\f[R]-.fi-.PP-Though this is not necessary in bibtex/biblatex, it is necessary with-citeproc, which stores titles internally in sentence case, and converts-to title case in styles that require it.-Here we protect \[lq]nm\[rq] so that it doesn\[cq]t get converted to-\[lq]Nm\[rq] at this stage.-.RE-.PP-If you are using a CSL bibliography (either JSON or YAML), then observe-the following rules:-.IP \[bu] 2-All titles should be in sentence case.-.IP \[bu] 2-Use the \f[C]language\f[R] field for non-English titles to prevent their-conversion to title case in styles that call for this.-(Conversion happens only if \f[C]language\f[R] begins with \f[C]en\f[R]-or is left empty.)-.IP \[bu] 2-Protect words that should not be converted to title case using this-syntax:-.RS 2-.IP-.nf-\f[C]-Spin wave dispersion on the <span class=\[dq]nocase\[dq]>nm</span> scale-\f[R]-.fi-.RE-.SS Conference Papers, Published vs.\ Unpublished-.PP-For a formally published conference paper, use the biblatex entry type-\f[C]inproceedings\f[R] (which will be mapped to CSL-\f[C]paper-conference\f[R]).-.PP-For an unpublished manuscript, use the biblatex entry type-\f[C]unpublished\f[R] without an \f[C]eventtitle\f[R] field (this entry-type will be mapped to CSL \f[C]manuscript\f[R]).-.PP-For a talk, an unpublished conference paper, or a poster presentation,-use the biblatex entry type \f[C]unpublished\f[R] with an-\f[C]eventtitle\f[R] field (this entry type will be mapped to CSL-\f[C]speech\f[R]).-Use the biblatex \f[C]type\f[R] field to indicate the type,-e.g.\ \[lq]Paper\[rq], or \[lq]Poster\[rq].-\f[C]venue\f[R] and \f[C]eventdate\f[R] may be useful too, though-\f[C]eventdate\f[R] will not be rendered by most CSL styles.-Note that \f[C]venue\f[R] is for the event\[cq]s venue, unlike-\f[C]location\f[R] which describes the publisher\[cq]s location; do not-use the latter for an unpublished conference paper.-.SS Specifying a citation style-.PP-Citations and references can be formatted using any style supported by-the Citation Style Language, listed in the Zotero Style Repository.-These files are specified using the \f[C]--csl\f[R] option or the-\f[C]csl\f[R] (or \f[C]citation-style\f[R]) metadata field.-By default, pandoc will use the Chicago Manual of Style author-date-format.-(You can override this default by copying a CSL style of your choice to-\f[C]default.csl\f[R] in your user data directory.)-The CSL project provides further information on finding and editing-styles.-.PP-The \f[C]--citation-abbreviations\f[R] option (or the-\f[C]citation-abbreviations\f[R] metadata field) may be used to specify-a JSON file containing abbreviations of journals that should be used in-formatted bibliographies when \f[C]form=\[dq]short\[dq]\f[R] is-specified.-The format of the file can be illustrated with an example:-.IP-.nf-\f[C]-{ \[dq]default\[dq]: {-    \[dq]container-title\[dq]: {-            \[dq]Lloyd\[aq]s Law Reports\[dq]: \[dq]Lloyd\[aq]s Rep\[dq],-            \[dq]Estates Gazette\[dq]: \[dq]EG\[dq],-            \[dq]Scots Law Times\[dq]: \[dq]SLT\[dq]-    }-  }-}-\f[R]-.fi-.SS Citations in note styles-.PP-Pandoc\[cq]s citation processing is designed to allow you to move-between author-date, numerical, and note styles without modifying the-markdown source.-When you\[cq]re using a note style, avoid inserting footnotes manually.-Instead, insert citations just as you would in an author-date-style\[em]for example,-.IP-.nf-\f[C]-Blah blah [\[at]foo, p. 33].-\f[R]-.fi-.PP-The footnote will be created automatically.-Pandoc will take care of removing the space and moving the note before-or after the period, depending on the setting of-\f[C]notes-after-punctuation\f[R], as described below in Other relevant-metadata fields.-.PP-In some cases you may need to put a citation inside a regular footnote.-Normal citations in footnotes (such as \f[C][\[at]foo, p. 33]\f[R]) will-be rendered in parentheses.-In-text citations (such as \f[C]\[at]foo [p. 33]\f[R]) will be rendered-without parentheses.-(A comma will be added if appropriate.)-Thus:-.IP-.nf-\f[C]-[\[ha]1]:  Some studies [\[at]foo; \[at]bar, p. 33] show that-frubulicious zoosnaps are quantical.  For a survey-of the literature, see \[at]baz [chap. 1].-\f[R]-.fi-.SS Raw content in a style-.PP-To include raw content in a prefix, suffix, delimiter, or term, surround-it with these tags indicating the format:-.IP-.nf-\f[C]-{{jats}}&lt;ref&gt;{{/jats}}-\f[R]-.fi-.PP-Without the tags, the string will be interpreted as a string and escaped-in the output, rather than being passed through raw.-.PP-This feature allows stylesheets to be customized to give different-output for different output formats.-However, stylesheets customized in this way will not be usable by other-CSL implementations.-.SS Placement of the bibliography-.PP-If the style calls for a list of works cited, it will be placed in a div-with id \f[C]refs\f[R], if one exists:-.IP-.nf-\f[C]-::: {#refs}-:::-\f[R]-.fi-.PP-Otherwise, it will be placed at the end of the document.-Generation of the bibliography can be suppressed by setting-\f[C]suppress-bibliography: true\f[R] in the YAML metadata.-.PP-If you wish the bibliography to have a section heading, you can set-\f[C]reference-section-title\f[R] in the metadata, or put the heading at-the beginning of the div with id \f[C]refs\f[R] (if you are using it) or-at the end of your document:-.IP-.nf-\f[C]-last paragraph...--# References-\f[R]-.fi-.PP-The bibliography will be inserted after this heading.-Note that the \f[C]unnumbered\f[R] class will be added to this heading,-so that the section will not be numbered.-.SS Including uncited items in the bibliography-.PP-If you want to include items in the bibliography without actually citing-them in the body text, you can define a dummy \f[C]nocite\f[R] metadata-field and put the citations there:-.IP-.nf-\f[C]-----nocite: |-  \[at]item1, \[at]item2-\&...--\[at]item3-\f[R]-.fi-.PP-In this example, the document will contain a citation for-\f[C]item3\f[R] only, but the bibliography will contain entries for-\f[C]item1\f[R], \f[C]item2\f[R], and \f[C]item3\f[R].-.PP-It is possible to create a bibliography with all the citations, whether-or not they appear in the document, by using a wildcard:-.IP-.nf-\f[C]-----nocite: |-  \[at]*-\&...-\f[R]-.fi-.PP-For LaTeX output, you can also use \f[C]natbib\f[R] or-\f[C]biblatex\f[R] to render the bibliography.-In order to do so, specify bibliography files as outlined above, and add-\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]-invocation.-Bear in mind that bibliography files have to be in either BibTeX (for-\f[C]--natbib\f[R]) or BibLaTeX (for \f[C]--biblatex\f[R]) format.-.SS Other relevant metadata fields-.PP-A few other metadata fields affect bibliography formatting:-.TP-\f[B]\f[CB]link-citations\f[B]\f[R]-If true, citations will be hyperlinked to the corresponding bibliography-entries (for author-date and numerical styles only).-Defaults to false.-.TP-\f[B]\f[CB]link-bibliography\f[B]\f[R]-If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered-as hyperlinks.-(If an entry contains a DOI, PMCID, PMID, or URL, but none of these-fields are rendered by the style, then the title, or in the absence of a-title the whole entry, will be hyperlinked.)-Defaults to true.-.TP-\f[B]\f[CB]lang\f[B]\f[R]-The \f[C]lang\f[R] field will affect how the style is localized, for-example in the translation of labels, the use of quotation marks, and-the way items are sorted.-(For backwards compatibility, \f[C]locale\f[R] may be used instead of-\f[C]lang\f[R], but this use is deprecated.)-.RS-.PP-A BCP 47 language tag is expected: for example, \f[C]en\f[R],-\f[C]de\f[R], \f[C]en-US\f[R], \f[C]fr-CA\f[R], \f[C]ug-Cyrl\f[R].-The unicode extension syntax (after \f[C]-u-\f[R]) may be used to-specify options for collation (sorting) more precisely.-Here are some examples:-.IP \[bu] 2-\f[C]zh-u-co-pinyin\f[R] \[en] Chinese with the Pinyin collation.-.IP \[bu] 2-\f[C]es-u-co-trad\f[R] \[en] Spanish with the traditional collation-(with \f[C]Ch\f[R] sorting after \f[C]C\f[R]).-.IP \[bu] 2-\f[C]fr-u-kb\f[R] \[en] French with \[lq]backwards\[rq] accent sorting-(with \f[C]cot\['e]\f[R] sorting after \f[C]c\[^o]te\f[R]).-.IP \[bu] 2-\f[C]en-US-u-kf-upper\f[R] \[en] English with uppercase letters sorting-before lower (default is lower before upper).-.RE-.TP-\f[B]\f[CB]notes-after-punctuation\f[B]\f[R]-If true (the default for note styles), pandoc will put footnote-references or superscripted numerical citations after following-punctuation.-For example, if the source contains \f[C]blah blah [\[at]jones99].\f[R],-the result will look like \f[C]blah blah.[\[ha]1]\f[R], with the note-moved after the period and the space collapsed.-If false, the space will still be collapsed, but the footnote will not-be moved after the punctuation.-The option may also be used in numerical styles that use superscripts-for citation numbers (but for these styles the default is not to move-the citation).-.SH SLIDE SHOWS-.PP-You can use pandoc to produce an HTML + JavaScript slide presentation-that can be viewed via a web browser.-There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or-reveal.js.-You can also produce a PDF slide show using LaTeX \f[C]beamer\f[R], or-slides shows in Microsoft PowerPoint format.-.PP-Here\[cq]s the Markdown source for a simple slide show,-\f[C]habits.txt\f[R]:-.IP-.nf-\f[C]-% Habits-% John Doe-% March 22, 2005--# In the morning--## Getting up--- Turn off alarm-- Get out of bed--## Breakfast--- Eat eggs-- Drink coffee--# In the evening--## Dinner--- Eat spaghetti-- Drink wine----------------------![picture of spaghetti](images/spaghetti.jpg)--## Going to sleep--- Get in bed-- Count sheep-\f[R]-.fi-.PP-To produce an HTML/JavaScript slide show, simply type-.IP-.nf-\f[C]-pandoc -t FORMAT -s habits.txt -o habits.html-\f[R]-.fi-.PP-where \f[C]FORMAT\f[R] is either \f[C]s5\f[R], \f[C]slidy\f[R],-\f[C]slideous\f[R], \f[C]dzslides\f[R], or \f[C]revealjs\f[R].-.PP-For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with-the \f[C]-s/--standalone\f[R] option embeds a link to JavaScript and CSS-files, which are assumed to be available at the relative path-\f[C]s5/default\f[R] (for S5), \f[C]slideous\f[R] (for Slideous),-\f[C]reveal.js\f[R] (for reveal.js), or at the Slidy website at-\f[C]w3.org\f[R] (for Slidy).-(These paths can be changed by setting the \f[C]slidy-url\f[R],-\f[C]slideous-url\f[R], \f[C]revealjs-url\f[R], or \f[C]s5-url\f[R]-variables; see Variables for HTML slides, above.)-For DZSlides, the (relatively short) JavaScript and CSS are included in-the file by default.-.PP-With all HTML slide formats, the \f[C]--self-contained\f[R] option can-be used to produce a single file that contains all of the data necessary-to display the slide show, including linked scripts, stylesheets,-images, and videos.-.PP-To produce a PDF slide show using beamer, type-.IP-.nf-\f[C]-pandoc -t beamer habits.txt -o habits.pdf-\f[R]-.fi-.PP-Note that a reveal.js slide show can also be converted to a PDF by-printing it to a file from the browser.-.PP-To produce a Powerpoint slide show, type-.IP-.nf-\f[C]-pandoc habits.txt -o habits.pptx-\f[R]-.fi-.SS Structuring the slide show-.PP-By default, the \f[I]slide level\f[R] is the highest heading level in-the hierarchy that is followed immediately by content, and not another-heading, somewhere in the document.-In the example above, level-1 headings are always followed by level-2-headings, which are followed by content, so the slide level is 2.-This default can be overridden using the \f[C]--slide-level\f[R] option.-.PP-The document is carved up into slides according to the following rules:-.IP \[bu] 2-A horizontal rule always starts a new slide.-.IP \[bu] 2-A heading at the slide level always starts a new slide.-.IP \[bu] 2-Headings \f[I]below\f[R] the slide level in the hierarchy create-headings \f[I]within\f[R] a slide.-(In beamer, a \[lq]block\[rq] will be created.-If the heading has the class \f[C]example\f[R], an-\f[C]exampleblock\f[R] environment will be used; if it has the class-\f[C]alert\f[R], an \f[C]alertblock\f[R] will be used; otherwise a-regular \f[C]block\f[R] will be used.)-.IP \[bu] 2-Headings \f[I]above\f[R] the slide level in the hierarchy create-\[lq]title slides,\[rq] which just contain the section title and help to-break the slide show into sections.-Non-slide content under these headings will be included on the title-slide (for HTML slide shows) or in a subsequent slide with the same-title (for beamer).-.IP \[bu] 2-A title page is constructed automatically from the document\[cq]s title-block, if present.-(In the case of beamer, this can be disabled by commenting out some-lines in the default template.)-.PP-These rules are designed to support many different styles of slide show.-If you don\[cq]t care about structuring your slides into sections and-subsections, you can either just use level-1 headings for all slides (in-that case, level 1 will be the slide level) or you can set-\f[C]--slide-level=0\f[R].-.PP-Note: in reveal.js slide shows, if slide level is 2, a two-dimensional-layout will be produced, with level-1 headings building horizontally and-level-2 headings building vertically.-It is not recommended that you use deeper nesting of section levels with-reveal.js unless you set \f[C]--slide-level=0\f[R] (which lets reveal.js-produce a one-dimensional layout and only interprets horizontal rules as-slide boundaries).-.SS PowerPoint layout choice-.PP-When creating slides, the pptx writer chooses from a number of-pre-defined layouts, based on the content of the slide:-.TP-Title Slide-This layout is used for the initial slide, which is generated and filled-from the metadata fields \f[C]date\f[R], \f[C]author\f[R], and-\f[C]title\f[R], if they are present.-.TP-Section Header-This layout is used for what pandoc calls \[lq]title slides\[rq], i.e.-slides which start with a header which is above the slide level in the-hierarchy.-.TP-Two Content-This layout is used for two-column slides, i.e.\ slides containing a div-with class \f[C]columns\f[R] which contains at least two divs with class-\f[C]column\f[R].-.TP-Comparison-This layout is used instead of \[lq]Two Content\[rq] for any two-column-slides in which at least one column contains text followed by non-text-(e.g.\ an image or a table).-.TP-Content with Caption-This layout is used for any non-two-column slides which contain text-followed by non-text (e.g.\ an image or a table).-.TP-Blank-This layout is used for any slides which only contain blank content,-e.g.\ a slide containing only speaker notes, or a slide containing only-a non-breaking space.-.TP-Title and Content-This layout is used for all slides which do not match the criteria for-another layout.-.PP-These layouts are chosen from the default pptx reference doc included-with pandoc, unless an alternative reference doc is specified using-\f[C]--reference-doc\f[R].-.SS Incremental lists-.PP-By default, these writers produce lists that display \[lq]all at-once.\[rq] If you want your lists to display incrementally (one item at-a time), use the \f[C]-i\f[R] option.-If you want a particular list to depart from the default, put it in a-\f[C]div\f[R] block with class \f[C]incremental\f[R] or-\f[C]nonincremental\f[R].-So, for example, using the \f[C]fenced div\f[R] syntax, the following-would be incremental regardless of the document default:-.IP-.nf-\f[C]-::: incremental--- Eat spaghetti-- Drink wine--:::-\f[R]-.fi-.PP-or-.IP-.nf-\f[C]-::: nonincremental--- Eat spaghetti-- Drink wine--:::-\f[R]-.fi-.PP-While using \f[C]incremental\f[R] and \f[C]nonincremental\f[R] divs are-the recommended method of setting incremental lists on a per-case basis,-an older method is also supported: putting lists inside a blockquote-will depart from the document default (that is, it will display-incrementally without the \f[C]-i\f[R] option and all at once with the-\f[C]-i\f[R] option):-.IP-.nf-\f[C]-> - Eat spaghetti-> - Drink wine-\f[R]-.fi-.PP-Both methods allow incremental and nonincremental lists to be mixed in a-single document.-.SS Inserting pauses-.PP-You can add \[lq]pauses\[rq] within a slide by including a paragraph-containing three dots, separated by spaces:-.IP-.nf-\f[C]-# Slide with a pause--content before the pause--\&. . .--content after the pause-\f[R]-.fi-.PP-Note: this feature is not yet implemented for PowerPoint output.-.SS Styling the slides-.PP-You can change the style of HTML slides by putting customized CSS files-in \f[C]$DATADIR/s5/default\f[R] (for S5), \f[C]$DATADIR/slidy\f[R] (for-Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where-\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],-above).-The originals may be found in pandoc\[cq]s system data directory-(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).-Pandoc will look there for any files it does not find in the user data-directory.-.PP-For dzslides, the CSS is included in the HTML file itself, and may be-modified there.-.PP-All reveal.js configuration options can be set through variables.-For example, themes can be used by setting the \f[C]theme\f[R] variable:-.IP-.nf-\f[C]--V theme=moon-\f[R]-.fi-.PP-Or you can specify a custom stylesheet using the \f[C]--css\f[R] option.-.PP-To style beamer slides, you can specify a \f[C]theme\f[R],-\f[C]colortheme\f[R], \f[C]fonttheme\f[R], \f[C]innertheme\f[R], and-\f[C]outertheme\f[R], using the \f[C]-V\f[R] option:-.IP-.nf-\f[C]-pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf-\f[R]-.fi-.PP-Note that heading attributes will turn into slide attributes (on a-\f[C]<div>\f[R] or \f[C]<section>\f[R]) in HTML slide formats, allowing-you to style individual slides.-In beamer, the only heading attribute that affects slides is the-\f[C]allowframebreaks\f[R] class, which sets the-\f[C]allowframebreaks\f[R] option, causing multiple slides to be created-if the content overfills the frame.-This is recommended especially for bibliographies:-.IP-.nf-\f[C]-# References {.allowframebreaks}-\f[R]-.fi-.SS Speaker notes-.PP-Speaker notes are supported in reveal.js and PowerPoint (pptx) output.-You can add notes to your Markdown document thus:-.IP-.nf-\f[C]-::: notes--This is my note.--- It can contain Markdown-- like this list--:::-\f[R]-.fi-.PP-To show the notes window in reveal.js, press \f[C]s\f[R] while viewing-the presentation.-Speaker notes in PowerPoint will be available, as usual, in handouts and-presenter view.-.PP-Notes are not yet supported for other slide formats, but the notes will-not appear on the slides themselves.-.SS Columns-.PP-To put material in side by side columns, you can use a native div-container with class \f[C]columns\f[R], containing two or more div-containers with class \f[C]column\f[R] and a \f[C]width\f[R] attribute:-.IP-.nf-\f[C]-:::::::::::::: {.columns}-::: {.column width=\[dq]40%\[dq]}-contents...-:::-::: {.column width=\[dq]60%\[dq]}-contents...-:::-::::::::::::::-\f[R]-.fi-.SS Additional columns attributes in beamer-.PP-The div containers with classes \f[C]columns\f[R] and \f[C]column\f[R]-can optionally have an \f[C]align\f[R] attribute.-The class \f[C]columns\f[R] can optionally have a \f[C]totalwidth\f[R]-attribute or an \f[C]onlytextwidth\f[R] class.-.IP-.nf-\f[C]-:::::::::::::: {.columns align=center totalwidth=8em}-::: {.column width=\[dq]40%\[dq]}-contents...-:::-::: {.column width=\[dq]60%\[dq] align=bottom}-contents...-:::-::::::::::::::-\f[R]-.fi-.PP-The \f[C]align\f[R] attributes on \f[C]columns\f[R] and \f[C]column\f[R]-can be used with the values \f[C]top\f[R], \f[C]top-baseline\f[R],-\f[C]center\f[R] and \f[C]bottom\f[R] to vertically align the columns.-It defaults to \f[C]top\f[R] in \f[C]columns\f[R].-.PP-The \f[C]totalwidth\f[R] attribute limits the width of the columns to-the given value.-.IP-.nf-\f[C]-:::::::::::::: {.columns align=top .onlytextwidth}-::: {.column width=\[dq]40%\[dq] align=center}-contents...-:::-::: {.column width=\[dq]60%\[dq]}-contents...-:::-::::::::::::::-\f[R]-.fi-.PP-The class \f[C]onlytextwidth\f[R] sets the \f[C]totalwidth\f[R] to-\f[C]\[rs]textwidth\f[R].-.PP-See Section 12.7 of the Beamer User\[cq]s Guide for more details.-.SS Frame attributes in beamer-.PP-Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[R] option to-a frame in beamer (for example, when using the \f[C]minted\f[R]-environment).-This can be forced by adding the \f[C]fragile\f[R] class to the heading-introducing the slide:-.IP-.nf-\f[C]-# Fragile slide {.fragile}-\f[R]-.fi-.PP-All of the other frame attributes described in Section 8.1 of the Beamer-User\[cq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],-\f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],-\f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],-\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].-.SS Background in reveal.js, beamer, and pptx-.PP-Background images can be added to self-contained reveal.js slide shows,-beamer slide shows, and pptx slide shows.-.SS On all slides (beamer, reveal.js, pptx)-.PP-With beamer and reveal.js, the configuration option-\f[C]background-image\f[R] can be used either in the YAML metadata block-or as a command-line variable to get the same image on every slide.-.PP-For pptx, you can use a reference doc in which background images have-been set on the relevant layouts.-.SS \f[C]parallaxBackgroundImage\f[R] (reveal.js)-.PP-For reveal.js, there is also the reveal.js-native option-\f[C]parallaxBackgroundImage\f[R], which can be used instead of-\f[C]background-image\f[R] to produce a parallax scrolling background.-You must also set \f[C]parallaxBackgroundSize\f[R], and can optionally-set \f[C]parallaxBackgroundHorizontal\f[R] and-\f[C]parallaxBackgroundVertical\f[R] to configure the scrolling-behaviour.-See the reveal.js documentation for more details about the meaning of-these options.-.PP-In reveal.js\[cq]s overview mode, the parallaxBackgroundImage will show-up only on the first slide.-.SS On individual slides (reveal.js, pptx)-.PP-To set an image for a particular reveal.js or pptx slide, add-\f[C]{background-image=\[dq]/path/to/image\[dq]}\f[R] to the first-slide-level heading on the slide (which may even be empty).-.PP-As the HTML writers pass unknown attributes through, other reveal.js-background settings also work on individual slides, including-\f[C]background-size\f[R], \f[C]background-repeat\f[R],-\f[C]background-color\f[R], \f[C]transition\f[R], and-\f[C]transition-speed\f[R].-(The \f[C]data-\f[R] prefix will automatically be added.)-.PP-Note: \f[C]data-background-image\f[R] is also supported in pptx for-consistency with reveal.js \[en] if \f[C]background-image\f[R] isn\[cq]t-found, \f[C]data-background-image\f[R] will be checked.-.SS On the title slide (reveal.js, pptx)-.PP-To add a background image to the automatically generated title slide for-reveal.js, use the \f[C]title-slide-attributes\f[R] variable in the YAML-metadata block.-It must contain a map of attribute names and values.-(Note that the \f[C]data-\f[R] prefix is required here, as it isn\[cq]t-added automatically.)-.PP-For pptx, pass a reference doc with the background image set on the-\[lq]Title Slide\[rq] layout.-.SS Example (reveal.js)-.IP-.nf-\f[C]-----title: My Slide Show-parallaxBackgroundImage: /path/to/my/background_image.png-title-slide-attributes:-    data-background-image: /path/to/title_image.png-    data-background-size: contain------## Slide One--Slide 1 has background_image.png as its background.--## {background-image=\[dq]/path/to/special_image.jpg\[dq]}--Slide 2 has a special image for its background, even though the heading has no content.-\f[R]-.fi-.SH EPUBS-.SS EPUB Metadata-.PP-EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]-option, but if the source document is Markdown, it is better to use a-YAML metadata block.-Here is an example:-.IP-.nf-\f[C]-----title:-- type: main-  text: My Book-- type: subtitle-  text: An investigation of metadata-creator:-- role: author-  text: John Smith-- role: editor-  text: Sarah Jones-identifier:-- scheme: DOI-  text: doi:10.234234.234/33-publisher:  My Press-rights: \[co] 2007 John Smith, CC BY-NC-ibooks:-  version: 1.3.4-\&...-\f[R]-.fi-.PP-The following fields are recognized:-.TP-\f[B]\f[CB]identifier\f[B]\f[R]-Either a string value or an object with fields \f[C]text\f[R] and-\f[C]scheme\f[R].-Valid values for \f[C]scheme\f[R] are \f[C]ISBN-10\f[R],-\f[C]GTIN-13\f[R], \f[C]UPC\f[R], \f[C]ISMN-10\f[R], \f[C]DOI\f[R],-\f[C]LCCN\f[R], \f[C]GTIN-14\f[R], \f[C]ISBN-13\f[R],-\f[C]Legal deposit number\f[R], \f[C]URN\f[R], \f[C]OCLC\f[R],-\f[C]ISMN-13\f[R], \f[C]ISBN-A\f[R], \f[C]JP\f[R], \f[C]OLCC\f[R].-.TP-\f[B]\f[CB]title\f[B]\f[R]-Either a string value, or an object with fields \f[C]file-as\f[R] and-\f[C]type\f[R], or a list of such objects.-Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],-\f[C]short\f[R], \f[C]collection\f[R], \f[C]edition\f[R],-\f[C]extended\f[R].-.TP-\f[B]\f[CB]creator\f[B]\f[R]-Either a string value, or an object with fields \f[C]role\f[R],-\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.-Valid values for \f[C]role\f[R] are MARC relators, but pandoc will-attempt to translate the human-readable versions (like \[lq]author\[rq]-and \[lq]editor\[rq]) to the appropriate marc relators.-.TP-\f[B]\f[CB]contributor\f[B]\f[R]-Same format as \f[C]creator\f[R].-.TP-\f[B]\f[CB]date\f[B]\f[R]-A string value in \f[C]YYYY-MM-DD\f[R] format.-(Only the year is necessary.)-Pandoc will attempt to convert other common date formats.-.TP-\f[B]\f[CB]lang\f[B]\f[R] (or legacy: \f[B]\f[CB]language\f[B]\f[R])-A string value in BCP 47 format.-Pandoc will default to the local language if nothing is specified.-.TP-\f[B]\f[CB]subject\f[B]\f[R]-Either a string value, or an object with fields \f[C]text\f[R],-\f[C]authority\f[R], and \f[C]term\f[R], or a list of such objects.-Valid values for \f[C]authority\f[R] are either a reserved authority-value (currently \f[C]AAT\f[R], \f[C]BIC\f[R], \f[C]BISAC\f[R],-\f[C]CLC\f[R], \f[C]DDC\f[R], \f[C]CLIL\f[R], \f[C]EuroVoc\f[R],-\f[C]MEDTOP\f[R], \f[C]LCSH\f[R], \f[C]NDC\f[R], \f[C]Thema\f[R],-\f[C]UDC\f[R], and \f[C]WGS\f[R]) or an absolute IRI identifying a-custom scheme.-Valid values for \f[C]term\f[R] are defined by the scheme.-.TP-\f[B]\f[CB]description\f[B]\f[R]-A string value.-.TP-\f[B]\f[CB]type\f[B]\f[R]-A string value.-.TP-\f[B]\f[CB]format\f[B]\f[R]-A string value.-.TP-\f[B]\f[CB]relation\f[B]\f[R]-A string value.-.TP-\f[B]\f[CB]coverage\f[B]\f[R]-A string value.-.TP-\f[B]\f[CB]rights\f[B]\f[R]-A string value.-.TP-\f[B]\f[CB]belongs-to-collection\f[B]\f[R]-A string value.-identifies the name of a collection to which the EPUB Publication-belongs.-.TP-\f[B]\f[CB]group-position\f[B]\f[R]-The \f[C]group-position\f[R] field indicates the numeric position in-which the EPUB Publication belongs relative to other works belonging to-the same \f[C]belongs-to-collection\f[R] field.-.TP-\f[B]\f[CB]cover-image\f[B]\f[R]-A string value (path to cover image).-.TP-\f[B]\f[CB]css\f[B]\f[R] (or legacy: \f[B]\f[CB]stylesheet\f[B]\f[R])-A string value (path to CSS stylesheet).-.TP-\f[B]\f[CB]page-progression-direction\f[B]\f[R]-Either \f[C]ltr\f[R] or \f[C]rtl\f[R].-Specifies the \f[C]page-progression-direction\f[R] attribute for the-\f[C]spine\f[R] element.-.TP-\f[B]\f[CB]ibooks\f[B]\f[R]-iBooks-specific metadata, with the following fields:-.RS-.IP \[bu] 2-\f[C]version\f[R]: (string)-.IP \[bu] 2-\f[C]specified-fonts\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default-\f[C]false\f[R])-.IP \[bu] 2-\f[C]ipad-orientation-lock\f[R]:-\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]-.IP \[bu] 2-\f[C]iphone-orientation-lock\f[R]:-\f[C]portrait-only\f[R]|\f[C]landscape-only\f[R]-.IP \[bu] 2-\f[C]binding\f[R]: \f[C]true\f[R]|\f[C]false\f[R] (default-\f[C]true\f[R])-.IP \[bu] 2-\f[C]scroll-axis\f[R]:-\f[C]vertical\f[R]|\f[C]horizontal\f[R]|\f[C]default\f[R]-.RE-.SS The \f[C]epub:type\f[R] attribute-.PP-For \f[C]epub3\f[R] output, you can mark up the heading that corresponds-to an EPUB chapter using the \f[C]epub:type\f[R] attribute.-For example, to set the attribute to the value \f[C]prologue\f[R], use-this markdown:-.IP-.nf-\f[C]-# My chapter {epub:type=prologue}-\f[R]-.fi-.PP-Which will result in:-.IP-.nf-\f[C]-<body epub:type=\[dq]frontmatter\[dq]>-  <section epub:type=\[dq]prologue\[dq]>-    <h1>My chapter</h1>-\f[R]-.fi-.PP-Pandoc will output \f[C]<body epub:type=\[dq]bodymatter\[dq]>\f[R],-unless you use one of the following values, in which case either-\f[C]frontmatter\f[R] or \f[C]backmatter\f[R] will be output.-.PP-.TS-tab(@);-l l.-T{-\f[C]epub:type\f[R] of first section-T}@T{-\f[C]epub:type\f[R] of body-T}-_-T{-prologue-T}@T{-frontmatter-T}-T{-abstract-T}@T{-frontmatter-T}-T{-acknowledgments-T}@T{-frontmatter-T}-T{-copyright-page-T}@T{-frontmatter-T}-T{-dedication-T}@T{-frontmatter-T}-T{-credits-T}@T{-frontmatter-T}-T{-keywords-T}@T{-frontmatter-T}-T{-imprint-T}@T{-frontmatter-T}-T{-contributors-T}@T{-frontmatter-T}-T{-other-credits-T}@T{-frontmatter-T}-T{-errata-T}@T{-frontmatter-T}-T{-revision-history-T}@T{-frontmatter-T}-T{-titlepage-T}@T{-frontmatter-T}-T{-halftitlepage-T}@T{-frontmatter-T}-T{-seriespage-T}@T{-frontmatter-T}-T{-foreword-T}@T{-frontmatter-T}-T{-preface-T}@T{-frontmatter-T}-T{-frontispiece-T}@T{-frontmatter-T}-T{-appendix-T}@T{-backmatter-T}-T{-colophon-T}@T{-backmatter-T}-T{-bibliography-T}@T{-backmatter-T}-T{-index-T}@T{-backmatter-T}-.TE-.SS Linked media-.PP-By default, pandoc will download media referenced from any-\f[C]<img>\f[R], \f[C]<audio>\f[R], \f[C]<video>\f[R] or-\f[C]<source>\f[R] element present in the generated EPUB, and include it-in the EPUB container, yielding a completely self-contained EPUB.-If you want to link to external media resources instead, use raw HTML in-your source and add \f[C]data-external=\[dq]1\[dq]\f[R] to the tag with-the \f[C]src\f[R] attribute.-For example:-.IP-.nf-\f[C]-<audio controls=\[dq]1\[dq]>-  <source src=\[dq]https://example.com/music/toccata.mp3\[dq]-          data-external=\[dq]1\[dq] type=\[dq]audio/mpeg\[dq]>-  </source>-</audio>-\f[R]-.fi-.PP-If the input format already is HTML then-\f[C]data-external=\[dq]1\[dq]\f[R] will work as expected for-\f[C]<img>\f[R] elements.-Similarly, for Markdown, external images can be declared with-\f[C]![img](url){external=1}\f[R].-Note that this only works for images; the other media elements have no-native representation in pandoc\[cq]s AST and requires the use of raw-HTML.-.SS EPUB styling-.PP-By default, pandoc will include some basic styling contained in its-\f[C]epub.css\f[R] data file.-(To see this, use \f[C]pandoc --print-default-data-file epub.css\f[R].)-To use a different CSS file, just use the \f[C]--css\f[R] command line-option.-A few inline styles are defined in addition; these are essential for-correct formatting of pandoc\[cq]s HTML output.-.PP-The \f[C]document-css\f[R] variable may be set if the more opinionated-styling of pandoc\[cq]s default HTML templates is desired (and in that-case the variables defined in Variables for HTML may be used to-fine-tune the style).-.SH JUPYTER NOTEBOOKS-.PP-When creating a Jupyter notebook, pandoc will try to infer the notebook-structure.-Code blocks with the class \f[C]code\f[R] will be taken as code cells,-and intervening content will be taken as Markdown cells.-Attachments will automatically be created for images in Markdown cells.-Metadata will be taken from the \f[C]jupyter\f[R] metadata field.-For example:-.IP-.nf-\f[C]-----title: My notebook-jupyter:-  nbformat: 4-  nbformat_minor: 5-  kernelspec:-     display_name: Python 2-     language: python-     name: python2-  language_info:-     codemirror_mode:-       name: ipython-       version: 2-     file_extension: \[dq].py\[dq]-     mimetype: \[dq]text/x-python\[dq]-     name: \[dq]python\[dq]-     nbconvert_exporter: \[dq]python\[dq]-     pygments_lexer: \[dq]ipython2\[dq]-     version: \[dq]2.7.15\[dq]------# Lorem ipsum--**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus-bibendum felis dictum sodales.--\[ga]\[ga]\[ga] code-print(\[dq]hello\[dq])-\[ga]\[ga]\[ga]--## Pyout--\[ga]\[ga]\[ga] code-from IPython.display import HTML-HTML(\[dq]\[dq]\[dq]-<script>-console.log(\[dq]hello\[dq]);-</script>-<b>HTML</b>-\[dq]\[dq]\[dq])-\[ga]\[ga]\[ga]--## Image--This image ![image](myimage.png) will be-included as a cell attachment.-\f[R]-.fi-.PP-If you want to add cell attributes, group cells differently, or add-output to code cells, then you need to include divs to indicate the-structure.-You can use either fenced divs or native divs for this.-Here is an example:-.IP-.nf-\f[C]-:::::: {.cell .markdown}-# Lorem--**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus-bibendum felis dictum sodales.-::::::--:::::: {.cell .code execution_count=1}-\[ga]\[ga]\[ga] {.python}-print(\[dq]hello\[dq])-\[ga]\[ga]\[ga]--::: {.output .stream .stdout}-\[ga]\[ga]\[ga]-hello-\[ga]\[ga]\[ga]-:::-::::::--:::::: {.cell .code execution_count=2}-\[ga]\[ga]\[ga] {.python}-from IPython.display import HTML-HTML(\[dq]\[dq]\[dq]-<script>-console.log(\[dq]hello\[dq]);-</script>-<b>HTML</b>-\[dq]\[dq]\[dq])-\[ga]\[ga]\[ga]--::: {.output .execute_result execution_count=2}-\[ga]\[ga]\[ga]{=html}-<script>-console.log(\[dq]hello\[dq]);-</script>-<b>HTML</b>-hello-\[ga]\[ga]\[ga]-:::-::::::-\f[R]-.fi-.PP-If you include raw HTML or TeX in an output cell, use the [raw-attribute][Extension: \f[C]fenced_attribute\f[R]], as shown in the last-cell of the example above.-Although pandoc can process \[lq]bare\[rq] raw HTML and TeX, the result-is often interspersed raw elements and normal textual elements, and in-an output cell pandoc expects a single, connected raw block.-To avoid using raw HTML or TeX except when marked explicitly using raw-attributes, we recommend specifying the extensions-\f[C]-raw_html-raw_tex+raw_attribute\f[R] when translating between-Markdown and ipynb notebooks.-.PP-Note that options and extensions that affect reading and writing of-Markdown will also affect Markdown cells in ipynb notebooks.-For example, \f[C]--wrap=preserve\f[R] will preserve soft line breaks in-Markdown cells; \f[C]--atx-headers\f[R] will cause ATX-style headings to-be used; and \f[C]--preserve-tabs\f[R] will prevent tabs from being-turned to spaces.-.SH SYNTAX HIGHLIGHTING-.PP-Pandoc will automatically highlight syntax in fenced code blocks that-are marked with a language name.-The Haskell library skylighting is used for highlighting.-Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and-LaTeX/PDF output.-To see a list of language names that pandoc will recognize, type-\f[C]pandoc --list-highlight-languages\f[R].-.PP-The color scheme can be selected using the \f[C]--highlight-style\f[R]-option.-The default color scheme is \f[C]pygments\f[R], which imitates the-default color scheme used by the Python library pygments (though-pygments is not actually used to do the highlighting).-To see a list of highlight styles, type-\f[C]pandoc --list-highlight-styles\f[R].-.PP-If you are not satisfied with the predefined styles, you can use-\f[C]--print-highlight-style\f[R] to generate a JSON \f[C].theme\f[R]-file which can be modified and used as the argument to-\f[C]--highlight-style\f[R].-To get a JSON version of the \f[C]pygments\f[R] style, for example:-.IP-.nf-\f[C]-pandoc --print-highlight-style pygments > my.theme-\f[R]-.fi-.PP-Then edit \f[C]my.theme\f[R] and use it like this:-.IP-.nf-\f[C]-pandoc --highlight-style my.theme-\f[R]-.fi-.PP-If you are not satisfied with the built-in highlighting, or you want-highlight a language that isn\[cq]t supported, you can use the-\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax-definition file.-Before writing your own, have a look at KDE\[cq]s repository of syntax-definitions.-.PP-To disable highlighting, use the \f[C]--no-highlight\f[R] option.-.SH CUSTOM STYLES-.PP-Custom styles can be used in the docx and ICML formats.-.SS Output-.PP-By default, pandoc\[cq]s docx and ICML output applies a predefined set-of styles for blocks such as paragraphs and block quotes, and uses-largely default formatting (italics, bold) for inlines.-This will work for most purposes, especially alongside a-\f[C]reference.docx\f[R] file.-However, if you need to apply your own styles to blocks, or match a-preexisting set of styles, pandoc allows you to define custom styles for-blocks and text using \f[C]div\f[R]s and \f[C]span\f[R]s, respectively.-.PP-If you define a \f[C]div\f[R] or \f[C]span\f[R] with the attribute-\f[C]custom-style\f[R], pandoc will apply your specified style to the-contained elements (with the exception of elements whose function-depends on a style, like headings, code blocks, block quotes, or links).-So, for example, using the \f[C]bracketed_spans\f[R] syntax,-.IP-.nf-\f[C]-[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.-\f[R]-.fi-.PP-would produce a docx file with \[lq]Get out\[rq] styled with character-style \f[C]Emphatically\f[R].-Similarly, using the \f[C]fenced_divs\f[R] syntax,-.IP-.nf-\f[C]-Dickinson starts the poem simply:--::: {custom-style=\[dq]Poetry\[dq]}-| A Bird came down the Walk----| He did not know I saw----:::-\f[R]-.fi-.PP-would style the two contained lines with the \f[C]Poetry\f[R] paragraph-style.-.PP-For docx output, styles will be defined in the output file as inheriting-from normal text, if the styles are not yet in your reference.docx.-If they are already defined, pandoc will not alter the definition.-.PP-This feature allows for greatest customization in conjunction with-pandoc filters.-If you want all paragraphs after block quotes to be indented, you can-write a filter to apply the styles necessary.-If you want all italics to be transformed to the \f[C]Emphasis\f[R]-character style (perhaps to change their color), you can write a filter-which will transform all italicized inlines to inlines within an-\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].-.PP-For docx output, you don\[cq]t need to enable any extensions for custom-styles to work.-.SS Input-.PP-The docx reader, by default, only reads those styles that it can convert-into pandoc elements, either by direct conversion or interpreting the-derivation of the input document\[cq]s styles.-.PP-By enabling the \f[C]styles\f[R] extension in the docx reader-(\f[C]-f docx+styles\f[R]), you can produce output that maintains the-styles of the input document, using the \f[C]custom-style\f[R] class.-Paragraph styles are interpreted as divs, while character styles are-interpreted as spans.-.PP-For example, using the \f[C]custom-style-reference.docx\f[R] file in the-test directory, we have the following different outputs:-.PP-Without the \f[C]+styles\f[R] extension:-.IP-.nf-\f[C]-$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown-This is some text.--This is text with an *emphasized* text style. And this is text with a-**strengthened** text style.--> Here is a styled paragraph that inherits from Block Text.-\f[R]-.fi-.PP-And with the extension:-.IP-.nf-\f[C]-$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown--::: {custom-style=\[dq]First Paragraph\[dq]}-This is some text.-:::--::: {custom-style=\[dq]Body Text\[dq]}-This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style.-And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]}-text style.-:::--::: {custom-style=\[dq]My Block Style\[dq]}-> Here is a styled paragraph that inherits from Block Text.-:::-\f[R]-.fi-.PP-With these custom styles, you can use your input document as a-reference-doc while creating docx output (see below), and maintain the-same styles in your input and output files.-.SH CUSTOM READERS AND WRITERS-.PP-Pandoc can be extended with custom readers and writers written in Lua.-(Pandoc includes a Lua interpreter, so Lua need not be installed-separately.)-.PP-To use a custom reader or writer, simply specify the path to the Lua-script in place of the input or output format.-For example:-.IP-.nf-\f[C]-pandoc -t data/sample.lua-pandoc -f my_custom_markup_language.lua -t latex -s-\f[R]-.fi-.PP-A custom reader is a Lua script that defines one function, Reader, which-takes a string as input and returns a Pandoc AST.-See the Lua filters documentation for documentation of the functions-that are available for creating pandoc AST elements.-For parsing, the lpeg parsing library is available by default.-To see a sample custom reader:-.IP-.nf-\f[C]-pandoc --print-default-data-file creole.lua-\f[R]-.fi-.PP-If you want your custom reader to have access to reader options-(e.g.\ the tab stop setting), you give your Reader function a second-\f[C]options\f[R] parameter.-.PP-A custom writer is a Lua script that defines a function that specifies-how to render each element in a Pandoc AST.-To see a documented example which you can modify according to your-needs:-.IP-.nf-\f[C]-pandoc --print-default-data-file sample.lua-\f[R]-.fi-.PP-Note that custom writers have no default template.-If you want to use \f[C]--standalone\f[R] with a custom writer, you will-need to specify a template manually using \f[C]--template\f[R] or add a-new default template with the name-\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]-subdirectory of your user data directory (see Templates).-.SH REPRODUCIBLE BUILDS-.PP-Some of the document formats pandoc targets (such as EPUB, docx, and-ODT) include build timestamps in the generated document.-That means that the files generated on successive builds will differ,-even if the source does not.-To avoid this, set the \f[C]SOURCE_DATE_EPOCH\f[R] environment variable,-and the timestamp will be taken from it instead of the current time.-\f[C]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp-(specifying the number of second since midnight UTC January 1, 1970).-.PP-Some document formats also include a unique identifier.-For EPUB, this can be set explicitly by setting the \f[C]identifier\f[R]-metadata field (see EPUB Metadata, above).-.SH A NOTE ON SECURITY-.PP-If you use pandoc to convert user-contributed content in a web-application, here are some things to keep in mind:-.IP "1." 3-Although pandoc itself will not create or modify any files other than-those you explicitly ask it create (with the exception of temporary-files used in producing PDFs), a filter or custom writer could in-principle do anything on your file system.-Please audit filters and custom writers very carefully before using-them.-.IP "2." 3-Several input formats (including HTML, Org, and RST) support-\f[C]include\f[R] directives that allow the contents of a file to be-included in the output.-An untrusted attacker could use these to view the contents of files on-the file system.-(Using the \f[C]--sandbox\f[R] option can protect against this threat.)-.IP "3." 3-Several output formats (including RTF, FB2, HTML with-\f[C]--self-contained\f[R], EPUB, Docx, and ODT) will embed encoded or-raw images into the output file.-An untrusted attacker could exploit this to view the contents of-non-image files on the file system.-(Using the \f[C]--sandbox\f[R] option can protect against this threat,-but will also prevent including images in these formats.)-.IP "4." 3-If your application uses pandoc as a Haskell library (rather than-shelling out to the executable), it is possible to use it in a mode that-fully isolates pandoc from your file system, by running the pandoc-operations in the \f[C]PandocPure\f[R] monad.-See the document Using the pandoc API for more details.-.IP "5." 3-Pandoc\[cq]s parsers can exhibit pathological performance on some corner-cases.-It is wise to put any pandoc operations under a timeout, to avoid DOS-attacks that exploit these issues.-If you are using the pandoc executable, you can add the command line-options \f[C]+RTS -M512M -RTS\f[R] (for example) to limit the heap size-to 512MB.-Note that the \f[C]commonmark\f[R] parser (including-\f[C]commonmark_x\f[R] and \f[C]gfm\f[R]) is much less vulnerable to-pathological performance than the \f[C]markdown\f[R] parser, so it is a-better choice when processing untrusted input.-.IP "6." 3-The HTML generated by pandoc is not guaranteed to be safe.-If \f[C]raw_html\f[R] is enabled for the Markdown input, users can-inject arbitrary HTML.-Even if \f[C]raw_html\f[R] is disabled, users can include dangerous-content in URLs and attributes.-To be safe, you should run all the generated HTML through an HTML-sanitizer.-.SH AUTHORS-.PP-Copyright 2006\[en]2022 John MacFarlane (jgm\[at]berkeley.edu).-Released under the GPL, version 2 or greater.-This software carries no warranty of any kind.-(See COPYRIGHT for full copyright and warranty notices.)-For a full list of contributors, see the file AUTHORS.md in the pandoc-source code.-.PP-The Pandoc source code and all documentation may be downloaded-from <https://pandoc.org>.+.\" Automatically generated by Pandoc 2.17.0.1+.\"+.\" Define V font for inline verbatim, using C font in formats+.\" that render this, and otherwise B font.+.ie "\f[CB]x\f[]"x" \{\+. ftr V B+. ftr VI BI+. ftr VB B+. ftr VBI BI+.\}+.el \{\+. ftr V CR+. ftr VI CI+. ftr VB CB+. ftr VBI CBI+.\}+.TH "Pandoc User\[cq]s Guide" "" "January 30, 2022" "pandoc 2.17.1" ""+.hy+.SH NAME+pandoc - general markup converter+.SH SYNOPSIS+.PP+\f[V]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]\&...+.SH DESCRIPTION+.PP+Pandoc is a Haskell library for converting from one markup format to+another, and a command-line tool that uses this library.+.PP+Pandoc can convert between numerous markup and word processing formats,+including, but not limited to, various flavors of Markdown, HTML, LaTeX+and Word docx.+For the full lists of input and output formats, see the \f[V]--from\f[R]+and \f[V]--to\f[R] options below.+Pandoc can also produce PDF output: see creating a PDF, below.+.PP+Pandoc\[cq]s enhanced version of Markdown includes syntax for tables,+definition lists, metadata blocks, footnotes, citations, math, and much+more.+See below under Pandoc\[cq]s Markdown.+.PP+Pandoc has a modular design: it consists of a set of readers, which+parse text in a given format and produce a native representation of the+document (an \f[I]abstract syntax tree\f[R] or AST), and a set of+writers, which convert this native representation into a target format.+Thus, adding an input or output format requires only adding a reader or+writer.+Users can also run custom pandoc filters to modify the intermediate AST.+.PP+Because pandoc\[cq]s intermediate representation of a document is less+expressive than many of the formats it converts between, one should not+expect perfect conversions between every format and every other.+Pandoc attempts to preserve the structural elements of a document, but+not formatting details such as margin size.+And some document elements, such as complex tables, may not fit into+pandoc\[cq]s simple document model.+While conversions from pandoc\[cq]s Markdown to all formats aspire to be+perfect, conversions from formats more expressive than pandoc\[cq]s+Markdown can be expected to be lossy.+.SS Using pandoc+.PP+If no \f[I]input-files\f[R] are specified, input is read from+\f[I]stdin\f[R].+Output goes to \f[I]stdout\f[R] by default.+For output to a file, use the \f[V]-o\f[R] option:+.IP+.nf+\f[C]+pandoc -o output.html input.txt+\f[R]+.fi+.PP+By default, pandoc produces a document fragment.+To produce a standalone document (e.g.\ a valid HTML file including+\f[V]<head>\f[R] and \f[V]<body>\f[R]), use the \f[V]-s\f[R] or+\f[V]--standalone\f[R] flag:+.IP+.nf+\f[C]+pandoc -s -o output.html input.txt+\f[R]+.fi+.PP+For more information on how standalone documents are produced, see+Templates below.+.PP+If multiple input files are given, pandoc will concatenate them all+(with blank lines between them) before parsing.+(Use \f[V]--file-scope\f[R] to parse files individually.)+.SS Specifying formats+.PP+The format of the input and output can be specified explicitly using+command-line options.+The input format can be specified using the \f[V]-f/--from\f[R] option,+the output format using the \f[V]-t/--to\f[R] option.+Thus, to convert \f[V]hello.txt\f[R] from Markdown to LaTeX, you could+type:+.IP+.nf+\f[C]+pandoc -f markdown -t latex hello.txt+\f[R]+.fi+.PP+To convert \f[V]hello.html\f[R] from HTML to Markdown:+.IP+.nf+\f[C]+pandoc -f html -t markdown hello.html+\f[R]+.fi+.PP+Supported input and output formats are listed below under Options (see+\f[V]-f\f[R] for input formats and \f[V]-t\f[R] for output formats).+You can also use \f[V]pandoc --list-input-formats\f[R] and+\f[V]pandoc --list-output-formats\f[R] to print lists of supported+formats.+.PP+If the input or output format is not specified explicitly, pandoc will+attempt to guess it from the extensions of the filenames.+Thus, for example,+.IP+.nf+\f[C]+pandoc -o hello.tex hello.txt+\f[R]+.fi+.PP+will convert \f[V]hello.txt\f[R] from Markdown to LaTeX.+If no output file is specified (so that output goes to+\f[I]stdout\f[R]), or if the output file\[cq]s extension is unknown, the+output format will default to HTML.+If no input file is specified (so that input comes from+\f[I]stdin\f[R]), or if the input files\[cq] extensions are unknown, the+input format will be assumed to be Markdown.+.SS Character encoding+.PP+Pandoc uses the UTF-8 character encoding for both input and output.+If your local character encoding is not UTF-8, you should pipe input and+output through \f[V]iconv\f[R]:+.IP+.nf+\f[C]+iconv -t utf-8 input.txt | pandoc | iconv -f utf-8+\f[R]+.fi+.PP+Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,+OPML, DocBook, and Texinfo), information about the character encoding is+included in the document header, which will only be included if you use+the \f[V]-s/--standalone\f[R] option.+.SS Creating a PDF+.PP+To produce a PDF, specify an output file with a \f[V].pdf\f[R]+extension:+.IP+.nf+\f[C]+pandoc test.txt -o test.pdf+\f[R]+.fi+.PP+By default, pandoc will use LaTeX to create the PDF, which requires that+a LaTeX engine be installed (see \f[V]--pdf-engine\f[R] below).+Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an+intermediate format.+To do this, specify an output file with a \f[V].pdf\f[R] extension, as+before, but add the \f[V]--pdf-engine\f[R] option or+\f[V]-t context\f[R], \f[V]-t html\f[R], or \f[V]-t ms\f[R] to the+command line.+The tool used to generate the PDF from the intermediate format may be+specified using \f[V]--pdf-engine\f[R].+.PP+You can control the PDF style using variables, depending on the+intermediate format used: see variables for LaTeX, variables for+ConTeXt, variables for \f[V]wkhtmltopdf\f[R], variables for ms.+When HTML is used as an intermediate format, the output can be styled+using \f[V]--css\f[R].+.PP+To debug the PDF creation, it can be useful to look at the intermediate+representation: instead of \f[V]-o test.pdf\f[R], use for example+\f[V]-s -o test.tex\f[R] to output the generated LaTeX.+You can then test it with \f[V]pdflatex test.tex\f[R].+.PP+When using LaTeX, the following packages need to be available (they are+included with all recent versions of TeX Live): \f[V]amsfonts\f[R],+\f[V]amsmath\f[R], \f[V]lm\f[R], \f[V]unicode-math\f[R],+\f[V]iftex\f[R], \f[V]listings\f[R] (if the \f[V]--listings\f[R] option+is used), \f[V]fancyvrb\f[R], \f[V]longtable\f[R], \f[V]booktabs\f[R],+\f[V]graphicx\f[R] (if the document contains images),+\f[V]hyperref\f[R], \f[V]xcolor\f[R], \f[V]ulem\f[R], \f[V]geometry\f[R]+(with the \f[V]geometry\f[R] variable set), \f[V]setspace\f[R] (with+\f[V]linestretch\f[R]), and \f[V]babel\f[R] (with \f[V]lang\f[R]).+If \f[V]CJKmainfont\f[R] is set, \f[V]xeCJK\f[R] is needed.+The use of \f[V]xelatex\f[R] or \f[V]lualatex\f[R] as the PDF engine+requires \f[V]fontspec\f[R].+\f[V]lualatex\f[R] uses \f[V]selnolig\f[R].+\f[V]xelatex\f[R] uses \f[V]bidi\f[R] (with the \f[V]dir\f[R] variable+set).+If the \f[V]mathspec\f[R] variable is set, \f[V]xelatex\f[R] will use+\f[V]mathspec\f[R] instead of \f[V]unicode-math\f[R].+The \f[V]upquote\f[R] and \f[V]microtype\f[R] packages are used if+available, and \f[V]csquotes\f[R] will be used for typography if the+\f[V]csquotes\f[R] variable or metadata field is set to a true value.+The \f[V]natbib\f[R], \f[V]biblatex\f[R], \f[V]bibtex\f[R], and+\f[V]biber\f[R] packages can optionally be used for citation rendering.+The following packages will be used to improve output quality if+present, but pandoc does not require them to be present:+\f[V]upquote\f[R] (for straight quotes in verbatim environments),+\f[V]microtype\f[R] (for better spacing adjustments), \f[V]parskip\f[R]+(for better inter-paragraph spaces), \f[V]xurl\f[R] (for better line+breaks in URLs), \f[V]bookmark\f[R] (for better PDF bookmarks), and+\f[V]footnotehyper\f[R] or \f[V]footnote\f[R] (to allow footnotes in+tables).+.SS Reading from the Web+.PP+Instead of an input file, an absolute URI may be given.+In this case pandoc will fetch the content using HTTP:+.IP+.nf+\f[C]+pandoc -f html -t markdown https://www.fsf.org+\f[R]+.fi+.PP+It is possible to supply a custom User-Agent string or other header when+requesting a document from a URL:+.IP+.nf+\f[C]+pandoc -f html -t markdown --request-header User-Agent:\[dq]Mozilla/5.0\[dq] \[rs]+  https://www.fsf.org+\f[R]+.fi+.SH OPTIONS+.SS General options+.TP+\f[V]-f\f[R] \f[I]FORMAT\f[R], \f[V]-r\f[R] \f[I]FORMAT\f[R], \f[V]--from=\f[R]\f[I]FORMAT\f[R], \f[V]--read=\f[R]\f[I]FORMAT\f[R]+Specify input format.+\f[I]FORMAT\f[R] can be:+.RS+.IP \[bu] 2+\f[V]bibtex\f[R] (BibTeX bibliography)+.IP \[bu] 2+\f[V]biblatex\f[R] (BibLaTeX bibliography)+.IP \[bu] 2+\f[V]commonmark\f[R] (CommonMark Markdown)+.IP \[bu] 2+\f[V]commonmark_x\f[R] (CommonMark Markdown with extensions)+.IP \[bu] 2+\f[V]creole\f[R] (Creole 1.0)+.IP \[bu] 2+\f[V]csljson\f[R] (CSL JSON bibliography)+.IP \[bu] 2+\f[V]csv\f[R] (CSV table)+.IP \[bu] 2+\f[V]docbook\f[R] (DocBook)+.IP \[bu] 2+\f[V]docx\f[R] (Word docx)+.IP \[bu] 2+\f[V]dokuwiki\f[R] (DokuWiki markup)+.IP \[bu] 2+\f[V]epub\f[R] (EPUB)+.IP \[bu] 2+\f[V]fb2\f[R] (FictionBook2 e-book)+.IP \[bu] 2+\f[V]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less+accurate \f[V]markdown_github\f[R]; use \f[V]markdown_github\f[R] only+if you need extensions not supported in \f[V]gfm\f[R].+.IP \[bu] 2+\f[V]haddock\f[R] (Haddock markup)+.IP \[bu] 2+\f[V]html\f[R] (HTML)+.IP \[bu] 2+\f[V]ipynb\f[R] (Jupyter notebook)+.IP \[bu] 2+\f[V]jats\f[R] (JATS XML)+.IP \[bu] 2+\f[V]jira\f[R] (Jira/Confluence wiki markup)+.IP \[bu] 2+\f[V]json\f[R] (JSON version of native AST)+.IP \[bu] 2+\f[V]latex\f[R] (LaTeX)+.IP \[bu] 2+\f[V]markdown\f[R] (Pandoc\[cq]s Markdown)+.IP \[bu] 2+\f[V]markdown_mmd\f[R] (MultiMarkdown)+.IP \[bu] 2+\f[V]markdown_phpextra\f[R] (PHP Markdown Extra)+.IP \[bu] 2+\f[V]markdown_strict\f[R] (original unextended Markdown)+.IP \[bu] 2+\f[V]mediawiki\f[R] (MediaWiki markup)+.IP \[bu] 2+\f[V]man\f[R] (roff man)+.IP \[bu] 2+\f[V]muse\f[R] (Muse)+.IP \[bu] 2+\f[V]native\f[R] (native Haskell)+.IP \[bu] 2+\f[V]odt\f[R] (ODT)+.IP \[bu] 2+\f[V]opml\f[R] (OPML)+.IP \[bu] 2+\f[V]org\f[R] (Emacs Org mode)+.IP \[bu] 2+\f[V]rtf\f[R] (Rich Text Format)+.IP \[bu] 2+\f[V]rst\f[R] (reStructuredText)+.IP \[bu] 2+\f[V]t2t\f[R] (txt2tags)+.IP \[bu] 2+\f[V]textile\f[R] (Textile)+.IP \[bu] 2+\f[V]tikiwiki\f[R] (TikiWiki markup)+.IP \[bu] 2+\f[V]twiki\f[R] (TWiki markup)+.IP \[bu] 2+\f[V]vimwiki\f[R] (Vimwiki)+.IP \[bu] 2+the path of a custom Lua reader, see Custom readers and writers below+.PP+Extensions can be individually enabled or disabled by appending+\f[V]+EXTENSION\f[R] or \f[V]-EXTENSION\f[R] to the format name.+See Extensions below, for a list of extensions and their names.+See \f[V]--list-input-formats\f[R] and \f[V]--list-extensions\f[R],+below.+.RE+.TP+\f[V]-t\f[R] \f[I]FORMAT\f[R], \f[V]-w\f[R] \f[I]FORMAT\f[R], \f[V]--to=\f[R]\f[I]FORMAT\f[R], \f[V]--write=\f[R]\f[I]FORMAT\f[R]+Specify output format.+\f[I]FORMAT\f[R] can be:+.RS+.IP \[bu] 2+\f[V]asciidoc\f[R] (AsciiDoc) or \f[V]asciidoctor\f[R] (AsciiDoctor)+.IP \[bu] 2+\f[V]beamer\f[R] (LaTeX beamer slide show)+.IP \[bu] 2+\f[V]bibtex\f[R] (BibTeX bibliography)+.IP \[bu] 2+\f[V]biblatex\f[R] (BibLaTeX bibliography)+.IP \[bu] 2+\f[V]commonmark\f[R] (CommonMark Markdown)+.IP \[bu] 2+\f[V]commonmark_x\f[R] (CommonMark Markdown with extensions)+.IP \[bu] 2+\f[V]context\f[R] (ConTeXt)+.IP \[bu] 2+\f[V]csljson\f[R] (CSL JSON bibliography)+.IP \[bu] 2+\f[V]docbook\f[R] or \f[V]docbook4\f[R] (DocBook 4)+.IP \[bu] 2+\f[V]docbook5\f[R] (DocBook 5)+.IP \[bu] 2+\f[V]docx\f[R] (Word docx)+.IP \[bu] 2+\f[V]dokuwiki\f[R] (DokuWiki markup)+.IP \[bu] 2+\f[V]epub\f[R] or \f[V]epub3\f[R] (EPUB v3 book)+.IP \[bu] 2+\f[V]epub2\f[R] (EPUB v2)+.IP \[bu] 2+\f[V]fb2\f[R] (FictionBook2 e-book)+.IP \[bu] 2+\f[V]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less+accurate \f[V]markdown_github\f[R]; use \f[V]markdown_github\f[R] only+if you need extensions not supported in \f[V]gfm\f[R].+.IP \[bu] 2+\f[V]haddock\f[R] (Haddock markup)+.IP \[bu] 2+\f[V]html\f[R] or \f[V]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot+markup)+.IP \[bu] 2+\f[V]html4\f[R] (XHTML 1.0 Transitional)+.IP \[bu] 2+\f[V]icml\f[R] (InDesign ICML)+.IP \[bu] 2+\f[V]ipynb\f[R] (Jupyter notebook)+.IP \[bu] 2+\f[V]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set)+.IP \[bu] 2+\f[V]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set)+.IP \[bu] 2+\f[V]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set)+.IP \[bu] 2+\f[V]jats\f[R] (alias for \f[V]jats_archiving\f[R])+.IP \[bu] 2+\f[V]jira\f[R] (Jira/Confluence wiki markup)+.IP \[bu] 2+\f[V]json\f[R] (JSON version of native AST)+.IP \[bu] 2+\f[V]latex\f[R] (LaTeX)+.IP \[bu] 2+\f[V]man\f[R] (roff man)+.IP \[bu] 2+\f[V]markdown\f[R] (Pandoc\[cq]s Markdown)+.IP \[bu] 2+\f[V]markdown_mmd\f[R] (MultiMarkdown)+.IP \[bu] 2+\f[V]markdown_phpextra\f[R] (PHP Markdown Extra)+.IP \[bu] 2+\f[V]markdown_strict\f[R] (original unextended Markdown)+.IP \[bu] 2+\f[V]markua\f[R] (Markua)+.IP \[bu] 2+\f[V]mediawiki\f[R] (MediaWiki markup)+.IP \[bu] 2+\f[V]ms\f[R] (roff ms)+.IP \[bu] 2+\f[V]muse\f[R] (Muse),+.IP \[bu] 2+\f[V]native\f[R] (native Haskell),+.IP \[bu] 2+\f[V]odt\f[R] (OpenOffice text document)+.IP \[bu] 2+\f[V]opml\f[R] (OPML)+.IP \[bu] 2+\f[V]opendocument\f[R] (OpenDocument)+.IP \[bu] 2+\f[V]org\f[R] (Emacs Org mode)+.IP \[bu] 2+\f[V]pdf\f[R] (PDF)+.IP \[bu] 2+\f[V]plain\f[R] (plain text),+.IP \[bu] 2+\f[V]pptx\f[R] (PowerPoint slide show)+.IP \[bu] 2+\f[V]rst\f[R] (reStructuredText)+.IP \[bu] 2+\f[V]rtf\f[R] (Rich Text Format)+.IP \[bu] 2+\f[V]texinfo\f[R] (GNU Texinfo)+.IP \[bu] 2+\f[V]textile\f[R] (Textile)+.IP \[bu] 2+\f[V]slideous\f[R] (Slideous HTML and JavaScript slide show)+.IP \[bu] 2+\f[V]slidy\f[R] (Slidy HTML and JavaScript slide show)+.IP \[bu] 2+\f[V]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show),+.IP \[bu] 2+\f[V]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show)+.IP \[bu] 2+\f[V]s5\f[R] (S5 HTML and JavaScript slide show)+.IP \[bu] 2+\f[V]tei\f[R] (TEI Simple)+.IP \[bu] 2+\f[V]xwiki\f[R] (XWiki markup)+.IP \[bu] 2+\f[V]zimwiki\f[R] (ZimWiki markup)+.IP \[bu] 2+the path of a custom Lua writer, see Custom readers and writers below+.PP+Note that \f[V]odt\f[R], \f[V]docx\f[R], \f[V]epub\f[R], and+\f[V]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless+forced with \f[V]-o -\f[R].+.PP+Extensions can be individually enabled or disabled by appending+\f[V]+EXTENSION\f[R] or \f[V]-EXTENSION\f[R] to the format name.+See Extensions below, for a list of extensions and their names.+See \f[V]--list-output-formats\f[R] and \f[V]--list-extensions\f[R],+below.+.RE+.TP+\f[V]-o\f[R] \f[I]FILE\f[R], \f[V]--output=\f[R]\f[I]FILE\f[R]+Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R].+If \f[I]FILE\f[R] is \f[V]-\f[R], output will go to \f[I]stdout\f[R],+even if a non-textual format (\f[V]docx\f[R], \f[V]odt\f[R],+\f[V]epub2\f[R], \f[V]epub3\f[R]) is specified.+.TP+\f[V]--data-dir=\f[R]\f[I]DIRECTORY\f[R]+Specify the user data directory to search for pandoc data files.+If this option is not specified, the default user data directory will be+used.+On *nix and macOS systems this will be the \f[V]pandoc\f[R] subdirectory+of the XDG data directory (by default, \f[V]$HOME/.local/share\f[R],+overridable by setting the \f[V]XDG_DATA_HOME\f[R] environment+variable).+If that directory does not exist and \f[V]$HOME/.pandoc\f[R] exists, it+will be used (for backwards compatibility).+On Windows the default user data directory is+\f[V]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].+You can find the default user data directory on your system by looking+at the output of \f[V]pandoc --version\f[R].+Data files placed in this directory (for example,+\f[V]reference.odt\f[R], \f[V]reference.docx\f[R], \f[V]epub.css\f[R],+\f[V]templates\f[R]) will override pandoc\[cq]s normal defaults.+.TP+\f[V]-d\f[R] \f[I]FILE\f[R], \f[V]--defaults=\f[R]\f[I]FILE\f[R]+Specify a set of default option settings.+\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line+option settings.+All options for document conversion, including input and output files,+can be set using a defaults file.+The file will be searched for first in the working directory, and then+in the \f[V]defaults\f[R] subdirectory of the user data directory (see+\f[V]--data-dir\f[R]).+The \f[V].yaml\f[R] extension may be omitted.+See the section Defaults files for more information on the file format.+Settings from the defaults file may be overridden or extended by+subsequent options on the command line.+.TP+\f[V]--bash-completion\f[R]+Generate a bash completion script.+To enable bash completion with pandoc, add this to your+\f[V].bashrc\f[R]:+.RS+.IP+.nf+\f[C]+eval \[dq]$(pandoc --bash-completion)\[dq]+\f[R]+.fi+.RE+.TP+\f[V]--verbose\f[R]+Give verbose debugging output.+.TP+\f[V]--quiet\f[R]+Suppress warning messages.+.TP+\f[V]--fail-if-warnings\f[R]+Exit with error status if there are any warnings.+.TP+\f[V]--log=\f[R]\f[I]FILE\f[R]+Write log messages in machine-readable JSON format to \f[I]FILE\f[R].+All messages above DEBUG level will be written, regardless of verbosity+settings (\f[V]--verbose\f[R], \f[V]--quiet\f[R]).+.TP+\f[V]--list-input-formats\f[R]+List supported input formats, one per line.+.TP+\f[V]--list-output-formats\f[R]+List supported output formats, one per line.+.TP+\f[V]--list-extensions\f[R][\f[V]=\f[R]\f[I]FORMAT\f[R]]+List supported extensions for \f[I]FORMAT\f[R], one per line, preceded+by a \f[V]+\f[R] or \f[V]-\f[R] indicating whether it is enabled by+default in \f[I]FORMAT\f[R].+If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown+are given.+.TP+\f[V]--list-highlight-languages\f[R]+List supported languages for syntax highlighting, one per line.+.TP+\f[V]--list-highlight-styles\f[R]+List supported styles for syntax highlighting, one per line.+See \f[V]--highlight-style\f[R].+.TP+\f[V]-v\f[R], \f[V]--version\f[R]+Print version.+.TP+\f[V]-h\f[R], \f[V]--help\f[R]+Show usage message.+.SS Reader options+.TP+\f[V]--shift-heading-level-by=\f[R]\f[I]NUMBER\f[R]+Shift heading levels by a positive or negative integer.+For example, with \f[V]--shift-heading-level-by=-1\f[R], level 2+headings become level 1 headings, and level 3 headings become level 2+headings.+Headings cannot have a level less than 1, so a heading that would be+shifted below level 1 becomes a regular paragraph.+Exception: with a shift of -N, a level-N heading at the beginning of the+document replaces the metadata title.+\f[V]--shift-heading-level-by=-1\f[R] is a good choice when converting+HTML or Markdown documents that use an initial level-1 heading for the+document title and level-2+ headings for sections.+\f[V]--shift-heading-level-by=1\f[R] may be a good choice for converting+Markdown documents that use level-1 headings for sections to HTML, since+pandoc uses a level-1 heading to render the document title.+.TP+\f[V]--base-header-level=\f[R]\f[I]NUMBER\f[R]+\f[I]Deprecated.+Use \f[VI]--shift-heading-level-by\f[I]=X instead, where X = NUMBER -+1.\f[R] Specify the base level for headings (defaults to 1).+.TP+\f[V]--strip-empty-paragraphs\f[R]+\f[I]Deprecated.+Use the \f[VI]+empty_paragraphs\f[I] extension instead.\f[R] Ignore+paragraphs with no content.+This option is useful for converting word processing documents where+users have used empty paragraphs to create inter-paragraph space.+.TP+\f[V]--indented-code-classes=\f[R]\f[I]CLASSES\f[R]+Specify classes to use for indented code blocks\[en]for example,+\f[V]perl,numberLines\f[R] or \f[V]haskell\f[R].+Multiple classes may be separated by spaces or commas.+.TP+\f[V]--default-image-extension=\f[R]\f[I]EXTENSION\f[R]+Specify a default extension to use when image paths/URLs have no+extension.+This allows you to use the same source for formats that require+different kinds of images.+Currently this option only affects the Markdown and LaTeX readers.+.TP+\f[V]--file-scope\f[R]+Parse each file individually before combining for multifile documents.+This will allow footnotes in different files with the same identifiers+to work as expected.+If this option is set, footnotes and links will not work across files.+Reading binary files (docx, odt, epub) implies \f[V]--file-scope\f[R].+.TP+\f[V]-F\f[R] \f[I]PROGRAM\f[R], \f[V]--filter=\f[R]\f[I]PROGRAM\f[R]+Specify an executable to be used as a filter transforming the pandoc AST+after the input is parsed and before the output is written.+The executable should read JSON from stdin and write JSON to stdout.+The JSON must be formatted like pandoc\[cq]s own JSON input and output.+The name of the output format will be passed to the filter as the first+argument.+Hence,+.RS+.IP+.nf+\f[C]+pandoc --filter ./caps.py -t latex+\f[R]+.fi+.PP+is equivalent to+.IP+.nf+\f[C]+pandoc -t json | ./caps.py latex | pandoc -f json -t latex+\f[R]+.fi+.PP+The latter form may be useful for debugging filters.+.PP+Filters may be written in any language.+\f[V]Text.Pandoc.JSON\f[R] exports \f[V]toJSONFilter\f[R] to facilitate+writing filters in Haskell.+Those who would prefer to write filters in python can use the module+\f[V]pandocfilters\f[R], installable from PyPI.+There are also pandoc filter libraries in PHP, perl, and+JavaScript/node.js.+.PP+In order of preference, pandoc will look for filters in+.IP "1." 3+a specified full or relative path (executable or non-executable)+.IP "2." 3+\f[V]$DATADIR/filters\f[R] (executable or non-executable) where+\f[V]$DATADIR\f[R] is the user data directory (see \f[V]--data-dir\f[R],+above).+.IP "3." 3+\f[V]$PATH\f[R] (executable only)+.PP+Filters, Lua-filters, and citeproc processing are applied in the order+specified on the command line.+.RE+.TP+\f[V]-L\f[R] \f[I]SCRIPT\f[R], \f[V]--lua-filter=\f[R]\f[I]SCRIPT\f[R]+Transform the document in a similar fashion as JSON filters (see+\f[V]--filter\f[R]), but use pandoc\[cq]s built-in Lua filtering system.+The given Lua script is expected to return a list of Lua filters which+will be applied in order.+Each Lua filter must contain element-transforming functions indexed by+the name of the AST element on which the filter function should be+applied.+.RS+.PP+The \f[V]pandoc\f[R] Lua module provides helper functions for element+creation.+It is always loaded into the script\[cq]s Lua environment.+.PP+See the Lua filters documentation for further details.+.PP+In order of preference, pandoc will look for Lua filters in+.IP "1." 3+a specified full or relative path+.IP "2." 3+\f[V]$DATADIR/filters\f[R] where \f[V]$DATADIR\f[R] is the user data+directory (see \f[V]--data-dir\f[R], above).+.PP+Filters, Lua filters, and citeproc processing are applied in the order+specified on the command line.+.RE+.TP+\f[V]-M\f[R] \f[I]KEY\f[R][\f[V]=\f[R]\f[I]VAL\f[R]], \f[V]--metadata=\f[R]\f[I]KEY\f[R][\f[V]:\f[R]\f[I]VAL\f[R]]+Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R].+A value specified on the command line overrides a value specified in the+document using YAML metadata blocks.+Values will be parsed as YAML boolean or string values.+If no value is specified, the value will be treated as Boolean true.+Like \f[V]--variable\f[R], \f[V]--metadata\f[R] causes template+variables to be set.+But unlike \f[V]--variable\f[R], \f[V]--metadata\f[R] affects the+metadata of the underlying document (which is accessible from filters+and may be printed in some output formats) and metadata values will be+escaped when inserted into the template.+.TP+\f[V]--metadata-file=\f[R]\f[I]FILE\f[R]+Read metadata from the supplied YAML (or JSON) file.+This option can be used with every input format, but string scalars in+the YAML file will always be parsed as Markdown.+Generally, the input will be handled the same as in YAML metadata+blocks.+This option can be used repeatedly to include multiple metadata files;+values in files specified later on the command line will be preferred+over those specified in earlier files.+Metadata values specified inside the document, or by using \f[V]-M\f[R],+overwrite values specified with this option.+The file will be searched for first in the working directory, and then+in the \f[V]metadata\f[R] subdirectory of the user data directory (see+\f[V]--data-dir\f[R]).+.TP+\f[V]-p\f[R], \f[V]--preserve-tabs\f[R]+Preserve tabs instead of converting them to spaces.+(By default, pandoc converts tabs to spaces before parsing its input.)+Note that this will only affect tabs in literal code spans and code+blocks.+Tabs in regular text are always treated as spaces.+.TP+\f[V]--tab-stop=\f[R]\f[I]NUMBER\f[R]+Specify the number of spaces per tab (default is 4).+.TP+\f[V]--track-changes=accept\f[R]|\f[V]reject\f[R]|\f[V]all\f[R]+Specifies what to do with insertions, deletions, and comments produced+by the MS Word \[lq]Track Changes\[rq] feature.+\f[V]accept\f[R] (the default) processes all the insertions and+deletions.+\f[V]reject\f[R] ignores them.+Both \f[V]accept\f[R] and \f[V]reject\f[R] ignore comments.+\f[V]all\f[R] includes all insertions, deletions, and comments, wrapped+in spans with \f[V]insertion\f[R], \f[V]deletion\f[R],+\f[V]comment-start\f[R], and \f[V]comment-end\f[R] classes,+respectively.+The author and time of change is included.+\f[V]all\f[R] is useful for scripting: only accepting changes from a+certain reviewer, say, or before a certain date.+If a paragraph is inserted or deleted, \f[V]track-changes=all\f[R]+produces a span with the class+\f[V]paragraph-insertion\f[R]/\f[V]paragraph-deletion\f[R] before the+affected paragraph break.+This option only affects the docx reader.+.TP+\f[V]--extract-media=\f[R]\f[I]DIR\f[R]+Extract images and other media contained in or linked from the source+document to the path \f[I]DIR\f[R], creating it if necessary, and adjust+the images references in the document so they point to the extracted+files.+Media are downloaded, read from the file system, or extracted from a+binary container (e.g.\ docx), as needed.+The original file paths are used if they are relative paths not+containing \f[V]..\f[R].+Otherwise filenames are constructed from the SHA1 hash of the contents.+.TP+\f[V]--abbreviations=\f[R]\f[I]FILE\f[R]+Specifies a custom abbreviations file, with abbreviations one to a line.+If this option is not specified, pandoc will read the data file+\f[V]abbreviations\f[R] from the user data directory or fall back on a+system default.+To see the system default, use+\f[V]pandoc --print-default-data-file=abbreviations\f[R].+The only use pandoc makes of this list is in the Markdown reader.+Strings found in this list will be followed by a nonbreaking space, and+the period will not produce sentence-ending space in formats like LaTeX.+The strings may not contain spaces.+.TP+\f[V]--trace\f[R]+Print diagnostic output tracing parser progress to stderr.+This option is intended for use by developers in diagnosing performance+issues.+.SS General writer options+.TP+\f[V]-s\f[R], \f[V]--standalone\f[R]+Produce output with an appropriate header and footer (e.g.\ a standalone+HTML, LaTeX, TEI, or RTF file, not a fragment).+This option is set automatically for \f[V]pdf\f[R], \f[V]epub\f[R],+\f[V]epub3\f[R], \f[V]fb2\f[R], \f[V]docx\f[R], and \f[V]odt\f[R]+output.+For \f[V]native\f[R] output, this option causes metadata to be included;+otherwise, metadata is suppressed.+.TP+\f[V]--template=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]+Use the specified file as a custom template for the generated document.+Implies \f[V]--standalone\f[R].+See Templates, below, for a description of template syntax.+If no extension is specified, an extension corresponding to the writer+will be added, so that \f[V]--template=special\f[R] looks for+\f[V]special.html\f[R] for HTML output.+If the template is not found, pandoc will search for it in the+\f[V]templates\f[R] subdirectory of the user data directory (see+\f[V]--data-dir\f[R]).+If this option is not used, a default template appropriate for the+output format will be used (see \f[V]-D/--print-default-template\f[R]).+.TP+\f[V]-V\f[R] \f[I]KEY\f[R][\f[V]=\f[R]\f[I]VAL\f[R]], \f[V]--variable=\f[R]\f[I]KEY\f[R][\f[V]:\f[R]\f[I]VAL\f[R]]+Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when+rendering the document in standalone mode.+If no \f[I]VAL\f[R] is specified, the key will be given the value+\f[V]true\f[R].+.TP+\f[V]--sandbox\f[R]+Run pandoc in a sandbox, limiting IO operations in readers and writers+to reading the files specified on the command line.+Note that this option does not limit IO operations by filters or in the+production of PDF documents.+But it does offer security against, for example, disclosure of files+through the use of \f[V]include\f[R] directives.+Anyone using pandoc on untrusted user input should use this option.+.TP+\f[V]-D\f[R] \f[I]FORMAT\f[R], \f[V]--print-default-template=\f[R]\f[I]FORMAT\f[R]+Print the system default template for an output \f[I]FORMAT\f[R].+(See \f[V]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.)+Templates in the user data directory are ignored.+This option may be used with \f[V]-o\f[R]/\f[V]--output\f[R] to redirect+output to a file, but \f[V]-o\f[R]/\f[V]--output\f[R] must come before+\f[V]--print-default-template\f[R] on the command line.+.RS+.PP+Note that some of the default templates use partials, for example+\f[V]styles.html\f[R].+To print the partials, use \f[V]--print-default-data-file\f[R]: for+example, \f[V]--print-default-data-file=templates/styles.html\f[R].+.RE+.TP+\f[V]--print-default-data-file=\f[R]\f[I]FILE\f[R]+Print a system default data file.+Files in the user data directory are ignored.+This option may be used with \f[V]-o\f[R]/\f[V]--output\f[R] to redirect+output to a file, but \f[V]-o\f[R]/\f[V]--output\f[R] must come before+\f[V]--print-default-data-file\f[R] on the command line.+.TP+\f[V]--eol=crlf\f[R]|\f[V]lf\f[R]|\f[V]native\f[R]+Manually specify line endings: \f[V]crlf\f[R] (Windows), \f[V]lf\f[R]+(macOS/Linux/UNIX), or \f[V]native\f[R] (line endings appropriate to the+OS on which pandoc is being run).+The default is \f[V]native\f[R].+.TP+\f[V]--dpi\f[R]=\f[I]NUMBER\f[R]+Specify the default dpi (dots per inch) value for conversion from pixels+to inch/centimeters and vice versa.+(Technically, the correct term would be ppi: pixels per inch.)+The default is 96dpi.+When images contain information about dpi internally, the encoded value+is used instead of the default specified by this option.+.TP+\f[V]--wrap=auto\f[R]|\f[V]none\f[R]|\f[V]preserve\f[R]+Determine how text is wrapped in the output (the source code, not the+rendered version).+With \f[V]auto\f[R] (the default), pandoc will attempt to wrap lines to+the column width specified by \f[V]--columns\f[R] (default 72).+With \f[V]none\f[R], pandoc will not wrap lines at all.+With \f[V]preserve\f[R], pandoc will attempt to preserve the wrapping+from the source document (that is, where there are nonsemantic newlines+in the source, there will be nonsemantic newlines in the output as+well).+In \f[V]ipynb\f[R] output, this option affects wrapping of the contents+of markdown cells.+.TP+\f[V]--columns=\f[R]\f[I]NUMBER\f[R]+Specify length of lines in characters.+This affects text wrapping in the generated source code (see+\f[V]--wrap\f[R]).+It also affects calculation of column widths for plain text tables (see+Tables below).+.TP+\f[V]--toc\f[R], \f[V]--table-of-contents\f[R]+Include an automatically generated table of contents (or, in the case of+\f[V]latex\f[R], \f[V]context\f[R], \f[V]docx\f[R], \f[V]odt\f[R],+\f[V]opendocument\f[R], \f[V]rst\f[R], or \f[V]ms\f[R], an instruction+to create one) in the output document.+This option has no effect unless \f[V]-s/--standalone\f[R] is used, and+it has no effect on \f[V]man\f[R], \f[V]docbook4\f[R],+\f[V]docbook5\f[R], or \f[V]jats\f[R] output.+.RS+.PP+Note that if you are producing a PDF via \f[V]ms\f[R], the table of+contents will appear at the beginning of the document, before the title.+If you would prefer it to be at the end of the document, use the option+\f[V]--pdf-engine-opt=--no-toc-relocation\f[R].+.RE+.TP+\f[V]--toc-depth=\f[R]\f[I]NUMBER\f[R]+Specify the number of section levels to include in the table of+contents.+The default is 3 (which means that level-1, 2, and 3 headings will be+listed in the contents).+.TP+\f[V]--strip-comments\f[R]+Strip out HTML comments in the Markdown or Textile source, rather than+passing them on to Markdown, Textile or HTML output as raw HTML.+This does not apply to HTML comments inside raw HTML blocks when the+\f[V]markdown_in_html_blocks\f[R] extension is not set.+.TP+\f[V]--no-highlight\f[R]+Disables syntax highlighting for code blocks and inlines, even when a+language attribute is given.+.TP+\f[V]--highlight-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]+Specifies the coloring style to be used in highlighted source code.+Options are \f[V]pygments\f[R] (the default), \f[V]kate\f[R],+\f[V]monochrome\f[R], \f[V]breezeDark\f[R], \f[V]espresso\f[R],+\f[V]zenburn\f[R], \f[V]haddock\f[R], and \f[V]tango\f[R].+For more information on syntax highlighting in pandoc, see Syntax+highlighting, below.+See also \f[V]--list-highlight-styles\f[R].+.RS+.PP+Instead of a \f[I]STYLE\f[R] name, a JSON file with extension+\f[V].theme\f[R] may be supplied.+This will be parsed as a KDE syntax highlighting theme and (if valid)+used as the highlighting style.+.PP+To generate the JSON version of an existing style, use+\f[V]--print-highlight-style\f[R].+.RE+.TP+\f[V]--print-highlight-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R]+Prints a JSON version of a highlighting style, which can be modified,+saved with a \f[V].theme\f[R] extension, and used with+\f[V]--highlight-style\f[R].+This option may be used with \f[V]-o\f[R]/\f[V]--output\f[R] to redirect+output to a file, but \f[V]-o\f[R]/\f[V]--output\f[R] must come before+\f[V]--print-highlight-style\f[R] on the command line.+.TP+\f[V]--syntax-definition=\f[R]\f[I]FILE\f[R]+Instructs pandoc to load a KDE XML syntax definition file, which will be+used for syntax highlighting of appropriately marked code blocks.+This can be used to add support for new languages or to use altered+syntax definitions for existing languages.+This option may be repeated to add multiple syntax definitions.+.TP+\f[V]-H\f[R] \f[I]FILE\f[R], \f[V]--include-in-header=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]+Include contents of \f[I]FILE\f[R], verbatim, at the end of the header.+This can be used, for example, to include special CSS or JavaScript in+HTML documents.+This option can be used repeatedly to include multiple files in the+header.+They will be included in the order specified.+Implies \f[V]--standalone\f[R].+.TP+\f[V]-B\f[R] \f[I]FILE\f[R], \f[V]--include-before-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]+Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the+document body (e.g.\ after the \f[V]<body>\f[R] tag in HTML, or the+\f[V]\[rs]begin{document}\f[R] command in LaTeX).+This can be used to include navigation bars or banners in HTML+documents.+This option can be used repeatedly to include multiple files.+They will be included in the order specified.+Implies \f[V]--standalone\f[R].+.TP+\f[V]-A\f[R] \f[I]FILE\f[R], \f[V]--include-after-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]+Include contents of \f[I]FILE\f[R], verbatim, at the end of the document+body (before the \f[V]</body>\f[R] tag in HTML, or the+\f[V]\[rs]end{document}\f[R] command in LaTeX).+This option can be used repeatedly to include multiple files.+They will be included in the order specified.+Implies \f[V]--standalone\f[R].+.TP+\f[V]--resource-path=\f[R]\f[I]SEARCHPATH\f[R]+List of paths to search for images and other resources.+The paths should be separated by \f[V]:\f[R] on Linux, UNIX, and macOS+systems, and by \f[V];\f[R] on Windows.+If \f[V]--resource-path\f[R] is not specified, the default resource path+is the working directory.+Note that, if \f[V]--resource-path\f[R] is specified, the working+directory must be explicitly listed or it will not be searched.+For example: \f[V]--resource-path=.:test\f[R] will search the working+directory and the \f[V]test\f[R] subdirectory, in that order.+This option can be used repeatedly.+Search path components that come later on the command line will be+searched before those that come earlier, so+\f[V]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent+to \f[V]--resource-path baz:bim:foo:bar\f[R].+.TP+\f[V]--request-header=\f[R]\f[I]NAME\f[R]\f[V]:\f[R]\f[I]VAL\f[R]+Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when+making HTTP requests (for example, when a URL is given on the command+line, or when resources used in a document must be downloaded).+If you\[cq]re behind a proxy, you also need to set the environment+variable \f[V]http_proxy\f[R] to \f[V]http://...\f[R].+.TP+\f[V]--no-check-certificate\f[R]+Disable the certificate verification to allow access to unsecure HTTP+resources (for example when the certificate is no longer valid or self+signed).+.SS Options affecting specific writers+.TP+\f[V]--self-contained\f[R]+Produce a standalone HTML file with no external dependencies, using+\f[V]data:\f[R] URIs to incorporate the contents of linked scripts,+stylesheets, images, and videos.+Implies \f[V]--standalone\f[R].+The resulting file should be \[lq]self-contained,\[rq] in the sense that+it needs no external files and no net access to be displayed properly by+a browser.+This option works only with HTML output formats, including+\f[V]html4\f[R], \f[V]html5\f[R], \f[V]html+lhs\f[R],+\f[V]html5+lhs\f[R], \f[V]s5\f[R], \f[V]slidy\f[R], \f[V]slideous\f[R],+\f[V]dzslides\f[R], and \f[V]revealjs\f[R].+Scripts, images, and stylesheets at absolute URLs will be downloaded;+those at relative URLs will be sought relative to the working directory+(if the first source file is local) or relative to the base URL (if the+first source file is remote).+Elements with the attribute \f[V]data-external=\[dq]1\[dq]\f[R] will be+left alone; the documents they link to will not be incorporated in the+document.+Limitation: resources that are loaded dynamically through JavaScript+cannot be incorporated; as a result, \f[V]--self-contained\f[R] does not+work with \f[V]--mathjax\f[R], and some advanced features (e.g.\ zoom or+speaker notes) may not work in an offline \[lq]self-contained\[rq]+\f[V]reveal.js\f[R] slide show.+.TP+\f[V]--html-q-tags\f[R]+Use \f[V]<q>\f[R] tags for quotes in HTML.+(This option only has an effect if the \f[V]smart\f[R] extension is+enabled for the input format used.)+.TP+\f[V]--ascii\f[R]+Use only ASCII characters in output.+Currently supported for XML and HTML formats (which use entities instead+of UTF-8 when this option is selected), CommonMark, gfm, and Markdown+(which use entities), roff ms (which use hexadecimal escapes), and to a+limited degree LaTeX (which uses standard commands for accented+characters when possible).+roff man output uses ASCII by default.+.TP+\f[V]--reference-links\f[R]+Use reference-style links, rather than inline links, in writing Markdown+or reStructuredText.+By default inline links are used.+The placement of link references is affected by the+\f[V]--reference-location\f[R] option.+.TP+\f[V]--reference-location=block\f[R]|\f[V]section\f[R]|\f[V]document\f[R]+Specify whether footnotes (and references, if \f[V]reference-links\f[R]+is set) are placed at the end of the current (top-level) block, the+current section, or the document.+The default is \f[V]document\f[R].+Currently this option only affects the \f[V]markdown\f[R],+\f[V]muse\f[R], \f[V]html\f[R], \f[V]epub\f[R], \f[V]slidy\f[R],+\f[V]s5\f[R], \f[V]slideous\f[R], \f[V]dzslides\f[R], and+\f[V]revealjs\f[R] writers.+.TP+\f[V]--markdown-headings=setext\f[R]|\f[V]atx\f[R]+Specify whether to use ATX-style (\f[V]#\f[R]-prefixed) or Setext-style+(underlined) headings for level 1 and 2 headings in Markdown output.+(The default is \f[V]atx\f[R].)+ATX-style headings are always used for levels 3+.+This option also affects Markdown cells in \f[V]ipynb\f[R] output.+.TP+\f[V]--atx-headers\f[R]+\f[I]Deprecated synonym for \f[VI]--markdown-headings=atx\f[I].\f[R]+.TP+\f[V]--top-level-division=default\f[R]|\f[V]section\f[R]|\f[V]chapter\f[R]|\f[V]part\f[R]+Treat top-level headings as the given division type in LaTeX, ConTeXt,+DocBook, and TEI output.+The hierarchy order is part, chapter, then section; all headings are+shifted such that the top-level heading becomes the specified type.+The default behavior is to determine the best division type via+heuristics: unless other conditions apply, \f[V]section\f[R] is chosen.+When the \f[V]documentclass\f[R] variable is set to \f[V]report\f[R],+\f[V]book\f[R], or \f[V]memoir\f[R] (unless the \f[V]article\f[R] option+is specified), \f[V]chapter\f[R] is implied as the setting for this+option.+If \f[V]beamer\f[R] is the output format, specifying either+\f[V]chapter\f[R] or \f[V]part\f[R] will cause top-level headings to+become \f[V]\[rs]part{..}\f[R], while second-level headings remain as+their default type.+.TP+\f[V]-N\f[R], \f[V]--number-sections\f[R]+Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB+output.+By default, sections are not numbered.+Sections with class \f[V]unnumbered\f[R] will never be numbered, even if+\f[V]--number-sections\f[R] is specified.+.TP+\f[V]--number-offset=\f[R]\f[I]NUMBER\f[R][\f[V],\f[R]\f[I]NUMBER\f[R]\f[V],\f[R]\f[I]\&...\f[R]]+Offset for section headings in HTML output (ignored in other output+formats).+The first number is added to the section number for top-level headings,+the second for second-level headings, and so on.+So, for example, if you want the first top-level heading in your+document to be numbered \[lq]6\[rq], specify+\f[V]--number-offset=5\f[R].+If your document starts with a level-2 heading which you want to be+numbered \[lq]1.5\[rq], specify \f[V]--number-offset=1,4\f[R].+Offsets are 0 by default.+Implies \f[V]--number-sections\f[R].+.TP+\f[V]--listings\f[R]+Use the \f[V]listings\f[R] package for LaTeX code blocks.+The package does not support multi-byte encoding for source code.+To handle UTF-8 you would need to use a custom template.+This issue is fully documented here: Encoding issue with the listings+package.+.TP+\f[V]-i\f[R], \f[V]--incremental\f[R]+Make list items in slide shows display incrementally (one by one).+The default is for lists to be displayed all at once.+.TP+\f[V]--slide-level=\f[R]\f[I]NUMBER\f[R]+Specifies that headings with the specified level create slides (for+\f[V]beamer\f[R], \f[V]s5\f[R], \f[V]slidy\f[R], \f[V]slideous\f[R],+\f[V]dzslides\f[R]).+Headings above this level in the hierarchy are used to divide the slide+show into sections; headings below this level create subheads within a+slide.+Valid values are 0-6.+If a slide level of 0 is specified, slides will not be split+automatically on headings, and horizontal rules must be used to indicate+slide boundaries.+If a slide level is not specified explicitly, the slide level will be+set automatically based on the contents of the document; see Structuring+the slide show.+.TP+\f[V]--section-divs\f[R]+Wrap sections in \f[V]<section>\f[R] tags (or \f[V]<div>\f[R] tags for+\f[V]html4\f[R]), and attach identifiers to the enclosing+\f[V]<section>\f[R] (or \f[V]<div>\f[R]) rather than the heading itself.+See Heading identifiers, below.+.TP+\f[V]--email-obfuscation=none\f[R]|\f[V]javascript\f[R]|\f[V]references\f[R]+Specify a method for obfuscating \f[V]mailto:\f[R] links in HTML+documents.+\f[V]none\f[R] leaves \f[V]mailto:\f[R] links as they are.+\f[V]javascript\f[R] obfuscates them using JavaScript.+\f[V]references\f[R] obfuscates them by printing their letters as+decimal or hexadecimal character references.+The default is \f[V]none\f[R].+.TP+\f[V]--id-prefix=\f[R]\f[I]STRING\f[R]+Specify a prefix to be added to all identifiers and internal links in+HTML and DocBook output, and to footnote numbers in Markdown and Haddock+output.+This is useful for preventing duplicate identifiers when generating+fragments to be included in other pages.+.TP+\f[V]-T\f[R] \f[I]STRING\f[R], \f[V]--title-prefix=\f[R]\f[I]STRING\f[R]+Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that+appears in the HTML header (but not in the title as it appears at the+beginning of the HTML body).+Implies \f[V]--standalone\f[R].+.TP+\f[V]-c\f[R] \f[I]URL\f[R], \f[V]--css=\f[R]\f[I]URL\f[R]+Link to a CSS style sheet.+This option can be used repeatedly to include multiple files.+They will be included in the order specified.+.RS+.PP+A stylesheet is required for generating EPUB.+If none is provided using this option (or the \f[V]css\f[R] or+\f[V]stylesheet\f[R] metadata fields), pandoc will look for a file+\f[V]epub.css\f[R] in the user data directory (see+\f[V]--data-dir\f[R]).+If it is not found there, sensible defaults will be used.+.RE+.TP+\f[V]--reference-doc=\f[R]\f[I]FILE\f[R]+Use the specified file as a style reference in producing a docx or ODT+file.+.RS+.TP+Docx+For best results, the reference docx should be a modified version of a+docx file produced using pandoc.+The contents of the reference docx are ignored, but its stylesheets and+document properties (including margins, page size, header, and footer)+are used in the new docx.+If no reference docx is specified on the command line, pandoc will look+for a file \f[V]reference.docx\f[R] in the user data directory (see+\f[V]--data-dir\f[R]).+If this is not found either, sensible defaults will be used.+.RS+.PP+To produce a custom \f[V]reference.docx\f[R], first get a copy of the+default \f[V]reference.docx\f[R]:+\f[V]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R].+Then open \f[V]custom-reference.docx\f[R] in Word, modify the styles as+you wish, and save the file.+For best results, do not make changes to this file other than modifying+the styles used by pandoc:+.PP+Paragraph styles:+.IP \[bu] 2+Normal+.IP \[bu] 2+Body Text+.IP \[bu] 2+First Paragraph+.IP \[bu] 2+Compact+.IP \[bu] 2+Title+.IP \[bu] 2+Subtitle+.IP \[bu] 2+Author+.IP \[bu] 2+Date+.IP \[bu] 2+Abstract+.IP \[bu] 2+Bibliography+.IP \[bu] 2+Heading 1+.IP \[bu] 2+Heading 2+.IP \[bu] 2+Heading 3+.IP \[bu] 2+Heading 4+.IP \[bu] 2+Heading 5+.IP \[bu] 2+Heading 6+.IP \[bu] 2+Heading 7+.IP \[bu] 2+Heading 8+.IP \[bu] 2+Heading 9+.IP \[bu] 2+Block Text+.IP \[bu] 2+Footnote Text+.IP \[bu] 2+Definition Term+.IP \[bu] 2+Definition+.IP \[bu] 2+Caption+.IP \[bu] 2+Table Caption+.IP \[bu] 2+Image Caption+.IP \[bu] 2+Figure+.IP \[bu] 2+Captioned Figure+.IP \[bu] 2+TOC Heading+.PP+Character styles:+.IP \[bu] 2+Default Paragraph Font+.IP \[bu] 2+Body Text Char+.IP \[bu] 2+Verbatim Char+.IP \[bu] 2+Footnote Reference+.IP \[bu] 2+Hyperlink+.IP \[bu] 2+Section Number+.PP+Table style:+.IP \[bu] 2+Table+.RE+.TP+ODT+For best results, the reference ODT should be a modified version of an+ODT produced using pandoc.+The contents of the reference ODT are ignored, but its stylesheets are+used in the new ODT.+If no reference ODT is specified on the command line, pandoc will look+for a file \f[V]reference.odt\f[R] in the user data directory (see+\f[V]--data-dir\f[R]).+If this is not found either, sensible defaults will be used.+.RS+.PP+To produce a custom \f[V]reference.odt\f[R], first get a copy of the+default \f[V]reference.odt\f[R]:+\f[V]pandoc -o custom-reference.odt --print-default-data-file reference.odt\f[R].+Then open \f[V]custom-reference.odt\f[R] in LibreOffice, modify the+styles as you wish, and save the file.+.RE+.TP+PowerPoint+Templates included with Microsoft PowerPoint 2013 (either with+\f[V].pptx\f[R] or \f[V].potx\f[R] extension) are known to work, as are+most templates derived from these.+.RS+.PP+The specific requirement is that the template should contain layouts+with the following names (as seen within PowerPoint):+.IP \[bu] 2+Title Slide+.IP \[bu] 2+Title and Content+.IP \[bu] 2+Section Header+.IP \[bu] 2+Two Content+.IP \[bu] 2+Comparison+.IP \[bu] 2+Content with Caption+.IP \[bu] 2+Blank+.PP+For each name, the first layout found with that name will be used.+If no layout is found with one of the names, pandoc will output a+warning and use the layout with that name from the default reference doc+instead.+(How these layouts are used is described in PowerPoint layout choice.)+.PP+All templates included with a recent version of MS PowerPoint will fit+these criteria.+(You can click on \f[V]Layout\f[R] under the \f[V]Home\f[R] menu to+check.)+.PP+You can also modify the default \f[V]reference.pptx\f[R]: first run+\f[V]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R],+and then modify \f[V]custom-reference.pptx\f[R] in MS PowerPoint (pandoc+will use the layouts with the names listed above).+.RE+.RE+.TP+\f[V]--epub-cover-image=\f[R]\f[I]FILE\f[R]+Use the specified image as the EPUB cover.+It is recommended that the image be less than 1000px in width and+height.+Note that in a Markdown source document you can also specify+\f[V]cover-image\f[R] in a YAML metadata block (see EPUB Metadata,+below).+.TP+\f[V]--epub-metadata=\f[R]\f[I]FILE\f[R]+Look in the specified XML file for metadata for the EPUB.+The file should contain a series of Dublin Core elements.+For example:+.RS+.IP+.nf+\f[C]+ <dc:rights>Creative Commons</dc:rights>+ <dc:language>es-AR</dc:language>+\f[R]+.fi+.PP+By default, pandoc will include the following metadata elements:+\f[V]<dc:title>\f[R] (from the document title), \f[V]<dc:creator>\f[R]+(from the document authors), \f[V]<dc:date>\f[R] (from the document+date, which should be in ISO 8601 format), \f[V]<dc:language>\f[R] (from+the \f[V]lang\f[R] variable, or, if is not set, the locale), and+\f[V]<dc:identifier id=\[dq]BookId\[dq]>\f[R] (a randomly generated+UUID).+Any of these may be overridden by elements in the metadata file.+.PP+Note: if the source document is Markdown, a YAML metadata block in the+document can be used instead.+See below under EPUB Metadata.+.RE+.TP+\f[V]--epub-embed-font=\f[R]\f[I]FILE\f[R]+Embed the specified font in the EPUB.+This option can be repeated to embed multiple fonts.+Wildcards can also be used: for example, \f[V]DejaVuSans-*.ttf\f[R].+However, if you use wildcards on the command line, be sure to escape+them or put the whole filename in single quotes, to prevent them from+being interpreted by the shell.+To use the embedded fonts, you will need to add declarations like the+following to your CSS (see \f[V]--css\f[R]):+.RS+.IP+.nf+\f[C]+\[at]font-face {+font-family: DejaVuSans;+font-style: normal;+font-weight: normal;+src:url(\[dq]DejaVuSans-Regular.ttf\[dq]);+}+\[at]font-face {+font-family: DejaVuSans;+font-style: normal;+font-weight: bold;+src:url(\[dq]DejaVuSans-Bold.ttf\[dq]);+}+\[at]font-face {+font-family: DejaVuSans;+font-style: italic;+font-weight: normal;+src:url(\[dq]DejaVuSans-Oblique.ttf\[dq]);+}+\[at]font-face {+font-family: DejaVuSans;+font-style: italic;+font-weight: bold;+src:url(\[dq]DejaVuSans-BoldOblique.ttf\[dq]);+}+body { font-family: \[dq]DejaVuSans\[dq]; }+\f[R]+.fi+.RE+.TP+\f[V]--epub-chapter-level=\f[R]\f[I]NUMBER\f[R]+Specify the heading level at which to split the EPUB into separate+\[lq]chapter\[rq] files.+The default is to split into chapters at level-1 headings.+This option only affects the internal composition of the EPUB, not the+way chapters and sections are displayed to users.+Some readers may be slow if the chapter files are too large, so for+large documents with few level-1 headings, one might want to use a+chapter level of 2 or 3.+.TP+\f[V]--epub-subdirectory=\f[R]\f[I]DIRNAME\f[R]+Specify the subdirectory in the OCF container that is to hold the+EPUB-specific contents.+The default is \f[V]EPUB\f[R].+To put the EPUB contents in the top level, use an empty string.+.TP+\f[V]--ipynb-output=all|none|best\f[R]+Determines how ipynb output cells are treated.+\f[V]all\f[R] means that all of the data formats included in the+original are preserved.+\f[V]none\f[R] means that the contents of data cells are omitted.+\f[V]best\f[R] causes pandoc to try to pick the richest data block in+each output cell that is compatible with the output format.+The default is \f[V]best\f[R].+.TP+\f[V]--pdf-engine=\f[R]\f[I]PROGRAM\f[R]+Use the specified engine when producing PDF output.+Valid values are \f[V]pdflatex\f[R], \f[V]lualatex\f[R],+\f[V]xelatex\f[R], \f[V]latexmk\f[R], \f[V]tectonic\f[R],+\f[V]wkhtmltopdf\f[R], \f[V]weasyprint\f[R], \f[V]pagedjs-cli\f[R],+\f[V]prince\f[R], \f[V]context\f[R], and \f[V]pdfroff\f[R].+If the engine is not in your PATH, the full path of the engine may be+specified here.+If this option is not specified, pandoc uses the following defaults+depending on the output format specified using \f[V]-t/--to\f[R]:+.RS+.IP \[bu] 2+\f[V]-t latex\f[R] or none: \f[V]pdflatex\f[R] (other options:+\f[V]xelatex\f[R], \f[V]lualatex\f[R], \f[V]tectonic\f[R],+\f[V]latexmk\f[R])+.IP \[bu] 2+\f[V]-t context\f[R]: \f[V]context\f[R]+.IP \[bu] 2+\f[V]-t html\f[R]: \f[V]wkhtmltopdf\f[R] (other options:+\f[V]prince\f[R], \f[V]weasyprint\f[R], \f[V]pagedjs-cli\f[R]; see+print-css.rocks for a good introduction to PDF generation from+HTML/CSS.)+.IP \[bu] 2+\f[V]-t ms\f[R]: \f[V]pdfroff\f[R]+.RE+.TP+\f[V]--pdf-engine-opt=\f[R]\f[I]STRING\f[R]+Use the given string as a command-line argument to the+\f[V]pdf-engine\f[R].+For example, to use a persistent directory \f[V]foo\f[R] for+\f[V]latexmk\f[R]\[cq]s auxiliary files, use+\f[V]--pdf-engine-opt=-outdir=foo\f[R].+Note that no check for duplicate options is done.+.SS Citation rendering+.TP+\f[V]-C\f[R], \f[V]--citeproc\f[R]+Process the citations in the file, replacing them with rendered+citations and adding a bibliography.+Citation processing will not take place unless bibliographic data is+supplied, either through an external file specified using the+\f[V]--bibliography\f[R] option or the \f[V]bibliography\f[R] field in+metadata, or via a \f[V]references\f[R] section in metadata containing a+list of citations in CSL YAML format with Markdown formatting.+The style is controlled by a CSL stylesheet specified using the+\f[V]--csl\f[R] option or the \f[V]csl\f[R] field in metadata.+(If no stylesheet is specified, the \f[V]chicago-author-date\f[R] style+will be used by default.)+The citation processing transformation may be applied before or after+filters or Lua filters (see \f[V]--filter\f[R], \f[V]--lua-filter\f[R]):+these transformations are applied in the order they appear on the+command line.+For more information, see the section on Citations.+.TP+\f[V]--bibliography=\f[R]\f[I]FILE\f[R]+Set the \f[V]bibliography\f[R] field in the document\[cq]s metadata to+\f[I]FILE\f[R], overriding any value set in the metadata.+If you supply this argument multiple times, each \f[I]FILE\f[R] will be+added to bibliography.+If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.+If \f[I]FILE\f[R] is not found relative to the working directory, it+will be sought in the resource path (see \f[V]--resource-path\f[R]).+.TP+\f[V]--csl=\f[R]\f[I]FILE\f[R]+Set the \f[V]csl\f[R] field in the document\[cq]s metadata to+\f[I]FILE\f[R], overriding any value set in the metadata.+(This is equivalent to \f[V]--metadata csl=FILE\f[R].)+If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.+If \f[I]FILE\f[R] is not found relative to the working directory, it+will be sought in the resource path (see \f[V]--resource-path\f[R]) and+finally in the \f[V]csl\f[R] subdirectory of the pandoc user data+directory.+.TP+\f[V]--citation-abbreviations=\f[R]\f[I]FILE\f[R]+Set the \f[V]citation-abbreviations\f[R] field in the document\[cq]s+metadata to \f[I]FILE\f[R], overriding any value set in the metadata.+(This is equivalent to+\f[V]--metadata citation-abbreviations=FILE\f[R].)+If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.+If \f[I]FILE\f[R] is not found relative to the working directory, it+will be sought in the resource path (see \f[V]--resource-path\f[R]) and+finally in the \f[V]csl\f[R] subdirectory of the pandoc user data+directory.+.TP+\f[V]--natbib\f[R]+Use \f[V]natbib\f[R] for citations in LaTeX output.+This option is not for use with the \f[V]--citeproc\f[R] option or with+PDF output.+It is intended for use in producing a LaTeX file that can be processed+with \f[V]bibtex\f[R].+.TP+\f[V]--biblatex\f[R]+Use \f[V]biblatex\f[R] for citations in LaTeX output.+This option is not for use with the \f[V]--citeproc\f[R] option or with+PDF output.+It is intended for use in producing a LaTeX file that can be processed+with \f[V]bibtex\f[R] or \f[V]biber\f[R].+.SS Math rendering in HTML+.PP+The default is to render TeX math as far as possible using Unicode+characters.+Formulas are put inside a \f[V]span\f[R] with+\f[V]class=\[dq]math\[dq]\f[R], so that they may be styled differently+from the surrounding text if needed.+However, this gives acceptable results only for basic math, usually you+will want to use \f[V]--mathjax\f[R] or another of the following+options.+.TP+\f[V]--mathjax\f[R][\f[V]=\f[R]\f[I]URL\f[R]]+Use MathJax to display embedded TeX math in HTML output.+TeX math will be put between \f[V]\[rs](...\[rs])\f[R] (for inline math)+or \f[V]\[rs][...\[rs]]\f[R] (for display math) and wrapped in+\f[V]<span>\f[R] tags with class \f[V]math\f[R].+Then the MathJax JavaScript will render it.+The \f[I]URL\f[R] should point to the \f[V]MathJax.js\f[R] load script.+If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be+inserted.+.TP+\f[V]--mathml\f[R]+Convert TeX math to MathML (in \f[V]epub3\f[R], \f[V]docbook4\f[R],+\f[V]docbook5\f[R], \f[V]jats\f[R], \f[V]html4\f[R] and+\f[V]html5\f[R]).+This is the default in \f[V]odt\f[R] output.+Note that currently only Firefox and Safari (and select e-book readers)+natively support MathML.+.TP+\f[V]--webtex\f[R][\f[V]=\f[R]\f[I]URL\f[R]]+Convert TeX formulas to \f[V]<img>\f[R] tags that link to an external+script that converts formulas to images.+The formula will be URL-encoded and concatenated with the URL provided.+For SVG images you can for example use+\f[V]--webtex https://latex.codecogs.com/svg.latex?\f[R].+If no URL is specified, the CodeCogs URL generating PNGs will be used+(\f[V]https://latex.codecogs.com/png.latex?\f[R]).+Note: the \f[V]--webtex\f[R] option will affect Markdown output as well+as HTML, which is useful if you\[cq]re targeting a version of Markdown+without native math support.+.TP+\f[V]--katex\f[R][\f[V]=\f[R]\f[I]URL\f[R]]+Use KaTeX to display embedded TeX math in HTML output.+The \f[I]URL\f[R] is the base URL for the KaTeX library.+That directory should contain a \f[V]katex.min.js\f[R] and a+\f[V]katex.min.css\f[R] file.+If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be+inserted.+.TP+\f[V]--gladtex\f[R]+Enclose TeX math in \f[V]<eq>\f[R] tags in HTML output.+The resulting HTML can then be processed by GladTeX to produce SVG+images of the typeset formulas and an HTML file with these images+embedded.+.RS+.IP+.nf+\f[C]+pandoc -s --gladtex input.md -o myfile.htex+gladtex -d image_dir myfile.htex+# produces myfile.html and images in image_dir+\f[R]+.fi+.RE+.SS Options for wrapper scripts+.TP+\f[V]--dump-args\f[R]+Print information about command-line arguments to \f[I]stdout\f[R], then+exit.+This option is intended primarily for use in wrapper scripts.+The first line of output contains the name of the output file specified+with the \f[V]-o\f[R] option, or \f[V]-\f[R] (for \f[I]stdout\f[R]) if+no output file was specified.+The remaining lines contain the command-line arguments, one per line, in+the order they appear.+These do not include regular pandoc options and their arguments, but do+include any options appearing after a \f[V]--\f[R] separator at the end+of the line.+.TP+\f[V]--ignore-args\f[R]+Ignore command-line arguments (for use in wrapper scripts).+Regular pandoc options are not ignored.+Thus, for example,+.RS+.IP+.nf+\f[C]+pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1+\f[R]+.fi+.PP+is equivalent to+.IP+.nf+\f[C]+pandoc -o foo.html -s+\f[R]+.fi+.RE+.SH EXIT CODES+.PP+If pandoc completes successfully, it will return exit code 0.+Nonzero exit codes have the following meanings:+.PP+.TS+tab(@);+r l.+T{+Code+T}@T{+Error+T}+_+T{+1+T}@T{+PandocIOError+T}+T{+3+T}@T{+PandocFailOnWarningError+T}+T{+4+T}@T{+PandocAppError+T}+T{+5+T}@T{+PandocTemplateError+T}+T{+6+T}@T{+PandocOptionError+T}+T{+21+T}@T{+PandocUnknownReaderError+T}+T{+22+T}@T{+PandocUnknownWriterError+T}+T{+23+T}@T{+PandocUnsupportedExtensionError+T}+T{+24+T}@T{+PandocCiteprocError+T}+T{+25+T}@T{+PandocBibliographyError+T}+T{+31+T}@T{+PandocEpubSubdirectoryError+T}+T{+43+T}@T{+PandocPDFError+T}+T{+44+T}@T{+PandocXMLError+T}+T{+47+T}@T{+PandocPDFProgramNotFoundError+T}+T{+61+T}@T{+PandocHttpError+T}+T{+62+T}@T{+PandocShouldNeverHappenError+T}+T{+63+T}@T{+PandocSomeError+T}+T{+64+T}@T{+PandocParseError+T}+T{+65+T}@T{+PandocParsecError+T}+T{+66+T}@T{+PandocMakePDFError+T}+T{+67+T}@T{+PandocSyntaxMapError+T}+T{+83+T}@T{+PandocFilterError+T}+T{+84+T}@T{+PandocLuaError+T}+T{+91+T}@T{+PandocMacroLoop+T}+T{+92+T}@T{+PandocUTF8DecodingError+T}+T{+93+T}@T{+PandocIpynbDecodingError+T}+T{+94+T}@T{+PandocUnsupportedCharsetError+T}+T{+97+T}@T{+PandocCouldNotFindDataFileError+T}+T{+98+T}@T{+PandocCouldNotFindMetadataFileError+T}+T{+99+T}@T{+PandocResourceNotFound+T}+.TE+.SH DEFAULTS FILES+.PP+The \f[V]--defaults\f[R] option may be used to specify a package of+options, in the form of a YAML file.+.PP+Fields that are omitted will just have their regular default values.+So a defaults file can be as simple as one line:+.IP+.nf+\f[C]+verbosity: INFO+\f[R]+.fi+.PP+In fields that expect a file path (or list of file paths), the following+syntax may be used to interpolate environment variables:+.IP+.nf+\f[C]+csl:  ${HOME}/mycsldir/special.csl+\f[R]+.fi+.PP+\f[V]${USERDATA}\f[R] may also be used; this will always resolve to the+user data directory that is current when the defaults file is parsed,+regardless of the setting of the environment variable+\f[V]USERDATA\f[R].+.PP+\f[V]${.}\f[R] will resolve to the directory containing the defaults+file itself.+This allows you to refer to resources contained in that directory:+.IP+.nf+\f[C]+epub-cover-image: ${.}/cover.jpg+epub-metadata: ${.}/meta.xml+resource-path:+- .             # the working directory from which pandoc is run+- ${.}/images   # the images subdirectory of the directory+                # containing this defaults file+\f[R]+.fi+.PP+This environment variable interpolation syntax \f[I]only\f[R] works in+fields that expect file paths.+.PP+Defaults files can be placed in the \f[V]defaults\f[R] subdirectory of+the user data directory and used from any directory.+For example, one could create a file specifying defaults for writing+letters, save it as \f[V]letter.yaml\f[R] in the \f[V]defaults\f[R]+subdirectory of the user data directory, and then invoke these defaults+from any directory using \f[V]pandoc --defaults letter\f[R] or+\f[V]pandoc -dletter\f[R].+.PP+When multiple defaults are used, their contents will be combined.+.PP+Note that, where command-line arguments may be repeated+(\f[V]--metadata-file\f[R], \f[V]--css\f[R],+\f[V]--include-in-header\f[R], \f[V]--include-before-body\f[R],+\f[V]--include-after-body\f[R], \f[V]--variable\f[R],+\f[V]--metadata\f[R], \f[V]--syntax-definition\f[R]), the values+specified on the command line will combine with values specified in the+defaults file, rather than replacing them.+.PP+The following tables show the mapping between the command line and+defaults file entries.+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+foo.md+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+input-file: foo.md+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+foo.md bar.md++\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+input-files:+  - foo.md+  - bar.md+\f[R]+.fi+.RE+T}+.TE+.PP+The value of \f[V]input-files\f[R] may be left empty to indicate input+from stdin, and it can be an empty sequence \f[V][]\f[R] for no input.+.SS General options+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+--from markdown+emoji+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+from: markdown+emoji+\f[R]+.fi+.IP+.nf+\f[C]+reader: markdown+emoji+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--to markdown+hard_line_breaks+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+to: markdown+hard_line_breaks+\f[R]+.fi+.IP+.nf+\f[C]+writer: markdown+hard_line_breaks+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--output foo.pdf+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+output-file: foo.pdf+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--output -+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+output-file:+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--data-dir dir+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+data-dir: dir+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--defaults file+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+defaults:+- file+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--verbose+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+verbosity: INFO+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--quiet+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+verbosity: ERROR+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--fail-if-warnings+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+fail-if-warnings: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--sandbox+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+sandbox: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--log=FILE+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+log-file: FILE+\f[R]+.fi+.RE+T}+.TE+.PP+Options specified in a defaults file itself always have priority over+those in another file included with a \f[V]defaults:\f[R] entry.+.PP+\f[V]verbosity\f[R] can have the values \f[V]ERROR\f[R],+\f[V]WARNING\f[R], or \f[V]INFO\f[R].+.SS Reader options+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+--shift-heading-level-by -1+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+shift-heading-level-by: -1+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--indented-code-classes python+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+indented-code-classes:+  - python+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--default-image-extension \[dq].jpg\[dq]+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+default-image-extension: \[aq].jpg\[aq]+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--file-scope+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+file-scope: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--filter pandoc-citeproc \[rs]+ --lua-filter count-words.lua \[rs]+ --filter special.lua++\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+filters:+  - pandoc-citeproc+  - count-words.lua+  - type: json+    path: special.lua+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--metadata key=value \[rs]+ --metadata key2+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+metadata:+  key: value+  key2: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--metadata-file meta.yaml+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+metadata-files:+  - meta.yaml+\f[R]+.fi+.IP+.nf+\f[C]+metadata-file: meta.yaml+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--preserve-tabs+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+preserve-tabs: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--tab-stop 8+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+tab-stop: 8+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--track-changes accept+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+track-changes: accept+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--extract-media dir+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+extract-media: dir+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--abbreviations abbrevs.txt+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+abbreviations: abbrevs.txt+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--trace+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+trace: true+\f[R]+.fi+.RE+T}+.TE+.PP+Metadata values specified in a defaults file are parsed as literal+string text, not Markdown.+.PP+Filters will be assumed to be Lua filters if they have the+\f[V].lua\f[R] extension, and JSON filters otherwise.+But the filter type can also be specified explicitly, as shown.+Filters are run in the order specified.+To include the built-in citeproc filter, use either \f[V]citeproc\f[R]+or \f[V]{type: citeproc}\f[R].+.SS General writer options+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+--standalone+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+standalone: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--template letter+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+template: letter+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--variable key=val \[rs]+  --variable key2+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+variables:+  key: val+  key2: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--eol nl+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+eol: nl+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--dpi 300+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+dpi: 300+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--wrap 60+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+wrap: 60+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--columns 72+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+columns: 72+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--table-of-contents+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+table-of-contents: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--toc+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+toc: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--toc-depth 3+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+toc-depth: 3+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--strip-comments+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+strip-comments: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--no-highlight+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+highlight-style: null+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--highlight-style kate+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+highlight-style: kate+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--syntax-definition mylang.xml+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+syntax-definitions:+  - mylang.xml+\f[R]+.fi+.IP+.nf+\f[C]+syntax-definition: mylang.xml+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--include-in-header inc.tex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+include-in-header:+  - inc.tex+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--include-before-body inc.tex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+include-before-body:+  - inc.tex+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--include-after-body inc.tex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+include-after-body:+  - inc.tex+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--resource-path .:foo+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+resource-path: [\[aq].\[aq],\[aq]foo\[aq]]+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--request-header foo:bar+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+request-headers:+  - [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]]+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--no-check-certificate+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+no-check-certificate: true+\f[R]+.fi+.RE+T}+.TE+.SS Options affecting specific writers+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+--self-contained+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+self-contained: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--html-q-tags+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+html-q-tags: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--ascii+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+ascii: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--reference-links+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+reference-links: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--reference-location block+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+reference-location: block+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--markdown-headings atx+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+markdown-headings: atx+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--top-level-division chapter+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+top-level-division: chapter+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--number-sections+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+number-sections: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--number-offset=1,4+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+number-offset: \[rs][1,4\[rs]]+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--listings+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+listings: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--incremental+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+incremental: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--slide-level 2+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+slide-level: 2+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--section-divs+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+section-divs: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--email-obfuscation references+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+email-obfuscation: references+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--id-prefix ch1+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+identifier-prefix: ch1+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--title-prefix MySite+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+title-prefix: MySite+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--css styles/screen.css  \[rs]+  --css styles/special.css+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+css:+  - styles/screen.css+  - styles/special.css+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--reference-doc my.docx+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+reference-doc: my.docx+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--epub-cover-image cover.jpg+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+epub-cover-image: cover.jpg+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--epub-metadata meta.xml+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+epub-metadata: meta.xml+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--epub-embed-font special.otf \[rs]+  --epub-embed-font headline.otf+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+epub-fonts:+  - special.otf+  - headline.otf+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--epub-chapter-level 2+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+epub-chapter-level: 2+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--epub-subdirectory=\[dq]\[dq]+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+epub-subdirectory: \[aq]\[aq]+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--ipynb-output best+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+ipynb-output: best+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--pdf-engine xelatex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+pdf-engine: xelatex+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--pdf-engine-opt=--shell-escape+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+pdf-engine-opts:+  - \[aq]-shell-escape\[aq]+\f[R]+.fi+.IP+.nf+\f[C]+pdf-engine-opt: \[aq]-shell-escape\[aq]+\f[R]+.fi+.RE+T}+.TE+.SS Citation rendering+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+--citeproc+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+citeproc: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--bibliography logic.bib+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+metadata:+  bibliography: logic.bib+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--csl ieee.csl+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+metadata:+  csl: ieee.csl+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--citation-abbreviations ab.json+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+metadata:+  citation-abbreviations: ab.json+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--natbib+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+cite-method: natbib+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--biblatex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+cite-method: biblatex+\f[R]+.fi+.RE+T}+.TE+.PP+\f[V]cite-method\f[R] can be \f[V]citeproc\f[R], \f[V]natbib\f[R], or+\f[V]biblatex\f[R].+This only affects LaTeX output.+If you want to use citeproc to format citations, you should also set+`citeproc: true'.+.PP+If you need control over when the citeproc processing is done relative+to other filters, you should instead use \f[V]citeproc\f[R] in the list+of \f[V]filters\f[R] (see above).+.SS Math rendering in HTML+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+--mathjax+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+html-math-method:+  method: mathjax+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--mathml+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+html-math-method:+  method: mathml+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--webtex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+html-math-method:+  method: webtex+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--katex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+html-math-method:+  method: katex+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--gladtex+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+html-math-method:+  method: gladtex+\f[R]+.fi+.RE+T}+.TE+.PP+In addition to the values listed above, \f[V]method\f[R] can have the+value \f[V]plain\f[R].+.PP+If the command line option accepts a URL argument, an \f[V]url:\f[R]+field can be added to \f[V]html-math-method:\f[R].+.SS Options for wrapper scripts+.PP+.TS+tab(@);+lw(34.0n) lw(35.0n).+T{+command line+T}@T{+defaults file+T}+_+T{+.RS -14n+.IP+.nf+\f[C]+--dump-args+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+dump-args: true+\f[R]+.fi+.RE+T}+T{+.RS -14n+.IP+.nf+\f[C]+--ignore-args+\f[R]+.fi+.RE+T}@T{+.RS -14n+.IP+.nf+\f[C]+ignore-args: true+\f[R]+.fi+.RE+T}+.TE+.SH TEMPLATES+.PP+When the \f[V]-s/--standalone\f[R] option is used, pandoc uses a+template to add header and footer material that is needed for a+self-standing document.+To see the default template that is used, just type+.IP+.nf+\f[C]+pandoc -D *FORMAT*+\f[R]+.fi+.PP+where \f[I]FORMAT\f[R] is the name of the output format.+A custom template can be specified using the \f[V]--template\f[R]+option.+You can also override the system default templates for a given output+format \f[I]FORMAT\f[R] by putting a file+\f[V]templates/default.*FORMAT*\f[R] in the user data directory (see+\f[V]--data-dir\f[R], above).+\f[I]Exceptions:\f[R]+.IP \[bu] 2+For \f[V]odt\f[R] output, customize the \f[V]default.opendocument\f[R]+template.+.IP \[bu] 2+For \f[V]pdf\f[R] output, customize the \f[V]default.latex\f[R] template+(or the \f[V]default.context\f[R] template, if you use+\f[V]-t context\f[R], or the \f[V]default.ms\f[R] template, if you use+\f[V]-t ms\f[R], or the \f[V]default.html\f[R] template, if you use+\f[V]-t html\f[R]).+.IP \[bu] 2+\f[V]docx\f[R] and \f[V]pptx\f[R] have no template (however, you can use+\f[V]--reference-doc\f[R] to customize the output).+.PP+Templates contain \f[I]variables\f[R], which allow for the inclusion of+arbitrary information at any point in the file.+They may be set at the command line using the \f[V]-V/--variable\f[R]+option.+If a variable is not set, pandoc will look for the key in the+document\[cq]s metadata, which can be set using either YAML metadata+blocks or with the \f[V]-M/--metadata\f[R] option.+In addition, some variables are given default values by pandoc.+See Variables below for a list of variables used in pandoc\[cq]s default+templates.+.PP+If you use custom templates, you may need to revise them as pandoc+changes.+We recommend tracking the changes in the default templates, and+modifying your custom templates accordingly.+An easy way to do this is to fork the pandoc-templates repository and+merge in changes after each pandoc release.+.SS Template syntax+.SS Comments+.PP+Anything between the sequence \f[V]$--\f[R] and the end of the line will+be treated as a comment and omitted from the output.+.SS Delimiters+.PP+To mark variables and control structures in the template, either+\f[V]$\f[R]\&...\f[V]$\f[R] or \f[V]${\f[R]\&...\f[V]}\f[R] may be used+as delimiters.+The styles may also be mixed in the same template, but the opening and+closing delimiter must match in each case.+The opening delimiter may be followed by one or more spaces or tabs,+which will be ignored.+The closing delimiter may be followed by one or more spaces or tabs,+which will be ignored.+.PP+To include a literal \f[V]$\f[R] in the document, use \f[V]$$\f[R].+.SS Interpolated variables+.PP+A slot for an interpolated variable is a variable name surrounded by+matched delimiters.+Variable names must begin with a letter and can contain letters,+numbers, \f[V]_\f[R], \f[V]-\f[R], and \f[V].\f[R].+The keywords \f[V]it\f[R], \f[V]if\f[R], \f[V]else\f[R],+\f[V]endif\f[R], \f[V]for\f[R], \f[V]sep\f[R], and \f[V]endfor\f[R] may+not be used as variable names.+Examples:+.IP+.nf+\f[C]+$foo$+$foo.bar.baz$+$foo_bar.baz-bim$+$ foo $+${foo}+${foo.bar.baz}+${foo_bar.baz-bim}+${ foo }+\f[R]+.fi+.PP+Variable names with periods are used to get at structured variable+values.+So, for example, \f[V]employee.salary\f[R] will return the value of the+\f[V]salary\f[R] field of the object that is the value of the+\f[V]employee\f[R] field.+.IP \[bu] 2+If the value of the variable is simple value, it will be rendered+verbatim.+(Note that no escaping is done; the assumption is that the calling+program will escape the strings appropriately for the output format.)+.IP \[bu] 2+If the value is a list, the values will be concatenated.+.IP \[bu] 2+If the value is a map, the string \f[V]true\f[R] will be rendered.+.IP \[bu] 2+Every other value will be rendered as the empty string.+.SS Conditionals+.PP+A conditional begins with \f[V]if(variable)\f[R] (enclosed in matched+delimiters) and ends with \f[V]endif\f[R] (enclosed in matched+delimiters).+It may optionally contain an \f[V]else\f[R] (enclosed in matched+delimiters).+The \f[V]if\f[R] section is used if \f[V]variable\f[R] has a non-empty+value, otherwise the \f[V]else\f[R] section is used (if present).+Examples:+.IP+.nf+\f[C]+$if(foo)$bar$endif$++$if(foo)$+  $foo$+$endif$++$if(foo)$+part one+$else$+part two+$endif$++${if(foo)}bar${endif}++${if(foo)}+  ${foo}+${endif}++${if(foo)}+${ foo.bar }+${else}+no foo!+${endif}+\f[R]+.fi+.PP+The keyword \f[V]elseif\f[R] may be used to simplify complex nested+conditionals:+.IP+.nf+\f[C]+$if(foo)$+XXX+$elseif(bar)$+YYY+$else$+ZZZ+$endif$+\f[R]+.fi+.SS For loops+.PP+A for loop begins with \f[V]for(variable)\f[R] (enclosed in matched+delimiters) and ends with \f[V]endfor\f[R] (enclosed in matched+delimiters.+.IP \[bu] 2+If \f[V]variable\f[R] is an array, the material inside the loop will be+evaluated repeatedly, with \f[V]variable\f[R] being set to each value of+the array in turn, and concatenated.+.IP \[bu] 2+If \f[V]variable\f[R] is a map, the material inside will be set to the+map.+.IP \[bu] 2+If the value of the associated variable is not an array or a map, a+single iteration will be performed on its value.+.PP+Examples:+.IP+.nf+\f[C]+$for(foo)$$foo$$sep$, $endfor$++$for(foo)$+  - $foo.last$, $foo.first$+$endfor$++${ for(foo.bar) }+  - ${ foo.bar.last }, ${ foo.bar.first }+${ endfor }++$for(mymap)$+$it.name$: $it.office$+$endfor$+\f[R]+.fi+.PP+You may optionally specify a separator between consecutive values using+\f[V]sep\f[R] (enclosed in matched delimiters).+The material between \f[V]sep\f[R] and the \f[V]endfor\f[R] is the+separator.+.IP+.nf+\f[C]+${ for(foo) }${ foo }${ sep }, ${ endfor }+\f[R]+.fi+.PP+Instead of using \f[V]variable\f[R] inside the loop, the special+anaphoric keyword \f[V]it\f[R] may be used.+.IP+.nf+\f[C]+${ for(foo.bar) }+  - ${ it.last }, ${ it.first }+${ endfor }+\f[R]+.fi+.SS Partials+.PP+Partials (subtemplates stored in different files) may be included by+using the name of the partial, followed by \f[V]()\f[R], for example:+.IP+.nf+\f[C]+${ styles() }+\f[R]+.fi+.PP+Partials will be sought in the directory containing the main template.+The file name will be assumed to have the same extension as the main+template if it lacks an extension.+When calling the partial, the full name including file extension can+also be used:+.IP+.nf+\f[C]+${ styles.html() }+\f[R]+.fi+.PP+(If a partial is not found in the directory of the template and the+template path is given as a relative path, it will also be sought in the+\f[V]templates\f[R] subdirectory of the user data directory.)+.PP+Partials may optionally be applied to variables using a colon:+.IP+.nf+\f[C]+${ date:fancy() }++${ articles:bibentry() }+\f[R]+.fi+.PP+If \f[V]articles\f[R] is an array, this will iterate over its values,+applying the partial \f[V]bibentry()\f[R] to each one.+So the second example above is equivalent to+.IP+.nf+\f[C]+${ for(articles) }+${ it:bibentry() }+${ endfor }+\f[R]+.fi+.PP+Note that the anaphoric keyword \f[V]it\f[R] must be used when iterating+over partials.+In the above examples, the \f[V]bibentry\f[R] partial should contain+\f[V]it.title\f[R] (and so on) instead of \f[V]articles.title\f[R].+.PP+Final newlines are omitted from included partials.+.PP+Partials may include other partials.+.PP+A separator between values of an array may be specified in square+brackets, immediately after the variable name or partial:+.IP+.nf+\f[C]+${months[, ]}$++${articles:bibentry()[; ]$+\f[R]+.fi+.PP+The separator in this case is literal and (unlike with \f[V]sep\f[R] in+an explicit \f[V]for\f[R] loop) cannot contain interpolated variables or+other template directives.+.SS Nesting+.PP+To ensure that content is \[lq]nested,\[rq] that is, subsequent lines+indented, use the \f[V]\[ha]\f[R] directive:+.IP+.nf+\f[C]+$item.number$  $\[ha]$$item.description$ ($item.price$)+\f[R]+.fi+.PP+In this example, if \f[V]item.description\f[R] has multiple lines, they+will all be indented to line up with the first line:+.IP+.nf+\f[C]+00123  A fine bottle of 18-year old+       Oban whiskey. ($148)+\f[R]+.fi+.PP+To nest multiple lines to the same level, align them with the+\f[V]\[ha]\f[R] directive in the template.+For example:+.IP+.nf+\f[C]+$item.number$  $\[ha]$$item.description$ ($item.price$)+               (Available til $item.sellby$.)+\f[R]+.fi+.PP+will produce+.IP+.nf+\f[C]+00123  A fine bottle of 18-year old+       Oban whiskey. ($148)+       (Available til March 30, 2020.)+\f[R]+.fi+.PP+If a variable occurs by itself on a line, preceded by whitespace and not+followed by further text or directives on the same line, and the+variable\[cq]s value contains multiple lines, it will be nested+automatically.+.SS Breakable spaces+.PP+Normally, spaces in the template itself (as opposed to values of the+interpolated variables) are not breakable, but they can be made+breakable in part of the template by using the \f[V]\[ti]\f[R] keyword+(ended with another \f[V]\[ti]\f[R]).+.IP+.nf+\f[C]+$\[ti]$This long line may break if the document is rendered+with a short line length.$\[ti]$+\f[R]+.fi+.SS Pipes+.PP+A pipe transforms the value of a variable or partial.+Pipes are specified using a slash (\f[V]/\f[R]) between the variable+name (or partial) and the pipe name.+Example:+.IP+.nf+\f[C]+$for(name)$+$name/uppercase$+$endfor$++$for(metadata/pairs)$+- $it.key$: $it.value$+$endfor$++$employee:name()/uppercase$+\f[R]+.fi+.PP+Pipes may be chained:+.IP+.nf+\f[C]+$for(employees/pairs)$+$it.key/alpha/uppercase$. $it.name$+$endfor$+\f[R]+.fi+.PP+Some pipes take parameters:+.IP+.nf+\f[C]+|----------------------|------------|+$for(employee)$+$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$+$endfor$+|----------------------|------------|+\f[R]+.fi+.PP+Currently the following pipes are predefined:+.IP \[bu] 2+\f[V]pairs\f[R]: Converts a map or array to an array of maps, each with+\f[V]key\f[R] and \f[V]value\f[R] fields.+If the original value was an array, the \f[V]key\f[R] will be the array+index, starting with 1.+.IP \[bu] 2+\f[V]uppercase\f[R]: Converts text to uppercase.+.IP \[bu] 2+\f[V]lowercase\f[R]: Converts text to lowercase.+.IP \[bu] 2+\f[V]length\f[R]: Returns the length of the value: number of characters+for a textual value, number of elements for a map or array.+.IP \[bu] 2+\f[V]reverse\f[R]: Reverses a textual value or array, and has no effect+on other values.+.IP \[bu] 2+\f[V]first\f[R]: Returns the first value of an array, if applied to a+non-empty array; otherwise returns the original value.+.IP \[bu] 2+\f[V]last\f[R]: Returns the last value of an array, if applied to a+non-empty array; otherwise returns the original value.+.IP \[bu] 2+\f[V]rest\f[R]: Returns all but the first value of an array, if applied+to a non-empty array; otherwise returns the original value.+.IP \[bu] 2+\f[V]allbutlast\f[R]: Returns all but the last value of an array, if+applied to a non-empty array; otherwise returns the original value.+.IP \[bu] 2+\f[V]chomp\f[R]: Removes trailing newlines (and breakable space).+.IP \[bu] 2+\f[V]nowrap\f[R]: Disables line wrapping on breakable spaces.+.IP \[bu] 2+\f[V]alpha\f[R]: Converts textual values that can be read as an integer+into lowercase alphabetic characters \f[V]a..z\f[R] (mod 26).+This can be used to get lettered enumeration from array indices.+To get uppercase letters, chain with \f[V]uppercase\f[R].+.IP \[bu] 2+\f[V]roman\f[R]: Converts textual values that can be read as an integer+into lowercase roman numerials.+This can be used to get lettered enumeration from array indices.+To get uppercase roman, chain with \f[V]uppercase\f[R].+.IP \[bu] 2+\f[V]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a+textual value in a block of width \f[V]n\f[R], aligned to the left, with+an optional left and right border.+Has no effect on other values.+This can be used to align material in tables.+Widths are positive integers indicating the number of characters.+Borders are strings inside double quotes; literal \f[V]\[dq]\f[R] and+\f[V]\[rs]\f[R] characters must be backslash-escaped.+.IP \[bu] 2+\f[V]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a+textual value in a block of width \f[V]n\f[R], aligned to the right, and+has no effect on other values.+.IP \[bu] 2+\f[V]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a+textual value in a block of width \f[V]n\f[R], aligned to the center,+and has no effect on other values.+.SS Variables+.SS Metadata variables+.TP+\f[V]title\f[R], \f[V]author\f[R], \f[V]date\f[R]+allow identification of basic aspects of the document.+Included in PDF metadata through LaTeX and ConTeXt.+These can be set through a pandoc title block, which allows for multiple+authors, or through a YAML metadata block:+.RS+.IP+.nf+\f[C]+---+author:+- Aristotle+- Peter Abelard+\&...+\f[R]+.fi+.PP+Note that if you just want to set PDF or HTML metadata, without+including a title block in the document itself, you can set the+\f[V]title-meta\f[R], \f[V]author-meta\f[R], and \f[V]date-meta\f[R]+variables.+(By default these are set automatically, based on \f[V]title\f[R],+\f[V]author\f[R], and \f[V]date\f[R].)+The page title in HTML is set by \f[V]pagetitle\f[R], which is equal to+\f[V]title\f[R] by default.+.RE+.TP+\f[V]subtitle\f[R]+document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx+documents+.TP+\f[V]abstract\f[R]+document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx+documents+.TP+\f[V]abstract-title\f[R]+title of abstract, currently used only in HTML and EPUB.+This will be set automatically to a localized value, depending on+\f[V]lang\f[R], but can be manually overridden.+.TP+\f[V]keywords\f[R]+list of keywords to be included in HTML, PDF, ODT, pptx, docx and+AsciiDoc metadata; repeat as for \f[V]author\f[R], above+.TP+\f[V]subject\f[R]+document subject, included in ODT, PDF, docx, EPUB, and pptx metadata+.TP+\f[V]description\f[R]+document description, included in ODT, docx and pptx metadata.+Some applications show this as \f[V]Comments\f[R] metadata.+.TP+\f[V]category\f[R]+document category, included in docx and pptx metadata+.PP+Additionally, any root-level string metadata, not included in ODT, docx+or pptx metadata is added as a \f[I]custom property\f[R].+The following YAML metadata block for instance:+.IP+.nf+\f[C]+---+title:  \[aq]This is the title\[aq]+subtitle: \[dq]This is the subtitle\[dq]+author:+- Author One+- Author Two+description: |+    This is a long+    description.++    It consists of two paragraphs+\&...+\f[R]+.fi+.PP+will include \f[V]title\f[R], \f[V]author\f[R] and \f[V]description\f[R]+as standard document properties and \f[V]subtitle\f[R] as a custom+property when converting to docx, ODT or pptx.+.SS Language variables+.TP+\f[V]lang\f[R]+identifies the main language of the document using IETF language tags+(following the BCP 47 standard), such as \f[V]en\f[R] or+\f[V]en-GB\f[R].+The Language subtag lookup tool can look up or verify these tags.+This affects most formats, and controls hyphenation in PDF output when+using LaTeX (through \f[V]babel\f[R] and \f[V]polyglossia\f[R]) or+ConTeXt.+.RS+.PP+Use native pandoc Divs and Spans with the \f[V]lang\f[R] attribute to+switch the language:+.IP+.nf+\f[C]+---+lang: en-GB+\&...++Text in the main document language (British English).++::: {lang=fr-CA}+> Cette citation est \['e]crite en fran\[,c]ais canadien.+:::++More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de}+\f[R]+.fi+.RE+.TP+\f[V]dir\f[R]+the base script direction, either \f[V]rtl\f[R] (right-to-left) or+\f[V]ltr\f[R] (left-to-right).+.RS+.PP+For bidirectional documents, native pandoc \f[V]span\f[R]s and+\f[V]div\f[R]s with the \f[V]dir\f[R] attribute (value \f[V]rtl\f[R] or+\f[V]ltr\f[R]) can be used to override the base direction in some output+formats.+This may not always be necessary if the final renderer (e.g.\ the+browser, when generating HTML) supports the Unicode Bidirectional+Algorithm.+.PP+When using LaTeX for bidirectional documents, only the \f[V]xelatex\f[R]+engine is fully supported (use \f[V]--pdf-engine=xelatex\f[R]).+.RE+.SS Variables for HTML+.TP+\f[V]document-css\f[R]+Enables inclusion of most of the CSS in the \f[V]styles.html\f[R]+partial (have a look with+\f[V]pandoc --print-default-data-file=templates/styles.html\f[R]).+Unless you use \f[V]--css\f[R], this variable is set to \f[V]true\f[R]+by default.+You can disable it with e.g.\ \f[V]pandoc -M document-css=false\f[R].+.TP+\f[V]mainfont\f[R]+sets the CSS \f[V]font-family\f[R] property on the \f[V]html\f[R]+element.+.TP+\f[V]fontsize\f[R]+sets the base CSS \f[V]font-size\f[R], which you\[cq]d usually set to+e.g.\ \f[V]20px\f[R], but it also accepts \f[V]pt\f[R] (12pt = 16px in+most browsers).+.TP+\f[V]fontcolor\f[R]+sets the CSS \f[V]color\f[R] property on the \f[V]html\f[R] element.+.TP+\f[V]linkcolor\f[R]+sets the CSS \f[V]color\f[R] property on all links.+.TP+\f[V]monofont\f[R]+sets the CSS \f[V]font-family\f[R] property on \f[V]code\f[R] elements.+.TP+\f[V]monobackgroundcolor\f[R]+sets the CSS \f[V]background-color\f[R] property on \f[V]code\f[R]+elements and adds extra padding.+.TP+\f[V]linestretch\f[R]+sets the CSS \f[V]line-height\f[R] property on the \f[V]html\f[R]+element, which is preferred to be unitless.+.TP+\f[V]backgroundcolor\f[R]+sets the CSS \f[V]background-color\f[R] property on the \f[V]html\f[R]+element.+.TP+\f[V]margin-left\f[R], \f[V]margin-right\f[R], \f[V]margin-top\f[R], \f[V]margin-bottom\f[R]+sets the corresponding CSS \f[V]padding\f[R] properties on the+\f[V]body\f[R] element.+.PP+To override or extend some CSS for just one document, include for+example:+.IP+.nf+\f[C]+---+header-includes: |+  <style>+  blockquote {+    font-style: italic;+  }+  tr.even {+    background-color: #f0f0f0;+  }+  td, th {+    padding: 0.5em 2em 0.5em 0.5em;+  }+  tbody {+    border-bottom: none;+  }+  </style>+---+\f[R]+.fi+.SS Variables for HTML math+.TP+\f[V]classoption\f[R]+when using KaTeX, you can render display math equations flush left using+YAML metadata or with \f[V]-M classoption=fleqn\f[R].+.SS Variables for HTML slides+.PP+These affect HTML output when [producing slide shows with pandoc].+.TP+\f[V]institute\f[R]+author affiliations: can be a list when there are multiple authors+.TP+\f[V]revealjs-url\f[R]+base URL for reveal.js documents (defaults to+\f[V]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R])+.TP+\f[V]s5-url\f[R]+base URL for S5 documents (defaults to \f[V]s5/default\f[R])+.TP+\f[V]slidy-url\f[R]+base URL for Slidy documents (defaults to+\f[V]https://www.w3.org/Talks/Tools/Slidy2\f[R])+.TP+\f[V]slideous-url\f[R]+base URL for Slideous documents (defaults to \f[V]slideous\f[R])+.TP+\f[V]title-slide-attributes\f[R]+additional attributes for the title slide of reveal.js slide shows.+See [background in reveal.js and beamer] for an example.+.PP+All reveal.js configuration options are available as variables.+To turn off boolean flags that default to true in reveal.js, use+\f[V]0\f[R].+.SS Variables for Beamer slides+.PP+These variables change the appearance of PDF slides using+\f[V]beamer\f[R].+.TP+\f[V]aspectratio\f[R]+slide aspect ratio (\f[V]43\f[R] for 4:3 [default], \f[V]169\f[R] for+16:9, \f[V]1610\f[R] for 16:10, \f[V]149\f[R] for 14:9, \f[V]141\f[R]+for 1.41:1, \f[V]54\f[R] for 5:4, \f[V]32\f[R] for 3:2)+.TP+\[ga]\f[V]beameroption\f[R]+add extra beamer option with \f[V]\[rs]setbeameroption{}\f[R]+.TP+\f[V]institute\f[R]+author affiliations: can be a list when there are multiple authors+.TP+\f[V]logo\f[R]+logo image for slides+.TP+\f[V]navigation\f[R]+controls navigation symbols (default is \f[V]empty\f[R] for no+navigation symbols; other valid values are \f[V]frame\f[R],+\f[V]vertical\f[R], and \f[V]horizontal\f[R])+.TP+\f[V]section-titles\f[R]+enables \[lq]title pages\[rq] for new sections (default is true)+.TP+\f[V]theme\f[R], \f[V]colortheme\f[R], \f[V]fonttheme\f[R], \f[V]innertheme\f[R], \f[V]outertheme\f[R]+beamer themes+.TP+\f[V]themeoptions\f[R]+options for LaTeX beamer themes (a list).+.TP+\f[V]titlegraphic\f[R]+image for title slide+.SS Variables for PowerPoint+.PP+These variables control the visual aspects of a slide show that are not+easily controlled via templates.+.TP+\f[V]monofont\f[R]+font to use for code.+.SS Variables for LaTeX+.PP+Pandoc uses these variables when creating a PDF with a LaTeX engine.+.SS Layout+.TP+\f[V]block-headings\f[R]+make \f[V]\[rs]paragraph\f[R] and \f[V]\[rs]subparagraph\f[R] (fourth-+and fifth-level headings, or fifth- and sixth-level with book classes)+free-standing rather than run-in; requires further formatting to+distinguish from \f[V]\[rs]subsubsection\f[R] (third- or fourth-level+headings).+Instead of using this option, KOMA-Script can adjust headings more+extensively:+.RS+.IP+.nf+\f[C]+---+documentclass: scrartcl+header-includes: |+  \[rs]RedeclareSectionCommand[+    beforeskip=-10pt plus -2pt minus -1pt,+    afterskip=1sp plus -1sp minus 1sp,+    font=\[rs]normalfont\[rs]itshape]{paragraph}+  \[rs]RedeclareSectionCommand[+    beforeskip=-10pt plus -2pt minus -1pt,+    afterskip=1sp plus -1sp minus 1sp,+    font=\[rs]normalfont\[rs]scshape,+    indent=0pt]{subparagraph}+\&...+\f[R]+.fi+.RE+.TP+\f[V]classoption\f[R]+option for document class, e.g.\ \f[V]oneside\f[R]; repeat for multiple+options:+.RS+.IP+.nf+\f[C]+---+classoption:+- twocolumn+- landscape+\&...+\f[R]+.fi+.RE+.TP+\f[V]documentclass\f[R]+document class: usually one of the standard classes, \f[V]article\f[R],+\f[V]book\f[R], and \f[V]report\f[R]; the KOMA-Script equivalents,+\f[V]scrartcl\f[R], \f[V]scrbook\f[R], and \f[V]scrreprt\f[R], which+default to smaller margins; or \f[V]memoir\f[R]+.TP+\f[V]geometry\f[R]+option for \f[V]geometry\f[R] package, e.g.\ \f[V]margin=1in\f[R];+repeat for multiple options:+.RS+.IP+.nf+\f[C]+---+geometry:+- top=30mm+- left=20mm+- heightrounded+\&...+\f[R]+.fi+.RE+.TP+\f[V]hyperrefoptions\f[R]+option for \f[V]hyperref\f[R] package, e.g.\ \f[V]linktoc=all\f[R];+repeat for multiple options:+.RS+.IP+.nf+\f[C]+---+hyperrefoptions:+- linktoc=all+- pdfwindowui+- pdfpagemode=FullScreen+\&...+\f[R]+.fi+.RE+.TP+\f[V]indent\f[R]+if true, pandoc will use document class settings for indentation (the+default LaTeX template otherwise removes indentation and adds space+between paragraphs)+.TP+\f[V]linestretch\f[R]+adjusts line spacing using the \f[V]setspace\f[R] package,+e.g.\ \f[V]1.25\f[R], \f[V]1.5\f[R]+.TP+\f[V]margin-left\f[R], \f[V]margin-right\f[R], \f[V]margin-top\f[R], \f[V]margin-bottom\f[R]+sets margins if \f[V]geometry\f[R] is not used (otherwise+\f[V]geometry\f[R] overrides these)+.TP+\f[V]pagestyle\f[R]+control \f[V]\[rs]pagestyle{}\f[R]: the default article class supports+\f[V]plain\f[R] (default), \f[V]empty\f[R] (no running heads or page+numbers), and \f[V]headings\f[R] (section titles in running heads)+.TP+\f[V]papersize\f[R]+paper size, e.g.\ \f[V]letter\f[R], \f[V]a4\f[R]+.TP+\f[V]secnumdepth\f[R]+numbering depth for sections (with \f[V]--number-sections\f[R] option or+\f[V]numbersections\f[R] variable)+.TP+\f[V]beamerarticle\f[R]+produce an article from Beamer slides+.SS Fonts+.TP+\f[V]fontenc\f[R]+allows font encoding to be specified through \f[V]fontenc\f[R] package+(with \f[V]pdflatex\f[R]); default is \f[V]T1\f[R] (see LaTeX font+encodings guide)+.TP+\f[V]fontfamily\f[R]+font package for use with \f[V]pdflatex\f[R]: TeX Live includes many+options, documented in the LaTeX Font Catalogue.+The default is Latin Modern.+.TP+\f[V]fontfamilyoptions\f[R]+options for package used as \f[V]fontfamily\f[R]; repeat for multiple+options.+For example, to use the Libertine font with proportional lowercase+(old-style) figures through the \f[V]libertinus\f[R] package:+.RS+.IP+.nf+\f[C]+---+fontfamily: libertinus+fontfamilyoptions:+- osf+- p+\&...+\f[R]+.fi+.RE+.TP+\f[V]fontsize\f[R]+font size for body text.+The standard classes allow 10pt, 11pt, and 12pt.+To use another size, set \f[V]documentclass\f[R] to one of the+KOMA-Script classes, such as \f[V]scrartcl\f[R] or \f[V]scrbook\f[R].+.TP+\f[V]mainfont\f[R], \f[V]sansfont\f[R], \f[V]monofont\f[R], \f[V]mathfont\f[R], \f[V]CJKmainfont\f[R]+font families for use with \f[V]xelatex\f[R] or \f[V]lualatex\f[R]: take+the name of any system font, using the \f[V]fontspec\f[R] package.+\f[V]CJKmainfont\f[R] uses the \f[V]xecjk\f[R] package.+.TP+\f[V]mainfontoptions\f[R], \f[V]sansfontoptions\f[R], \f[V]monofontoptions\f[R], \f[V]mathfontoptions\f[R], \f[V]CJKoptions\f[R]+options to use with \f[V]mainfont\f[R], \f[V]sansfont\f[R],+\f[V]monofont\f[R], \f[V]mathfont\f[R], \f[V]CJKmainfont\f[R] in+\f[V]xelatex\f[R] and \f[V]lualatex\f[R].+Allow for any choices available through \f[V]fontspec\f[R]; repeat for+multiple options.+For example, to use the TeX Gyre version of Palatino with lowercase+figures:+.RS+.IP+.nf+\f[C]+---+mainfont: TeX Gyre Pagella+mainfontoptions:+- Numbers=Lowercase+- Numbers=Proportional+\&...+\f[R]+.fi+.RE+.TP+\f[V]microtypeoptions\f[R]+options to pass to the microtype package+.SS Links+.TP+\f[V]colorlinks\f[R]+add color to link text; automatically enabled if any of+\f[V]linkcolor\f[R], \f[V]filecolor\f[R], \f[V]citecolor\f[R],+\f[V]urlcolor\f[R], or \f[V]toccolor\f[R] are set+.TP+\f[V]linkcolor\f[R], \f[V]filecolor\f[R], \f[V]citecolor\f[R], \f[V]urlcolor\f[R], \f[V]toccolor\f[R]+color for internal links, external links, citation links, linked URLs,+and links in table of contents, respectively: uses options allowed by+\f[V]xcolor\f[R], including the \f[V]dvipsnames\f[R],+\f[V]svgnames\f[R], and \f[V]x11names\f[R] lists+.TP+\f[V]links-as-notes\f[R]+causes links to be printed as footnotes+.SS Front matter+.TP+\f[V]lof\f[R], \f[V]lot\f[R]+include list of figures, list of tables+.TP+\f[V]thanks\f[R]+contents of acknowledgments footnote after document title+.TP+\f[V]toc\f[R]+include table of contents (can also be set using+\f[V]--toc/--table-of-contents\f[R])+.TP+\f[V]toc-depth\f[R]+level of section to include in table of contents+.SS BibLaTeX Bibliographies+.PP+These variables function when using BibLaTeX for citation rendering.+.TP+\f[V]biblatexoptions\f[R]+list of options for biblatex+.TP+\f[V]biblio-style\f[R]+bibliography style, when used with \f[V]--natbib\f[R] and+\f[V]--biblatex\f[R].+.TP+\f[V]biblio-title\f[R]+bibliography title, when used with \f[V]--natbib\f[R] and+\f[V]--biblatex\f[R].+.TP+\f[V]bibliography\f[R]+bibliography to use for resolving references+.TP+\f[V]natbiboptions\f[R]+list of options for natbib+.SS Variables for ConTeXt+.PP+Pandoc uses these variables when creating a PDF with ConTeXt.+.TP+\f[V]fontsize\f[R]+font size for body text (e.g.\ \f[V]10pt\f[R], \f[V]12pt\f[R])+.TP+\f[V]headertext\f[R], \f[V]footertext\f[R]+text to be placed in running header or footer (see ConTeXt Headers and+Footers); repeat up to four times for different placement+.TP+\f[V]indenting\f[R]+controls indentation of paragraphs, e.g.\ \f[V]yes,small,next\f[R] (see+ConTeXt Indentation); repeat for multiple options+.TP+\f[V]interlinespace\f[R]+adjusts line spacing, e.g.\ \f[V]4ex\f[R] (using+\f[V]setupinterlinespace\f[R]); repeat for multiple options+.TP+\f[V]layout\f[R]+options for page margins and text arrangement (see ConTeXt Layout);+repeat for multiple options+.TP+\f[V]linkcolor\f[R], \f[V]contrastcolor\f[R]+color for links outside and inside a page, e.g.\ \f[V]red\f[R],+\f[V]blue\f[R] (see ConTeXt Color)+.TP+\f[V]linkstyle\f[R]+typeface style for links, e.g.\ \f[V]normal\f[R], \f[V]bold\f[R],+\f[V]slanted\f[R], \f[V]boldslanted\f[R], \f[V]type\f[R], \f[V]cap\f[R],+\f[V]small\f[R]+.TP+\f[V]lof\f[R], \f[V]lot\f[R]+include list of figures, list of tables+.TP+\f[V]mainfont\f[R], \f[V]sansfont\f[R], \f[V]monofont\f[R], \f[V]mathfont\f[R]+font families: take the name of any system font (see ConTeXt Font+Switching)+.TP+\f[V]margin-left\f[R], \f[V]margin-right\f[R], \f[V]margin-top\f[R], \f[V]margin-bottom\f[R]+sets margins, if \f[V]layout\f[R] is not used (otherwise+\f[V]layout\f[R] overrides these)+.TP+\f[V]pagenumbering\f[R]+page number style and location (using \f[V]setuppagenumbering\f[R]);+repeat for multiple options+.TP+\f[V]papersize\f[R]+paper size, e.g.\ \f[V]letter\f[R], \f[V]A4\f[R], \f[V]landscape\f[R]+(see ConTeXt Paper Setup); repeat for multiple options+.TP+\f[V]pdfa\f[R]+adds to the preamble the setup necessary to generate PDF/A of the type+specified, e.g.\ \f[V]1a:2005\f[R], \f[V]2a\f[R].+If no type is specified (i.e.\ the value is set to True, by e.g.+\f[V]--metadata=pdfa\f[R] or \f[V]pdfa: true\f[R] in a YAML metadata+block), \f[V]1b:2005\f[R] will be used as default, for reasons of+backwards compatibility.+Using \f[V]--variable=pdfa\f[R] without specified value is not+supported.+To successfully generate PDF/A the required ICC color profiles have to+be available and the content and all included files (such as images)+have to be standard conforming.+The ICC profiles and output intent may be specified using the variables+\f[V]pdfaiccprofile\f[R] and \f[V]pdfaintent\f[R].+See also ConTeXt PDFA for more details.+.TP+\f[V]pdfaiccprofile\f[R]+when used in conjunction with \f[V]pdfa\f[R], specifies the ICC profile+to use in the PDF, e.g.\ \f[V]default.cmyk\f[R].+If left unspecified, \f[V]sRGB.icc\f[R] is used as default.+May be repeated to include multiple profiles.+Note that the profiles have to be available on the system.+They can be obtained from ConTeXt ICC Profiles.+.TP+\f[V]pdfaintent\f[R]+when used in conjunction with \f[V]pdfa\f[R], specifies the output+intent for the colors,+e.g.\ \f[V]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If+left unspecified, \f[V]sRGB IEC61966-2.1\f[R] is used as default.+.TP+\f[V]toc\f[R]+include table of contents (can also be set using+\f[V]--toc/--table-of-contents\f[R])+.TP+\f[V]whitespace\f[R]+spacing between paragraphs, e.g.\ \f[V]none\f[R], \f[V]small\f[R] (using+\f[V]setupwhitespace\f[R])+.TP+\f[V]includesource\f[R]+include all source documents as file attachments in the PDF file+.SS Variables for \f[V]wkhtmltopdf\f[R]+.PP+Pandoc uses these variables when creating a PDF with+\f[V]wkhtmltopdf\f[R].+The \f[V]--css\f[R] option also affects the output.+.TP+\f[V]footer-html\f[R], \f[V]header-html\f[R]+add information to the header and footer+.TP+\f[V]margin-left\f[R], \f[V]margin-right\f[R], \f[V]margin-top\f[R], \f[V]margin-bottom\f[R]+set the page margins+.TP+\f[V]papersize\f[R]+sets the PDF paper size+.SS Variables for man pages+.TP+\f[V]adjusting\f[R]+adjusts text to left (\f[V]l\f[R]), right (\f[V]r\f[R]), center+(\f[V]c\f[R]), or both (\f[V]b\f[R]) margins+.TP+\f[V]footer\f[R]+footer in man pages+.TP+\f[V]header\f[R]+header in man pages+.TP+\f[V]hyphenate\f[R]+if \f[V]true\f[R] (the default), hyphenation will be used+.TP+\f[V]section\f[R]+section number in man pages+.SS Variables for ms+.TP+\f[V]fontfamily\f[R]+font family (e.g.\ \f[V]T\f[R] or \f[V]P\f[R])+.TP+\f[V]indent\f[R]+paragraph indent (e.g.\ \f[V]2m\f[R])+.TP+\f[V]lineheight\f[R]+line height (e.g.\ \f[V]12p\f[R])+.TP+\f[V]pointsize\f[R]+point size (e.g.\ \f[V]10p\f[R])+.SS Variables set automatically+.PP+Pandoc sets these variables automatically in response to options or+document contents; users can also modify them.+These vary depending on the output format, and include the following:+.TP+\f[V]body\f[R]+body of document+.TP+\f[V]date-meta\f[R]+the \f[V]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included+in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,+s5, slideous, slidy).+The recognized formats for \f[V]date\f[R] are: \f[V]mm/dd/yyyy\f[R],+\f[V]mm/dd/yy\f[R], \f[V]yyyy-mm-dd\f[R] (ISO 8601),+\f[V]dd MM yyyy\f[R] (e.g.\ either \f[V]02 Apr 2018\f[R] or+\f[V]02 April 2018\f[R]), \f[V]MM dd, yyyy\f[R]+(e.g.\ \f[V]Apr. 02, 2018\f[R] or+\f[V]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[V](e.g.\f[R]20180402,+\f[V]201804\f[R] or \f[V]2018\f[R]).+.TP+\f[V]header-includes\f[R]+contents specified by \f[V]-H/--include-in-header\f[R] (may have+multiple values)+.TP+\f[V]include-before\f[R]+contents specified by \f[V]-B/--include-before-body\f[R] (may have+multiple values)+.TP+\f[V]include-after\f[R]+contents specified by \f[V]-A/--include-after-body\f[R] (may have+multiple values)+.TP+\f[V]meta-json\f[R]+JSON representation of all of the document\[cq]s metadata.+Field values are transformed to the selected output format.+.TP+\f[V]numbersections\f[R]+non-null value if \f[V]-N/--number-sections\f[R] was specified+.TP+\f[V]sourcefile\f[R], \f[V]outputfile\f[R]+source and destination filenames, as given on the command line.+\f[V]sourcefile\f[R] can also be a list if input comes from multiple+files, or empty if input is from stdin.+You can use the following snippet in your template to distinguish them:+.RS+.IP+.nf+\f[C]+$if(sourcefile)$+$for(sourcefile)$+$sourcefile$+$endfor$+$else$+(stdin)+$endif$+\f[R]+.fi+.PP+Similarly, \f[V]outputfile\f[R] can be \f[V]-\f[R] if output goes to the+terminal.+.PP+If you need absolute paths, use e.g.\ \f[V]$curdir$/$sourcefile$\f[R].+.RE+.TP+\f[V]curdir\f[R]+working directory from which pandoc is run.+.TP+\f[V]toc\f[R]+non-null value if \f[V]--toc/--table-of-contents\f[R] was specified+.TP+\f[V]toc-title\f[R]+title of table of contents (works only with EPUB, HTML, revealjs,+opendocument, odt, docx, pptx, beamer, LaTeX)+.SH EXTENSIONS+.PP+The behavior of some of the readers and writers can be adjusted by+enabling or disabling various extensions.+.PP+An extension can be enabled by adding \f[V]+EXTENSION\f[R] to the format+name and disabled by adding \f[V]-EXTENSION\f[R].+For example, \f[V]--from markdown_strict+footnotes\f[R] is strict+Markdown with footnotes enabled, while+\f[V]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s Markdown+without footnotes or pipe tables.+.PP+The markdown reader and writer make by far the most use of extensions.+Extensions only used by them are therefore covered in the section+Pandoc\[cq]s Markdown below (See Markdown variants for+\f[V]commonmark\f[R] and \f[V]gfm\f[R].)+In the following, extensions that also work for other formats are+covered.+.PP+Note that markdown extensions added to the \f[V]ipynb\f[R] format affect+Markdown cells in Jupyter notebooks (as do command-line options like+\f[V]--atx-headers\f[R]).+.SS Typography+.SS Extension: \f[V]smart\f[R]+.PP+Interpret straight quotes as curly quotes, \f[V]---\f[R] as em-dashes,+\f[V]--\f[R] as en-dashes, and \f[V]...\f[R] as ellipses.+Nonbreaking spaces are inserted after certain abbreviations, such as+\[lq]Mr.\[rq]+.PP+This extension can be enabled/disabled for the following formats:+.TP+input formats+\f[V]markdown\f[R], \f[V]commonmark\f[R], \f[V]latex\f[R],+\f[V]mediawiki\f[R], \f[V]org\f[R], \f[V]rst\f[R], \f[V]twiki\f[R]+.TP+output formats+\f[V]markdown\f[R], \f[V]latex\f[R], \f[V]context\f[R], \f[V]rst\f[R]+.TP+enabled by default in+\f[V]markdown\f[R], \f[V]latex\f[R], \f[V]context\f[R] (both input and+output)+.PP+Note: If you are \f[I]writing\f[R] Markdown, then the \f[V]smart\f[R]+extension has the reverse effect: what would have been curly quotes+comes out straight.+.PP+In LaTeX, \f[V]smart\f[R] means to use the standard TeX ligatures for+quotation marks (\f[V]\[ga]\[ga]\f[R] and \f[V]\[aq]\[aq]\f[R] for+double quotes, \f[V]\[ga]\f[R] and \f[V]\[aq]\f[R] for single quotes)+and dashes (\f[V]--\f[R] for en-dash and \f[V]---\f[R] for em-dash).+If \f[V]smart\f[R] is disabled, then in reading LaTeX pandoc will parse+these characters literally.+In writing LaTeX, enabling \f[V]smart\f[R] tells pandoc to use the+ligatures when possible; if \f[V]smart\f[R] is disabled pandoc will use+unicode quotation mark and dash characters.+.SS Headings and sections+.SS Extension: \f[V]auto_identifiers\f[R]+.PP+A heading without an explicitly specified identifier will be+automatically assigned a unique identifier based on the heading text.+.PP+This extension can be enabled/disabled for the following formats:+.TP+input formats+\f[V]markdown\f[R], \f[V]latex\f[R], \f[V]rst\f[R], \f[V]mediawiki\f[R],+\f[V]textile\f[R]+.TP+output formats+\f[V]markdown\f[R], \f[V]muse\f[R]+.TP+enabled by default in+\f[V]markdown\f[R], \f[V]muse\f[R]+.PP+The default algorithm used to derive the identifier from the heading+text is:+.IP \[bu] 2+Remove all formatting, links, etc.+.IP \[bu] 2+Remove all footnotes.+.IP \[bu] 2+Remove all non-alphanumeric characters, except underscores, hyphens, and+periods.+.IP \[bu] 2+Replace all spaces and newlines with hyphens.+.IP \[bu] 2+Convert all alphabetic characters to lowercase.+.IP \[bu] 2+Remove everything up to the first letter (identifiers may not begin with+a number or punctuation mark).+.IP \[bu] 2+If nothing is left after this, use the identifier \f[V]section\f[R].+.PP+Thus, for example,+.PP+.TS+tab(@);+l l.+T{+Heading+T}@T{+Identifier+T}+_+T{+\f[V]Heading identifiers in HTML\f[R]+T}@T{+\f[V]heading-identifiers-in-html\f[R]+T}+T{+\f[V]Ma\[^i]tre d\[aq]h\[^o]tel\f[R]+T}@T{+\f[V]ma\[^i]tre-dh\[^o]tel\f[R]+T}+T{+\f[V]*Dogs*?--in *my* house?\f[R]+T}@T{+\f[V]dogs--in-my-house\f[R]+T}+T{+\f[V][HTML], [S5], or [RTF]?\f[R]+T}@T{+\f[V]html-s5-or-rtf\f[R]+T}+T{+\f[V]3. Applications\f[R]+T}@T{+\f[V]applications\f[R]+T}+T{+\f[V]33\f[R]+T}@T{+\f[V]section\f[R]+T}+.TE+.PP+These rules should, in most cases, allow one to determine the identifier+from the heading text.+The exception is when several headings have the same text; in this case,+the first will get an identifier as described above; the second will get+the same identifier with \f[V]-1\f[R] appended; the third with+\f[V]-2\f[R]; and so on.+.PP+(However, a different algorithm is used if+\f[V]gfm_auto_identifiers\f[R] is enabled; see below.)+.PP+These identifiers are used to provide link targets in the table of+contents generated by the \f[V]--toc|--table-of-contents\f[R] option.+They also make it easy to provide links from one section of a document+to another.+A link to this section, for example, might look like this:+.IP+.nf+\f[C]+See the section on+[heading identifiers](#heading-identifiers-in-html-latex-and-context).+\f[R]+.fi+.PP+Note, however, that this method of providing links to sections works+only in HTML, LaTeX, and ConTeXt formats.+.PP+If the \f[V]--section-divs\f[R] option is specified, then each section+will be wrapped in a \f[V]section\f[R] (or a \f[V]div\f[R], if+\f[V]html4\f[R] was specified), and the identifier will be attached to+the enclosing \f[V]<section>\f[R] (or \f[V]<div>\f[R]) tag rather than+the heading itself.+This allows entire sections to be manipulated using JavaScript or+treated differently in CSS.+.SS Extension: \f[V]ascii_identifiers\f[R]+.PP+Causes the identifiers produced by \f[V]auto_identifiers\f[R] to be pure+ASCII.+Accents are stripped off of accented Latin letters, and non-Latin+letters are omitted.+.SS Extension: \f[V]gfm_auto_identifiers\f[R]+.PP+Changes the algorithm used by \f[V]auto_identifiers\f[R] to conform to+GitHub\[cq]s method.+Spaces are converted to dashes (\f[V]-\f[R]), uppercase characters to+lowercase characters, and punctuation characters other than \f[V]-\f[R]+and \f[V]_\f[R] are removed.+Emojis are replaced by their names.+.SS Math Input+.PP+The extensions \f[V]tex_math_dollars\f[R],+\f[V]tex_math_single_backslash\f[R], and+\f[V]tex_math_double_backslash\f[R] are described in the section about+Pandoc\[cq]s Markdown.+.PP+However, they can also be used with HTML input.+This is handy for reading web pages formatted using MathJax, for+example.+.SS Raw HTML/TeX+.PP+The following extensions are described in more detail in their+respective sections of Pandoc\[cq]s Markdown:+.IP \[bu] 2+\f[V]raw_html\f[R] allows HTML elements which are not representable in+pandoc\[cq]s AST to be parsed as raw HTML.+By default, this is disabled for HTML input.+.IP \[bu] 2+\f[V]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a+document.+This extension can be enabled/disabled for the following formats (in+addition to \f[V]markdown\f[R]):+.RS 2+.TP+input formats+\f[V]latex\f[R], \f[V]textile\f[R], \f[V]html\f[R] (environments,+\f[V]\[rs]ref\f[R], and \f[V]\[rs]eqref\f[R] only), \f[V]ipynb\f[R]+.TP+output formats+\f[V]textile\f[R], \f[V]commonmark\f[R]+.PP+Note: as applied to \f[V]ipynb\f[R], \f[V]raw_html\f[R] and+\f[V]raw_tex\f[R] affect not only raw TeX in markdown cells, but data+with mime type \f[V]text/html\f[R] in output cells.+Since the \f[V]ipynb\f[R] reader attempts to preserve the richest+possible outputs when several options are given, you will get best+results if you disable \f[V]raw_html\f[R] and \f[V]raw_tex\f[R] when+converting to formats like \f[V]docx\f[R] which don\[cq]t allow raw+\f[V]html\f[R] or \f[V]tex\f[R].+.RE+.IP \[bu] 2+\f[V]native_divs\f[R] causes HTML \f[V]div\f[R] elements to be parsed as+native pandoc Div blocks.+If you want them to be parsed as raw HTML, use+\f[V]-f html-native_divs+raw_html\f[R].+.IP \[bu] 2+\f[V]native_spans\f[R] causes HTML \f[V]span\f[R] elements to be parsed+as native pandoc Span inlines.+If you want them to be parsed as raw HTML, use+\f[V]-f html-native_spans+raw_html\f[R].+If you want to drop all \f[V]div\f[R]s and \f[V]span\f[R]s when+converting HTML to Markdown, you can use+\f[V]pandoc -f html-native_divs-native_spans -t markdown\f[R].+.SS Literate Haskell support+.SS Extension: \f[V]literate_haskell\f[R]+.PP+Treat the document as literate Haskell source.+.PP+This extension can be enabled/disabled for the following formats:+.TP+input formats+\f[V]markdown\f[R], \f[V]rst\f[R], \f[V]latex\f[R]+.TP+output formats+\f[V]markdown\f[R], \f[V]rst\f[R], \f[V]latex\f[R], \f[V]html\f[R]+.PP+If you append \f[V]+lhs\f[R] (or \f[V]+literate_haskell\f[R]) to one of+the formats above, pandoc will treat the document as literate Haskell+source.+This means that+.IP \[bu] 2+In Markdown input, \[lq]bird track\[rq] sections will be parsed as+Haskell code rather than block quotations.+Text between \f[V]\[rs]begin{code}\f[R] and \f[V]\[rs]end{code}\f[R]+will also be treated as Haskell code.+For ATX-style headings the character `=' will be used instead of `#'.+.IP \[bu] 2+In Markdown output, code blocks with classes \f[V]haskell\f[R] and+\f[V]literate\f[R] will be rendered using bird tracks, and block+quotations will be indented one space, so they will not be treated as+Haskell code.+In addition, headings will be rendered setext-style (with underlines)+rather than ATX-style (with `#' characters).+(This is because ghc treats `#' characters in column 1 as introducing+line numbers.)+.IP \[bu] 2+In restructured text input, \[lq]bird track\[rq] sections will be parsed+as Haskell code.+.IP \[bu] 2+In restructured text output, code blocks with class \f[V]haskell\f[R]+will be rendered using bird tracks.+.IP \[bu] 2+In LaTeX input, text in \f[V]code\f[R] environments will be parsed as+Haskell code.+.IP \[bu] 2+In LaTeX output, code blocks with class \f[V]haskell\f[R] will be+rendered inside \f[V]code\f[R] environments.+.IP \[bu] 2+In HTML output, code blocks with class \f[V]haskell\f[R] will be+rendered with class \f[V]literatehaskell\f[R] and bird tracks.+.PP+Examples:+.IP+.nf+\f[C]+pandoc -f markdown+lhs -t html+\f[R]+.fi+.PP+reads literate Haskell source formatted with Markdown conventions and+writes ordinary HTML (without bird tracks).+.IP+.nf+\f[C]+pandoc -f markdown+lhs -t html+lhs+\f[R]+.fi+.PP+writes HTML with the Haskell code in bird tracks, so it can be copied+and pasted as literate Haskell source.+.PP+Note that GHC expects the bird tracks in the first column, so indented+literate code blocks (e.g.\ inside an itemized environment) will not be+picked up by the Haskell compiler.+.SS Other extensions+.SS Extension: \f[V]empty_paragraphs\f[R]+.PP+Allows empty paragraphs.+By default empty paragraphs are omitted.+.PP+This extension can be enabled/disabled for the following formats:+.TP+input formats+\f[V]docx\f[R], \f[V]html\f[R]+.TP+output formats+\f[V]docx\f[R], \f[V]odt\f[R], \f[V]opendocument\f[R], \f[V]html\f[R]+.SS Extension: \f[V]native_numbering\f[R]+.PP+Enables native numbering of figures and tables.+Enumeration starts at 1.+.PP+This extension can be enabled/disabled for the following formats:+.TP+output formats+\f[V]odt\f[R], \f[V]opendocument\f[R], \f[V]docx\f[R]+.SS Extension: \f[V]xrefs_name\f[R]+.PP+Links to headings, figures and tables inside the document are+substituted with cross-references that will use the name or caption of+the referenced item.+The original link text is replaced once the generated document is+refreshed.+This extension can be combined with \f[V]xrefs_number\f[R] in which case+numbers will appear before the name.+.PP+Text in cross-references is only made consistent with the referenced+item once the document has been refreshed.+.PP+This extension can be enabled/disabled for the following formats:+.TP+output formats+\f[V]odt\f[R], \f[V]opendocument\f[R]+.SS Extension: \f[V]xrefs_number\f[R]+.PP+Links to headings, figures and tables inside the document are+substituted with cross-references that will use the number of the+referenced item.+The original link text is discarded.+This extension can be combined with \f[V]xrefs_name\f[R] in which case+the name or caption numbers will appear after the number.+.PP+For the \f[V]xrefs_number\f[R] to be useful heading numbers must be+enabled in the generated document, also table and figure captions must+be enabled using for example the \f[V]native_numbering\f[R] extension.+.PP+Numbers in cross-references are only visible in the final document once+it has been refreshed.+.PP+This extension can be enabled/disabled for the following formats:+.TP+output formats+\f[V]odt\f[R], \f[V]opendocument\f[R]+.SS Extension: \f[V]styles\f[R]+.PP+When converting from docx, read all docx styles as divs (for paragraph+styles) and spans (for character styles) regardless of whether pandoc+understands the meaning of these styles.+This can be used with docx custom styles.+Disabled by default.+.TP+input formats+\f[V]docx\f[R]+.SS Extension: \f[V]amuse\f[R]+.PP+In the \f[V]muse\f[R] input format, this enables Text::Amuse extensions+to Emacs Muse markup.+.SS Extension: \f[V]raw_markdown\f[R]+.PP+In the \f[V]ipynb\f[R] input format, this causes Markdown cells to be+included as raw Markdown blocks (allowing lossless round-tripping)+rather than being parsed.+Use this only when you are targeting \f[V]ipynb\f[R] or a markdown-based+output format.+.SS Extension: \f[V]citations\f[R]+.PP+Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted+in \f[V]org\f[R] input.+.SS Extension: \f[V]fancy_lists\f[R]+.PP+Some aspects of Pandoc\[cq]s Markdown fancy lists are also accepted in+\f[V]org\f[R] input, mimicking the option+\f[V]org-list-allow-alphabetical\f[R] in Emacs.+As in Org Mode, enabling this extension allows lowercase and uppercase+alphabetical markers for ordered lists to be parsed in addition to+arabic ones.+Note that for Org, this does not include roman numerals or the+\f[V]#\f[R] placeholder that are enabled by the extension in+Pandoc\[cq]s Markdown.+.SS Extension: \f[V]element_citations\f[R]+.PP+In the \f[V]jats\f[R] output formats, this causes reference items to be+replaced with \f[V]<element-citation>\f[R] elements.+These elements are not influenced by CSL styles, but all information on+the item is included in tags.+.SS Extension: \f[V]ntb\f[R]+.PP+In the \f[V]context\f[R] output format this enables the use of Natural+Tables (TABLE) instead of the default Extreme Tables (xtables).+Natural tables allow more fine-grained global customization but come at+a performance penalty compared to extreme tables.+.SH PANDOC\[cq]S MARKDOWN+.PP+Pandoc understands an extended and slightly revised version of John+Gruber\[cq]s Markdown syntax.+This document explains the syntax, noting differences from original+Markdown.+Except where noted, these differences can be suppressed by using the+\f[V]markdown_strict\f[R] format instead of \f[V]markdown\f[R].+Extensions can be enabled or disabled to specify the behavior more+granularly.+They are described in the following.+See also Extensions above, for extensions that work also on other+formats.+.SS Philosophy+.PP+Markdown is designed to be easy to write, and, even more importantly,+easy to read:+.RS+.PP+A Markdown-formatted document should be publishable as-is, as plain+text, without looking like it\[cq]s been marked up with tags or+formatting instructions.+\[en] John Gruber+.RE+.PP+This principle has guided pandoc\[cq]s decisions in finding syntax for+tables, footnotes, and other extensions.+.PP+There is, however, one respect in which pandoc\[cq]s aims are different+from the original aims of Markdown.+Whereas Markdown was originally designed with HTML generation in mind,+pandoc is designed for multiple output formats.+Thus, while pandoc allows the embedding of raw HTML, it discourages it,+and provides other, non-HTMLish ways of representing important document+elements like definition lists, tables, mathematics, and footnotes.+.SS Paragraphs+.PP+A paragraph is one or more lines of text followed by one or more blank+lines.+Newlines are treated as spaces, so you can reflow your paragraphs as you+like.+If you need a hard line break, put two or more spaces at the end of a+line.+.SS Extension: \f[V]escaped_line_breaks\f[R]+.PP+A backslash followed by a newline is also a hard line break.+Note: in multiline and grid table cells, this is the only way to create+a hard line break, since trailing spaces in the cells are ignored.+.SS Headings+.PP+There are two kinds of headings: Setext and ATX.+.SS Setext-style headings+.PP+A setext-style heading is a line of text \[lq]underlined\[rq] with a row+of \f[V]=\f[R] signs (for a level-one heading) or \f[V]-\f[R] signs (for+a level-two heading):+.IP+.nf+\f[C]+A level-one heading+===================++A level-two heading+-------------------+\f[R]+.fi+.PP+The heading text can contain inline formatting, such as emphasis (see+Inline formatting, below).+.SS ATX-style headings+.PP+An ATX-style heading consists of one to six \f[V]#\f[R] signs and a line+of text, optionally followed by any number of \f[V]#\f[R] signs.+The number of \f[V]#\f[R] signs at the beginning of the line is the+heading level:+.IP+.nf+\f[C]+## A level-two heading++### A level-three heading ###+\f[R]+.fi+.PP+As with setext-style headings, the heading text can contain formatting:+.IP+.nf+\f[C]+# A level-one heading with a [link](/url) and *emphasis*+\f[R]+.fi+.SS Extension: \f[V]blank_before_header\f[R]+.PP+Original Markdown syntax does not require a blank line before a heading.+Pandoc does require this (except, of course, at the beginning of the+document).+The reason for the requirement is that it is all too easy for a+\f[V]#\f[R] to end up at the beginning of a line by accident (perhaps+through line wrapping).+Consider, for example:+.IP+.nf+\f[C]+I like several of their flavors of ice cream:+#22, for example, and #5.+\f[R]+.fi+.SS Extension: \f[V]space_in_atx_header\f[R]+.PP+Many Markdown implementations do not require a space between the opening+\f[V]#\f[R]s of an ATX heading and the heading text, so that+\f[V]#5 bolt\f[R] and \f[V]#hashtag\f[R] count as headings.+With this extension, pandoc does require the space.+.SS Heading identifiers+.PP+See also the \f[V]auto_identifiers\f[R] extension above.+.SS Extension: \f[V]header_attributes\f[R]+.PP+Headings can be assigned attributes using this syntax at the end of the+line containing the heading text:+.IP+.nf+\f[C]+{#identifier .class .class key=value key=value}+\f[R]+.fi+.PP+Thus, for example, the following headings will all be assigned the+identifier \f[V]foo\f[R]:+.IP+.nf+\f[C]+# My heading {#foo}++## My heading ##    {#foo}++My other heading   {#foo}+---------------+\f[R]+.fi+.PP+(This syntax is compatible with PHP Markdown Extra.)+.PP+Note that although this syntax allows assignment of classes and+key/value attributes, writers generally don\[cq]t use all of this+information.+Identifiers, classes, and key/value attributes are used in HTML and+HTML-based formats such as EPUB and slidy.+Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,+Textile, Jira markup, and AsciiDoc writers.+.PP+Headings with the class \f[V]unnumbered\f[R] will not be numbered, even+if \f[V]--number-sections\f[R] is specified.+A single hyphen (\f[V]-\f[R]) in an attribute context is equivalent to+\f[V].unnumbered\f[R], and preferable in non-English documents.+So,+.IP+.nf+\f[C]+# My heading {-}+\f[R]+.fi+.PP+is just the same as+.IP+.nf+\f[C]+# My heading {.unnumbered}+\f[R]+.fi+.PP+If the \f[V]unlisted\f[R] class is present in addition to+\f[V]unnumbered\f[R], the heading will not be included in a table of+contents.+(Currently this feature is only implemented for certain formats: those+based on LaTeX and HTML, PowerPoint, and RTF.)+.SS Extension: \f[V]implicit_header_references\f[R]+.PP+Pandoc behaves as if reference links have been defined for each heading.+So, to link to a heading+.IP+.nf+\f[C]+# Heading identifiers in HTML+\f[R]+.fi+.PP+you can simply write+.IP+.nf+\f[C]+[Heading identifiers in HTML]+\f[R]+.fi+.PP+or+.IP+.nf+\f[C]+[Heading identifiers in HTML][]+\f[R]+.fi+.PP+or+.IP+.nf+\f[C]+[the section on heading identifiers][heading identifiers in+HTML]+\f[R]+.fi+.PP+instead of giving the identifier explicitly:+.IP+.nf+\f[C]+[Heading identifiers in HTML](#heading-identifiers-in-html)+\f[R]+.fi+.PP+If there are multiple headings with identical text, the corresponding+reference will link to the first one only, and you will need to use+explicit links to link to the others, as described above.+.PP+Like regular reference links, these references are case-insensitive.+.PP+Explicit link reference definitions always take priority over implicit+heading references.+So, in the following example, the link will point to \f[V]bar\f[R], not+to \f[V]#foo\f[R]:+.IP+.nf+\f[C]+# Foo++[foo]: bar++See [foo]+\f[R]+.fi+.SS Block quotations+.PP+Markdown uses email conventions for quoting blocks of text.+A block quotation is one or more paragraphs or other block elements+(such as lists or headings), with each line preceded by a \f[V]>\f[R]+character and an optional space.+(The \f[V]>\f[R] need not start at the left margin, but it should not be+indented more than three spaces.)+.IP+.nf+\f[C]+> This is a block quote. This+> paragraph has two lines.+>+> 1. This is a list inside a block quote.+> 2. Second item.+\f[R]+.fi+.PP+A \[lq]lazy\[rq] form, which requires the \f[V]>\f[R] character only on+the first line of each block, is also allowed:+.IP+.nf+\f[C]+> This is a block quote. This+paragraph has two lines.++> 1. This is a list inside a block quote.+2. Second item.+\f[R]+.fi+.PP+Among the block elements that can be contained in a block quote are+other block quotes.+That is, block quotes can be nested:+.IP+.nf+\f[C]+> This is a block quote.+>+> > A block quote within a block quote.+\f[R]+.fi+.PP+If the \f[V]>\f[R] character is followed by an optional space, that+space will be considered part of the block quote marker and not part of+the indentation of the contents.+Thus, to put an indented code block in a block quote, you need five+spaces after the \f[V]>\f[R]:+.IP+.nf+\f[C]+>     code+\f[R]+.fi+.SS Extension: \f[V]blank_before_blockquote\f[R]+.PP+Original Markdown syntax does not require a blank line before a block+quote.+Pandoc does require this (except, of course, at the beginning of the+document).+The reason for the requirement is that it is all too easy for a+\f[V]>\f[R] to end up at the beginning of a line by accident (perhaps+through line wrapping).+So, unless the \f[V]markdown_strict\f[R] format is used, the following+does not produce a nested block quote in pandoc:+.IP+.nf+\f[C]+> This is a block quote.+>> Nested.+\f[R]+.fi+.SS Verbatim (code) blocks+.SS Indented code blocks+.PP+A block of text indented four spaces (or one tab) is treated as verbatim+text: that is, special characters do not trigger special formatting, and+all spaces and line breaks are preserved.+For example,+.IP+.nf+\f[C]+    if (a > 3) {+      moveShip(5 * gravity, DOWN);+    }+\f[R]+.fi+.PP+The initial (four space or one tab) indentation is not considered part+of the verbatim text, and is removed in the output.+.PP+Note: blank lines in the verbatim text need not begin with four spaces.+.SS Fenced code blocks+.SS Extension: \f[V]fenced_code_blocks\f[R]+.PP+In addition to standard indented code blocks, pandoc supports+\f[I]fenced\f[R] code blocks.+These begin with a row of three or more tildes (\f[V]\[ti]\f[R]) and end+with a row of tildes that must be at least as long as the starting row.+Everything between these lines is treated as code.+No indentation is necessary:+.IP+.nf+\f[C]+\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]+if (a > 3) {+  moveShip(5 * gravity, DOWN);+}+\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]+\f[R]+.fi+.PP+Like regular code blocks, fenced code blocks must be separated from+surrounding text by blank lines.+.PP+If the code itself contains a row of tildes or backticks, just use a+longer row of tildes or backticks at the start and end:+.IP+.nf+\f[C]+\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]+\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]+code including tildes+\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]+\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]+\f[R]+.fi+.SS Extension: \f[V]backtick_code_blocks\f[R]+.PP+Same as \f[V]fenced_code_blocks\f[R], but uses backticks+(\f[V]\[ga]\f[R]) instead of tildes (\f[V]\[ti]\f[R]).+.SS Extension: \f[V]fenced_code_attributes\f[R]+.PP+Optionally, you may attach attributes to fenced or backtick code block+using this syntax:+.IP+.nf+\f[C]+\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]}+qsort []     = []+qsort (x:xs) = qsort (filter (< x) xs) ++ [x] +++               qsort (filter (>= x) xs)+\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]+\f[R]+.fi+.PP+Here \f[V]mycode\f[R] is an identifier, \f[V]haskell\f[R] and+\f[V]numberLines\f[R] are classes, and \f[V]startFrom\f[R] is an+attribute with value \f[V]100\f[R].+Some output formats can use this information to do syntax highlighting.+Currently, the only output formats that uses this information are HTML,+LaTeX, Docx, Ms, and PowerPoint.+If highlighting is supported for your output format and language, then+the code block above will appear highlighted, with numbered lines.+(To see which languages are supported, type+\f[V]pandoc --list-highlight-languages\f[R].)+Otherwise, the code block above will appear as follows:+.IP+.nf+\f[C]+<pre id=\[dq]mycode\[dq] class=\[dq]haskell numberLines\[dq] startFrom=\[dq]100\[dq]>+  <code>+  ...+  </code>+</pre>+\f[R]+.fi+.PP+The \f[V]numberLines\f[R] (or \f[V]number-lines\f[R]) class will cause+the lines of the code block to be numbered, starting with \f[V]1\f[R] or+the value of the \f[V]startFrom\f[R] attribute.+The \f[V]lineAnchors\f[R] (or \f[V]line-anchors\f[R]) class will cause+the lines to be clickable anchors in HTML output.+.PP+A shortcut form can also be used for specifying the language of the code+block:+.IP+.nf+\f[C]+\[ga]\[ga]\[ga]haskell+qsort [] = []+\[ga]\[ga]\[ga]+\f[R]+.fi+.PP+This is equivalent to:+.IP+.nf+\f[C]+\[ga]\[ga]\[ga] {.haskell}+qsort [] = []+\[ga]\[ga]\[ga]+\f[R]+.fi+.PP+If the \f[V]fenced_code_attributes\f[R] extension is disabled, but input+contains class attribute(s) for the code block, the first class+attribute will be printed after the opening fence as a bare word.+.PP+To prevent all highlighting, use the \f[V]--no-highlight\f[R] flag.+To set the highlighting style, use \f[V]--highlight-style\f[R].+For more information on highlighting, see Syntax highlighting, below.+.SS Line blocks+.SS Extension: \f[V]line_blocks\f[R]+.PP+A line block is a sequence of lines beginning with a vertical bar+(\f[V]|\f[R]) followed by a space.+The division into lines will be preserved in the output, as will any+leading spaces; otherwise, the lines will be formatted as Markdown.+This is useful for verse and addresses:+.IP+.nf+\f[C]+| The limerick packs laughs anatomical+| In space that is quite economical.+|    But the good ones I\[aq]ve seen+|    So seldom are clean+| And the clean ones so seldom are comical++| 200 Main St.+| Berkeley, CA 94718+\f[R]+.fi+.PP+The lines can be hard-wrapped if needed, but the continuation line must+begin with a space.+.IP+.nf+\f[C]+| The Right Honorable Most Venerable and Righteous Samuel L.+  Constable, Jr.+| 200 Main St.+| Berkeley, CA 94718+\f[R]+.fi+.PP+Inline formatting (such as emphasis) is allowed in the content, but not+block-level formatting (such as block quotes or lists).+.PP+This syntax is borrowed from reStructuredText.+.SS Lists+.SS Bullet lists+.PP+A bullet list is a list of bulleted list items.+A bulleted list item begins with a bullet (\f[V]*\f[R], \f[V]+\f[R], or+\f[V]-\f[R]).+Here is a simple example:+.IP+.nf+\f[C]+* one+* two+* three+\f[R]+.fi+.PP+This will produce a \[lq]compact\[rq] list.+If you want a \[lq]loose\[rq] list, in which each item is formatted as a+paragraph, put spaces between the items:+.IP+.nf+\f[C]+* one++* two++* three+\f[R]+.fi+.PP+The bullets need not be flush with the left margin; they may be indented+one, two, or three spaces.+The bullet must be followed by whitespace.+.PP+List items look best if subsequent lines are flush with the first line+(after the bullet):+.IP+.nf+\f[C]+* here is my first+  list item.+* and my second.+\f[R]+.fi+.PP+But Markdown also allows a \[lq]lazy\[rq] format:+.IP+.nf+\f[C]+* here is my first+list item.+* and my second.+\f[R]+.fi+.SS Block content in list items+.PP+A list item may contain multiple paragraphs and other block-level+content.+However, subsequent paragraphs must be preceded by a blank line and+indented to line up with the first non-space content after the list+marker.+.IP+.nf+\f[C]+  * First paragraph.++    Continued.++  * Second paragraph. With a code block, which must be indented+    eight spaces:++        { code }+\f[R]+.fi+.PP+Exception: if the list marker is followed by an indented code block,+which must begin 5 spaces after the list marker, then subsequent+paragraphs must begin two columns after the last character of the list+marker:+.IP+.nf+\f[C]+*     code++  continuation paragraph+\f[R]+.fi+.PP+List items may include other lists.+In this case the preceding blank line is optional.+The nested list must be indented to line up with the first non-space+character after the list marker of the containing list item.+.IP+.nf+\f[C]+* fruits+  + apples+    - macintosh+    - red delicious+  + pears+  + peaches+* vegetables+  + broccoli+  + chard+\f[R]+.fi+.PP+As noted above, Markdown allows you to write list items+\[lq]lazily,\[rq] instead of indenting continuation lines.+However, if there are multiple paragraphs or other blocks in a list+item, the first line of each must be indented.+.IP+.nf+\f[C]++ A lazy, lazy, list+item.+++ Another one; this looks+bad but is legal.++    Second paragraph of second+list item.+\f[R]+.fi+.SS Ordered lists+.PP+Ordered lists work just like bulleted lists, except that the items begin+with enumerators rather than bullets.+.PP+In original Markdown, enumerators are decimal numbers followed by a+period and a space.+The numbers themselves are ignored, so there is no difference between+this list:+.IP+.nf+\f[C]+1.  one+2.  two+3.  three+\f[R]+.fi+.PP+and this one:+.IP+.nf+\f[C]+5.  one+7.  two+1.  three+\f[R]+.fi+.SS Extension: \f[V]fancy_lists\f[R]+.PP+Unlike original Markdown, pandoc allows ordered list items to be marked+with uppercase and lowercase letters and roman numerals, in addition to+Arabic numerals.+List markers may be enclosed in parentheses or followed by a single+right-parentheses or period.+They must be separated from the text that follows by at least one space,+and, if the list marker is a capital letter with a period, by at least+two spaces.+.PP+The \f[V]fancy_lists\f[R] extension also allows `\f[V]#\f[R]' to be used+as an ordered list marker in place of a numeral:+.IP+.nf+\f[C]+#. one+#. two+\f[R]+.fi+.SS Extension: \f[V]startnum\f[R]+.PP+Pandoc also pays attention to the type of list marker used, and to the+starting number, and both of these are preserved where possible in the+output format.+Thus, the following yields a list with numbers followed by a single+parenthesis, starting with 9, and a sublist with lowercase roman+numerals:+.IP+.nf+\f[C]+ 9)  Ninth+10)  Tenth+11)  Eleventh+       i. subone+      ii. subtwo+     iii. subthree+\f[R]+.fi+.PP+Pandoc will start a new list each time a different type of list marker+is used.+So, the following will create three lists:+.IP+.nf+\f[C]+(2) Two+(5) Three+1.  Four+*   Five+\f[R]+.fi+.PP+If default list markers are desired, use \f[V]#.\f[R]:+.IP+.nf+\f[C]+#.  one+#.  two+#.  three+\f[R]+.fi+.SS Extension: \f[V]task_lists\f[R]+.PP+Pandoc supports task lists, using the syntax of GitHub-Flavored+Markdown.+.IP+.nf+\f[C]+- [ ] an unchecked task list item+- [x] checked item+\f[R]+.fi+.SS Definition lists+.SS Extension: \f[V]definition_lists\f[R]+.PP+Pandoc supports definition lists, using the syntax of PHP Markdown Extra+with some extensions.+.IP+.nf+\f[C]+Term 1++:   Definition 1++Term 2 with *inline markup*++:   Definition 2++        { some code, part of Definition 2 }++    Third paragraph of definition 2.+\f[R]+.fi+.PP+Each term must fit on one line, which may optionally be followed by a+blank line, and must be followed by one or more definitions.+A definition begins with a colon or tilde, which may be indented one or+two spaces.+.PP+A term may have multiple definitions, and each definition may consist of+one or more block elements (paragraph, code block, list, etc.), each+indented four spaces or one tab stop.+The body of the definition (not including the first line) should be+indented four spaces.+However, as with other Markdown lists, you can \[lq]lazily\[rq] omit+indentation except at the beginning of a paragraph or other block+element:+.IP+.nf+\f[C]+Term 1++:   Definition+with lazy continuation.++    Second paragraph of the definition.+\f[R]+.fi+.PP+If you leave space before the definition (as in the example above), the+text of the definition will be treated as a paragraph.+In some output formats, this will mean greater spacing between+term/definition pairs.+For a more compact definition list, omit the space before the+definition:+.IP+.nf+\f[C]+Term 1+  \[ti] Definition 1++Term 2+  \[ti] Definition 2a+  \[ti] Definition 2b+\f[R]+.fi+.PP+Note that space between items in a definition list is required.+(A variant that loosens this requirement, but disallows \[lq]lazy\[rq]+hard wrapping, can be activated with \f[V]compact_definition_lists\f[R]:+see Non-default extensions, below.)+.SS Numbered example lists+.SS Extension: \f[V]example_lists\f[R]+.PP+The special list marker \f[V]\[at]\f[R] can be used for sequentially+numbered examples.+The first list item with a \f[V]\[at]\f[R] marker will be numbered `1',+the next `2', and so on, throughout the document.+The numbered examples need not occur in a single list; each new list+using \f[V]\[at]\f[R] will take up where the last stopped.+So, for example:+.IP+.nf+\f[C]+(\[at])  My first example will be numbered (1).+(\[at])  My second example will be numbered (2).++Explanation of examples.++(\[at])  My third example will be numbered (3).+\f[R]+.fi+.PP+Numbered examples can be labeled and referred to elsewhere in the+document:+.IP+.nf+\f[C]+(\[at]good)  This is a good example.++As (\[at]good) illustrates, ...+\f[R]+.fi+.PP+The label can be any string of alphanumeric characters, underscores, or+hyphens.+.PP+Note: continuation paragraphs in example lists must always be indented+four spaces, regardless of the length of the list marker.+That is, example lists always behave as if the \f[V]four_space_rule\f[R]+extension is set.+This is because example labels tend to be long, and indenting content to+the first non-space character after the label would be awkward.+.SS Ending a list+.PP+What if you want to put an indented code block after a list?+.IP+.nf+\f[C]+-   item one+-   item two++    { my code block }+\f[R]+.fi+.PP+Trouble!+Here pandoc (like other Markdown implementations) will treat+\f[V]{ my code block }\f[R] as the second paragraph of item two, and not+as a code block.+.PP+To \[lq]cut off\[rq] the list after item two, you can insert some+non-indented content, like an HTML comment, which won\[cq]t produce+visible output in any format:+.IP+.nf+\f[C]+-   item one+-   item two++<!-- end of list -->++    { my code block }+\f[R]+.fi+.PP+You can use the same trick if you want two consecutive lists instead of+one big list:+.IP+.nf+\f[C]+1.  one+2.  two+3.  three++<!-- -->++1.  uno+2.  dos+3.  tres+\f[R]+.fi+.SS Horizontal rules+.PP+A line containing a row of three or more \f[V]*\f[R], \f[V]-\f[R], or+\f[V]_\f[R] characters (optionally separated by spaces) produces a+horizontal rule:+.IP+.nf+\f[C]+*  *  *  *++---------------+\f[R]+.fi+.SS Tables+.PP+Four kinds of tables may be used.+The first three kinds presuppose the use of a fixed-width font, such as+Courier.+The fourth kind can be used with proportionally spaced fonts, as it does+not require lining up columns.+.SS Extension: \f[V]table_captions\f[R]+.PP+A caption may optionally be provided with all 4 kinds of tables (as+illustrated in the examples below).+A caption is a paragraph beginning with the string \f[V]Table:\f[R] (or+just \f[V]:\f[R]), which will be stripped off.+It may appear either before or after the table.+.SS Extension: \f[V]simple_tables\f[R]+.PP+Simple tables look like this:+.IP+.nf+\f[C]+  Right     Left     Center     Default+-------     ------ ----------   -------+     12     12        12            12+    123     123       123          123+      1     1          1             1++Table:  Demonstration of simple table syntax.+\f[R]+.fi+.PP+The header and table rows must each fit on one line.+Column alignments are determined by the position of the header text+relative to the dashed line below it:+.IP \[bu] 2+If the dashed line is flush with the header text on the right side but+extends beyond it on the left, the column is right-aligned.+.IP \[bu] 2+If the dashed line is flush with the header text on the left side but+extends beyond it on the right, the column is left-aligned.+.IP \[bu] 2+If the dashed line extends beyond the header text on both sides, the+column is centered.+.IP \[bu] 2+If the dashed line is flush with the header text on both sides, the+default alignment is used (in most cases, this will be left).+.PP+The table must end with a blank line, or a line of dashes followed by a+blank line.+.PP+The column header row may be omitted, provided a dashed line is used to+end the table.+For example:+.IP+.nf+\f[C]+-------     ------ ----------   -------+     12     12        12             12+    123     123       123           123+      1     1          1              1+-------     ------ ----------   -------+\f[R]+.fi+.PP+When the header row is omitted, column alignments are determined on the+basis of the first line of the table body.+So, in the tables above, the columns would be right, left, center, and+right aligned, respectively.+.SS Extension: \f[V]multiline_tables\f[R]+.PP+Multiline tables allow header and table rows to span multiple lines of+text (but cells that span multiple columns or rows of the table are not+supported).+Here is an example:+.IP+.nf+\f[C]+-------------------------------------------------------------+ Centered   Default           Right Left+  Header    Aligned         Aligned Aligned+----------- ------- --------------- -------------------------+   First    row                12.0 Example of a row that+                                    spans multiple lines.++  Second    row                 5.0 Here\[aq]s another one. Note+                                    the blank line between+                                    rows.+-------------------------------------------------------------++Table: Here\[aq]s the caption. It, too, may span+multiple lines.+\f[R]+.fi+.PP+These work like simple tables, but with the following differences:+.IP \[bu] 2+They must begin with a row of dashes, before the header text (unless the+header row is omitted).+.IP \[bu] 2+They must end with a row of dashes, then a blank line.+.IP \[bu] 2+The rows must be separated by blank lines.+.PP+In multiline tables, the table parser pays attention to the widths of+the columns, and the writers try to reproduce these relative widths in+the output.+So, if you find that one of the columns is too narrow in the output, try+widening it in the Markdown source.+.PP+The header may be omitted in multiline tables as well as simple tables:+.IP+.nf+\f[C]+----------- ------- --------------- -------------------------+   First    row                12.0 Example of a row that+                                    spans multiple lines.++  Second    row                 5.0 Here\[aq]s another one. Note+                                    the blank line between+                                    rows.+----------- ------- --------------- -------------------------++: Here\[aq]s a multiline table without a header.+\f[R]+.fi+.PP+It is possible for a multiline table to have just one row, but the row+should be followed by a blank line (and then the row of dashes that ends+the table), or the table may be interpreted as a simple table.+.SS Extension: \f[V]grid_tables\f[R]+.PP+Grid tables look like this:+.IP+.nf+\f[C]+: Sample grid table.+++---------------+---------------+--------------------++| Fruit         | Price         | Advantages         |++===============+===============+====================++| Bananas       | $1.34         | - built-in wrapper |+|               |               | - bright color     |++---------------+---------------+--------------------++| Oranges       | $2.10         | - cures scurvy     |+|               |               | - tasty            |++---------------+---------------+--------------------++\f[R]+.fi+.PP+The row of \f[V]=\f[R]s separates the header from the table body, and+can be omitted for a headerless table.+The cells of grid tables may contain arbitrary block elements (multiple+paragraphs, code blocks, lists, etc.).+Cells that span multiple columns or rows are not supported.+Grid tables can be created easily using Emacs\[cq] table-mode+(\f[V]M-x table-insert\f[R]).+.PP+Alignments can be specified as with pipe tables, by putting colons at+the boundaries of the separator line after the header:+.IP+.nf+\f[C]++---------------+---------------+--------------------++| Right         | Left          | Centered           |++==============:+:==============+:==================:++| Bananas       | $1.34         | built-in wrapper   |++---------------+---------------+--------------------++\f[R]+.fi+.PP+For headerless tables, the colons go on the top line instead:+.IP+.nf+\f[C]++--------------:+:--------------+:------------------:++| Right         | Left          | Centered           |++---------------+---------------+--------------------++\f[R]+.fi+.SS Grid Table Limitations+.PP+Pandoc does not support grid tables with row spans or column spans.+This means that neither variable numbers of columns across rows nor+variable numbers of rows across columns are supported by Pandoc.+All grid tables must have the same number of columns in each row, and+the same number of rows in each column.+For example, the Docutils sample grid tables will not render as expected+with Pandoc.+.SS Extension: \f[V]pipe_tables\f[R]+.PP+Pipe tables look like this:+.IP+.nf+\f[C]+| Right | Left | Default | Center |+|------:|:-----|---------|:------:|+|   12  |  12  |    12   |    12  |+|  123  |  123 |   123   |   123  |+|    1  |    1 |     1   |     1  |++  : Demonstration of pipe table syntax.+\f[R]+.fi+.PP+The syntax is identical to PHP Markdown Extra tables.+The beginning and ending pipe characters are optional, but pipes are+required between all columns.+The colons indicate column alignment as shown.+The header cannot be omitted.+To simulate a headerless table, include a header with blank cells.+.PP+Since the pipes indicate column boundaries, columns need not be+vertically aligned, as they are in the above example.+So, this is a perfectly legal (though ugly) pipe table:+.IP+.nf+\f[C]+fruit| price+-----|-----:+apple|2.05+pear|1.37+orange|3.09+\f[R]+.fi+.PP+The cells of pipe tables cannot contain block elements like paragraphs+and lists, and cannot span multiple lines.+If any line of the markdown source is longer than the column width (see+\f[V]--columns\f[R]), then the table will take up the full text width+and the cell contents will wrap, with the relative cell widths+determined by the number of dashes in the line separating the table+header from the table body.+(For example \f[V]---|-\f[R] would make the first column 3/4 and the+second column 1/4 of the full text width.)+On the other hand, if no lines are wider than column width, then cell+contents will not be wrapped, and the cells will be sized to their+contents.+.PP+Note: pandoc also recognizes pipe tables of the following form, as can+be produced by Emacs\[cq] orgtbl-mode:+.IP+.nf+\f[C]+| One | Two   |+|-----+-------|+| my  | table |+| is  | nice  |+\f[R]+.fi+.PP+The difference is that \f[V]+\f[R] is used instead of \f[V]|\f[R].+Other orgtbl features are not supported.+In particular, to get non-default column alignment, you\[cq]ll need to+add colons as above.+.SS Metadata blocks+.SS Extension: \f[V]pandoc_title_block\f[R]+.PP+If the file begins with a title block+.IP+.nf+\f[C]+% title+% author(s) (separated by semicolons)+% date+\f[R]+.fi+.PP+it will be parsed as bibliographic information, not regular text.+(It will be used, for example, in the title of standalone LaTeX or HTML+output.)+The block may contain just a title, a title and an author, or all three+elements.+If you want to include an author but no title, or a title and a date but+no author, you need a blank line:+.IP+.nf+\f[C]+%+% Author+\f[R]+.fi+.IP+.nf+\f[C]+% My title+%+% June 15, 2006+\f[R]+.fi+.PP+The title may occupy multiple lines, but continuation lines must begin+with leading space, thus:+.IP+.nf+\f[C]+% My title+  on multiple lines+\f[R]+.fi+.PP+If a document has multiple authors, the authors may be put on separate+lines with leading space, or separated by semicolons, or both.+So, all of the following are equivalent:+.IP+.nf+\f[C]+% Author One+  Author Two+\f[R]+.fi+.IP+.nf+\f[C]+% Author One; Author Two+\f[R]+.fi+.IP+.nf+\f[C]+% Author One;+  Author Two+\f[R]+.fi+.PP+The date must fit on one line.+.PP+All three metadata fields may contain standard inline formatting+(italics, links, footnotes, etc.).+.PP+Title blocks will always be parsed, but they will affect the output only+when the \f[V]--standalone\f[R] (\f[V]-s\f[R]) option is chosen.+In HTML output, titles will appear twice: once in the document head+\[en] this is the title that will appear at the top of the window in a+browser \[en] and once at the beginning of the document body.+The title in the document head can have an optional prefix attached+(\f[V]--title-prefix\f[R] or \f[V]-T\f[R] option).+The title in the body appears as an H1 element with class+\[lq]title\[rq], so it can be suppressed or reformatted with CSS.+If a title prefix is specified with \f[V]-T\f[R] and no title block+appears in the document, the title prefix will be used by itself as the+HTML title.+.PP+The man page writer extracts a title, man page section number, and other+header and footer information from the title line.+The title is assumed to be the first word on the title line, which may+optionally end with a (single-digit) section number in parentheses.+(There should be no space between the title and the parentheses.)+Anything after this is assumed to be additional footer and header text.+A single pipe character (\f[V]|\f[R]) should be used to separate the+footer text from the header text.+Thus,+.IP+.nf+\f[C]+% PANDOC(1)+\f[R]+.fi+.PP+will yield a man page with the title \f[V]PANDOC\f[R] and section 1.+.IP+.nf+\f[C]+% PANDOC(1) Pandoc User Manuals+\f[R]+.fi+.PP+will also have \[lq]Pandoc User Manuals\[rq] in the footer.+.IP+.nf+\f[C]+% PANDOC(1) Pandoc User Manuals | Version 4.0+\f[R]+.fi+.PP+will also have \[lq]Version 4.0\[rq] in the header.+.SS Extension: \f[V]yaml_metadata_block\f[R]+.PP+A YAML metadata block is a valid YAML object, delimited by a line of+three hyphens (\f[V]---\f[R]) at the top and a line of three hyphens+(\f[V]---\f[R]) or three dots (\f[V]...\f[R]) at the bottom.+A YAML metadata block may occur anywhere in the document, but if it is+not at the beginning, it must be preceded by a blank line.+(Note that, because of the way pandoc concatenates input files when+several are provided, you may also keep the metadata in a separate YAML+file and pass it to pandoc as an argument, along with your Markdown+files:+.IP+.nf+\f[C]+pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html+\f[R]+.fi+.PP+Just be sure that the YAML file begins with \f[V]---\f[R] and ends with+\f[V]---\f[R] or \f[V]...\f[R].)+Alternatively, you can use the \f[V]--metadata-file\f[R] option.+Using that approach however, you cannot reference content (like+footnotes) from the main markdown input document.+.PP+Metadata will be taken from the fields of the YAML object and added to+any existing document metadata.+Metadata can contain lists and objects (nested arbitrarily), but all+string scalars will be interpreted as Markdown.+Fields with names ending in an underscore will be ignored by pandoc.+(They may be given a role by external processors.)+Field names must not be interpretable as YAML numbers or boolean values+(so, for example, \f[V]yes\f[R], \f[V]True\f[R], and \f[V]15\f[R] cannot+be used as field names).+.PP+A document may contain multiple metadata blocks.+If two metadata blocks attempt to set the same field, the value from the+second block will be taken.+.PP+Each metadata block is handled internally as an independent YAML+document.+This means, for example, that any YAML anchors defined in a block cannot+be referenced in another block.+.PP+When pandoc is used with \f[V]-t markdown\f[R] to create a Markdown+document, a YAML metadata block will be produced only if the+\f[V]-s/--standalone\f[R] option is used.+All of the metadata will appear in a single block at the beginning of+the document.+.PP+Note that YAML escaping rules must be followed.+Thus, for example, if a title contains a colon, it must be quoted, and+if it contains a backslash escape, then it must be ensured that it is+not treated as a YAML escape sequence.+The pipe character (\f[V]|\f[R]) can be used to begin an indented block+that will be interpreted literally, without need for escaping.+This form is necessary when the field contains blank lines or+block-level formatting:+.IP+.nf+\f[C]+---+title:  \[aq]This is the title: it contains a colon\[aq]+author:+- Author One+- Author Two+keywords: [nothing, nothingness]+abstract: |+  This is the abstract.++  It consists of two paragraphs.+\&...+\f[R]+.fi+.PP+The literal block after the \f[V]|\f[R] must be indented relative to the+line containing the \f[V]|\f[R].+If it is not, the YAML will be invalid and pandoc will not interpret it+as metadata.+For an overview of the complex rules governing YAML, see the Wikipedia+entry on YAML syntax.+.PP+Template variables will be set automatically from the metadata.+Thus, for example, in writing HTML, the variable \f[V]abstract\f[R] will+be set to the HTML equivalent of the Markdown in the \f[V]abstract\f[R]+field:+.IP+.nf+\f[C]+<p>This is the abstract.</p>+<p>It consists of two paragraphs.</p>+\f[R]+.fi+.PP+Variables can contain arbitrary YAML structures, but the template must+match this structure.+The \f[V]author\f[R] variable in the default templates expects a simple+list or string, but can be changed to support more complicated+structures.+The following combination, for example, would add an affiliation to the+author if one is given:+.IP+.nf+\f[C]+---+title: The document title+author:+- name: Author One+  affiliation: University of Somewhere+- name: Author Two+  affiliation: University of Nowhere+\&...+\f[R]+.fi+.PP+To use the structured authors in the example above, you would need a+custom template:+.IP+.nf+\f[C]+$for(author)$+$if(author.name)$+$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$+$else$+$author$+$endif$+$endfor$+\f[R]+.fi+.PP+Raw content to include in the document\[cq]s header may be specified+using \f[V]header-includes\f[R]; however, it is important to mark up+this content as raw code for a particular output format, using the+\f[V]raw_attribute\f[R] extension), or it will be interpreted as+markdown.+For example:+.IP+.nf+\f[C]+header-includes:+- |+  \[ga]\[ga]\[ga]{=latex}+  \[rs]let\[rs]oldsection\[rs]section+  \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}}+  \[ga]\[ga]\[ga]+\f[R]+.fi+.PP+Note: the \f[V]yaml_metadata_block\f[R] extension works with+\f[V]commonmark\f[R] as well as \f[V]markdown\f[R] (and it is enabled by+default in \f[V]gfm\f[R] and \f[V]commonmark_x\f[R]).+However, in these formats the following restrictions apply:+.IP \[bu] 2+The YAML metadata block must occur at the beginning of the document (and+there can be only one).+If multiple files are given as arguments to pandoc, only the first can+be a YAML metadata block.+.IP \[bu] 2+The leaf nodes of the YAML structure are parsed in isolation from each+other and from the rest of the document.+So, for example, you can\[cq]t use a reference link in these contexts if+the link definition is somewhere else in the document.+.SS Backslash escapes+.SS Extension: \f[V]all_symbols_escapable\f[R]+.PP+Except inside a code block or inline code, any punctuation or space+character preceded by a backslash will be treated literally, even if it+would normally indicate formatting.+Thus, for example, if one writes+.IP+.nf+\f[C]+*\[rs]*hello\[rs]**+\f[R]+.fi+.PP+one will get+.IP+.nf+\f[C]+<em>*hello*</em>+\f[R]+.fi+.PP+instead of+.IP+.nf+\f[C]+<strong>hello</strong>+\f[R]+.fi+.PP+This rule is easier to remember than original Markdown\[cq]s rule, which+allows only the following characters to be backslash-escaped:+.IP+.nf+\f[C]+\[rs]\[ga]*_{}[]()>#+-.!+\f[R]+.fi+.PP+(However, if the \f[V]markdown_strict\f[R] format is used, the original+Markdown rule will be used.)+.PP+A backslash-escaped space is parsed as a nonbreaking space.+In TeX output, it will appear as \f[V]\[ti]\f[R].+In HTML and XML output, it will appear as a literal unicode nonbreaking+space character (note that it will thus actually look+\[lq]invisible\[rq] in the generated HTML source; you can still use the+\f[V]--ascii\f[R] command-line option to make it appear as an explicit+entity).+.PP+A backslash-escaped newline (i.e.\ a backslash occurring at the end of a+line) is parsed as a hard line break.+It will appear in TeX output as \f[V]\[rs]\[rs]\f[R] and in HTML as+\f[V]<br />\f[R].+This is a nice alternative to Markdown\[cq]s \[lq]invisible\[rq] way of+indicating hard line breaks using two trailing spaces on a line.+.PP+Backslash escapes do not work in verbatim contexts.+.SS Inline formatting+.SS Emphasis+.PP+To \f[I]emphasize\f[R] some text, surround it with \f[V]*\f[R]s or+\f[V]_\f[R], like this:+.IP+.nf+\f[C]+This text is _emphasized with underscores_, and this+is *emphasized with asterisks*.+\f[R]+.fi+.PP+Double \f[V]*\f[R] or \f[V]_\f[R] produces \f[B]strong emphasis\f[R]:+.IP+.nf+\f[C]+This is **strong emphasis** and __with underscores__.+\f[R]+.fi+.PP+A \f[V]*\f[R] or \f[V]_\f[R] character surrounded by spaces, or+backslash-escaped, will not trigger emphasis:+.IP+.nf+\f[C]+This is * not emphasized *, and \[rs]*neither is this\[rs]*.+\f[R]+.fi+.SS Extension: \f[V]intraword_underscores\f[R]+.PP+Because \f[V]_\f[R] is sometimes used inside words and identifiers,+pandoc does not interpret a \f[V]_\f[R] surrounded by alphanumeric+characters as an emphasis marker.+If you want to emphasize just part of a word, use \f[V]*\f[R]:+.IP+.nf+\f[C]+feas*ible*, not feas*able*.+\f[R]+.fi+.SS Strikeout+.SS Extension: \f[V]strikeout\f[R]+.PP+To strikeout a section of text with a horizontal line, begin and end it+with \f[V]\[ti]\[ti]\f[R].+Thus, for example,+.IP+.nf+\f[C]+This \[ti]\[ti]is deleted text.\[ti]\[ti]+\f[R]+.fi+.SS Superscripts and subscripts+.SS Extension: \f[V]superscript\f[R], \f[V]subscript\f[R]+.PP+Superscripts may be written by surrounding the superscripted text by+\f[V]\[ha]\f[R] characters; subscripts may be written by surrounding the+subscripted text by \f[V]\[ti]\f[R] characters.+Thus, for example,+.IP+.nf+\f[C]+H\[ti]2\[ti]O is a liquid.  2\[ha]10\[ha] is 1024.+\f[R]+.fi+.PP+The text between \f[V]\[ha]...\[ha]\f[R] or \f[V]\[ti]...\[ti]\f[R] may+not contain spaces or newlines.+If the superscripted or subscripted text contains spaces, these spaces+must be escaped with backslashes.+(This is to prevent accidental superscripting and subscripting through+the ordinary use of \f[V]\[ti]\f[R] and \f[V]\[ha]\f[R], and also bad+interactions with footnotes.)+Thus, if you want the letter P with `a cat' in subscripts, use+\f[V]P\[ti]a\[rs] cat\[ti]\f[R], not \f[V]P\[ti]a cat\[ti]\f[R].+.SS Verbatim+.PP+To make a short span of text verbatim, put it inside backticks:+.IP+.nf+\f[C]+What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]?+\f[R]+.fi+.PP+If the verbatim text includes a backtick, use double backticks:+.IP+.nf+\f[C]+Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga].+\f[R]+.fi+.PP+(The spaces after the opening backticks and before the closing backticks+will be ignored.)+.PP+The general rule is that a verbatim span starts with a string of+consecutive backticks (optionally followed by a space) and ends with a+string of the same number of backticks (optionally preceded by a space).+.PP+Note that backslash-escapes (and other Markdown constructs) do not work+in verbatim contexts:+.IP+.nf+\f[C]+This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga].+\f[R]+.fi+.SS Extension: \f[V]inline_code_attributes\f[R]+.PP+Attributes can be attached to verbatim text, just as with fenced code+blocks:+.IP+.nf+\f[C]+\[ga]<$>\[ga]{.haskell}+\f[R]+.fi+.SS Underline+.PP+To underline text, use the \f[V]underline\f[R] class:+.IP+.nf+\f[C]+[Underline]{.underline}+\f[R]+.fi+.PP+Or, without the \f[V]bracketed_spans\f[R] extension (but with+\f[V]native_spans\f[R]):+.IP+.nf+\f[C]+<span class=\[dq]underline\[dq]>Underline</span>+\f[R]+.fi+.PP+This will work in all output formats that support underline.+.SS Small caps+.PP+To write small caps, use the \f[V]smallcaps\f[R] class:+.IP+.nf+\f[C]+[Small caps]{.smallcaps}+\f[R]+.fi+.PP+Or, without the \f[V]bracketed_spans\f[R] extension:+.IP+.nf+\f[C]+<span class=\[dq]smallcaps\[dq]>Small caps</span>+\f[R]+.fi+.PP+For compatibility with other Markdown flavors, CSS is also supported:+.IP+.nf+\f[C]+<span style=\[dq]font-variant:small-caps;\[dq]>Small caps</span>+\f[R]+.fi+.PP+This will work in all output formats that support small caps.+.SS Math+.SS Extension: \f[V]tex_math_dollars\f[R]+.PP+Anything between two \f[V]$\f[R] characters will be treated as TeX math.+The opening \f[V]$\f[R] must have a non-space character immediately to+its right, while the closing \f[V]$\f[R] must have a non-space character+immediately to its left, and must not be followed immediately by a+digit.+Thus, \f[V]$20,000 and $30,000\f[R] won\[cq]t parse as math.+If for some reason you need to enclose text in literal \f[V]$\f[R]+characters, backslash-escape them and they won\[cq]t be treated as math+delimiters.+.PP+For display math, use \f[V]$$\f[R] delimiters.+(In this case, the delimiters may be separated from the formula by+whitespace.+However, there can be no blank lines betwen the opening and closing+\f[V]$$\f[R] delimiters.)+.PP+TeX math will be printed in all output formats.+How it is rendered depends on the output format:+.TP+LaTeX+It will appear verbatim surrounded by \f[V]\[rs](...\[rs])\f[R] (for+inline math) or \f[V]\[rs][...\[rs]]\f[R] (for display math).+.TP+Markdown, Emacs Org mode, ConTeXt, ZimWiki+It will appear verbatim surrounded by \f[V]$...$\f[R] (for inline math)+or \f[V]$$...$$\f[R] (for display math).+.TP+XWiki+It will appear verbatim surrounded by+\f[V]{{formula}}..{{/formula}}\f[R].+.TP+reStructuredText+It will be rendered using an interpreted text role \f[V]:math:\f[R].+.TP+AsciiDoc+For AsciiDoc output format (\f[V]-t asciidoc\f[R]) it will appear+verbatim surrounded by \f[V]latexmath:[$...$]\f[R] (for inline math) or+\f[V][latexmath]++++\[rs][...\[rs]]+++\f[R] (for display math).+For AsciiDoctor output format (\f[V]-t asciidoctor\f[R]) the LaTex+delimiters (\f[V]$..$\f[R] and \f[V]\[rs][..\[rs]]\f[R]) are omitted.+.TP+Texinfo+It will be rendered inside a \f[V]\[at]math\f[R] command.+.TP+roff man, Jira markup+It will be rendered verbatim without \f[V]$\f[R]\[cq]s.+.TP+MediaWiki, DokuWiki+It will be rendered inside \f[V]<math>\f[R] tags.+.TP+Textile+It will be rendered inside \f[V]<span class=\[dq]math\[dq]>\f[R] tags.+.TP+RTF, OpenDocument+It will be rendered, if possible, using Unicode characters, and will+otherwise appear verbatim.+.TP+ODT+It will be rendered, if possible, using MathML.+.TP+DocBook+If the \f[V]--mathml\f[R] flag is used, it will be rendered using MathML+in an \f[V]inlineequation\f[R] or \f[V]informalequation\f[R] tag.+Otherwise it will be rendered, if possible, using Unicode characters.+.TP+Docx+It will be rendered using OMML math markup.+.TP+FictionBook2+If the \f[V]--webtex\f[R] option is used, formulas are rendered as+images using CodeCogs or other compatible web service, downloaded and+embedded in the e-book.+Otherwise, they will appear verbatim.+.TP+HTML, Slidy, DZSlides, S5, EPUB+The way math is rendered in HTML will depend on the command-line options+selected.+Therefore see Math rendering in HTML above.+.SS Raw HTML+.SS Extension: \f[V]raw_html\f[R]+.PP+Markdown allows you to insert raw HTML (or DocBook) anywhere in a+document (except verbatim contexts, where \f[V]<\f[R], \f[V]>\f[R], and+\f[V]&\f[R] are interpreted literally).+(Technically this is not an extension, since standard Markdown allows+it, but it has been made an extension so that it can be disabled if+desired.)+.PP+The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,+DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile+output, and suppressed in other formats.+.PP+For a more explicit way of including raw HTML in a Markdown document,+see the \f[V]raw_attribute\f[R] extension.+.PP+In the CommonMark format, if \f[V]raw_html\f[R] is enabled,+superscripts, subscripts, strikeouts and small capitals will be+represented as HTML.+Otherwise, plain-text fallbacks will be used.+Note that even if \f[V]raw_html\f[R] is disabled, tables will be+rendered with HTML syntax if they cannot use pipe syntax.+.SS Extension: \f[V]markdown_in_html_blocks\f[R]+.PP+Original Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of+HTML between balanced tags that are separated from the surrounding text+with blank lines, and start and end at the left margin.+Within these blocks, everything is interpreted as HTML, not Markdown; so+(for example), \f[V]*\f[R] does not signify emphasis.+.PP+Pandoc behaves this way when the \f[V]markdown_strict\f[R] format is+used; but by default, pandoc interprets material between HTML block tags+as Markdown.+Thus, for example, pandoc will turn+.IP+.nf+\f[C]+<table>+<tr>+<td>*one*</td>+<td>[a link](https://google.com)</td>+</tr>+</table>+\f[R]+.fi+.PP+into+.IP+.nf+\f[C]+<table>+<tr>+<td><em>one</em></td>+<td><a href=\[dq]https://google.com\[dq]>a link</a></td>+</tr>+</table>+\f[R]+.fi+.PP+whereas \f[V]Markdown.pl\f[R] will preserve it as is.+.PP+There is one exception to this rule: text between \f[V]<script>\f[R],+\f[V]<style>\f[R], and \f[V]<textarea>\f[R] tags is not interpreted as+Markdown.+.PP+This departure from original Markdown should make it easier to mix+Markdown with HTML block elements.+For example, one can surround a block of Markdown text with+\f[V]<div>\f[R] tags without preventing it from being interpreted as+Markdown.+.SS Extension: \f[V]native_divs\f[R]+.PP+Use native pandoc \f[V]Div\f[R] blocks for content inside+\f[V]<div>\f[R] tags.+For the most part this should give the same output as+\f[V]markdown_in_html_blocks\f[R], but it makes it easier to write+pandoc filters to manipulate groups of blocks.+.SS Extension: \f[V]native_spans\f[R]+.PP+Use native pandoc \f[V]Span\f[R] blocks for content inside+\f[V]<span>\f[R] tags.+For the most part this should give the same output as+\f[V]raw_html\f[R], but it makes it easier to write pandoc filters to+manipulate groups of inlines.+.SS Extension: \f[V]raw_tex\f[R]+.PP+In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be+included in a document.+Inline TeX commands will be preserved and passed unchanged to the LaTeX+and ConTeXt writers.+Thus, for example, you can use LaTeX to include BibTeX citations:+.IP+.nf+\f[C]+This result was proved in \[rs]cite{jones.1967}.+\f[R]+.fi+.PP+Note that in LaTeX environments, like+.IP+.nf+\f[C]+\[rs]begin{tabular}{|l|l|}\[rs]hline+Age & Frequency \[rs]\[rs] \[rs]hline+18--25  & 15 \[rs]\[rs]+26--35  & 33 \[rs]\[rs]+36--45  & 22 \[rs]\[rs] \[rs]hline+\[rs]end{tabular}+\f[R]+.fi+.PP+the material between the begin and end tags will be interpreted as raw+LaTeX, not as Markdown.+.PP+For a more explicit and flexible way of including raw TeX in a Markdown+document, see the \f[V]raw_attribute\f[R] extension.+.PP+Inline LaTeX is ignored in output formats other than Markdown, LaTeX,+Emacs Org mode, and ConTeXt.+.SS Generic raw attribute+.SS Extension: \f[V]raw_attribute\f[R]+.PP+Inline spans and fenced code blocks with a special kind of attribute+will be parsed as raw content with the designated format.+For example, the following produces a raw roff \f[V]ms\f[R] block:+.IP+.nf+\f[C]+\[ga]\[ga]\[ga]{=ms}+\&.MYMACRO+blah blah+\[ga]\[ga]\[ga]+\f[R]+.fi+.PP+And the following produces a raw \f[V]html\f[R] inline element:+.IP+.nf+\f[C]+This is \[ga]<a>html</a>\[ga]{=html}+\f[R]+.fi+.PP+This can be useful to insert raw xml into \f[V]docx\f[R] documents, e.g.+a pagebreak:+.IP+.nf+\f[C]+\[ga]\[ga]\[ga]{=openxml}+<w:p>+  <w:r>+    <w:br w:type=\[dq]page\[dq]/>+  </w:r>+</w:p>+\[ga]\[ga]\[ga]+\f[R]+.fi+.PP+The format name should match the target format name (see+\f[V]-t/--to\f[R], above, for a list, or use+\f[V]pandoc --list-output-formats\f[R]).+Use \f[V]openxml\f[R] for \f[V]docx\f[R] output, \f[V]opendocument\f[R]+for \f[V]odt\f[R] output, \f[V]html5\f[R] for \f[V]epub3\f[R] output,+\f[V]html4\f[R] for \f[V]epub2\f[R] output, and \f[V]latex\f[R],+\f[V]beamer\f[R], \f[V]ms\f[R], or \f[V]html5\f[R] for \f[V]pdf\f[R]+output (depending on what you use for \f[V]--pdf-engine\f[R]).+.PP+This extension presupposes that the relevant kind of inline code or+fenced code block is enabled.+Thus, for example, to use a raw attribute with a backtick code block,+\f[V]backtick_code_blocks\f[R] must be enabled.+.PP+The raw attribute cannot be combined with regular attributes.+.SS LaTeX macros+.SS Extension: \f[V]latex_macros\f[R]+.PP+When this extension is enabled, pandoc will parse LaTeX macro+definitions and apply the resulting macros to all LaTeX math and raw+LaTeX.+So, for example, the following will work in all output formats, not just+LaTeX:+.IP+.nf+\f[C]+\[rs]newcommand{\[rs]tuple}[1]{\[rs]langle #1 \[rs]rangle}++$\[rs]tuple{a, b, c}$+\f[R]+.fi+.PP+Note that LaTeX macros will not be applied if they occur inside a raw+span or block marked with the \f[V]raw_attribute\f[R] extension.+.PP+When \f[V]latex_macros\f[R] is disabled, the raw LaTeX and math will not+have macros applied.+This is usually a better approach when you are targeting LaTeX or PDF.+.PP+Macro definitions in LaTeX will be passed through as raw LaTeX only if+\f[V]latex_macros\f[R] is not enabled.+Macro definitions in Markdown source (or other formats allowing+\f[V]raw_tex\f[R]) will be passed through regardless of whether+\f[V]latex_macros\f[R] is enabled.+.SS Links+.PP+Markdown allows links to be specified in several ways.+.SS Automatic links+.PP+If you enclose a URL or email address in pointy brackets, it will become+a link:+.IP+.nf+\f[C]+<https://google.com>+<sam\[at]green.eggs.ham>+\f[R]+.fi+.SS Inline links+.PP+An inline link consists of the link text in square brackets, followed by+the URL in parentheses.+(Optionally, the URL can be followed by a link title, in quotes.)+.IP+.nf+\f[C]+This is an [inline link](/url), and here\[aq]s [one with+a title](https://fsf.org \[dq]click here for a good time!\[dq]).+\f[R]+.fi+.PP+There can be no space between the bracketed part and the parenthesized+part.+The link text can contain formatting (such as emphasis), but the title+cannot.+.PP+Email addresses in inline links are not autodetected, so they have to be+prefixed with \f[V]mailto\f[R]:+.IP+.nf+\f[C]+[Write me!](mailto:sam\[at]green.eggs.ham)+\f[R]+.fi+.SS Reference links+.PP+An \f[I]explicit\f[R] reference link has two parts, the link itself and+the link definition, which may occur elsewhere in the document (either+before or after the link).+.PP+The link consists of link text in square brackets, followed by a label+in square brackets.+(There cannot be space between the two unless the+\f[V]spaced_reference_links\f[R] extension is enabled.)+The link definition consists of the bracketed label, followed by a colon+and a space, followed by the URL, and optionally (after a space) a link+title either in quotes or in parentheses.+The label must not be parseable as a citation (assuming the+\f[V]citations\f[R] extension is enabled): citations take precedence+over link labels.+.PP+Here are some examples:+.IP+.nf+\f[C]+[my label 1]: /foo/bar.html  \[dq]My title, optional\[dq]+[my label 2]: /foo+[my label 3]: https://fsf.org (The free software foundation)+[my label 4]: /bar#special  \[aq]A title in single quotes\[aq]+\f[R]+.fi+.PP+The URL may optionally be surrounded by angle brackets:+.IP+.nf+\f[C]+[my label 5]: <http://foo.bar.baz>+\f[R]+.fi+.PP+The title may go on the next line:+.IP+.nf+\f[C]+[my label 3]: https://fsf.org+  \[dq]The free software foundation\[dq]+\f[R]+.fi+.PP+Note that link labels are not case sensitive.+So, this will work:+.IP+.nf+\f[C]+Here is [my link][FOO]++[Foo]: /bar/baz+\f[R]+.fi+.PP+In an \f[I]implicit\f[R] reference link, the second pair of brackets is+empty:+.IP+.nf+\f[C]+See [my website][].++[my website]: http://foo.bar.baz+\f[R]+.fi+.PP+Note: In \f[V]Markdown.pl\f[R] and most other Markdown implementations,+reference link definitions cannot occur in nested constructions such as+list items or block quotes.+Pandoc lifts this arbitrary seeming restriction.+So the following is fine in pandoc, though not in most other+implementations:+.IP+.nf+\f[C]+> My block [quote].+>+> [quote]: /foo+\f[R]+.fi+.SS Extension: \f[V]shortcut_reference_links\f[R]+.PP+In a \f[I]shortcut\f[R] reference link, the second pair of brackets may+be omitted entirely:+.IP+.nf+\f[C]+See [my website].++[my website]: http://foo.bar.baz+\f[R]+.fi+.SS Internal links+.PP+To link to another section of the same document, use the automatically+generated identifier (see Heading identifiers).+For example:+.IP+.nf+\f[C]+See the [Introduction](#introduction).+\f[R]+.fi+.PP+or+.IP+.nf+\f[C]+See the [Introduction].++[Introduction]: #introduction+\f[R]+.fi+.PP+Internal links are currently supported for HTML formats (including HTML+slide shows and EPUB), LaTeX, and ConTeXt.+.SS Images+.PP+A link immediately preceded by a \f[V]!\f[R] will be treated as an+image.+The link text will be used as the image\[cq]s alt text:+.IP+.nf+\f[C]+![la lune](lalune.jpg \[dq]Voyage to the moon\[dq])++![movie reel]++[movie reel]: movie.gif+\f[R]+.fi+.SS Extension: \f[V]implicit_figures\f[R]+.PP+An image with nonempty alt text, occurring by itself in a paragraph,+will be rendered as a figure with a caption.+The image\[cq]s alt text will be used as the caption.+.IP+.nf+\f[C]+![This is the caption](/url/of/image.png)+\f[R]+.fi+.PP+How this is rendered depends on the output format.+Some output formats (e.g.\ RTF) do not yet support figures.+In those formats, you\[cq]ll just get an image in a paragraph by itself,+with no caption.+.PP+If you just want a regular inline image, just make sure it is not the+only thing in the paragraph.+One way to do this is to insert a nonbreaking space after the image:+.IP+.nf+\f[C]+![This image won\[aq]t be a figure](/url/of/image.png)\[rs]+\f[R]+.fi+.PP+Note that in reveal.js slide shows, an image in a paragraph by itself+that has the \f[V]r-stretch\f[R] class will fill the screen, and the+caption and figure tags will be omitted.+.SS Extension: \f[V]link_attributes\f[R]+.PP+Attributes can be set on links and images:+.IP+.nf+\f[C]+An inline ![image](foo.jpg){#id .class width=30 height=20px}+and a reference ![image][ref] with attributes.++[ref]: foo.jpg \[dq]optional title\[dq] {#id .class key=val key2=\[dq]val 2\[dq]}+\f[R]+.fi+.PP+(This syntax is compatible with PHP Markdown Extra when only+\f[V]#id\f[R] and \f[V].class\f[R] are used.)+.PP+For HTML and EPUB, all known HTML5 attributes except \f[V]width\f[R] and+\f[V]height\f[R] (but including \f[V]srcset\f[R] and \f[V]sizes\f[R])+are passed through as is.+Unknown attributes are passed through as custom attributes, with+\f[V]data-\f[R] prepended.+The other writers ignore attributes that are not specifically supported+by their output format.+.PP+The \f[V]width\f[R] and \f[V]height\f[R] attributes on images are+treated specially.+When used without a unit, the unit is assumed to be pixels.+However, any of the following unit identifiers can be used:+\f[V]px\f[R], \f[V]cm\f[R], \f[V]mm\f[R], \f[V]in\f[R], \f[V]inch\f[R]+and \f[V]%\f[R].+There must not be any spaces between the number and the unit.+For example:+.IP+.nf+\f[C]+![](file.jpg){ width=50% }+\f[R]+.fi+.IP \[bu] 2+Dimensions may be converted to a form that is compatible with the output+format (for example, dimensions given in pixels will be converted to+inches when converting HTML to LaTeX).+Conversion between pixels and physical measurements is affected by the+\f[V]--dpi\f[R] option (by default, 96 dpi is assumed, unless the image+itself contains dpi information).+.IP \[bu] 2+The \f[V]%\f[R] unit is generally relative to some available space.+For example the above example will render to the following.+.RS 2+.IP \[bu] 2+HTML:+\f[V]<img href=\[dq]file.jpg\[dq] style=\[dq]width: 50%;\[dq] />\f[R]+.IP \[bu] 2+LaTeX:+\f[V]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]+(If you\[cq]re using a custom template, you need to configure+\f[V]graphicx\f[R] as in the default template.)+.IP \[bu] 2+ConTeXt:+\f[V]\[rs]externalfigure[file.jpg][width=0.5\[rs]textwidth]\f[R]+.RE+.IP \[bu] 2+Some output formats have a notion of a class (ConTeXt) or a unique+identifier (LaTeX \f[V]\[rs]caption\f[R]), or both (HTML).+.IP \[bu] 2+When no \f[V]width\f[R] or \f[V]height\f[R] attributes are specified,+the fallback is to look at the image resolution and the dpi metadata+embedded in the image file.+.SS Divs and Spans+.PP+Using the \f[V]native_divs\f[R] and \f[V]native_spans\f[R] extensions+(see above), HTML syntax can be used as part of markdown to create+native \f[V]Div\f[R] and \f[V]Span\f[R] elements in the pandoc AST (as+opposed to raw HTML).+However, there is also nicer syntax available:+.SS Extension: \f[V]fenced_divs\f[R]+.PP+Allow special fenced syntax for native \f[V]Div\f[R] blocks.+A Div starts with a fence containing at least three consecutive colons+plus some attributes.+The attributes may optionally be followed by another string of+consecutive colons.+The attribute syntax is exactly as in fenced code blocks (see Extension:+\f[V]fenced_code_attributes\f[R]).+As with fenced code blocks, one can use either attributes in curly+braces or a single unbraced word, which will be treated as a class name.+The Div ends with another line containing a string of at least three+consecutive colons.+The fenced Div should be separated by blank lines from preceding and+following blocks.+.PP+Example:+.IP+.nf+\f[C]+::::: {#special .sidebar}+Here is a paragraph.++And another.+:::::+\f[R]+.fi+.PP+Fenced divs can be nested.+Opening fences are distinguished because they \f[I]must\f[R] have+attributes:+.IP+.nf+\f[C]+::: Warning ::::::+This is a warning.++::: Danger+This is a warning within a warning.+:::+::::::::::::::::::+\f[R]+.fi+.PP+Fences without attributes are always closing fences.+Unlike with fenced code blocks, the number of colons in the closing+fence need not match the number in the opening fence.+However, it can be helpful for visual clarity to use fences of different+lengths to distinguish nested divs from their parents.+.SS Extension: \f[V]bracketed_spans\f[R]+.PP+A bracketed sequence of inlines, as one would use to begin a link, will+be treated as a \f[V]Span\f[R] with attributes if it is followed+immediately by attributes:+.IP+.nf+\f[C]+[This is *some text*]{.class key=\[dq]val\[dq]}+\f[R]+.fi+.SS Footnotes+.SS Extension: \f[V]footnotes\f[R]+.PP+Pandoc\[cq]s Markdown allows footnotes, using the following syntax:+.IP+.nf+\f[C]+Here is a footnote reference,[\[ha]1] and another.[\[ha]longnote]++[\[ha]1]: Here is the footnote.++[\[ha]longnote]: Here\[aq]s one with multiple blocks.++    Subsequent paragraphs are indented to show that they+belong to the previous footnote.++        { some.code }++    The whole paragraph can be indented, or just the first+    line.  In this way, multi-paragraph footnotes work like+    multi-paragraph list items.++This paragraph won\[aq]t be part of the note, because it+isn\[aq]t indented.+\f[R]+.fi+.PP+The identifiers in footnote references may not contain spaces, tabs, or+newlines.+These identifiers are used only to correlate the footnote reference with+the note itself; in the output, footnotes will be numbered sequentially.+.PP+The footnotes themselves need not be placed at the end of the document.+They may appear anywhere except inside other block elements (lists,+block quotes, tables, etc.).+Each footnote should be separated from surrounding content (including+other footnotes) by blank lines.+.SS Extension: \f[V]inline_notes\f[R]+.PP+Inline footnotes are also allowed (though, unlike regular notes, they+cannot contain multiple paragraphs).+The syntax is as follows:+.IP+.nf+\f[C]+Here is an inline note.\[ha][Inlines notes are easier to write, since+you don\[aq]t have to pick an identifier and move down to type the+note.]+\f[R]+.fi+.PP+Inline and regular footnotes may be mixed freely.+.SS Citation syntax+.SS Extension: \f[V]citations\f[R]+.PP+To cite a bibliographic item with an identifier foo, use the syntax+\f[V]\[at]foo\f[R].+Normal citations should be included in square brackets, with semicolons+separating distinct items:+.IP+.nf+\f[C]+Blah blah [\[at]doe99; \[at]smith2000; \[at]smith2004].+\f[R]+.fi+.PP+How this is rendered depends on the citation style.+In an author-date style, it might render as+.IP+.nf+\f[C]+Blah blah (Doe 1999, Smith 2000, 2004).+\f[R]+.fi+.PP+In a footnote style, it might render as+.IP+.nf+\f[C]+Blah blah.[\[ha]1]++[\[ha]1]:  John Doe, \[dq]Frogs,\[dq] *Journal of Amphibians* 44 (1999);+Susan Smith, \[dq]Flies,\[dq] *Journal of Insects* (2000);+Susan Smith, \[dq]Bees,\[dq] *Journal of Insects* (2004).+\f[R]+.fi+.PP+See the CSL user documentation for more information about CSL styles and+how they affect rendering.+.PP+Unless a citation key start with a letter, digit, or \f[V]_\f[R], and+contains only alphanumerics and single internal punctuation characters+(\f[V]:.#$%&-+?<>\[ti]/\f[R]), it must be surrounded by curly braces,+which are not considered part of the key.+In \f[V]\[at]Foo_bar.baz.\f[R], the key is \f[V]Foo_bar.baz\f[R] because+the final period is not \f[I]internal\f[R] punctuation, so it is not+included in the key.+In \f[V]\[at]{Foo_bar.baz.}\f[R], the key is \f[V]Foo_bar.baz.\f[R],+including the final period.+In \f[V]\[at]Foo_bar--baz\f[R], the key is \f[V]Foo_bar\f[R] because the+repeated internal punctuation characters terminate the key.+The curly braces are recommended if you use URLs as keys:+\f[V][\[at]{https://example.com/bib?name=foobar&date=2000}, p.  33]\f[R].+.PP+Citation items may optionally include a prefix, a locator, and a suffix.+In+.IP+.nf+\f[C]+Blah blah [see \[at]doe99, pp. 33-35 and *passim*; \[at]smith04, chap. 1].+\f[R]+.fi+.PP+The first item (\f[V]doe99\f[R]) has prefix \f[V]see\f[R], locator+\f[V]pp.  33-35\f[R], and suffix \f[V]and *passim*\f[R].+The second item (\f[V]smith04\f[R]) has locator \f[V]chap. 1\f[R] and no+prefix or suffix.+.PP+Pandoc uses some heuristics to separate the locator from the rest of the+subject.+It is sensitive to the locator terms defined in the CSL locale files.+Either abbreviated or unabbreviated forms are accepted.+In the \f[V]en-US\f[R] locale, locator terms can be written in either+singular or plural forms, as \f[V]book\f[R],+\f[V]bk.\f[R]/\f[V]bks.\f[R]; \f[V]chapter\f[R],+\f[V]chap.\f[R]/\f[V]chaps.\f[R]; \f[V]column\f[R],+\f[V]col.\f[R]/\f[V]cols.\f[R]; \f[V]figure\f[R],+\f[V]fig.\f[R]/\f[V]figs.\f[R]; \f[V]folio\f[R],+\f[V]fol.\f[R]/\f[V]fols.\f[R]; \f[V]number\f[R],+\f[V]no.\f[R]/\f[V]nos.\f[R]; \f[V]line\f[R],+\f[V]l.\f[R]/\f[V]ll.\f[R]; \f[V]note\f[R], \f[V]n.\f[R]/\f[V]nn.\f[R];+\f[V]opus\f[R], \f[V]op.\f[R]/\f[V]opp.\f[R]; \f[V]page\f[R],+\f[V]p.\f[R]/\f[V]pp.\f[R]; \f[V]paragraph\f[R],+\f[V]para.\f[R]/\f[V]paras.\f[R]; \f[V]part\f[R],+\f[V]pt.\f[R]/\f[V]pts.\f[R]; \f[V]section\f[R],+\f[V]sec.\f[R]/\f[V]secs.\f[R]; \f[V]sub verbo\f[R],+\f[V]s.v.\f[R]/\f[V]s.vv.\f[R]; \f[V]verse\f[R],+\f[V]v.\f[R]/\f[V]vv.\f[R]; \f[V]volume\f[R],+\f[V]vol.\f[R]/\f[V]vols.\f[R]; \f[V]\[ps]\f[R]/\f[V]\[ps]\[ps]\f[R];+\f[V]\[sc]\f[R]/\f[V]\[sc]\[sc]\f[R].+If no locator term is used, \[lq]page\[rq] is assumed.+.PP+In complex cases, you can force something to be treated as a locator by+enclosing it in curly braces or prevent parsing the suffix as locator by+prepending curly braces:+.IP+.nf+\f[C]+[\[at]smith{ii, A, D-Z}, with a suffix]+[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]+[\[at]smith{}, 99 years later]+\f[R]+.fi+.PP+A minus sign (\f[V]-\f[R]) before the \f[V]\[at]\f[R] will suppress+mention of the author in the citation.+This can be useful when the author is already mentioned in the text:+.IP+.nf+\f[C]+Smith says blah [-\[at]smith04].+\f[R]+.fi+.PP+You can also write an author-in-text citation, by omitting the square+brackets:+.IP+.nf+\f[C]+\[at]smith04 says blah.++\[at]smith04 [p. 33] says blah.+\f[R]+.fi+.PP+This will cause the author\[cq]s name to be rendered, followed by the+bibliographical details.+Use this form when you want to make the citation the subject of a+sentence.+.PP+When you are using a note style, it is usually better to let citeproc+create the footnotes from citations rather than writing an explicit+note.+If you do write an explicit note that contains a citation, note that+normal citations will be put in parentheses, while author-in-text+citations will not.+For this reason, it is sometimes preferable to use the author-in-text+style inside notes when using a note style.+.SS Non-default extensions+.PP+The following Markdown syntax extensions are not enabled by default in+pandoc, but may be enabled by adding \f[V]+EXTENSION\f[R] to the format+name, where \f[V]EXTENSION\f[R] is the name of the extension.+Thus, for example, \f[V]markdown+hard_line_breaks\f[R] is Markdown with+hard line breaks.+.SS Extension: \f[V]rebase_relative_paths\f[R]+.PP+Rewrite relative paths for Markdown links and images, depending on the+path of the file containing the link or image link.+For each link or image, pandoc will compute the directory of the+containing file, relative to the working directory, and prepend the+resulting path to the link or image path.+.PP+The use of this extension is best understood by example.+Suppose you have a a subdirectory for each chapter of a book,+\f[V]chap1\f[R], \f[V]chap2\f[R], \f[V]chap3\f[R].+Each contains a file \f[V]text.md\f[R] and a number of images used in+the chapter.+You would like to have \f[V]![image](spider.jpg)\f[R] in+\f[V]chap1/text.md\f[R] refer to \f[V]chap1/spider.jpg\f[R] and+\f[V]![image](spider.jpg)\f[R] in \f[V]chap2/text.md\f[R] refer to+\f[V]chap2/spider.jpg\f[R].+To do this, use+.IP+.nf+\f[C]+pandoc chap*/*.md -f markdown+rebase_relative_paths+\f[R]+.fi+.PP+Without this extension, you would have to use+\f[V]![image](chap1/spider.jpg)\f[R] in \f[V]chap1/text.md\f[R] and+\f[V]![image](chap2/spider.jpg)\f[R] in \f[V]chap2/text.md\f[R].+Links with relative paths will be rewritten in the same way as images.+.PP+Absolute paths and URLs are not changed.+Neither are empty paths or paths consisting entirely of a fragment,+e.g., \f[V]#foo\f[R].+.PP+Note that relative paths in reference links and images will be rewritten+relative to the file containing the link reference definition, not the+file containing the reference link or image itself, if these differ.+.SS Extension: \f[V]attributes\f[R]+.PP+Allows attributes to be attached to any inline or block-level element+when parsing \f[V]commonmark\f[R].+The syntax for the attributes is the same as that used in+\f[V]header_attributes\f[R].+.IP \[bu] 2+Attributes that occur immediately after an inline element affect that+element.+If they follow a space, then they belong to the space.+(Hence, this option subsumes \f[V]inline_code_attributes\f[R] and+\f[V]link_attributes\f[R].)+.IP \[bu] 2+Attributes that occur immediately before a block element, on a line by+themselves, affect that element.+.IP \[bu] 2+Consecutive attribute specifiers may be used, either for blocks or for+inlines.+Their attributes will be combined.+.IP \[bu] 2+Attributes that occur at the end of the text of a Setext or ATX heading+(separated by whitespace from the text) affect the heading element.+(Hence, this option subsumes \f[V]header_attributes\f[R].)+.IP \[bu] 2+Attributes that occur after the opening fence in a fenced code block+affect the code block element.+(Hence, this option subsumes \f[V]fenced_code_attributes\f[R].)+.IP \[bu] 2+Attributes that occur at the end of a reference link definition affect+links that refer to that definition.+.PP+Note that pandoc\[cq]s AST does not currently allow attributes to be+attached to arbitrary elements.+Hence a Span or Div container will be added if needed.+.SS Extension: \f[V]old_dashes\f[R]+.PP+Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:+\f[V]-\f[R] before a numeral is an en-dash, and \f[V]--\f[R] is an+em-dash.+This option only has an effect if \f[V]smart\f[R] is enabled.+It is selected automatically for \f[V]textile\f[R] input.+.SS Extension: \f[V]angle_brackets_escapable\f[R]+.PP+Allow \f[V]<\f[R] and \f[V]>\f[R] to be backslash-escaped, as they can+be in GitHub flavored Markdown but not original Markdown.+This is implied by pandoc\[cq]s default \f[V]all_symbols_escapable\f[R].+.SS Extension: \f[V]lists_without_preceding_blankline\f[R]+.PP+Allow a list to occur right after a paragraph, with no intervening blank+space.+.SS Extension: \f[V]four_space_rule\f[R]+.PP+Selects the pandoc <= 2.0 behavior for parsing lists, so that four+spaces indent are needed for list item continuation paragraphs.+.SS Extension: \f[V]spaced_reference_links\f[R]+.PP+Allow whitespace between the two components of a reference link, for+example,+.IP+.nf+\f[C]+[foo] [bar].+\f[R]+.fi+.SS Extension: \f[V]hard_line_breaks\f[R]+.PP+Causes all newlines within a paragraph to be interpreted as hard line+breaks instead of spaces.+.SS Extension: \f[V]ignore_line_breaks\f[R]+.PP+Causes newlines within a paragraph to be ignored, rather than being+treated as spaces or as hard line breaks.+This option is intended for use with East Asian languages where spaces+are not used between words, but text is divided into lines for+readability.+.SS Extension: \f[V]east_asian_line_breaks\f[R]+.PP+Causes newlines within a paragraph to be ignored, rather than being+treated as spaces or as hard line breaks, when they occur between two+East Asian wide characters.+This is a better choice than \f[V]ignore_line_breaks\f[R] for texts that+include a mix of East Asian wide characters and other characters.+.SS Extension: \f[V]emoji\f[R]+.PP+Parses textual emojis like \f[V]:smile:\f[R] as Unicode emoticons.+.SS Extension: \f[V]tex_math_single_backslash\f[R]+.PP+Causes anything between \f[V]\[rs](\f[R] and \f[V]\[rs])\f[R] to be+interpreted as inline TeX math, and anything between \f[V]\[rs][\f[R]+and \f[V]\[rs]]\f[R] to be interpreted as display TeX math.+Note: a drawback of this extension is that it precludes escaping+\f[V](\f[R] and \f[V][\f[R].+.SS Extension: \f[V]tex_math_double_backslash\f[R]+.PP+Causes anything between \f[V]\[rs]\[rs](\f[R] and \f[V]\[rs]\[rs])\f[R]+to be interpreted as inline TeX math, and anything between+\f[V]\[rs]\[rs][\f[R] and \f[V]\[rs]\[rs]]\f[R] to be interpreted as+display TeX math.+.SS Extension: \f[V]markdown_attribute\f[R]+.PP+By default, pandoc interprets material inside block-level tags as+Markdown.+This extension changes the behavior so that Markdown is only parsed+inside block-level tags if the tags have the attribute+\f[V]markdown=1\f[R].+.SS Extension: \f[V]mmd_title_block\f[R]+.PP+Enables a MultiMarkdown style title block at the top of the document,+for example:+.IP+.nf+\f[C]+Title:   My title+Author:  John Doe+Date:    September 1, 2008+Comment: This is a sample mmd title block, with+         a field spanning multiple lines.+\f[R]+.fi+.PP+See the MultiMarkdown documentation for details.+If \f[V]pandoc_title_block\f[R] or \f[V]yaml_metadata_block\f[R] is+enabled, it will take precedence over \f[V]mmd_title_block\f[R].+.SS Extension: \f[V]abbreviations\f[R]+.PP+Parses PHP Markdown Extra abbreviation keys, like+.IP+.nf+\f[C]+*[HTML]: Hypertext Markup Language+\f[R]+.fi+.PP+Note that the pandoc document model does not support abbreviations, so+if this extension is enabled, abbreviation keys are simply skipped (as+opposed to being parsed as paragraphs).+.SS Extension: \f[V]autolink_bare_uris\f[R]+.PP+Makes all absolute URIs into links, even when not surrounded by pointy+braces \f[V]<...>\f[R].+.SS Extension: \f[V]mmd_link_attributes\f[R]+.PP+Parses multimarkdown style key-value attributes on link and image+references.+This extension should not be confused with the \f[V]link_attributes\f[R]+extension.+.IP+.nf+\f[C]+This is a reference ![image][ref] with multimarkdown attributes.++[ref]: https://path.to/image \[dq]Image title\[dq] width=20px height=30px+       id=myId class=\[dq]myClass1 myClass2\[dq]+\f[R]+.fi+.SS Extension: \f[V]mmd_header_identifiers\f[R]+.PP+Parses multimarkdown style heading identifiers (in square brackets,+after the heading but before any trailing \f[V]#\f[R]s in an ATX+heading).+.SS Extension: \f[V]compact_definition_lists\f[R]+.PP+Activates the definition list syntax of pandoc 1.12.x and earlier.+This syntax differs from the one described above under Definition lists+in several respects:+.IP \[bu] 2+No blank line is required between consecutive items of the definition+list.+.IP \[bu] 2+To get a \[lq]tight\[rq] or \[lq]compact\[rq] list, omit space between+consecutive items; the space between a term and its definition does not+affect anything.+.IP \[bu] 2+Lazy wrapping of paragraphs is not allowed: the entire definition must+be indented four spaces.+.SS Extension: \f[V]gutenberg\f[R]+.PP+Use Project Gutenberg conventions for \f[V]plain\f[R] output: all-caps+for strong emphasis, surround by underscores for regular emphasis, add+extra blank space around headings.+.SS Extension: \f[V]sourcepos\f[R]+.PP+Include source position attributes when parsing \f[V]commonmark\f[R].+For elements that accept attributes, a \f[V]data-pos\f[R] attribute is+added; other elements are placed in a surrounding Div or Span element+with a \f[V]data-pos\f[R] attribute.+.SS Extension: \f[V]short_subsuperscripts\f[R]+.PP+Parse multimarkdown style subscripts and superscripts, which start with+a `\[ti]' or `\[ha]' character, respectively, and include the+alphanumeric sequence that follows.+For example:+.IP+.nf+\f[C]+x\[ha]2 = 4+\f[R]+.fi+.PP+or+.IP+.nf+\f[C]+Oxygen is O\[ti]2.+\f[R]+.fi+.SS Markdown variants+.PP+In addition to pandoc\[cq]s extended Markdown, the following Markdown+variants are supported:+.IP \[bu] 2+\f[V]markdown_phpextra\f[R] (PHP Markdown Extra)+.IP \[bu] 2+\f[V]markdown_github\f[R] (deprecated GitHub-Flavored Markdown)+.IP \[bu] 2+\f[V]markdown_mmd\f[R] (MultiMarkdown)+.IP \[bu] 2+\f[V]markdown_strict\f[R] (Markdown.pl)+.IP \[bu] 2+\f[V]commonmark\f[R] (CommonMark)+.IP \[bu] 2+\f[V]gfm\f[R] (Github-Flavored Markdown)+.IP \[bu] 2+\f[V]commonmark_x\f[R] (CommonMark with many pandoc extensions)+.PP+To see which extensions are supported for a given format, and which are+enabled by default, you can use the command+.IP+.nf+\f[C]+pandoc --list-extensions=FORMAT+\f[R]+.fi+.PP+where \f[V]FORMAT\f[R] is replaced with the name of the format.+.PP+Note that the list of extensions for \f[V]commonmark\f[R],+\f[V]gfm\f[R], and \f[V]commonmark_x\f[R] are defined relative to+default commonmark.+So, for example, \f[V]backtick_code_blocks\f[R] does not appear as an+extension, since it is enabled by default and cannot be disabled.+.SH CITATIONS+.PP+When the \f[V]--citeproc\f[R] option is used, pandoc can automatically+generate citations and a bibliography in a number of styles.+Basic usage is+.IP+.nf+\f[C]+pandoc --citeproc myinput.txt+\f[R]+.fi+.PP+To use this feature, you will need to have+.IP \[bu] 2+a document containing citations (see Extension: \f[V]citations\f[R]);+.IP \[bu] 2+a source of bibliographic data: either an external bibliography file or+a list of \f[V]references\f[R] in the document\[cq]s YAML metadata+.IP \[bu] 2+optionally, a CSL citation style.+.SS Specifying bibliographic data+.PP+You can specify an external bibliography using the+\f[V]bibliography\f[R] metadata field in a YAML metadata section or the+\f[V]--bibliography\f[R] command line argument.+If you want to use multiple bibliography files, you can supply multiple+\f[V]--bibliography\f[R] arguments or set \f[V]bibliography\f[R]+metadata field to YAML array.+A bibliography may have any of these formats:+.PP+.TS+tab(@);+l l.+T{+Format+T}@T{+File extension+T}+_+T{+BibLaTeX+T}@T{+\&.bib+T}+T{+BibTeX+T}@T{+\&.bibtex+T}+T{+CSL JSON+T}@T{+\&.json+T}+T{+CSL YAML+T}@T{+\&.yaml+T}+.TE+.PP+Note that \f[V].bib\f[R] can be used with both BibTeX and BibLaTeX+files; use the extension \f[V].bibtex\f[R] to force interpretation as+BibTeX.+.PP+In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside+fields such as \f[V]title\f[R]; in CSL YAML databases, pandoc Markdown;+and in CSL JSON databases, an HTML-like markup:+.TP+\f[V]<i>...</i>\f[R]+italics+.TP+\f[V]<b>...</b>\f[R]+bold+.TP+\f[V]<span style=\[dq]font-variant:small-caps;\[dq]>...</span>\f[R] or \f[V]<sc>...</sc>\f[R]+small capitals+.TP+\f[V]<sub>...</sub>\f[R]+subscript+.TP+\f[V]<sup>...</sup>\f[R]+superscript+.TP+\f[V]<span class=\[dq]nocase\[dq]>...</span>\f[R]+prevent a phrase from being capitalized as title case+.PP+As an alternative to specifying a bibliography file using+\f[V]--bibliography\f[R] or the YAML metadata field+\f[V]bibliography\f[R], you can include the citation data directly in+the \f[V]references\f[R] field of the document\[cq]s YAML metadata.+The field should contain an array of YAML-encoded references, for+example:+.IP+.nf+\f[C]+---+references:+- type: article-journal+  id: WatsonCrick1953+  author:+  - family: Watson+    given: J. D.+  - family: Crick+    given: F. H. C.+  issued:+    date-parts:+    - - 1953+      - 4+      - 25+  title: \[aq]Molecular structure of nucleic acids: a structure for+    deoxyribose nucleic acid\[aq]+  title-short: Molecular structure of nucleic acids+  container-title: Nature+  volume: 171+  issue: 4356+  page: 737-738+  DOI: 10.1038/171737a0+  URL: https://www.nature.com/articles/171737a0+  language: en-GB+\&...+\f[R]+.fi+.PP+If both an external bibliography and inline (YAML metadata) references+are provided, both will be used.+In case of conflicting \f[V]id\f[R]s, the inline references will take+precedence.+.PP+Note that pandoc can be used to produce such a YAML metadata section+from a BibTeX, BibLaTeX, or CSL JSON bibliography:+.IP+.nf+\f[C]+pandoc chem.bib -s -f biblatex -t markdown+pandoc chem.json -s -f csljson -t markdown+\f[R]+.fi+.PP+Indeed, pandoc can convert between any of these citation formats:+.IP+.nf+\f[C]+pandoc chem.bib -s -f biblatex -t csljson+pandoc chem.yaml -s -f markdown -t biblatex+\f[R]+.fi+.PP+Running pandoc on a bibliography file with the \f[V]--citeproc\f[R]+option will create a formatted bibliography in the format of your+choice:+.IP+.nf+\f[C]+pandoc chem.bib -s --citeproc -o chem.html+pandoc chem.bib -s --citeproc -o chem.pdf+\f[R]+.fi+.SS Capitalization in titles+.PP+If you are using a bibtex or biblatex bibliography, then observe the+following rules:+.IP \[bu] 2+English titles should be in title case.+Non-English titles should be in sentence case, and the \f[V]langid\f[R]+field in biblatex should be set to the relevant language.+(The following values are treated as English: \f[V]american\f[R],+\f[V]british\f[R], \f[V]canadian\f[R], \f[V]english\f[R],+\f[V]australian\f[R], \f[V]newzealand\f[R], \f[V]USenglish\f[R], or+\f[V]UKenglish\f[R].)+.IP \[bu] 2+As is standard with bibtex/biblatex, proper names should be protected+with curly braces so that they won\[cq]t be lowercased in styles that+call for sentence case.+For example:+.RS 2+.IP+.nf+\f[C]+title = {My Dinner with {Andre}}+\f[R]+.fi+.RE+.IP \[bu] 2+In addition, words that should remain lowercase (or camelCase) should be+protected:+.RS 2+.IP+.nf+\f[C]+title = {Spin Wave Dispersion on the {nm} Scale}+\f[R]+.fi+.PP+Though this is not necessary in bibtex/biblatex, it is necessary with+citeproc, which stores titles internally in sentence case, and converts+to title case in styles that require it.+Here we protect \[lq]nm\[rq] so that it doesn\[cq]t get converted to+\[lq]Nm\[rq] at this stage.+.RE+.PP+If you are using a CSL bibliography (either JSON or YAML), then observe+the following rules:+.IP \[bu] 2+All titles should be in sentence case.+.IP \[bu] 2+Use the \f[V]language\f[R] field for non-English titles to prevent their+conversion to title case in styles that call for this.+(Conversion happens only if \f[V]language\f[R] begins with \f[V]en\f[R]+or is left empty.)+.IP \[bu] 2+Protect words that should not be converted to title case using this+syntax:+.RS 2+.IP+.nf+\f[C]+Spin wave dispersion on the <span class=\[dq]nocase\[dq]>nm</span> scale+\f[R]+.fi+.RE+.SS Conference Papers, Published vs.\ Unpublished+.PP+For a formally published conference paper, use the biblatex entry type+\f[V]inproceedings\f[R] (which will be mapped to CSL+\f[V]paper-conference\f[R]).+.PP+For an unpublished manuscript, use the biblatex entry type+\f[V]unpublished\f[R] without an \f[V]eventtitle\f[R] field (this entry+type will be mapped to CSL \f[V]manuscript\f[R]).+.PP+For a talk, an unpublished conference paper, or a poster presentation,+use the biblatex entry type \f[V]unpublished\f[R] with an+\f[V]eventtitle\f[R] field (this entry type will be mapped to CSL+\f[V]speech\f[R]).+Use the biblatex \f[V]type\f[R] field to indicate the type,+e.g.\ \[lq]Paper\[rq], or \[lq]Poster\[rq].+\f[V]venue\f[R] and \f[V]eventdate\f[R] may be useful too, though+\f[V]eventdate\f[R] will not be rendered by most CSL styles.+Note that \f[V]venue\f[R] is for the event\[cq]s venue, unlike+\f[V]location\f[R] which describes the publisher\[cq]s location; do not+use the latter for an unpublished conference paper.+.SS Specifying a citation style+.PP+Citations and references can be formatted using any style supported by+the Citation Style Language, listed in the Zotero Style Repository.+These files are specified using the \f[V]--csl\f[R] option or the+\f[V]csl\f[R] (or \f[V]citation-style\f[R]) metadata field.+By default, pandoc will use the Chicago Manual of Style author-date+format.+(You can override this default by copying a CSL style of your choice to+\f[V]default.csl\f[R] in your user data directory.)+The CSL project provides further information on finding and editing+styles.+.PP+The \f[V]--citation-abbreviations\f[R] option (or the+\f[V]citation-abbreviations\f[R] metadata field) may be used to specify+a JSON file containing abbreviations of journals that should be used in+formatted bibliographies when \f[V]form=\[dq]short\[dq]\f[R] is+specified.+The format of the file can be illustrated with an example:+.IP+.nf+\f[C]+{ \[dq]default\[dq]: {+    \[dq]container-title\[dq]: {+            \[dq]Lloyd\[aq]s Law Reports\[dq]: \[dq]Lloyd\[aq]s Rep\[dq],+            \[dq]Estates Gazette\[dq]: \[dq]EG\[dq],+            \[dq]Scots Law Times\[dq]: \[dq]SLT\[dq]+    }+  }+}+\f[R]+.fi+.SS Citations in note styles+.PP+Pandoc\[cq]s citation processing is designed to allow you to move+between author-date, numerical, and note styles without modifying the+markdown source.+When you\[cq]re using a note style, avoid inserting footnotes manually.+Instead, insert citations just as you would in an author-date+style\[em]for example,+.IP+.nf+\f[C]+Blah blah [\[at]foo, p. 33].+\f[R]+.fi+.PP+The footnote will be created automatically.+Pandoc will take care of removing the space and moving the note before+or after the period, depending on the setting of+\f[V]notes-after-punctuation\f[R], as described below in Other relevant+metadata fields.+.PP+In some cases you may need to put a citation inside a regular footnote.+Normal citations in footnotes (such as \f[V][\[at]foo, p. 33]\f[R]) will+be rendered in parentheses.+In-text citations (such as \f[V]\[at]foo [p. 33]\f[R]) will be rendered+without parentheses.+(A comma will be added if appropriate.)+Thus:+.IP+.nf+\f[C]+[\[ha]1]:  Some studies [\[at]foo; \[at]bar, p. 33] show that+frubulicious zoosnaps are quantical.  For a survey+of the literature, see \[at]baz [chap. 1].+\f[R]+.fi+.SS Raw content in a style+.PP+To include raw content in a prefix, suffix, delimiter, or term, surround+it with these tags indicating the format:+.IP+.nf+\f[C]+{{jats}}&lt;ref&gt;{{/jats}}+\f[R]+.fi+.PP+Without the tags, the string will be interpreted as a string and escaped+in the output, rather than being passed through raw.+.PP+This feature allows stylesheets to be customized to give different+output for different output formats.+However, stylesheets customized in this way will not be usable by other+CSL implementations.+.SS Placement of the bibliography+.PP+If the style calls for a list of works cited, it will be placed in a div+with id \f[V]refs\f[R], if one exists:+.IP+.nf+\f[C]+::: {#refs}+:::+\f[R]+.fi+.PP+Otherwise, it will be placed at the end of the document.+Generation of the bibliography can be suppressed by setting+\f[V]suppress-bibliography: true\f[R] in the YAML metadata.+.PP+If you wish the bibliography to have a section heading, you can set+\f[V]reference-section-title\f[R] in the metadata, or put the heading at+the beginning of the div with id \f[V]refs\f[R] (if you are using it) or+at the end of your document:+.IP+.nf+\f[C]+last paragraph...++# References+\f[R]+.fi+.PP+The bibliography will be inserted after this heading.+Note that the \f[V]unnumbered\f[R] class will be added to this heading,+so that the section will not be numbered.+.SS Including uncited items in the bibliography+.PP+If you want to include items in the bibliography without actually citing+them in the body text, you can define a dummy \f[V]nocite\f[R] metadata+field and put the citations there:+.IP+.nf+\f[C]+---+nocite: |+  \[at]item1, \[at]item2+\&...++\[at]item3+\f[R]+.fi+.PP+In this example, the document will contain a citation for+\f[V]item3\f[R] only, but the bibliography will contain entries for+\f[V]item1\f[R], \f[V]item2\f[R], and \f[V]item3\f[R].+.PP+It is possible to create a bibliography with all the citations, whether+or not they appear in the document, by using a wildcard:+.IP+.nf+\f[C]+---+nocite: |+  \[at]*+\&...+\f[R]+.fi+.PP+For LaTeX output, you can also use \f[V]natbib\f[R] or+\f[V]biblatex\f[R] to render the bibliography.+In order to do so, specify bibliography files as outlined above, and add+\f[V]--natbib\f[R] or \f[V]--biblatex\f[R] argument to pandoc+invocation.+Bear in mind that bibliography files have to be in either BibTeX (for+\f[V]--natbib\f[R]) or BibLaTeX (for \f[V]--biblatex\f[R]) format.+.SS Other relevant metadata fields+.PP+A few other metadata fields affect bibliography formatting:+.TP+\f[V]link-citations\f[R]+If true, citations will be hyperlinked to the corresponding bibliography+entries (for author-date and numerical styles only).+Defaults to false.+.TP+\f[V]link-bibliography\f[R]+If true, DOIs, PMCIDs, PMID, and URLs in bibliographies will be rendered+as hyperlinks.+(If an entry contains a DOI, PMCID, PMID, or URL, but none of these+fields are rendered by the style, then the title, or in the absence of a+title the whole entry, will be hyperlinked.)+Defaults to true.+.TP+\f[V]lang\f[R]+The \f[V]lang\f[R] field will affect how the style is localized, for+example in the translation of labels, the use of quotation marks, and+the way items are sorted.+(For backwards compatibility, \f[V]locale\f[R] may be used instead of+\f[V]lang\f[R], but this use is deprecated.)+.RS+.PP+A BCP 47 language tag is expected: for example, \f[V]en\f[R],+\f[V]de\f[R], \f[V]en-US\f[R], \f[V]fr-CA\f[R], \f[V]ug-Cyrl\f[R].+The unicode extension syntax (after \f[V]-u-\f[R]) may be used to+specify options for collation (sorting) more precisely.+Here are some examples:+.IP \[bu] 2+\f[V]zh-u-co-pinyin\f[R] \[en] Chinese with the Pinyin collation.+.IP \[bu] 2+\f[V]es-u-co-trad\f[R] \[en] Spanish with the traditional collation+(with \f[V]Ch\f[R] sorting after \f[V]C\f[R]).+.IP \[bu] 2+\f[V]fr-u-kb\f[R] \[en] French with \[lq]backwards\[rq] accent sorting+(with \f[V]cot\['e]\f[R] sorting after \f[V]c\[^o]te\f[R]).+.IP \[bu] 2+\f[V]en-US-u-kf-upper\f[R] \[en] English with uppercase letters sorting+before lower (default is lower before upper).+.RE+.TP+\f[V]notes-after-punctuation\f[R]+If true (the default for note styles), pandoc will put footnote+references or superscripted numerical citations after following+punctuation.+For example, if the source contains \f[V]blah blah [\[at]jones99].\f[R],+the result will look like \f[V]blah blah.[\[ha]1]\f[R], with the note+moved after the period and the space collapsed.+If false, the space will still be collapsed, but the footnote will not+be moved after the punctuation.+The option may also be used in numerical styles that use superscripts+for citation numbers (but for these styles the default is not to move+the citation).+.SH SLIDE SHOWS+.PP+You can use pandoc to produce an HTML + JavaScript slide presentation+that can be viewed via a web browser.+There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or+reveal.js.+You can also produce a PDF slide show using LaTeX \f[V]beamer\f[R], or+slides shows in Microsoft PowerPoint format.+.PP+Here\[cq]s the Markdown source for a simple slide show,+\f[V]habits.txt\f[R]:+.IP+.nf+\f[C]+% Habits+% John Doe+% March 22, 2005++# In the morning++## Getting up++- Turn off alarm+- Get out of bed++## Breakfast++- Eat eggs+- Drink coffee++# In the evening++## Dinner++- Eat spaghetti+- Drink wine++------------------++![picture of spaghetti](images/spaghetti.jpg)++## Going to sleep++- Get in bed+- Count sheep+\f[R]+.fi+.PP+To produce an HTML/JavaScript slide show, simply type+.IP+.nf+\f[C]+pandoc -t FORMAT -s habits.txt -o habits.html+\f[R]+.fi+.PP+where \f[V]FORMAT\f[R] is either \f[V]s5\f[R], \f[V]slidy\f[R],+\f[V]slideous\f[R], \f[V]dzslides\f[R], or \f[V]revealjs\f[R].+.PP+For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with+the \f[V]-s/--standalone\f[R] option embeds a link to JavaScript and CSS+files, which are assumed to be available at the relative path+\f[V]s5/default\f[R] (for S5), \f[V]slideous\f[R] (for Slideous),+\f[V]reveal.js\f[R] (for reveal.js), or at the Slidy website at+\f[V]w3.org\f[R] (for Slidy).+(These paths can be changed by setting the \f[V]slidy-url\f[R],+\f[V]slideous-url\f[R], \f[V]revealjs-url\f[R], or \f[V]s5-url\f[R]+variables; see Variables for HTML slides, above.)+For DZSlides, the (relatively short) JavaScript and CSS are included in+the file by default.+.PP+With all HTML slide formats, the \f[V]--self-contained\f[R] option can+be used to produce a single file that contains all of the data necessary+to display the slide show, including linked scripts, stylesheets,+images, and videos.+.PP+To produce a PDF slide show using beamer, type+.IP+.nf+\f[C]+pandoc -t beamer habits.txt -o habits.pdf+\f[R]+.fi+.PP+Note that a reveal.js slide show can also be converted to a PDF by+printing it to a file from the browser.+.PP+To produce a Powerpoint slide show, type+.IP+.nf+\f[C]+pandoc habits.txt -o habits.pptx+\f[R]+.fi+.SS Structuring the slide show+.PP+By default, the \f[I]slide level\f[R] is the highest heading level in+the hierarchy that is followed immediately by content, and not another+heading, somewhere in the document.+In the example above, level-1 headings are always followed by level-2+headings, which are followed by content, so the slide level is 2.+This default can be overridden using the \f[V]--slide-level\f[R] option.+.PP+The document is carved up into slides according to the following rules:+.IP \[bu] 2+A horizontal rule always starts a new slide.+.IP \[bu] 2+A heading at the slide level always starts a new slide.+.IP \[bu] 2+Headings \f[I]below\f[R] the slide level in the hierarchy create+headings \f[I]within\f[R] a slide.+(In beamer, a \[lq]block\[rq] will be created.+If the heading has the class \f[V]example\f[R], an+\f[V]exampleblock\f[R] environment will be used; if it has the class+\f[V]alert\f[R], an \f[V]alertblock\f[R] will be used; otherwise a+regular \f[V]block\f[R] will be used.)+.IP \[bu] 2+Headings \f[I]above\f[R] the slide level in the hierarchy create+\[lq]title slides,\[rq] which just contain the section title and help to+break the slide show into sections.+Non-slide content under these headings will be included on the title+slide (for HTML slide shows) or in a subsequent slide with the same+title (for beamer).+.IP \[bu] 2+A title page is constructed automatically from the document\[cq]s title+block, if present.+(In the case of beamer, this can be disabled by commenting out some+lines in the default template.)+.PP+These rules are designed to support many different styles of slide show.+If you don\[cq]t care about structuring your slides into sections and+subsections, you can either just use level-1 headings for all slides (in+that case, level 1 will be the slide level) or you can set+\f[V]--slide-level=0\f[R].+.PP+Note: in reveal.js slide shows, if slide level is 2, a two-dimensional+layout will be produced, with level-1 headings building horizontally and+level-2 headings building vertically.+It is not recommended that you use deeper nesting of section levels with+reveal.js unless you set \f[V]--slide-level=0\f[R] (which lets reveal.js+produce a one-dimensional layout and only interprets horizontal rules as+slide boundaries).+.SS PowerPoint layout choice+.PP+When creating slides, the pptx writer chooses from a number of+pre-defined layouts, based on the content of the slide:+.TP+Title Slide+This layout is used for the initial slide, which is generated and filled+from the metadata fields \f[V]date\f[R], \f[V]author\f[R], and+\f[V]title\f[R], if they are present.+.TP+Section Header+This layout is used for what pandoc calls \[lq]title slides\[rq], i.e.+slides which start with a header which is above the slide level in the+hierarchy.+.TP+Two Content+This layout is used for two-column slides, i.e.\ slides containing a div+with class \f[V]columns\f[R] which contains at least two divs with class+\f[V]column\f[R].+.TP+Comparison+This layout is used instead of \[lq]Two Content\[rq] for any two-column+slides in which at least one column contains text followed by non-text+(e.g.\ an image or a table).+.TP+Content with Caption+This layout is used for any non-two-column slides which contain text+followed by non-text (e.g.\ an image or a table).+.TP+Blank+This layout is used for any slides which only contain blank content,+e.g.\ a slide containing only speaker notes, or a slide containing only+a non-breaking space.+.TP+Title and Content+This layout is used for all slides which do not match the criteria for+another layout.+.PP+These layouts are chosen from the default pptx reference doc included+with pandoc, unless an alternative reference doc is specified using+\f[V]--reference-doc\f[R].+.SS Incremental lists+.PP+By default, these writers produce lists that display \[lq]all at+once.\[rq] If you want your lists to display incrementally (one item at+a time), use the \f[V]-i\f[R] option.+If you want a particular list to depart from the default, put it in a+\f[V]div\f[R] block with class \f[V]incremental\f[R] or+\f[V]nonincremental\f[R].+So, for example, using the \f[V]fenced div\f[R] syntax, the following+would be incremental regardless of the document default:+.IP+.nf+\f[C]+::: incremental++- Eat spaghetti+- Drink wine++:::+\f[R]+.fi+.PP+or+.IP+.nf+\f[C]+::: nonincremental++- Eat spaghetti+- Drink wine++:::+\f[R]+.fi+.PP+While using \f[V]incremental\f[R] and \f[V]nonincremental\f[R] divs are+the recommended method of setting incremental lists on a per-case basis,+an older method is also supported: putting lists inside a blockquote+will depart from the document default (that is, it will display+incrementally without the \f[V]-i\f[R] option and all at once with the+\f[V]-i\f[R] option):+.IP+.nf+\f[C]+> - Eat spaghetti+> - Drink wine+\f[R]+.fi+.PP+Both methods allow incremental and nonincremental lists to be mixed in a+single document.+.SS Inserting pauses+.PP+You can add \[lq]pauses\[rq] within a slide by including a paragraph+containing three dots, separated by spaces:+.IP+.nf+\f[C]+# Slide with a pause++content before the pause++\&. . .++content after the pause+\f[R]+.fi+.PP+Note: this feature is not yet implemented for PowerPoint output.+.SS Styling the slides+.PP+You can change the style of HTML slides by putting customized CSS files+in \f[V]$DATADIR/s5/default\f[R] (for S5), \f[V]$DATADIR/slidy\f[R] (for+Slidy), or \f[V]$DATADIR/slideous\f[R] (for Slideous), where+\f[V]$DATADIR\f[R] is the user data directory (see \f[V]--data-dir\f[R],+above).+The originals may be found in pandoc\[cq]s system data directory+(generally \f[V]$CABALDIR/pandoc-VERSION/s5/default\f[R]).+Pandoc will look there for any files it does not find in the user data+directory.+.PP+For dzslides, the CSS is included in the HTML file itself, and may be+modified there.+.PP+All reveal.js configuration options can be set through variables.+For example, themes can be used by setting the \f[V]theme\f[R] variable:+.IP+.nf+\f[C]+-V theme=moon+\f[R]+.fi+.PP+Or you can specify a custom stylesheet using the \f[V]--css\f[R] option.+.PP+To style beamer slides, you can specify a \f[V]theme\f[R],+\f[V]colortheme\f[R], \f[V]fonttheme\f[R], \f[V]innertheme\f[R], and+\f[V]outertheme\f[R], using the \f[V]-V\f[R] option:+.IP+.nf+\f[C]+pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf+\f[R]+.fi+.PP+Note that heading attributes will turn into slide attributes (on a+\f[V]<div>\f[R] or \f[V]<section>\f[R]) in HTML slide formats, allowing+you to style individual slides.+In beamer, a number of heading classes and attributes are recognized as+frame options and will be passed through as options to the frame: see+Frame attributes in beamer, below.+.SS Speaker notes+.PP+Speaker notes are supported in reveal.js, PowerPoint (pptx), and beamer+output.+You can add notes to your Markdown document thus:+.IP+.nf+\f[C]+::: notes++This is my note.++- It can contain Markdown+- like this list++:::+\f[R]+.fi+.PP+To show the notes window in reveal.js, press \f[V]s\f[R] while viewing+the presentation.+Speaker notes in PowerPoint will be available, as usual, in handouts and+presenter view.+.PP+Notes are not yet supported for other slide formats, but the notes will+not appear on the slides themselves.+.SS Columns+.PP+To put material in side by side columns, you can use a native div+container with class \f[V]columns\f[R], containing two or more div+containers with class \f[V]column\f[R] and a \f[V]width\f[R] attribute:+.IP+.nf+\f[C]+:::::::::::::: {.columns}+::: {.column width=\[dq]40%\[dq]}+contents...+:::+::: {.column width=\[dq]60%\[dq]}+contents...+:::+::::::::::::::+\f[R]+.fi+.SS Additional columns attributes in beamer+.PP+The div containers with classes \f[V]columns\f[R] and \f[V]column\f[R]+can optionally have an \f[V]align\f[R] attribute.+The class \f[V]columns\f[R] can optionally have a \f[V]totalwidth\f[R]+attribute or an \f[V]onlytextwidth\f[R] class.+.IP+.nf+\f[C]+:::::::::::::: {.columns align=center totalwidth=8em}+::: {.column width=\[dq]40%\[dq]}+contents...+:::+::: {.column width=\[dq]60%\[dq] align=bottom}+contents...+:::+::::::::::::::+\f[R]+.fi+.PP+The \f[V]align\f[R] attributes on \f[V]columns\f[R] and \f[V]column\f[R]+can be used with the values \f[V]top\f[R], \f[V]top-baseline\f[R],+\f[V]center\f[R] and \f[V]bottom\f[R] to vertically align the columns.+It defaults to \f[V]top\f[R] in \f[V]columns\f[R].+.PP+The \f[V]totalwidth\f[R] attribute limits the width of the columns to+the given value.+.IP+.nf+\f[C]+:::::::::::::: {.columns align=top .onlytextwidth}+::: {.column width=\[dq]40%\[dq] align=center}+contents...+:::+::: {.column width=\[dq]60%\[dq]}+contents...+:::+::::::::::::::+\f[R]+.fi+.PP+The class \f[V]onlytextwidth\f[R] sets the \f[V]totalwidth\f[R] to+\f[V]\[rs]textwidth\f[R].+.PP+See Section 12.7 of the Beamer User\[cq]s Guide for more details.+.SS Frame attributes in beamer+.PP+Sometimes it is necessary to add the LaTeX \f[V][fragile]\f[R] option to+a frame in beamer (for example, when using the \f[V]minted\f[R]+environment).+This can be forced by adding the \f[V]fragile\f[R] class to the heading+introducing the slide:+.IP+.nf+\f[C]+# Fragile slide {.fragile}+\f[R]+.fi+.PP+All of the other frame attributes described in Section 8.1 of the Beamer+User\[cq]s Guide may also be used: \f[V]allowdisplaybreaks\f[R],+\f[V]allowframebreaks\f[R], \f[V]b\f[R], \f[V]c\f[R], \f[V]s\f[R],+\f[V]t\f[R], \f[V]environment\f[R], \f[V]label\f[R], \f[V]plain\f[R],+\f[V]shrink\f[R], \f[V]standout\f[R], \f[V]noframenumbering\f[R],+\f[V]squeeze\f[R].+\f[V]allowframebreaks\f[R] is recommended especially for bibliographies,+as it allows multiple slides to be created if the content overfills the+frame:+.IP+.nf+\f[C]+# References {.allowframebreaks}+\f[R]+.fi+.PP+In addition, the \f[V]frameoptions\f[R] attribute may be used to pass+arbitrary frame options to a beamer slide:+.IP+.nf+\f[C]+# Heading {frameoptions=\[dq]squeeze,shrink,customoption=foobar\[dq]}+\f[R]+.fi+.SS Background in reveal.js, beamer, and pptx+.PP+Background images can be added to self-contained reveal.js slide shows,+beamer slide shows, and pptx slide shows.+.SS On all slides (beamer, reveal.js, pptx)+.PP+With beamer and reveal.js, the configuration option+\f[V]background-image\f[R] can be used either in the YAML metadata block+or as a command-line variable to get the same image on every slide.+.PP+For pptx, you can use a reference doc in which background images have+been set on the relevant layouts.+.SS \f[V]parallaxBackgroundImage\f[R] (reveal.js)+.PP+For reveal.js, there is also the reveal.js-native option+\f[V]parallaxBackgroundImage\f[R], which can be used instead of+\f[V]background-image\f[R] to produce a parallax scrolling background.+You must also set \f[V]parallaxBackgroundSize\f[R], and can optionally+set \f[V]parallaxBackgroundHorizontal\f[R] and+\f[V]parallaxBackgroundVertical\f[R] to configure the scrolling+behaviour.+See the reveal.js documentation for more details about the meaning of+these options.+.PP+In reveal.js\[cq]s overview mode, the parallaxBackgroundImage will show+up only on the first slide.+.SS On individual slides (reveal.js, pptx)+.PP+To set an image for a particular reveal.js or pptx slide, add+\f[V]{background-image=\[dq]/path/to/image\[dq]}\f[R] to the first+slide-level heading on the slide (which may even be empty).+.PP+As the HTML writers pass unknown attributes through, other reveal.js+background settings also work on individual slides, including+\f[V]background-size\f[R], \f[V]background-repeat\f[R],+\f[V]background-color\f[R], \f[V]transition\f[R], and+\f[V]transition-speed\f[R].+(The \f[V]data-\f[R] prefix will automatically be added.)+.PP+Note: \f[V]data-background-image\f[R] is also supported in pptx for+consistency with reveal.js \[en] if \f[V]background-image\f[R] isn\[cq]t+found, \f[V]data-background-image\f[R] will be checked.+.SS On the title slide (reveal.js, pptx)+.PP+To add a background image to the automatically generated title slide for+reveal.js, use the \f[V]title-slide-attributes\f[R] variable in the YAML+metadata block.+It must contain a map of attribute names and values.+(Note that the \f[V]data-\f[R] prefix is required here, as it isn\[cq]t+added automatically.)+.PP+For pptx, pass a reference doc with the background image set on the+\[lq]Title Slide\[rq] layout.+.SS Example (reveal.js)+.IP+.nf+\f[C]+---+title: My Slide Show+parallaxBackgroundImage: /path/to/my/background_image.png+title-slide-attributes:+    data-background-image: /path/to/title_image.png+    data-background-size: contain+---++## Slide One++Slide 1 has background_image.png as its background.++## {background-image=\[dq]/path/to/special_image.jpg\[dq]}++Slide 2 has a special image for its background, even though the heading has no content.+\f[R]+.fi+.SH EPUBS+.SS EPUB Metadata+.PP+EPUB metadata may be specified using the \f[V]--epub-metadata\f[R]+option, but if the source document is Markdown, it is better to use a+YAML metadata block.+Here is an example:+.IP+.nf+\f[C]+---+title:+- type: main+  text: My Book+- type: subtitle+  text: An investigation of metadata+creator:+- role: author+  text: John Smith+- role: editor+  text: Sarah Jones+identifier:+- scheme: DOI+  text: doi:10.234234.234/33+publisher:  My Press+rights: \[co] 2007 John Smith, CC BY-NC+ibooks:+  version: 1.3.4+\&...+\f[R]+.fi+.PP+The following fields are recognized:+.TP+\f[V]identifier\f[R]+Either a string value or an object with fields \f[V]text\f[R] and+\f[V]scheme\f[R].+Valid values for \f[V]scheme\f[R] are \f[V]ISBN-10\f[R],+\f[V]GTIN-13\f[R], \f[V]UPC\f[R], \f[V]ISMN-10\f[R], \f[V]DOI\f[R],+\f[V]LCCN\f[R], \f[V]GTIN-14\f[R], \f[V]ISBN-13\f[R],+\f[V]Legal deposit number\f[R], \f[V]URN\f[R], \f[V]OCLC\f[R],+\f[V]ISMN-13\f[R], \f[V]ISBN-A\f[R], \f[V]JP\f[R], \f[V]OLCC\f[R].+.TP+\f[V]title\f[R]+Either a string value, or an object with fields \f[V]file-as\f[R] and+\f[V]type\f[R], or a list of such objects.+Valid values for \f[V]type\f[R] are \f[V]main\f[R], \f[V]subtitle\f[R],+\f[V]short\f[R], \f[V]collection\f[R], \f[V]edition\f[R],+\f[V]extended\f[R].+.TP+\f[V]creator\f[R]+Either a string value, or an object with fields \f[V]role\f[R],+\f[V]file-as\f[R], and \f[V]text\f[R], or a list of such objects.+Valid values for \f[V]role\f[R] are MARC relators, but pandoc will+attempt to translate the human-readable versions (like \[lq]author\[rq]+and \[lq]editor\[rq]) to the appropriate marc relators.+.TP+\f[V]contributor\f[R]+Same format as \f[V]creator\f[R].+.TP+\f[V]date\f[R]+A string value in \f[V]YYYY-MM-DD\f[R] format.+(Only the year is necessary.)+Pandoc will attempt to convert other common date formats.+.TP+\f[V]lang\f[R] (or legacy: \f[V]language\f[R])+A string value in BCP 47 format.+Pandoc will default to the local language if nothing is specified.+.TP+\f[V]subject\f[R]+Either a string value, or an object with fields \f[V]text\f[R],+\f[V]authority\f[R], and \f[V]term\f[R], or a list of such objects.+Valid values for \f[V]authority\f[R] are either a reserved authority+value (currently \f[V]AAT\f[R], \f[V]BIC\f[R], \f[V]BISAC\f[R],+\f[V]CLC\f[R], \f[V]DDC\f[R], \f[V]CLIL\f[R], \f[V]EuroVoc\f[R],+\f[V]MEDTOP\f[R], \f[V]LCSH\f[R], \f[V]NDC\f[R], \f[V]Thema\f[R],+\f[V]UDC\f[R], and \f[V]WGS\f[R]) or an absolute IRI identifying a+custom scheme.+Valid values for \f[V]term\f[R] are defined by the scheme.+.TP+\f[V]description\f[R]+A string value.+.TP+\f[V]type\f[R]+A string value.+.TP+\f[V]format\f[R]+A string value.+.TP+\f[V]relation\f[R]+A string value.+.TP+\f[V]coverage\f[R]+A string value.+.TP+\f[V]rights\f[R]+A string value.+.TP+\f[V]belongs-to-collection\f[R]+A string value.+identifies the name of a collection to which the EPUB Publication+belongs.+.TP+\f[V]group-position\f[R]+The \f[V]group-position\f[R] field indicates the numeric position in+which the EPUB Publication belongs relative to other works belonging to+the same \f[V]belongs-to-collection\f[R] field.+.TP+\f[V]cover-image\f[R]+A string value (path to cover image).+.TP+\f[V]css\f[R] (or legacy: \f[V]stylesheet\f[R])+A string value (path to CSS stylesheet).+.TP+\f[V]page-progression-direction\f[R]+Either \f[V]ltr\f[R] or \f[V]rtl\f[R].+Specifies the \f[V]page-progression-direction\f[R] attribute for the+\f[V]spine\f[R] element.+.TP+\f[V]ibooks\f[R]+iBooks-specific metadata, with the following fields:+.RS+.IP \[bu] 2+\f[V]version\f[R]: (string)+.IP \[bu] 2+\f[V]specified-fonts\f[R]: \f[V]true\f[R]|\f[V]false\f[R] (default+\f[V]false\f[R])+.IP \[bu] 2+\f[V]ipad-orientation-lock\f[R]:+\f[V]portrait-only\f[R]|\f[V]landscape-only\f[R]+.IP \[bu] 2+\f[V]iphone-orientation-lock\f[R]:+\f[V]portrait-only\f[R]|\f[V]landscape-only\f[R]+.IP \[bu] 2+\f[V]binding\f[R]: \f[V]true\f[R]|\f[V]false\f[R] (default+\f[V]true\f[R])+.IP \[bu] 2+\f[V]scroll-axis\f[R]:+\f[V]vertical\f[R]|\f[V]horizontal\f[R]|\f[V]default\f[R]+.RE+.SS The \f[V]epub:type\f[R] attribute+.PP+For \f[V]epub3\f[R] output, you can mark up the heading that corresponds+to an EPUB chapter using the \f[V]epub:type\f[R] attribute.+For example, to set the attribute to the value \f[V]prologue\f[R], use+this markdown:+.IP+.nf+\f[C]+# My chapter {epub:type=prologue}+\f[R]+.fi+.PP+Which will result in:+.IP+.nf+\f[C]+<body epub:type=\[dq]frontmatter\[dq]>+  <section epub:type=\[dq]prologue\[dq]>+    <h1>My chapter</h1>+\f[R]+.fi+.PP+Pandoc will output \f[V]<body epub:type=\[dq]bodymatter\[dq]>\f[R],+unless you use one of the following values, in which case either+\f[V]frontmatter\f[R] or \f[V]backmatter\f[R] will be output.+.PP+.TS+tab(@);+l l.+T{+\f[V]epub:type\f[R] of first section+T}@T{+\f[V]epub:type\f[R] of body+T}+_+T{+prologue+T}@T{+frontmatter+T}+T{+abstract+T}@T{+frontmatter+T}+T{+acknowledgments+T}@T{+frontmatter+T}+T{+copyright-page+T}@T{+frontmatter+T}+T{+dedication+T}@T{+frontmatter+T}+T{+credits+T}@T{+frontmatter+T}+T{+keywords+T}@T{+frontmatter+T}+T{+imprint+T}@T{+frontmatter+T}+T{+contributors+T}@T{+frontmatter+T}+T{+other-credits+T}@T{+frontmatter+T}+T{+errata+T}@T{+frontmatter+T}+T{+revision-history+T}@T{+frontmatter+T}+T{+titlepage+T}@T{+frontmatter+T}+T{+halftitlepage+T}@T{+frontmatter+T}+T{+seriespage+T}@T{+frontmatter+T}+T{+foreword+T}@T{+frontmatter+T}+T{+preface+T}@T{+frontmatter+T}+T{+frontispiece+T}@T{+frontmatter+T}+T{+appendix+T}@T{+backmatter+T}+T{+colophon+T}@T{+backmatter+T}+T{+bibliography+T}@T{+backmatter+T}+T{+index+T}@T{+backmatter+T}+.TE+.SS Linked media+.PP+By default, pandoc will download media referenced from any+\f[V]<img>\f[R], \f[V]<audio>\f[R], \f[V]<video>\f[R] or+\f[V]<source>\f[R] element present in the generated EPUB, and include it+in the EPUB container, yielding a completely self-contained EPUB.+If you want to link to external media resources instead, use raw HTML in+your source and add \f[V]data-external=\[dq]1\[dq]\f[R] to the tag with+the \f[V]src\f[R] attribute.+For example:+.IP+.nf+\f[C]+<audio controls=\[dq]1\[dq]>+  <source src=\[dq]https://example.com/music/toccata.mp3\[dq]+          data-external=\[dq]1\[dq] type=\[dq]audio/mpeg\[dq]>+  </source>+</audio>+\f[R]+.fi+.PP+If the input format already is HTML then+\f[V]data-external=\[dq]1\[dq]\f[R] will work as expected for+\f[V]<img>\f[R] elements.+Similarly, for Markdown, external images can be declared with+\f[V]![img](url){external=1}\f[R].+Note that this only works for images; the other media elements have no+native representation in pandoc\[cq]s AST and requires the use of raw+HTML.+.SS EPUB styling+.PP+By default, pandoc will include some basic styling contained in its+\f[V]epub.css\f[R] data file.+(To see this, use \f[V]pandoc --print-default-data-file epub.css\f[R].)+To use a different CSS file, just use the \f[V]--css\f[R] command line+option.+A few inline styles are defined in addition; these are essential for+correct formatting of pandoc\[cq]s HTML output.+.PP+The \f[V]document-css\f[R] variable may be set if the more opinionated+styling of pandoc\[cq]s default HTML templates is desired (and in that+case the variables defined in Variables for HTML may be used to+fine-tune the style).+.SH JUPYTER NOTEBOOKS+.PP+When creating a Jupyter notebook, pandoc will try to infer the notebook+structure.+Code blocks with the class \f[V]code\f[R] will be taken as code cells,+and intervening content will be taken as Markdown cells.+Attachments will automatically be created for images in Markdown cells.+Metadata will be taken from the \f[V]jupyter\f[R] metadata field.+For example:+.IP+.nf+\f[C]+---+title: My notebook+jupyter:+  nbformat: 4+  nbformat_minor: 5+  kernelspec:+     display_name: Python 2+     language: python+     name: python2+  language_info:+     codemirror_mode:+       name: ipython+       version: 2+     file_extension: \[dq].py\[dq]+     mimetype: \[dq]text/x-python\[dq]+     name: \[dq]python\[dq]+     nbconvert_exporter: \[dq]python\[dq]+     pygments_lexer: \[dq]ipython2\[dq]+     version: \[dq]2.7.15\[dq]+---++# Lorem ipsum++**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus+bibendum felis dictum sodales.++\[ga]\[ga]\[ga] code+print(\[dq]hello\[dq])+\[ga]\[ga]\[ga]++## Pyout++\[ga]\[ga]\[ga] code+from IPython.display import HTML+HTML(\[dq]\[dq]\[dq]+<script>+console.log(\[dq]hello\[dq]);+</script>+<b>HTML</b>+\[dq]\[dq]\[dq])+\[ga]\[ga]\[ga]++## Image++This image ![image](myimage.png) will be+included as a cell attachment.+\f[R]+.fi+.PP+If you want to add cell attributes, group cells differently, or add+output to code cells, then you need to include divs to indicate the+structure.+You can use either fenced divs or native divs for this.+Here is an example:+.IP+.nf+\f[C]+:::::: {.cell .markdown}+# Lorem++**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus+bibendum felis dictum sodales.+::::::++:::::: {.cell .code execution_count=1}+\[ga]\[ga]\[ga] {.python}+print(\[dq]hello\[dq])+\[ga]\[ga]\[ga]++::: {.output .stream .stdout}+\[ga]\[ga]\[ga]+hello+\[ga]\[ga]\[ga]+:::+::::::++:::::: {.cell .code execution_count=2}+\[ga]\[ga]\[ga] {.python}+from IPython.display import HTML+HTML(\[dq]\[dq]\[dq]+<script>+console.log(\[dq]hello\[dq]);+</script>+<b>HTML</b>+\[dq]\[dq]\[dq])+\[ga]\[ga]\[ga]++::: {.output .execute_result execution_count=2}+\[ga]\[ga]\[ga]{=html}+<script>+console.log(\[dq]hello\[dq]);+</script>+<b>HTML</b>+hello+\[ga]\[ga]\[ga]+:::+::::::+\f[R]+.fi+.PP+If you include raw HTML or TeX in an output cell, use the [raw+attribute][Extension: \f[V]fenced_attribute\f[R]], as shown in the last+cell of the example above.+Although pandoc can process \[lq]bare\[rq] raw HTML and TeX, the result+is often interspersed raw elements and normal textual elements, and in+an output cell pandoc expects a single, connected raw block.+To avoid using raw HTML or TeX except when marked explicitly using raw+attributes, we recommend specifying the extensions+\f[V]-raw_html-raw_tex+raw_attribute\f[R] when translating between+Markdown and ipynb notebooks.+.PP+Note that options and extensions that affect reading and writing of+Markdown will also affect Markdown cells in ipynb notebooks.+For example, \f[V]--wrap=preserve\f[R] will preserve soft line breaks in+Markdown cells; \f[V]--atx-headers\f[R] will cause ATX-style headings to+be used; and \f[V]--preserve-tabs\f[R] will prevent tabs from being+turned to spaces.+.SH SYNTAX HIGHLIGHTING+.PP+Pandoc will automatically highlight syntax in fenced code blocks that+are marked with a language name.+The Haskell library skylighting is used for highlighting.+Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and+LaTeX/PDF output.+To see a list of language names that pandoc will recognize, type+\f[V]pandoc --list-highlight-languages\f[R].+.PP+The color scheme can be selected using the \f[V]--highlight-style\f[R]+option.+The default color scheme is \f[V]pygments\f[R], which imitates the+default color scheme used by the Python library pygments (though+pygments is not actually used to do the highlighting).+To see a list of highlight styles, type+\f[V]pandoc --list-highlight-styles\f[R].+.PP+If you are not satisfied with the predefined styles, you can use+\f[V]--print-highlight-style\f[R] to generate a JSON \f[V].theme\f[R]+file which can be modified and used as the argument to+\f[V]--highlight-style\f[R].+To get a JSON version of the \f[V]pygments\f[R] style, for example:+.IP+.nf+\f[C]+pandoc --print-highlight-style pygments > my.theme+\f[R]+.fi+.PP+Then edit \f[V]my.theme\f[R] and use it like this:+.IP+.nf+\f[C]+pandoc --highlight-style my.theme+\f[R]+.fi+.PP+If you are not satisfied with the built-in highlighting, or you want+highlight a language that isn\[cq]t supported, you can use the+\f[V]--syntax-definition\f[R] option to load a KDE-style XML syntax+definition file.+Before writing your own, have a look at KDE\[cq]s repository of syntax+definitions.+.PP+To disable highlighting, use the \f[V]--no-highlight\f[R] option.+.SH CUSTOM STYLES+.PP+Custom styles can be used in the docx and ICML formats.+.SS Output+.PP+By default, pandoc\[cq]s docx and ICML output applies a predefined set+of styles for blocks such as paragraphs and block quotes, and uses+largely default formatting (italics, bold) for inlines.+This will work for most purposes, especially alongside a+\f[V]reference.docx\f[R] file.+However, if you need to apply your own styles to blocks, or match a+preexisting set of styles, pandoc allows you to define custom styles for+blocks and text using \f[V]div\f[R]s and \f[V]span\f[R]s, respectively.+.PP+If you define a \f[V]div\f[R] or \f[V]span\f[R] with the attribute+\f[V]custom-style\f[R], pandoc will apply your specified style to the+contained elements (with the exception of elements whose function+depends on a style, like headings, code blocks, block quotes, or links).+So, for example, using the \f[V]bracketed_spans\f[R] syntax,+.IP+.nf+\f[C]+[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said.+\f[R]+.fi+.PP+would produce a docx file with \[lq]Get out\[rq] styled with character+style \f[V]Emphatically\f[R].+Similarly, using the \f[V]fenced_divs\f[R] syntax,+.IP+.nf+\f[C]+Dickinson starts the poem simply:++::: {custom-style=\[dq]Poetry\[dq]}+| A Bird came down the Walk---+| He did not know I saw---+:::+\f[R]+.fi+.PP+would style the two contained lines with the \f[V]Poetry\f[R] paragraph+style.+.PP+For docx output, styles will be defined in the output file as inheriting+from normal text, if the styles are not yet in your reference.docx.+If they are already defined, pandoc will not alter the definition.+.PP+This feature allows for greatest customization in conjunction with+pandoc filters.+If you want all paragraphs after block quotes to be indented, you can+write a filter to apply the styles necessary.+If you want all italics to be transformed to the \f[V]Emphasis\f[R]+character style (perhaps to change their color), you can write a filter+which will transform all italicized inlines to inlines within an+\f[V]Emphasis\f[R] custom-style \f[V]span\f[R].+.PP+For docx output, you don\[cq]t need to enable any extensions for custom+styles to work.+.SS Input+.PP+The docx reader, by default, only reads those styles that it can convert+into pandoc elements, either by direct conversion or interpreting the+derivation of the input document\[cq]s styles.+.PP+By enabling the \f[V]styles\f[R] extension in the docx reader+(\f[V]-f docx+styles\f[R]), you can produce output that maintains the+styles of the input document, using the \f[V]custom-style\f[R] class.+Paragraph styles are interpreted as divs, while character styles are+interpreted as spans.+.PP+For example, using the \f[V]custom-style-reference.docx\f[R] file in the+test directory, we have the following different outputs:+.PP+Without the \f[V]+styles\f[R] extension:+.IP+.nf+\f[C]+$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown+This is some text.++This is text with an *emphasized* text style. And this is text with a+**strengthened** text style.++> Here is a styled paragraph that inherits from Block Text.+\f[R]+.fi+.PP+And with the extension:+.IP+.nf+\f[C]+$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown++::: {custom-style=\[dq]First Paragraph\[dq]}+This is some text.+:::++::: {custom-style=\[dq]Body Text\[dq]}+This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style.+And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]}+text style.+:::++::: {custom-style=\[dq]My Block Style\[dq]}+> Here is a styled paragraph that inherits from Block Text.+:::+\f[R]+.fi+.PP+With these custom styles, you can use your input document as a+reference-doc while creating docx output (see below), and maintain the+same styles in your input and output files.+.SH CUSTOM READERS AND WRITERS+.PP+Pandoc can be extended with custom readers and writers written in Lua.+(Pandoc includes a Lua interpreter, so Lua need not be installed+separately.)+.PP+To use a custom reader or writer, simply specify the path to the Lua+script in place of the input or output format.+For example:+.IP+.nf+\f[C]+pandoc -t data/sample.lua+pandoc -f my_custom_markup_language.lua -t latex -s+\f[R]+.fi+.PP+A custom reader is a Lua script that defines one function, Reader, which+takes a string as input and returns a Pandoc AST.+See the Lua filters documentation for documentation of the functions+that are available for creating pandoc AST elements.+For parsing, the lpeg parsing library is available by default.+To see a sample custom reader:+.IP+.nf+\f[C]+pandoc --print-default-data-file creole.lua+\f[R]+.fi+.PP+If you want your custom reader to have access to reader options+(e.g.\ the tab stop setting), you give your Reader function a second+\f[V]options\f[R] parameter.+.PP+A custom writer is a Lua script that defines a function that specifies+how to render each element in a Pandoc AST.+To see a documented example which you can modify according to your+needs:+.IP+.nf+\f[C]+pandoc --print-default-data-file sample.lua+\f[R]+.fi+.PP+Note that custom writers have no default template.+If you want to use \f[V]--standalone\f[R] with a custom writer, you will+need to specify a template manually using \f[V]--template\f[R] or add a+new default template with the name+\f[V]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[V]templates\f[R]+subdirectory of your user data directory (see Templates).+.SH REPRODUCIBLE BUILDS+.PP+Some of the document formats pandoc targets (such as EPUB, docx, and+ODT) include build timestamps in the generated document.+That means that the files generated on successive builds will differ,+even if the source does not.+To avoid this, set the \f[V]SOURCE_DATE_EPOCH\f[R] environment variable,+and the timestamp will be taken from it instead of the current time.+\f[V]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp+(specifying the number of second since midnight UTC January 1, 1970).+.PP+Some document formats also include a unique identifier.+For EPUB, this can be set explicitly by setting the \f[V]identifier\f[R]+metadata field (see EPUB Metadata, above).+.SH A NOTE ON SECURITY+.PP+If you use pandoc to convert user-contributed content in a web+application, here are some things to keep in mind:+.IP "1." 3+Although pandoc itself will not create or modify any files other than+those you explicitly ask it create (with the exception of temporary+files used in producing PDFs), a filter or custom writer could in+principle do anything on your file system.+Please audit filters and custom writers very carefully before using+them.+.IP "2." 3+Several input formats (including HTML, Org, and RST) support+\f[V]include\f[R] directives that allow the contents of a file to be+included in the output.+An untrusted attacker could use these to view the contents of files on+the file system.+(Using the \f[V]--sandbox\f[R] option can protect against this threat.)+.IP "3." 3+Several output formats (including RTF, FB2, HTML with+\f[V]--self-contained\f[R], EPUB, Docx, and ODT) will embed encoded or+raw images into the output file.+An untrusted attacker could exploit this to view the contents of+non-image files on the file system.+(Using the \f[V]--sandbox\f[R] option can protect against this threat,+but will also prevent including images in these formats.)+.IP "4." 3+If your application uses pandoc as a Haskell library (rather than+shelling out to the executable), it is possible to use it in a mode that+fully isolates pandoc from your file system, by running the pandoc+operations in the \f[V]PandocPure\f[R] monad.+See the document Using the pandoc API for more details.+.IP "5." 3+Pandoc\[cq]s parsers can exhibit pathological performance on some corner+cases.+It is wise to put any pandoc operations under a timeout, to avoid DOS+attacks that exploit these issues.+If you are using the pandoc executable, you can add the command line+options \f[V]+RTS -M512M -RTS\f[R] (for example) to limit the heap size+to 512MB.+Note that the \f[V]commonmark\f[R] parser (including+\f[V]commonmark_x\f[R] and \f[V]gfm\f[R]) is much less vulnerable to+pathological performance than the \f[V]markdown\f[R] parser, so it is a+better choice when processing untrusted input.+.IP "6." 3+The HTML generated by pandoc is not guaranteed to be safe.+If \f[V]raw_html\f[R] is enabled for the Markdown input, users can+inject arbitrary HTML.+Even if \f[V]raw_html\f[R] is disabled, users can include dangerous+content in URLs and attributes.+To be safe, you should run all the generated HTML through an HTML+sanitizer.+.SH AUTHORS+.PP+Copyright 2006\[en]2022 John MacFarlane (jgm\[at]berkeley.edu).+Released under the GPL, version 2 or greater.+This software carries no warranty of any kind.+(See COPYRIGHT for full copyright and warranty notices.)+For a full list of contributors, see the file AUTHORS.md in the pandoc+source code.+.PP+The Pandoc source code may be downloaded+from <https://hackage.haskell.org/package/pandoc> or+<https://github.com/jgm/pandoc/releases>.  Further+documentation is available at <https://pandoc.org>.
man/pandoc.1.after view
@@ -1,3 +1,5 @@ .PP-The Pandoc source code and all documentation may be downloaded-from <https://pandoc.org>.+The Pandoc source code may be downloaded+from <https://hackage.haskell.org/package/pandoc> or+<https://github.com/jgm/pandoc/releases>.  Further+documentation is available at <https://pandoc.org>.
pandoc.cabal view
@@ -1,6 +1,6 @@ cabal-version:   2.4 name:            pandoc-version:         2.17.0.1+version:         2.17.1 build-type:      Simple license:         GPL-2.0-or-later license-file:    COPYING.md@@ -251,6 +251,11 @@                  test/command/3510-export.latex                  test/command/3510-src.hs                  test/command/3971b.tex+                 test/command/5876.yaml+                 test/command/5876/metadata/5876.yaml+                 test/command/5876/metadata/command/5876.yaml+                 test/command/7861.yaml+                 test/command/7861/metadata/placeholder                  test/docbook-chapter.docbook                  test/docbook-reader.docbook                  test/docbook-xref.docbook@@ -475,9 +480,9 @@                  file-embed            >= 0.0      && < 0.1,                  filepath              >= 1.1      && < 1.5,                  haddock-library       >= 1.10     && < 1.11,-                 hslua                 >= 2.0.1    && < 2.1,-                 hslua-aeson           >= 2.0.1    && < 2.1,-                 hslua-marshalling     >= 2.0.1    && < 2.1,+                 hslua                 >= 2.1      && < 2.2,+                 hslua-aeson           >= 2.1      && < 2.2,+                 hslua-marshalling     >= 2.1      && < 2.2,                  hslua-module-path     >= 1.0      && < 1.1,                  hslua-module-system   >= 1.0      && < 1.1,                  hslua-module-text     >= 1.0      && < 1.1,@@ -500,8 +505,8 @@                  random                >= 1        && < 1.3,                  safe                  >= 0.3.18   && < 0.4,                  scientific            >= 0.3      && < 0.4,-                 skylighting           >= 0.12.1   && < 0.13,-                 skylighting-core      >= 0.12.1   && < 0.13,+                 skylighting           >= 0.12.2   && < 0.13,+                 skylighting-core      >= 0.12.2   && < 0.13,                  split                 >= 0.2      && < 0.3,                  syb                   >= 0.1      && < 0.8,                  tagsoup               >= 0.14.6   && < 0.15,@@ -719,7 +724,6 @@                    Text.Pandoc.Lua.Orphans,                    Text.Pandoc.Lua.Packages,                    Text.Pandoc.Lua.PandocLua,-                   Text.Pandoc.Lua.Util,                    Text.Pandoc.XML.Light,                    Text.Pandoc.XML.Light.Types,                    Text.Pandoc.XML.Light.Proc,@@ -777,7 +781,7 @@                   doctemplates      >= 0.10    && < 0.11,                   exceptions        >= 0.8     && < 0.11,                   filepath          >= 1.1     && < 1.5,-                  hslua             >= 2.0     && < 2.1,+                  hslua             >= 2.1     && < 2.2,                   mtl               >= 2.2     && < 2.3,                   pandoc-types      >= 1.22.1  && < 1.23,                   process           >= 1.2.3   && < 1.7,
src/Text/Pandoc/App.hs view
@@ -219,7 +219,7 @@       case optMetadataFiles opts of         []    -> return mempty         paths -> mconcat <$>-           mapM (\path -> do raw <- readFileStrict path+           mapM (\path -> do raw <- readMetadataFile path                              yamlToMeta readerOpts (Just path) raw) paths      let transforms = (case optShiftHeadingLevelBy opts of
src/Text/Pandoc/App/CommandLineOptions.hs view
@@ -109,7 +109,7 @@ latexEngines  = ["pdflatex", "lualatex", "xelatex", "latexmk", "tectonic"]  htmlEngines :: [String]-htmlEngines  = ["wkhtmltopdf", "weasyprint", "prince"]+htmlEngines  = ["pagedjs-cli", "wkhtmltopdf", "weasyprint", "prince"]  engines :: [(Text, String)] engines = map ("html",) htmlEngines ++
src/Text/Pandoc/App/Opt.hs view
@@ -707,9 +707,10 @@   let fp = if null (takeExtension file)               then addExtension file "yaml"               else file-  defaultDataDir <- liftIO defaultUserDataDir-  let defaultFp = fromMaybe defaultDataDir dataDir </> "defaults" </> fp-  fromMaybe fp <$> findM fileExists [fp, defaultFp]+  let searchpath = fp : case dataDir of+                          Nothing -> []+                          Just d  -> [d </> "defaults" </> fp]+  fromMaybe fp <$> findM fileExists searchpath  -- | In a list of lists, append another list in front of every list which -- starts with specific element.
src/Text/Pandoc/CSS.hs view
@@ -18,6 +18,7 @@   ) where +import Data.Either (fromRight) import Data.Maybe (mapMaybe, listToMaybe) import Data.Text (Text, pack) import Text.Pandoc.Shared (trim)@@ -37,10 +38,7 @@ -- Returns an empty list on failure. cssAttributes :: Text -> [(Text, Text)] cssAttributes styleString =-  -- Use Data.Either.fromRight once GHC 8.0 is no longer supported-  case parse styleAttrParser "" styleString of-    Left _  -> []-    Right x -> x+  fromRight [] $ parse styleAttrParser "" styleString  -- | takes a list of keys/properties and a CSS string and -- returns the corresponding key-value-pairs.
src/Text/Pandoc/Class/PandocMonad.hs view
@@ -46,6 +46,7 @@   , getResourcePath   , readDefaultDataFile   , readDataFile+  , readMetadataFile   , fillMediaBag   , toLang   , setTranslations@@ -573,11 +574,25 @@      Nothing   -> foldr addEntryToArchive emptyArchive <$>                      mapM pathToEntry paths --- | Read file from user data directory or,--- if not found there, from the default data files.+-- | Checks if the file path is relative to a parent directory.+isRelativeToParentDir :: FilePath -> Bool+isRelativeToParentDir fname =+  let canonical = makeCanonical fname+   in length canonical >= 2 && take 2 canonical == ".."++-- | Returns possible user data directory if the file path refers to a file or+-- subdirectory within it.+checkUserDataDir :: PandocMonad m => FilePath -> m (Maybe FilePath)+checkUserDataDir fname =+  if isRelative fname && not (isRelativeToParentDir fname)+     then getUserDataDir+     else return Nothing++--- | Read file from user data directory or,+--- if not found there, from the default data files. readDataFile :: PandocMonad m => FilePath -> m B.ByteString readDataFile fname = do-  datadir <- getUserDataDir+  datadir <- checkUserDataDir fname   case datadir of        Nothing -> readDefaultDataFile fname        Just userDir -> do@@ -586,6 +601,25 @@             then readFileStrict (userDir </> fname)             else readDefaultDataFile fname +-- | Read metadata file from the working directory or, if not found there, from+-- the metadata subdirectory of the user data directory.+readMetadataFile :: PandocMonad m => FilePath -> m B.ByteString+readMetadataFile fname = do+  existsInWorkingDir <- fileExists fname+  if existsInWorkingDir+     then readFileStrict fname+     else do+       dataDir <- checkUserDataDir fname+       case dataDir of+         Nothing ->+           throwError $ PandocCouldNotFindMetadataFileError $ T.pack fname+         Just userDir -> do+           let path = userDir </> "metadata" </> fname+           existsInUserDir <- fileExists path+           if existsInUserDir+              then readFileStrict path+              else throwError $ PandocCouldNotFindMetadataFileError $ T.pack fname+ -- | Read file from from the default data files. readDefaultDataFile :: PandocMonad m => FilePath -> m B.ByteString readDefaultDataFile "reference.docx" =@@ -617,9 +651,10 @@ makeCanonical :: FilePath -> FilePath makeCanonical = Posix.joinPath . transformPathParts . splitDirectories  where  transformPathParts = reverse . foldl' go []-        go as     "."  = as-        go (_:as) ".." = as-        go as     x    = x : as+        go as        "."  = as+        go ("..":as) ".." = ["..", ".."] <> as+        go (_:as)    ".." = as+        go as        x    = x : as  -- | Tries to run an action on a file: for each directory given, a -- filepath is created from the given filename, and the action is run on
src/Text/Pandoc/Error.hs view
@@ -54,6 +54,7 @@                  | PandocFilterError Text Text                  | PandocLuaError Text                  | PandocCouldNotFindDataFileError Text+                 | PandocCouldNotFindMetadataFileError Text                  | PandocResourceNotFound Text                  | PandocTemplateError Text                  | PandocAppError Text@@ -118,6 +119,8 @@     PandocLuaError msg -> "Error running Lua:\n" <> msg     PandocCouldNotFindDataFileError fn ->         "Could not find data file " <> fn+    PandocCouldNotFindMetadataFileError fn ->+        "Could not find metadata file " <> fn     PandocResourceNotFound fn ->         "File " <> fn <> " not found in resource path"     PandocTemplateError s -> "Error compiling template " <> s@@ -198,6 +201,7 @@       PandocIpynbDecodingError{} -> 93       PandocUnsupportedCharsetError{} -> 94       PandocCouldNotFindDataFileError{} -> 97+      PandocCouldNotFindMetadataFileError{} -> 98       PandocResourceNotFound{} -> 99  err :: Int -> Text -> IO a
src/Text/Pandoc/Lua/ErrorConversion.hs view
@@ -1,5 +1,4 @@ {-# OPTIONS_GHC -fno-warn-orphans #-}-{-# LANGUAGE LambdaCase #-} {- |    Module      : Text.Pandoc.Lua.ErrorConversion    Copyright   : © 2020-2022 Albert Krewinkel@@ -17,7 +16,6 @@  import HsLua (LuaError, LuaE, top) import HsLua.Marshalling (resultToEither, runPeek)-import HsLua.Class.Peekable (PeekError (..)) import Text.Pandoc.Error (PandocError (PandocLuaError)) import Text.Pandoc.Lua.Marshal.PandocError (pushPandocError, peekPandocError) @@ -41,8 +39,3 @@   popException = popPandocError   pushException = pushPandocError   luaException = PandocLuaError . T.pack--instance PeekError PandocError where-  messageFromException = \case-    PandocLuaError m -> T.unpack m-    err -> show err
src/Text/Pandoc/Lua/Filter.hs view
@@ -23,13 +23,12 @@ import Text.Pandoc.Lua.Marshal.AST import Text.Pandoc.Lua.Marshal.Filter -import qualified Text.Pandoc.Lua.Util as LuaUtil  -- | Transform document using the filter defined in the given file. runFilterFile :: FilePath -> Pandoc -> LuaE PandocError Pandoc runFilterFile filterPath doc = do   oldtop <- gettop-  stat <- LuaUtil.dofileWithTraceback filterPath+  stat <- dofileTrace filterPath   if stat /= Lua.OK     then throwErrorAsException     else do
src/Text/Pandoc/Lua/Marshal/ReaderOptions.hs view
@@ -21,8 +21,8 @@  import Data.Default (def) import HsLua as Lua+import HsLua.Aeson (peekViaJSON, pushViaJSON) import Text.Pandoc.Lua.Marshal.List (pushPandocList)-import Text.Pandoc.Lua.Util (peekViaJSON, pushViaJSON) import Text.Pandoc.Options (ReaderOptions (..))  --
src/Text/Pandoc/Lua/Marshal/Reference.hs view
@@ -28,7 +28,6 @@ import Text.Pandoc.Lua.Marshal.List (pushPandocList)  import qualified Data.Map as Map-import qualified HsLua  -- | Pushes a ReaderOptions value as userdata object. pushReference :: LuaError e => Pusher e (Reference Inlines)@@ -94,14 +93,3 @@  where    -- date parts are lists of Int values    pushDateParts (DateParts dp) = pushPandocList pushIntegral dp---- | Helper funtion to push an object as a table.-pushAsTable :: LuaError e-            => [(HsLua.Name, a -> LuaE e ())]-            -> a -> LuaE e ()-pushAsTable props obj = do-  createtable 0 (length props)-  forM_ props $ \(name, pushValue) -> do-    HsLua.pushName name-    pushValue obj-    rawset (nth 3)
src/Text/Pandoc/Lua/Marshal/WriterOptions.hs view
@@ -20,9 +20,9 @@ import Control.Applicative (optional) import Data.Default (def) import HsLua as Lua+import HsLua.Aeson (peekViaJSON, pushViaJSON) import Text.Pandoc.Lua.Marshal.List (pushPandocList) import Text.Pandoc.Lua.Marshal.Template (peekTemplate, pushTemplate)-import Text.Pandoc.Lua.Util (peekViaJSON, pushViaJSON) import Text.Pandoc.Options (WriterOptions (..))  --
src/Text/Pandoc/Lua/Module/MediaBag.hs view
@@ -16,7 +16,7 @@ import Data.Maybe (fromMaybe) import HsLua ( LuaE, DocumentedFunction, Module (..)              , (<#>), (###), (=#>), (=?>), defun, functionResult-             , optionalParameter , parameter)+             , opt, parameter, stringParam, textParam) import Text.Pandoc.Class.CommonState (CommonState (..)) import Text.Pandoc.Class.PandocMonad (fetchItem, getMediaBag, modifyCommonState,                                       setMediaBag)@@ -55,7 +55,7 @@ delete = defun "delete"   ### (\fp -> unPandocLua $ modifyCommonState               (\st -> st { stMediaBag = MB.deleteMedia fp (stMediaBag st) }))-  <#> parameter Lua.peekString "string" "filepath" "filename of item to delete"+  <#> stringParam "filepath" "filename of item to delete"   =#> []  @@ -72,10 +72,10 @@           mb <- getMediaBag           setMediaBag $ MB.insertMedia fp mmime contents mb           return (Lua.NumResults 0))-  <#> parameter Lua.peekString "string" "filepath" "item file path"-  <#> optionalParameter Lua.peekText "string" "mimetype" "the item's MIME type"+  <#> stringParam "filepath" "item file path"+  <#> opt (textParam "mimetype" "the item's MIME type")   <#> parameter Lua.peekLazyByteString "string" "contents" "binary contents"-  =?> "Nothing"+  =#> []  -- | Returns iterator values to be used with a Lua @for@ loop. items :: DocumentedFunction PandocError@@ -98,7 +98,7 @@           Just item -> 2 <$ do             Lua.pushText $ MB.mediaMimeType item             Lua.pushLazyByteString $ MB.mediaContents item)-  <#> parameter Lua.peekString "string" "filepath" "path of item to lookup"+  <#> stringParam "filepath" "path of item to lookup"   =?> "MIME type and contents"  -- | Function listing all mediabag items.@@ -122,5 +122,5 @@           Lua.pushText $ fromMaybe "" mimeType           Lua.pushByteString bs           return 2)-  <#> parameter Lua.peekText "string" "src" "URI to fetch"+  <#> textParam "src" "URI to fetch"   =?> "Returns two string values: the fetched contents and the mimetype."
src/Text/Pandoc/Lua/Module/Pandoc.hs view
@@ -26,7 +26,6 @@ import Data.Maybe (fromMaybe) import Data.Proxy (Proxy (Proxy)) import HsLua hiding (pushModule)-import HsLua.Class.Peekable (PeekError) import System.Exit (ExitCode (..)) import Text.Pandoc.Definition import Text.Pandoc.Error (PandocError (..))@@ -49,7 +48,6 @@ import qualified Data.ByteString.Lazy as BL import qualified Data.ByteString.Lazy.Char8 as BSL import qualified Data.Text as T-import qualified Text.Pandoc.Lua.Util as LuaUtil import qualified Text.Pandoc.UTF8 as UTF8  -- | Push the "pandoc" package to the Lua stack. Requires the `List`@@ -198,9 +196,9 @@               Left e ->                 throwM e)     <#> parameter peekByteString "string" "content" "text to parse"-    <#> optionalParameter peekText "string" "formatspec" "format and extensions"-    <#> optionalParameter peekReaderOptions "ReaderOptions" "reader_options"-          "reader options"+    <#> opt (textParam "formatspec" "format and extensions")+    <#> opt (parameter peekReaderOptions "ReaderOptions" "reader_options"+             "reader options")     =#> functionResult pushPandoc "Pandoc" "result document"    , sha1@@ -227,10 +225,9 @@               (ByteStringWriter w, es) -> Left <$>                 w writerOpts{ writerExtensions = es } doc)     <#> parameter peekPandoc "Pandoc" "doc" "document to convert"-    <#> optionalParameter peekText "string" "formatspec"-          "format and extensions"-    <#> optionalParameter peekWriterOptions "WriterOptions" "writer_options"-          "writer options"+    <#> opt (textParam "formatspec" "format and extensions")+    <#> opt (parameter peekWriterOptions "WriterOptions" "writer_options"+              "writer options")     =#> functionResult (either pushLazyByteString pushText) "string"           "result document"   ]@@ -247,23 +244,23 @@   , pipeErrorOutput :: BL.ByteString   } -peekPipeError :: PeekError e => StackIndex -> LuaE e PipeError+peekPipeError :: LuaError e => StackIndex -> LuaE e PipeError peekPipeError idx =   PipeError   <$> (Lua.getfield idx "command"    *> Lua.peek (-1) <* Lua.pop 1)   <*> (Lua.getfield idx "error_code" *> Lua.peek (-1) <* Lua.pop 1)   <*> (Lua.getfield idx "output"     *> Lua.peek (-1) <* Lua.pop 1) -pushPipeError :: PeekError e => Pusher e PipeError+pushPipeError :: LuaError e => Pusher e PipeError pushPipeError pipeErr = do-  Lua.newtable-  LuaUtil.addField "command" (pipeErrorCommand pipeErr)-  LuaUtil.addField "error_code" (pipeErrorCode pipeErr)-  LuaUtil.addField "output" (pipeErrorOutput pipeErr)+  pushAsTable [ ("command"    , pushText . pipeErrorCommand)+              , ("error_code" , pushIntegral . pipeErrorCode)+              , ("output"     , pushLazyByteString . pipeErrorOutput)+              ] pipeErr   pushPipeErrorMetaTable-  Lua.setmetatable (-2)+  Lua.setmetatable (nth 2)     where-      pushPipeErrorMetaTable :: PeekError e => LuaE e ()+      pushPipeErrorMetaTable :: LuaError e => LuaE e ()       pushPipeErrorMetaTable = do         v <- Lua.newmetatable "pandoc pipe error"         when v $ do@@ -271,7 +268,7 @@           pushHaskellFunction pipeErrorMessage           rawset (nth 3) -      pipeErrorMessage :: PeekError e => LuaE e NumResults+      pipeErrorMessage :: LuaError e => LuaE e NumResults       pipeErrorMessage = do         (PipeError cmd errorCode output) <- peekPipeError (nthBottom 1)         pushByteString . BSL.toStrict . BSL.concat $
src/Text/Pandoc/Lua/Module/Template.hs view
@@ -42,7 +42,7 @@              Nothing -> runWithDefaultPartials                         (compileTemplate "templates/default" template))      <#> parameter peekText "string" "template" "template string"-     <#> optionalParameter peekString "string" "templ_path" "template path"+     <#> opt (stringParam "templ_path" "template path")      =#> functionResult (either failLua pushTemplate) "pandoc Template"            "compiled template" @@ -53,8 +53,8 @@                  forcePeek $ peekText top `lastly` pop 1            format <- maybe getFORMAT pure mformat            getDefaultTemplate format)-     <#> optionalParameter peekText "string" "writer"-           "writer for which the template should be returned."+     <#> opt (textParam "writer"+              "writer for which the template should be returned.")      =#> functionResult pushText "string"            "string representation of the writer's default template"
src/Text/Pandoc/Lua/Module/Utils.hs view
@@ -56,8 +56,7 @@               return $ B.toList (Shared.blocksToInlinesWithSep sep blks))       <#> parameter (peekList peekBlock) "list of blocks"             "blocks" ""-      <#> optionalParameter (peekList peekInline) "list of inlines"-            "inline" ""+      <#> opt (parameter (peekList peekInline) "list of inlines" "inline" "")       =#> functionResult pushInlines "list of inlines" ""      , defun "equals"@@ -121,8 +120,8 @@           )       <#> parameter peekPandoc "Pandoc" "doc" "input document"       <#> parameter peekString "filepath" "filter_path" "path to filter"-      <#> optionalParameter (peekList peekString) "list of strings"-            "args" "arguments to pass to the filter"+      <#> opt (parameter (peekList peekString) "list of strings"+               "args" "arguments to pass to the filter")       =#> functionResult pushPandoc "Pandoc" "filtered document"      , defun "stringify"
src/Text/Pandoc/Lua/Orphans.hs view
@@ -65,9 +65,6 @@ instance Pushable Cell where   push = pushCell -instance Peekable Cell where-  peek = forcePeek . peekCell- instance Pushable Inline where   push = pushInline @@ -92,25 +89,28 @@ -- These instances exist only for testing. It's a hack to avoid making -- the marshalling modules public. instance Peekable Inline where-  peek = forcePeek . peekInline+  safepeek = peekInline  instance Peekable Block where-  peek = forcePeek . peekBlock+  safepeek = peekBlock +instance Peekable Cell where+  safepeek = peekCell+ instance Peekable Meta where-  peek = forcePeek . peekMeta+  safepeek = peekMeta  instance Peekable Pandoc where-  peek = forcePeek . peekPandoc+  safepeek = peekPandoc  instance Peekable Row where-  peek = forcePeek . peekRow+  safepeek = peekRow  instance Peekable Version where-  peek = forcePeek . peekVersionFuzzy+  safepeek = peekVersionFuzzy  instance {-# OVERLAPPING #-} Peekable Attr where-  peek = forcePeek . peekAttr+  safepeek = peekAttr  instance Pushable Sources where   push = pushSources
src/Text/Pandoc/Lua/PandocLua.hs view
@@ -68,10 +68,10 @@   return result  instance {-# OVERLAPPING #-} Exposable PandocError (PandocLua NumResults) where-  partialApply _narg = unPandocLua+  partialApply _narg = liftLua . unPandocLua  instance Pushable a => Exposable PandocError (PandocLua a) where-  partialApply _narg x = 1 <$ (unPandocLua x >>= Lua.push)+  partialApply _narg x = 1 <$ (liftLua (unPandocLua x >>= Lua.push))  -- | Global variables which should always be set. defaultGlobals :: PandocMonad m => m [Global]
− src/Text/Pandoc/Lua/Util.hs 
@@ -1,83 +0,0 @@-{-# LANGUAGE OverloadedStrings     #-}-{- |-   Module      : Text.Pandoc.Lua.Util-   Copyright   : © 2012-2022 John MacFarlane,-                 © 2017-2022 Albert Krewinkel-   License     : GNU GPL, version 2 or above--   Maintainer  : Albert Krewinkel <tarleb+pandoc@moltkeplatz.de>-   Stability   : alpha--Lua utility functions.--}-module Text.Pandoc.Lua.Util-  ( addField-  , callWithTraceback-  , pcallWithTraceback-  , dofileWithTraceback-  , peekViaJSON-  , pushViaJSON-  ) where--import Control.Monad (when)-import HsLua-import HsLua.Aeson (peekValue, pushValue)-import qualified Data.Aeson as Aeson-import qualified HsLua as Lua-import qualified Text.Pandoc.UTF8 as UTF8---- | Add a value to the table at the top of the stack at a string-index.-addField :: (LuaError e, Pushable a) => String -> a -> LuaE e ()-addField key value = do-  Lua.push key-  Lua.push value-  Lua.rawset (Lua.nth 3)---- | Like @'Lua.pcall'@, but uses a predefined error handler which adds a--- traceback on error.-pcallWithTraceback :: LuaError e => NumArgs -> NumResults -> LuaE e Status-pcallWithTraceback nargs nresults = do-  let traceback' :: LuaError e => LuaE e NumResults-      traceback' = do-        l <- Lua.state-        msg <- Lua.tostring' (Lua.nthBottom 1)-        Lua.traceback l (Just msg) 2-        return 1-  tracebackIdx <- Lua.absindex (Lua.nth (Lua.fromNumArgs nargs + 1))-  Lua.pushHaskellFunction traceback'-  Lua.insert tracebackIdx-  result <- Lua.pcall nargs nresults (Just tracebackIdx)-  Lua.remove tracebackIdx-  return result---- | Like @'Lua.call'@, but adds a traceback to the error message (if any).-callWithTraceback :: LuaError e => NumArgs -> NumResults -> LuaE e ()-callWithTraceback nargs nresults = do-  result <- pcallWithTraceback nargs nresults-  when (result /= Lua.OK)-    Lua.throwErrorAsException---- | Run the given string as a Lua program, while also adding a traceback to the--- error message if an error occurs.-dofileWithTraceback :: LuaError e => FilePath -> LuaE e Status-dofileWithTraceback fp = do-  loadRes <- Lua.loadfile fp-  case loadRes of-    Lua.OK -> pcallWithTraceback 0 Lua.multret-    _ -> return loadRes----- These will become part of hslua-aeson in future versions.---- | Retrieves a value from the Lua stack via JSON.-peekViaJSON :: (Aeson.FromJSON a, LuaError e) => Peeker e a-peekViaJSON idx = do-  value <- peekValue idx-  case Aeson.fromJSON value of-    Aeson.Success x -> pure x-    Aeson.Error msg -> failPeek $ "failed to decode: " <>-                       UTF8.fromString msg---- | Pushes a value to the Lua stack as a JSON-like value.-pushViaJSON :: (Aeson.ToJSON a, LuaError e) => Pusher e a-pushViaJSON = pushValue . Aeson.toJSON
src/Text/Pandoc/PDF.hs view
@@ -70,7 +70,8 @@  makePDF :: (PandocMonad m, MonadIO m, MonadMask m)         => String              -- ^ pdf creator (pdflatex, lualatex, xelatex,-                               -- wkhtmltopdf, weasyprint, prince, context, pdfroff,+                               -- wkhtmltopdf, weasyprint, prince, context,+                               -- pdfroff, pagedjs,                                -- or path to executable)         -> [String]            -- ^ arguments to pass to pdf creator         -> (WriterOptions -> Pandoc -> m Text)  -- ^ writer@@ -80,7 +81,7 @@ makePDF program pdfargs writer opts doc =   case takeBaseName program of     "wkhtmltopdf" -> makeWithWkhtmltopdf program pdfargs writer opts doc-    prog | prog `elem` ["weasyprint", "prince"] -> do+    prog | prog `elem` ["pagedjs-cli" ,"weasyprint", "prince"] -> do       source <- writer opts doc       verbosity <- getVerbosity       liftIO $ html2pdf verbosity program pdfargs source@@ -434,7 +435,8 @@       hClose h1       hClose h2       BS.writeFile file $ UTF8.fromText source-      let pdfFileArgName = ["-o" | takeBaseName program == "prince"]+      let pdfFileArgName = ["-o" | takeBaseName program `elem`+                                   ["pagedjs-cli", "prince"]]       let programArgs = args ++ [file] ++ pdfFileArgName ++ [pdfFile]       env' <- getEnvironment       when (verbosity >= INFO) $
src/Text/Pandoc/Readers/CommonMark.hs view
@@ -30,10 +30,10 @@ import Control.Monad.Except import Data.Functor.Identity (runIdentity) import Data.Typeable-import Text.Pandoc.Parsing (runParserT, getInput,+import Text.Pandoc.Parsing (runParserT, getInput, getPosition,                             runF, defaultParserState, option, many1, anyChar,                             Sources(..), ToSources(..), ParserT, Future,-                            sourceName)+                            sourceName, sourceLine, incSourceLine) import qualified Data.Text as T  -- | Parse a CommonMark formatted string into a 'Pandoc' structure.@@ -42,11 +42,19 @@ readCommonMark opts s   | isEnabled Ext_yaml_metadata_block opts = do     let sources = toSources s+    let firstSourceName = case unSources sources of+                               ((pos,_):_) -> sourceName pos+                               _ -> ""     let toks = concatMap sourceToToks (unSources sources)     res <- runParserT (do meta <- yamlMetaBlock (metaValueParser opts)+                          pos <- getPosition                           rest <- getInput-                          return (meta, rest))-                      defaultParserState "YAML metadata" (toSources s)+                          let rest' = case rest of+                                -- update position of first source (#7863):+                                Sources ((_,t):xs) -> Sources ((pos,t):xs)+                                _ -> rest+                          return (meta, rest'))+                      defaultParserState firstSourceName sources     case res of       Left _ -> readCommonMarkBody opts sources toks       Right (meta, rest) -> do@@ -60,7 +68,13 @@     readCommonMarkBody opts sources toks  sourceToToks :: (SourcePos, Text) -> [Tok]-sourceToToks (pos, s) = tokenize (sourceName pos) s+sourceToToks (pos, s) = map adjust $ tokenize (sourceName pos) s+ where+   adjust = case sourceLine pos of+              1 -> id+              n -> \tok -> tok{ tokPos =+                                  incSourceLine (tokPos tok) (n - 1) }+  metaValueParser :: Monad m                 => ReaderOptions -> ParserT Sources st m (Future st MetaValue)
src/Text/Pandoc/Readers/Custom.hs view
@@ -14,7 +14,7 @@ module Text.Pandoc.Readers.Custom ( readCustom ) where import Control.Exception import Control.Monad (when)-import HsLua as Lua hiding (Operation (Div), render)+import HsLua as Lua hiding (Operation (Div)) import Control.Monad.IO.Class (MonadIO) import Text.Pandoc.Definition import Text.Pandoc.Class (PandocMonad, report)@@ -22,8 +22,6 @@ import Text.Pandoc.Lua (Global (..), runLua, setGlobals) import Text.Pandoc.Lua.PandocLua import Text.Pandoc.Lua.Marshal.Pandoc (peekPandoc)-import Text.Pandoc.Lua.Util (dofileWithTraceback, callWithTraceback,-                             pcallWithTraceback) import Text.Pandoc.Options import Text.Pandoc.Sources (ToSources(..), sourcesToText) import qualified Data.Text as T@@ -35,7 +33,7 @@   let globals = [ PANDOC_SCRIPT_FILE luaFile ]   res <- runLua $ do     setGlobals globals-    stat <- dofileWithTraceback luaFile+    stat <- dofileTrace luaFile     -- check for error in lua script (later we'll change the return type     -- to handle this more gracefully):     when (stat /= Lua.OK)@@ -50,7 +48,7 @@     getglobal "Reader"     push input     push opts-    pcallWithTraceback 2 1 >>= \case+    pcallTrace 2 1 >>= \case       OK -> forcePeek $ peekPandoc top       ErrRun -> do         -- Caught a runtime error. Check if parsing might work if we@@ -74,7 +72,7 @@                 getglobal "Reader"                 push $ sourcesToText input  -- push sources as string                 push opts-                callWithTraceback 2 1+                callTrace 2 1                 forcePeek $ peekPandoc top               else                 -- nothing we can do here
src/Text/Pandoc/Readers/DocBook.hs view
@@ -1022,7 +1022,7 @@              Just t  -> Just ("titleabbrev", strContentRecursive t)              Nothing -> Nothing          lineItems = mapM getInlines $ filterChildren (named "line") e-         -- | Admonitions are parsed into a div. Following other Docbook tools that output HTML,+         -- Admonitions are parsed into a div. Following other Docbook tools that output HTML,          -- we parse the optional title as a div with the @title@ class, and give the          -- block itself a class corresponding to the admonition name.          parseAdmonition label = do
src/Text/Pandoc/Readers/Docx/Fields.hs view
@@ -26,6 +26,8 @@ data FieldInfo = HyperlinkField URL                 -- The boolean indicates whether the field is a hyperlink.                | PagerefField Anchor Bool+               | ZoteroItem T.Text+               | ZoteroBibliography                | UnknownField                deriving (Show) @@ -38,7 +40,29 @@   <|>   try ((uncurry PagerefField) <$> pageref)    <|>+  try addIn+  <|>   return UnknownField++addIn :: Parser FieldInfo+addIn = do+  spaces+  string "ADDIN"+  spaces+  try zoteroItem <|> zoteroBibliography++zoteroItem :: Parser FieldInfo+zoteroItem = do+  string "ZOTERO_ITEM"+  spaces+  string "CSL_CITATION"+  spaces+  ZoteroItem <$> getInput++zoteroBibliography :: Parser FieldInfo+zoteroBibliography = do+  string "ZOTERO_BIBL"+  return ZoteroBibliography  escapedQuote :: Parser T.Text escapedQuote = string "\\\"" $> "\\\""
src/Text/Pandoc/Readers/Docx/Parse.hs view
@@ -274,15 +274,10 @@       spans = g cells Nothing (listToMaybe acc)       in spans : acc -    g ::-      -- | The current row-      [Cell] ->-      -- | Number of columns left below-      Maybe Integer ->-      -- | (rowspan so far, cell) for the row below this one-      Maybe [(Int, Cell)] ->-      -- | (rowspan so far, cell) for this row-      [(Int, Cell)]+    g :: [Cell] -- the current row+      -> Maybe Integer -- Number of columns left below+      -> Maybe [(Int, Cell)] -- (rowspan so far, cell) for the row below this one+      -> [(Int, Cell)] -- (rowspan so far, cell) for this row     g cells _ Nothing = zip (repeat 1) cells     g cells columnsLeftBelow (Just rowBelow) =         case cells of
src/Text/Pandoc/Readers/LaTeX.hs view
@@ -126,7 +126,8 @@ --   res <- runIOorExplode (runParserT p defaultLaTeXState{ --             sOptions = def{ readerExtensions = --               enableExtension Ext_raw_tex $---                 getDefaultExtensions "latex" }} "source" (tokenize "source" t))+--                 getDefaultExtensions "latex" }} "source"+--                   (tokenize (initialPos "source") t)) --   case res of --        Left e  -> error (show e) --        Right r -> return r@@ -137,14 +138,15 @@ rawLaTeXBlock = do   lookAhead (try (char '\\' >> letter))   toks <- getInputTokens-  snd <$> (rawLaTeXParser toks False (macroDef (const mempty)) blocks-      <|> rawLaTeXParser toks True-             (do choice (map controlSeq+  snd <$> (+          rawLaTeXParser toks+             (macroDef (const mempty) <|>+              do choice (map controlSeq                    ["include", "input", "subfile", "usepackage"])                  skipMany opt                  braced                  return mempty) blocks-      <|> rawLaTeXParser toks True+      <|> rawLaTeXParser toks            (environment <|> blockCommand)            (mconcat <$> many (block <|> beginOrEndCommand))) @@ -168,10 +170,10 @@   lookAhead (try (char '\\' >> letter))   toks <- getInputTokens   raw <- snd <$>-          (   rawLaTeXParser toks True+          (   rawLaTeXParser toks               (mempty <$ (controlSeq "input" >> skipMany rawopt >> braced))               inlines-          <|> rawLaTeXParser toks True (inlineEnvironment <|> inlineCommand')+          <|> rawLaTeXParser toks (inlineEnvironment <|> inlineCommand')               inlines           )   finalbraces <- mconcat <$> many (try (string "{}")) -- see #5439@@ -181,7 +183,7 @@ inlineCommand = do   lookAhead (try (char '\\' >> letter))   toks <- getInputTokens-  fst <$> rawLaTeXParser toks True (inlineEnvironment <|> inlineCommand')+  fst <$> rawLaTeXParser toks (inlineEnvironment <|> inlineCommand')           inlines  -- inline elements:@@ -721,7 +723,7 @@                    Nothing -> do                      report $ CouldNotLoadIncludeFile (T.pack f) pos                      return ""-  getInput >>= setInput . (tokenize f contents ++)+  getInput >>= setInput . (tokenize (initialPos f) contents ++)   updateState dropLatestIncludeFile  authors :: PandocMonad m => LP m ()@@ -919,6 +921,8 @@    , ("PackageError", mempty <$ (braced >> braced >> braced))    -- epigraph package    , ("epigraph", epigraph)+   -- alignment+   , ("raggedright", pure mempty)    ]  skipSameFileToks :: PandocMonad m => LP m ()@@ -1185,7 +1189,7 @@  descItem :: PandocMonad m => LP m (Inlines, [Blocks]) descItem = do-  blocks -- skip blocks before item+  optional spaces1   controlSeq "item"   sp   ils <- opt
src/Text/Pandoc/Readers/LaTeX/Inline.hs view
@@ -96,7 +96,7 @@          let (t1, t2) = T.splitAt i txt          inp <- getInput          setInput $ Tok (incSourceColumn pos i) Symbol (T.singleton stopchar)-                  : totoks (incSourceColumn pos (i + 1)) (T.drop 1 t2) ++ inp+                  : tokenize (incSourceColumn pos (i + 1)) (T.drop 1 t2) ++ inp          return $ Tok pos toktype t1  listingsLanguage :: [(Text, Text)] -> Maybe Text
src/Text/Pandoc/Readers/LaTeX/Macro.hs view
@@ -130,13 +130,17 @@                    Macro GroupScope ExpandWhenUsed [] Nothing                    [ Tok pos (CtrlSeq "def") "\\def"                    , Tok pos (CtrlSeq name) ("\\" <> name)+                   , Tok pos Symbol "{"                    , Tok pos (CtrlSeq "iftrue") "\\iftrue"+                   , Tok pos Symbol "}"                    ])            , (base <> "false",                    Macro GroupScope ExpandWhenUsed [] Nothing                    [ Tok pos (CtrlSeq "def") "\\def"                    , Tok pos (CtrlSeq name) ("\\" <> name)+                   , Tok pos Symbol "{"                    , Tok pos (CtrlSeq "iffalse") "\\iffalse"+                   , Tok pos Symbol "}"                    ])            ]
src/Text/Pandoc/Readers/LaTeX/Parsing.hs view
@@ -32,7 +32,6 @@   , getInputTokens   , untokenize   , untoken-  , totoks   , toksToString   , satisfyTok   , parseFromToks@@ -256,9 +255,9 @@        return result  rawLaTeXParser :: (PandocMonad m, HasMacros s, HasReaderOptions s, Show a)-               => [Tok] -> Bool -> LP m a -> LP m a+               => [Tok] -> LP m a -> LP m a                -> ParserT Sources s m (a, Text)-rawLaTeXParser toks retokenize parser valParser = do+rawLaTeXParser toks parser valParser = do   pstate <- getState   let lstate = def{ sOptions = extractReaderOptions pstate }   let lstate' = lstate { sMacros = extractMacros pstate :| [] }@@ -272,12 +271,7 @@   case res' of        Left _    -> mzero        Right (endpos, toks') -> do-         res <- lift $ runParserT (do when retokenize $ do-                                        -- retokenize, applying macros-                                        ts <- many anyTok-                                        setInput ts-                                      rawparser)-                        lstate' "chunk" toks'+         res <- lift $ runParserT rawparser lstate' "chunk" toks'          case res of               Left _    -> mzero               Right ((val, raw), st) -> do@@ -307,7 +301,7 @@       pstate <- getState       let lstate = def{ sOptions = extractReaderOptions pstate                       , sMacros  = extractMacros pstate :| [] }-      res <- runParserT retokenize lstate "math" (tokenize "math" s)+      res <- runParserT retokenize lstate "math" (tokenize (initialPos "math") s)       case res of            Left e   -> Prelude.fail (show e)            Right s' -> return s'@@ -324,7 +318,7 @@ tokenizeSources :: Sources -> [Tok] tokenizeSources = concatMap tokenizeSource . unSources  where-   tokenizeSource (pos, t) = totoks pos t+   tokenizeSource (pos, t) = tokenize pos t  -- Return tokens from input sources. Ensure that starting position is -- correct.@@ -337,12 +331,11 @@       Sources [] -> []       Sources ((_,t):rest) -> tokenizeSources $ Sources ((pos,t):rest) -tokenize :: SourceName -> Text -> [Tok]-tokenize sourcename = totoks (initialPos sourcename)--totoks :: SourcePos -> Text -> [Tok]-totoks pos t =-  case T.uncons t of+tokenize :: SourcePos -> Text -> [Tok]+tokenize = totoks+ where+  totoks pos t =+    case T.uncons t of        Nothing        -> []        Just (c, rest)          | c == '\n' ->@@ -806,7 +799,7 @@   let updPos (Tok pos' toktype' txt') =         Tok (incSourceColumn (incSourceLine pos' (sourceLine pos - 1))              (sourceColumn pos)) toktype' txt'-  let newtoks = map updPos $ tokenize (sourceName pos) $ T.tail txt+  let newtoks = map updPos $ tokenize pos $ T.tail txt   getInput >>= setInput . ((Tok pos Symbol "%" : newtoks) ++))     <|> return ()
src/Text/Pandoc/Readers/Org/Inlines.hs view
@@ -332,7 +332,7 @@   moreCitations <- many (try $ char ',' *> orgRefCiteList mode)   return . sequence $ firstCitation : moreCitations  where-  -- | A list of org-ref style citation keys, parsed as citation of the given+  -- A list of org-ref style citation keys, parsed as citation of the given   -- citation mode.   orgRefCiteList :: PandocMonad m => CitationMode -> OrgParser m (F Citation)   orgRefCiteList citeMode = try $ do
src/Text/Pandoc/Shared.hs view
@@ -390,18 +390,11 @@ deLink (Link _ ils _) = Span nullAttr ils deLink x              = x -deQuote :: Inline -> Inline-deQuote (Quoted SingleQuote xs) =-  Span ("",[],[]) (Str "\8216" : xs ++ [Str "\8217"])-deQuote (Quoted DoubleQuote xs) =-  Span ("",[],[]) (Str "\8220" : xs ++ [Str "\8221"])-deQuote x = x- -- | Convert pandoc structure to a string with formatting removed. -- Footnotes are skipped (since we don't want their contents in link -- labels). stringify :: Walkable Inline a => a -> T.Text-stringify = query go . walk (deNote . deQuote)+stringify = query go . walk fixInlines   where go :: Inline -> T.Text         go Space                                       = " "         go SoftBreak                                   = " "@@ -413,6 +406,19 @@         go LineBreak                                   = " "         go _                                           = "" +        fixInlines :: Inline -> Inline+        fixInlines (Cite _ ils) = Cite [] ils+        fixInlines (Note _) = Note []+        fixInlines (q@Quoted{}) = deQuote q+        fixInlines x = x++deQuote :: Inline -> Inline+deQuote (Quoted SingleQuote xs) =+  Span ("",[],[]) (Str "\8216" : xs ++ [Str "\8217"])+deQuote (Quoted DoubleQuote xs) =+  Span ("",[],[]) (Str "\8220" : xs ++ [Str "\8221"])+deQuote x = x+ -- | Bring all regular text in a pandoc structure to uppercase. -- -- This function correctly handles cases where a lowercase character doesn't@@ -965,10 +971,13 @@ -- XDG_DATA_HOME (or its default value), but for backwards compatibility, -- we fall back to the legacy user data directory ($HOME/.pandoc on *nix) -- if the XDG_DATA_HOME is missing and this exists.  If neither directory--- is present, we return the XDG data directory.+-- is present, we return the XDG data directory.  If the XDG data directory+-- is not defined (e.g. because we are in an environment where $HOME is+-- not defined), we return the empty string. defaultUserDataDir :: IO FilePath defaultUserDataDir = do-  xdgDir <- getXdgDirectory XdgData "pandoc"+  xdgDir <- E.catch (getXdgDirectory XdgData "pandoc")+               (\(_ :: E.SomeException) -> return mempty)   legacyDir <- getAppUserDataDirectory "pandoc"   xdgExists <- doesDirectoryExist xdgDir   legacyDirExists <- doesDirectoryExist legacyDir
src/Text/Pandoc/Writers/AsciiDoc.hs view
@@ -248,13 +248,13 @@              $ zipWith colspec aligns widths')          <> text ","          <> headerspec <> text "]"-         +   -- construct cells and recurse in case of nested tables   parentTableLevel <- gets tableNestingLevel   let currentNestingLevel = parentTableLevel + 1-  +   modify $ \st -> st{ tableNestingLevel = currentNestingLevel }-  +   let separator = text (if parentTableLevel == 0                           then "|"  -- top level separator                           else "!") -- nested separator@@ -283,7 +283,7 @@   let maxwidth = maximum $ fmap offset (head' :| rows')   let body = if maxwidth > colwidth then vsep rows' else vcat rows'   let border = separator <> text "==="-  return $ +  return $     caption'' $$ tablespec $$ border $$ head'' $$ body $$ border $$ blankline blockToAsciiDoc opts (BulletList items) = do   inlist <- gets inList@@ -342,11 +342,25 @@ bulletListItemToAsciiDoc opts blocks = do   lev <- gets bulletListLevel   modify $ \s -> s{ bulletListLevel = lev + 1 }-  contents <- foldM (addBlock opts) empty blocks+  isAsciidoctor <- gets asciidoctorVariant+  let blocksWithTasks = if isAsciidoctor+                          then (taskListItemToAsciiDoc blocks)+                          else blocks+  contents <- foldM (addBlock opts) empty blocksWithTasks   modify $ \s -> s{ bulletListLevel = lev }   let marker = text (replicate (lev + 1) '*')-  return $ marker <> text " " <> listBegin blocks <>+  return $ marker <> text " " <> listBegin blocksWithTasks <>     contents <> cr++-- | Convert a list item containing text starting with @U+2610 BALLOT BOX@+-- or @U+2612 BALLOT BOX WITH X@ to asciidoctor checkbox syntax (e.g. @[x]@).+taskListItemToAsciiDoc :: [Block] -> [Block]+taskListItemToAsciiDoc = handleTaskListItem toOrg listExt+  where+    toOrg (Str "☐" : Space : is) = Str "[ ]" : Space : is+    toOrg (Str "☒" : Space : is) = Str "[x]" : Space : is+    toOrg is = is+    listExt = extensionsFromList [Ext_task_lists]  addBlock :: PandocMonad m          => WriterOptions -> Doc Text -> Block -> ADW m (Doc Text)
src/Text/Pandoc/Writers/Blaze.hs view
@@ -30,9 +30,13 @@        in literal open'             <> attrs             <> char '>'-            <> (if allowsWrap open'-                   then go wrap mempty content-                   else flush $ go False mempty content)+            <> (case open' of+                  "<code" -> go False mempty content+                  t | t == "<pre" ||+                      t == "<style" ||+                      t == "<script" ||+                      t == "<textarea" -> flush $ go False mempty content+                    | otherwise -> go wrap mempty content)             <> literal (getText close)     go wrap attrs (CustomParent tag content) =         char '<'@@ -77,9 +81,6 @@     go _ _ (Empty _) = mempty     space' wrap = if wrap then space else char ' ' -allowsWrap :: T.Text -> Bool-allowsWrap t =-  not (t == "<pre" || t == "<style" || t == "<script" || t == "<textarea")  fromChoiceString :: Bool                  -- ^ Allow wrapping                  -> ChoiceString          -- ^ String to render
src/Text/Pandoc/Writers/Custom.hs view
@@ -21,59 +21,62 @@ import Control.Exception import Control.Monad (when) import Data.List (intersperse)-import qualified Data.Map as M import Data.Maybe (fromMaybe) import qualified Data.Text as T import Data.Text (Text, pack)-import HsLua as Lua hiding (Operation (Div), render)-import HsLua.Class.Peekable (PeekError)+import HsLua as Lua hiding (Operation (Div))+import HsLua.Aeson (peekViaJSON) import Text.DocLayout (render, literal) import Text.DocTemplates (Context) import Control.Monad.IO.Class (MonadIO) import Text.Pandoc.Definition import Text.Pandoc.Lua (Global (..), runLua, setGlobals)-import Text.Pandoc.Lua.Util (addField, dofileWithTraceback, peekViaJSON)+import Text.Pandoc.Lua.Marshal.Attr (pushAttributeList) import Text.Pandoc.Options import Text.Pandoc.Class (PandocMonad) import Text.Pandoc.Templates (renderTemplate) import Text.Pandoc.Writers.Shared -attrToMap :: Attr -> M.Map T.Text T.Text-attrToMap (id',classes,keyvals) = M.fromList+-- | List of key-value pairs that is pushed to Lua as AttributeList+-- userdata.+newtype AttributeList = AttributeList [(Text, Text)]+instance Pushable AttributeList where+  push (AttributeList kvs) = pushAttributeList kvs++attrToMap :: Attr -> AttributeList+attrToMap (id',classes,keyvals) = AttributeList     $ ("id", id')     : ("class", T.unwords classes)     : keyvals -newtype Stringify e a = Stringify a+newtype Stringify a = Stringify a -instance Pushable (Stringify e Format) where+instance Pushable (Stringify Format) where   push (Stringify (Format f)) = Lua.push (T.toLower f) -instance PeekError e => Pushable (Stringify e [Inline]) where-  push (Stringify ils) = Lua.push =<<-    changeErrorType ((inlineListToCustom @e) ils)+instance Pushable (Stringify [Inline]) where+  push (Stringify ils) = Lua.push =<< inlineListToCustom ils -instance PeekError e => Pushable (Stringify e [Block]) where-  push (Stringify blks) = Lua.push =<<-    changeErrorType ((blockListToCustom @e) blks)+instance Pushable (Stringify [Block]) where+  push (Stringify blks) = Lua.push =<< blockListToCustom blks -instance PeekError e => Pushable (Stringify e MetaValue) where-  push (Stringify (MetaMap m))       = Lua.push (fmap (Stringify @e) m)-  push (Stringify (MetaList xs))     = Lua.push (map (Stringify @e) xs)+instance Pushable (Stringify MetaValue) where+  push (Stringify (MetaMap m))       = Lua.push (fmap Stringify m)+  push (Stringify (MetaList xs))     = Lua.push (map Stringify xs)   push (Stringify (MetaBool x))      = Lua.push x   push (Stringify (MetaString s))    = Lua.push s-  push (Stringify (MetaInlines ils)) = Lua.push (Stringify @e ils)-  push (Stringify (MetaBlocks bs))   = Lua.push (Stringify @e bs)+  push (Stringify (MetaInlines ils)) = Lua.push (Stringify ils)+  push (Stringify (MetaBlocks bs))   = Lua.push (Stringify bs) -instance PeekError e => Pushable (Stringify e Citation) where-  push (Stringify cit) = do-    Lua.createtable 6 0-    addField "citationId" $ citationId cit-    addField "citationPrefix" . Stringify @e $ citationPrefix cit-    addField "citationSuffix" . Stringify @e $ citationSuffix cit-    addField "citationMode" $ show (citationMode cit)-    addField "citationNoteNum" $ citationNoteNum cit-    addField "citationHash" $ citationHash cit+instance Pushable (Stringify Citation) where+  push (Stringify cit) = flip pushAsTable cit+    [ ("citationId", push . citationId)+    , ("citationPrefix",  push . Stringify . citationPrefix)+    , ("citationSuffix",  push . Stringify . citationSuffix)+    , ("citationMode",    push . citationMode)+    , ("citationNoteNum", push . citationNoteNum)+    , ("citationHash",    push . citationHash)+    ]  -- | Key-value pair, pushed as a table with @a@ as the only key and @v@ as the -- associated value.@@ -96,7 +99,7 @@                 ]   res <- runLua $ do     setGlobals globals-    stat <- dofileWithTraceback luaFile+    stat <- dofileTrace luaFile     -- check for error in lua script (later we'll change the return type     -- to handle this more gracefully):     when (stat /= Lua.OK)@@ -115,7 +118,7 @@         Just tpl -> render Nothing $                     renderTemplate tpl $ setField "body" body context -docToCustom :: forall e. PeekError e+docToCustom :: forall e. LuaError e             => WriterOptions -> Pandoc -> LuaE e (String, Context Text) docToCustom opts (Pandoc (Meta metamap) blocks) = do   body <- blockListToCustom blocks@@ -123,7 +126,7 @@   -- `Doc` manually.   Lua.getglobal "Doc"                 -- function   push body                           -- argument 1-  push (fmap (Stringify @e) metamap)  -- argument 2+  push (fmap Stringify  metamap)      -- argument 2   push (writerVariables opts)         -- argument 3   call 3 2   rendered  <- peek (nth 2)           -- first return value@@ -131,125 +134,125 @@   return (rendered, fromMaybe mempty context)  -- | Convert Pandoc block element to Custom.-blockToCustom :: forall e. PeekError e+blockToCustom :: forall e. LuaError e               => Block         -- ^ Block element               -> LuaE e String  blockToCustom Null = return "" -blockToCustom (Plain inlines) = invoke @e "Plain" (Stringify @e inlines)+blockToCustom (Plain inlines) = invoke "Plain" (Stringify inlines)  blockToCustom (Para [Image attr txt (src,tit)]) =-  invoke @e "CaptionedImage" src tit (Stringify @e txt) (attrToMap attr)+  invoke "CaptionedImage" src tit (Stringify txt) (attrToMap attr) -blockToCustom (Para inlines) = invoke @e "Para" (Stringify @e inlines)+blockToCustom (Para inlines) = invoke "Para" (Stringify inlines)  blockToCustom (LineBlock linesList) =-  invoke @e "LineBlock" (map (Stringify @e) linesList)+  invoke "LineBlock" (map (Stringify) linesList)  blockToCustom (RawBlock format str) =-  invoke @e "RawBlock" (Stringify @e format) str+  invoke "RawBlock" (Stringify format) str -blockToCustom HorizontalRule = invoke @e "HorizontalRule"+blockToCustom HorizontalRule = invoke "HorizontalRule"  blockToCustom (Header level attr inlines) =-  invoke @e "Header" level (Stringify @e inlines) (attrToMap attr)+  invoke "Header" level (Stringify inlines) (attrToMap attr)  blockToCustom (CodeBlock attr str) =-  invoke @e "CodeBlock" str (attrToMap attr)+  invoke "CodeBlock" str (attrToMap attr)  blockToCustom (BlockQuote blocks) =-  invoke @e "BlockQuote" (Stringify @e blocks)+  invoke "BlockQuote" (Stringify blocks)  blockToCustom (Table _ blkCapt specs thead tbody tfoot) =   let (capt, aligns, widths, headers, rows) = toLegacyTable blkCapt specs thead tbody tfoot       aligns' = map show aligns-      capt' = Stringify @e capt-      headers' = map (Stringify @e) headers-      rows' = map (map (Stringify @e)) rows-  in invoke @e "Table" capt' aligns' widths headers' rows'+      capt' = Stringify capt+      headers' = map (Stringify) headers+      rows' = map (map (Stringify)) rows+  in invoke "Table" capt' aligns' widths headers' rows'  blockToCustom (BulletList items) =-  invoke @e "BulletList" (map (Stringify @e) items)+  invoke "BulletList" (map (Stringify) items)  blockToCustom (OrderedList (num,sty,delim) items) =-  invoke @e "OrderedList" (map (Stringify @e) items) num (show sty) (show delim)+  invoke "OrderedList" (map (Stringify) items) num (show sty) (show delim)  blockToCustom (DefinitionList items) =-  invoke @e "DefinitionList"-               (map (KeyValue . (Stringify @e *** map (Stringify @e))) items)+  invoke "DefinitionList"+               (map (KeyValue . (Stringify *** map (Stringify))) items)  blockToCustom (Div attr items) =-  invoke @e "Div" (Stringify @e items) (attrToMap attr)+  invoke "Div" (Stringify items) (attrToMap attr)  -- | Convert list of Pandoc block elements to Custom.-blockListToCustom :: forall e. PeekError e+blockListToCustom :: forall e. LuaError e                   => [Block]       -- ^ List of block elements                   -> LuaE e String blockListToCustom xs = do-  blocksep <- invoke @e "Blocksep"+  blocksep <- invoke "Blocksep"   bs <- mapM blockToCustom xs   return $ mconcat $ intersperse blocksep bs  -- | Convert list of Pandoc inline elements to Custom.-inlineListToCustom :: forall e. PeekError e => [Inline] -> LuaE e String+inlineListToCustom :: forall e. LuaError e => [Inline] -> LuaE e String inlineListToCustom lst = do   xs <- mapM (inlineToCustom @e) lst   return $ mconcat xs  -- | Convert Pandoc inline element to Custom.-inlineToCustom :: forall e. PeekError e => Inline -> LuaE e String+inlineToCustom :: forall e. LuaError e => Inline -> LuaE e String -inlineToCustom (Str str) = invoke @e "Str" str+inlineToCustom (Str str) = invoke "Str" str -inlineToCustom Space = invoke @e "Space"+inlineToCustom Space = invoke "Space" -inlineToCustom SoftBreak = invoke @e "SoftBreak"+inlineToCustom SoftBreak = invoke "SoftBreak" -inlineToCustom (Emph lst) = invoke @e "Emph" (Stringify @e lst)+inlineToCustom (Emph lst) = invoke "Emph" (Stringify lst) -inlineToCustom (Underline lst) = invoke @e "Underline" (Stringify @e lst)+inlineToCustom (Underline lst) = invoke "Underline" (Stringify lst) -inlineToCustom (Strong lst) = invoke @e "Strong" (Stringify @e lst)+inlineToCustom (Strong lst) = invoke "Strong" (Stringify lst) -inlineToCustom (Strikeout lst) = invoke @e "Strikeout" (Stringify @e lst)+inlineToCustom (Strikeout lst) = invoke "Strikeout" (Stringify lst) -inlineToCustom (Superscript lst) = invoke @e "Superscript" (Stringify @e lst)+inlineToCustom (Superscript lst) = invoke "Superscript" (Stringify lst) -inlineToCustom (Subscript lst) = invoke @e "Subscript" (Stringify @e lst)+inlineToCustom (Subscript lst) = invoke "Subscript" (Stringify lst) -inlineToCustom (SmallCaps lst) = invoke @e "SmallCaps" (Stringify @e lst)+inlineToCustom (SmallCaps lst) = invoke "SmallCaps" (Stringify lst)  inlineToCustom (Quoted SingleQuote lst) =-  invoke @e "SingleQuoted" (Stringify @e lst)+  invoke "SingleQuoted" (Stringify lst)  inlineToCustom (Quoted DoubleQuote lst) =-  invoke @e "DoubleQuoted" (Stringify @e lst)+  invoke "DoubleQuoted" (Stringify lst)  inlineToCustom (Cite cs lst) =-  invoke @e "Cite" (Stringify @e lst) (map (Stringify @e) cs)+  invoke "Cite" (Stringify lst) (map (Stringify) cs)  inlineToCustom (Code attr str) =-  invoke @e "Code" str (attrToMap attr)+  invoke "Code" str (attrToMap attr)  inlineToCustom (Math DisplayMath str) =-  invoke @e "DisplayMath" str+  invoke "DisplayMath" str  inlineToCustom (Math InlineMath str) =-  invoke @e "InlineMath" str+  invoke "InlineMath" str  inlineToCustom (RawInline format str) =-  invoke @e "RawInline" (Stringify @e format) str+  invoke "RawInline" (Stringify format) str -inlineToCustom LineBreak = invoke @e "LineBreak"+inlineToCustom LineBreak = invoke "LineBreak"  inlineToCustom (Link attr txt (src,tit)) =-  invoke @e "Link" (Stringify @e txt) src tit (attrToMap attr)+  invoke "Link" (Stringify txt) src tit (attrToMap attr)  inlineToCustom (Image attr alt (src,tit)) =-  invoke @e "Image" (Stringify @e alt) src tit (attrToMap attr)+  invoke "Image" (Stringify alt) src tit (attrToMap attr) -inlineToCustom (Note contents) = invoke @e "Note" (Stringify @e contents)+inlineToCustom (Note contents) = invoke "Note" (Stringify contents)  inlineToCustom (Span attr items) =-  invoke @e "Span" (Stringify @e items) (attrToMap attr)+  invoke "Span" (Stringify items) (attrToMap attr)
src/Text/Pandoc/Writers/Docx.hs view
@@ -769,7 +769,11 @@  -- | Convert a list of Pandoc blocks to OpenXML. blocksToOpenXML :: (PandocMonad m) => WriterOptions -> [Block] -> WS m [Content]-blocksToOpenXML opts = fmap concat . mapM (blockToOpenXML opts) . separateTables+blocksToOpenXML opts = fmap concat . mapM (blockToOpenXML opts) . separateTables . filter (not . isForeignRawBlock)++isForeignRawBlock :: Block -> Bool+isForeignRawBlock (RawBlock format _) = format /= "openxml"+isForeignRawBlock _                   = False  -- Word combines adjacent tables unless you put an empty paragraph between -- them.  See #4315.
src/Text/Pandoc/Writers/HTML.hs view
@@ -44,6 +44,7 @@ import Text.DocTemplates (FromContext (lookupContext), Context (..)) import Text.Blaze.Html hiding (contents) import Text.Pandoc.Translations (Term(Abstract))+import Text.Pandoc.CSS (cssAttributes) import Text.Pandoc.Definition import Text.Pandoc.Highlighting (formatHtmlBlock, formatHtmlInline, highlight,                                  styleToCss)@@ -1282,28 +1283,47 @@ tableCellToHtml opts ctype colAlign (Cell attr align rowspan colspan item) = do   contents <- blockListToHtml opts item   html5 <- gets stHtml5+  let (ident, cls, kvs) = attr   let tag' = case ctype of         BodyCell   -> H.td         HeaderCell -> H.th   let align' = case align of         AlignDefault -> colAlign         _            -> align-  let alignAttribs = case alignmentToString align' of-        Nothing ->-          mempty-        Just alignStr ->-          if html5-          then A.style (toValue $ "text-align: " <> alignStr <> ";")-          else A.align (toValue alignStr)-  otherAttribs <- attrsToHtml opts attr+  let kvs' = case alignmentToString align' of+               Nothing ->+                 kvs+               Just alignStr ->+                 if html5+                 then addStyle ("text-align", alignStr) kvs+                 else case break ((== "align") . fst) kvs of+                   (_, []) -> ("align", alignStr) : kvs+                   (xs, _:rest) -> xs ++ ("align", alignStr) : rest+  otherAttribs <- attrsToHtml opts (ident, cls, kvs')   let attribs = mconcat-              $ alignAttribs-              : colspanAttrib colspan+              $ colspanAttrib colspan               : rowspanAttrib rowspan               : otherAttribs   return $ do     tag' ! attribs $ contents     nl++-- | Adds a key-value pair to the @style@ attribute.+addStyle :: (Text, Text) -> [(Text, Text)] -> [(Text, Text)]+addStyle (key, value) kvs =+  let cssToStyle = T.intercalate " " . map (\(k, v) -> k <> ": " <> v <> ";")+  in case break ((== "style") . fst) kvs of+    (_, []) ->+      -- no style attribute yet, add new one+      ("style", cssToStyle [(key, value)]) : kvs+    (xs, (_,cssStyles):rest) ->+      -- modify the style attribute+      xs ++ ("style", cssToStyle modifiedCssStyles) : rest+      where+        modifiedCssStyles =+          case break ((== key) . fst) $ cssAttributes cssStyles of+            (cssAttribs, []) -> (key, value) : cssAttribs+            (pre, _:post)    -> pre ++ (key, value) : post  toListItems :: [Html] -> [Html] toListItems items = map toListItem items ++ [nl]
src/Text/Pandoc/Writers/LaTeX.hs view
@@ -235,10 +235,13 @@              isSlide _                         = False          let (titleBs, slideBs) = break isSlide ys          return $-           if null titleBs-              then Div (ident,"section":dclasses,dkvs) xs-              else Div (ident,"section":dclasses,dkvs)-                    (h : Div ("","slide":dclasses,dkvs) (h:titleBs) : slideBs)+           case titleBs of+              [] -> Div (ident,"section":dclasses,dkvs) xs+              [Div (_,"notes":_,_) _] ->  -- see #7857, don't create frame+                    -- just for speaker notes after section heading+                    Div (ident,"section":dclasses,dkvs) xs+              _  -> Div (ident,"section":dclasses,dkvs)+                     (h : Div ("","slide":dclasses,dkvs) (h:titleBs) : slideBs)   | otherwise     = return $ Div (ident,"slide":dclasses,dkvs) xs elementToBeamer _ x = return x@@ -281,14 +284,15 @@   let fragile = "fragile" `elem` classes ||                 not (null $ query hasCodeBlock bs ++ query hasCode bs)   let frameoptions = ["allowdisplaybreaks", "allowframebreaks", "fragile",-                      "b", "c", "t", "environment",+                      "b", "c", "t", "environment", "s", "squeeze",                       "label", "plain", "shrink", "standout",                       "noframenumbering"]   let optionslist = ["fragile" | fragile                                , isNothing (lookup "fragile" kvs)                                , "fragile" `notElem` classes] ++                     [k | k <- classes, k `elem` frameoptions] ++-                    [k <> "=" <> v | (k,v) <- kvs, k `elem` frameoptions]+                    [k <> "=" <> v | (k,v) <- kvs, k `elem` frameoptions] +++                    [v | ("frameoptions", v) <- kvs]   let options = if null optionslist                    then empty                    else brackets (literal (T.intercalate "," optionslist))
src/Text/Pandoc/Writers/Man.hs view
@@ -27,7 +27,6 @@ import Text.Pandoc.Options import Text.DocLayout import Text.Pandoc.Shared-import Text.Pandoc.Walk (walk) import Text.Pandoc.Templates (renderTemplate) import Text.Pandoc.Writers.Math import Text.Pandoc.Writers.Shared@@ -229,7 +228,7 @@ definitionListItemToMan opts (label, defs) = do   -- in most man pages, option and other code in option lists is boldface,   -- but not other things, so we try to reproduce this style:-  labelText <- inlineListToMan opts $ makeCodeBold label+  labelText <- inlineListToMan opts label   contents <- if null defs                  then return empty                  else liftM vcat $ forM defs $ \case@@ -247,11 +246,6 @@                           [] -> return empty   return $ literal ".TP" $$ nowrap labelText $$ contents -makeCodeBold :: [Inline] -> [Inline]-makeCodeBold = walk go-  where go x@Code{} = Strong [x]-        go x        = x- -- | Convert list of Pandoc block elements to man. blockListToMan :: PandocMonad m                => WriterOptions -- ^ Options@@ -293,7 +287,8 @@ inlineToMan opts (Cite _ lst) =   inlineListToMan opts lst inlineToMan opts (Code _ str) =-  withFontFeature 'C' (return (literal $ escString opts str))+  -- note that the V font is specially defined in the default man template+  withFontFeature 'V' (return (literal $ escString opts str)) inlineToMan opts (Str str@(T.uncons -> Just ('.',_))) =   return $ afterBreak "\\&" <> literal (escString opts str) inlineToMan opts (Str str) = return $ literal $ escString opts str
src/Text/Pandoc/Writers/Markdown.hs view
@@ -360,7 +360,7 @@                    case () of                         () | "blurb" `elem` classes' -> prefixed "B> " contents <> blankline                            | "aside" `elem` classes' -> prefixed "A> " contents <> blankline-                           -- | necessary to enable option to create a bibliography+                           -- necessary to enable option to create a bibliography                            | (take 3 (T.unpack id')) == "ref" -> contents <> blankline                            | otherwise -> contents <> blankline            | isEnabled Ext_fenced_divs opts &&@@ -599,7 +599,8 @@                 rawHeaders <- padRow <$> mapM (blockListToMarkdown opts) headers                 rawRows <- mapM (fmap padRow . mapM (blockListToMarkdown opts))                            rows-                (id,) <$> pipeTable (all null headers) aligns' rawHeaders rawRows+                (id,) <$> pipeTable opts (all null headers) aligns' widths'+                            rawHeaders rawRows             | not hasBlocks &&               isEnabled Ext_multiline_tables opts -> do                 rawHeaders <- padRow <$> mapM (blockListToMarkdown opts) headers@@ -616,7 +617,8 @@                 rawHeaders <- padRow <$> mapM (blockListToMarkdown opts) headers                 rawRows <- mapM (fmap padRow . mapM (blockListToMarkdown opts))                            rows-                (id,) <$> pipeTable (all null headers) aligns' rawHeaders rawRows+                (id,) <$> pipeTable opts (all null headers) aligns' widths'+                           rawHeaders rawRows             | isEnabled Ext_raw_html opts -> fmap (id,) $                    literal <$>                    writeHtml5String opts{ writerTemplate = Nothing } (Pandoc nullMeta [t])@@ -667,19 +669,31 @@        _ -> s  pipeTable :: PandocMonad m-          => Bool -> [Alignment] -> [Doc Text] -> [[Doc Text]]+          => WriterOptions+          -> Bool -> [Alignment] -> [Double] -> [Doc Text] -> [[Doc Text]]           -> MD m (Doc Text)-pipeTable headless aligns rawHeaders rawRows = do+pipeTable opts headless aligns widths rawHeaders rawRows = do   let sp = literal " "   let blockFor AlignLeft   x y = lblock (x + 2) (sp <> y) <> lblock 0 empty       blockFor AlignCenter x y = cblock (x + 2) (sp <> y <> sp) <> lblock 0 empty       blockFor AlignRight  x y = rblock (x + 2) (y <> sp) <> lblock 0 empty       blockFor _           x y = lblock (x + 2) (sp <> y) <> lblock 0 empty-  let widths = map (max 3 . maybe 3 maximum . nonEmpty . map offset) $-                     transpose (rawHeaders : rawRows)+  let contentWidths = map (max 3 . maybe 3 maximum . nonEmpty . map offset) $+                       transpose (rawHeaders : rawRows)+  let colwidth = writerColumns opts+  let numcols = length contentWidths+  let maxwidth = sum contentWidths+  variant <- asks envVariant+  let pipeWidths = if variant == Markdown &&+                      not (all (== 0) widths) &&+                      maxwidth + (numcols + 1) > colwidth+                      then map+                            (floor . (* fromIntegral (colwidth - (numcols +1))))+                            widths+                      else contentWidths   let torow cs = nowrap $ literal "|" <>                     hcat (intersperse (literal "|") $-                          zipWith3 blockFor aligns widths (map chomp cs))+                          zipWith3 blockFor aligns contentWidths (map chomp cs))                     <> literal "|"   let toborder a w = literal $ case a of                           AlignLeft    -> ":" <> T.replicate (w + 1) "-"@@ -693,7 +707,7 @@                   then torow (replicate (length aligns) empty)                   else torow rawHeaders   let border = nowrap $ literal "|" <> hcat (intersperse (literal "|") $-                        zipWith toborder aligns widths) <> literal "|"+                        zipWith toborder aligns pipeWidths) <> literal "|"   let body   = vcat $ map torow rawRows   return $ header $$ border $$ body
src/Text/Pandoc/Writers/Muse.hs view
@@ -213,8 +213,8 @@   topLevel <- asks envTopLevel   return $ (if topLevel then nest 1 else id) (vcat contents) $$ blankline   where orderedListItemToMuse :: PandocMonad m-                              => Text     -- ^ marker for list item-                              -> [Block]  -- ^ list item (list of blocks)+                              => Text     -- marker for list item+                              -> [Block]  -- list item (list of blocks)                               -> Muse m (Doc Text)         orderedListItemToMuse marker item = hang (T.length marker + 1) (literal marker <> space)           <$> blockListToMuse item@@ -597,7 +597,7 @@     else if null lst' || startsWithSpace lst' || endsWithSpace lst'            then emphasis "**<em>" "</em>**" lst'            else emphasis "***" "***" lst'--- | Underline is only supported in Emacs Muse mode.+-- Underline is only supported in Emacs Muse mode. inlineToMuse (Underline lst) = do   opts <- asks envOptions   contents <- inlineListToMuse lst
src/Text/Pandoc/Writers/Powerpoint/Output.hs view
@@ -448,7 +448,7 @@         in (thisId, Elem newRelationship : relationships)       in (newRelationshipIds, e {elContent = elContent e <> newRelationships}) -    -- | Whether the layout needs to be added to the Relationships element.+    -- Whether the layout needs to be added to the Relationships element.     isNew :: Element -> SlideLayout -> Bool     isNew relationships SlideLayout{..} = let       toDetails = fmap (takeFileName . T.unpack)
src/Text/Pandoc/Writers/Roff.hs view
@@ -55,6 +55,7 @@                                                        ('I',False)                                                      , ('B',False)                                                      , ('C',False)+                                                     , ('V',False)                                                      ]                                 , stHasTables     = False                                 }@@ -106,6 +107,7 @@   features <- gets stFontFeatures   inHeader <- gets stInHeader   let filling = ['C' | fromMaybe False $ Map.lookup 'C' features] +++                ['V' | fromMaybe False $ Map.lookup 'V' features] ++                 ['B' | inHeader ||                        fromMaybe False (Map.lookup 'B' features)] ++                 ['I' | fromMaybe False $ Map.lookup 'I' features]
src/Text/Pandoc/Writers/TEI.hs view
@@ -192,7 +192,7 @@                              ,("type","separator")                              ,("rendition","line")] --- | TEI Tables+-- TEI Tables -- TEI Simple's tables are composed of cells and rows; other -- table info in the AST is here lossily discard. blockToTEI opts (Table _ blkCapt specs thead tbody tfoot) = do
src/Text/Pandoc/Writers/ZimWiki.hs view
@@ -324,7 +324,7 @@                      DisplayMath -> "$$"                      InlineMath  -> "$" --- | f == Format "html"     = return $ "<html>" <> str <> "</html>"+-- f == Format "html"     = return $ "<html>" <> str <> "</html>" inlineToZimWiki opts il@(RawInline f str)   | f == Format "zimwiki" = return str   | f == Format "html"    = indentFromHTML opts str
stack.yaml view
@@ -7,27 +7,28 @@ packages: - '.' extra-deps:-- skylighting-core-0.12.1-- skylighting-0.12.1+- skylighting-core-0.12.2+- skylighting-0.12.2 - doctemplates-0.10.0.1 - emojis-0.1.2 - doclayout-0.3.1.1-- lpeg-1.0.1-- hslua-2.0.1-- hslua-aeson-2.0.1-- hslua-classes-2.0.0-- hslua-core-2.0.0.2-- hslua-marshalling-2.0.1-- hslua-module-path-1.0.0-- hslua-module-system-1.0.0-- hslua-module-text-1.0.0-- hslua-module-version-1.0.0-- hslua-objectorientation-2.0.1-- hslua-packaging-2.0.0-- lua-2.0.2-- tasty-hslua-1.0.0-- tasty-lua-1.0.0-- pandoc-lua-marshal-0.1.3.1+- lpeg-1.0.2+- hslua-2.1.0+- hslua-aeson-2.1.0+- hslua-classes-2.1.0+- hslua-core-2.1.0+- hslua-marshalling-2.1.0+- hslua-module-path-1.0.1+- hslua-module-system-1.0.1+- hslua-module-text-1.0.1+- hslua-module-version-1.0.1+- hslua-objectorientation-2.1.0+- hslua-packaging-2.1.0+- lua-2.1.0+- lua-arbitrary-1.0.0+- tasty-hslua-1.0.1+- tasty-lua-1.0.1+- pandoc-lua-marshal-0.1.4 - pandoc-types-1.22.1 - aeson-pretty-0.8.9 - unicode-transforms-0.4.0@@ -43,5 +44,3 @@ resolver: lts-18.10 nix:   packages: [zlib]--
test/Tests/Command.hs view
@@ -1,3 +1,4 @@+{-# LANGUAGE BangPatterns #-} {- |    Module      : Tests.Command    Copyright   : © 2006-2022 John MacFarlane@@ -8,6 +9,27 @@    Portability : portable  Run commands, and test results, defined in markdown files.++A command test is a code block with the following format:++> ```+> % pandoc -f markdown -t latex+> *hi*+> ^D+> \emph{hi}+> ```++- The first line, after "%", should contain a command to run.+- Then comes zero or more lines of text which will be passed+  to the command as stdin.+- The stdin terminates with a line containing "^D".+- The following lines are typically the expected output+  on stdout.+- If any output on stderr is expected, it should come first+  and each stderr line should be preceded by the string "2> ".+- If a nonzero exit status is expected, the last line should+  contain "=> " followed by the exit status.+ -} module Tests.Command (runTest, tests) where@@ -21,7 +43,6 @@ import System.Directory import System.Exit import System.FilePath ((</>))-import System.IO (hPutStr, stderr) import System.IO.Unsafe (unsafePerformIO) import System.Process import Test.Tasty@@ -39,12 +60,13 @@ execTest testExePath cmd inp = do   env' <- setupEnvironment testExePath   let pr = (shell (pandocToEmulate True cmd)){ env = Just env' }-  (ec, out', err') <- readCreateProcessWithExitCode pr inp+  (!ec, out', err') <- readCreateProcessWithExitCode pr inp+  let err = unlines . map ("2> " ++) . lines $ err'   -- filter \r so the tests will work on Windows machines-  let out = filter (/= '\r') $ err' ++ out'-  case ec of-    ExitFailure _ -> hPutStr stderr err'-    ExitSuccess   -> return ()+  let out'' = filter (/= '\r') $ err ++ out'+  let out = out'' ++ case ec of+                        ExitFailure !n -> "=> " ++ show n ++ "\n"+                        ExitSuccess    -> ""   return (ec, out)  pandocToEmulate :: Bool -> String -> String@@ -63,15 +85,11 @@         -> String    -- ^ Expected output         -> TestTree runTest testExePath testname cmd inp norm = testCase testname $ do-  (ec, out) <- execTest testExePath cmd inp-  result  <- if ec == ExitSuccess-                then-                  if out == norm-                     then return TestPassed-                     else return-                          $ TestFailed cmd "expected"-                          $ getDiff (lines out) (lines norm)-                else return $ TestError ec+  (_ec, out) <- execTest testExePath cmd inp+  result  <- if out == norm+                then return TestPassed+                else return $ TestFailed cmd "expected"+                            $ getDiff (lines out) (lines norm)   assertBool (show result) (result == TestPassed)  tests :: TestTree
test/Tests/Writers/AsciiDoc.hs view
@@ -9,14 +9,23 @@ import Text.Pandoc.Builder  asciidoc :: (ToPandoc a) => a -> String-asciidoc = unpack . purely (writeAsciiDoc def{ writerWrapText = WrapNone }) . toPandoc+asciidoc = unpack . purely (writeAsciiDoc def) . toPandoc +asciidoctor :: (ToPandoc a) => a -> String+asciidoctor = unpack . purely (writeAsciiDoctor def) . toPandoc+ testAsciidoc :: (ToString a, ToPandoc a)              => String              -> (a, String)              -> TestTree testAsciidoc = test asciidoc +testAsciidoctor :: (ToString a, ToPandoc a)+             => String+             -> (a, String)+             -> TestTree+testAsciidoctor = test asciidoctor+ tests :: [TestTree] tests = [ testGroup "emphasis"           [ testAsciidoc "emph word before" $@@ -76,4 +85,12 @@                                            , "|==="                                            ]           ]+        , testGroup "lists"+          [ testAsciidoctor "bullet task list" $+               bulletList [plain "☐ a", plain "☒ b"] =?> unlines+                                           [ "* [ ] a"+                                           , "* [x] b"+                                           ]+          ]         ]+
test/Tests/Writers/Docx.hs view
@@ -133,6 +133,11 @@             "docx/table_one_row.native"             "docx/golden/table_one_row.docx"           , docxTest+            "tables separated with RawBlock"+            def+            "docx/tables_separated_with_rawblock.native"+            "docx/golden/tables_separated_with_rawblock.docx"+          , docxTest             "code block"             def             "docx/codeblock.native"
test/command/1718.md view
@@ -6,7 +6,7 @@  [^2]: the second, unused, note. ^D-[WARNING] Note with key '2' defined at line 5 column 1 but not used.+2> [WARNING] Note with key '2' defined at line 5 column 1 but not used. [ Para     [ Str "Note"     , Note
test/command/3534.md view
@@ -3,8 +3,7 @@ I want to explain the interface of \lstinline[language=Java]{public class MyClass}. ^D <p>I want to explain the interface of <code-class="sourceCode java"><span class="kw">public</span> <span-class="kw">class</span> MyClass</code>.</p>+class="sourceCode java"><span class="kw">public</span> <span class="kw">class</span> MyClass</code>.</p>  ``` @@ -12,8 +11,8 @@ % pandoc -f latex -t html I want to explain the interface of \lstinline{public class MyClass}. ^D-<p>I want to explain the interface of <code>public class-MyClass</code>.</p>+<p>I want to explain the interface of+<code>public class MyClass</code>.</p>  ``` @@ -47,8 +46,7 @@ I want to explain the interface of \mintinline{java}{public class MyClass}. ^D <p>I want to explain the interface of <code-class="sourceCode java"><span class="kw">public</span> <span-class="kw">class</span> MyClass</code>.</p>+class="sourceCode java"><span class="kw">public</span> <span class="kw">class</span> MyClass</code>.</p>  ``` @@ -57,8 +55,7 @@ I want to explain the interface of \mintinline{java}|public class MyClass|. ^D <p>I want to explain the interface of <code-class="sourceCode java"><span class="kw">public</span> <span-class="kw">class</span> MyClass</code>.</p>+class="sourceCode java"><span class="kw">public</span> <span class="kw">class</span> MyClass</code>.</p>  ```
test/command/3568.md view
@@ -10,7 +10,7 @@ normal \f[I]italic \f[BI]bold in the middle\f[I] only italic\f[R] normal. .PP-normal \f[B]bold \f[CB]code\f[B] more bold\f[R] normal.+normal \f[B]bold \f[VB]code\f[B] more bold\f[R] normal. .PP-normal \f[C]code\f[R] normal.+normal \f[V]code\f[R] normal. ```
test/command/3734.md view
@@ -5,7 +5,7 @@ | aaaaaaaaaaaa |       | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc                                                              |-|--------------|-------|--------------------------------------------------------------------------|+|------------|-------|------------------------------------------------------| | aaaaaaaaaaaa |       | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ``` @@ -16,7 +16,7 @@ | aaaaaaaaaaaa |       | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc                                                              |-|--------------|-------|--------------------------------------------------------------------------|+|------------|-------|------------------------------------------------------| | aaaaaaaaaaaa |       | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ```
test/command/3752.md view
@@ -1,9 +1,9 @@ ``` % pandoc command/chap1/text.md command/chap2/text.md -f markdown+rebase_relative_paths --verbose -t docx -o - | pandoc -f docx -t plain ^D-[INFO] Loaded command/chap1/spider.png from command/chap1/spider.png-[INFO] Loaded command/chap2/spider.png from command/chap2/spider.png-[INFO] Loaded command/chap1/../../lalune.jpg from command/chap1/../../lalune.jpg+2> [INFO] Loaded command/chap1/spider.png from command/chap1/spider.png+2> [INFO] Loaded command/chap2/spider.png from command/chap2/spider.png+2> [INFO] Loaded command/chap1/../../lalune.jpg from command/chap1/../../lalune.jpg Chapter one  A spider: [spider]
test/command/512.md view
@@ -37,7 +37,7 @@  __ link1_ ^D-[WARNING] Circular reference 'link1' at line 1 column 15+2> [WARNING] Circular reference 'link1' at line 1 column 15 <p><a href="">click here</a></p> ```
test/command/5620.md view
@@ -4,6 +4,6 @@ :   Write output to *OUTFILE* instead of `stdout`(3) ^D .TP-\f[B]\f[CB]-o\f[B]\f[R], \f[B]\f[CB]--output=\f[B]\f[R]\f[I]OUTFILE\f[R]-Write output to \f[I]OUTFILE\f[R] instead of \f[C]stdout\f[R](3)+\f[V]-o\f[R], \f[V]--output=\f[R]\f[I]OUTFILE\f[R]+Write output to \f[I]OUTFILE\f[R] instead of \f[V]stdout\f[R](3) ```
+ test/command/5876.md view
@@ -0,0 +1,60 @@+```+% pandoc -s -t native --data-dir=command/5876 --metadata-file=5876.yaml+Hello+^D+Pandoc+  Meta+    { unMeta =+        fromList+          [ ( "desc"+            , MetaInlines+                [ Str "Found"+                , Space+                , Str "in"+                , Space+                , Str "metadata"+                , Space+                , Str "directory."+                ]+            )+          ]+    }+  [ Para [ Str "Hello" ] ]+```+```+% pandoc -s -t native --data-dir=command/5876 --metadata-file=command/5876.yaml+Hello+^D+Pandoc+  Meta+    { unMeta =+        fromList+          [ ( "desc"+            , MetaInlines+                [ Str "Found"+                , Space+                , Str "in"+                , Space+                , Str "working"+                , Space+                , Str "directory."+                ]+            )+          ]+    }+  [ Para [ Str "Hello" ] ]+```+```+% pandoc -s -t native --data-dir=command/5876 --metadata-file=does-not-exist.yaml+Hello+^D+2> Could not find metadata file does-not-exist.yaml+=> 98+```+```+% pandoc -s -t native --metadata-file=does-not-exist.yaml+Hello+^D+2> Could not find metadata file does-not-exist.yaml+=> 98+```
+ test/command/5876.yaml view
@@ -0,0 +1,3 @@+---+desc: Found in working directory.+---
+ test/command/5876/metadata/5876.yaml view
@@ -0,0 +1,3 @@+---+desc: Found in metadata directory.+---
+ test/command/5876/metadata/command/5876.yaml view
@@ -0,0 +1,3 @@+---+desc: Should not be loaded.+---
test/command/6837.md view
@@ -14,9 +14,9 @@ % pandoc -t markdown+lhs # Hi ^D-[WARNING] Rendering heading 'Hi' as a paragraph.-  ATX headings cannot be used in literate Haskell, because '#' is not-  allowed in column 1. Consider using --markdown-headings=setext.+2> [WARNING] Rendering heading 'Hi' as a paragraph.+2>   ATX headings cannot be used in literate Haskell, because '#' is not+2>   allowed in column 1. Consider using --markdown-headings=setext. Hi ```
test/command/6873.md view
@@ -2,7 +2,7 @@ % pandoc -f latex -t native --citeproc \cite[„Etwas […{]} auslassen“]{key} ^D-[WARNING] Citeproc: citation key not found+2> [WARNING] Citeproc: citation key not found [ Para     [ Cite         [ Citation
test/command/7099.md view
@@ -2,7 +2,7 @@ % pandoc -f html -t native --verbose <iframe src=""></iframe> ^D-[INFO] Skipped '<iframe src></iframe>' at input line 1 column 16+2> [INFO] Skipped '<iframe src></iframe>' at input line 1 column 16 [] ``` @@ -10,9 +10,9 @@ % pandoc -f html -t native --verbose <iframe src="h:invalid@url"></iframe> ^D-[INFO] Fetching h:invalid@url...-[WARNING] Could not fetch resource h:invalid@url: Could not fetch h:invalid@url-  InvalidUrlException "h:invalid@url" "Invalid scheme"-[INFO] Skipped '<iframe src="h:invalid@url"></iframe>' at input line 1 column 29+2> [INFO] Fetching h:invalid@url...+2> [WARNING] Could not fetch resource h:invalid@url: Could not fetch h:invalid@url+2>   InvalidUrlException "h:invalid@url" "Invalid scheme"+2> [INFO] Skipped '<iframe src="h:invalid@url"></iframe>' at input line 1 column 29 [] ```
+ test/command/7847.md view
@@ -0,0 +1,85 @@+```+% pandoc -f html -t markdown_strict+pipe_tables+<table>+<colgroup>+<col style="width: 20%" />+<col style="width: 60%" />+<col style="width: 20%" />+</colgroup>+<thead>+<tr class="header">+<th>aaa</th>+<th>bbb</th>+<th>ccc</th>+</tr>+</thead>+<tbody>+<tr class="odd">+<td>Consequat nisi sit amet nibh. Nunc mi tortor, tristique+sit amet, rhoncus porta, malesuada elementum, nisi.</td>+<td></td>+<td>ccc</td>+</tr>+</tbody>+</table>+^D+| aaa                                                                                                         | bbb | ccc |+|---------------|------------------------------------------|---------------|+| Consequat nisi sit amet nibh. Nunc mi tortor, tristique sit amet, rhoncus porta, malesuada elementum, nisi. |     | ccc |++```++```+% pandoc -f html -t markdown_strict+pipe_tables+<table>+<tr>+<th>aaa</th>+<th>bbb</th>+<th>ccc</th>+</tr>+<tr>+<td>Consequat nisi sit amet nibh. Nunc mi tortor, tristique+sit amet, rhoncus porta, malesuada elementum, nisi.</td>+<td></td>+<td>ccc</td>+</tr>+</table>+^D+| aaa                                                                                                         | bbb | ccc |+|-------------------------------------------------------------------------------------------------------------|-----|-----|+| Consequat nisi sit amet nibh. Nunc mi tortor, tristique sit amet, rhoncus porta, malesuada elementum, nisi. |     | ccc |++```++```+% pandoc -f html -t commonmark+pipe_tables+<table>+<colgroup>+<col style="width: 20%" />+<col style="width: 60%" />+<col style="width: 20%" />+</colgroup>+<thead>+<tr class="header">+<th>aaa</th>+<th>bbb</th>+<th>ccc</th>+</tr>+</thead>+<tbody>+<tr class="odd">+<td>Consequat nisi sit amet nibh. Nunc mi tortor, tristique+sit amet, rhoncus porta, malesuada elementum, nisi.</td>+<td>bbb</td>+<td>ccc</td>+</tr>+</tbody>+</table>+^D+| aaa                                                                                                         | bbb | ccc |+|-------------------------------------------------------------------------------------------------------------|-----|-----|+| Consequat nisi sit amet nibh. Nunc mi tortor, tristique sit amet, rhoncus porta, malesuada elementum, nisi. | bbb | ccc |++```++
+ test/command/7857.md view
@@ -0,0 +1,22 @@+```+% pandoc --slide-level=2 -t beamer+# section++::: notes+my note+:::++## slide++ok+^D+\hypertarget{section}{%+\section{section}\label{section}}++\note{my note}++\begin{frame}{slide}+\protect\hypertarget{slide}{}+ok+\end{frame}+```
+ test/command/7858.md view
@@ -0,0 +1,6 @@+```+% pandoc -t html --columns=50 --wrap=auto+`neuth asontue stheuosnt aeosunth asnoetuh asneotuh snatehou snatoehu sntahe ousntahoe unstaheou sntaheou aoeu sthoeu sntaoeusnth ansoetuhs atoeuh saonteu`+^D+<p><code>neuth asontue stheuosnt aeosunth asnoetuh asneotuh snatehou snatoehu sntahe ousntahoe unstaheou sntaheou aoeu sthoeu sntaoeusnth ansoetuhs atoeuh saonteu</code></p>+```
+ test/command/7861.md view
@@ -0,0 +1,7 @@+```+% pandoc -s -t native --data-dir=command/7861 --metadata-file=../../7861.yaml+Hello+^D+2> Could not find metadata file ../../7861.yaml+=> 98+```
+ test/command/7861.yaml view
+ test/command/7861/metadata/placeholder view
+ test/command/7863.md view
@@ -0,0 +1,20 @@+```+% pandoc -f commonmark+yaml_metadata_block+sourcepos -t native+---+key:+  |+  value+...+++Text+^D+[ Div+    ( "" , [] , [ ( "data-pos" , "8:1-9:1" ) ] )+    [ Para+        [ Span+            ( "" , [] , [ ( "data-pos" , "8:1-8:5" ) ] ) [ Str "Text" ]+        ]+    ]+]+```
+ test/command/7871.md view
@@ -0,0 +1,14 @@+```+% pandoc -f html -t html+<table>+<tr><td style="padding-right:4px;text-align:right">a</td></tr>+</table>+^D+<table>+<tbody>+<tr class="odd">+<td style="text-align: right; padding-right: 4px;">a</td>+</tr>+</tbody>+</table>+```
test/command/defaults-inheritance-2.md view
@@ -2,4 +2,5 @@ % pandoc -d command/defaults6 2>&1 ^D Error: Circular defaults file reference in 'command/defaults7.yaml'+=> 63 ```
test/command/duplicate_attributes.md view
@@ -2,6 +2,6 @@ % pandoc [span]{.foobar style="color:blue" class="zip" style="color:red"} ^D-[WARNING] Ignoring duplicate attribute style="color:red".+2> [WARNING] Ignoring duplicate attribute style="color:red". <p><span class="foobar zip" style="color:blue">span</span></p> ```
− test/command/jats.csl 
@@ -1,208 +0,0 @@-<?xml version="1.0" encoding="utf-8"?>-<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0" default-locale="en-US">-  <info>-    <title>Journal Article Tag Suite</title>-    <title-short>JATS</title-short>-    <id>http://www.zotero.org/styles/journal-article-tag-suite</id>-    <link href="https://github.com/MartinPaulEve/JATS-CSL/blob/master/jats.csl" rel="self"/>-    <link rel="documentation" href="http://jats.nlm.nih.gov/archiving/tag-library/1.0/index.html"/>-    <author>-      <name>Martin Paul Eve</name>-      <email>martin@martineve.com</email>-    </author>-    <category citation-format="numeric"/>-    <category field="medicine"/>-    <category field="biology"/>-    <summary>Use this style to generate bibliographic data in Journal Article Tagging Suite (JATS) 1.0 XML format</summary>-    <updated>2014-06-21T17:41:26+00:00</updated>-    <rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License. Originally by Martin Fenner.</rights>-  </info>-  <locale xml:lang="en">-    <terms>-        <term name="et-al">{{jats}}&lt;etal/&gt;{{/jats}}</term>-    </terms>-  </locale>-  <macro name="citation-number">-    <text variable="citation-number" prefix="{{jats}}id=&quot;ref-{{/jats}}" suffix="{{jats}}&quot;&gt;{{/jats}}"/>-  </macro>-  <macro name="author">-    <names variable="author">-        <name prefix="{{jats}}&lt;name&gt;{{/jats}}" suffix="{{jats}}&lt;/name&gt;{{/jats}}" name-as-sort-order="all" sort-separator="">-            <name-part name="family" text-case="capitalize-first" prefix="{{jats}}&lt;surname&gt;{{/jats}}" suffix="{{jats}}&lt;/surname&gt;{{/jats}}"/>-            <name-part name="given" text-case="capitalize-first" prefix="{{jats}}&lt;given-names&gt;{{/jats}}" suffix="{{jats}}&lt;/given-names&gt;{{/jats}}"/>-      </name>-      <substitute>-        <names variable="editor"/>-      </substitute>-    </names>-  </macro>--  <macro name="editor">-    <names variable="editor" prefix="{{jats}}&lt;person-group person-group-type=&quot;editor&quot;&gt;{{/jats}}" suffix="{{jats}}&lt;/person-group&gt;{{/jats}}">-      <name prefix="{{jats}}&lt;name&gt;{{/jats}}" suffix="{{jats}}&lt;/name&gt;{{/jats}}" name-as-sort-order="all" sort-separator="">-        <name-part name="family" text-case="capitalize-first" prefix="{{jats}}&lt;surname&gt;{{/jats}}" suffix="{{jats}}&lt;/surname&gt;{{/jats}}"/>-        <name-part name="given" text-case="capitalize-first" prefix="{{jats}}&lt;given-names&gt;{{/jats}}" suffix="{{jats}}&lt;/given-names&gt;{{/jats}}"/>-      </name>-      <substitute>-        <names variable="editor"/>-      </substitute>-    </names>-  </macro>--  <macro name="editor">-    <group delimiter=": ">-      <names variable="editor">-        <name prefix="{{jats}}&lt;name&gt;{{/jats}}" suffix="{{jats}}&lt;/name&gt;{{/jats}}" name-as-sort-order="all" sort-separator="">-          <name-part name="family" text-case="capitalize-first" prefix="{{jats}}&lt;surname&gt;{{/jats}}" suffix="{{jats}}&lt;/surname&gt;{{/jats}}"/>-          <name-part name="given" text-case="capitalize-first" prefix="{{jats}}&lt;given-names&gt;{{/jats}}" suffix="{{jats}}&lt;given-names&gt;{{/jats}}"/>-        </name>-      </names>-    </group>-  </macro>-  <macro name="title">-    <choose>-      <if type="book" match="any">-        <group prefix="{{jats}}&lt;source&gt;{{/jats}}" suffix="{{jats}}&lt;/source&gt;{{/jats}}">-	        <text variable="title"/>-				</group>			-			</if>-      <else>-        <group prefix="{{jats}}&lt;article-title&gt;{{/jats}}" suffix="{{jats}}&lt;/article-title&gt;{{/jats}}">-	        <text variable="title"/>-				</group>-      </else>-    </choose>-  </macro>-  <macro name="container-title">-    <text variable="container-title" form="short" prefix="{{jats}}&lt;source&gt;{{/jats}}" suffix="{{jats}}&lt;/source&gt;{{/jats}}"/>-  </macro>-  <macro name="publisher">-    <text variable="publisher" prefix="{{jats}}&lt;publisher-name&gt;{{/jats}}" suffix="{{jats}}&lt;/publisher-name&gt;{{/jats}}"/>-    <text variable="publisher-place" prefix="{{jats}}&lt;publisher-loc&gt;{{/jats}}" suffix="{{jats}}&lt;/publisher-loc&gt;{{/jats}}"/>-  </macro>-  <macro name="link">-    <choose>-      <if match="any" variable="DOI">-        <group prefix="{{jats}}&lt;pub-id pub-id-type=&quot;doi&quot;&gt;{{/jats}}" suffix="{{jats}}&lt;/pub-id&gt;{{/jats}}">-          <text variable="DOI"/>-        </group>-      </if>-    </choose>-    <choose>-      <if match="any" variable="PMID">-        <group prefix="{{jats}}&lt;ext-link ext-link-type=&quot;pmid&quot; {{/jats}}" suffix="{{jats}}&lt;/ext-link&gt;{{/jats}}">-          <text variable="PMID" prefix="{{jats}}xlink:href=&quot;http://www.ncbi.nlm.nih.gov/pubmed/{{/jats}}" suffix="{{jats}}&quot; xlink:type=&quot;simple&quot;&gt;{{/jats}}"/>-          <text variable="PMID"/>-        </group>-      </if>-    </choose>-    <choose>-      <if variable="URL" match="any">-        <group prefix="{{jats}}&lt;ext-link ext-link-type=&quot;uri&quot; {{/jats}}" suffix="{{jats}}&lt;/ext-link&gt;{{/jats}}">-          <text variable="URL" prefix="{{jats}}xlink:href=&quot;{{/jats}}" suffix="{{jats}}&quot; xlink:type=&quot;simple&quot;&gt;{{/jats}}"/>-          <text variable="URL"/>-        </group>-      </if>-    </choose>-  </macro>-  <macro name="date">-    <choose>-      <if type="article-journal article-magazine article-newspaper report patent book" match="any">-        <group prefix="{{jats}}&lt;date&gt;{{/jats}}" suffix="{{jats}}&lt;/date&gt;{{/jats}}">-          <date variable="issued">-            <date-part name="day" form="numeric-leading-zeros" prefix="{{jats}}&lt;day&gt;{{/jats}}" suffix="{{jats}}&lt;/day&gt;{{/jats}}"/>-            <date-part name="month" form="numeric-leading-zeros" prefix="{{jats}}&lt;month&gt;{{/jats}}" suffix="{{jats}}&lt;/month&gt;{{/jats}}"/>-            <date-part name="year" prefix="{{jats}}&lt;year&gt;{{/jats}}" suffix="{{jats}}&lt;/year&gt;{{/jats}}"/>-          </date>-        </group>-      </if>-      <else>-        <group prefix="{{jats}}&lt;date-in-citation content-type=&quot;access-date&quot;{{/jats}}" suffix="{{jats}}&lt;/date-in-citation&gt;{{/jats}}">-          <date variable="accessed" prefix="{{jats}} iso-8601-date=&quot;{{/jats}}" suffix="{{jats}}&quot;&gt;{{/jats}}">-            <date-part name="year"/>-            <date-part name="month" form="numeric-leading-zeros" prefix="{{jats}}-{{/jats}}"/>-            <date-part name="day" form="numeric-leading-zeros" prefix="{{jats}}-{{/jats}}"/>-          </date>-          <date variable="accessed">-            <date-part name="day" prefix="{{jats}}&lt;day&gt;{{/jats}}" suffix="{{jats}}&lt;/day&gt;{{/jats}}"/>-            <date-part name="month" form="numeric-leading-zeros" prefix="{{jats}}&lt;month&gt;{{/jats}}" suffix="{{jats}}&lt;/month&gt;{{/jats}}"/>-            <date-part name="year" prefix="{{jats}}&lt;year&gt;{{/jats}}" suffix="{{jats}}&lt;/year&gt;{{/jats}}"/>-          </date>-        </group>-      </else>-    </choose>-  </macro>-  <macro name="location">-    <choose>-      <if type="article-journal article-magazine" match="any">-        <text variable="volume" prefix="{{jats}}&lt;volume&gt;{{/jats}}" suffix="{{jats}}&lt;/volume&gt;{{/jats}}"/>-        <text variable="issue" prefix="{{jats}}&lt;issue&gt;{{/jats}}" suffix="{{jats}}&lt;/issue&gt;{{/jats}}"/>-      </if>-    </choose>-    <choose>-      <if type="article-journal article-magazine article-newspaper chapter" match="any">-        <text variable="page-first" prefix="{{jats}}&lt;fpage&gt;{{/jats}}" suffix="{{jats}}&lt;/fpage&gt;{{/jats}}"/>-      </if>-    </choose>-  </macro>-  <macro name="publication-type">-    <group prefix="{{jats}} publication-type=&quot;{{/jats}}" suffix="{{jats}}&quot;&gt;{{/jats}}">-      <choose>-        <if type="article-journal article-magazine article-newspaper" match="any">-          <text value="journal"/>-        </if>-        <else-if type="book" match="any">-          <text value="book"/>-        </else-if>-        <else-if type="chapter" match="any">-          <text value="bookchapter"/>-        </else-if>-        <else-if type="dataset" match="any">-          <text value="dataset"/>-        </else-if>-        <else-if type="patent" match="any">-          <text value="patent"/>-        </else-if>-        <else-if type="report" match="any">-          <text value="report"/>-        </else-if>-        <else-if type="review" match="any">-          <text value="review"/>-        </else-if>-        <else>-          <text value="standard"/>-        </else>-      </choose>-    </group>-  </macro>-  <citation collapse="citation-number">-    <sort>-      <key variable="citation-number"/>-    </sort>-    <layout delimiter=",">-      <group prefix="{{jats}}&lt;xref ref-type=&quot;bibr&quot; rid=&quot;{{/jats}}" suffix="{{jats}}&lt;/xref&gt;{{/jats}}">-        <text variable="citation-number" prefix="{{jats}}ref-{{/jats}}" suffix="{{jats}}&quot;&gt;{{/jats}}"/>-        <text variable="citation-number"/>-      </group>-    </layout>-  </citation>-  <bibliography sort-separator="">-    <layout>-      <group prefix="{{jats}}&lt;ref {{/jats}}" suffix="{{jats}}&lt;/ref&gt;{{/jats}}">-        <text macro="citation-number"/>-        <group prefix="{{jats}}&lt;element-citation{{/jats}}" suffix="{{jats}}&lt;/element-citation&gt;{{/jats}}">-          <text macro="publication-type"/>-          <text macro="author" prefix="{{jats}}&lt;person-group person-group-type=&quot;author&quot;&gt;{{/jats}}" suffix="{{jats}}&lt;/person-group&gt;{{/jats}}"/>-          <text macro="title" />-          <text macro="container-title"/>-          <text macro="editor"/>-          <text macro="publisher"/>-          <text macro="date"/>-          <text macro="location"/>-          <text macro="link"/>-        </group>-      </group>-    </layout>-  </bibliography>-</style>-
test/command/nested-table-to-asciidoc-6942.md view
@@ -67,7 +67,7 @@ </body> </html> ^D-[INFO] Not rendering Table ("",[],[]) (Caption Nothing []) [(AlignDefault,ColWidth 0.5),(AlignDefault,ColWidth 0.5)] (TableHead ("",[],[]) []) [TableBody ("",[],[]) (RowHeadColumns 0) [] [Row ("",[],[]) [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "a1"]],Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Table ("",[],[]) (Caption Nothing []) [(AlignDefault,ColWidthDefault),(AlignDefault,ColWidthDefault)] (TableHead ("",[],[]) []) [TableBody ("",[],[]) (RowHeadColumns 0) [] [Row ("",[],[]) [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "1"]],Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "2"]]]]] (TableFoot ("",[],[]) [])]]]] (TableFoot ("",[],[]) [])+2> [INFO] Not rendering Table ("",[],[]) (Caption Nothing []) [(AlignDefault,ColWidth 0.5),(AlignDefault,ColWidth 0.5)] (TableHead ("",[],[]) []) [TableBody ("",[],[]) (RowHeadColumns 0) [] [Row ("",[],[]) [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "a1"]],Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Table ("",[],[]) (Caption Nothing []) [(AlignDefault,ColWidthDefault),(AlignDefault,ColWidthDefault)] (TableHead ("",[],[]) []) [TableBody ("",[],[]) (RowHeadColumns 0) [] [Row ("",[],[]) [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "1"]],Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "2"]]]]] (TableFoot ("",[],[]) [])]]]] (TableFoot ("",[],[]) []) [width="100%",cols="50%,50%",] |=== a|
test/command/pandoc-citeproc-356.md view
@@ -15,6 +15,6 @@  [@bar] ^D-[WARNING] Citeproc: citation bar not found+2> [WARNING] Citeproc: citation bar not found (**bar?**) ```
test/command/pandoc-citeproc-chicago-author-date.md view
@@ -47,7 +47,7 @@ [^3]: Like a citation without author: [-@item1], and now Doe with a     locator [-@item2 p. 44]. ^D-[WARNING] Citeproc: citation nonexistent not found+2> [WARNING] Citeproc: citation nonexistent not found # Pandoc with citeproc-hs  ([**nonexistent?**](#ref-nonexistent))
test/command/pandoc-citeproc-chicago-fullnote-bibliography.md view
@@ -48,7 +48,7 @@ [^3]: Like a citation without author: [-@item1], and again     [-@item1], and now Doe with a locator [-@item2 p. 44]. ^D-[WARNING] Citeproc: citation nonexistent not found+2> [WARNING] Citeproc: citation nonexistent not found # Pandoc with citeproc-hs  [^1]
test/command/pandoc-citeproc-ieee.md view
@@ -48,7 +48,7 @@ [^3]: Like a citation without author: [-@item1], and now Doe with a     locator [-@item2 p. 44]. ^D-[WARNING] Citeproc: citation nonexistent not found+2> [WARNING] Citeproc: citation nonexistent not found # Pandoc with citeproc-hs  [**nonexistent?**](#ref-nonexistent)
test/command/svg.md view
@@ -2,7 +2,7 @@ % pandoc -f latex -t icml \includegraphics{command/corrupt.svg} ^D-[WARNING] Could not determine image size for command/corrupt.svg: could not determine image type+2> [WARNING] Could not determine image size for command/corrupt.svg: could not determine image type <ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">   <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">     <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 150 -100">
+ test/docx/golden/tables_separated_with_rawblock.docx view
binary file changed (absent → 9852 bytes)
+ test/docx/tables_separated_with_rawblock.native view
@@ -0,0 +1,27 @@+[Table ("", [], []) (Caption Nothing+ [])+ [(AlignDefault,ColWidthDefault)+ ,(AlignDefault,ColWidthDefault)]+ (TableHead ("",[],[]) [])+ [TableBody ("",[],[]) (RowHeadColumns 0)+  []+  [Row ("",[],[])+   [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)+    [Plain [Str "a"]]+   ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)+    [Plain [Str "b"]]]]]+ (TableFoot ("",[],[]) [])+,RawBlock (Format "latex") ""+,Table ("",[],[]) (Caption Nothing+ [])+ [(AlignDefault,ColWidthDefault)+ ,(AlignDefault,ColWidthDefault)]+   (TableHead ("",[],[]) [])+   [TableBody ("",[],[]) (RowHeadColumns 0)+    []+    [Row ("",[],[])+     [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)+      [Plain [Str "c"]]+     ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)+      [Plain [Str "d"]]]]]+ (TableFoot ("",[],[]) [])]
test/lhs-test.html view
@@ -30,6 +30,9 @@         font-size: 0.9em;         padding: 1em;       }+      h1 {+        font-size: 1.8em;+      }     }     @media print {       body {@@ -133,6 +136,12 @@     }     #TOC li {       list-style: none;+    }+    #TOC ul {+      padding-left: 1.3em;+    }+    #TOC > ul {+      padding-left: 0;     }     #TOC a:not(:hover) {       text-decoration: none;
test/lhs-test.html+lhs view
@@ -30,6 +30,9 @@         font-size: 0.9em;         padding: 1em;       }+      h1 {+        font-size: 1.8em;+      }     }     @media print {       body {@@ -133,6 +136,12 @@     }     #TOC li {       list-style: none;+    }+    #TOC ul {+      padding-left: 1.3em;+    }+    #TOC > ul {+      padding-left: 0;     }     #TOC a:not(:hover) {       text-decoration: none;
test/tables/nordics.html4 view
@@ -51,8 +51,8 @@ <tr id="summary" class="even"> <td align="center">Total</td> <td align="left"></td>-<td align="left" id="total-population">27,376,022</td>-<td align="left" id="total-area">1,258,336</td>+<td id="total-population" align="left">27,376,022</td>+<td id="total-area" align="left">1,258,336</td> </tr> </tfoot> 
test/tables/nordics.html5 view
@@ -51,8 +51,8 @@ <tr id="summary" class="even"> <td style="text-align: center;">Total</td> <td style="text-align: left;"></td>-<td style="text-align: left;" id="total-population">27,376,022</td>-<td style="text-align: left;" id="total-area">1,258,336</td>+<td id="total-population" style="text-align: left;">27,376,022</td>+<td id="total-area" style="text-align: left;">1,258,336</td> </tr> </tfoot> 
test/tables/planets.html4 view
@@ -2,7 +2,7 @@ <caption><p>Data about the planets of our solar system.</p></caption> <thead> <tr class="header">-<th align="center" colspan="2"></th>+<th colspan="2" align="center"></th> <th>Name</th> <th align="right">Mass (10^24kg)</th> <th align="right">Diameter (km)</th>@@ -17,7 +17,7 @@ </thead> <tbody> <tr class="odd">-<th align="center" colspan="2" rowspan="4">Terrestrial planets</th>+<th colspan="2" rowspan="4" align="center">Terrestrial planets</th> <th>Mercury</th> <td align="right">0.330</td> <td align="right">4,879</td>@@ -66,8 +66,8 @@ <td>The red planet</td> </tr> <tr class="odd">-<th align="center" rowspan="4">Jovian planets</th>-<th align="center" rowspan="2">Gas giants</th>+<th rowspan="4" align="center">Jovian planets</th>+<th rowspan="2" align="center">Gas giants</th> <th>Jupiter</th> <td align="right">1898</td> <td align="right">142,984</td>@@ -92,7 +92,7 @@ <td></td> </tr> <tr class="odd">-<th align="center" rowspan="2">Ice giants</th>+<th rowspan="2" align="center">Ice giants</th> <th>Uranus</th> <td align="right">86.8</td> <td align="right">51,118</td>@@ -117,7 +117,7 @@ <td></td> </tr> <tr class="odd">-<th align="center" colspan="2">Dwarf planets</th>+<th colspan="2" align="center">Dwarf planets</th> <th>Pluto</th> <td align="right">0.0146</td> <td align="right">2,370</td>
test/tables/planets.html5 view
@@ -2,7 +2,7 @@ <caption><p>Data about the planets of our solar system.</p></caption> <thead> <tr class="header">-<th style="text-align: center;" colspan="2"></th>+<th colspan="2" style="text-align: center;"></th> <th>Name</th> <th style="text-align: right;">Mass (10^24kg)</th> <th style="text-align: right;">Diameter (km)</th>@@ -17,7 +17,7 @@ </thead> <tbody> <tr class="odd">-<th style="text-align: center;" colspan="2" rowspan="4">Terrestrial planets</th>+<th colspan="2" rowspan="4" style="text-align: center;">Terrestrial planets</th> <th>Mercury</th> <td style="text-align: right;">0.330</td> <td style="text-align: right;">4,879</td>@@ -66,8 +66,8 @@ <td>The red planet</td> </tr> <tr class="odd">-<th style="text-align: center;" rowspan="4">Jovian planets</th>-<th style="text-align: center;" rowspan="2">Gas giants</th>+<th rowspan="4" style="text-align: center;">Jovian planets</th>+<th rowspan="2" style="text-align: center;">Gas giants</th> <th>Jupiter</th> <td style="text-align: right;">1898</td> <td style="text-align: right;">142,984</td>@@ -92,7 +92,7 @@ <td></td> </tr> <tr class="odd">-<th style="text-align: center;" rowspan="2">Ice giants</th>+<th rowspan="2" style="text-align: center;">Ice giants</th> <th>Uranus</th> <td style="text-align: right;">86.8</td> <td style="text-align: right;">51,118</td>@@ -117,7 +117,7 @@ <td></td> </tr> <tr class="odd">-<th style="text-align: center;" colspan="2">Dwarf planets</th>+<th colspan="2" style="text-align: center;">Dwarf planets</th> <th>Pluto</th> <td style="text-align: right;">0.0146</td> <td style="text-align: right;">2,370</td>
test/tables/students.html4 view
@@ -12,7 +12,7 @@ </thead> <tbody class="souvereign-states"> <tr class="odd">-<th align="left" colspan="2">Computer Science</th>+<th colspan="2" align="left">Computer Science</th> </tr>  <tr class="odd">@@ -30,7 +30,7 @@ </tbody> <tbody> <tr class="odd">-<th align="left" colspan="2">Russian Literature</th>+<th colspan="2" align="left">Russian Literature</th> </tr>  <tr class="odd">@@ -40,7 +40,7 @@ </tbody> <tbody> <tr class="odd">-<th align="left" colspan="2">Astrophysics</th>+<th colspan="2" align="left">Astrophysics</th> </tr>  <tr class="odd">
test/tables/students.html5 view
@@ -12,7 +12,7 @@ </thead> <tbody class="souvereign-states"> <tr class="odd">-<th style="text-align: left;" colspan="2">Computer Science</th>+<th colspan="2" style="text-align: left;">Computer Science</th> </tr>  <tr class="odd">@@ -30,7 +30,7 @@ </tbody> <tbody> <tr class="odd">-<th style="text-align: left;" colspan="2">Russian Literature</th>+<th colspan="2" style="text-align: left;">Russian Literature</th> </tr>  <tr class="odd">@@ -40,7 +40,7 @@ </tbody> <tbody> <tr class="odd">-<th style="text-align: left;" colspan="2">Astrophysics</th>+<th colspan="2" style="text-align: left;">Astrophysics</th> </tr>  <tr class="odd">
test/writer.html4 view
@@ -33,6 +33,9 @@         font-size: 0.9em;         padding: 1em;       }+      h1 {+        font-size: 1.8em;+      }     }     @media print {       body {@@ -136,6 +139,12 @@     }     #TOC li {       list-style: none;+    }+    #TOC ul {+      padding-left: 1.3em;+    }+    #TOC > ul {+      padding-left: 0;     }     #TOC a:not(:hover) {       text-decoration: none;
test/writer.html5 view
@@ -33,6 +33,9 @@         font-size: 0.9em;         padding: 1em;       }+      h1 {+        font-size: 1.8em;+      }     }     @media print {       body {@@ -136,6 +139,12 @@     }     #TOC li {       list-style: none;+    }+    #TOC ul {+      padding-left: 1.3em;+    }+    #TOC > ul {+      padding-left: 0;     }     #TOC a:not(:hover) {       text-decoration: none;
test/writer.man view
@@ -1,3 +1,17 @@+.\" Define V font for inline verbatim, using C font in formats+.\" that render this, and otherwise B font.+.ie "\f[CB]x\f[]"x" \{\+. ftr V B+. ftr VI BI+. ftr VB B+. ftr VBI BI+.\}+.el \{\+. ftr V CR+. ftr VI CI+. ftr VB CB+. ftr VBI CBI+.\} .TH "Pandoc Test Suite" "" "July 17, 2006" "" "" .hy .PP@@ -487,8 +501,8 @@ .PP So is \f[B]\f[BI]this\f[B]\f[R] word. .PP-This is code: \f[C]>\f[R], \f[C]$\f[R], \f[C]\[rs]\f[R], \f[C]\[rs]$\f[R],-\f[C]<html>\f[R].+This is code: \f[V]>\f[R], \f[V]$\f[R], \f[V]\[rs]\f[R], \f[V]\[rs]$\f[R],+\f[V]<html>\f[R]. .PP [STRIKEOUT:This is \f[I]strikeout\f[R].] .PP@@ -512,7 +526,7 @@ .PP `He said, \[lq]I want to go.\[rq]' Were you alive in the 70\[cq]s? .PP-Here is some quoted `\f[C]code\f[R]' and a \[lq]quoted+Here is some quoted `\f[V]code\f[R]' and a \[lq]quoted link (http://example.com/?foo=1&bar=2)\[rq]. .PP Some dashes: one\[em]two \[em] three\[em]four \[em] five.@@ -545,7 +559,7 @@ .PP These shouldn\[cq]t be math: .IP \[bu] 2-To get the famous equation, write \f[C]$e = mc\[ha]2$\f[R].+To get the famous equation, write \f[V]$e = mc\[ha]2$\f[R]. .IP \[bu] 2 $22,000 is a \f[I]lot\f[R] of money. So is $34,000.@@ -553,7 +567,7 @@ .IP \[bu] 2 Shoes ($20) and socks ($5). .IP \[bu] 2-Escaped \f[C]$\f[R]: $73 \f[I]this should be emphasized\f[R] 23$.+Escaped \f[V]$\f[R]: $73 \f[I]this should be emphasized\f[R] 23$. .PP Here\[cq]s a LaTeX table: .PP@@ -686,7 +700,7 @@ Blockquoted: <http://example.com/> .RE .PP-Auto-links should not occur here: \f[C]<http://example.com/>\f[R]+Auto-links should not occur here: \f[V]<http://example.com/>\f[R] .IP .nf \f[C]@@ -742,7 +756,7 @@ .SS [3] .PP This is \f[I]easier\f[R] to type.-Inline notes may contain links (http://google.com) and \f[C]]\f[R] verbatim+Inline notes may contain links (http://google.com) and \f[V]]\f[R] verbatim characters, as well as [bracketed text]. .SS [4] .PP