diff --git a/AUTHORS.md b/AUTHORS.md --- a/AUTHORS.md +++ b/AUTHORS.md @@ -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 diff --git a/MANUAL.txt b/MANUAL.txt --- a/MANUAL.txt +++ b/MANUAL.txt @@ -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 `
` or `
`) 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 diff --git a/changelog.md b/changelog.md --- a/changelog.md +++ b/changelog.md @@ -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. + + + * 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). diff --git a/data/templates/default.man b/data/templates/default.man --- a/data/templates/default.man +++ b/data/templates/default.man @@ -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$ diff --git a/data/templates/styles.html b/data/templates/styles.html --- a/data/templates/styles.html +++ b/data/templates/styles.html @@ -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; diff --git a/man/manfilter.lua b/man/manfilter.lua --- a/man/manfilter.lua +++ b/man/manfilter.lua @@ -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 diff --git a/man/pandoc.1 b/man/pandoc.1 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -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]\f[R] and \f[C]\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]\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]\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]\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]
\f[R] tags (or \f[C]
\f[R] tags for -\f[C]html4\f[R]), and attach identifiers to the enclosing -\f[C]
\f[R] (or \f[C]
\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] - Creative Commons - es-AR -\f[R] -.fi -.PP -By default, pandoc will include the following metadata elements: -\f[C]\f[R] (from the document title), \f[C]\f[R] -(from the document authors), \f[C]\f[R] (from the document -date, which should be in ISO 8601 format), \f[C]\f[R] (from -the \f[C]lang\f[R] variable, or, if is not set, the locale), and -\f[C]\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]\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]\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]\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: | - ---- -\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]
\f[R] (or \f[C]
\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]\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] -
-  
-  ...
-  
-
-\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 - - - - { 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] -

This is the abstract.

-

It consists of two paragraphs.

-\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] -*hello* -\f[R] -.fi -.PP -instead of -.IP -.nf -\f[C] -hello -\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]
\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] -Underline -\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] -Small caps -\f[R] -.fi -.PP -For compatibility with other Markdown flavors, CSS is also supported: -.IP -.nf -\f[C] -Small caps -\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]\f[R] tags. -.TP -Textile -It will be rendered inside \f[C]\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] - - - - - -
*one*[a link](https://google.com)
-\f[R] -.fi -.PP -into -.IP -.nf -\f[C] - - - - - -
onea link
-\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] -HTML -\[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] - -HTML -\[dq]\[dq]\[dq]) -\[ga]\[ga]\[ga] - -::: {.output .execute_result execution_count=2} -\[ga]\[ga]\[ga]{=html} - -HTML -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 . +.\" 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]\f[R] and \f[V]\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]\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]\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]\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]
\f[R] tags (or \f[V]
\f[R] tags for +\f[V]html4\f[R]), and attach identifiers to the enclosing +\f[V]
\f[R] (or \f[V]
\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] + Creative Commons + es-AR +\f[R] +.fi +.PP +By default, pandoc will include the following metadata elements: +\f[V]\f[R] (from the document title), \f[V]\f[R] +(from the document authors), \f[V]\f[R] (from the document +date, which should be in ISO 8601 format), \f[V]\f[R] (from +the \f[V]lang\f[R] variable, or, if is not set, the locale), and +\f[V]\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]\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]\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]\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: | + +--- +\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]
\f[R] (or \f[V]
\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]\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] +
+  
+  ...
+  
+
+\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 + + + + { 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] +

This is the abstract.

+

It consists of two paragraphs.

