diff --git a/AUTHORS.md b/AUTHORS.md --- a/AUTHORS.md +++ b/AUTHORS.md @@ -44,6 +44,7 @@ - Ben Steinberg - Beni Cherniavsky-Paskin - Benjamin Bray +- Benjamin Esham - Benjamin Wuethrich - Benoit Schweblin - Benson Muite 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: August 31, 2023 +date: September 08, 2023 --- # Synopsis diff --git a/changelog.md b/changelog.md --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,54 @@ # Revision history for pandoc +## pandoc 3.1.8 (2023-09-08) + + * JATS reader: + + + Ignore `` element (#9057, Julia Diaz). + + Fix conversion of date to ISO 8601 format (#8865). + + * LaTeX template: + + + Add code allow `\cite` to break across lines (#9050). + + Fix regression with CSL `display="block"` (#7363). + This restores the line break before the block. + + Rewrite `CSLReferences` environment to avoid depending on + `enumitem`, which plays badly with beamer. Instead we use + a regular list environment. Thanks to @jpcirrus for the + concept (#9053). + + Restore the pre-3.1.7 format of the `CSLReferences` + environment, which again has two parameters. The first + determines whether a hanging indent is used (1 = yes, 0 = no), + and the second is the entry line spacing (0 = none). + + Add a strut to avoid inconsistencies in spacing (#9058). + - Remove a break at the end of `CSLRightInline` to avoid + inconsistencies in spacing. It shouldn't be necessary + because the paragraph should extend to the right margin (#9058). + + * LaTeX writer: + + + Fix regression with figure labels (#9045). In 3.1.7, pandoc + added two labels to LaTeX figure environments, one with a + phantomsection. + + Fix default citeproc entry-spacing. According to the CSL manual, + the default entry spacing is 1. We were treating it as 0 (#9058). + + * HTML writer: + + + Use the ID prefix in the ID for the footnotes section (#9044, + Benjamin Esham). + + Fix CSL entry-spacing default (#9058). + + * Text.Pandoc.Citeproc: always include an `entry-spacing` attribute + in the Div if the bibliography element contains an entry-spacing + attribute (previously we omitted it when it was 0) (#9058). + + * Clean up pandoc's own man pages by regenerating with pandoc 3.1.7. + + * pandoc-lua-engine: bump lower bound for pandoc (#9046). + + * Depend on texmath 0.12.8.2, fixing binom in typst writer (#9063). + ## pandoc 3.1.7 (2023-08-31) * Org reader: diff --git a/data/default.csl b/data/default.csl --- a/data/default.csl +++ b/data/default.csl @@ -217,7 +217,7 @@ - + diff --git a/data/templates/default.latex b/data/templates/default.latex --- a/data/templates/default.latex +++ b/data/templates/default.latex @@ -339,8 +339,10 @@ \NewDocumentCommand\citeproctext{}{} \NewDocumentCommand\citeproc{mm}{% \begingroup\def\citeproctext{#2}\cite{#1}\endgroup} -% avoid brackets around text for \cite: \makeatletter + % allow citations to break across lines + \let\@cite@ofmt\@firstofone + % avoid brackets around text for \cite: \def\@biblabel#1{} \def\@cite#1#2{{#1\if@tempswa , #2\fi}} \makeatother @@ -348,19 +350,23 @@ \setlength{\cslhangindent}{1.5em} \newlength{\csllabelwidth} \setlength{\csllabelwidth}{3em} -\newlength{\cslentryspacing} -\setlength{\cslentryspacing}{0em} -\usepackage{enumitem} -\newlist{CSLReferences}{itemize}{1} -\setlist[CSLReferences]{label={}, - leftmargin=\cslhangindent, - itemindent=-1\cslhangindent, - parsep=\parskip, - itemsep=\cslentryspacing} +\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing + {\begin{list}{}{% + \setlength{\itemindent}{0pt} + \setlength{\leftmargin}{0pt} + \setlength{\parsep}{0pt} + % turn on hanging indent if param 1 is 1 + \ifodd #1 + \setlength{\leftmargin}{\cslhangindent} + \setlength{\itemindent}{-1\cslhangindent} + \fi + % set entry spacing + \setlength{\itemsep}{#2\baselineskip}}} + {\end{list}} \usepackage{calc} -\newcommand{\CSLBlock}[1]{#1\hfill\break} -\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{#1}} -\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{#1}\break} +\newcommand{\CSLBlock}[1]{\hfill\break#1\hfill\break} +\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}} +\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}} \newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1} $endif$ $if(lang)$ diff --git a/man/pandoc.1 b/man/pandoc.1 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,8348 +1,7628 @@ -.\" Automatically generated by Pandoc 3.1.6.2 -.\" -.\" 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" "" "August 31, 2023" "pandoc 3.1.7" "" -.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]soul\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]tsv\f[R] (TSV 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]endnotexml\f[R] (EndNote XML bibliography) -.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]ris\f[R] (RIS bibliography) -.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]typst\f[R] (typst) -.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] (modern AsciiDoc as interpreted by AsciiDoctor) -.IP \[bu] 2 -\f[V]asciidoc_legacy\f[R] (AsciiDoc as interpreted by -\f[V]asciidoc-py\f[R]). -.IP \[bu] 2 -\f[V]asciidoctor\f[R] (deprecated synonym for \f[V]asciidoc\f[R]) -.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]chunkedhtml\f[R] (zip archive of multiple linked HTML files) -.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]typst\f[R] (typst) -.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. -If the output format is \f[V]chunkedhtml\f[R] and \f[I]FILE\f[R] has no -extension, then instead of producing a \f[V].zip\f[R] file pandoc will -create a directory \f[I]FILE\f[R] and unpack the zip archive there -(unless \f[I]FILE\f[R] already exists, in which case an error will be -raised). -.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]%APPDATA%\[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. -(Note that the user data directory is not created by pandoc, so you will -need to create it yourself if you want to make use of it.) -.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[=true|false]\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]--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[=true|false]\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]. -.RS -.PP -If two or more files are processed using \f[V]--file-scope\f[R], -prefixes based on the filenames will be added to identifiers in order to -disambiguate them, and internal links will be adjusted accordingly. -For example, a header with identifier \f[V]foo\f[R] in -\f[V]subdir/file1.txt\f[R] will have its identifier changed to -\f[V]subdir__file1.txt__foo\f[R]. -.PP -In addition, a Div with an identifier based on the filename will be -added around the file\[cq]s content, so that internal links to the -filename will point to this Div\[cq]s identifier. -.RE -.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 metadata file will always be parsed as Markdown. -(If the input format is Markdown or a Markdown variant, then the same -variant will be used to parse the metadata file; if it is a non-Markdown -format, pandoc\[cq]s default Markdown extensions will be used.) -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[=true|false]\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[=true|false]\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[=true|false]\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. -.RS -.PP -Note: some readers and writers (e.g., \f[V]docx\f[R]) need access to -data files. -If these are stored on the file system, then pandoc will not be able to -find them when run in \f[V]--sandbox\f[R] mode and will raise an error. -For these applications, we recommend using a pandoc binary compiled with -the \f[V]embed_data_files\f[R] option, which causes the data files to be -baked into the binary instead of being stored on the file system. -.RE -.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[=true|false]\f[R], \f[V]--table-of-contents[=true|false]\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[=true|false]\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[=true|false]\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[=true|false]\f[R] -\f[I]Deprecated synonym for -\f[VI]--embed-resources --standalone\f[I].\f[R] -.TP -\f[V]--embed-resources[=true|false]\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. -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, fonts may be missing when -\f[V]--mathjax\f[R] is used, 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[=true|false]\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[=true|false]\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 man and ms (which use hexadecimal escapes), -and to a limited degree LaTeX (which uses standard commands for accented -characters when possible). -.TP -\f[V]--reference-links[=true|false]\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. -In slide formats, specifying \f[V]--reference-location=section\f[R] will -cause notes to be rendered at the bottom of a slide. -.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]--list-tables[=true|false]\f[R] -Render tables as list tables in RST output. -.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[=true|false]\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[=true|false]\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[=true|false]\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). -This option only affects HTML output (and does not affect HTML slide -formats). -.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. -This option only affects HTML (including HTML slide shows) and EPUB -output. -It should be used together with \f[V]-s/--standalone\f[R], because the -link to the stylesheet goes in the document header. -.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]|\f[I]URL\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 -AbstractTitle -.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 -Source Code -.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]--split-level=\f[R]\f[I]NUMBER\f[R] -Specify the heading level at which to split an EPUB or chunked HTML -document into separate files. -The default is to split into chapters at level-1 headings. -In the case of EPUB, 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. -For chunked HTML, this option determines how much content goes in each -\[lq]chunk.\[rq] -.TP -\f[V]--chunk-template=\f[R]\f[I]PATHTEMPLATE\f[R] -Specify a template for the filenames in a \f[V]chunkedhtml\f[R] -document. -In the template, \f[V]%n\f[R] will be replaced by the chunk number -(padded with leading 0s to 3 digits), \f[V]%s\f[R] with the section -number of the chunk, \f[V]%h\f[R] with the heading text (with formatting -removed), \f[V]%i\f[R] with the section identifier. -For example, \f[V]%section-%s-%i.html\f[R] might be resolved to -\f[V]section-1.1-introduction.html\f[R]. -The characters \f[V]/\f[R] and \f[V]\[rs]\f[R] are not allowed in chunk -templates and will be ignored. -The default is \f[V]%s-%i.html\f[R]. -.TP -\f[V]--epub-chapter-level=\f[R]\f[I]NUMBER\f[R] -\f[I]Deprecated synonym for \f[VI]--split-level\f[I].\f[R] -.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-title-page=true\f[R]|\f[V]false\f[R] -Determines whether a the title page is included in the EPUB (default is -\f[V]true\f[R]). -.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]../fonts/DejaVuSans-Regular.ttf\[dq]); -} -\[at]font-face { - font-family: DejaVuSans; - font-style: normal; - font-weight: bold; - src:url(\[dq]../fonts/DejaVuSans-Bold.ttf\[dq]); -} -\[at]font-face { - font-family: DejaVuSans; - font-style: italic; - font-weight: normal; - src:url(\[dq]../fonts/DejaVuSans-Oblique.ttf\[dq]); -} -\[at]font-face { - font-family: DejaVuSans; - font-style: italic; - font-weight: bold; - src:url(\[dq]../fonts/DejaVuSans-BoldOblique.ttf\[dq]); -} -body { font-family: \[dq]DejaVuSans\[dq]; } -\f[R] -.fi -.RE -.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], \f[V]pdfroff\f[R], and -\f[V]typst\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] -.IP \[bu] 2 -\f[V]-t typst\f[R]: \f[V]typst\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. -MathML is supported natively by the main web browsers and select e-book -readers. -.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[=true|false]\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[=true|false]\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: -.RS -14n -.IP -.nf -\f[C] - Code Error - ------ ------------------------------------- - 1 PandocIOError - 3 PandocFailOnWarningError - 4 PandocAppError - 5 PandocTemplateError - 6 PandocOptionError - 21 PandocUnknownReaderError - 22 PandocUnknownWriterError - 23 PandocUnsupportedExtensionError - 24 PandocCiteprocError - 25 PandocBibliographyError - 31 PandocEpubSubdirectoryError - 43 PandocPDFError - 44 PandocXMLError - 47 PandocPDFProgramNotFoundError - 61 PandocHttpError - 62 PandocShouldNeverHappenError - 63 PandocSomeError - 64 PandocParseError - 66 PandocMakePDFError - 67 PandocSyntaxMapError - 83 PandocFilterError - 84 PandocLuaError - 89 PandocNoScriptingEngine - 91 PandocMacroLoop - 92 PandocUTF8DecodingError - 93 PandocIpynbDecodingError - 94 PandocUnsupportedCharsetError - 97 PandocCouldNotFindDataFileError - 98 PandocCouldNotFindMetadataFileError - 99 PandocResourceNotFound -\f[R] -.fi -.RE -.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. -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - foo.md input-file: foo.md - - foo.md bar.md input-files: - - foo.md - - bar.md - -\f[R] -.fi -.RE -.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 -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - --from markdown+emoji from: markdown+emoji - - reader: markdown+emoji - - to: markdown+hard_line_breaks - --to markdown+hard_line_breaks - - writer: markdown+hard_line_breaks - - --output foo.pdf output-file: foo.pdf - - --output - output-file: - - --data-dir dir data-dir: dir - - --defaults file defaults: - - file - - --verbose verbosity: INFO - - --quiet verbosity: ERROR - - --fail-if-warnings fail-if-warnings: true - - --sandbox sandbox: true - - --log=FILE log-file: FILE - -\f[R] -.fi -.RE -.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 -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - --shift-heading-level-by -1 shift-heading-level-by: -1 - - indented-code-classes: - --indented-code-classes python - python - - - --default-image-extension \[dq].jpg\[dq] default-image-extension: \[aq].jpg\[aq] - - --file-scope file-scope: true - - --filter pandoc-citeproc \[rs] filters: - - pandoc-citeproc - --lua-filter count-words.lua \[rs] - count-words.lua - --filter special.lua - type: json - path: special.lua - - --metadata key=value \[rs] metadata: - --metadata key2 key: value - key2: true - - --metadata-file meta.yaml metadata-files: - - meta.yaml - - metadata-file: meta.yaml - - --preserve-tabs preserve-tabs: true - - --tab-stop 8 tab-stop: 8 - - --track-changes accept track-changes: accept - - --extract-media dir extract-media: dir - - --abbreviations abbrevs.txt abbreviations: abbrevs.txt - - --trace trace: true - -\f[R] -.fi -.RE -.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 -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - --standalone standalone: true - - --template letter template: letter - - --variable key=val \[rs] variables: - --variable key2 key: val - key2: true - - --eol nl eol: nl - - --dpi 300 dpi: 300 - - --wrap 60 wrap: 60 - - --columns 72 columns: 72 - - --table-of-contents table-of-contents: true - - --toc toc: true - - --toc-depth 3 toc-depth: 3 - - --strip-comments strip-comments: true - - --no-highlight highlight-style: null - - --highlight-style kate highlight-style: kate - - syntax-definitions: - --syntax-definition mylang.xml - mylang.xml - - syntax-definition: mylang.xml - - --include-in-header inc.tex include-in-header: - - inc.tex - - include-before-body: ---include-before-body inc.tex - inc.tex - - --include-after-body inc.tex include-after-body: - - inc.tex - - --resource-path .:foo resource-path: [\[aq].\[aq],\[aq]foo\[aq]] - - --request-header foo:bar request-headers: - - - [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]] - - --no-check-certificate no-check-certificate: true - -\f[R] -.fi -.RE -.SS Options affecting specific writers -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - --self-contained self-contained: true - - --html-q-tags html-q-tags: true - - --ascii ascii: true - - --reference-links reference-links: true - - --reference-location block reference-location: block - - --markdown-headings atx markdown-headings: atx - - --list-tables list-tables: true - - --top-level-division chapter top-level-division: chapter - - --number-sections number-sections: true - - --number-offset=1,4 number-offset: \[rs][1,4\[rs]] - - --listings listings: true - - --incremental incremental: true - - --slide-level 2 slide-level: 2 - - --section-divs section-divs: true - - email-obfuscation: references - --email-obfuscation references - - --id-prefix ch1 identifier-prefix: ch1 - - --title-prefix MySite title-prefix: MySite - - --css styles/screen.css \[rs] css: - --css styles/special.css - styles/screen.css - - styles/special.css - - --reference-doc my.docx reference-doc: my.docx - - --epub-cover-image cover.jpg epub-cover-image: cover.jpg - - --epub-title-page=false epub-title-page: false - - --epub-metadata meta.xml epub-metadata: meta.xml - - epub-fonts: - --epub-embed-font special.otf \[rs] - special.otf - - headline.otf - --epub-embed-font headline.otf - - --split-level 2 split-level: 2 - - --chunk-template=\[dq]%i.html\[dq] chunk-template: \[dq]%i.html\[dq] - - --epub-subdirectory=\[dq]\[dq] epub-subdirectory: \[aq]\[aq] - - --ipynb-output best ipynb-output: best - - --pdf-engine xelatex pdf-engine: xelatex - - pdf-engine-opts: - --pdf-engine-opt=--shell-escape - \[aq]-shell-escape\[aq] - - - pdf-engine-opt: \[aq]-shell-escape\[aq] - -\f[R] -.fi -.RE -.SS Citation rendering -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - --citeproc citeproc: true - - --bibliography logic.bib metadata: - bibliography: logic.bib - - --csl ieee.csl metadata: - csl: ieee.csl - - metadata: - --citation-abbreviations ab.json - citation-abbreviations: ab.json - - --natbib cite-method: natbib - - --biblatex cite-method: biblatex - -\f[R] -.fi -.RE -.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 -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - --mathjax html-math-method: - method: mathjax - - --mathml html-math-method: - method: mathml - - --webtex html-math-method: - method: webtex - - --katex html-math-method: - method: katex - - --gladtex html-math-method: - method: gladtex - -\f[R] -.fi -.RE -.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 -.RS -14n -.IP -.nf -\f[C] - - command line defaults file - --------------------------------- ---------------------------------- - --dump-args dump-args: true - - --ignore-args ignore-args: true - -\f[R] -.fi -.RE -.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 preceded 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 a 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 numerals. -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 HTML, LaTeX, ConTeXt, AsciiDoc, and docx -documents -.TP -\f[V]abstract-title\f[R] -title of abstract, currently used only in HTML, EPUB, and docx. -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 écrite en franç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]maxwidth\f[R] -sets the CSS \f[V]max-width\f[R] property (default is 32em). -.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, beamer, and pptx 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 -\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], \f[V]CJKsansfont\f[R], \f[V]CJKmonofont\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]babelfonts\f[R] -a map of Babel language names (e.g.\ \f[V]chinese\f[R]) to the font to -be used with the language: -.RS -.PP - * * * * * -.PP -babelfonts: chinese-hant: \[lq]Noto Serif CJK TC\[rq] russian: \[lq]Noto -Serif\[rq] \&... -.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]boxlinks\f[R] -add visible box around links (has no effect if \f[V]colorlinks\f[R] is -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 -.TP -\f[V]urlstyle\f[R] -style for URLs (e.g., \f[V]tt\f[R], \f[V]rm\f[R], \f[V]sf\f[R], and, the -default, \f[V]same\f[R]) -.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]urlstyle\f[R] -typeface style for links without link text, 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]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]section\f[R] -section number in man pages -.SS Variables for Typst -.TP -\f[V]margin\f[R] -A dictionary with the fields defined in the Typst documentation: -\f[V]x\f[R], \f[V]y\f[R], \f[V]top\f[R], \f[V]bottom\f[R], -\f[V]left\f[R], \f[V]right\f[R]. -.TP -\f[V]papersize\f[R] -Paper size: \f[V]a4\f[R], \f[V]us-letter\f[R], etc. -.TP -\f[V]mainfont\f[R] -Name of system font to use for the main font. -.TP -\f[V]fontsize\f[R] -Font size (e.g., \f[V]12pt\f[R]). -.TP -\f[V]section-numbering\f[R] -Schema to use for numbering sections, e.g.\ \f[V]1.A.1\f[R]. -.TP -\f[V]columns\f[R] -Number of columns for body text. -.SS Variables for ms -.TP -\f[V]fontfamily\f[R] -\f[V]A\f[R] (Avant Garde), \f[V]B\f[R] (Bookman), \f[V]C\f[R] -(Helvetica), \f[V]HN\f[R] (Helvetica Narrow), \f[V]P\f[R] (Palatino), or -\f[V]T\f[R] (Times New Roman). -This setting does not affect source code, which is always displayed -using monospace Courier. -These built-in fonts are limited in their coverage of characters. -Additional fonts may be installed using the script -\f[V]install-font.sh\f[R] provided by Peter Schaffter and documented in -detail on his web site. -.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]pandoc-version\f[R] -pandoc version. -.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]--markdown-headings\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], -\f[V]html\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, -.RS -14n -.IP -.nf -\f[C] - Heading Identifier - ----------------------------- ----------------------------- - Heading identifiers in HTML heading-identifiers-in-html - Maître d\[aq]hôtel maître-dhôtel - *Dogs*?--in *my* house? dogs--in-my-house - [HTML], [S5], or [RTF]? html-s5-or-rtf - 3. Applications applications - 33 section -\f[R] -.fi -.RE -.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 -When the \f[V]citations\f[R] extension is enabled in \f[V]org\f[R], -org-cite and org-ref style citations will be parsed as native pandoc -citations. -.PP -When \f[V]citations\f[R] is enabled in \f[V]docx\f[R], citations -inserted by Zotero or Mendeley or EndNote plugins will be parsed as -native pandoc citations. -(Otherwise, the formatted citations generated by the bibliographic -software will be parsed as regular text.) -.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. -.SS Extension: \f[V]tagging\f[R] -.PP -Enabling this extension with \f[V]context\f[R] output will produce -markup suitable for the production of tagged PDFs. -This includes additional markers for paragraphs and alternative markup -for emphasized text. -The \f[V]emphasis-command\f[R] template variable is set if the extension -is enabled. -.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. ->> Not nested, since \[ga]blank_before_blockquote\[ga] is enabled by default -\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 use 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 -This shortcut form may be combined with attributes: -.IP -.nf -\f[C] -\[ga]\[ga]\[ga]haskell {.numberLines} -qsort [] = [] -\[ga]\[ga]\[ga] -\f[R] -.fi -.PP -Which is equivalent to: -.IP -.nf -\f[C] -\[ga]\[ga]\[ga] {.haskell .numberLines} -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-parenthesis 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 -.PP -Note: the `\f[V]#\f[R]' ordered list marker doesn\[cq]t work with -\f[V]commonmark\f[R]. -.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 the -\f[V]compact_definition_lists\f[R] extension.) -.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 -.PP -We strongly recommend that horizontal rules be separated from -surrounding text by blank lines. -If a horizontal rule is not followed by a blank line, pandoc may try to -interpret the lines that follow as a YAML metadata block or a table. -.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 -\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.). -.PP -Cells can span multiple columns or rows: -.IP -.nf -\f[C] -+---------------------+----------+ -| Property | Earth | -+=============+=======+==========+ -| | min | -89.2 °C | -| Temperature +-------+----------+ -| 1961-1990 | mean | 14 °C | -| +-------+----------+ -| | max | 56.7 °C | -+-------------+-------+----------+ -\f[R] -.fi -.PP -A table header may contain more than one row: -.IP -.nf -\f[C] -+---------------------+-----------------------+ -| Location | Temperature 1961-1990 | -| | in degree Celsius | -| +-------+-------+-------+ -| | min | mean | max | -+=====================+=======+=======+=======+ -| Antarctica | -89.2 | N/A | 19.8 | -+---------------------+-------+-------+-------+ -| Earth | -89.2 | 14 | 56.7 | -+---------------------+-------+-------+-------+ -\f[R] -.fi -.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 -.PP -A table foot can be defined by enclosing it with separator lines that -use \f[V]=\f[R] instead of \f[V]-\f[R]: -.IP -.nf -\f[C] - +---------------+---------------+ - | Fruit | Price | - +===============+===============+ - | Bananas | $1.34 | - +---------------+---------------+ - | Oranges | $2.10 | - +===============+===============+ - | Sum | $3.44 | - +===============+===============+ -\f[R] -.fi -.PP -The foot must always be placed at the very bottom of the table. -.PP -Grid tables can be created easily using Emacs\[cq] table-mode -(\f[V]M-x table-insert\f[R]). -.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. -The initial line \f[V]---\f[R] must not be followed by a blank line. -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. -.PP -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 strike out 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 Highlighting -.PP -To highlight text, use the \f[V]mark\f[R] class: -.IP -.nf -\f[C] -[Mark]{.mark} -\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] -Mark -\f[R] -.fi -.PP -This will work in all output formats that support highlighting. -.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 between 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 math will appear verbatim surrounded by -\f[V]latexmath:[...]\f[R]. -For \f[V]asciidoc_legacy\f[R] the bracketed material will also include -inline or display math delimiters. -.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 and PowerPoint -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, -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]--markdown-headings=setext\f[R] will cause -Setext-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 to -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 -If the script is not found relative to the working directory, it will be -sought in the \f[V]custom\f[R] subdirectory of the user data directory -(see \f[V]--data-dir\f[R]). -.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. -See the djot-writer.lua for a full-featured example. -.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 seconds 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 ACCESSIBLE PDFS AND PDF ARCHIVING STANDARDS -.PP -PDF is a flexible format, and using PDF in certain contexts requires -additional conventions. -For example, PDFs are not accessible by default; they define how -characters are placed on a page but do not contain semantic information -on the content. -However, it is possible to generate accessible PDFs, which use tagging -to add semantic information to the document. -.PP -Pandoc defaults to LaTeX to generate PDF. -Tagging support in LaTeX is in development and not readily available, so -PDFs generated in this way will always be untagged and not accessible. -This means that alternative engines must be used to generate accessible -PDFs. -.PP -The PDF standards PDF/A and PDF/UA define further restrictions intended -to optimize PDFs for archiving and accessibility. -Tagging is commonly used in combination with these standards to ensure -best results. -.PP -Note, however, that standard compliance depends on many things, -including the colorspace of embedded images. -Pandoc cannot check this, and external programs must be used to ensure -that generated PDFs are in compliance. -.SS ConTeXt -.PP -ConTeXt always produces tagged PDFs, but the quality depends on the -input. -The default ConTeXt markup generated by pandoc is optimized for -readability and reuse, not tagging. -Enable the \f[V]tagging\f[R] format extension to force markup that is -optimized for tagging. -This can be combined with the \f[V]pdfa\f[R] variable to generate -standard-compliant PDFs. -E.g.: -.IP -.nf -\f[C] -pandoc --to=context+tagging -V pdfa=3a -\f[R] -.fi -.PP -A recent \f[V]context\f[R] version should be used, as older versions -contained a bug that lead to invalid PDF metadata. -.SS WeasyPrint -.PP -The HTML-based engine WeasyPrint includes experimental support for PDF/A -and PDF/UA since version 57. -Tagged PDFs can created with -.IP -.nf -\f[C] -pandoc --pdf-engine=weasyprint \[rs] - --pdf-engine-opt=--pdf-variant=pdf/ua-1 ... -\f[R] -.fi -.PP -The feature is experimental and standard compliance should not be -assumed. -.SS Prince XML -.PP -The non-free HTML-to-PDf converter \f[V]prince\f[R] has extensive -support for various PDF standards as well as tagging. -E.g.: -.IP -.nf -\f[C] -pandoc --pdf-engine=prince \[rs] - --pdf-engine-opt=--tagged-pdf ... -\f[R] -.fi -.PP -See the prince documentation for more info. -.SS Word Processors -.PP -Word processors like LibreOffice and MS Word can also be used to -generate standardized and tagged PDF output. -Pandoc does not support direct conversions via these tools. -However, pandoc can convert a document to a \f[V]docx\f[R] or -\f[V]odt\f[R] file, which can then be opened and converted to PDF with -the respective word processor. -See the documentation for Word and LibreOffice. -.SH RUNNING PANDOC AS A WEB SERVER -.PP -If you rename (or symlink) the pandoc executable to -\f[V]pandoc-server\f[R], or if you call pandoc with \f[V]server\f[R] as -the first argument, it will start up a web server with a JSON API. -This server exposes most of the conversion functionality of pandoc. -For full documentation, see the pandoc-server man page. -.PP -If you rename (or symlink) the pandoc executable to -\f[V]pandoc-server.cgi\f[R], it will function as a CGI program exposing -the same API as \f[V]pandoc-server\f[R]. -.PP -\f[V]pandoc-server\f[R] is designed to be maximally secure; it uses -Haskell\[cq]s type system to provide strong guarantees that no I/O will -be performed on the server during pandoc conversions. -.SH RUNNING PANDOC AS A LUA INTERPRETER -.PP -Calling the pandoc executable under the name \f[V]pandoc-lua\f[R] or -with \f[V]lua\f[R] as the first argument will make it function as a -standalone Lua interpreter. -The behavior is mostly identical to that of the standalone \f[V]lua\f[R] -executable, version 5.4. -However, there is no REPL yet, and the \f[V]-i\f[R] option has no -effect. -For full documentation, see the pandoc-lua man page. -.SH A NOTE ON SECURITY -.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. -(This corresponds to the use of the \f[V]--sandbox\f[R] option on the -command line.) -.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 HTML generated from untrusted user input -through an HTML sanitizer. -.SH AUTHORS -.PP +.\" Automatically generated by Pandoc 3.1.7 +.\" +.TH "pandoc" "1" "September 08, 2023" "pandoc 3.1.8" "Pandoc User\[cq]s Guide" +.SH NAME +pandoc - general markup converter +.SH SYNOPSIS +\f[CR]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]\&... +.SH DESCRIPTION +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[CR]--from\f[R] and \f[CR]--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 +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[CR]-o\f[R] option: +.IP +.EX +pandoc -o output.html input.txt +.EE +.PP +By default, pandoc produces a document fragment. +To produce a standalone document (e.g.\ a valid HTML file including +\f[CR]\f[R] and \f[CR]\f[R]), use the \f[CR]-s\f[R] or +\f[CR]--standalone\f[R] flag: +.IP +.EX +pandoc -s -o output.html input.txt +.EE +.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[CR]--file-scope\f[R] to parse files individually.) +.SS Specifying formats +The format of the input and output can be specified explicitly using +command-line options. +The input format can be specified using the \f[CR]-f/--from\f[R] option, +the output format using the \f[CR]-t/--to\f[R] option. +Thus, to convert \f[CR]hello.txt\f[R] from Markdown to LaTeX, you could +type: +.IP +.EX +pandoc -f markdown -t latex hello.txt +.EE +.PP +To convert \f[CR]hello.html\f[R] from HTML to Markdown: +.IP +.EX +pandoc -f html -t markdown hello.html +.EE +.PP +Supported input and output formats are listed below under Options (see +\f[CR]-f\f[R] for input formats and \f[CR]-t\f[R] for output formats). +You can also use \f[CR]pandoc --list-input-formats\f[R] and +\f[CR]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 +.EX +pandoc -o hello.tex hello.txt +.EE +.PP +will convert \f[CR]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 +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[CR]iconv\f[R]: +.IP +.EX +iconv -t utf-8 input.txt | pandoc | iconv -f utf-8 +.EE +.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[CR]-s/--standalone\f[R] option. +.SS Creating a PDF +To produce a PDF, specify an output file with a \f[CR].pdf\f[R] +extension: +.IP +.EX +pandoc test.txt -o test.pdf +.EE +.PP +By default, pandoc will use LaTeX to create the PDF, which requires that +a LaTeX engine be installed (see \f[CR]--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[CR].pdf\f[R] extension, as +before, but add the \f[CR]--pdf-engine\f[R] option or +\f[CR]-t context\f[R], \f[CR]-t html\f[R], or \f[CR]-t ms\f[R] to the +command line. +The tool used to generate the PDF from the intermediate format may be +specified using \f[CR]--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[CR]wkhtmltopdf\f[R], variables for ms. +When HTML is used as an intermediate format, the output can be styled +using \f[CR]--css\f[R]. +.PP +To debug the PDF creation, it can be useful to look at the intermediate +representation: instead of \f[CR]-o test.pdf\f[R], use for example +\f[CR]-s -o test.tex\f[R] to output the generated LaTeX. +You can then test it with \f[CR]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[CR]amsfonts\f[R], +\f[CR]amsmath\f[R], \f[CR]lm\f[R], \f[CR]unicode-math\f[R], +\f[CR]iftex\f[R], \f[CR]listings\f[R] (if the \f[CR]--listings\f[R] +option is used), \f[CR]fancyvrb\f[R], \f[CR]longtable\f[R], +\f[CR]booktabs\f[R], \f[CR]graphicx\f[R] (if the document contains +images), \f[CR]hyperref\f[R], \f[CR]xcolor\f[R], \f[CR]soul\f[R], +\f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] variable set), +\f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and \f[CR]babel\f[R] +(with \f[CR]lang\f[R]). +If \f[CR]CJKmainfont\f[R] is set, \f[CR]xeCJK\f[R] is needed. +The use of \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R] as the PDF engine +requires \f[CR]fontspec\f[R]. +\f[CR]lualatex\f[R] uses \f[CR]selnolig\f[R]. +\f[CR]xelatex\f[R] uses \f[CR]bidi\f[R] (with the \f[CR]dir\f[R] +variable set). +If the \f[CR]mathspec\f[R] variable is set, \f[CR]xelatex\f[R] will use +\f[CR]mathspec\f[R] instead of \f[CR]unicode-math\f[R]. +The \f[CR]upquote\f[R] and \f[CR]microtype\f[R] packages are used if +available, and \f[CR]csquotes\f[R] will be used for typography if the +\f[CR]csquotes\f[R] variable or metadata field is set to a true value. +The \f[CR]natbib\f[R], \f[CR]biblatex\f[R], \f[CR]bibtex\f[R], and +\f[CR]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[CR]upquote\f[R] (for straight quotes in verbatim environments), +\f[CR]microtype\f[R] (for better spacing adjustments), +\f[CR]parskip\f[R] (for better inter-paragraph spaces), \f[CR]xurl\f[R] +(for better line breaks in URLs), \f[CR]bookmark\f[R] (for better PDF +bookmarks), and \f[CR]footnotehyper\f[R] or \f[CR]footnote\f[R] (to +allow footnotes in tables). +.SS Reading from the Web +Instead of an input file, an absolute URI may be given. +In this case pandoc will fetch the content using HTTP: +.IP +.EX +pandoc -f html -t markdown https://www.fsf.org +.EE +.PP +It is possible to supply a custom User-Agent string or other header when +requesting a document from a URL: +.IP +.EX +pandoc -f html -t markdown --request-header User-Agent:\[dq]Mozilla/5.0\[dq] \[rs] + https://www.fsf.org +.EE +.SH OPTIONS +.SS General options +.TP +\f[CR]-f\f[R] \f[I]FORMAT\f[R], \f[CR]-r\f[R] \f[I]FORMAT\f[R], \f[CR]--from=\f[R]\f[I]FORMAT\f[R], \f[CR]--read=\f[R]\f[I]FORMAT\f[R] +Specify input format. +\f[I]FORMAT\f[R] can be: +.RS +.IP \[bu] 2 +\f[CR]bibtex\f[R] (BibTeX bibliography) +.IP \[bu] 2 +\f[CR]biblatex\f[R] (BibLaTeX bibliography) +.IP \[bu] 2 +\f[CR]commonmark\f[R] (CommonMark Markdown) +.IP \[bu] 2 +\f[CR]commonmark_x\f[R] (CommonMark Markdown with extensions) +.IP \[bu] 2 +\f[CR]creole\f[R] (Creole 1.0) +.IP \[bu] 2 +\f[CR]csljson\f[R] (CSL JSON bibliography) +.IP \[bu] 2 +\f[CR]csv\f[R] (CSV table) +.IP \[bu] 2 +\f[CR]tsv\f[R] (TSV table) +.IP \[bu] 2 +\f[CR]docbook\f[R] (DocBook) +.IP \[bu] 2 +\f[CR]docx\f[R] (Word docx) +.IP \[bu] 2 +\f[CR]dokuwiki\f[R] (DokuWiki markup) +.IP \[bu] 2 +\f[CR]endnotexml\f[R] (EndNote XML bibliography) +.IP \[bu] 2 +\f[CR]epub\f[R] (EPUB) +.IP \[bu] 2 +\f[CR]fb2\f[R] (FictionBook2 e-book) +.IP \[bu] 2 +\f[CR]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less +accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only +if you need extensions not supported in \f[CR]gfm\f[R]. +.IP \[bu] 2 +\f[CR]haddock\f[R] (Haddock markup) +.IP \[bu] 2 +\f[CR]html\f[R] (HTML) +.IP \[bu] 2 +\f[CR]ipynb\f[R] (Jupyter notebook) +.IP \[bu] 2 +\f[CR]jats\f[R] (JATS XML) +.IP \[bu] 2 +\f[CR]jira\f[R] (Jira/Confluence wiki markup) +.IP \[bu] 2 +\f[CR]json\f[R] (JSON version of native AST) +.IP \[bu] 2 +\f[CR]latex\f[R] (LaTeX) +.IP \[bu] 2 +\f[CR]markdown\f[R] (Pandoc\[cq]s Markdown) +.IP \[bu] 2 +\f[CR]markdown_mmd\f[R] (MultiMarkdown) +.IP \[bu] 2 +\f[CR]markdown_phpextra\f[R] (PHP Markdown Extra) +.IP \[bu] 2 +\f[CR]markdown_strict\f[R] (original unextended Markdown) +.IP \[bu] 2 +\f[CR]mediawiki\f[R] (MediaWiki markup) +.IP \[bu] 2 +\f[CR]man\f[R] (roff man) +.IP \[bu] 2 +\f[CR]muse\f[R] (Muse) +.IP \[bu] 2 +\f[CR]native\f[R] (native Haskell) +.IP \[bu] 2 +\f[CR]odt\f[R] (ODT) +.IP \[bu] 2 +\f[CR]opml\f[R] (OPML) +.IP \[bu] 2 +\f[CR]org\f[R] (Emacs Org mode) +.IP \[bu] 2 +\f[CR]ris\f[R] (RIS bibliography) +.IP \[bu] 2 +\f[CR]rtf\f[R] (Rich Text Format) +.IP \[bu] 2 +\f[CR]rst\f[R] (reStructuredText) +.IP \[bu] 2 +\f[CR]t2t\f[R] (txt2tags) +.IP \[bu] 2 +\f[CR]textile\f[R] (Textile) +.IP \[bu] 2 +\f[CR]tikiwiki\f[R] (TikiWiki markup) +.IP \[bu] 2 +\f[CR]twiki\f[R] (TWiki markup) +.IP \[bu] 2 +\f[CR]typst\f[R] (typst) +.IP \[bu] 2 +\f[CR]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[CR]+EXTENSION\f[R] or \f[CR]-EXTENSION\f[R] to the format name. +See Extensions below, for a list of extensions and their names. +See \f[CR]--list-input-formats\f[R] and \f[CR]--list-extensions\f[R], +below. +.RE +.TP +\f[CR]-t\f[R] \f[I]FORMAT\f[R], \f[CR]-w\f[R] \f[I]FORMAT\f[R], \f[CR]--to=\f[R]\f[I]FORMAT\f[R], \f[CR]--write=\f[R]\f[I]FORMAT\f[R] +Specify output format. +\f[I]FORMAT\f[R] can be: +.RS +.IP \[bu] 2 +\f[CR]asciidoc\f[R] (modern AsciiDoc as interpreted by AsciiDoctor) +.IP \[bu] 2 +\f[CR]asciidoc_legacy\f[R] (AsciiDoc as interpreted by +\f[CR]asciidoc-py\f[R]). +.IP \[bu] 2 +\f[CR]asciidoctor\f[R] (deprecated synonym for \f[CR]asciidoc\f[R]) +.IP \[bu] 2 +\f[CR]beamer\f[R] (LaTeX beamer slide show) +.IP \[bu] 2 +\f[CR]bibtex\f[R] (BibTeX bibliography) +.IP \[bu] 2 +\f[CR]biblatex\f[R] (BibLaTeX bibliography) +.IP \[bu] 2 +\f[CR]chunkedhtml\f[R] (zip archive of multiple linked HTML files) +.IP \[bu] 2 +\f[CR]commonmark\f[R] (CommonMark Markdown) +.IP \[bu] 2 +\f[CR]commonmark_x\f[R] (CommonMark Markdown with extensions) +.IP \[bu] 2 +\f[CR]context\f[R] (ConTeXt) +.IP \[bu] 2 +\f[CR]csljson\f[R] (CSL JSON bibliography) +.IP \[bu] 2 +\f[CR]docbook\f[R] or \f[CR]docbook4\f[R] (DocBook 4) +.IP \[bu] 2 +\f[CR]docbook5\f[R] (DocBook 5) +.IP \[bu] 2 +\f[CR]docx\f[R] (Word docx) +.IP \[bu] 2 +\f[CR]dokuwiki\f[R] (DokuWiki markup) +.IP \[bu] 2 +\f[CR]epub\f[R] or \f[CR]epub3\f[R] (EPUB v3 book) +.IP \[bu] 2 +\f[CR]epub2\f[R] (EPUB v2) +.IP \[bu] 2 +\f[CR]fb2\f[R] (FictionBook2 e-book) +.IP \[bu] 2 +\f[CR]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less +accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only +if you need extensions not supported in \f[CR]gfm\f[R]. +.IP \[bu] 2 +\f[CR]haddock\f[R] (Haddock markup) +.IP \[bu] 2 +\f[CR]html\f[R] or \f[CR]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot +markup) +.IP \[bu] 2 +\f[CR]html4\f[R] (XHTML 1.0 Transitional) +.IP \[bu] 2 +\f[CR]icml\f[R] (InDesign ICML) +.IP \[bu] 2 +\f[CR]ipynb\f[R] (Jupyter notebook) +.IP \[bu] 2 +\f[CR]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set) +.IP \[bu] 2 +\f[CR]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set) +.IP \[bu] 2 +\f[CR]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set) +.IP \[bu] 2 +\f[CR]jats\f[R] (alias for \f[CR]jats_archiving\f[R]) +.IP \[bu] 2 +\f[CR]jira\f[R] (Jira/Confluence wiki markup) +.IP \[bu] 2 +\f[CR]json\f[R] (JSON version of native AST) +.IP \[bu] 2 +\f[CR]latex\f[R] (LaTeX) +.IP \[bu] 2 +\f[CR]man\f[R] (roff man) +.IP \[bu] 2 +\f[CR]markdown\f[R] (Pandoc\[cq]s Markdown) +.IP \[bu] 2 +\f[CR]markdown_mmd\f[R] (MultiMarkdown) +.IP \[bu] 2 +\f[CR]markdown_phpextra\f[R] (PHP Markdown Extra) +.IP \[bu] 2 +\f[CR]markdown_strict\f[R] (original unextended Markdown) +.IP \[bu] 2 +\f[CR]markua\f[R] (Markua) +.IP \[bu] 2 +\f[CR]mediawiki\f[R] (MediaWiki markup) +.IP \[bu] 2 +\f[CR]ms\f[R] (roff ms) +.IP \[bu] 2 +\f[CR]muse\f[R] (Muse) +.IP \[bu] 2 +\f[CR]native\f[R] (native Haskell) +.IP \[bu] 2 +\f[CR]odt\f[R] (OpenOffice text document) +.IP \[bu] 2 +\f[CR]opml\f[R] (OPML) +.IP \[bu] 2 +\f[CR]opendocument\f[R] (OpenDocument) +.IP \[bu] 2 +\f[CR]org\f[R] (Emacs Org mode) +.IP \[bu] 2 +\f[CR]pdf\f[R] (PDF) +.IP \[bu] 2 +\f[CR]plain\f[R] (plain text) +.IP \[bu] 2 +\f[CR]pptx\f[R] (PowerPoint slide show) +.IP \[bu] 2 +\f[CR]rst\f[R] (reStructuredText) +.IP \[bu] 2 +\f[CR]rtf\f[R] (Rich Text Format) +.IP \[bu] 2 +\f[CR]texinfo\f[R] (GNU Texinfo) +.IP \[bu] 2 +\f[CR]textile\f[R] (Textile) +.IP \[bu] 2 +\f[CR]slideous\f[R] (Slideous HTML and JavaScript slide show) +.IP \[bu] 2 +\f[CR]slidy\f[R] (Slidy HTML and JavaScript slide show) +.IP \[bu] 2 +\f[CR]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show) +.IP \[bu] 2 +\f[CR]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show) +.IP \[bu] 2 +\f[CR]s5\f[R] (S5 HTML and JavaScript slide show) +.IP \[bu] 2 +\f[CR]tei\f[R] (TEI Simple) +.IP \[bu] 2 +\f[CR]typst\f[R] (typst) +.IP \[bu] 2 +\f[CR]xwiki\f[R] (XWiki markup) +.IP \[bu] 2 +\f[CR]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[CR]odt\f[R], \f[CR]docx\f[R], \f[CR]epub\f[R], and +\f[CR]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless +forced with \f[CR]-o -\f[R]. +.PP +Extensions can be individually enabled or disabled by appending +\f[CR]+EXTENSION\f[R] or \f[CR]-EXTENSION\f[R] to the format name. +See Extensions below, for a list of extensions and their names. +See \f[CR]--list-output-formats\f[R] and \f[CR]--list-extensions\f[R], +below. +.RE +.TP +\f[CR]-o\f[R] \f[I]FILE\f[R], \f[CR]--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[CR]-\f[R], output will go to \f[I]stdout\f[R], +even if a non-textual format (\f[CR]docx\f[R], \f[CR]odt\f[R], +\f[CR]epub2\f[R], \f[CR]epub3\f[R]) is specified. +If the output format is \f[CR]chunkedhtml\f[R] and \f[I]FILE\f[R] has no +extension, then instead of producing a \f[CR].zip\f[R] file pandoc will +create a directory \f[I]FILE\f[R] and unpack the zip archive there +(unless \f[I]FILE\f[R] already exists, in which case an error will be +raised). +.TP +\f[CR]--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[CR]pandoc\f[R] +subdirectory of the XDG data directory (by default, +\f[CR]$HOME/.local/share\f[R], overridable by setting the +\f[CR]XDG_DATA_HOME\f[R] environment variable). +If that directory does not exist and \f[CR]$HOME/.pandoc\f[R] exists, it +will be used (for backwards compatibility). +On Windows the default user data directory is +\f[CR]%APPDATA%\[rs]pandoc\f[R]. +You can find the default user data directory on your system by looking +at the output of \f[CR]pandoc --version\f[R]. +Data files placed in this directory (for example, +\f[CR]reference.odt\f[R], \f[CR]reference.docx\f[R], +\f[CR]epub.css\f[R], \f[CR]templates\f[R]) will override pandoc\[cq]s +normal defaults. +(Note that the user data directory is not created by pandoc, so you will +need to create it yourself if you want to make use of it.) +.TP +\f[CR]-d\f[R] \f[I]FILE\f[R], \f[CR]--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[CR]defaults\f[R] subdirectory of the user data directory (see +\f[CR]--data-dir\f[R]). +The \f[CR].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[CR]--bash-completion\f[R] +Generate a bash completion script. +To enable bash completion with pandoc, add this to your +\f[CR].bashrc\f[R]: +.RS +.IP +.EX +eval \[dq]$(pandoc --bash-completion)\[dq] +.EE +.RE +.TP +\f[CR]--verbose\f[R] +Give verbose debugging output. +.TP +\f[CR]--quiet\f[R] +Suppress warning messages. +.TP +\f[CR]--fail-if-warnings[=true|false]\f[R] +Exit with error status if there are any warnings. +.TP +\f[CR]--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[CR]--verbose\f[R], \f[CR]--quiet\f[R]). +.TP +\f[CR]--list-input-formats\f[R] +List supported input formats, one per line. +.TP +\f[CR]--list-output-formats\f[R] +List supported output formats, one per line. +.TP +\f[CR]--list-extensions\f[R][\f[CR]=\f[R]\f[I]FORMAT\f[R]] +List supported extensions for \f[I]FORMAT\f[R], one per line, preceded +by a \f[CR]+\f[R] or \f[CR]-\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[CR]--list-highlight-languages\f[R] +List supported languages for syntax highlighting, one per line. +.TP +\f[CR]--list-highlight-styles\f[R] +List supported styles for syntax highlighting, one per line. +See \f[CR]--highlight-style\f[R]. +.TP +\f[CR]-v\f[R], \f[CR]--version\f[R] +Print version. +.TP +\f[CR]-h\f[R], \f[CR]--help\f[R] +Show usage message. +.SS Reader options +.TP +\f[CR]--shift-heading-level-by=\f[R]\f[I]NUMBER\f[R] +Shift heading levels by a positive or negative integer. +For example, with \f[CR]--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[CR]--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[CR]--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[CR]--base-header-level=\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[CR]--indented-code-classes=\f[R]\f[I]CLASSES\f[R] +Specify classes to use for indented code blocks\[en]for example, +\f[CR]perl,numberLines\f[R] or \f[CR]haskell\f[R]. +Multiple classes may be separated by spaces or commas. +.TP +\f[CR]--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[CR]--file-scope[=true|false]\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[CR]--file-scope\f[R]. +.RS +.PP +If two or more files are processed using \f[CR]--file-scope\f[R], +prefixes based on the filenames will be added to identifiers in order to +disambiguate them, and internal links will be adjusted accordingly. +For example, a header with identifier \f[CR]foo\f[R] in +\f[CR]subdir/file1.txt\f[R] will have its identifier changed to +\f[CR]subdir__file1.txt__foo\f[R]. +.PP +In addition, a Div with an identifier based on the filename will be +added around the file\[cq]s content, so that internal links to the +filename will point to this Div\[cq]s identifier. +.RE +.TP +\f[CR]-F\f[R] \f[I]PROGRAM\f[R], \f[CR]--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 +.EX +pandoc --filter ./caps.py -t latex +.EE +.PP +is equivalent to +.IP +.EX +pandoc -t json | ./caps.py latex | pandoc -f json -t latex +.EE +.PP +The latter form may be useful for debugging filters. +.PP +Filters may be written in any language. +\f[CR]Text.Pandoc.JSON\f[R] exports \f[CR]toJSONFilter\f[R] to +facilitate writing filters in Haskell. +Those who would prefer to write filters in python can use the module +\f[CR]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[CR]$DATADIR/filters\f[R] (executable or non-executable) where +\f[CR]$DATADIR\f[R] is the user data directory (see +\f[CR]--data-dir\f[R], above), +.IP "3." 3 +\f[CR]$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[CR]-L\f[R] \f[I]SCRIPT\f[R], \f[CR]--lua-filter=\f[R]\f[I]SCRIPT\f[R] +Transform the document in a similar fashion as JSON filters (see +\f[CR]--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[CR]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[CR]$DATADIR/filters\f[R] where \f[CR]$DATADIR\f[R] is the user data +directory (see \f[CR]--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[CR]-M\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]--metadata=\f[R]\f[I]KEY\f[R][\f[CR]:\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[CR]--variable\f[R], \f[CR]--metadata\f[R] causes template +variables to be set. +But unlike \f[CR]--variable\f[R], \f[CR]--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[CR]--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 metadata file will always be parsed as Markdown. +(If the input format is Markdown or a Markdown variant, then the same +variant will be used to parse the metadata file; if it is a non-Markdown +format, pandoc\[cq]s default Markdown extensions will be used.) +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[CR]-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[CR]metadata\f[R] subdirectory of the user data directory (see +\f[CR]--data-dir\f[R]). +.TP +\f[CR]-p\f[R], \f[CR]--preserve-tabs[=true|false]\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[CR]--tab-stop=\f[R]\f[I]NUMBER\f[R] +Specify the number of spaces per tab (default is 4). +.TP +\f[CR]--track-changes=accept\f[R]|\f[CR]reject\f[R]|\f[CR]all\f[R] +Specifies what to do with insertions, deletions, and comments produced +by the MS Word \[lq]Track Changes\[rq] feature. +\f[CR]accept\f[R] (the default) processes all the insertions and +deletions. +\f[CR]reject\f[R] ignores them. +Both \f[CR]accept\f[R] and \f[CR]reject\f[R] ignore comments. +\f[CR]all\f[R] includes all insertions, deletions, and comments, wrapped +in spans with \f[CR]insertion\f[R], \f[CR]deletion\f[R], +\f[CR]comment-start\f[R], and \f[CR]comment-end\f[R] classes, +respectively. +The author and time of change is included. +\f[CR]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[CR]track-changes=all\f[R] +produces a span with the class +\f[CR]paragraph-insertion\f[R]/\f[CR]paragraph-deletion\f[R] before the +affected paragraph break. +This option only affects the docx reader. +.TP +\f[CR]--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[CR]..\f[R]. +Otherwise filenames are constructed from the SHA1 hash of the contents. +.TP +\f[CR]--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[CR]abbreviations\f[R] from the user data directory or fall back on a +system default. +To see the system default, use +\f[CR]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[CR]--trace[=true|false]\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[CR]-s\f[R], \f[CR]--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[CR]pdf\f[R], \f[CR]epub\f[R], +\f[CR]epub3\f[R], \f[CR]fb2\f[R], \f[CR]docx\f[R], and \f[CR]odt\f[R] +output. +For \f[CR]native\f[R] output, this option causes metadata to be +included; otherwise, metadata is suppressed. +.TP +\f[CR]--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[CR]--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[CR]--template=special\f[R] looks for +\f[CR]special.html\f[R] for HTML output. +If the template is not found, pandoc will search for it in the +\f[CR]templates\f[R] subdirectory of the user data directory (see +\f[CR]--data-dir\f[R]). +If this option is not used, a default template appropriate for the +output format will be used (see \f[CR]-D/--print-default-template\f[R]). +.TP +\f[CR]-V\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]--variable=\f[R]\f[I]KEY\f[R][\f[CR]:\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[CR]true\f[R]. +.TP +\f[CR]--sandbox[=true|false]\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[CR]include\f[R] directives. +Anyone using pandoc on untrusted user input should use this option. +.RS +.PP +Note: some readers and writers (e.g., \f[CR]docx\f[R]) need access to +data files. +If these are stored on the file system, then pandoc will not be able to +find them when run in \f[CR]--sandbox\f[R] mode and will raise an error. +For these applications, we recommend using a pandoc binary compiled with +the \f[CR]embed_data_files\f[R] option, which causes the data files to +be baked into the binary instead of being stored on the file system. +.RE +.TP +\f[CR]-D\f[R] \f[I]FORMAT\f[R], \f[CR]--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[CR]-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[CR]-o\f[R]/\f[CR]--output\f[R] to +redirect output to a file, but \f[CR]-o\f[R]/\f[CR]--output\f[R] must +come before \f[CR]--print-default-template\f[R] on the command line. +.RS +.PP +Note that some of the default templates use partials, for example +\f[CR]styles.html\f[R]. +To print the partials, use \f[CR]--print-default-data-file\f[R]: for +example, \f[CR]--print-default-data-file=templates/styles.html\f[R]. +.RE +.TP +\f[CR]--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[CR]-o\f[R]/\f[CR]--output\f[R] to +redirect output to a file, but \f[CR]-o\f[R]/\f[CR]--output\f[R] must +come before \f[CR]--print-default-data-file\f[R] on the command line. +.TP +\f[CR]--eol=crlf\f[R]|\f[CR]lf\f[R]|\f[CR]native\f[R] +Manually specify line endings: \f[CR]crlf\f[R] (Windows), \f[CR]lf\f[R] +(macOS/Linux/UNIX), or \f[CR]native\f[R] (line endings appropriate to +the OS on which pandoc is being run). +The default is \f[CR]native\f[R]. +.TP +\f[CR]--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[CR]--wrap=auto\f[R]|\f[CR]none\f[R]|\f[CR]preserve\f[R] +Determine how text is wrapped in the output (the source code, not the +rendered version). +With \f[CR]auto\f[R] (the default), pandoc will attempt to wrap lines to +the column width specified by \f[CR]--columns\f[R] (default 72). +With \f[CR]none\f[R], pandoc will not wrap lines at all. +With \f[CR]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[CR]ipynb\f[R] output, this option affects wrapping of the contents +of markdown cells. +.TP +\f[CR]--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[CR]--wrap\f[R]). +It also affects calculation of column widths for plain text tables (see +Tables below). +.TP +\f[CR]--toc[=true|false]\f[R], \f[CR]--table-of-contents[=true|false]\f[R] +Include an automatically generated table of contents (or, in the case of +\f[CR]latex\f[R], \f[CR]context\f[R], \f[CR]docx\f[R], \f[CR]odt\f[R], +\f[CR]opendocument\f[R], \f[CR]rst\f[R], or \f[CR]ms\f[R], an +instruction to create one) in the output document. +This option has no effect unless \f[CR]-s/--standalone\f[R] is used, and +it has no effect on \f[CR]man\f[R], \f[CR]docbook4\f[R], +\f[CR]docbook5\f[R], or \f[CR]jats\f[R] output. +.RS +.PP +Note that if you are producing a PDF via \f[CR]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[CR]--pdf-engine-opt=--no-toc-relocation\f[R]. +.RE +.TP +\f[CR]--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[CR]--strip-comments[=true|false]\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[CR]markdown_in_html_blocks\f[R] extension is not set. +.TP +\f[CR]--no-highlight\f[R] +Disables syntax highlighting for code blocks and inlines, even when a +language attribute is given. +.TP +\f[CR]--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[CR]pygments\f[R] (the default), \f[CR]kate\f[R], +\f[CR]monochrome\f[R], \f[CR]breezeDark\f[R], \f[CR]espresso\f[R], +\f[CR]zenburn\f[R], \f[CR]haddock\f[R], and \f[CR]tango\f[R]. +For more information on syntax highlighting in pandoc, see Syntax +highlighting, below. +See also \f[CR]--list-highlight-styles\f[R]. +.RS +.PP +Instead of a \f[I]STYLE\f[R] name, a JSON file with extension +\f[CR].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[CR]--print-highlight-style\f[R]. +.RE +.TP +\f[CR]--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[CR].theme\f[R] extension, and used with +\f[CR]--highlight-style\f[R]. +This option may be used with \f[CR]-o\f[R]/\f[CR]--output\f[R] to +redirect output to a file, but \f[CR]-o\f[R]/\f[CR]--output\f[R] must +come before \f[CR]--print-highlight-style\f[R] on the command line. +.TP +\f[CR]--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[CR]-H\f[R] \f[I]FILE\f[R], \f[CR]--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[CR]--standalone\f[R]. +.TP +\f[CR]-B\f[R] \f[I]FILE\f[R], \f[CR]--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[CR]\f[R] tag in HTML, or the +\f[CR]\[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[CR]--standalone\f[R]. +.TP +\f[CR]-A\f[R] \f[I]FILE\f[R], \f[CR]--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[CR]\f[R] tag in HTML, or the +\f[CR]\[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[CR]--standalone\f[R]. +.TP +\f[CR]--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[CR]:\f[R] on Linux, UNIX, and macOS +systems, and by \f[CR];\f[R] on Windows. +If \f[CR]--resource-path\f[R] is not specified, the default resource +path is the working directory. +Note that, if \f[CR]--resource-path\f[R] is specified, the working +directory must be explicitly listed or it will not be searched. +For example: \f[CR]--resource-path=.:test\f[R] will search the working +directory and the \f[CR]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[CR]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent +to \f[CR]--resource-path baz:bim:foo:bar\f[R]. +.TP +\f[CR]--request-header=\f[R]\f[I]NAME\f[R]\f[CR]:\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[CR]http_proxy\f[R] to \f[CR]http://...\f[R]. +.TP +\f[CR]--no-check-certificate[=true|false]\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[CR]--self-contained[=true|false]\f[R] +\f[I]Deprecated synonym for +\f[CI]--embed-resources --standalone\f[I].\f[R] +.TP +\f[CR]--embed-resources[=true|false]\f[R] +Produce a standalone HTML file with no external dependencies, using +\f[CR]data:\f[R] URIs to incorporate the contents of linked scripts, +stylesheets, images, and videos. +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[CR]html4\f[R], \f[CR]html5\f[R], \f[CR]html+lhs\f[R], +\f[CR]html5+lhs\f[R], \f[CR]s5\f[R], \f[CR]slidy\f[R], +\f[CR]slideous\f[R], \f[CR]dzslides\f[R], and \f[CR]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[CR]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, fonts may be missing when +\f[CR]--mathjax\f[R] is used, and some advanced features (e.g.\ zoom or +speaker notes) may not work in an offline \[lq]self-contained\[rq] +\f[CR]reveal.js\f[R] slide show. +.TP +\f[CR]--html-q-tags[=true|false]\f[R] +Use \f[CR]\f[R] tags for quotes in HTML. +(This option only has an effect if the \f[CR]smart\f[R] extension is +enabled for the input format used.) +.TP +\f[CR]--ascii[=true|false]\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 man and ms (which use hexadecimal escapes), +and to a limited degree LaTeX (which uses standard commands for accented +characters when possible). +.TP +\f[CR]--reference-links[=true|false]\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[CR]--reference-location\f[R] option. +.TP +\f[CR]--reference-location=block\f[R]|\f[CR]section\f[R]|\f[CR]document\f[R] +Specify whether footnotes (and references, if \f[CR]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[CR]document\f[R]. +Currently this option only affects the \f[CR]markdown\f[R], +\f[CR]muse\f[R], \f[CR]html\f[R], \f[CR]epub\f[R], \f[CR]slidy\f[R], +\f[CR]s5\f[R], \f[CR]slideous\f[R], \f[CR]dzslides\f[R], and +\f[CR]revealjs\f[R] writers. +In slide formats, specifying \f[CR]--reference-location=section\f[R] +will cause notes to be rendered at the bottom of a slide. +.TP +\f[CR]--markdown-headings=setext\f[R]|\f[CR]atx\f[R] +Specify whether to use ATX-style (\f[CR]#\f[R]-prefixed) or Setext-style +(underlined) headings for level 1 and 2 headings in Markdown output. +(The default is \f[CR]atx\f[R].) +ATX-style headings are always used for levels 3+. +This option also affects Markdown cells in \f[CR]ipynb\f[R] output. +.TP +\f[CR]--list-tables[=true|false]\f[R] +Render tables as list tables in RST output. +.TP +\f[CR]--top-level-division=default\f[R]|\f[CR]section\f[R]|\f[CR]chapter\f[R]|\f[CR]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[CR]section\f[R] is chosen. +When the \f[CR]documentclass\f[R] variable is set to \f[CR]report\f[R], +\f[CR]book\f[R], or \f[CR]memoir\f[R] (unless the \f[CR]article\f[R] +option is specified), \f[CR]chapter\f[R] is implied as the setting for +this option. +If \f[CR]beamer\f[R] is the output format, specifying either +\f[CR]chapter\f[R] or \f[CR]part\f[R] will cause top-level headings to +become \f[CR]\[rs]part{..}\f[R], while second-level headings remain as +their default type. +.TP +\f[CR]-N\f[R], \f[CR]--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[CR]unnumbered\f[R] will never be numbered, even +if \f[CR]--number-sections\f[R] is specified. +.TP +\f[CR]--number-offset=\f[R]\f[I]NUMBER\f[R][\f[CR],\f[R]\f[I]NUMBER\f[R]\f[CR],\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[CR]--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[CR]--number-offset=1,4\f[R]. +Offsets are 0 by default. +Implies \f[CR]--number-sections\f[R]. +.TP +\f[CR]--listings[=true|false]\f[R] +Use the \f[CR]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[CR]-i\f[R], \f[CR]--incremental[=true|false]\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[CR]--slide-level=\f[R]\f[I]NUMBER\f[R] +Specifies that headings with the specified level create slides (for +\f[CR]beamer\f[R], \f[CR]s5\f[R], \f[CR]slidy\f[R], \f[CR]slideous\f[R], +\f[CR]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[CR]--section-divs[=true|false]\f[R] +Wrap sections in \f[CR]
\f[R] tags (or \f[CR]
\f[R] tags for +\f[CR]html4\f[R]), and attach identifiers to the enclosing +\f[CR]
\f[R] (or \f[CR]
\f[R]) rather than the heading +itself (see Heading identifiers, below). +This option only affects HTML output (and does not affect HTML slide +formats). +.TP +\f[CR]--email-obfuscation=none\f[R]|\f[CR]javascript\f[R]|\f[CR]references\f[R] +Specify a method for obfuscating \f[CR]mailto:\f[R] links in HTML +documents. +\f[CR]none\f[R] leaves \f[CR]mailto:\f[R] links as they are. +\f[CR]javascript\f[R] obfuscates them using JavaScript. +\f[CR]references\f[R] obfuscates them by printing their letters as +decimal or hexadecimal character references. +The default is \f[CR]none\f[R]. +.TP +\f[CR]--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[CR]-T\f[R] \f[I]STRING\f[R], \f[CR]--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[CR]--standalone\f[R]. +.TP +\f[CR]-c\f[R] \f[I]URL\f[R], \f[CR]--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. +This option only affects HTML (including HTML slide shows) and EPUB +output. +It should be used together with \f[CR]-s/--standalone\f[R], because the +link to the stylesheet goes in the document header. +.RS +.PP +A stylesheet is required for generating EPUB. +If none is provided using this option (or the \f[CR]css\f[R] or +\f[CR]stylesheet\f[R] metadata fields), pandoc will look for a file +\f[CR]epub.css\f[R] in the user data directory (see +\f[CR]--data-dir\f[R]). +If it is not found there, sensible defaults will be used. +.RE +.TP +\f[CR]--reference-doc=\f[R]\f[I]FILE\f[R]|\f[I]URL\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[CR]reference.docx\f[R] in the user data directory (see +\f[CR]--data-dir\f[R]). +If this is not found either, sensible defaults will be used. +.RS +.PP +To produce a custom \f[CR]reference.docx\f[R], first get a copy of the +default \f[CR]reference.docx\f[R]: +\f[CR]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R]. +Then open \f[CR]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 +AbstractTitle +.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 +Source Code +.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[CR]reference.odt\f[R] in the user data directory (see +\f[CR]--data-dir\f[R]). +If this is not found either, sensible defaults will be used. +.RS +.PP +To produce a custom \f[CR]reference.odt\f[R], first get a copy of the +default \f[CR]reference.odt\f[R]: +\f[CR]pandoc -o custom-reference.odt --print-default-data-file reference.odt\f[R]. +Then open \f[CR]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[CR].pptx\f[R] or \f[CR].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[CR]Layout\f[R] under the \f[CR]Home\f[R] menu to +check.) +.PP +You can also modify the default \f[CR]reference.pptx\f[R]: first run +\f[CR]pandoc -o custom-reference.pptx --print-default-data-file reference.pptx\f[R], +and then modify \f[CR]custom-reference.pptx\f[R] in MS PowerPoint +(pandoc will use the layouts with the names listed above). +.RE +.RE +.TP +\f[CR]--split-level=\f[R]\f[I]NUMBER\f[R] +Specify the heading level at which to split an EPUB or chunked HTML +document into separate files. +The default is to split into chapters at level-1 headings. +In the case of EPUB, 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. +For chunked HTML, this option determines how much content goes in each +\[lq]chunk.\[rq] +.TP +\f[CR]--chunk-template=\f[R]\f[I]PATHTEMPLATE\f[R] +Specify a template for the filenames in a \f[CR]chunkedhtml\f[R] +document. +In the template, \f[CR]%n\f[R] will be replaced by the chunk number +(padded with leading 0s to 3 digits), \f[CR]%s\f[R] with the section +number of the chunk, \f[CR]%h\f[R] with the heading text (with +formatting removed), \f[CR]%i\f[R] with the section identifier. +For example, \f[CR]%section-%s-%i.html\f[R] might be resolved to +\f[CR]section-1.1-introduction.html\f[R]. +The characters \f[CR]/\f[R] and \f[CR]\[rs]\f[R] are not allowed in +chunk templates and will be ignored. +The default is \f[CR]%s-%i.html\f[R]. +.TP +\f[CR]--epub-chapter-level=\f[R]\f[I]NUMBER\f[R] +\f[I]Deprecated synonym for \f[CI]--split-level\f[I].\f[R] +.TP +\f[CR]--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[CR]cover-image\f[R] in a YAML metadata block (see EPUB Metadata, +below). +.TP +\f[CR]--epub-title-page=true\f[R]|\f[CR]false\f[R] +Determines whether a the title page is included in the EPUB (default is +\f[CR]true\f[R]). +.TP +\f[CR]--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 +.EX + Creative Commons + es-AR +.EE +.PP +By default, pandoc will include the following metadata elements: +\f[CR]\f[R] (from the document title), \f[CR]\f[R] +(from the document authors), \f[CR]\f[R] (from the document +date, which should be in ISO 8601 format), \f[CR]\f[R] +(from the \f[CR]lang\f[R] variable, or, if is not set, the locale), and +\f[CR]\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[CR]--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[CR]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[CR]--css\f[R]): +.RS +.IP +.EX +\[at]font-face { + font-family: DejaVuSans; + font-style: normal; + font-weight: normal; + src:url(\[dq]../fonts/DejaVuSans-Regular.ttf\[dq]); +} +\[at]font-face { + font-family: DejaVuSans; + font-style: normal; + font-weight: bold; + src:url(\[dq]../fonts/DejaVuSans-Bold.ttf\[dq]); +} +\[at]font-face { + font-family: DejaVuSans; + font-style: italic; + font-weight: normal; + src:url(\[dq]../fonts/DejaVuSans-Oblique.ttf\[dq]); +} +\[at]font-face { + font-family: DejaVuSans; + font-style: italic; + font-weight: bold; + src:url(\[dq]../fonts/DejaVuSans-BoldOblique.ttf\[dq]); +} +body { font-family: \[dq]DejaVuSans\[dq]; } +.EE +.RE +.TP +\f[CR]--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[CR]EPUB\f[R]. +To put the EPUB contents in the top level, use an empty string. +.TP +\f[CR]--ipynb-output=all|none|best\f[R] +Determines how ipynb output cells are treated. +\f[CR]all\f[R] means that all of the data formats included in the +original are preserved. +\f[CR]none\f[R] means that the contents of data cells are omitted. +\f[CR]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[CR]best\f[R]. +.TP +\f[CR]--pdf-engine=\f[R]\f[I]PROGRAM\f[R] +Use the specified engine when producing PDF output. +Valid values are \f[CR]pdflatex\f[R], \f[CR]lualatex\f[R], +\f[CR]xelatex\f[R], \f[CR]latexmk\f[R], \f[CR]tectonic\f[R], +\f[CR]wkhtmltopdf\f[R], \f[CR]weasyprint\f[R], \f[CR]pagedjs-cli\f[R], +\f[CR]prince\f[R], \f[CR]context\f[R], \f[CR]pdfroff\f[R], and +\f[CR]typst\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[CR]-t/--to\f[R]: +.RS +.IP \[bu] 2 +\f[CR]-t latex\f[R] or none: \f[CR]pdflatex\f[R] (other options: +\f[CR]xelatex\f[R], \f[CR]lualatex\f[R], \f[CR]tectonic\f[R], +\f[CR]latexmk\f[R]) +.IP \[bu] 2 +\f[CR]-t context\f[R]: \f[CR]context\f[R] +.IP \[bu] 2 +\f[CR]-t html\f[R]: \f[CR]wkhtmltopdf\f[R] (other options: +\f[CR]prince\f[R], \f[CR]weasyprint\f[R], \f[CR]pagedjs-cli\f[R]; see +print-css.rocks for a good introduction to PDF generation from HTML/CSS) +.IP \[bu] 2 +\f[CR]-t ms\f[R]: \f[CR]pdfroff\f[R] +.IP \[bu] 2 +\f[CR]-t typst\f[R]: \f[CR]typst\f[R] +.RE +.TP +\f[CR]--pdf-engine-opt=\f[R]\f[I]STRING\f[R] +Use the given string as a command-line argument to the +\f[CR]pdf-engine\f[R]. +For example, to use a persistent directory \f[CR]foo\f[R] for +\f[CR]latexmk\f[R]\[cq]s auxiliary files, use +\f[CR]--pdf-engine-opt=-outdir=foo\f[R]. +Note that no check for duplicate options is done. +.SS Citation rendering +.TP +\f[CR]-C\f[R], \f[CR]--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[CR]--bibliography\f[R] option or the \f[CR]bibliography\f[R] field in +metadata, or via a \f[CR]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[CR]--csl\f[R] option or the \f[CR]csl\f[R] field in metadata. +(If no stylesheet is specified, the \f[CR]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[CR]--filter\f[R], +\f[CR]--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[CR]--bibliography=\f[R]\f[I]FILE\f[R] +Set the \f[CR]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[CR]--resource-path\f[R]). +.TP +\f[CR]--csl=\f[R]\f[I]FILE\f[R] +Set the \f[CR]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[CR]--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[CR]--resource-path\f[R]) and +finally in the \f[CR]csl\f[R] subdirectory of the pandoc user data +directory. +.TP +\f[CR]--citation-abbreviations=\f[R]\f[I]FILE\f[R] +Set the \f[CR]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[CR]--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[CR]--resource-path\f[R]) and +finally in the \f[CR]csl\f[R] subdirectory of the pandoc user data +directory. +.TP +\f[CR]--natbib\f[R] +Use \f[CR]natbib\f[R] for citations in LaTeX output. +This option is not for use with the \f[CR]--citeproc\f[R] option or with +PDF output. +It is intended for use in producing a LaTeX file that can be processed +with \f[CR]bibtex\f[R]. +.TP +\f[CR]--biblatex\f[R] +Use \f[CR]biblatex\f[R] for citations in LaTeX output. +This option is not for use with the \f[CR]--citeproc\f[R] option or with +PDF output. +It is intended for use in producing a LaTeX file that can be processed +with \f[CR]bibtex\f[R] or \f[CR]biber\f[R]. +.SS Math rendering in HTML +The default is to render TeX math as far as possible using Unicode +characters. +Formulas are put inside a \f[CR]span\f[R] with +\f[CR]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[CR]--mathjax\f[R] or another of the following +options. +.TP +\f[CR]--mathjax\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +Use MathJax to display embedded TeX math in HTML output. +TeX math will be put between \f[CR]\[rs](...\[rs])\f[R] (for inline +math) or \f[CR]\[rs][...\[rs]]\f[R] (for display math) and wrapped in +\f[CR]\f[R] tags with class \f[CR]math\f[R]. +Then the MathJax JavaScript will render it. +The \f[I]URL\f[R] should point to the \f[CR]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[CR]--mathml\f[R] +Convert TeX math to MathML (in \f[CR]epub3\f[R], \f[CR]docbook4\f[R], +\f[CR]docbook5\f[R], \f[CR]jats\f[R], \f[CR]html4\f[R] and +\f[CR]html5\f[R]). +This is the default in \f[CR]odt\f[R] output. +MathML is supported natively by the main web browsers and select e-book +readers. +.TP +\f[CR]--webtex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +Convert TeX formulas to \f[CR]\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[CR]--webtex https://latex.codecogs.com/svg.latex?\f[R]. +If no URL is specified, the CodeCogs URL generating PNGs will be used +(\f[CR]https://latex.codecogs.com/png.latex?\f[R]). +Note: the \f[CR]--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[CR]--katex\f[R][\f[CR]=\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[CR]katex.min.js\f[R] and a +\f[CR]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[CR]--gladtex\f[R] +Enclose TeX math in \f[CR]\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 +.EX +pandoc -s --gladtex input.md -o myfile.htex +gladtex -d image_dir myfile.htex +# produces myfile.html and images in image_dir +.EE +.RE +.SS Options for wrapper scripts +.TP +\f[CR]--dump-args[=true|false]\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[CR]-o\f[R] option, or \f[CR]-\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[CR]--\f[R] separator at the end +of the line. +.TP +\f[CR]--ignore-args[=true|false]\f[R] +Ignore command-line arguments (for use in wrapper scripts). +Regular pandoc options are not ignored. +Thus, for example, +.RS +.IP +.EX +pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1 +.EE +.PP +is equivalent to +.IP +.EX +pandoc -o foo.html -s +.EE +.RE +.SH EXIT CODES +If pandoc completes successfully, it will return exit code 0. +Nonzero exit codes have the following meanings: +.RS -14n +.IP +.EX + Code Error + ------ ------------------------------------- + 1 PandocIOError + 3 PandocFailOnWarningError + 4 PandocAppError + 5 PandocTemplateError + 6 PandocOptionError + 21 PandocUnknownReaderError + 22 PandocUnknownWriterError + 23 PandocUnsupportedExtensionError + 24 PandocCiteprocError + 25 PandocBibliographyError + 31 PandocEpubSubdirectoryError + 43 PandocPDFError + 44 PandocXMLError + 47 PandocPDFProgramNotFoundError + 61 PandocHttpError + 62 PandocShouldNeverHappenError + 63 PandocSomeError + 64 PandocParseError + 66 PandocMakePDFError + 67 PandocSyntaxMapError + 83 PandocFilterError + 84 PandocLuaError + 89 PandocNoScriptingEngine + 91 PandocMacroLoop + 92 PandocUTF8DecodingError + 93 PandocIpynbDecodingError + 94 PandocUnsupportedCharsetError + 97 PandocCouldNotFindDataFileError + 98 PandocCouldNotFindMetadataFileError + 99 PandocResourceNotFound +.EE +.RE +.SH DEFAULTS FILES +The \f[CR]--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 +.EX +verbosity: INFO +.EE +.PP +In fields that expect a file path (or list of file paths), the following +syntax may be used to interpolate environment variables: +.IP +.EX +csl: ${HOME}/mycsldir/special.csl +.EE +.PP +\f[CR]${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[CR]USERDATA\f[R]. +.PP +\f[CR]${.}\f[R] will resolve to the directory containing the defaults +file itself. +This allows you to refer to resources contained in that directory: +.IP +.EX +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 +.EE +.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[CR]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[CR]letter.yaml\f[R] in the \f[CR]defaults\f[R] +subdirectory of the user data directory, and then invoke these defaults +from any directory using \f[CR]pandoc --defaults letter\f[R] or +\f[CR]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[CR]--metadata-file\f[R], \f[CR]--css\f[R], +\f[CR]--include-in-header\f[R], \f[CR]--include-before-body\f[R], +\f[CR]--include-after-body\f[R], \f[CR]--variable\f[R], +\f[CR]--metadata\f[R], \f[CR]--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. +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + foo.md input-file: foo.md + + foo.md bar.md input-files: + - foo.md + - bar.md + +.EE +.RE +.PP +The value of \f[CR]input-files\f[R] may be left empty to indicate input +from stdin, and it can be an empty sequence \f[CR][]\f[R] for no input. +.SS General options +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --from markdown+emoji from: markdown+emoji + + reader: markdown+emoji + + to: markdown+hard_line_breaks + --to markdown+hard_line_breaks + + writer: markdown+hard_line_breaks + + --output foo.pdf output-file: foo.pdf + + --output - output-file: + + --data-dir dir data-dir: dir + + --defaults file defaults: + - file + + --verbose verbosity: INFO + + --quiet verbosity: ERROR + + --fail-if-warnings fail-if-warnings: true + + --sandbox sandbox: true + + --log=FILE log-file: FILE + +.EE +.RE +.PP +Options specified in a defaults file itself always have priority over +those in another file included with a \f[CR]defaults:\f[R] entry. +.PP +\f[CR]verbosity\f[R] can have the values \f[CR]ERROR\f[R], +\f[CR]WARNING\f[R], or \f[CR]INFO\f[R]. +.SS Reader options +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --shift-heading-level-by -1 shift-heading-level-by: -1 + + indented-code-classes: + --indented-code-classes python - python + + + --default-image-extension \[dq].jpg\[dq] default-image-extension: \[aq].jpg\[aq] + + --file-scope file-scope: true + + --filter pandoc-citeproc \[rs] filters: + - pandoc-citeproc + --lua-filter count-words.lua \[rs] - count-words.lua + --filter special.lua - type: json + path: special.lua + + --metadata key=value \[rs] metadata: + --metadata key2 key: value + key2: true + + --metadata-file meta.yaml metadata-files: + - meta.yaml + + metadata-file: meta.yaml + + --preserve-tabs preserve-tabs: true + + --tab-stop 8 tab-stop: 8 + + --track-changes accept track-changes: accept + + --extract-media dir extract-media: dir + + --abbreviations abbrevs.txt abbreviations: abbrevs.txt + + --trace trace: true + +.EE +.RE +.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[CR].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[CR]citeproc\f[R] +or \f[CR]{type: citeproc}\f[R]. +.SS General writer options +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --standalone standalone: true + + --template letter template: letter + + --variable key=val \[rs] variables: + --variable key2 key: val + key2: true + + --eol nl eol: nl + + --dpi 300 dpi: 300 + + --wrap 60 wrap: 60 + + --columns 72 columns: 72 + + --table-of-contents table-of-contents: true + + --toc toc: true + + --toc-depth 3 toc-depth: 3 + + --strip-comments strip-comments: true + + --no-highlight highlight-style: null + + --highlight-style kate highlight-style: kate + + syntax-definitions: + --syntax-definition mylang.xml - mylang.xml + + syntax-definition: mylang.xml + + --include-in-header inc.tex include-in-header: + - inc.tex + + include-before-body: +--include-before-body inc.tex - inc.tex + + --include-after-body inc.tex include-after-body: + - inc.tex + + --resource-path .:foo resource-path: [\[aq].\[aq],\[aq]foo\[aq]] + + --request-header foo:bar request-headers: + + - [\[dq]User-Agent\[dq], \[dq]Mozilla/5.0\[dq]] + + --no-check-certificate no-check-certificate: true + +.EE +.RE +.SS Options affecting specific writers +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --self-contained self-contained: true + + --html-q-tags html-q-tags: true + + --ascii ascii: true + + --reference-links reference-links: true + + --reference-location block reference-location: block + + --markdown-headings atx markdown-headings: atx + + --list-tables list-tables: true + + --top-level-division chapter top-level-division: chapter + + --number-sections number-sections: true + + --number-offset=1,4 number-offset: \[rs][1,4\[rs]] + + --listings listings: true + + --incremental incremental: true + + --slide-level 2 slide-level: 2 + + --section-divs section-divs: true + + email-obfuscation: references + --email-obfuscation references + + --id-prefix ch1 identifier-prefix: ch1 + + --title-prefix MySite title-prefix: MySite + + --css styles/screen.css \[rs] css: + --css styles/special.css - styles/screen.css + - styles/special.css + + --reference-doc my.docx reference-doc: my.docx + + --epub-cover-image cover.jpg epub-cover-image: cover.jpg + + --epub-title-page=false epub-title-page: false + + --epub-metadata meta.xml epub-metadata: meta.xml + + epub-fonts: + --epub-embed-font special.otf \[rs] - special.otf + - headline.otf + --epub-embed-font headline.otf + + --split-level 2 split-level: 2 + + --chunk-template=\[dq]%i.html\[dq] chunk-template: \[dq]%i.html\[dq] + + --epub-subdirectory=\[dq]\[dq] epub-subdirectory: \[aq]\[aq] + + --ipynb-output best ipynb-output: best + + --pdf-engine xelatex pdf-engine: xelatex + + pdf-engine-opts: + --pdf-engine-opt=--shell-escape - \[aq]-shell-escape\[aq] + + + pdf-engine-opt: \[aq]-shell-escape\[aq] + +.EE +.RE +.SS Citation rendering +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --citeproc citeproc: true + + --bibliography logic.bib metadata: + bibliography: logic.bib + + --csl ieee.csl metadata: + csl: ieee.csl + + metadata: + --citation-abbreviations ab.json + citation-abbreviations: ab.json + + --natbib cite-method: natbib + + --biblatex cite-method: biblatex + +.EE +.RE +.PP +\f[CR]cite-method\f[R] can be \f[CR]citeproc\f[R], \f[CR]natbib\f[R], or +\f[CR]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[CR]citeproc\f[R] in the list +of \f[CR]filters\f[R] (see above). +.SS Math rendering in HTML +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --mathjax html-math-method: + method: mathjax + + --mathml html-math-method: + method: mathml + + --webtex html-math-method: + method: webtex + + --katex html-math-method: + method: katex + + --gladtex html-math-method: + method: gladtex + +.EE +.RE +.PP +In addition to the values listed above, \f[CR]method\f[R] can have the +value \f[CR]plain\f[R]. +.PP +If the command line option accepts a URL argument, an \f[CR]url:\f[R] +field can be added to \f[CR]html-math-method:\f[R]. +.SS Options for wrapper scripts +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --dump-args dump-args: true + + --ignore-args ignore-args: true + +.EE +.RE +.SH TEMPLATES +When the \f[CR]-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 +.EX +pandoc -D *FORMAT* +.EE +.PP +where \f[I]FORMAT\f[R] is the name of the output format. +A custom template can be specified using the \f[CR]--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[CR]templates/default.*FORMAT*\f[R] in the user data directory (see +\f[CR]--data-dir\f[R], above). +\f[I]Exceptions:\f[R] +.IP \[bu] 2 +For \f[CR]odt\f[R] output, customize the \f[CR]default.opendocument\f[R] +template. +.IP \[bu] 2 +For \f[CR]pdf\f[R] output, customize the \f[CR]default.latex\f[R] +template (or the \f[CR]default.context\f[R] template, if you use +\f[CR]-t context\f[R], or the \f[CR]default.ms\f[R] template, if you use +\f[CR]-t ms\f[R], or the \f[CR]default.html\f[R] template, if you use +\f[CR]-t html\f[R]). +.IP \[bu] 2 +\f[CR]docx\f[R] and \f[CR]pptx\f[R] have no template (however, you can +use \f[CR]--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[CR]-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[CR]-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 +Anything between the sequence \f[CR]$--\f[R] and the end of the line +will be treated as a comment and omitted from the output. +.SS Delimiters +To mark variables and control structures in the template, either +\f[CR]$\f[R]\&...\f[CR]$\f[R] or \f[CR]${\f[R]\&...\f[CR]}\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 preceded by one or more spaces or tabs, +which will be ignored. +.PP +To include a literal \f[CR]$\f[R] in the document, use \f[CR]$$\f[R]. +.SS Interpolated variables +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[CR]_\f[R], \f[CR]-\f[R], and \f[CR].\f[R]. +The keywords \f[CR]it\f[R], \f[CR]if\f[R], \f[CR]else\f[R], +\f[CR]endif\f[R], \f[CR]for\f[R], \f[CR]sep\f[R], and \f[CR]endfor\f[R] +may not be used as variable names. +Examples: +.IP +.EX +$foo$ +$foo.bar.baz$ +$foo_bar.baz-bim$ +$ foo $ +${foo} +${foo.bar.baz} +${foo_bar.baz-bim} +${ foo } +.EE +.PP +Variable names with periods are used to get at structured variable +values. +So, for example, \f[CR]employee.salary\f[R] will return the value of the +\f[CR]salary\f[R] field of the object that is the value of the +\f[CR]employee\f[R] field. +.IP \[bu] 2 +If the value of the variable is a 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[CR]true\f[R] will be rendered. +.IP \[bu] 2 +Every other value will be rendered as the empty string. +.SS Conditionals +A conditional begins with \f[CR]if(variable)\f[R] (enclosed in matched +delimiters) and ends with \f[CR]endif\f[R] (enclosed in matched +delimiters). +It may optionally contain an \f[CR]else\f[R] (enclosed in matched +delimiters). +The \f[CR]if\f[R] section is used if \f[CR]variable\f[R] has a non-empty +value, otherwise the \f[CR]else\f[R] section is used (if present). +Examples: +.IP +.EX +$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} +.EE +.PP +The keyword \f[CR]elseif\f[R] may be used to simplify complex nested +conditionals: +.IP +.EX +$if(foo)$ +XXX +$elseif(bar)$ +YYY +$else$ +ZZZ +$endif$ +.EE +.SS For loops +A for loop begins with \f[CR]for(variable)\f[R] (enclosed in matched +delimiters) and ends with \f[CR]endfor\f[R] (enclosed in matched +delimiters). +.IP \[bu] 2 +If \f[CR]variable\f[R] is an array, the material inside the loop will be +evaluated repeatedly, with \f[CR]variable\f[R] being set to each value +of the array in turn, and concatenated. +.IP \[bu] 2 +If \f[CR]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 +.EX +$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$ +.EE +.PP +You may optionally specify a separator between consecutive values using +\f[CR]sep\f[R] (enclosed in matched delimiters). +The material between \f[CR]sep\f[R] and the \f[CR]endfor\f[R] is the +separator. +.IP +.EX +${ for(foo) }${ foo }${ sep }, ${ endfor } +.EE +.PP +Instead of using \f[CR]variable\f[R] inside the loop, the special +anaphoric keyword \f[CR]it\f[R] may be used. +.IP +.EX +${ for(foo.bar) } + - ${ it.last }, ${ it.first } +${ endfor } +.EE +.SS Partials +Partials (subtemplates stored in different files) may be included by +using the name of the partial, followed by \f[CR]()\f[R], for example: +.IP +.EX +${ styles() } +.EE +.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 +.EX +${ styles.html() } +.EE +.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[CR]templates\f[R] subdirectory of the user data directory.) +.PP +Partials may optionally be applied to variables using a colon: +.IP +.EX +${ date:fancy() } + +${ articles:bibentry() } +.EE +.PP +If \f[CR]articles\f[R] is an array, this will iterate over its values, +applying the partial \f[CR]bibentry()\f[R] to each one. +So the second example above is equivalent to +.IP +.EX +${ for(articles) } +${ it:bibentry() } +${ endfor } +.EE +.PP +Note that the anaphoric keyword \f[CR]it\f[R] must be used when +iterating over partials. +In the above examples, the \f[CR]bibentry\f[R] partial should contain +\f[CR]it.title\f[R] (and so on) instead of \f[CR]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 +.EX +${months[, ]}$ + +${articles:bibentry()[; ]$ +.EE +.PP +The separator in this case is literal and (unlike with \f[CR]sep\f[R] in +an explicit \f[CR]for\f[R] loop) cannot contain interpolated variables +or other template directives. +.SS Nesting +To ensure that content is \[lq]nested,\[rq] that is, subsequent lines +indented, use the \f[CR]\[ha]\f[R] directive: +.IP +.EX +$item.number$ $\[ha]$$item.description$ ($item.price$) +.EE +.PP +In this example, if \f[CR]item.description\f[R] has multiple lines, they +will all be indented to line up with the first line: +.IP +.EX +00123 A fine bottle of 18-year old + Oban whiskey. ($148) +.EE +.PP +To nest multiple lines to the same level, align them with the +\f[CR]\[ha]\f[R] directive in the template. +For example: +.IP +.EX +$item.number$ $\[ha]$$item.description$ ($item.price$) + (Available til $item.sellby$.) +.EE +.PP +will produce +.IP +.EX +00123 A fine bottle of 18-year old + Oban whiskey. ($148) + (Available til March 30, 2020.) +.EE +.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 +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[CR]\[ti]\f[R] keyword +(ended with another \f[CR]\[ti]\f[R]). +.IP +.EX +$\[ti]$This long line may break if the document is rendered +with a short line length.$\[ti]$ +.EE +.SS Pipes +A pipe transforms the value of a variable or partial. +Pipes are specified using a slash (\f[CR]/\f[R]) between the variable +name (or partial) and the pipe name. +Example: +.IP +.EX +$for(name)$ +$name/uppercase$ +$endfor$ + +$for(metadata/pairs)$ +- $it.key$: $it.value$ +$endfor$ + +$employee:name()/uppercase$ +.EE +.PP +Pipes may be chained: +.IP +.EX +$for(employees/pairs)$ +$it.key/alpha/uppercase$. $it.name$ +$endfor$ +.EE +.PP +Some pipes take parameters: +.IP +.EX +|----------------------|------------| +$for(employee)$ +$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$ +$endfor$ +|----------------------|------------| +.EE +.PP +Currently the following pipes are predefined: +.IP \[bu] 2 +\f[CR]pairs\f[R]: Converts a map or array to an array of maps, each with +\f[CR]key\f[R] and \f[CR]value\f[R] fields. +If the original value was an array, the \f[CR]key\f[R] will be the array +index, starting with 1. +.IP \[bu] 2 +\f[CR]uppercase\f[R]: Converts text to uppercase. +.IP \[bu] 2 +\f[CR]lowercase\f[R]: Converts text to lowercase. +.IP \[bu] 2 +\f[CR]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[CR]reverse\f[R]: Reverses a textual value or array, and has no effect +on other values. +.IP \[bu] 2 +\f[CR]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[CR]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[CR]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[CR]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[CR]chomp\f[R]: Removes trailing newlines (and breakable space). +.IP \[bu] 2 +\f[CR]nowrap\f[R]: Disables line wrapping on breakable spaces. +.IP \[bu] 2 +\f[CR]alpha\f[R]: Converts textual values that can be read as an integer +into lowercase alphabetic characters \f[CR]a..z\f[R] (mod 26). +This can be used to get lettered enumeration from array indices. +To get uppercase letters, chain with \f[CR]uppercase\f[R]. +.IP \[bu] 2 +\f[CR]roman\f[R]: Converts textual values that can be read as an integer +into lowercase roman numerals. +This can be used to get lettered enumeration from array indices. +To get uppercase roman, chain with \f[CR]uppercase\f[R]. +.IP \[bu] 2 +\f[CR]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +textual value in a block of width \f[CR]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[CR]\[dq]\f[R] and +\f[CR]\[rs]\f[R] characters must be backslash-escaped. +.IP \[bu] 2 +\f[CR]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +textual value in a block of width \f[CR]n\f[R], aligned to the right, +and has no effect on other values. +.IP \[bu] 2 +\f[CR]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders +a textual value in a block of width \f[CR]n\f[R], aligned to the center, +and has no effect on other values. +.SS Variables +.SS Metadata variables +.TP +\f[CR]title\f[R], \f[CR]author\f[R], \f[CR]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 +.EX +--- +author: +- Aristotle +- Peter Abelard +\&... +.EE +.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[CR]title-meta\f[R], \f[CR]author-meta\f[R], and \f[CR]date-meta\f[R] +variables. +(By default these are set automatically, based on \f[CR]title\f[R], +\f[CR]author\f[R], and \f[CR]date\f[R].) +The page title in HTML is set by \f[CR]pagetitle\f[R], which is equal to +\f[CR]title\f[R] by default. +.RE +.TP +\f[CR]subtitle\f[R] +document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx +documents +.TP +\f[CR]abstract\f[R] +document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc, and docx +documents +.TP +\f[CR]abstract-title\f[R] +title of abstract, currently used only in HTML, EPUB, and docx. +This will be set automatically to a localized value, depending on +\f[CR]lang\f[R], but can be manually overridden. +.TP +\f[CR]keywords\f[R] +list of keywords to be included in HTML, PDF, ODT, pptx, docx and +AsciiDoc metadata; repeat as for \f[CR]author\f[R], above +.TP +\f[CR]subject\f[R] +document subject, included in ODT, PDF, docx, EPUB, and pptx metadata +.TP +\f[CR]description\f[R] +document description, included in ODT, docx and pptx metadata. +Some applications show this as \f[CR]Comments\f[R] metadata. +.TP +\f[CR]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 +.EX +--- +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 +\&... +.EE +.PP +will include \f[CR]title\f[R], \f[CR]author\f[R] and +\f[CR]description\f[R] as standard document properties and +\f[CR]subtitle\f[R] as a custom property when converting to docx, ODT or +pptx. +.SS Language variables +.TP +\f[CR]lang\f[R] +identifies the main language of the document using IETF language tags +(following the BCP 47 standard), such as \f[CR]en\f[R] or +\f[CR]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[CR]babel\f[R] and \f[CR]polyglossia\f[R]) or +ConTeXt. +.RS +.PP +Use native pandoc Divs and Spans with the \f[CR]lang\f[R] attribute to +switch the language: +.IP +.EX +--- +lang: en-GB +\&... + +Text in the main document language (British English). + +::: {lang=fr-CA} +> Cette citation est écrite en français canadien. +::: + +More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de} +.EE +.RE +.TP +\f[CR]dir\f[R] +the base script direction, either \f[CR]rtl\f[R] (right-to-left) or +\f[CR]ltr\f[R] (left-to-right). +.RS +.PP +For bidirectional documents, native pandoc \f[CR]span\f[R]s and +\f[CR]div\f[R]s with the \f[CR]dir\f[R] attribute (value \f[CR]rtl\f[R] +or \f[CR]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[CR]xelatex\f[R] engine is fully supported (use +\f[CR]--pdf-engine=xelatex\f[R]). +.RE +.SS Variables for HTML +.TP +\f[CR]document-css\f[R] +Enables inclusion of most of the CSS in the \f[CR]styles.html\f[R] +partial (have a look with +\f[CR]pandoc --print-default-data-file=templates/styles.html\f[R]). +Unless you use \f[CR]--css\f[R], this variable is set to \f[CR]true\f[R] +by default. +You can disable it with e.g.\ \f[CR]pandoc -M document-css=false\f[R]. +.TP +\f[CR]mainfont\f[R] +sets the CSS \f[CR]font-family\f[R] property on the \f[CR]html\f[R] +element. +.TP +\f[CR]fontsize\f[R] +sets the base CSS \f[CR]font-size\f[R], which you\[cq]d usually set to +e.g.\ \f[CR]20px\f[R], but it also accepts \f[CR]pt\f[R] (12pt = 16px in +most browsers). +.TP +\f[CR]fontcolor\f[R] +sets the CSS \f[CR]color\f[R] property on the \f[CR]html\f[R] element. +.TP +\f[CR]linkcolor\f[R] +sets the CSS \f[CR]color\f[R] property on all links. +.TP +\f[CR]monofont\f[R] +sets the CSS \f[CR]font-family\f[R] property on \f[CR]code\f[R] +elements. +.TP +\f[CR]monobackgroundcolor\f[R] +sets the CSS \f[CR]background-color\f[R] property on \f[CR]code\f[R] +elements and adds extra padding. +.TP +\f[CR]linestretch\f[R] +sets the CSS \f[CR]line-height\f[R] property on the \f[CR]html\f[R] +element, which is preferred to be unitless. +.TP +\f[CR]maxwidth\f[R] +sets the CSS \f[CR]max-width\f[R] property (default is 32em). +.TP +\f[CR]backgroundcolor\f[R] +sets the CSS \f[CR]background-color\f[R] property on the \f[CR]html\f[R] +element. +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +sets the corresponding CSS \f[CR]padding\f[R] properties on the +\f[CR]body\f[R] element. +.PP +To override or extend some CSS for just one document, include for +example: +.IP +.EX +--- +header-includes: | + +--- +.EE +.SS Variables for HTML math +.TP +\f[CR]classoption\f[R] +when using KaTeX, you can render display math equations flush left using +YAML metadata or with \f[CR]-M classoption=fleqn\f[R]. +.SS Variables for HTML slides +These affect HTML output when producing slide shows with pandoc. +.TP +\f[CR]institute\f[R] +author affiliations: can be a list when there are multiple authors +.TP +\f[CR]revealjs-url\f[R] +base URL for reveal.js documents (defaults to +\f[CR]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R]) +.TP +\f[CR]s5-url\f[R] +base URL for S5 documents (defaults to \f[CR]s5/default\f[R]) +.TP +\f[CR]slidy-url\f[R] +base URL for Slidy documents (defaults to +\f[CR]https://www.w3.org/Talks/Tools/Slidy2\f[R]) +.TP +\f[CR]slideous-url\f[R] +base URL for Slideous documents (defaults to \f[CR]slideous\f[R]) +.TP +\f[CR]title-slide-attributes\f[R] +additional attributes for the title slide of reveal.js slide shows. +See background in reveal.js, beamer, and pptx 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[CR]0\f[R]. +.SS Variables for Beamer slides +These variables change the appearance of PDF slides using +\f[CR]beamer\f[R]. +.TP +\f[CR]aspectratio\f[R] +slide aspect ratio (\f[CR]43\f[R] for 4:3 [default], \f[CR]169\f[R] for +16:9, \f[CR]1610\f[R] for 16:10, \f[CR]149\f[R] for 14:9, \f[CR]141\f[R] +for 1.41:1, \f[CR]54\f[R] for 5:4, \f[CR]32\f[R] for 3:2) +.TP +\f[CR]beameroption\f[R] +add extra beamer option with \f[CR]\[rs]setbeameroption{}\f[R] +.TP +\f[CR]institute\f[R] +author affiliations: can be a list when there are multiple authors +.TP +\f[CR]logo\f[R] +logo image for slides +.TP +\f[CR]navigation\f[R] +controls navigation symbols (default is \f[CR]empty\f[R] for no +navigation symbols; other valid values are \f[CR]frame\f[R], +\f[CR]vertical\f[R], and \f[CR]horizontal\f[R]) +.TP +\f[CR]section-titles\f[R] +enables \[lq]title pages\[rq] for new sections (default is true) +.TP +\f[CR]theme\f[R], \f[CR]colortheme\f[R], \f[CR]fonttheme\f[R], \f[CR]innertheme\f[R], \f[CR]outertheme\f[R] +beamer themes +.TP +\f[CR]themeoptions\f[R] +options for LaTeX beamer themes (a list). +.TP +\f[CR]titlegraphic\f[R] +image for title slide +.SS Variables for PowerPoint +These variables control the visual aspects of a slide show that are not +easily controlled via templates. +.TP +\f[CR]monofont\f[R] +font to use for code. +.SS Variables for LaTeX +Pandoc uses these variables when creating a PDF with a LaTeX engine. +.SS Layout +.TP +\f[CR]block-headings\f[R] +make \f[CR]\[rs]paragraph\f[R] and \f[CR]\[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[CR]\[rs]subsubsection\f[R] (third- or fourth-level +headings). +Instead of using this option, KOMA-Script can adjust headings more +extensively: +.RS +.IP +.EX +--- +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} +\&... +.EE +.RE +.TP +\f[CR]classoption\f[R] +option for document class, e.g.\ \f[CR]oneside\f[R]; repeat for multiple +options: +.RS +.IP +.EX +--- +classoption: +- twocolumn +- landscape +\&... +.EE +.RE +.TP +\f[CR]documentclass\f[R] +document class: usually one of the standard classes, \f[CR]article\f[R], +\f[CR]book\f[R], and \f[CR]report\f[R]; the KOMA-Script equivalents, +\f[CR]scrartcl\f[R], \f[CR]scrbook\f[R], and \f[CR]scrreprt\f[R], which +default to smaller margins; or \f[CR]memoir\f[R] +.TP +\f[CR]geometry\f[R] +option for \f[CR]geometry\f[R] package, e.g.\ \f[CR]margin=1in\f[R]; +repeat for multiple options: +.RS +.IP +.EX +--- +geometry: +- top=30mm +- left=20mm +- heightrounded +\&... +.EE +.RE +.TP +\f[CR]hyperrefoptions\f[R] +option for \f[CR]hyperref\f[R] package, e.g.\ \f[CR]linktoc=all\f[R]; +repeat for multiple options: +.RS +.IP +.EX +--- +hyperrefoptions: +- linktoc=all +- pdfwindowui +- pdfpagemode=FullScreen +\&... +.EE +.RE +.TP +\f[CR]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[CR]linestretch\f[R] +adjusts line spacing using the \f[CR]setspace\f[R] package, +e.g.\ \f[CR]1.25\f[R], \f[CR]1.5\f[R] +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +sets margins if \f[CR]geometry\f[R] is not used (otherwise +\f[CR]geometry\f[R] overrides these) +.TP +\f[CR]pagestyle\f[R] +control \f[CR]\[rs]pagestyle{}\f[R]: the default article class supports +\f[CR]plain\f[R] (default), \f[CR]empty\f[R] (no running heads or page +numbers), and \f[CR]headings\f[R] (section titles in running heads) +.TP +\f[CR]papersize\f[R] +paper size, e.g.\ \f[CR]letter\f[R], \f[CR]a4\f[R] +.TP +\f[CR]secnumdepth\f[R] +numbering depth for sections (with \f[CR]--number-sections\f[R] option +or \f[CR]numbersections\f[R] variable) +.TP +\f[CR]beamerarticle\f[R] +produce an article from Beamer slides +.SS Fonts +.TP +\f[CR]fontenc\f[R] +allows font encoding to be specified through \f[CR]fontenc\f[R] package +(with \f[CR]pdflatex\f[R]); default is \f[CR]T1\f[R] (see LaTeX font +encodings guide) +.TP +\f[CR]fontfamily\f[R] +font package for use with \f[CR]pdflatex\f[R]: TeX Live includes many +options, documented in the LaTeX Font Catalogue. +The default is Latin Modern. +.TP +\f[CR]fontfamilyoptions\f[R] +options for package used as \f[CR]fontfamily\f[R]; repeat for multiple +options. +For example, to use the Libertine font with proportional lowercase +(old-style) figures through the \f[CR]libertinus\f[R] package: +.RS +.IP +.EX +--- +fontfamily: libertinus +fontfamilyoptions: +- osf +- p +\&... +.EE +.RE +.TP +\f[CR]fontsize\f[R] +font size for body text. +The standard classes allow 10pt, 11pt, and 12pt. +To use another size, set \f[CR]documentclass\f[R] to one of the +KOMA-Script classes, such as \f[CR]scrartcl\f[R] or \f[CR]scrbook\f[R]. +.TP +\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R], \f[CR]CJKsansfont\f[R], \f[CR]CJKmonofont\f[R] +font families for use with \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R]: +take the name of any system font, using the \f[CR]fontspec\f[R] package. +\f[CR]CJKmainfont\f[R] uses the \f[CR]xecjk\f[R] package. +.TP +\f[CR]mainfontoptions\f[R], \f[CR]sansfontoptions\f[R], \f[CR]monofontoptions\f[R], \f[CR]mathfontoptions\f[R], \f[CR]CJKoptions\f[R] +options to use with \f[CR]mainfont\f[R], \f[CR]sansfont\f[R], +\f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R] in +\f[CR]xelatex\f[R] and \f[CR]lualatex\f[R]. +Allow for any choices available through \f[CR]fontspec\f[R]; repeat for +multiple options. +For example, to use the TeX Gyre version of Palatino with lowercase +figures: +.RS +.IP +.EX +--- +mainfont: TeX Gyre Pagella +mainfontoptions: +- Numbers=Lowercase +- Numbers=Proportional +\&... +.EE +.RE +.TP +\f[CR]babelfonts\f[R] +a map of Babel language names (e.g.\ \f[CR]chinese\f[R]) to the font to +be used with the language: +.RS +.PP + * * * * * +.PP +babelfonts: chinese-hant: \[lq]Noto Serif CJK TC\[rq] russian: \[lq]Noto +Serif\[rq] \&... +.RE +.TP +\f[CR]microtypeoptions\f[R] +options to pass to the microtype package +.SS Links +.TP +\f[CR]colorlinks\f[R] +add color to link text; automatically enabled if any of +\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], +\f[CR]urlcolor\f[R], or \f[CR]toccolor\f[R] are set +.TP +\f[CR]boxlinks\f[R] +add visible box around links (has no effect if \f[CR]colorlinks\f[R] is +set) +.TP +\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], \f[CR]urlcolor\f[R], \f[CR]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[CR]xcolor\f[R], including the \f[CR]dvipsnames\f[R], +\f[CR]svgnames\f[R], and \f[CR]x11names\f[R] lists +.TP +\f[CR]links-as-notes\f[R] +causes links to be printed as footnotes +.TP +\f[CR]urlstyle\f[R] +style for URLs (e.g., \f[CR]tt\f[R], \f[CR]rm\f[R], \f[CR]sf\f[R], and, +the default, \f[CR]same\f[R]) +.SS Front matter +.TP +\f[CR]lof\f[R], \f[CR]lot\f[R] +include list of figures, list of tables +.TP +\f[CR]thanks\f[R] +contents of acknowledgments footnote after document title +.TP +\f[CR]toc\f[R] +include table of contents (can also be set using +\f[CR]--toc/--table-of-contents\f[R]) +.TP +\f[CR]toc-depth\f[R] +level of section to include in table of contents +.SS BibLaTeX Bibliographies +These variables function when using BibLaTeX for citation rendering. +.TP +\f[CR]biblatexoptions\f[R] +list of options for biblatex +.TP +\f[CR]biblio-style\f[R] +bibliography style, when used with \f[CR]--natbib\f[R] and +\f[CR]--biblatex\f[R] +.TP +\f[CR]biblio-title\f[R] +bibliography title, when used with \f[CR]--natbib\f[R] and +\f[CR]--biblatex\f[R] +.TP +\f[CR]bibliography\f[R] +bibliography to use for resolving references +.TP +\f[CR]natbiboptions\f[R] +list of options for natbib +.SS Variables for ConTeXt +Pandoc uses these variables when creating a PDF with ConTeXt. +.TP +\f[CR]fontsize\f[R] +font size for body text (e.g.\ \f[CR]10pt\f[R], \f[CR]12pt\f[R]) +.TP +\f[CR]headertext\f[R], \f[CR]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[CR]indenting\f[R] +controls indentation of paragraphs, e.g.\ \f[CR]yes,small,next\f[R] (see +ConTeXt Indentation); repeat for multiple options +.TP +\f[CR]interlinespace\f[R] +adjusts line spacing, e.g.\ \f[CR]4ex\f[R] (using +\f[CR]setupinterlinespace\f[R]); repeat for multiple options +.TP +\f[CR]layout\f[R] +options for page margins and text arrangement (see ConTeXt Layout); +repeat for multiple options +.TP +\f[CR]linkcolor\f[R], \f[CR]contrastcolor\f[R] +color for links outside and inside a page, e.g.\ \f[CR]red\f[R], +\f[CR]blue\f[R] (see ConTeXt Color) +.TP +\f[CR]linkstyle\f[R] +typeface style for links, e.g.\ \f[CR]normal\f[R], \f[CR]bold\f[R], +\f[CR]slanted\f[R], \f[CR]boldslanted\f[R], \f[CR]type\f[R], +\f[CR]cap\f[R], \f[CR]small\f[R] +.TP +\f[CR]lof\f[R], \f[CR]lot\f[R] +include list of figures, list of tables +.TP +\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R] +font families: take the name of any system font (see ConTeXt Font +Switching) +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +sets margins, if \f[CR]layout\f[R] is not used (otherwise +\f[CR]layout\f[R] overrides these) +.TP +\f[CR]pagenumbering\f[R] +page number style and location (using \f[CR]setuppagenumbering\f[R]); +repeat for multiple options +.TP +\f[CR]papersize\f[R] +paper size, e.g.\ \f[CR]letter\f[R], \f[CR]A4\f[R], \f[CR]landscape\f[R] +(see ConTeXt Paper Setup); repeat for multiple options +.TP +\f[CR]pdfa\f[R] +adds to the preamble the setup necessary to generate PDF/A of the type +specified, e.g.\ \f[CR]1a:2005\f[R], \f[CR]2a\f[R]. +If no type is specified (i.e.\ the value is set to True, by e.g. +\f[CR]--metadata=pdfa\f[R] or \f[CR]pdfa: true\f[R] in a YAML metadata +block), \f[CR]1b:2005\f[R] will be used as default, for reasons of +backwards compatibility. +Using \f[CR]--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[CR]pdfaiccprofile\f[R] and \f[CR]pdfaintent\f[R]. +See also ConTeXt PDFA for more details. +.TP +\f[CR]pdfaiccprofile\f[R] +when used in conjunction with \f[CR]pdfa\f[R], specifies the ICC profile +to use in the PDF, e.g.\ \f[CR]default.cmyk\f[R]. +If left unspecified, \f[CR]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[CR]pdfaintent\f[R] +when used in conjunction with \f[CR]pdfa\f[R], specifies the output +intent for the colors, +e.g.\ \f[CR]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If +left unspecified, \f[CR]sRGB IEC61966-2.1\f[R] is used as default. +.TP +\f[CR]toc\f[R] +include table of contents (can also be set using +\f[CR]--toc/--table-of-contents\f[R]) +.TP +\f[CR]urlstyle\f[R] +typeface style for links without link text, e.g.\ \f[CR]normal\f[R], +\f[CR]bold\f[R], \f[CR]slanted\f[R], \f[CR]boldslanted\f[R], +\f[CR]type\f[R], \f[CR]cap\f[R], \f[CR]small\f[R] +.TP +\f[CR]whitespace\f[R] +spacing between paragraphs, e.g.\ \f[CR]none\f[R], \f[CR]small\f[R] +(using \f[CR]setupwhitespace\f[R]) +.TP +\f[CR]includesource\f[R] +include all source documents as file attachments in the PDF file +.SS Variables for \f[CR]wkhtmltopdf\f[R] +Pandoc uses these variables when creating a PDF with +\f[CR]wkhtmltopdf\f[R]. +The \f[CR]--css\f[R] option also affects the output. +.TP +\f[CR]footer-html\f[R], \f[CR]header-html\f[R] +add information to the header and footer +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +set the page margins +.TP +\f[CR]papersize\f[R] +sets the PDF paper size +.SS Variables for man pages +.TP +\f[CR]adjusting\f[R] +adjusts text to left (\f[CR]l\f[R]), right (\f[CR]r\f[R]), center +(\f[CR]c\f[R]), or both (\f[CR]b\f[R]) margins +.TP +\f[CR]footer\f[R] +footer in man pages +.TP +\f[CR]header\f[R] +header in man pages +.TP +\f[CR]section\f[R] +section number in man pages +.SS Variables for Typst +.TP +\f[CR]margin\f[R] +A dictionary with the fields defined in the Typst documentation: +\f[CR]x\f[R], \f[CR]y\f[R], \f[CR]top\f[R], \f[CR]bottom\f[R], +\f[CR]left\f[R], \f[CR]right\f[R]. +.TP +\f[CR]papersize\f[R] +Paper size: \f[CR]a4\f[R], \f[CR]us-letter\f[R], etc. +.TP +\f[CR]mainfont\f[R] +Name of system font to use for the main font. +.TP +\f[CR]fontsize\f[R] +Font size (e.g., \f[CR]12pt\f[R]). +.TP +\f[CR]section-numbering\f[R] +Schema to use for numbering sections, e.g.\ \f[CR]1.A.1\f[R]. +.TP +\f[CR]columns\f[R] +Number of columns for body text. +.SS Variables for ms +.TP +\f[CR]fontfamily\f[R] +\f[CR]A\f[R] (Avant Garde), \f[CR]B\f[R] (Bookman), \f[CR]C\f[R] +(Helvetica), \f[CR]HN\f[R] (Helvetica Narrow), \f[CR]P\f[R] (Palatino), +or \f[CR]T\f[R] (Times New Roman). +This setting does not affect source code, which is always displayed +using monospace Courier. +These built-in fonts are limited in their coverage of characters. +Additional fonts may be installed using the script +\f[CR]install-font.sh\f[R] provided by Peter Schaffter and documented in +detail on his web site. +.TP +\f[CR]indent\f[R] +paragraph indent (e.g.\ \f[CR]2m\f[R]) +.TP +\f[CR]lineheight\f[R] +line height (e.g.\ \f[CR]12p\f[R]) +.TP +\f[CR]pointsize\f[R] +point size (e.g.\ \f[CR]10p\f[R]) +.SS Variables set automatically +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[CR]body\f[R] +body of document +.TP +\f[CR]date-meta\f[R] +the \f[CR]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[CR]date\f[R] are: \f[CR]mm/dd/yyyy\f[R], +\f[CR]mm/dd/yy\f[R], \f[CR]yyyy-mm-dd\f[R] (ISO 8601), +\f[CR]dd MM yyyy\f[R] (e.g.\ either \f[CR]02 Apr 2018\f[R] or +\f[CR]02 April 2018\f[R]), \f[CR]MM dd, yyyy\f[R] +(e.g.\ \f[CR]Apr. 02, 2018\f[R] or +\f[CR]April 02, 2018),\f[R]yyyy[mm[dd]]\f[CR](e.g.\f[R]20180402, +\f[CR]201804\f[R] or \f[CR]2018\f[R]). +.TP +\f[CR]header-includes\f[R] +contents specified by \f[CR]-H/--include-in-header\f[R] (may have +multiple values) +.TP +\f[CR]include-before\f[R] +contents specified by \f[CR]-B/--include-before-body\f[R] (may have +multiple values) +.TP +\f[CR]include-after\f[R] +contents specified by \f[CR]-A/--include-after-body\f[R] (may have +multiple values) +.TP +\f[CR]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[CR]numbersections\f[R] +non-null value if \f[CR]-N/--number-sections\f[R] was specified +.TP +\f[CR]sourcefile\f[R], \f[CR]outputfile\f[R] +source and destination filenames, as given on the command line. +\f[CR]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 +.EX +$if(sourcefile)$ +$for(sourcefile)$ +$sourcefile$ +$endfor$ +$else$ +(stdin) +$endif$ +.EE +.PP +Similarly, \f[CR]outputfile\f[R] can be \f[CR]-\f[R] if output goes to +the terminal. +.PP +If you need absolute paths, use e.g.\ \f[CR]$curdir$/$sourcefile$\f[R]. +.RE +.TP +\f[CR]curdir\f[R] +working directory from which pandoc is run. +.TP +\f[CR]pandoc-version\f[R] +pandoc version. +.TP +\f[CR]toc\f[R] +non-null value if \f[CR]--toc/--table-of-contents\f[R] was specified +.TP +\f[CR]toc-title\f[R] +title of table of contents (works only with EPUB, HTML, revealjs, +opendocument, odt, docx, pptx, beamer, LaTeX) +.SH EXTENSIONS +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[CR]+EXTENSION\f[R] to the +format name and disabled by adding \f[CR]-EXTENSION\f[R]. +For example, \f[CR]--from markdown_strict+footnotes\f[R] is strict +Markdown with footnotes enabled, while +\f[CR]--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[CR]commonmark\f[R] and \f[CR]gfm\f[R]). +In the following, extensions that also work for other formats are +covered. +.PP +Note that markdown extensions added to the \f[CR]ipynb\f[R] format +affect Markdown cells in Jupyter notebooks (as do command-line options +like \f[CR]--markdown-headings\f[R]). +.SS Typography +.SS Extension: \f[CR]smart\f[R] +Interpret straight quotes as curly quotes, \f[CR]---\f[R] as em-dashes, +\f[CR]--\f[R] as en-dashes, and \f[CR]...\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[CR]markdown\f[R], \f[CR]commonmark\f[R], \f[CR]latex\f[R], +\f[CR]mediawiki\f[R], \f[CR]org\f[R], \f[CR]rst\f[R], \f[CR]twiki\f[R], +\f[CR]html\f[R] +.TP +output formats +\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R], +\f[CR]rst\f[R] +.TP +enabled by default in +\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R] (both input +and output) +.PP +Note: If you are \f[I]writing\f[R] Markdown, then the \f[CR]smart\f[R] +extension has the reverse effect: what would have been curly quotes +comes out straight. +.PP +In LaTeX, \f[CR]smart\f[R] means to use the standard TeX ligatures for +quotation marks (\f[CR]\[ga]\[ga]\f[R] and \f[CR]\[aq]\[aq]\f[R] for +double quotes, \f[CR]\[ga]\f[R] and \f[CR]\[aq]\f[R] for single quotes) +and dashes (\f[CR]--\f[R] for en-dash and \f[CR]---\f[R] for em-dash). +If \f[CR]smart\f[R] is disabled, then in reading LaTeX pandoc will parse +these characters literally. +In writing LaTeX, enabling \f[CR]smart\f[R] tells pandoc to use the +ligatures when possible; if \f[CR]smart\f[R] is disabled pandoc will use +unicode quotation mark and dash characters. +.SS Headings and sections +.SS Extension: \f[CR]auto_identifiers\f[R] +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[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]rst\f[R], +\f[CR]mediawiki\f[R], \f[CR]textile\f[R] +.TP +output formats +\f[CR]markdown\f[R], \f[CR]muse\f[R] +.TP +enabled by default in +\f[CR]markdown\f[R], \f[CR]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[CR]section\f[R]. +.PP +Thus, for example, +.RS -14n +.IP +.EX + Heading Identifier + ----------------------------- ----------------------------- + Heading identifiers in HTML heading-identifiers-in-html + Maître d\[aq]hôtel maître-dhôtel + *Dogs*?--in *my* house? dogs--in-my-house + [HTML], [S5], or [RTF]? html-s5-or-rtf + 3. Applications applications + 33 section +.EE +.RE +.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[CR]-1\f[R] appended; the third with +\f[CR]-2\f[R]; and so on. +.PP +(However, a different algorithm is used if +\f[CR]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[CR]--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 +.EX +See the section on +[heading identifiers](#heading-identifiers-in-html-latex-and-context). +.EE +.PP +Note, however, that this method of providing links to sections works +only in HTML, LaTeX, and ConTeXt formats. +.PP +If the \f[CR]--section-divs\f[R] option is specified, then each section +will be wrapped in a \f[CR]section\f[R] (or a \f[CR]div\f[R], if +\f[CR]html4\f[R] was specified), and the identifier will be attached to +the enclosing \f[CR]
\f[R] (or \f[CR]
\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[CR]ascii_identifiers\f[R] +Causes the identifiers produced by \f[CR]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[CR]gfm_auto_identifiers\f[R] +Changes the algorithm used by \f[CR]auto_identifiers\f[R] to conform to +GitHub\[cq]s method. +Spaces are converted to dashes (\f[CR]-\f[R]), uppercase characters to +lowercase characters, and punctuation characters other than \f[CR]-\f[R] +and \f[CR]_\f[R] are removed. +Emojis are replaced by their names. +.SS Math Input +The extensions \f[CR]tex_math_dollars\f[R], +\f[CR]tex_math_single_backslash\f[R], and +\f[CR]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 +The following extensions are described in more detail in their +respective sections of Pandoc\[cq]s Markdown: +.IP \[bu] 2 +\f[CR]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[CR]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[CR]markdown\f[R]): +.RS 2 +.TP +input formats +\f[CR]latex\f[R], \f[CR]textile\f[R], \f[CR]html\f[R] (environments, +\f[CR]\[rs]ref\f[R], and \f[CR]\[rs]eqref\f[R] only), \f[CR]ipynb\f[R] +.TP +output formats +\f[CR]textile\f[R], \f[CR]commonmark\f[R] +.PP +Note: as applied to \f[CR]ipynb\f[R], \f[CR]raw_html\f[R] and +\f[CR]raw_tex\f[R] affect not only raw TeX in markdown cells, but data +with mime type \f[CR]text/html\f[R] in output cells. +Since the \f[CR]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[CR]raw_html\f[R] and \f[CR]raw_tex\f[R] when +converting to formats like \f[CR]docx\f[R] which don\[cq]t allow raw +\f[CR]html\f[R] or \f[CR]tex\f[R]. +.RE +.IP \[bu] 2 +\f[CR]native_divs\f[R] causes HTML \f[CR]div\f[R] elements to be parsed +as native pandoc Div blocks. +If you want them to be parsed as raw HTML, use +\f[CR]-f html-native_divs+raw_html\f[R]. +.IP \[bu] 2 +\f[CR]native_spans\f[R] causes HTML \f[CR]span\f[R] elements to be +parsed as native pandoc Span inlines. +If you want them to be parsed as raw HTML, use +\f[CR]-f html-native_spans+raw_html\f[R]. +If you want to drop all \f[CR]div\f[R]s and \f[CR]span\f[R]s when +converting HTML to Markdown, you can use +\f[CR]pandoc -f html-native_divs-native_spans -t markdown\f[R]. +.SS Literate Haskell support +.SS Extension: \f[CR]literate_haskell\f[R] +Treat the document as literate Haskell source. +.PP +This extension can be enabled/disabled for the following formats: +.TP +input formats +\f[CR]markdown\f[R], \f[CR]rst\f[R], \f[CR]latex\f[R] +.TP +output formats +\f[CR]markdown\f[R], \f[CR]rst\f[R], \f[CR]latex\f[R], \f[CR]html\f[R] +.PP +If you append \f[CR]+lhs\f[R] (or \f[CR]+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[CR]\[rs]begin{code}\f[R] and \f[CR]\[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[CR]haskell\f[R] and +\f[CR]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[CR]haskell\f[R] +will be rendered using bird tracks. +.IP \[bu] 2 +In LaTeX input, text in \f[CR]code\f[R] environments will be parsed as +Haskell code. +.IP \[bu] 2 +In LaTeX output, code blocks with class \f[CR]haskell\f[R] will be +rendered inside \f[CR]code\f[R] environments. +.IP \[bu] 2 +In HTML output, code blocks with class \f[CR]haskell\f[R] will be +rendered with class \f[CR]literatehaskell\f[R] and bird tracks. +.PP +Examples: +.IP +.EX +pandoc -f markdown+lhs -t html +.EE +.PP +reads literate Haskell source formatted with Markdown conventions and +writes ordinary HTML (without bird tracks). +.IP +.EX +pandoc -f markdown+lhs -t html+lhs +.EE +.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[CR]empty_paragraphs\f[R] +Allows empty paragraphs. +By default empty paragraphs are omitted. +.PP +This extension can be enabled/disabled for the following formats: +.TP +input formats +\f[CR]docx\f[R], \f[CR]html\f[R] +.TP +output formats +\f[CR]docx\f[R], \f[CR]odt\f[R], \f[CR]opendocument\f[R], +\f[CR]html\f[R] +.SS Extension: \f[CR]native_numbering\f[R] +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[CR]odt\f[R], \f[CR]opendocument\f[R], \f[CR]docx\f[R] +.SS Extension: \f[CR]xrefs_name\f[R] +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[CR]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[CR]odt\f[R], \f[CR]opendocument\f[R] +.SS Extension: \f[CR]xrefs_number\f[R] +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[CR]xrefs_name\f[R] in which case +the name or caption numbers will appear after the number. +.PP +For the \f[CR]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[CR]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[CR]odt\f[R], \f[CR]opendocument\f[R] +.SS Extension: \f[CR]styles\f[R] +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[CR]docx\f[R] +.SS Extension: \f[CR]amuse\f[R] +In the \f[CR]muse\f[R] input format, this enables Text::Amuse extensions +to Emacs Muse markup. +.SS Extension: \f[CR]raw_markdown\f[R] +In the \f[CR]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[CR]ipynb\f[R] or a +markdown-based output format. +.SS Extension: \f[CR]citations\f[R] +When the \f[CR]citations\f[R] extension is enabled in \f[CR]org\f[R], +org-cite and org-ref style citations will be parsed as native pandoc +citations. +.PP +When \f[CR]citations\f[R] is enabled in \f[CR]docx\f[R], citations +inserted by Zotero or Mendeley or EndNote plugins will be parsed as +native pandoc citations. +(Otherwise, the formatted citations generated by the bibliographic +software will be parsed as regular text.) +.SS Extension: \f[CR]fancy_lists\f[R] +Some aspects of Pandoc\[cq]s Markdown fancy lists are also accepted in +\f[CR]org\f[R] input, mimicking the option +\f[CR]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[CR]#\f[R] placeholder that are enabled by the extension in +Pandoc\[cq]s Markdown. +.SS Extension: \f[CR]element_citations\f[R] +In the \f[CR]jats\f[R] output formats, this causes reference items to be +replaced with \f[CR]\f[R] elements. +These elements are not influenced by CSL styles, but all information on +the item is included in tags. +.SS Extension: \f[CR]ntb\f[R] +In the \f[CR]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. +.SS Extension: \f[CR]tagging\f[R] +Enabling this extension with \f[CR]context\f[R] output will produce +markup suitable for the production of tagged PDFs. +This includes additional markers for paragraphs and alternative markup +for emphasized text. +The \f[CR]emphasis-command\f[R] template variable is set if the +extension is enabled. +.SH PANDOC\[cq]S MARKDOWN +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[CR]markdown_strict\f[R] format instead of \f[CR]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 +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 +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[CR]escaped_line_breaks\f[R] +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 +There are two kinds of headings: Setext and ATX. +.SS Setext-style headings +A setext-style heading is a line of text \[lq]underlined\[rq] with a row +of \f[CR]=\f[R] signs (for a level-one heading) or \f[CR]-\f[R] signs +(for a level-two heading): +.IP +.EX +A level-one heading +=================== + +A level-two heading +------------------- +.EE +.PP +The heading text can contain inline formatting, such as emphasis (see +Inline formatting, below). +.SS ATX-style headings +An ATX-style heading consists of one to six \f[CR]#\f[R] signs and a +line of text, optionally followed by any number of \f[CR]#\f[R] signs. +The number of \f[CR]#\f[R] signs at the beginning of the line is the +heading level: +.IP +.EX +## A level-two heading + +### A level-three heading ### +.EE +.PP +As with setext-style headings, the heading text can contain formatting: +.IP +.EX +# A level-one heading with a [link](/url) and *emphasis* +.EE +.SS Extension: \f[CR]blank_before_header\f[R] +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[CR]#\f[R] to end up at the beginning of a line by accident (perhaps +through line wrapping). +Consider, for example: +.IP +.EX +I like several of their flavors of ice cream: +#22, for example, and #5. +.EE +.SS Extension: \f[CR]space_in_atx_header\f[R] +Many Markdown implementations do not require a space between the opening +\f[CR]#\f[R]s of an ATX heading and the heading text, so that +\f[CR]#5 bolt\f[R] and \f[CR]#hashtag\f[R] count as headings. +With this extension, pandoc does require the space. +.SS Heading identifiers +See also the \f[CR]auto_identifiers\f[R] extension above. +.SS Extension: \f[CR]header_attributes\f[R] +Headings can be assigned attributes using this syntax at the end of the +line containing the heading text: +.IP +.EX +{#identifier .class .class key=value key=value} +.EE +.PP +Thus, for example, the following headings will all be assigned the +identifier \f[CR]foo\f[R]: +.IP +.EX +# My heading {#foo} + +## My heading ## {#foo} + +My other heading {#foo} +--------------- +.EE +.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[CR]unnumbered\f[R] will not be numbered, even +if \f[CR]--number-sections\f[R] is specified. +A single hyphen (\f[CR]-\f[R]) in an attribute context is equivalent to +\f[CR].unnumbered\f[R], and preferable in non-English documents. +So, +.IP +.EX +# My heading {-} +.EE +.PP +is just the same as +.IP +.EX +# My heading {.unnumbered} +.EE +.PP +If the \f[CR]unlisted\f[R] class is present in addition to +\f[CR]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[CR]implicit_header_references\f[R] +Pandoc behaves as if reference links have been defined for each heading. +So, to link to a heading +.IP +.EX +# Heading identifiers in HTML +.EE +.PP +you can simply write +.IP +.EX +[Heading identifiers in HTML] +.EE +.PP +or +.IP +.EX +[Heading identifiers in HTML][] +.EE +.PP +or +.IP +.EX +[the section on heading identifiers][heading identifiers in +HTML] +.EE +.PP +instead of giving the identifier explicitly: +.IP +.EX +[Heading identifiers in HTML](#heading-identifiers-in-html) +.EE +.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[CR]bar\f[R], not +to \f[CR]#foo\f[R]: +.IP +.EX +# Foo + +[foo]: bar + +See [foo] +.EE +.SS Block quotations +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[CR]>\f[R] +character and an optional space. +(The \f[CR]>\f[R] need not start at the left margin, but it should not +be indented more than three spaces.) +.IP +.EX +> This is a block quote. This +> paragraph has two lines. +> +> 1. This is a list inside a block quote. +> 2. Second item. +.EE +.PP +A \[lq]lazy\[rq] form, which requires the \f[CR]>\f[R] character only on +the first line of each block, is also allowed: +.IP +.EX +> This is a block quote. This +paragraph has two lines. + +> 1. This is a list inside a block quote. +2. Second item. +.EE +.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 +.EX +> This is a block quote. +> +> > A block quote within a block quote. +.EE +.PP +If the \f[CR]>\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[CR]>\f[R]: +.IP +.EX +> code +.EE +.SS Extension: \f[CR]blank_before_blockquote\f[R] +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[CR]>\f[R] to end up at the beginning of a line by accident (perhaps +through line wrapping). +So, unless the \f[CR]markdown_strict\f[R] format is used, the following +does not produce a nested block quote in pandoc: +.IP +.EX +> This is a block quote. +>> Not nested, since \[ga]blank_before_blockquote\[ga] is enabled by default +.EE +.SS Verbatim (code) blocks +.SS Indented code blocks +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 +.EX + if (a > 3) { + moveShip(5 * gravity, DOWN); + } +.EE +.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[CR]fenced_code_blocks\f[R] +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[CR]\[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 +.EX +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +if (a > 3) { + moveShip(5 * gravity, DOWN); +} +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +.EE +.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 +.EX +\[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] +.EE +.SS Extension: \f[CR]backtick_code_blocks\f[R] +Same as \f[CR]fenced_code_blocks\f[R], but uses backticks +(\f[CR]\[ga]\f[R]) instead of tildes (\f[CR]\[ti]\f[R]). +.SS Extension: \f[CR]fenced_code_attributes\f[R] +Optionally, you may attach attributes to fenced or backtick code block +using this syntax: +.IP +.EX +\[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] +.EE +.PP +Here \f[CR]mycode\f[R] is an identifier, \f[CR]haskell\f[R] and +\f[CR]numberLines\f[R] are classes, and \f[CR]startFrom\f[R] is an +attribute with value \f[CR]100\f[R]. +Some output formats can use this information to do syntax highlighting. +Currently, the only output formats that use 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[CR]pandoc --list-highlight-languages\f[R].) +Otherwise, the code block above will appear as follows: +.IP +.EX +
+  
+  ...
+  
+
+.EE +.PP +The \f[CR]numberLines\f[R] (or \f[CR]number-lines\f[R]) class will cause +the lines of the code block to be numbered, starting with \f[CR]1\f[R] +or the value of the \f[CR]startFrom\f[R] attribute. +The \f[CR]lineAnchors\f[R] (or \f[CR]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 +.EX +\[ga]\[ga]\[ga]haskell +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +This is equivalent to: +.IP +.EX +\[ga]\[ga]\[ga] {.haskell} +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +This shortcut form may be combined with attributes: +.IP +.EX +\[ga]\[ga]\[ga]haskell {.numberLines} +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +Which is equivalent to: +.IP +.EX +\[ga]\[ga]\[ga] {.haskell .numberLines} +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +If the \f[CR]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[CR]--no-highlight\f[R] flag. +To set the highlighting style, use \f[CR]--highlight-style\f[R]. +For more information on highlighting, see Syntax highlighting, below. +.SS Line blocks +.SS Extension: \f[CR]line_blocks\f[R] +A line block is a sequence of lines beginning with a vertical bar +(\f[CR]|\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 +.EX +| 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 +.EE +.PP +The lines can be hard-wrapped if needed, but the continuation line must +begin with a space. +.IP +.EX +| The Right Honorable Most Venerable and Righteous Samuel L. + Constable, Jr. +| 200 Main St. +| Berkeley, CA 94718 +.EE +.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 +A bullet list is a list of bulleted list items. +A bulleted list item begins with a bullet (\f[CR]*\f[R], \f[CR]+\f[R], +or \f[CR]-\f[R]). +Here is a simple example: +.IP +.EX +* one +* two +* three +.EE +.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 +.EX +* one + +* two + +* three +.EE +.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 +.EX +* here is my first + list item. +* and my second. +.EE +.PP +But Markdown also allows a \[lq]lazy\[rq] format: +.IP +.EX +* here is my first +list item. +* and my second. +.EE +.SS Block content in list items +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 +.EX + * First paragraph. + + Continued. + + * Second paragraph. With a code block, which must be indented + eight spaces: + + { code } +.EE +.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 +.EX +* code + + continuation paragraph +.EE +.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 +.EX +* fruits + + apples + - macintosh + - red delicious + + pears + + peaches +* vegetables + + broccoli + + chard +.EE +.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 +.EX ++ A lazy, lazy, list +item. + ++ Another one; this looks +bad but is legal. + + Second paragraph of second +list item. +.EE +.SS Ordered lists +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 +.EX +1. one +2. two +3. three +.EE +.PP +and this one: +.IP +.EX +5. one +7. two +1. three +.EE +.SS Extension: \f[CR]fancy_lists\f[R] +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-parenthesis 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[CR]fancy_lists\f[R] extension also allows `\f[CR]#\f[R]' to be +used as an ordered list marker in place of a numeral: +.IP +.EX +#. one +#. two +.EE +.PP +Note: the `\f[CR]#\f[R]' ordered list marker doesn\[cq]t work with +\f[CR]commonmark\f[R]. +.SS Extension: \f[CR]startnum\f[R] +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 +.EX + 9) Ninth +10) Tenth +11) Eleventh + i. subone + ii. subtwo + iii. subthree +.EE +.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 +.EX +(2) Two +(5) Three +1. Four +* Five +.EE +.PP +If default list markers are desired, use \f[CR]#.\f[R]: +.IP +.EX +#. one +#. two +#. three +.EE +.SS Extension: \f[CR]task_lists\f[R] +Pandoc supports task lists, using the syntax of GitHub-Flavored +Markdown. +.IP +.EX +- [ ] an unchecked task list item +- [x] checked item +.EE +.SS Definition lists +.SS Extension: \f[CR]definition_lists\f[R] +Pandoc supports definition lists, using the syntax of PHP Markdown Extra +with some extensions. +.IP +.EX +Term 1 + +: Definition 1 + +Term 2 with *inline markup* + +: Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. +.EE +.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 +.EX +Term 1 + +: Definition +with lazy continuation. + + Second paragraph of the definition. +.EE +.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 +.EX +Term 1 + \[ti] Definition 1 + +Term 2 + \[ti] Definition 2a + \[ti] Definition 2b +.EE +.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 the +\f[CR]compact_definition_lists\f[R] extension.) +.SS Numbered example lists +.SS Extension: \f[CR]example_lists\f[R] +The special list marker \f[CR]\[at]\f[R] can be used for sequentially +numbered examples. +The first list item with a \f[CR]\[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[CR]\[at]\f[R] will take up where the last stopped. +So, for example: +.IP +.EX +(\[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). +.EE +.PP +Numbered examples can be labeled and referred to elsewhere in the +document: +.IP +.EX +(\[at]good) This is a good example. + +As (\[at]good) illustrates, ... +.EE +.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[CR]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 +What if you want to put an indented code block after a list? +.IP +.EX +- item one +- item two + + { my code block } +.EE +.PP +Trouble! +Here pandoc (like other Markdown implementations) will treat +\f[CR]{ 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 +.EX +- item one +- item two + + + + { my code block } +.EE +.PP +You can use the same trick if you want two consecutive lists instead of +one big list: +.IP +.EX +1. one +2. two +3. three + + + +1. uno +2. dos +3. tres +.EE +.SS Horizontal rules +A line containing a row of three or more \f[CR]*\f[R], \f[CR]-\f[R], or +\f[CR]_\f[R] characters (optionally separated by spaces) produces a +horizontal rule: +.IP +.EX +* * * * + +--------------- +.EE +.PP +We strongly recommend that horizontal rules be separated from +surrounding text by blank lines. +If a horizontal rule is not followed by a blank line, pandoc may try to +interpret the lines that follow as a YAML metadata block or a table. +.SS Tables +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[CR]table_captions\f[R] +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[CR]Table:\f[R] (or +\f[CR]table:\f[R] or just \f[CR]:\f[R]), which will be stripped off. +It may appear either before or after the table. +.SS Extension: \f[CR]simple_tables\f[R] +Simple tables look like this: +.IP +.EX + Right Left Center Default +------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 + +Table: Demonstration of simple table syntax. +.EE +.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 +.EX +------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 +------- ------ ---------- ------- +.EE +.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[CR]multiline_tables\f[R] +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 +.EX +------------------------------------------------------------- + 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. +.EE +.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 +.EX +----------- ------- --------------- ------------------------- + 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. +.EE +.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[CR]grid_tables\f[R] +Grid tables look like this: +.IP +.EX +: Sample grid table. + ++---------------+---------------+--------------------+ +| Fruit | Price | Advantages | ++===============+===============+====================+ +| Bananas | $1.34 | - built-in wrapper | +| | | - bright color | ++---------------+---------------+--------------------+ +| Oranges | $2.10 | - cures scurvy | +| | | - tasty | ++---------------+---------------+--------------------+ +.EE +.PP +The row of \f[CR]=\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.). +.PP +Cells can span multiple columns or rows: +.IP +.EX ++---------------------+----------+ +| Property | Earth | ++=============+=======+==========+ +| | min | -89.2 °C | +| Temperature +-------+----------+ +| 1961-1990 | mean | 14 °C | +| +-------+----------+ +| | max | 56.7 °C | ++-------------+-------+----------+ +.EE +.PP +A table header may contain more than one row: +.IP +.EX ++---------------------+-----------------------+ +| Location | Temperature 1961-1990 | +| | in degree Celsius | +| +-------+-------+-------+ +| | min | mean | max | ++=====================+=======+=======+=======+ +| Antarctica | -89.2 | N/A | 19.8 | ++---------------------+-------+-------+-------+ +| Earth | -89.2 | 14 | 56.7 | ++---------------------+-------+-------+-------+ +.EE +.PP +Alignments can be specified as with pipe tables, by putting colons at +the boundaries of the separator line after the header: +.IP +.EX ++---------------+---------------+--------------------+ +| Right | Left | Centered | ++==============:+:==============+:==================:+ +| Bananas | $1.34 | built-in wrapper | ++---------------+---------------+--------------------+ +.EE +.PP +For headerless tables, the colons go on the top line instead: +.IP +.EX ++--------------:+:--------------+:------------------:+ +| Right | Left | Centered | ++---------------+---------------+--------------------+ +.EE +.PP +A table foot can be defined by enclosing it with separator lines that +use \f[CR]=\f[R] instead of \f[CR]-\f[R]: +.IP +.EX + +---------------+---------------+ + | Fruit | Price | + +===============+===============+ + | Bananas | $1.34 | + +---------------+---------------+ + | Oranges | $2.10 | + +===============+===============+ + | Sum | $3.44 | + +===============+===============+ +.EE +.PP +The foot must always be placed at the very bottom of the table. +.PP +Grid tables can be created easily using Emacs\[cq] table-mode +(\f[CR]M-x table-insert\f[R]). +.SS Extension: \f[CR]pipe_tables\f[R] +Pipe tables look like this: +.IP +.EX +| Right | Left | Default | Center | +|------:|:-----|---------|:------:| +| 12 | 12 | 12 | 12 | +| 123 | 123 | 123 | 123 | +| 1 | 1 | 1 | 1 | + + : Demonstration of pipe table syntax. +.EE +.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 +.EX +fruit| price +-----|-----: +apple|2.05 +pear|1.37 +orange|3.09 +.EE +.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[CR]--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[CR]---|-\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 +.EX +| One | Two | +|-----+-------| +| my | table | +| is | nice | +.EE +.PP +The difference is that \f[CR]+\f[R] is used instead of \f[CR]|\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[CR]pandoc_title_block\f[R] +If the file begins with a title block +.IP +.EX +% title +% author(s) (separated by semicolons) +% date +.EE +.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 +.EX +% +% Author +.EE +.IP +.EX +% My title +% +% June 15, 2006 +.EE +.PP +The title may occupy multiple lines, but continuation lines must begin +with leading space, thus: +.IP +.EX +% My title + on multiple lines +.EE +.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 +.EX +% Author One + Author Two +.EE +.IP +.EX +% Author One; Author Two +.EE +.IP +.EX +% Author One; + Author Two +.EE +.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[CR]--standalone\f[R] (\f[CR]-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[CR]--title-prefix\f[R] or \f[CR]-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[CR]-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[CR]|\f[R]) should be used to separate the +footer text from the header text. +Thus, +.IP +.EX +% PANDOC(1) +.EE +.PP +will yield a man page with the title \f[CR]PANDOC\f[R] and section 1. +.IP +.EX +% PANDOC(1) Pandoc User Manuals +.EE +.PP +will also have \[lq]Pandoc User Manuals\[rq] in the footer. +.IP +.EX +% PANDOC(1) Pandoc User Manuals | Version 4.0 +.EE +.PP +will also have \[lq]Version 4.0\[rq] in the header. +.SS Extension: \f[CR]yaml_metadata_block\f[R] +A YAML metadata block is a valid YAML object, delimited by a line of +three hyphens (\f[CR]---\f[R]) at the top and a line of three hyphens +(\f[CR]---\f[R]) or three dots (\f[CR]...\f[R]) at the bottom. +The initial line \f[CR]---\f[R] must not be followed by a blank line. +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. +.PP +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 +.EX +pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html +.EE +.PP +Just be sure that the YAML file begins with \f[CR]---\f[R] and ends with +\f[CR]---\f[R] or \f[CR]...\f[R]. +Alternatively, you can use the \f[CR]--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[CR]yes\f[R], \f[CR]True\f[R], and \f[CR]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[CR]-t markdown\f[R] to create a Markdown +document, a YAML metadata block will be produced only if the +\f[CR]-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[CR]|\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 +.EX +--- +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. +\&... +.EE +.PP +The literal block after the \f[CR]|\f[R] must be indented relative to +the line containing the \f[CR]|\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[CR]abstract\f[R] +will be set to the HTML equivalent of the Markdown in the +\f[CR]abstract\f[R] field: +.IP +.EX +

This is the abstract.

+

It consists of two paragraphs.

+.EE +.PP +Variables can contain arbitrary YAML structures, but the template must +match this structure. +The \f[CR]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 +.EX +--- +title: The document title +author: +- name: Author One + affiliation: University of Somewhere +- name: Author Two + affiliation: University of Nowhere +\&... +.EE +.PP +To use the structured authors in the example above, you would need a +custom template: +.IP +.EX +$for(author)$ +$if(author.name)$ +$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$ +$else$ +$author$ +$endif$ +$endfor$ +.EE +.PP +Raw content to include in the document\[cq]s header may be specified +using \f[CR]header-includes\f[R]; however, it is important to mark up +this content as raw code for a particular output format, using the +\f[CR]raw_attribute\f[R] extension, or it will be interpreted as +markdown. +For example: +.IP +.EX +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] +.EE +.PP +Note: the \f[CR]yaml_metadata_block\f[R] extension works with +\f[CR]commonmark\f[R] as well as \f[CR]markdown\f[R] (and it is enabled +by default in \f[CR]gfm\f[R] and \f[CR]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[CR]all_symbols_escapable\f[R] +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 +.EX +*\[rs]*hello\[rs]** +.EE +.PP +one will get +.IP +.EX +*hello* +.EE +.PP +instead of +.IP +.EX +hello +.EE +.PP +This rule is easier to remember than original Markdown\[cq]s rule, which +allows only the following characters to be backslash-escaped: +.IP +.EX +\[rs]\[ga]*_{}[]()>#+-.! +.EE +.PP +(However, if the \f[CR]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[CR]\[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[CR]--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[CR]\[rs]\[rs]\f[R] and in HTML as +\f[CR]
\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 +To \f[I]emphasize\f[R] some text, surround it with \f[CR]*\f[R]s or +\f[CR]_\f[R], like this: +.IP +.EX +This text is _emphasized with underscores_, and this +is *emphasized with asterisks*. +.EE +.PP +Double \f[CR]*\f[R] or \f[CR]_\f[R] produces \f[B]strong emphasis\f[R]: +.IP +.EX +This is **strong emphasis** and __with underscores__. +.EE +.PP +A \f[CR]*\f[R] or \f[CR]_\f[R] character surrounded by spaces, or +backslash-escaped, will not trigger emphasis: +.IP +.EX +This is * not emphasized *, and \[rs]*neither is this\[rs]*. +.EE +.SS Extension: \f[CR]intraword_underscores\f[R] +Because \f[CR]_\f[R] is sometimes used inside words and identifiers, +pandoc does not interpret a \f[CR]_\f[R] surrounded by alphanumeric +characters as an emphasis marker. +If you want to emphasize just part of a word, use \f[CR]*\f[R]: +.IP +.EX +feas*ible*, not feas*able*. +.EE +.SS Strikeout +.SS Extension: \f[CR]strikeout\f[R] +To strike out a section of text with a horizontal line, begin and end it +with \f[CR]\[ti]\[ti]\f[R]. +Thus, for example, +.IP +.EX +This \[ti]\[ti]is deleted text.\[ti]\[ti] +.EE +.SS Superscripts and subscripts +.SS Extension: \f[CR]superscript\f[R], \f[CR]subscript\f[R] +Superscripts may be written by surrounding the superscripted text by +\f[CR]\[ha]\f[R] characters; subscripts may be written by surrounding +the subscripted text by \f[CR]\[ti]\f[R] characters. +Thus, for example, +.IP +.EX +H\[ti]2\[ti]O is a liquid. 2\[ha]10\[ha] is 1024. +.EE +.PP +The text between \f[CR]\[ha]...\[ha]\f[R] or \f[CR]\[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[CR]\[ti]\f[R] and \f[CR]\[ha]\f[R], and also bad +interactions with footnotes.) +Thus, if you want the letter P with `a cat' in subscripts, use +\f[CR]P\[ti]a\[rs] cat\[ti]\f[R], not \f[CR]P\[ti]a cat\[ti]\f[R]. +.SS Verbatim +To make a short span of text verbatim, put it inside backticks: +.IP +.EX +What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]? +.EE +.PP +If the verbatim text includes a backtick, use double backticks: +.IP +.EX +Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga]. +.EE +.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 +.EX +This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga]. +.EE +.SS Extension: \f[CR]inline_code_attributes\f[R] +Attributes can be attached to verbatim text, just as with fenced code +blocks: +.IP +.EX +\[ga]<$>\[ga]{.haskell} +.EE +.SS Underline +To underline text, use the \f[CR]underline\f[R] class: +.IP +.EX +[Underline]{.underline} +.EE +.PP +Or, without the \f[CR]bracketed_spans\f[R] extension (but with +\f[CR]native_spans\f[R]): +.IP +.EX +Underline +.EE +.PP +This will work in all output formats that support underline. +.SS Small caps +To write small caps, use the \f[CR]smallcaps\f[R] class: +.IP +.EX +[Small caps]{.smallcaps} +.EE +.PP +Or, without the \f[CR]bracketed_spans\f[R] extension: +.IP +.EX +Small caps +.EE +.PP +For compatibility with other Markdown flavors, CSS is also supported: +.IP +.EX +Small caps +.EE +.PP +This will work in all output formats that support small caps. +.SS Highlighting +To highlight text, use the \f[CR]mark\f[R] class: +.IP +.EX +[Mark]{.mark} +.EE +.PP +Or, without the \f[CR]bracketed_spans\f[R] extension (but with +\f[CR]native_spans\f[R]): +.IP +.EX +Mark +.EE +.PP +This will work in all output formats that support highlighting. +.SS Math +.SS Extension: \f[CR]tex_math_dollars\f[R] +Anything between two \f[CR]$\f[R] characters will be treated as TeX +math. +The opening \f[CR]$\f[R] must have a non-space character immediately to +its right, while the closing \f[CR]$\f[R] must have a non-space +character immediately to its left, and must not be followed immediately +by a digit. +Thus, \f[CR]$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[CR]$\f[R] +characters, backslash-escape them and they won\[cq]t be treated as math +delimiters. +.PP +For display math, use \f[CR]$$\f[R] delimiters. +(In this case, the delimiters may be separated from the formula by +whitespace. +However, there can be no blank lines between the opening and closing +\f[CR]$$\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[CR]\[rs](...\[rs])\f[R] (for +inline math) or \f[CR]\[rs][...\[rs]]\f[R] (for display math). +.TP +Markdown, Emacs Org mode, ConTeXt, ZimWiki +It will appear verbatim surrounded by \f[CR]$...$\f[R] (for inline math) +or \f[CR]$$...$$\f[R] (for display math). +.TP +XWiki +It will appear verbatim surrounded by +\f[CR]{{formula}}..{{/formula}}\f[R]. +.TP +reStructuredText +It will be rendered using an interpreted text role \f[CR]:math:\f[R]. +.TP +AsciiDoc +For AsciiDoc output math will appear verbatim surrounded by +\f[CR]latexmath:[...]\f[R]. +For \f[CR]asciidoc_legacy\f[R] the bracketed material will also include +inline or display math delimiters. +.TP +Texinfo +It will be rendered inside a \f[CR]\[at]math\f[R] command. +.TP +roff man, Jira markup +It will be rendered verbatim without \f[CR]$\f[R]\[cq]s. +.TP +MediaWiki, DokuWiki +It will be rendered inside \f[CR]\f[R] tags. +.TP +Textile +It will be rendered inside \f[CR]\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[CR]--mathml\f[R] flag is used, it will be rendered using +MathML in an \f[CR]inlineequation\f[R] or \f[CR]informalequation\f[R] +tag. +Otherwise it will be rendered, if possible, using Unicode characters. +.TP +Docx and PowerPoint +It will be rendered using OMML math markup. +.TP +FictionBook2 +If the \f[CR]--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[CR]raw_html\f[R] +Markdown allows you to insert raw HTML (or DocBook) anywhere in a +document (except verbatim contexts, where \f[CR]<\f[R], \f[CR]>\f[R], +and \f[CR]&\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[CR]raw_attribute\f[R] extension. +.PP +In the CommonMark format, if \f[CR]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[CR]raw_html\f[R] is disabled, tables will be +rendered with HTML syntax if they cannot use pipe syntax. +.SS Extension: \f[CR]markdown_in_html_blocks\f[R] +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[CR]*\f[R] does not signify emphasis. +.PP +Pandoc behaves this way when the \f[CR]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 +.EX + + + + + +
*one*[a link](https://google.com)
+.EE +.PP +into +.IP +.EX + + + + + +
onea link
+.EE +.PP +whereas \f[CR]Markdown.pl\f[R] will preserve it as is. +.PP +There is one exception to this rule: text between \f[CR] +HTML +\[dq]\[dq]\[dq]) +\[ga]\[ga]\[ga] + +## Image + +This image ![image](myimage.png) will be +included as a cell attachment. +.EE +.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 +.EX +:::::: {.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] +::: +:::::: +.EE +.PP +If you include raw HTML or TeX in an output cell, use the raw attribute, +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[CR]-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[CR]--wrap=preserve\f[R] will preserve soft line breaks +in Markdown cells; \f[CR]--markdown-headings=setext\f[R] will cause +Setext-style headings to be used; and \f[CR]--preserve-tabs\f[R] will +prevent tabs from being turned to spaces. +.SH SYNTAX HIGHLIGHTING +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[CR]pandoc --list-highlight-languages\f[R]. +.PP +The color scheme can be selected using the \f[CR]--highlight-style\f[R] +option. +The default color scheme is \f[CR]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[CR]pandoc --list-highlight-styles\f[R]. +.PP +If you are not satisfied with the predefined styles, you can use +\f[CR]--print-highlight-style\f[R] to generate a JSON \f[CR].theme\f[R] +file which can be modified and used as the argument to +\f[CR]--highlight-style\f[R]. +To get a JSON version of the \f[CR]pygments\f[R] style, for example: +.IP +.EX +pandoc --print-highlight-style pygments > my.theme +.EE +.PP +Then edit \f[CR]my.theme\f[R] and use it like this: +.IP +.EX +pandoc --highlight-style my.theme +.EE +.PP +If you are not satisfied with the built-in highlighting, or you want to +highlight a language that isn\[cq]t supported, you can use the +\f[CR]--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[CR]--no-highlight\f[R] option. +.SH CUSTOM STYLES +Custom styles can be used in the docx and ICML formats. +.SS Output +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[CR]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[CR]div\f[R]s and \f[CR]span\f[R]s, +respectively. +.PP +If you define a \f[CR]div\f[R] or \f[CR]span\f[R] with the attribute +\f[CR]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[CR]bracketed_spans\f[R] syntax, +.IP +.EX +[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said. +.EE +.PP +would produce a docx file with \[lq]Get out\[rq] styled with character +style \f[CR]Emphatically\f[R]. +Similarly, using the \f[CR]fenced_divs\f[R] syntax, +.IP +.EX +Dickinson starts the poem simply: + +::: {custom-style=\[dq]Poetry\[dq]} +| A Bird came down the Walk--- +| He did not know I saw--- +::: +.EE +.PP +would style the two contained lines with the \f[CR]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[CR]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[CR]Emphasis\f[R] custom-style \f[CR]span\f[R]. +.PP +For docx output, you don\[cq]t need to enable any extensions for custom +styles to work. +.SS Input +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[CR]styles\f[R] extension in the docx reader +(\f[CR]-f docx+styles\f[R]), you can produce output that maintains the +styles of the input document, using the \f[CR]custom-style\f[R] class. +Paragraph styles are interpreted as divs, while character styles are +interpreted as spans. +.PP +For example, using the \f[CR]custom-style-reference.docx\f[R] file in +the test directory, we have the following different outputs: +.PP +Without the \f[CR]+styles\f[R] extension: +.IP +.EX +$ 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. +.EE +.PP +And with the extension: +.IP +.EX +$ 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. +::: +.EE +.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 +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 +.EX +pandoc -t data/sample.lua +pandoc -f my_custom_markup_language.lua -t latex -s +.EE +.PP +If the script is not found relative to the working directory, it will be +sought in the \f[CR]custom\f[R] subdirectory of the user data directory +(see \f[CR]--data-dir\f[R]). +.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 +.EX +pandoc --print-default-data-file creole.lua +.EE +.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[CR]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. +See the djot-writer.lua for a full-featured example. +.PP +Note that custom writers have no default template. +If you want to use \f[CR]--standalone\f[R] with a custom writer, you +will need to specify a template manually using \f[CR]--template\f[R] or +add a new default template with the name +\f[CR]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[CR]templates\f[R] +subdirectory of your user data directory (see Templates). +.SH REPRODUCIBLE BUILDS +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[CR]SOURCE_DATE_EPOCH\f[R] environment +variable, and the timestamp will be taken from it instead of the current +time. +\f[CR]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp +(specifying the number of seconds 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[CR]identifier\f[R] metadata field (see EPUB Metadata, above). +.SH ACCESSIBLE PDFS AND PDF ARCHIVING STANDARDS +PDF is a flexible format, and using PDF in certain contexts requires +additional conventions. +For example, PDFs are not accessible by default; they define how +characters are placed on a page but do not contain semantic information +on the content. +However, it is possible to generate accessible PDFs, which use tagging +to add semantic information to the document. +.PP +Pandoc defaults to LaTeX to generate PDF. +Tagging support in LaTeX is in development and not readily available, so +PDFs generated in this way will always be untagged and not accessible. +This means that alternative engines must be used to generate accessible +PDFs. +.PP +The PDF standards PDF/A and PDF/UA define further restrictions intended +to optimize PDFs for archiving and accessibility. +Tagging is commonly used in combination with these standards to ensure +best results. +.PP +Note, however, that standard compliance depends on many things, +including the colorspace of embedded images. +Pandoc cannot check this, and external programs must be used to ensure +that generated PDFs are in compliance. +.SS ConTeXt +ConTeXt always produces tagged PDFs, but the quality depends on the +input. +The default ConTeXt markup generated by pandoc is optimized for +readability and reuse, not tagging. +Enable the \f[CR]tagging\f[R] format extension to force markup that is +optimized for tagging. +This can be combined with the \f[CR]pdfa\f[R] variable to generate +standard-compliant PDFs. +E.g.: +.IP +.EX +pandoc --to=context+tagging -V pdfa=3a +.EE +.PP +A recent \f[CR]context\f[R] version should be used, as older versions +contained a bug that lead to invalid PDF metadata. +.SS WeasyPrint +The HTML-based engine WeasyPrint includes experimental support for PDF/A +and PDF/UA since version 57. +Tagged PDFs can created with +.IP +.EX +pandoc --pdf-engine=weasyprint \[rs] + --pdf-engine-opt=--pdf-variant=pdf/ua-1 ... +.EE +.PP +The feature is experimental and standard compliance should not be +assumed. +.SS Prince XML +The non-free HTML-to-PDf converter \f[CR]prince\f[R] has extensive +support for various PDF standards as well as tagging. +E.g.: +.IP +.EX +pandoc --pdf-engine=prince \[rs] + --pdf-engine-opt=--tagged-pdf ... +.EE +.PP +See the prince documentation for more info. +.SS Word Processors +Word processors like LibreOffice and MS Word can also be used to +generate standardized and tagged PDF output. +Pandoc does not support direct conversions via these tools. +However, pandoc can convert a document to a \f[CR]docx\f[R] or +\f[CR]odt\f[R] file, which can then be opened and converted to PDF with +the respective word processor. +See the documentation for Word and LibreOffice. +.SH RUNNING PANDOC AS A WEB SERVER +If you rename (or symlink) the pandoc executable to +\f[CR]pandoc-server\f[R], or if you call pandoc with \f[CR]server\f[R] +as the first argument, it will start up a web server with a JSON API. +This server exposes most of the conversion functionality of pandoc. +For full documentation, see the pandoc-server man page. +.PP +If you rename (or symlink) the pandoc executable to +\f[CR]pandoc-server.cgi\f[R], it will function as a CGI program exposing +the same API as \f[CR]pandoc-server\f[R]. +.PP +\f[CR]pandoc-server\f[R] is designed to be maximally secure; it uses +Haskell\[cq]s type system to provide strong guarantees that no I/O will +be performed on the server during pandoc conversions. +.SH RUNNING PANDOC AS A LUA INTERPRETER +Calling the pandoc executable under the name \f[CR]pandoc-lua\f[R] or +with \f[CR]lua\f[R] as the first argument will make it function as a +standalone Lua interpreter. +The behavior is mostly identical to that of the standalone +\f[CR]lua\f[R] executable, version 5.4. +However, there is no REPL yet, and the \f[CR]-i\f[R] option has no +effect. +For full documentation, see the pandoc-lua man page. +.SH A NOTE ON SECURITY +.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[CR]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[CR]--sandbox\f[R] option can protect against this threat.) +.IP "3." 3 +Several output formats (including RTF, FB2, HTML with +\f[CR]--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[CR]--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[CR]PandocPure\f[R] monad. +See the document Using the pandoc API for more details. +(This corresponds to the use of the \f[CR]--sandbox\f[R] option on the +command line.) +.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[CR]+RTS -M512M -RTS\f[R] (for example) to limit the heap size +to 512MB. +Note that the \f[CR]commonmark\f[R] parser (including +\f[CR]commonmark_x\f[R] and \f[CR]gfm\f[R]) is much less vulnerable to +pathological performance than the \f[CR]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[CR]raw_html\f[R] is enabled for the Markdown input, users can +inject arbitrary HTML. +Even if \f[CR]raw_html\f[R] is disabled, users can include dangerous +content in URLs and attributes. +To be safe, you should run all HTML generated from untrusted user input +through an HTML sanitizer. +.SH AUTHORS 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. 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: 3.1.7 +version: 3.1.8 build-type: Simple license: GPL-2.0-or-later license-file: COPYING.md @@ -11,8 +11,8 @@ stability: alpha homepage: https://pandoc.org category: Text -tested-with: GHC == 8.6.5, GHC == 8.8.4, GHC == 8.10.7, GHC == 9.0.2, - GHC == 9.2.5, GHC == 9.4.4 +tested-with: GHC == 8.10.7, GHC == 9.0.2, + GHC == 9.2.5, GHC == 9.4.4, GHC == 9.6.1 synopsis: Conversion between markup formats description: Pandoc is a Haskell library for converting from one markup format to another. The formats it can handle include @@ -514,7 +514,7 @@ syb >= 0.1 && < 0.8, tagsoup >= 0.14.6 && < 0.15, temporary >= 1.1 && < 1.4, - texmath >= 0.12.8.1 && < 0.13, + texmath >= 0.12.8.2 && < 0.13, text >= 1.1.1.0 && < 2.2, text-conversions >= 0.3 && < 0.4, time >= 1.5 && < 1.14, diff --git a/src/Text/Pandoc/Citeproc.hs b/src/Text/Pandoc/Citeproc.hs --- a/src/Text/Pandoc/Citeproc.hs +++ b/src/Text/Pandoc/Citeproc.hs @@ -87,7 +87,7 @@ "csl-bib-body" : ["hanging-indent" | styleHangingIndent sopts] let refkvs = (case styleEntrySpacing sopts of - Just es | es > 0 -> (("entry-spacing",T.pack $ show es):) + Just es -> (("entry-spacing",T.pack $ show es):) _ -> id) . (case styleLineSpacing sopts of Just ls | ls > 1 -> (("line-spacing",T.pack $ show ls):) diff --git a/src/Text/Pandoc/Readers/JATS.hs b/src/Text/Pandoc/Readers/JATS.hs --- a/src/Text/Pandoc/Readers/JATS.hs +++ b/src/Text/Pandoc/Readers/JATS.hs @@ -39,6 +39,7 @@ import Data.Set ((\\)) import Text.Pandoc.Sources (ToSources(..), sourcesToText) import Safe (headMay) +import Text.Printf (printf) type JATS m = StateT JATSState m @@ -201,6 +202,7 @@ "journal-meta" -> parseMetadata e "article-meta" -> parseMetadata e "custom-meta" -> parseMetadata e + "processing-meta" -> return mempty "title" -> return mempty -- processed by header "label" -> return mempty -- processed by header "table" -> parseTable @@ -436,15 +438,27 @@ getPubDate :: PandocMonad m => Element -> JATS m () getPubDate e = case filterElement (named "pub-date") e of - Just d -> do - case maybeAttrValue "iso-8601-date" d of - Just isod -> addMeta "date" (text isod) - Nothing -> do - let yr = strContent <$> filterElement (named "year") d - let mon = strContent <$> filterElement (named "month") d - let day = strContent <$> filterElement (named "day") d - addMeta "date" $ text $ T.intercalate "-" $ catMaybes [yr, mon, day] + Just d -> getDate d >>= addMeta "date" . text Nothing -> pure () + +-- extract a structured date and create an ISO-8901 string date from it +getDate :: PandocMonad m => Element -> JATS m Text +getDate e = + case maybeAttrValue "iso-8601-date" e of + Just isod -> pure isod + Nothing -> do + let extractDate :: Element -> Maybe Int + extractDate = safeRead . strContent + let yr = filterElement (named "year") e >>= extractDate + let mon = filterElement (named "month") e >>= extractDate + let day = filterElement (named "day") e >>= extractDate + let stringDate = strContent <$> filterElement (named "string-date") e + pure $ + case (yr, mon, day) of + (Just y, Just m, Just d) -> T.pack $ printf "%04d-%02d-%02d" y m d + (Just y, Just m, Nothing) -> T.pack $ printf "%04d-%02d" y m + (Just y, Nothing, Nothing) -> T.pack $ printf "%04d" y + _ -> fromMaybe mempty stringDate getPermissions :: PandocMonad m => Element -> JATS m () getPermissions e = do 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 @@ -42,10 +42,6 @@ -- -- Functions acting on the parser state -- -recordAnchorId :: PandocMonad m => Text -> OrgParser m () -recordAnchorId i = updateState $ \s -> - s{ orgStateAnchorIds = i : orgStateAnchorIds s } - pushToInlineCharStack :: PandocMonad m => Char -> OrgParser m () pushToInlineCharStack c = updateState $ \s -> s{ orgStateEmphasisCharStack = c:orgStateEmphasisCharStack s } @@ -513,15 +509,9 @@ -- @anchor-id@ contains spaces, we are more restrictive in what is accepted as -- an anchor. anchor :: PandocMonad m => OrgParser m (F Inlines) -anchor = try $ do - anchorId <- parseAnchor - recordAnchorId anchorId +anchor = do + anchorId <- orgAnchor returnF $ B.spanWith (solidify anchorId, [], []) mempty - where - parseAnchor = string "<<" - *> many1Char (noneOf "\t\n\r<>\"' ") - <* string ">>" - <* skipSpaces -- | Replace every char but [a-zA-Z0-9_.-:] with a hyphen '-'. This mirrors -- the org function @org-export-solidify-link-text@. diff --git a/src/Text/Pandoc/Readers/Org/Parsing.hs b/src/Text/Pandoc/Readers/Org/Parsing.hs --- a/src/Text/Pandoc/Readers/Org/Parsing.hs +++ b/src/Text/Pandoc/Readers/Org/Parsing.hs @@ -29,6 +29,7 @@ , orgArgWordChar , orgTagWord , orgTagWordChar + , orgAnchor -- * Re-exports from Text.Pandoc.Parser , ParserContext (..) , textStr @@ -216,3 +217,16 @@ orgTagWordChar :: Monad m => OrgParser m Char orgTagWordChar = alphaNum <|> oneOf "@%#_" + +orgAnchor :: Monad m => OrgParser m Text +orgAnchor = try $ do + string "<<" + anchorId <- many1Char (noneOf "\t\n\r<>\"' ") + string ">>" + skipSpaces + recordAnchorId anchorId + return anchorId + +recordAnchorId :: Monad m => Text -> OrgParser m () +recordAnchorId i = updateState $ \s -> + s{ orgStateAnchorIds = i : orgStateAnchorIds s } 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 @@ -299,7 +299,7 @@ if null (stNotes st) then return mempty else do - notes <- footnoteSection EndOfDocument (stEmittedNotes st + 1) (reverse (stNotes st)) + notes <- footnoteSection opts EndOfDocument (stEmittedNotes st + 1) (reverse (stNotes st)) modify (\st' -> st'{ stNotes = mempty, stEmittedNotes = stEmittedNotes st' + length (stNotes st') }) return notes st <- get @@ -356,7 +356,6 @@ then defField "csl-css" True . (case stCslEntrySpacing st of Nothing -> id - Just 0 -> id Just n -> defField "csl-entry-spacing" (literal $ tshow n <> "em")) @@ -524,8 +523,8 @@ -- | Convert list of Note blocks to a footnote
. -- Assumes notes are sorted. footnoteSection :: - PandocMonad m => ReferenceLocation -> Int -> [Html] -> StateT WriterState m Html -footnoteSection refLocation startCounter notes = do + PandocMonad m => WriterOptions -> ReferenceLocation -> Int -> [Html] -> StateT WriterState m Html +footnoteSection opts refLocation startCounter notes = do html5 <- gets stHtml5 slideVariant <- gets stSlideVariant let hrtag = if refLocation /= EndOfBlock @@ -550,7 +549,7 @@ ! A5.class_ className ! A5.role "doc-endnotes" $ x - | html5 = H5.aside ! A5.id "footnotes" + | html5 = H5.aside ! prefixedId opts "footnotes" ! A5.class_ className ! A5.role "doc-endnotes" $ x @@ -805,7 +804,7 @@ if emitNotes then do st <- get - renderedNotes <- footnoteSection (writerReferenceLocation opts) + renderedNotes <- footnoteSection opts (writerReferenceLocation opts) (stEmittedNotes st + 1) (reverse notes) modify (\st' -> st'{ stNotes = mempty, stEmittedNotes = stEmittedNotes st' + length notes }) @@ -1084,7 +1083,8 @@ then do notes <- if null (stNotes st) then return mempty - else footnoteSection (writerReferenceLocation opts) (stEmittedNotes st + 1) (reverse (stNotes st)) + else footnoteSection opts (writerReferenceLocation opts) + (stEmittedNotes st + 1) (reverse (stNotes st)) modify (\st' -> st'{ stNotes = mempty, stEmittedNotes = stEmittedNotes st' + length (stNotes st') }) return (doc <> notes) else return doc 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 @@ -339,14 +339,13 @@ then do modify $ \st -> st{ stHasCslRefs = True } inner <- blockListToLaTeX bs - return $ (if "hanging-indent" `notElem` classes - then "\\setlength{\\cslhangindent}{0em}" - else mempty) - $$ ("\\setlength{\\cslentryspacing}" <> braces - (case lookup "entry-spacing" kvs of - Nothing -> "0em" - Just s -> (literal s <> "\\baselineskip"))) - $$ "\\begin{CSLReferences}" + return $ ("\\begin{CSLReferences}" + <> braces + (if "hanging-indent" `elem` classes + then "1" + else "0") + <> braces + (maybe "1" literal (lookup "entry-spacing" kvs))) $$ inner $+$ "\\end{CSLReferences}" else blockListToLaTeX bs @@ -569,8 +568,7 @@ [b] -> blockToLaTeX b bs -> mconcat . intersperse (cr <> "\\hfill") <$> mapM (toSubfigure (length bs)) bs - target <- hypertarget ident - let innards = target $$ "\\centering" $$ contents $$ caption <> cr + let innards = "\\centering" $$ contents $$ caption <> cr modify $ \st -> st{ stInFigure = isSubfigure , stSubfigure = stSubfigure st || isSubfigure diff --git a/test/command/4235.md b/test/command/4235.md --- a/test/command/4235.md +++ b/test/command/4235.md @@ -4,7 +4,7 @@ ^D

This.1

-