diff --git a/man/pandoc-lua.1 b/man/pandoc-lua.1 --- a/man/pandoc-lua.1 +++ b/man/pandoc-lua.1 @@ -1,13 +1,13 @@ -.\" Automatically generated by Pandoc 3.6.4 +.\" Automatically generated by Pandoc 3.7 .\" -.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.6.4" "Pandoc User\[cq]s Guide" +.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.7" "Pandoc User\[cq]s Guide" .SH SYNOPSIS \f[CR]pandoc\-lua\f[R] [\f[I]options\f[R]] [\f[I]script\f[R] [\f[I]args\f[R]]] .SH DESCRIPTION \f[CR]pandoc\-lua\f[R] is a standalone Lua interpreter with behavior similar to that of the standard \f[CR]lua\f[R] executable, but exposing -all of pandoc\[cq]s Lua libraries. +all of pandoc\(cqs Lua libraries. All \f[CR]pandoc.*\f[R] packages, as well as the packages \f[CR]re\f[R] and \f[CR]lpeg\f[R], are available via global variables. Furthermore, the globals \f[CR]PANDOC_VERSION\f[R], @@ -27,7 +27,7 @@ for an environment variable \f[CR]LUA_INIT\f[R] before running any argument. If the variable content has the format -\f[I]\f[CI]\[at]filename\f[I]\f[R], then \f[CR]pandoc\-lua\f[R] executes +\f[I]\f[CI]\(atfilename\f[I]\f[R], then \f[CR]pandoc\-lua\f[R] executes the file. Otherwise, \f[CR]pandoc\-lua\f[R] executes the string itself. .SH OPTIONS @@ -69,9 +69,9 @@ \f[CR]Ctrl\-C\f[R], or by typing \f[CR]os.exit()\f[R]. The \f[I]Isocline\f[R] library is used for line editing. Press \f[CR]F1\f[R] to get a list of available keybindings; the -\f[CR]ctrl\f[R] key is abbreviated as \f[CR]\[ha]\f[R] in that list. +\f[CR]ctrl\f[R] key is abbreviated as \f[CR]\(ha\f[R] in that list. .SH AUTHORS -Copyright 2023 John MacFarlane (jgm\[at]berkeley.edu) and contributors. +Copyright 2023 John MacFarlane (jgm\(atberkeley.edu) and contributors. Released under the GPL, version 2 or later. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) diff --git a/man/pandoc-server.1 b/man/pandoc-server.1 --- a/man/pandoc-server.1 +++ b/man/pandoc-server.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.6.4 +.\" Automatically generated by Pandoc 3.7 .\" -.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.6.4" "Pandoc User\[cq]s Guide" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.7" "Pandoc User\[cq]s Guide" .SH SYNOPSIS \f[CR]pandoc\-server\f[R] [\f[I]options\f[R]] .SH DESCRIPTION @@ -10,7 +10,7 @@ .PP To use \f[CR]pandoc\-server\f[R] as a CGI program, rename it (or symlink it) as \f[CR]pandoc\-server.cgi\f[R]. -(Note: if you symlink it, you may need to adjust your webserver\[cq]s +(Note: if you symlink it, you may need to adjust your webserver\(cqs configuration in order to allow it to follow symlinks for the CGI script.) .PP @@ -18,13 +18,13 @@ they can do no I/O operations on the server. This should provide a high degree of security. This security does, however, impose certain limitations: -.IP \[bu] 2 +.IP \(bu 2 PDFs cannot be produced. -.IP \[bu] 2 +.IP \(bu 2 Filters are not supported. -.IP \[bu] 2 +.IP \(bu 2 Resources cannot be fetched via HTTP. -.IP \[bu] 2 +.IP \(bu 2 Any images, include files, or other resources needed for the document conversion must be explicitly included in the request, via the \f[CR]files\f[R] field (see below under API). @@ -54,11 +54,11 @@ .SS Response It returns a converted document in one of the following formats (in order of preference), depending on the \f[CR]Accept\f[R] header: -.IP \[bu] 2 +.IP \(bu 2 \f[CR]application/octet\-stream\f[R] -.IP \[bu] 2 +.IP \(bu 2 \f[CR]text/plain\f[R] -.IP \[bu] 2 +.IP \(bu 2 \f[CR]application/json\f[R] .PP If the result is a binary format (e.g., \f[CR]epub\f[R] or @@ -69,22 +69,22 @@ If the conversion is not successful: .IP .EX -{ \[dq]error\[dq]: string with the error message } +{ \(dqerror\(dq: string with the error message } .EE .PP If the conversion is successful: .IP .EX -{ \[dq]output\[dq]: string with textual or base64\-encoded binary output, - \[dq]base64\[dq]: boolean (true means the \[dq]output\[dq] is base64\-encoded), - \[dq]messages\[dq]: array of message objects (see below) } +{ \(dqoutput\(dq: string with textual or base64\-encoded binary output, + \(dqbase64\(dq: boolean (true means the \(dqoutput\(dq is base64\-encoded), + \(dqmessages\(dq: array of message objects (see below) } .EE .PP -Each element of the \[lq]messages\[rq] array will have the format +Each element of the \(lqmessages\(rq array will have the format .IP .EX -{ \[dq]message\[dq]: string, - \[dq]verbosity\[dq]: string (either \[dq]WARNING\[dq] or \[dq]INFO\[dq]) } +{ \(dqmessage\(dq: string, + \(dqverbosity\(dq: string (either \(dqWARNING\(dq or \(dqINFO\(dq) } .EE .SS Request The body of the POST request should be a JSON object, with the following @@ -100,11 +100,11 @@ \f[CR]docx\f[R]), then \f[CR]text\f[R] should be a base64 encoding of the document. .TP -\f[CR]from\f[R] (string, default \f[CR]\[dq]markdown\[dq]\f[R]) +\f[CR]from\f[R] (string, default \f[CR]\(dqmarkdown\(dq\f[R]) The input format, possibly with extensions, just as it is specified on the pandoc command line. .TP -\f[CR]to\f[R] (string, default \f[CR]\[dq]html\[dq]\f[R]) +\f[CR]to\f[R] (string, default \f[CR]\(dqhtml\(dq\f[R]) The output format, possibly with extensions, just as it is specified on the pandoc command line. .TP @@ -116,7 +116,7 @@ .TP \f[CR]default\-image\-extension\f[R] (string) Extension to be applied to image sources that lack extensions -(e.g.\ \f[CR]\[dq].jpg\[dq]\f[R]). +(e.g.\ \f[CR]\(dq.jpg\(dq\f[R]). .TP \f[CR]metadata\f[R] (JSON map) String\-valued metadata. @@ -124,9 +124,9 @@ \f[CR]tab\-stop\f[R] (integer, default 4) Tab stop (spaces per tab). .TP -\f[CR]track\-changes\f[R] (\f[CR]\[dq]accept\[dq]|\[dq]reject\[dq]|\[dq]all\[dq]\f[R]) +\f[CR]track\-changes\f[R] (\f[CR]\(dqaccept\(dq|\(dqreject\(dq|\(dqall\(dq\f[R]) Specifies what to do with insertions, deletions, and comments produced -by the MS Word \[lq]Track Changes\[rq] feature. +by the MS Word \(lqTrack Changes\(rq feature. Only affects docx input. .TP \f[CR]abbreviations\f[R] (file path) @@ -150,12 +150,12 @@ Dots\-per\-inch to use for conversions between pixels and other measurements (for image sizes). .TP -\f[CR]wrap\f[R] (\f[CR]\[dq]auto\[dq]|\[dq]preserve\[dq]|\[dq]none\[dq]\f[R]) -Text wrapping option: either \f[CR]\[dq]auto\[dq]\f[R] (automatic +\f[CR]wrap\f[R] (\f[CR]\(dqauto\(dq|\(dqpreserve\(dq|\(dqnone\(dq\f[R]) +Text wrapping option: either \f[CR]\(dqauto\(dq\f[R] (automatic hard\-wrapping to fit within a column width), -\f[CR]\[dq]preserve\[dq]\f[R] (insert newlines where they are present in -the source), or \f[CR]\[dq]none\[dq]\f[R] (don\[cq]t insert any -unnecessary newlines at all). +\f[CR]\(dqpreserve\(dq\f[R] (insert newlines where they are present in +the source), or \f[CR]\(dqnone\(dq\f[R] (don\(cqt insert any unnecessary +newlines at all). .TP \f[CR]columns\f[R] (integer, default 72) Column width (affects text wrapping and calculation of table column @@ -179,11 +179,11 @@ .TP \f[CR]highlight\-style\f[R] (string, leave unset for no highlighting) Specify the style to use for syntax highlighting of code. -Standard styles are \f[CR]\[dq]pygments\[dq]\f[R] (the default), -\f[CR]\[dq]kate\[dq]\f[R], \f[CR]\[dq]monochrome\[dq]\f[R], -\f[CR]\[dq]breezeDark\[dq]\f[R], \f[CR]\[dq]espresso\[dq]\f[R], -\f[CR]\[dq]zenburn\[dq]\f[R], \f[CR]\[dq]haddock\[dq]\f[R], and -\f[CR]\[dq]tango\[dq]\f[R]. +Standard styles are \f[CR]\(dqpygments\(dq\f[R] (the default), +\f[CR]\(dqkate\(dq\f[R], \f[CR]\(dqmonochrome\(dq\f[R], +\f[CR]\(dqbreezeDark\(dq\f[R], \f[CR]\(dqespresso\(dq\f[R], +\f[CR]\(dqzenburn\(dq\f[R], \f[CR]\(dqhaddock\(dq\f[R], and +\f[CR]\(dqtango\(dq\f[R]. Alternatively, the path of a \f[CR].theme\f[R] with a KDE syntax theme may be used (in this case, the relevant file contents must also be included in \f[CR]files\f[R], see below). @@ -204,7 +204,7 @@ \f[CR]reference\-links\f[R] (boolean, default false) Create reference links rather than inline links in Markdown output. .TP -\f[CR]reference\-location\f[R] (\f[CR]\[dq]document\[dq]|\[dq]section\[dq]|\[dq]block\[dq]\f[R]) +\f[CR]reference\-location\f[R] (\f[CR]\(dqdocument\(dq|\(dqsection\(dq|\(dqblock\(dq\f[R]) Determines whether link references and footnotes are placed at the end of the document, the end of the section, or the end of the block (e.g.\ paragraph), in certain formats. @@ -214,10 +214,10 @@ Use Setext (underlined) headings instead of ATX (\f[CR]#\f[R]\-prefixed) in Markdown output. .TP -\f[CR]top\-level\-division\f[R] (\f[CR]\[dq]default\[dq]|\[dq]part\[dq]|\[dq]chapter\[dq]|\[dq]section\[dq]\f[R]) +\f[CR]top\-level\-division\f[R] (\f[CR]\(dqdefault\(dq|\(dqpart\(dq|\(dqchapter\(dq|\(dqsection\(dq\f[R]) Determines how top\-level headings are interpreted in LaTeX, ConTeXt, DocBook, and TEI. -The \f[CR]\[dq]default\[dq]\f[R] value tries to choose the best +The \f[CR]\(dqdefault\(dq\f[R] value tries to choose the best interpretation based on heuristics. .TP \f[CR]number\-sections\f[R] (boolean, default false) @@ -226,11 +226,11 @@ \f[CR]number\-offset\f[R] (array of integers) Offsets to be added to each component of the section number. For example, \f[CR][1]\f[R] will cause the first section to be numbered -\[lq]2\[rq] and the first subsection \[lq]2.1\[rq]; \f[CR][0,1]\f[R] -will cause the first section to be numbered \[lq]1\[rq] and the first -subsection \[lq]1.2.\[rq] +\(lq2\(rq and the first subsection \(lq2.1\(rq; \f[CR][0,1]\f[R] will +cause the first section to be numbered \(lq1\(rq and the first +subsection \(lq1.2.\(rq .TP -\f[CR]html\-math\-method\f[R] (\f[CR]\[dq]plain\[dq]|\[dq]webtex\[dq]|\[dq]gladtex\[dq]|\[dq]mathml\[dq]|\[dq]mathjax\[dq]|\[dq]katex\[dq]\f[R]) +\f[CR]html\-math\-method\f[R] (\f[CR]\(dqplain\(dq|\(dqwebtex\(dq|\(dqgladtex\(dq|\(dqmathml\(dq|\(dqmathjax\(dq|\(dqkatex\(dq\f[R]) Determines how math is represented in HTML. .TP \f[CR]listings\f[R] (boolean, default false) @@ -248,7 +248,7 @@ Arrange the document into a hierarchy of nested sections based on the headings. .TP -\f[CR]email\-obfuscation\f[R] (\f[CR]\[dq]none\[dq]|\[dq]references\[dq]|\[dq]javascript\[dq]\f[R]) +\f[CR]email\-obfuscation\f[R] (\f[CR]\(dqnone\(dq|\(dqreferences\(dq|\(dqjavascript\(dq\f[R]) Determines how email addresses are obfuscated in HTML. .TP \f[CR]identifier\-prefix\f[R] (string) @@ -276,14 +276,14 @@ metadata. The contents of the file must be included under \f[CR]files\f[R]. .TP -\f[CR]epub\-subdirectory\f[R] (string, default \[lq]EPUB\[rq]) +\f[CR]epub\-subdirectory\f[R] (string, default \(lqEPUB\(rq) Name of content subdirectory in the EPUB container. .TP \f[CR]epub\-fonts\f[R] (array of file paths) Fonts to include in the EPUB. The fonts themselves must be included in \f[CR]files\f[R] (see below). .TP -\f[CR]ipynb\-output\f[R] (\f[CR]\[dq]best\[dq]|\[dq]all\[dq]|\[dq]none\[dq]\f[R]) +\f[CR]ipynb\-output\f[R] (\f[CR]\(dqbest\(dq|\(dqall\(dq|\(dqnone\(dq\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. @@ -303,7 +303,7 @@ CSL style file. The contents of the file must be included in \f[CR]files\f[R]. .TP -\f[CR]cite\-method\f[R] (\f[CR]\[dq]citeproc\[dq]|\[dq]natbib\[dq]|\[dq]biblatex\[dq]\f[R]) +\f[CR]cite\-method\f[R] (\f[CR]\(dqciteproc\(dq|\(dqnatbib\(dq|\(dqbiblatex\(dq\f[R]) Determines how citations are formatted in LaTeX output. .TP \f[CR]files\f[R] (JSON mapping of file paths to base64\-encoded strings) @@ -315,10 +315,10 @@ .SS \f[CR]/batch\f[R] endpoint The \f[CR]/batch\f[R] endpoint behaves like the root endpoint, except for these two points: -.IP \[bu] 2 +.IP \(bu 2 It accepts a JSON array, each element of which is a JSON object like the one expected by the root endpoint. -.IP \[bu] 2 +.IP \(bu 2 It returns a JSON array of JSON results. .PP This endpoint can be used to convert a sequence of small snippets in one @@ -330,21 +330,21 @@ .SS \f[CR]/babelmark\f[R] endpoint The \f[CR]/babelmark\f[R] endpoint accepts a GET request with the following query parameters: -.IP \[bu] 2 +.IP \(bu 2 \f[CR]text\f[R] (required string) -.IP \[bu] 2 +.IP \(bu 2 \f[CR]from\f[R] (optional string, default is -\f[CR]\[dq]markdown\[dq]\f[R]) -.IP \[bu] 2 -\f[CR]to\f[R] (optional string, default is \f[CR]\[dq]html\[dq]\f[R]) -.IP \[bu] 2 +\f[CR]\(dqmarkdown\(dq\f[R]) +.IP \(bu 2 +\f[CR]to\f[R] (optional string, default is \f[CR]\(dqhtml\(dq\f[R]) +.IP \(bu 2 \f[CR]standalone\f[R] (optional boolean, default is \f[CR]false\f[R]) .PP It returns a JSON object with fields \f[CR]html\f[R] and \f[CR]version\f[R]. This endpoint is designed to support the Babelmark website. .SH AUTHORS -Copyright 2022 John MacFarlane (jgm\[at]berkeley.edu). +Copyright 2022 John MacFarlane (jgm\(atberkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) diff --git a/man/pandoc.1 b/man/pandoc.1 --- a/man/pandoc.1 +++ b/man/pandoc.1 @@ -1,7956 +1,7985 @@ -.\" Automatically generated by Pandoc 3.6.4 -.\" -.TH "pandoc" "1" "March 16, 2025" "pandoc 3.6.4" "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]multirow\f[R]] (if the document contains a -table with cells that cross multiple rows), \f[CR]graphicx\f[R] (if the -document contains images), \f[CR]bookmark\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 if -\f[CR]xelatex\f[R] is used, else \f[CR]luatexja\f[R] is needed if -\f[CR]lualatex\f[R] is used. -\f[CR]framed\f[R] is required if code is highlighted in a scheme that -use a colored background. -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] and \f[CR]lua\-ul\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), 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]bits\f[R] (BITS XML, alias for \f[CR]jats\f[R]) -.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]djot\f[R] (Djot markup) -.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]mdoc\f[R] (mdoc manual page markup) -.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] (OpenDocument text document) -.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]pod\f[R] (Perl\[cq]s Plain Old Documentation) -.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]ansi\f[R] (text with ANSI escape codes, for terminal viewing) -.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]djot\f[R] (Djot markup) -.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] (OpenDocument text document) -.IP \[bu] 2 -\f[CR]opml\f[R] (OPML) -.IP \[bu] 2 -\f[CR]opendocument\f[R] (OpenDocument XML) -.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\[em]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]. -.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 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 no extension is specified and an extensionless template is not found, -pandoc will look for a template with an extension corresponding to the -writer, so that \f[CR]\-\-template=special\f[R] looks for -\f[CR]special.html\f[R] for HTML output. -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 string 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]. -Structured values (lists, maps) cannot be assigned using this option, -but they can be assigned in the \f[CR]variables\f[R] section of a -defaults file. -.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]\-\-lof[=true|false]\f[R], \f[CR]\-\-list\-of\-figures[=true|false]\f[R] -Include an automatically generated list of figures (or, in some formats, -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 only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and -\f[CR]docx\f[R] output. -.TP -\f[CR]\-\-lot[=true|false]\f[R], \f[CR]\-\-list\-of\-tables[=true|false]\f[R] -Include an automatically generated list of tables (or, in some formats, -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 only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and -\f[CR]docx\f[R] output. -.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]. -Note that if the output format is \f[CR]odt\f[R], this file must be in -OpenDocument XML format suitable for insertion into the body of the -document, and if the output is \f[CR]docx\f[R], this file must be in -appropriate OpenXML format. -.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]. -Note that if the output format is \f[CR]odt\f[R], this file must be in -OpenDocument XML format suitable for insertion into the body of the -document, and if the output is \f[CR]docx\f[R], this file must be in -appropriate OpenXML format. -.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]. -Note that this option only has an effect when pandoc itself needs to -find an image (e.g., in producing a PDF or docx, or when -\f[CR]\-\-embed\-resources\f[R] is used.) -It will not cause image paths to be rewritten in other cases (e.g., when -pandoc is generating LaTeX or HTML). -.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. -.RS -.PP -For SVG images, \f[CR]img\f[R] tags with \f[CR]data:\f[R] URIs are used, -unless the image has the class \f[CR]inline\-svg\f[R], in which case an -inline SVG element is inserted. -This approach is recommended when there are many occurrences of the same -SVG in a document, as \f[CR]\f[R] elements will be used to reduce -duplication. -.RE -.TP -\f[CR]\-\-link\-images[=true|false]\f[R] -Include links to images instead of embedding the images in ODT. -(This option currently only affects ODT output.) -.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]\-\-figure\-caption\-position=above\f[R]|\f[CR]below\f[R] -Specify whether figure captions go above or below figures (default is -\f[CR]below\f[R]). -This option only affects HTML, LaTeX, Docx, ODT, and Typst output. -.TP -\f[CR]\-\-table\-caption\-position=above\f[R]|\f[CR]below\f[R] -Specify whether table captions go above or below tables (default is -\f[CR]above\f[R]). -This option only affects HTML, LaTeX, Docx, ODT, and Typst output. -.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. -.RS -.PP -In Docx output, this option adds section breaks before first\-level -headings if \f[CR]chapter\f[R] is selected, and before first\- and -second\-level headings if \f[CR]part\f[R] is selected. -Footnote numbers will restart with each section break unless the -reference doc modifies this. -.RE -.TP -\f[CR]\-N\f[R], \f[CR]\-\-number\-sections=[true|false]\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]] -Offsets for section heading numbers. -The first number is added to the section number for level\-1 headings, -the second for level\-2 headings, and so on. -So, for example, if you want the first level\-1 heading in your document -to be numbered \[lq]6\[rq] instead of \[lq]1\[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]. -\f[CR]\-\-number\-offset\f[R] only directly affects the number of the -first section heading in a document; subsequent numbers increment in the -normal way. -Implies \f[CR]\-\-number\-sections\f[R]. -Currently this feature only affects HTML and Docx output. -.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]revealjs\f[R], \f[CR]pptx\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 [for block quotes] -.IP \[bu] 2 -Footnote Block Text [for block quotes in footnotes] -.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]weasyprint\f[R] (other options: -\f[CR]prince\f[R], \f[CR]wkhtmltopdf\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. -.RS -.PP -Note: if this option is specified, the \f[CR]citations\f[R] extension -will be disabled automatically in the writer, to ensure that the -citeproc\-generated citations will be rendered instead of the -format\[cq]s own citation syntax. -.RE -.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\f[B]:\f[R] 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\f[B]:\f[R] ${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\f[B]:\f[R] ${.}/cover.jpg -epub\-metadata\f[B]:\f[R] ${.}/meta.xml -resource\-path\f[B]:\f[R] -\f[B]\-\f[R] .\f[I] # the working directory from which pandoc is run\f[R] -\f[B]\-\f[R] ${.}/images\f[I] # the images subdirectory of the directory\f[R] -\f[I] # containing this defaults file\f[R] -.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 - - \-\-citeproc \[rs] filters: - \- 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 - - \-\-link\-images link\-images: true - - \-\-html\-q\-tags html\-q\-tags: true - - \-\-ascii ascii: true - - \-\-reference\-links reference\-links: true - - \-\-reference\-location block reference\-location: block - - - \-\-figure\-caption\-position=above figure\-caption\-position: above - - table\-caption\-position: below - \-\-table\-caption\-position=below - - \-\-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 - - \-\-list\-of\-figures list\-of\-figures: true - - \-\-lof lof: true - - \-\-list\-of\-tables list\-of\-tables: true - - \-\-lot lot: 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 bibliography: logic.bib - - \-\-csl ieee.csl csl: ieee.csl - - - \-\-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 Reader options). -.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]docx\f[R] output, customize the \f[CR]default.openxml\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]pptx\f[R] has no template. -.PP -Note that \f[CR]docx\f[R], \f[CR]odt\f[R], and \f[CR]pptx\f[R] output -can also be customized using \f[CR]\-\-reference\-doc\f[R]. -Use a reference doc to adjust the styles in your document; use a -template to handle variable interpolation and customize the presentation -of metadata, the position of the table of contents, boilerplate text, -etc. -.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 true -value, otherwise the \f[CR]else\f[R] section is used (if present). -The following values count as true: -.IP \[bu] 2 -any map -.IP \[bu] 2 -any array containing at least one true value -.IP \[bu] 2 -any nonempty string -.IP \[bu] 2 -boolean True -.PP -Note that in YAML metadata (and metadata specified on the command line -using \f[CR]\-M/\-\-metadata\f[R]), unquoted \f[CR]true\f[R] and -\f[CR]false\f[R] will be interpreted as Boolean values. -But a variable specified on the command line using -\f[CR]\-V/\-\-variable\f[R] will always be given a string value. -Hence a conditional \f[CR]if(foo)\f[R] will be triggered if you use -\f[CR]\-V foo=false\f[R], but not if you use \f[CR]\-M foo=false\f[R]. -.PP -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 36em). -.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 \f[CR]\-\-katex\f[R], 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], \f[CR]colorthemeoptions\f[R], \f[CR]fontthemeoptions\f[R], \f[CR]innerthemeoptions\f[R], \f[CR]outerthemeoptions\f[R] -options for LaTeX beamer themes (lists) -.TP -\f[CR]titlegraphic\f[R] -image for title slide: can be a list -.TP -\f[CR]titlegraphicoptions\f[R] -options for title slide image -.TP -\f[CR]shorttitle\f[R], \f[CR]shortsubtitle\f[R], \f[CR]shortauthor\f[R], \f[CR]shortinstitute\f[R], \f[CR]shortdate\f[R] -some beamer themes use short versions of the title, subtitle, author, -institute, date -.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. -Note: if you set this variable, you must specify the beamer writer but -use the default \f[I]LaTeX\f[R] template: for example, -\f[CR]pandoc \-Vbeamerarticle \-t beamer \-\-template default.latex\f[R]. -.TP -\f[CR]handout\f[R] -produce a handout version of Beamer slides (with overlays condensed into -single slides) -.TP -\f[CR]csquotes\f[R] -load \f[CR]csquotes\f[R] package and use \f[CR]\[rs]enquote\f[R] or -\f[CR]\[rs]enquote*\f[R] for quoted text. -.TP -\f[CR]csquotesoptions\f[R] -options to use for \f[CR]csquotes\f[R] package (repeat for multiple -options). -.TP -\f[CR]babeloptions\f[R] -options to pass to the babel package (may be repeated for multiple -options). -This defaults to \f[CR]provide=*\f[R] if the main language isn\[cq]t a -European language written with Latin or Cyrillic script or Vietnamese. -Most users will not need to adjust the default setting. -.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 if -\f[CR]xelatex\f[R] is used, or the \f[CR]luatexja\f[R] package if -\f[CR]lualatex\f[R] is used. -.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], \f[CR]luatexjapresetoptions\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]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] -fonts to try if a glyph isn\[cq]t found in \f[CR]mainfont\f[R], -\f[CR]sansfont\f[R], or \f[CR]monofont\f[R] respectively. -These are lists. -The font name must be followed by a colon and optionally a set of -options, for example: -.RS -.IP -.EX -\-\-\- -mainfontfallback: - \- \[dq]FreeSans:\[dq] - \- \[dq]NotoColorEmoji:mode=harf\[dq] -\&... -.EE -.PP -Font fallbacks currently only work with \f[CR]lualatex\f[R]. -.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 -.IP -.EX -\-\-\- -babelfonts: - chinese\-hant: \[dq]Noto Serif CJK TC\[dq] - russian: \[dq]Noto Serif\[dq] -\&... -.EE -.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 (can also be set using -\f[CR]\-\-lof/\-\-list\-of\-figures\f[R], -\f[CR]\-\-lot/\-\-list\-of\-tables\f[R]) -.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]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] -list of fonts to try, in order, if a glyph is not found in the main -font. -Use \f[CR]\[rs]definefallbackfamily\f[R]\-compatible font name syntax. -Emoji fonts are unsupported. -.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 Texinfo -.TP -\f[CR]version\f[R] -version of software (used in title and title page) -.TP -\f[CR]filename\f[R] -name of info file to be generated (defaults to a name based on the texi -filename) -.SS Variables for Typst -.TP -\f[CR]template\f[R] -Typst template to use. -.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]page\-numbering\f[R] -Schema to use for numbering pages, e.g.\ \f[CR]1\f[R] or \f[CR]i\f[R], -or an empty string to omit page numbering. -.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). -Note that in docx and pptx a custom \f[CR]toc\-title\f[R] will be picked -up from metadata, but cannot be set as a variable. -.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_gfm\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], \f[CR]latex\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, add \f[CR]custom\-styles\f[R] attributes for -all docx styles, regardless of whether pandoc understands the meanings -of these styles. -Because attributes cannot be added directly to paragraphs or text in the -pandoc AST, paragraph styles will cause Divs to be created and character -styles will cause Spans to be created to hold the attributes. -(Table styles will be added to the Table elements directly.) -This extension can be used with docx custom styles. -.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] (typst) -When the \f[CR]citations\f[R] extension is enabled in \f[CR]typst\f[R] -(as it is by default), \f[CR]typst\f[R] citations will be parsed as -native pandoc citations, and native pandoc citations will be rendered as -\f[CR]typst\f[R] citations. -.SS Extension: \f[CR]citations\f[R] (org) -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, and org\-cite citations will be used to render native pandoc -citations. -.SS Extension: \f[CR]citations\f[R] (docx) -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] (org) -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. -.PD 0 -.P -.PD -\[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 (though -it can\[cq]t cross line boundaries). -Block\-level formatting (such as block quotes or lists) is not -recognized. -.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 -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. -.PP -You can repeat an earlier numbered example by re\-using its label: -.IP -.EX -(\[at]foo) Sample sentence. - -Intervening text... - -This theory can explain the case we saw earlier (repeated): - -(\[at]foo) Sample sentence. -.EE -.PP -This only works reliably, though, if the repeated item is in a list by -itself, because each numbered example list will be numbered continuously -from its starting number. -.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 date 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\[em]this is the title that will appear at the top of the window in -a browser\[em]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, Man, -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 \-o my.theme \-\-print\-highlight\-style pygments -.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 -If you receive an error that pandoc \[lq]Could not read highlighting -theme\[rq], check that the JSON file is encoded with UTF\-8 and has no -Byte\-Order Mark (BOM). -.PP -To disable highlighting, use the \f[CR]\-\-no\-highlight\f[R] option. -.SH CUSTOM STYLES -Custom styles can be used in the docx, odt and ICML formats. -.SS Output -By default, pandoc\[cq]s odt, 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 reference doc -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 Div, Span, or Table 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 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 -Styles will be defined in the output file as inheriting from normal text -(docx) or Default Paragraph Style (odt), if the styles are not yet in -your reference doc. -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 or odt 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. -A \f[CR]custom\-style\f[R] attribute will be added for each style. -Divs will be created to hold the paragraph styles, and Spans to hold the -character styles. -Table styles will be applied directly to the Table. -.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 Typst -Typst 0.12 can produce PDF/A\-2b: -.IP -.EX -pandoc \-\-pdf\-engine=typst \-\-pdf\-engine\-opt=\-\-pdf\-standard=a\-2b ... -.EE -.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. -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 LaTeX, Org, RST, and Typst) 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 -In reading HTML files, pandoc will attempt to include the contents of -\f[CR]iframe\f[R] elements by fetching content from the local file or -URL specified by \f[CR]src\f[R]. -If untrusted HTML is processed on a server, this has the potential to -reveal anything readable by the process running the server. -Using the \f[CR]\-f html+raw_html\f[R] will mitigate this threat by -causing the whole \f[CR]iframe\f[R] to be parsed as a raw HTML block. -Using \[ga]\[en]sandbox will also protect against the threat. -.IP "5." 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 "6." 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 "7." 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]2024 John MacFarlane (jgm\[at]berkeley.edu). +.\" Automatically generated by Pandoc 3.7 +.\" +.TH "pandoc" "1" "2025\-05\-14" "pandoc 3.7" "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\(cqs enhanced version of Markdown includes syntax for tables, +definition lists, metadata blocks, footnotes, citations, math, and much +more. +See below under Pandoc\(cqs 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\(cqs 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\(cqs simple document model. +While conversions from pandoc\(cqs Markdown to all formats aspire to be +perfect, conversions from formats more expressive than pandoc\(cqs +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\(cqs 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]multirow\f[R]] (if the document contains a +table with cells that cross multiple rows), \f[CR]graphicx\f[R] (if the +document contains images), \f[CR]bookmark\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 if +\f[CR]xelatex\f[R] is used, else \f[CR]luatexja\f[R] is needed if +\f[CR]lualatex\f[R] is used. +\f[CR]framed\f[R] is required if code is highlighted in a scheme that +use a colored background. +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] and \f[CR]lua\-ul\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), 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:\(dqMozilla/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]bits\f[R] (BITS XML, alias for \f[CR]jats\f[R]) +.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]djot\f[R] (Djot markup) +.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\(cqs 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]mdoc\f[R] (mdoc manual page markup) +.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] (OpenDocument text document) +.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]pod\f[R] (Perl\(cqs Plain Old Documentation) +.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]ansi\f[R] (text with ANSI escape codes, for terminal viewing) +.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]djot\f[R] (Djot markup) +.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\(cqs 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] (OpenDocument text document) +.IP \(bu 2 +\f[CR]opml\f[R] (OPML) +.IP \(bu 2 +\f[CR]opendocument\f[R] (OpenDocument XML) +.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%\(rspandoc\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\(cqs +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\(cqs 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\(emfor 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]. +.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\(cqs 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\(cqs 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\(cqs 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\(cqs 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 \(lqTrack 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 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 no extension is specified and an extensionless template is not found, +pandoc will look for a template with an extension corresponding to the +writer, so that \f[CR]\-\-template=special\f[R] looks for +\f[CR]special.html\f[R] for HTML output. +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 string value +\f[I]VAL\f[R] when rendering the document in standalone mode. +Either \f[CR]:\f[R] or \f[CR]=\f[R] may be used to separate +\f[I]KEY\f[R] from \f[I]VAL\f[R]. +If no \f[I]VAL\f[R] is specified, the key will be given the value +\f[CR]true\f[R]. +Structured values (lists, maps) cannot be assigned using this option, +but they can be assigned in the \f[CR]variables\f[R] section of a +defaults file or using the \f[CR]\-\-variable\-json\f[R] option. +If the variable already has a \f[I]list\f[R] value, the value will be +added to the list. +If it already has another kind of value, it will be made into a list +containing the previous and the new value. +For example, \f[CR]\-V keyword=Joe \-V author=Sue\f[R] makes +\f[CR]author\f[R] contain a list of strings: \f[CR]Joe\f[R] and +\f[CR]Sue\f[R]. +.TP +\f[CR]\-\-variable\-json=\f[R]\f[I]KEY\f[R][\f[CR]=\f[R]:\f[I]JSON\f[R]] +Set the template variable \f[I]KEY\f[R] to the value specified by a JSON +string (this may be a boolean, a string, a list, or a mapping; a number +will be treated as a string). +For example, \f[CR]\-\-variable\-json foo=false\f[R] will give +\f[CR]foo\f[R] the boolean false value, while +\f[CR]\-\-variable\-json foo=\(aq\(dqfalse\(dq\(aq\f[R] will give it the +string value \f[CR]\(dqfalse\(dq\f[R]. +Either \f[CR]:\f[R] or \f[CR]=\f[R] may be used to separate +\f[I]KEY\f[R] from \f[I]VAL\f[R]. +If the variable already has a value, this value will be replaced. +.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] and using (the +default) \f[CR]pdfroff\f[R] as a \f[CR]\-\-pdf\-engine\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]. +If \f[CR]groff\f[R] is used as the \f[CR]\-\-pdf\-engine\f[R], the table +of contents will always appear at the end of the document. +.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]\-\-lof[=true|false]\f[R], \f[CR]\-\-list\-of\-figures[=true|false]\f[R] +Include an automatically generated list of figures (or, in some formats, +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 only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and +\f[CR]docx\f[R] output. +.TP +\f[CR]\-\-lot[=true|false]\f[R], \f[CR]\-\-list\-of\-tables[=true|false]\f[R] +Include an automatically generated list of tables (or, in some formats, +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 only has an effect on \f[CR]latex\f[R], \f[CR]context\f[R], and +\f[CR]docx\f[R] output. +.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]\(rsbegin{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]. +Note that if the output format is \f[CR]odt\f[R], this file must be in +OpenDocument XML format suitable for insertion into the body of the +document, and if the output is \f[CR]docx\f[R], this file must be in +appropriate OpenXML format. +.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]\(rsend{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]. +Note that if the output format is \f[CR]odt\f[R], this file must be in +OpenDocument XML format suitable for insertion into the body of the +document, and if the output is \f[CR]docx\f[R], this file must be in +appropriate OpenXML format. +.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]. +Note that this option only has an effect when pandoc itself needs to +find an image (e.g., in producing a PDF or docx, or when +\f[CR]\-\-embed\-resources\f[R] is used.) +It will not cause image paths to be rewritten in other cases (e.g., when +pandoc is generating LaTeX or HTML). +.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\(cqre 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 \(lqself\-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=\(dq1\(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 \(lqself\-contained\(rq +\f[CR]reveal.js\f[R] slide show. +.RS +.PP +For SVG images, \f[CR]img\f[R] tags with \f[CR]data:\f[R] URIs are used, +unless the image has the class \f[CR]inline\-svg\f[R], in which case an +inline SVG element is inserted. +This approach is recommended when there are many occurrences of the same +SVG in a document, as \f[CR]\f[R] elements will be used to reduce +duplication. +.RE +.TP +\f[CR]\-\-link\-images[=true|false]\f[R] +Include links to images instead of embedding the images in ODT. +(This option currently only affects ODT output.) +.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]\-\-figure\-caption\-position=above\f[R]|\f[CR]below\f[R] +Specify whether figure captions go above or below figures (default is +\f[CR]below\f[R]). +This option only affects HTML, LaTeX, Docx, ODT, and Typst output. +.TP +\f[CR]\-\-table\-caption\-position=above\f[R]|\f[CR]below\f[R] +Specify whether table captions go above or below tables (default is +\f[CR]above\f[R]). +This option only affects HTML, LaTeX, Docx, ODT, and Typst output. +.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]\(rspart{..}\f[R], while second\-level headings remain as +their default type. +.RS +.PP +In Docx output, this option adds section breaks before first\-level +headings if \f[CR]chapter\f[R] is selected, and before first\- and +second\-level headings if \f[CR]part\f[R] is selected. +Footnote numbers will restart with each section break unless the +reference doc modifies this. +.RE +.TP +\f[CR]\-N\f[R], \f[CR]\-\-number\-sections=[true|false]\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]] +Offsets for section heading numbers. +The first number is added to the section number for level\-1 headings, +the second for level\-2 headings, and so on. +So, for example, if you want the first level\-1 heading in your document +to be numbered \(lq6\(rq instead of \(lq1\(rq, specify +\f[CR]\-\-number\-offset=5\f[R]. +If your document starts with a level\-2 heading which you want to be +numbered \(lq1.5\(rq, specify \f[CR]\-\-number\-offset=1,4\f[R]. +\f[CR]\-\-number\-offset\f[R] only directly affects the number of the +first section heading in a document; subsequent numbers increment in the +normal way. +Implies \f[CR]\-\-number\-sections\f[R]. +Currently this feature only affects HTML and Docx output. +.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]revealjs\f[R], \f[CR]pptx\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 [for block quotes] +.IP \(bu 2 +Footnote Block Text [for block quotes in footnotes] +.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 +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 +\(lqchunk.\(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 +\(atfont\-face { + font\-family: DejaVuSans; + font\-style: normal; + font\-weight: normal; + src:url(\(dq../fonts/DejaVuSans\-Regular.ttf\(dq); +} +\(atfont\-face { + font\-family: DejaVuSans; + font\-style: normal; + font\-weight: bold; + src:url(\(dq../fonts/DejaVuSans\-Bold.ttf\(dq); +} +\(atfont\-face { + font\-family: DejaVuSans; + font\-style: italic; + font\-weight: normal; + src:url(\(dq../fonts/DejaVuSans\-Oblique.ttf\(dq); +} +\(atfont\-face { + font\-family: DejaVuSans; + font\-style: italic; + font\-weight: bold; + src:url(\(dq../fonts/DejaVuSans\-BoldOblique.ttf\(dq); +} +body { font\-family: \(dqDejaVuSans\(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]groff\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]weasyprint\f[R] (other options: +\f[CR]prince\f[R], \f[CR]wkhtmltopdf\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] +.PP +This option is normally intended to be used when a PDF file is specified +as \f[CR]\-o/\-\-output\f[R]. +However, it may still have an effect when other output formats are +requested. +For example, \f[CR]ms\f[R] output will include \f[CR].pdfhref\f[R] +macros only if a \f[CR]\-\-pdf\-engine\f[R] is selected, and the macros +will be differently encoded depending on whether \f[CR]groff\f[R] or +\f[CR]pdfroff\f[R] is specified. +.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]\(cqs 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. +.RS +.PP +Note: if this option is specified, the \f[CR]citations\f[R] extension +will be disabled automatically in the writer, to ensure that the +citeproc\-generated citations will be rendered instead of the +format\(cqs own citation syntax. +.RE +.TP +\f[CR]\-\-bibliography=\f[R]\f[I]FILE\f[R] +Set the \f[CR]bibliography\f[R] field in the document\(cqs 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\(cqs 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\(cqs +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=\(dqmath\(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\(cqre 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\f[B]:\f[R] 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\f[B]:\f[R] ${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\f[B]:\f[R] ${.}/cover.jpg +epub\-metadata\f[B]:\f[R] ${.}/meta.xml +resource\-path\f[B]:\f[R] +\f[B]\-\f[R] .\f[I] # the working directory from which pandoc is run\f[R] +\f[B]\-\f[R] ${.}/images\f[I] # the images subdirectory of the directory\f[R] +\f[I] # containing this defaults file\f[R] +.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 python indented\-code\-classes: + \- python + + \-\-default\-image\-extension \(dq.jpg\(dq default\-image\-extension: \(aq.jpg\(aq + + \-\-file\-scope file\-scope: true + + \-\-citeproc \(rs filters: + \-\-lua\-filter count\-words.lua \(rs \- citeproc + \-\-filter special.lua \- count\-words.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\-definition mylang.xml syntax\-definitions: + \- mylang.xml + + syntax\-definition: mylang.xml + + \-\-include\-in\-header inc.tex include\-in\-header: + \- inc.tex + + \-\-include\-before\-body inc.tex include\-before\-body: + \- inc.tex + + \-\-include\-after\-body inc.tex include\-after\-body: + \- inc.tex + + \-\-resource\-path .:foo resource\-path: [\(aq.\(aq,\(aqfoo\(aq] + + \-\-request\-header foo:bar request\-headers: + \- [\(dqUser\-Agent\(dq, \(dqMozilla/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 + + \-\-link\-images link\-images: true + + \-\-html\-q\-tags html\-q\-tags: true + + \-\-ascii ascii: true + + \-\-reference\-links reference\-links: true + + \-\-reference\-location block reference\-location: block + + \-\-figure\-caption\-position=above figure\-caption\-position: above + + \-\-table\-caption\-position=below table\-caption\-position: below + + \-\-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 + + \-\-list\-of\-figures list\-of\-figures: true + + \-\-lof lof: true + + \-\-list\-of\-tables list\-of\-tables: true + + \-\-lot lot: 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\-embed\-font special.otf \(rs epub\-fonts: + \-\-epub\-embed\-font headline.otf \- special.otf + \- 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\-opt=\-\-shell\-escape pdf\-engine\-opts: + \- \(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 bibliography: logic.bib + + \-\-csl ieee.csl csl: ieee.csl + + \-\-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 Reader options). +.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]docx\f[R] output, customize the \f[CR]default.openxml\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]pptx\f[R] has no template. +.PP +Note that \f[CR]docx\f[R], \f[CR]odt\f[R], and \f[CR]pptx\f[R] output +can also be customized using \f[CR]\-\-reference\-doc\f[R]. +Use a reference doc to adjust the styles in your document; use a +template to handle variable interpolation and customize the presentation +of metadata, the position of the table of contents, boilerplate text, +etc. +.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\(cqs 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\(cqs 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 true +value, otherwise the \f[CR]else\f[R] section is used (if present). +The following values count as true: +.IP \(bu 2 +any map +.IP \(bu 2 +any array containing at least one true value +.IP \(bu 2 +any nonempty string +.IP \(bu 2 +boolean True +.PP +Note that in YAML metadata (and metadata specified on the command line +using \f[CR]\-M/\-\-metadata\f[R]), unquoted \f[CR]true\f[R] and +\f[CR]false\f[R] will be interpreted as Boolean values. +But a variable specified on the command line using +\f[CR]\-V/\-\-variable\f[R] will always be given a string value. +Hence a conditional \f[CR]if(foo)\f[R] will be triggered if you use +\f[CR]\-V foo=false\f[R], but not if you use \f[CR]\-M foo=false\f[R]. +.PP +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 \(lqnested,\(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\(cqs 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 \(dqleftborder\(dq \(dqrightborder\(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 \(dqleftborder\(dq \(dqrightborder\(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 \(dqleftborder\(dq \(dqrightborder\(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: \(aqThis is the title\(aq +subtitle: \(dqThis 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. [\(aqZitat 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\(cqd 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 36em). +.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 \f[CR]\-\-katex\f[R], 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\(ha5\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]\(rssetbeameroption{}\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 \(lqtitle 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], \f[CR]colorthemeoptions\f[R], \f[CR]fontthemeoptions\f[R], \f[CR]innerthemeoptions\f[R], \f[CR]outerthemeoptions\f[R] +options for LaTeX beamer themes (lists) +.TP +\f[CR]titlegraphic\f[R] +image for title slide: can be a list +.TP +\f[CR]titlegraphicoptions\f[R] +options for title slide image +.TP +\f[CR]shorttitle\f[R], \f[CR]shortsubtitle\f[R], \f[CR]shortauthor\f[R], \f[CR]shortinstitute\f[R], \f[CR]shortdate\f[R] +some beamer themes use short versions of the title, subtitle, author, +institute, date +.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]\(rsparagraph\f[R] and \f[CR]\(rssubparagraph\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]\(rssubsubsection\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: | + \(rsRedeclareSectionCommand[ + beforeskip=\-10pt plus \-2pt minus \-1pt, + afterskip=1sp plus \-1sp minus 1sp, + font=\(rsnormalfont\(rsitshape]{paragraph} + \(rsRedeclareSectionCommand[ + beforeskip=\-10pt plus \-2pt minus \-1pt, + afterskip=1sp plus \-1sp minus 1sp, + font=\(rsnormalfont\(rsscshape, + 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]\(rspagestyle{}\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. +Note: if you set this variable, you must specify the beamer writer but +use the default \f[I]LaTeX\f[R] template: for example, +\f[CR]pandoc \-Vbeamerarticle \-t beamer \-\-template default.latex\f[R]. +.TP +\f[CR]handout\f[R] +produce a handout version of Beamer slides (with overlays condensed into +single slides) +.TP +\f[CR]csquotes\f[R] +load \f[CR]csquotes\f[R] package and use \f[CR]\(rsenquote\f[R] or +\f[CR]\(rsenquote*\f[R] for quoted text. +.TP +\f[CR]csquotesoptions\f[R] +options to use for \f[CR]csquotes\f[R] package (repeat for multiple +options). +.TP +\f[CR]babeloptions\f[R] +options to pass to the babel package (may be repeated for multiple +options). +This defaults to \f[CR]provide=*\f[R] if the main language isn\(cqt a +European language written with Latin or Cyrillic script or Vietnamese. +Most users will not need to adjust the default setting. +.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 if +\f[CR]xelatex\f[R] is used, or the \f[CR]luatexja\f[R] package if +\f[CR]lualatex\f[R] is used. +.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], \f[CR]luatexjapresetoptions\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]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] +fonts to try if a glyph isn\(cqt found in \f[CR]mainfont\f[R], +\f[CR]sansfont\f[R], or \f[CR]monofont\f[R] respectively. +These are lists. +The font name must be followed by a colon and optionally a set of +options, for example: +.RS +.IP +.EX +\-\-\- +mainfontfallback: + \- \(dqFreeSans:\(dq + \- \(dqNotoColorEmoji:mode=harf\(dq +\&... +.EE +.PP +Font fallbacks currently only work with \f[CR]lualatex\f[R]. +.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 +.IP +.EX +\-\-\- +babelfonts: + chinese\-hant: \(dqNoto Serif CJK TC\(dq + russian: \(dqNoto Serif\(dq +\&... +.EE +.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 (can also be set using +\f[CR]\-\-lof/\-\-list\-of\-figures\f[R], +\f[CR]\-\-lot/\-\-list\-of\-tables\f[R]) +.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]mainfontfallback\f[R], \f[CR]sansfontfallback\f[R], \f[CR]monofontfallback\f[R] +list of fonts to try, in order, if a glyph is not found in the main +font. +Use \f[CR]\(rsdefinefallbackfamily\f[R]\-compatible font name syntax. +Emoji fonts are unsupported. +.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\(rsletterpercent\(rsspace (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 Texinfo +.TP +\f[CR]version\f[R] +version of software (used in title and title page) +.TP +\f[CR]filename\f[R] +name of info file to be generated (defaults to a name based on the texi +filename) +.SS Variables for Typst +.TP +\f[CR]template\f[R] +Typst template to use. +.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]page\-numbering\f[R] +Schema to use for numbering pages, e.g.\ \f[CR]1\f[R] or \f[CR]i\f[R], +or an empty string to omit page numbering. +.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\(cqs 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]pdf\-engine\f[R] +name of PDF engine if provided using \f[CR]\-\-pdf\-engine\f[R], or the +default engine for the format if PDF output is requested. +.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). +Note that in docx and pptx a custom \f[CR]toc\-title\f[R] will be picked +up from metadata, but cannot be set as a variable. +.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\(cqs +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\(cqs 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 +\(lqMr.\(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\(aqhô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\(cqs 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_gfm\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\(cqs 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\(cqs Markdown: +.IP \(bu 2 +\f[CR]raw_html\f[R] allows HTML elements which are not representable in +pandoc\(cqs 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]\(rsref\f[R], and \f[CR]\(rseqref\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\(cqt 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, \(lqbird track\(rq sections will be parsed as Haskell +code rather than block quotations. +Text between \f[CR]\(rsbegin{code}\f[R] and \f[CR]\(rsend{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, \(lqbird 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], \f[CR]latex\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, add \f[CR]custom\-styles\f[R] attributes for +all docx styles, regardless of whether pandoc understands the meanings +of these styles. +Because attributes cannot be added directly to paragraphs or text in the +pandoc AST, paragraph styles will cause Divs to be created and character +styles will cause Spans to be created to hold the attributes. +(Table styles will be added to the Table elements directly.) +This extension can be used with docx custom styles. +.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] (typst) +When the \f[CR]citations\f[R] extension is enabled in \f[CR]typst\f[R] +(as it is by default), \f[CR]typst\f[R] citations will be parsed as +native pandoc citations, and native pandoc citations will be rendered as +\f[CR]typst\f[R] citations. +.SS Extension: \f[CR]citations\f[R] (org) +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, and org\-cite citations will be used to render native pandoc +citations. +.SS Extension: \f[CR]citations\f[R] (docx) +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] (org) +Some aspects of Pandoc\(cqs 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\(cqs 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\(cqS MARKDOWN +Pandoc understands an extended and slightly revised version of John +Gruber\(cqs 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\(cqs been marked up with tags or +formatting instructions. +.PD 0 +.P +.PD +\(en John Gruber +.RE +.PP +This principle has guided pandoc\(cqs decisions in finding syntax for +tables, footnotes, and other extensions. +.PP +There is, however, one respect in which pandoc\(cqs 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 \(lqunderlined\(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\(cqt 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 \(lqlazy\(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 \(gablank_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=\(dq100\(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\(gahaskell +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\(gahaskell {.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\(aqve 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 (though +it can\(cqt cross line boundaries). +Block\-level formatting (such as block quotes or lists) is not +recognized. +.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 \(lqcompact\(rq list. +If you want a \(lqloose\(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 \(lqlazy\(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 \(lqlazily,\(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\(cqt 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 \(lqlazily\(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 \(lqlazy\(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 +(\(atgood) This is a good example. + +As (\(atgood) illustrates, ... +.EE +.PP +The label can be any string of alphanumeric characters, underscores, or +hyphens. +.PP +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. +.PP +You can repeat an earlier numbered example by re\-using its label: +.IP +.EX +(\(atfoo) Sample sentence. + +Intervening text... + +This theory can explain the case we saw earlier (repeated): + +(\(atfoo) Sample sentence. +.EE +.PP +This only works reliably, though, if the repeated item is in a list by +itself, because each numbered example list will be numbered continuously +from its starting number. +.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 \(lqcut off\(rq the list after item two, you can insert some +non\-indented content, like an HTML comment, which won\(cqt 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\(aqs another one. Note + the blank line between + rows. +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +Table: Here\(aqs 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\(aqs another one. Note + the blank line between + rows. +\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + +: Here\(aqs 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\(cqll 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 date 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\(emthis is the title that will appear at the top of the window in a +browser\(emand 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 \(lqtitle\(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 \(lqPandoc User Manuals\(rq in the footer. +.IP +.EX +% PANDOC(1) Pandoc User Manuals | Version 4.0 +.EE +.PP +will also have \(lqVersion 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: \(aqThis 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\(cqs 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} + \(rslet\(rsoldsection\(rssection + \(rsrenewcommand{\(rssection}[1]{\(rsclearpage\(rsoldsection{#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\(cqt 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\(cqs 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 \(lqinvisible\(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\(cqs \(lqinvisible\(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\(tiis 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\(ti2\(tiO is a liquid. 2\(ha10\(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\(tia\(rs cat\(ti\f[R], not \f[CR]P\(tia 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\(cqt 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\(cqt 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]\(atmath\f[R] command. +.TP +roff man, Jira markup +It will be rendered verbatim without \f[CR]$\f[R]\(cqs. +.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 \(lqblocks\(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(\(dqhello\(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 \(lqbare\(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, Man, +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 \-o my.theme \-\-print\-highlight\-style pygments +.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\(cqt 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\(cqs repository of syntax +definitions. +.PP +If you receive an error that pandoc \(lqCould not read highlighting +theme\(rq, check that the JSON file is encoded with UTF\-8 and has no +Byte\-Order Mark (BOM). +.PP +To disable highlighting, use the \f[CR]\-\-no\-highlight\f[R] option. +.SH CUSTOM STYLES +Custom styles can be used in the docx, odt and ICML formats. +.SS Output +By default, pandoc\(cqs odt, 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 reference doc +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 Div, Span, or Table 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=\(dqEmphatically\(dq}, he said. +.EE +.PP +would produce a file with \(lqGet 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=\(dqPoetry\(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 +Styles will be defined in the output file as inheriting from normal text +(docx) or Default Paragraph Style (odt), if the styles are not yet in +your reference doc. +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 or odt output, you don\(cqt 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\(cqs 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. +A \f[CR]custom\-style\f[R] attribute will be added for each style. +Divs will be created to hold the paragraph styles, and Spans to hold the +character styles. +Table styles will be applied directly to the Table. +.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=\(dqFirst Paragraph\(dq} +This is some text. +::: + +::: {custom\-style=\(dqBody Text\(dq} +This is text with an [emphasized]{custom\-style=\(dqEmphatic\(dq} text style. +And this is text with a [strengthened]{custom\-style=\(dqStrengthened\(dq} +text style. +::: + +::: {custom\-style=\(dqMy 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 Typst +Typst 0.12 can produce PDF/A\-2b: +.IP +.EX +pandoc \-\-pdf\-engine=typst \-\-pdf\-engine\-opt=\-\-pdf\-standard=a\-2b ... +.EE +.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\(cqs 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. +All \f[CR]pandoc.*\f[R] packages, as well as the packages \f[CR]re\f[R] +and \f[CR]lpeg\f[R], are available via global variables. +Furthermore, the globals \f[CR]PANDOC_VERSION\f[R], +\f[CR]PANDOC_STATE\f[R], and \f[CR]PANDOC_API_VERSION\f[R] are set at +startup. +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 LaTeX, Org, RST, and Typst) 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 +In reading HTML files, pandoc will attempt to include the contents of +\f[CR]iframe\f[R] elements by fetching content from the local file or +URL specified by \f[CR]src\f[R]. +If untrusted HTML is processed on a server, this has the potential to +reveal anything readable by the process running the server. +Using the \f[CR]\-f html+raw_html\f[R] will mitigate this threat by +causing the whole \f[CR]iframe\f[R] to be parsed as a raw HTML block. +Using \(ga\(ensandbox will also protect against the threat. +.IP "5." 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 "6." 3 +Pandoc\(cqs 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 "7." 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\(en2024 John MacFarlane (jgm\(atberkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.) diff --git a/pandoc-cli.cabal b/pandoc-cli.cabal --- a/pandoc-cli.cabal +++ b/pandoc-cli.cabal @@ -1,6 +1,6 @@ cabal-version: 2.4 name: pandoc-cli -version: 3.6.4 +version: 3.7 build-type: Simple license: GPL-2.0-or-later license-file: COPYING.md @@ -70,7 +70,7 @@ buildable: True -- Note: we always link to an exact version of pandoc, with the -- same version as this package: - build-depends: pandoc == 3.6.4, + build-depends: pandoc == 3.7, text other-modules: PandocCLI.Lua , PandocCLI.Server