+\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] +*hello* +\f[R] +.fi +.PP +instead of +.IP +.nf +\f[C] +hello +\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]
\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] +Underline +\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] +Small caps +\f[R] +.fi +.PP +For compatibility with other Markdown flavors, CSS is also supported: +.IP +.nf +\f[C] +Small caps +\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]\f[R] tags. +.TP +Textile +It will be rendered inside \f[V]\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] + + + + + +
*one*[a link](https://google.com)
+\f[R] +.fi +.PP +into +.IP +.nf +\f[C] + + + + + +
onea link
+\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] +HTML +\[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] + +HTML +\[dq]\[dq]\[dq]) +\[ga]\[ga]\[ga] + +::: {.output .execute_result execution_count=2} +\[ga]\[ga]\[ga]{=html} + +HTML +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 or +. Further +documentation is available at . diff --git a/man/pandoc.1.after b/man/pandoc.1.after --- a/man/pandoc.1.after +++ b/man/pandoc.1.after @@ -1,3 +1,5 @@ .PP -The Pandoc source code and all documentation may be downloaded -from . +The Pandoc source code may be downloaded +from or +. Further +documentation is available at . diff --git a/pandoc.cabal b/pandoc.cabal --- a/pandoc.cabal +++ b/pandoc.cabal @@ -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, diff --git a/src/Text/Pandoc/App.hs b/src/Text/Pandoc/App.hs --- a/src/Text/Pandoc/App.hs +++ b/src/Text/Pandoc/App.hs @@ -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 diff --git a/src/Text/Pandoc/App/CommandLineOptions.hs b/src/Text/Pandoc/App/CommandLineOptions.hs --- a/src/Text/Pandoc/App/CommandLineOptions.hs +++ b/src/Text/Pandoc/App/CommandLineOptions.hs @@ -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 ++ diff --git a/src/Text/Pandoc/App/Opt.hs b/src/Text/Pandoc/App/Opt.hs --- a/src/Text/Pandoc/App/Opt.hs +++ b/src/Text/Pandoc/App/Opt.hs @@ -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. diff --git a/src/Text/Pandoc/CSS.hs b/src/Text/Pandoc/CSS.hs --- a/src/Text/Pandoc/CSS.hs +++ b/src/Text/Pandoc/CSS.hs @@ -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. diff --git a/src/Text/Pandoc/Class/PandocMonad.hs b/src/Text/Pandoc/Class/PandocMonad.hs --- a/src/Text/Pandoc/Class/PandocMonad.hs +++ b/src/Text/Pandoc/Class/PandocMonad.hs @@ -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 diff --git a/src/Text/Pandoc/Error.hs b/src/Text/Pandoc/Error.hs --- a/src/Text/Pandoc/Error.hs +++ b/src/Text/Pandoc/Error.hs @@ -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 diff --git a/src/Text/Pandoc/Lua/ErrorConversion.hs b/src/Text/Pandoc/Lua/ErrorConversion.hs --- a/src/Text/Pandoc/Lua/ErrorConversion.hs +++ b/src/Text/Pandoc/Lua/ErrorConversion.hs @@ -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 diff --git a/src/Text/Pandoc/Lua/Filter.hs b/src/Text/Pandoc/Lua/Filter.hs --- a/src/Text/Pandoc/Lua/Filter.hs +++ b/src/Text/Pandoc/Lua/Filter.hs @@ -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 diff --git a/src/Text/Pandoc/Lua/Marshal/ReaderOptions.hs b/src/Text/Pandoc/Lua/Marshal/ReaderOptions.hs --- a/src/Text/Pandoc/Lua/Marshal/ReaderOptions.hs +++ b/src/Text/Pandoc/Lua/Marshal/ReaderOptions.hs @@ -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 (..)) -- diff --git a/src/Text/Pandoc/Lua/Marshal/Reference.hs b/src/Text/Pandoc/Lua/Marshal/Reference.hs --- a/src/Text/Pandoc/Lua/Marshal/Reference.hs +++ b/src/Text/Pandoc/Lua/Marshal/Reference.hs @@ -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) diff --git a/src/Text/Pandoc/Lua/Marshal/WriterOptions.hs b/src/Text/Pandoc/Lua/Marshal/WriterOptions.hs --- a/src/Text/Pandoc/Lua/Marshal/WriterOptions.hs +++ b/src/Text/Pandoc/Lua/Marshal/WriterOptions.hs @@ -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 (..)) -- diff --git a/src/Text/Pandoc/Lua/Module/MediaBag.hs b/src/Text/Pandoc/Lua/Module/MediaBag.hs --- a/src/Text/Pandoc/Lua/Module/MediaBag.hs +++ b/src/Text/Pandoc/Lua/Module/MediaBag.hs @@ -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." diff --git a/src/Text/Pandoc/Lua/Module/Pandoc.hs b/src/Text/Pandoc/Lua/Module/Pandoc.hs --- a/src/Text/Pandoc/Lua/Module/Pandoc.hs +++ b/src/Text/Pandoc/Lua/Module/Pandoc.hs @@ -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 $ diff --git a/src/Text/Pandoc/Lua/Module/Template.hs b/src/Text/Pandoc/Lua/Module/Template.hs --- a/src/Text/Pandoc/Lua/Module/Template.hs +++ b/src/Text/Pandoc/Lua/Module/Template.hs @@ -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" diff --git a/src/Text/Pandoc/Lua/Module/Utils.hs b/src/Text/Pandoc/Lua/Module/Utils.hs --- a/src/Text/Pandoc/Lua/Module/Utils.hs +++ b/src/Text/Pandoc/Lua/Module/Utils.hs @@ -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" diff --git a/src/Text/Pandoc/Lua/Orphans.hs b/src/Text/Pandoc/Lua/Orphans.hs --- a/src/Text/Pandoc/Lua/Orphans.hs +++ b/src/Text/Pandoc/Lua/Orphans.hs @@ -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 diff --git a/src/Text/Pandoc/Lua/PandocLua.hs b/src/Text/Pandoc/Lua/PandocLua.hs --- a/src/Text/Pandoc/Lua/PandocLua.hs +++ b/src/Text/Pandoc/Lua/PandocLua.hs @@ -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] diff --git a/src/Text/Pandoc/Lua/Util.hs b/src/Text/Pandoc/Lua/Util.hs deleted file mode 100644 --- a/src/Text/Pandoc/Lua/Util.hs +++ /dev/null @@ -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 - 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 diff --git a/src/Text/Pandoc/PDF.hs b/src/Text/Pandoc/PDF.hs --- a/src/Text/Pandoc/PDF.hs +++ b/src/Text/Pandoc/PDF.hs @@ -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) $ diff --git a/src/Text/Pandoc/Readers/CommonMark.hs b/src/Text/Pandoc/Readers/CommonMark.hs --- a/src/Text/Pandoc/Readers/CommonMark.hs +++ b/src/Text/Pandoc/Readers/CommonMark.hs @@ -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) diff --git a/src/Text/Pandoc/Readers/Custom.hs b/src/Text/Pandoc/Readers/Custom.hs --- a/src/Text/Pandoc/Readers/Custom.hs +++ b/src/Text/Pandoc/Readers/Custom.hs @@ -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 diff --git a/src/Text/Pandoc/Readers/DocBook.hs b/src/Text/Pandoc/Readers/DocBook.hs --- a/src/Text/Pandoc/Readers/DocBook.hs +++ b/src/Text/Pandoc/Readers/DocBook.hs @@ -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 diff --git a/src/Text/Pandoc/Readers/Docx/Fields.hs b/src/Text/Pandoc/Readers/Docx/Fields.hs --- a/src/Text/Pandoc/Readers/Docx/Fields.hs +++ b/src/Text/Pandoc/Readers/Docx/Fields.hs @@ -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 "\\\"" $> "\\\"" diff --git a/src/Text/Pandoc/Readers/Docx/Parse.hs b/src/Text/Pandoc/Readers/Docx/Parse.hs --- a/src/Text/Pandoc/Readers/Docx/Parse.hs +++ b/src/Text/Pandoc/Readers/Docx/Parse.hs @@ -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 diff --git a/src/Text/Pandoc/Readers/LaTeX.hs b/src/Text/Pandoc/Readers/LaTeX.hs --- a/src/Text/Pandoc/Readers/LaTeX.hs +++ b/src/Text/Pandoc/Readers/LaTeX.hs @@ -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 diff --git a/src/Text/Pandoc/Readers/LaTeX/Inline.hs b/src/Text/Pandoc/Readers/LaTeX/Inline.hs --- a/src/Text/Pandoc/Readers/LaTeX/Inline.hs +++ b/src/Text/Pandoc/Readers/LaTeX/Inline.hs @@ -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 diff --git a/src/Text/Pandoc/Readers/LaTeX/Macro.hs b/src/Text/Pandoc/Readers/LaTeX/Macro.hs --- a/src/Text/Pandoc/Readers/LaTeX/Macro.hs +++ b/src/Text/Pandoc/Readers/LaTeX/Macro.hs @@ -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 "}" ]) ] diff --git a/src/Text/Pandoc/Readers/LaTeX/Parsing.hs b/src/Text/Pandoc/Readers/LaTeX/Parsing.hs --- a/src/Text/Pandoc/Readers/LaTeX/Parsing.hs +++ b/src/Text/Pandoc/Readers/LaTeX/Parsing.hs @@ -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 () diff --git a/src/Text/Pandoc/Readers/Org/Inlines.hs b/src/Text/Pandoc/Readers/Org/Inlines.hs --- a/src/Text/Pandoc/Readers/Org/Inlines.hs +++ b/src/Text/Pandoc/Readers/Org/Inlines.hs @@ -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 diff --git a/src/Text/Pandoc/Shared.hs b/src/Text/Pandoc/Shared.hs --- a/src/Text/Pandoc/Shared.hs +++ b/src/Text/Pandoc/Shared.hs @@ -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 diff --git a/src/Text/Pandoc/Writers/AsciiDoc.hs b/src/Text/Pandoc/Writers/AsciiDoc.hs --- a/src/Text/Pandoc/Writers/AsciiDoc.hs +++ b/src/Text/Pandoc/Writers/AsciiDoc.hs @@ -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) diff --git a/src/Text/Pandoc/Writers/Blaze.hs b/src/Text/Pandoc/Writers/Blaze.hs --- a/src/Text/Pandoc/Writers/Blaze.hs +++ b/src/Text/Pandoc/Writers/Blaze.hs @@ -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 + " go False mempty content + t | t == " 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 == " ChoiceString -- ^ String to render diff --git a/src/Text/Pandoc/Writers/Custom.hs b/src/Text/Pandoc/Writers/Custom.hs --- a/src/Text/Pandoc/Writers/Custom.hs +++ b/src/Text/Pandoc/Writers/Custom.hs @@ -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) diff --git a/src/Text/Pandoc/Writers/Docx.hs b/src/Text/Pandoc/Writers/Docx.hs --- a/src/Text/Pandoc/Writers/Docx.hs +++ b/src/Text/Pandoc/Writers/Docx.hs @@ -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. diff --git a/src/Text/Pandoc/Writers/HTML.hs b/src/Text/Pandoc/Writers/HTML.hs --- a/src/Text/Pandoc/Writers/HTML.hs +++ b/src/Text/Pandoc/Writers/HTML.hs @@ -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] diff --git a/src/Text/Pandoc/Writers/LaTeX.hs b/src/Text/Pandoc/Writers/LaTeX.hs --- a/src/Text/Pandoc/Writers/LaTeX.hs +++ b/src/Text/Pandoc/Writers/LaTeX.hs @@ -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)) diff --git a/src/Text/Pandoc/Writers/Man.hs b/src/Text/Pandoc/Writers/Man.hs --- a/src/Text/Pandoc/Writers/Man.hs +++ b/src/Text/Pandoc/Writers/Man.hs @@ -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 diff --git a/src/Text/Pandoc/Writers/Markdown.hs b/src/Text/Pandoc/Writers/Markdown.hs --- a/src/Text/Pandoc/Writers/Markdown.hs +++ b/src/Text/Pandoc/Writers/Markdown.hs @@ -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 diff --git a/src/Text/Pandoc/Writers/Muse.hs b/src/Text/Pandoc/Writers/Muse.hs --- a/src/Text/Pandoc/Writers/Muse.hs +++ b/src/Text/Pandoc/Writers/Muse.hs @@ -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 "**" "**" 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 diff --git a/src/Text/Pandoc/Writers/Powerpoint/Output.hs b/src/Text/Pandoc/Writers/Powerpoint/Output.hs --- a/src/Text/Pandoc/Writers/Powerpoint/Output.hs +++ b/src/Text/Pandoc/Writers/Powerpoint/Output.hs @@ -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) diff --git a/src/Text/Pandoc/Writers/Roff.hs b/src/Text/Pandoc/Writers/Roff.hs --- a/src/Text/Pandoc/Writers/Roff.hs +++ b/src/Text/Pandoc/Writers/Roff.hs @@ -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] diff --git a/src/Text/Pandoc/Writers/TEI.hs b/src/Text/Pandoc/Writers/TEI.hs --- a/src/Text/Pandoc/Writers/TEI.hs +++ b/src/Text/Pandoc/Writers/TEI.hs @@ -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 diff --git a/src/Text/Pandoc/Writers/ZimWiki.hs b/src/Text/Pandoc/Writers/ZimWiki.hs --- a/src/Text/Pandoc/Writers/ZimWiki.hs +++ b/src/Text/Pandoc/Writers/ZimWiki.hs @@ -324,7 +324,7 @@ DisplayMath -> "$$" InlineMath -> "$" --- | f == Format "html" = return $ "" <> str <> "" +-- f == Format "html" = return $ "" <> str <> "" inlineToZimWiki opts il@(RawInline f str) | f == Format "zimwiki" = return str | f == Format "html" = indentFromHTML opts str diff --git a/stack.yaml b/stack.yaml --- a/stack.yaml +++ b/stack.yaml @@ -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] - - diff --git a/test/Tests/Command.hs b/test/Tests/Command.hs --- a/test/Tests/Command.hs +++ b/test/Tests/Command.hs @@ -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 diff --git a/test/Tests/Writers/AsciiDoc.hs b/test/Tests/Writers/AsciiDoc.hs --- a/test/Tests/Writers/AsciiDoc.hs +++ b/test/Tests/Writers/AsciiDoc.hs @@ -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" + ] + ] ] + diff --git a/test/Tests/Writers/Docx.hs b/test/Tests/Writers/Docx.hs --- a/test/Tests/Writers/Docx.hs +++ b/test/Tests/Writers/Docx.hs @@ -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" diff --git a/test/command/1718.md b/test/command/1718.md --- a/test/command/1718.md +++ b/test/command/1718.md @@ -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 diff --git a/test/command/3534.md b/test/command/3534.md --- a/test/command/3534.md +++ b/test/command/3534.md @@ -3,8 +3,7 @@ I want to explain the interface of \lstinline[language=Java]{public class MyClass}. ^D

I want to explain the interface of public class MyClass.

+class="sourceCode java">public class MyClass.

``` @@ -12,8 +11,8 @@ % pandoc -f latex -t html I want to explain the interface of \lstinline{public class MyClass}. ^D -

I want to explain the interface of public class -MyClass.

+

I want to explain the interface of +public class MyClass.

``` @@ -47,8 +46,7 @@ I want to explain the interface of \mintinline{java}{public class MyClass}. ^D

I want to explain the interface of public class MyClass.

+class="sourceCode java">public class MyClass.

``` @@ -57,8 +55,7 @@ I want to explain the interface of \mintinline{java}|public class MyClass|. ^D

I want to explain the interface of public class MyClass.

+class="sourceCode java">public class MyClass.

``` diff --git a/test/command/3568.md b/test/command/3568.md --- a/test/command/3568.md +++ b/test/command/3568.md @@ -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. ``` diff --git a/test/command/3734.md b/test/command/3734.md --- a/test/command/3734.md +++ b/test/command/3734.md @@ -5,7 +5,7 @@ | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | -|--------------|-------|--------------------------------------------------------------------------| +|------------|-------|------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ``` @@ -16,7 +16,7 @@ | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | -|--------------|-------|--------------------------------------------------------------------------| +|------------|-------|------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ``` diff --git a/test/command/3752.md b/test/command/3752.md --- a/test/command/3752.md +++ b/test/command/3752.md @@ -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] diff --git a/test/command/512.md b/test/command/512.md --- a/test/command/512.md +++ b/test/command/512.md @@ -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

click here

``` diff --git a/test/command/5620.md b/test/command/5620.md --- a/test/command/5620.md +++ b/test/command/5620.md @@ -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) ``` diff --git a/test/command/5876.md b/test/command/5876.md new file mode 100644 --- /dev/null +++ b/test/command/5876.md @@ -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 +``` diff --git a/test/command/5876.yaml b/test/command/5876.yaml new file mode 100644 --- /dev/null +++ b/test/command/5876.yaml @@ -0,0 +1,3 @@ +--- +desc: Found in working directory. +--- diff --git a/test/command/5876/metadata/5876.yaml b/test/command/5876/metadata/5876.yaml new file mode 100644 --- /dev/null +++ b/test/command/5876/metadata/5876.yaml @@ -0,0 +1,3 @@ +--- +desc: Found in metadata directory. +--- diff --git a/test/command/5876/metadata/command/5876.yaml b/test/command/5876/metadata/command/5876.yaml new file mode 100644 --- /dev/null +++ b/test/command/5876/metadata/command/5876.yaml @@ -0,0 +1,3 @@ +--- +desc: Should not be loaded. +--- diff --git a/test/command/6837.md b/test/command/6837.md --- a/test/command/6837.md +++ b/test/command/6837.md @@ -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 ``` diff --git a/test/command/6873.md b/test/command/6873.md --- a/test/command/6873.md +++ b/test/command/6873.md @@ -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 diff --git a/test/command/7099.md b/test/command/7099.md --- a/test/command/7099.md +++ b/test/command/7099.md @@ -2,7 +2,7 @@ % pandoc -f html -t native --verbose ^D -[INFO] Skipped '' at input line 1 column 16 +2> [INFO] Skipped '' at input line 1 column 16 [] ``` @@ -10,9 +10,9 @@ % pandoc -f html -t native --verbose ^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 '' 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 '' at input line 1 column 29 [] ``` diff --git a/test/command/7847.md b/test/command/7847.md new file mode 100644 --- /dev/null +++ b/test/command/7847.md @@ -0,0 +1,85 @@ +``` +% pandoc -f html -t markdown_strict+pipe_tables + +++++ + + + + + + + + + + + + + + +
aaabbbccc
Consequat nisi sit amet nibh. Nunc mi tortor, tristique +sit amet, rhoncus porta, malesuada elementum, nisi.ccc
+^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 + + + + + + + + + + + +
aaabbbccc
Consequat nisi sit amet nibh. Nunc mi tortor, tristique +sit amet, rhoncus porta, malesuada elementum, nisi.ccc
+^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 + +++++ + + + + + + + + + + + + + + +
aaabbbccc
Consequat nisi sit amet nibh. Nunc mi tortor, tristique +sit amet, rhoncus porta, malesuada elementum, nisi.bbbccc
+^D +| aaa | bbb | ccc | +|-------------------------------------------------------------------------------------------------------------|-----|-----| +| Consequat nisi sit amet nibh. Nunc mi tortor, tristique sit amet, rhoncus porta, malesuada elementum, nisi. | bbb | ccc | + +``` + + diff --git a/test/command/7857.md b/test/command/7857.md new file mode 100644 --- /dev/null +++ b/test/command/7857.md @@ -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} +``` diff --git a/test/command/7858.md b/test/command/7858.md new file mode 100644 --- /dev/null +++ b/test/command/7858.md @@ -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 +

neuth asontue stheuosnt aeosunth asnoetuh asneotuh snatehou snatoehu sntahe ousntahoe unstaheou sntaheou aoeu sthoeu sntaoeusnth ansoetuhs atoeuh saonteu

+``` diff --git a/test/command/7861.md b/test/command/7861.md new file mode 100644 --- /dev/null +++ b/test/command/7861.md @@ -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 +``` diff --git a/test/command/7861.yaml b/test/command/7861.yaml new file mode 100644 --- /dev/null +++ b/test/command/7861.yaml diff --git a/test/command/7861/metadata/placeholder b/test/command/7861/metadata/placeholder new file mode 100644 --- /dev/null +++ b/test/command/7861/metadata/placeholder diff --git a/test/command/7863.md b/test/command/7863.md new file mode 100644 --- /dev/null +++ b/test/command/7863.md @@ -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" ] + ] + ] +] +``` diff --git a/test/command/7871.md b/test/command/7871.md new file mode 100644 --- /dev/null +++ b/test/command/7871.md @@ -0,0 +1,14 @@ +``` +% pandoc -f html -t html + + +
a
+^D + + + + + + +
a
+``` diff --git a/test/command/defaults-inheritance-2.md b/test/command/defaults-inheritance-2.md --- a/test/command/defaults-inheritance-2.md +++ b/test/command/defaults-inheritance-2.md @@ -2,4 +2,5 @@ % pandoc -d command/defaults6 2>&1 ^D Error: Circular defaults file reference in 'command/defaults7.yaml' +=> 63 ``` diff --git a/test/command/duplicate_attributes.md b/test/command/duplicate_attributes.md --- a/test/command/duplicate_attributes.md +++ b/test/command/duplicate_attributes.md @@ -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".

span

``` diff --git a/test/command/jats.csl b/test/command/jats.csl deleted file mode 100644 --- a/test/command/jats.csl +++ /dev/null @@ -1,208 +0,0 @@ - - - diff --git a/test/command/nested-table-to-asciidoc-6942.md b/test/command/nested-table-to-asciidoc-6942.md --- a/test/command/nested-table-to-asciidoc-6942.md +++ b/test/command/nested-table-to-asciidoc-6942.md @@ -67,7 +67,7 @@ ^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| diff --git a/test/command/pandoc-citeproc-356.md b/test/command/pandoc-citeproc-356.md --- a/test/command/pandoc-citeproc-356.md +++ b/test/command/pandoc-citeproc-356.md @@ -15,6 +15,6 @@ [@bar] ^D -[WARNING] Citeproc: citation bar not found +2> [WARNING] Citeproc: citation bar not found (**bar?**) ``` diff --git a/test/command/pandoc-citeproc-chicago-author-date.md b/test/command/pandoc-citeproc-chicago-author-date.md --- a/test/command/pandoc-citeproc-chicago-author-date.md +++ b/test/command/pandoc-citeproc-chicago-author-date.md @@ -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)) diff --git a/test/command/pandoc-citeproc-chicago-fullnote-bibliography.md b/test/command/pandoc-citeproc-chicago-fullnote-bibliography.md --- a/test/command/pandoc-citeproc-chicago-fullnote-bibliography.md +++ b/test/command/pandoc-citeproc-chicago-fullnote-bibliography.md @@ -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] diff --git a/test/command/pandoc-citeproc-ieee.md b/test/command/pandoc-citeproc-ieee.md --- a/test/command/pandoc-citeproc-ieee.md +++ b/test/command/pandoc-citeproc-ieee.md @@ -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) diff --git a/test/command/svg.md b/test/command/svg.md --- a/test/command/svg.md +++ b/test/command/svg.md @@ -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 diff --git a/test/docx/golden/tables_separated_with_rawblock.docx b/test/docx/golden/tables_separated_with_rawblock.docx new file mode 100644 Binary files /dev/null and b/test/docx/golden/tables_separated_with_rawblock.docx differ diff --git a/test/docx/tables_separated_with_rawblock.native b/test/docx/tables_separated_with_rawblock.native new file mode 100644 --- /dev/null +++ b/test/docx/tables_separated_with_rawblock.native @@ -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 ("",[],[]) [])] diff --git a/test/lhs-test.html b/test/lhs-test.html --- a/test/lhs-test.html +++ b/test/lhs-test.html @@ -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; diff --git a/test/lhs-test.html+lhs b/test/lhs-test.html+lhs --- a/test/lhs-test.html+lhs +++ b/test/lhs-test.html+lhs @@ -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; diff --git a/test/tables/nordics.html4 b/test/tables/nordics.html4 --- a/test/tables/nordics.html4 +++ b/test/tables/nordics.html4 @@ -51,8 +51,8 @@ Total -27,376,022 -1,258,336 +27,376,022 +1,258,336 diff --git a/test/tables/nordics.html5 b/test/tables/nordics.html5 --- a/test/tables/nordics.html5 +++ b/test/tables/nordics.html5 @@ -51,8 +51,8 @@ Total -27,376,022 -1,258,336 +27,376,022 +1,258,336 diff --git a/test/tables/planets.html4 b/test/tables/planets.html4 --- a/test/tables/planets.html4 +++ b/test/tables/planets.html4 @@ -2,7 +2,7 @@

Data about the planets of our solar system.

- + Name Mass (10^24kg) Diameter (km) @@ -17,7 +17,7 @@ -Terrestrial planets +Terrestrial planets Mercury 0.330 4,879 @@ -66,8 +66,8 @@ The red planet -Jovian planets -Gas giants +Jovian planets +Gas giants Jupiter 1898 142,984 @@ -92,7 +92,7 @@ -Ice giants +Ice giants Uranus 86.8 51,118 @@ -117,7 +117,7 @@ -Dwarf planets +Dwarf planets Pluto 0.0146 2,370 diff --git a/test/tables/planets.html5 b/test/tables/planets.html5 --- a/test/tables/planets.html5 +++ b/test/tables/planets.html5 @@ -2,7 +2,7 @@

Data about the planets of our solar system.

- + Name Mass (10^24kg) Diameter (km) @@ -17,7 +17,7 @@ -Terrestrial planets +Terrestrial planets Mercury 0.330 4,879 @@ -66,8 +66,8 @@ The red planet -Jovian planets -Gas giants +Jovian planets +Gas giants Jupiter 1898 142,984 @@ -92,7 +92,7 @@ -Ice giants +Ice giants Uranus 86.8 51,118 @@ -117,7 +117,7 @@ -Dwarf planets +Dwarf planets Pluto 0.0146 2,370 diff --git a/test/tables/students.html4 b/test/tables/students.html4 --- a/test/tables/students.html4 +++ b/test/tables/students.html4 @@ -12,7 +12,7 @@ -Computer Science +Computer Science @@ -30,7 +30,7 @@ -Russian Literature +Russian Literature @@ -40,7 +40,7 @@ -Astrophysics +Astrophysics diff --git a/test/tables/students.html5 b/test/tables/students.html5 --- a/test/tables/students.html5 +++ b/test/tables/students.html5 @@ -12,7 +12,7 @@ -Computer Science +Computer Science @@ -30,7 +30,7 @@ -Russian Literature +Russian Literature @@ -40,7 +40,7 @@ -Astrophysics +Astrophysics diff --git a/test/writer.html4 b/test/writer.html4 --- a/test/writer.html4 +++ b/test/writer.html4 @@ -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; diff --git a/test/writer.html5 b/test/writer.html5 --- a/test/writer.html5 +++ b/test/writer.html5 @@ -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; diff --git a/test/writer.man b/test/writer.man --- a/test/writer.man +++ b/test/writer.man @@ -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]\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]\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: .RE .PP -Auto-links should not occur here: \f[C]\f[R] +Auto-links should not occur here: \f[V]\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