diff --git a/man/pandoc-lua.1 b/man/pandoc-lua.1 new file mode 100644 --- /dev/null +++ b/man/pandoc-lua.1 @@ -0,0 +1,82 @@ +.\" Automatically generated by Pandoc 3.1.9 +.\" +.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.1.9" "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 \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. +.PP +If no script argument is given, then the script is assumed to be passed +in via \f[I]stdin\f[R]. +When called without arguments, \f[CR]pandoc-lua\f[R] behaves as +\f[CR]pandoc-lua -v -i\f[R] when the standard input (\f[CR]stdin\f[R]) +is a terminal, and as \f[CR]pandoc-lua -\f[R] otherwise. +On Windows the program will always behave as if it was connected to a +terminal. +.PP +When called without the option \f[CR]-E\f[R], the interpreter checks 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 +the file. +Otherwise, \f[CR]pandoc-lua\f[R] executes the string itself. +.SH OPTIONS +.TP +\f[CR]-e stat\f[R] +Execute statement \f[CR]stat\f[R]. +.TP +\f[CR]-l mod\f[R] +If mod has the pattern \f[CR]g=m\f[R], then require library \f[CR]m\f[R] +into global \f[CR]g\f[R]; otherwise require library \f[CR]mod\f[R] into +global \f[CR]mod\f[R]. +.TP +\f[CR]-v\f[R] +Show version information. +.TP +\f[CR]-i\f[R] +Enter interactive mode after running \f[I]script\f[R]. +.TP +\f[CR]-E\f[R] +Ignore environment variables. +This is not fully implemented yet and only ignores the +\f[CR]LUA_INIT\f[R] variable. +Other variables like \f[CR]LUA_PATH\f[R] and \f[CR]LUA_CPATH\f[R] are +\f[B]not\f[R] ignored. +.TP +\f[CR]-W\f[R] +Turn warnings on. +.SH INTERACTIVE MODE +In interactive mode, the Lua interpreter repeatedly prompts and waits +for a line. +After reading a line, Lua first tries to interpret the line as an +expression. +If it succeeds, it prints its value. +Otherwise, it interprets the line as a statement. +If you write an incomplete statement, the interpreter waits for its +completion by issuing a different prompt. +.PP +Exit the interactive mode by pressing \f[CR]Ctrl-D\f[R] or +\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. +.SH AUTHORS +Copyright 2023 John MacFarlane (jgm\[at]berkeley.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.) +.PP +Lua: Copyright 1994-2022 Lua.org, PUC-Rio. +.PP +The Pandoc source code may be downloaded +from or +. Further +documentation is available at . diff --git a/man/pandoc-server.1 b/man/pandoc-server.1 new file mode 100644 --- /dev/null +++ b/man/pandoc-server.1 @@ -0,0 +1,348 @@ +.\" Automatically generated by Pandoc 3.1.9 +.\" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.1.9" "Pandoc User\[cq]s Guide" +.SH SYNOPSIS +\f[CR]pandoc-server\f[R] [\f[I]options\f[R]] +.SH DESCRIPTION +\f[CR]pandoc-server\f[R] is a web server that can perform pandoc +conversions. +It can be used either as a running server or as a CGI program. +.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 +configuration in order to allow it to follow symlinks for the CGI +script.) +.PP +All pandoc functions are run in the PandocPure monad, which ensures that +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 +PDFs cannot be produced. +.IP \[bu] 2 +Filters are not supported. +.IP \[bu] 2 +Resources cannot be fetched via HTTP. +.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). +.SH OPTIONS +.TP +\f[CR]--port NUM\f[R] +HTTP port on which to run the server. +Default: 3030. +.TP +\f[CR]--timeout SECONDS\f[R] +Timeout in seconds, after which a conversion is killed. +Default: 2. +.RS +.PP +When \f[CR]pandoc-server\f[R] is run as a CGI program, this option can +be set via the \f[CR]PANDOC_SERVER_TIMEOUT\f[R] environment variable. +.RE +.TP +\f[CR]--help\f[R] +Print this help. +.TP +\f[CR]--version\f[R] +Print version. +.SH API +.SS Root endpoint +The root (\f[CR]/\f[R]) endpoint accepts only POST requests. +.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 +\f[CR]application/octet-stream\f[R] +.IP \[bu] 2 +\f[CR]text/plain\f[R] +.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 +\f[CR]docx\f[R]) and the content is returned as plain text or JSON, the +binary will be base64 encoded. +.PP +If a JSON response is given, it will have one of the following formats. +If the conversion is not successful: +.IP +.EX +{ \[dq]error\[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) } +.EE +.PP +Each element of the \[lq]messages\[rq] array will have the format +.IP +.EX +{ \[dq]message\[dq]: string, + \[dq]verbosity\[dq]: string (either \[dq]WARNING\[dq] or \[dq]INFO\[dq]) } +.EE +.SS Request +The body of the POST request should be a JSON object, with the following +fields. +Only the \f[CR]text\f[R] field is required; all of the others can be +omitted for default values. +When there are several string alternatives, the first one given is the +default. +.TP +\f[CR]text\f[R] (string) +The document to be converted. +Note: if the \f[CR]from\f[R] format is binary (e.g., \f[CR]epub\f[R] or +\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]) +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]) +The output format, possibly with extensions, just as it is specified on +the pandoc command line. +.TP +\f[CR]shift-heading-level-by\f[R] (integer, default 0) +Increase or decrease the level of all headings. +.TP +\f[CR]indented-code-classes\f[R] (array of strings) +List of classes to be applied to indented Markdown code blocks. +.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]). +.TP +\f[CR]metadata\f[R] (JSON map) +String-valued metadata. +.TP +\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]) +Specifies what to do with insertions, deletions, and comments produced +by the MS Word \[lq]Track Changes\[rq] feature. +Only affects docx input. +.TP +\f[CR]abbreviations\f[R] (file path) +List of strings to be regarded as abbreviations when parsing Markdown. +See \f[CR]--abbreviations\f[R] in \f[CR]pandoc(1)\f[R] for details. +.TP +\f[CR]standalone\f[R] (boolean, default false) +If true, causes a standalone document to be produced, using the default +template or the custom template specified using \f[CR]template\f[R]. +If false, a fragment will be produced. +.TP +\f[CR]template\f[R] (string) +String contents of a document template (see Templates in +\f[CR]pandoc(1)\f[R] for the format). +.TP +\f[CR]variables\f[R] (JSON map) +Variables to be interpolated in the template. +(See Templates in \f[CR]pandoc(1)\f[R].) +.TP +\f[CR]dpi\f[R] (integer, default 96) +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 +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). +.TP +\f[CR]columns\f[R] (integer, default 72) +Column width (affects text wrapping and calculation of table column +widths in plain text formats) +.TP +\f[CR]table-of-contents\f[R] (boolean, default false) +Include a table of contents (in supported formats). +.TP +\f[CR]toc-depth\f[R] (integer, default 3) +Depth of sections to include in the table of contents. +.TP +\f[CR]strip-comments\f[R] (boolean, default false) +Causes HTML comments to be stripped in Markdown or Textile source, +instead of being passed through to the output format. +.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]. +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). +.TP +\f[CR]embed-resources\f[R] +Embed images, scripts, styles and other resources in an HTML document +using \f[CR]data\f[R] URIs. +Note that this will not work unless the contents of all external +resources are included under \f[CR]files\f[R]. +.TP +\f[CR]html-q-tags\f[R] (boolean, default false) +Use \f[CR]\f[R] elements in HTML instead of literal quotation marks. +.TP +\f[CR]ascii\f[R] (boolean, default false) +Use entities and escapes when possible to avoid non-ASCII characters in +the output. +.TP +\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]) +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. +(See \f[CR]pandoc(1)\f[R] under \f[CR]--reference-location\f[R].) +.TP +\f[CR]setext-headers\f[R] (boolean, default false) +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]) +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 +interpretation based on heuristics. +.TP +\f[CR]number-sections\f[R] (boolean, default false) +Automatically number sections (in supported formats). +.TP +\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] +.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]) +Determines how math is represented in HTML. +.TP +\f[CR]listings\f[R] (boolean, default false) +Use the \f[CR]listings\f[R] package to format code in LaTeX output. +.TP +\f[CR]incremental\f[R] (boolean, default false) +If true, lists appear incrementally by default in slide shows. +.TP +\f[CR]slide-level\f[R] (integer) +Heading level that deterimes slide divisions in slide shows. +The default is to pick the highest heading level under which there is +body text. +.TP +\f[CR]section-divs\f[R] (boolean, default false) +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]) +Determines how email addresses are obfuscated in HTML. +.TP +\f[CR]identifier-prefix\f[R] (string) +Prefix to be added to all automatically-generated identifiers. +.TP +\f[CR]title-prefix\f[R] (string) +Prefix to be added to the title in the HTML header. +.TP +\f[CR]reference-doc\f[R] (file path) +Reference doc to use in creating \f[CR]docx\f[R] or \f[CR]odt\f[R] or +\f[CR]pptx\f[R]. +See \f[CR]pandoc(1)\f[R] under \f[CR]--reference-doc\f[R] for details. +The contents of the file must be included under \f[CR]files\f[R]. +.TP +\f[CR]split-level\f[R] (integer, default 1) +Heading level at which documents are split in EPUB or chunked HTML. +.TP +\f[CR]epub-cover-image\f[R] (file path) +Cover image for EPUB. +The contents of the file must be included under \f[CR]files\f[R]. +.TP +\f[CR]epub-metadata\f[R] (file path) +Path of file containing Dublin core XML elements to be used for EPUB +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]) +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]) +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. +.TP +\f[CR]citeproc\f[R] (boolean, default false) +Causes citations to be processed using citeproc. +See Citations in \f[CR]pandoc(1)\f[R] for details. +.TP +\f[CR]bibliography\f[R] (array of file paths) +Files containing bibliographic data. +The contents of the files must be included in \f[CR]files\f[R]. +.TP +\f[CR]csl\f[R] (file path) +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]) +Determines how citations are formatted in LaTeX output. +.TP +\f[CR]files\f[R] (JSON mapping of file paths to base64-encoded strings) +Any files needed for the conversion, including images referred to in the +document source, should be included here. +Binary data must be base64-encoded. +Textual data may be left as it is, unless it is \f[I]also\f[R] valid +base 64 data, in which case it will be interpreted that way. +.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 +It accepts a JSON array, each element of which is a JSON object like the +one expected by the root endpoint. +.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 +request. +.SS \f[CR]/version\f[R] endpoint +The \f[CR]/version\f[R] endpoint accepts a GET request and returns the +pandoc version as a plain or JSON-encoded string, depending on Accept +headers. +.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 +\f[CR]text\f[R] (required string) +.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]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). +Released under the GPL, version 2 or greater. +This software carries no warranty of any kind. +(See COPYRIGHT for full copyright and warranty notices.) +.PP +The Pandoc source code may be downloaded +from or +. Further +documentation is available at . diff --git a/man/pandoc.1 b/man/pandoc.1 new file mode 100644 --- /dev/null +++ b/man/pandoc.1 @@ -0,0 +1,7657 @@ +.\" Automatically generated by Pandoc 3.1.9 +.\" +.TH "pandoc" "1" "December 11, 2023" "pandoc 3.1.10" "Pandoc User\[cq]s Guide" +.SH NAME +pandoc - general markup converter +.SH SYNOPSIS +\f[CR]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]\&... +.SH DESCRIPTION +Pandoc is a Haskell library for converting from one markup format to +another, and a command-line tool that uses this library. +.PP +Pandoc can convert between numerous markup and word processing formats, +including, but not limited to, various flavors of Markdown, HTML, LaTeX +and Word docx. +For the full lists of input and output formats, see the +\f[CR]--from\f[R] and \f[CR]--to\f[R] options below. +Pandoc can also produce PDF output: see creating a PDF, below. +.PP +Pandoc\[cq]s enhanced version of Markdown includes syntax for tables, +definition lists, metadata blocks, footnotes, citations, math, and much +more. +See below under Pandoc\[cq]s Markdown. +.PP +Pandoc has a modular design: it consists of a set of readers, which +parse text in a given format and produce a native representation of the +document (an \f[I]abstract syntax tree\f[R] or AST), and a set of +writers, which convert this native representation into a target format. +Thus, adding an input or output format requires only adding a reader or +writer. +Users can also run custom pandoc filters to modify the intermediate AST. +.PP +Because pandoc\[cq]s intermediate representation of a document is less +expressive than many of the formats it converts between, one should not +expect perfect conversions between every format and every other. +Pandoc attempts to preserve the structural elements of a document, but +not formatting details such as margin size. +And some document elements, such as complex tables, may not fit into +pandoc\[cq]s simple document model. +While conversions from pandoc\[cq]s Markdown to all formats aspire to be +perfect, conversions from formats more expressive than pandoc\[cq]s +Markdown can be expected to be lossy. +.SS Using pandoc +If no \f[I]input-files\f[R] are specified, input is read from +\f[I]stdin\f[R]. +Output goes to \f[I]stdout\f[R] by default. +For output to a file, use the \f[CR]-o\f[R] option: +.IP +.EX +pandoc -o output.html input.txt +.EE +.PP +By default, pandoc produces a document fragment. +To produce a standalone document (e.g.\ a valid HTML file including +\f[CR]\f[R] and \f[CR]\f[R]), use the \f[CR]-s\f[R] or +\f[CR]--standalone\f[R] flag: +.IP +.EX +pandoc -s -o output.html input.txt +.EE +.PP +For more information on how standalone documents are produced, see +Templates below. +.PP +If multiple input files are given, pandoc will concatenate them all +(with blank lines between them) before parsing. +(Use \f[CR]--file-scope\f[R] to parse files individually.) +.SS Specifying formats +The format of the input and output can be specified explicitly using +command-line options. +The input format can be specified using the \f[CR]-f/--from\f[R] option, +the output format using the \f[CR]-t/--to\f[R] option. +Thus, to convert \f[CR]hello.txt\f[R] from Markdown to LaTeX, you could +type: +.IP +.EX +pandoc -f markdown -t latex hello.txt +.EE +.PP +To convert \f[CR]hello.html\f[R] from HTML to Markdown: +.IP +.EX +pandoc -f html -t markdown hello.html +.EE +.PP +Supported input and output formats are listed below under Options (see +\f[CR]-f\f[R] for input formats and \f[CR]-t\f[R] for output formats). +You can also use \f[CR]pandoc --list-input-formats\f[R] and +\f[CR]pandoc --list-output-formats\f[R] to print lists of supported +formats. +.PP +If the input or output format is not specified explicitly, pandoc will +attempt to guess it from the extensions of the filenames. +Thus, for example, +.IP +.EX +pandoc -o hello.tex hello.txt +.EE +.PP +will convert \f[CR]hello.txt\f[R] from Markdown to LaTeX. +If no output file is specified (so that output goes to +\f[I]stdout\f[R]), or if the output file\[cq]s extension is unknown, the +output format will default to HTML. +If no input file is specified (so that input comes from +\f[I]stdin\f[R]), or if the input files\[cq] extensions are unknown, the +input format will be assumed to be Markdown. +.SS Character encoding +Pandoc uses the UTF-8 character encoding for both input and output. +If your local character encoding is not UTF-8, you should pipe input and +output through \f[CR]iconv\f[R]: +.IP +.EX +iconv -t utf-8 input.txt | pandoc | iconv -f utf-8 +.EE +.PP +Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF, +OPML, DocBook, and Texinfo), information about the character encoding is +included in the document header, which will only be included if you use +the \f[CR]-s/--standalone\f[R] option. +.SS Creating a PDF +To produce a PDF, specify an output file with a \f[CR].pdf\f[R] +extension: +.IP +.EX +pandoc test.txt -o test.pdf +.EE +.PP +By default, pandoc will use LaTeX to create the PDF, which requires that +a LaTeX engine be installed (see \f[CR]--pdf-engine\f[R] below). +Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an +intermediate format. +To do this, specify an output file with a \f[CR].pdf\f[R] extension, as +before, but add the \f[CR]--pdf-engine\f[R] option or +\f[CR]-t context\f[R], \f[CR]-t html\f[R], or \f[CR]-t ms\f[R] to the +command line. +The tool used to generate the PDF from the intermediate format may be +specified using \f[CR]--pdf-engine\f[R]. +.PP +You can control the PDF style using variables, depending on the +intermediate format used: see variables for LaTeX, variables for +ConTeXt, variables for \f[CR]wkhtmltopdf\f[R], variables for ms. +When HTML is used as an intermediate format, the output can be styled +using \f[CR]--css\f[R]. +.PP +To debug the PDF creation, it can be useful to look at the intermediate +representation: instead of \f[CR]-o test.pdf\f[R], use for example +\f[CR]-s -o test.tex\f[R] to output the generated LaTeX. +You can then test it with \f[CR]pdflatex test.tex\f[R]. +.PP +When using LaTeX, the following packages need to be available (they are +included with all recent versions of TeX Live): \f[CR]amsfonts\f[R], +\f[CR]amsmath\f[R], \f[CR]lm\f[R], \f[CR]unicode-math\f[R], +\f[CR]iftex\f[R], \f[CR]listings\f[R] (if the \f[CR]--listings\f[R] +option is used), \f[CR]fancyvrb\f[R], \f[CR]longtable\f[R], +\f[CR]booktabs\f[R], \f[CR]graphicx\f[R] (if the document contains +images), \f[CR]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. +The use of \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R] as the PDF engine +requires \f[CR]fontspec\f[R]. +\f[CR]lualatex\f[R] uses \f[CR]selnolig\f[R]. +\f[CR]xelatex\f[R] uses \f[CR]bidi\f[R] (with the \f[CR]dir\f[R] +variable set). +If the \f[CR]mathspec\f[R] variable is set, \f[CR]xelatex\f[R] will use +\f[CR]mathspec\f[R] instead of \f[CR]unicode-math\f[R]. +The \f[CR]upquote\f[R] and \f[CR]microtype\f[R] packages are used if +available, and \f[CR]csquotes\f[R] will be used for typography if the +\f[CR]csquotes\f[R] variable or metadata field is set to a true value. +The \f[CR]natbib\f[R], \f[CR]biblatex\f[R], \f[CR]bibtex\f[R], and +\f[CR]biber\f[R] packages can optionally be used for citation rendering. +The following packages will be used to improve output quality if +present, but pandoc does not require them to be present: +\f[CR]upquote\f[R] (for straight quotes in verbatim environments), +\f[CR]microtype\f[R] (for better spacing adjustments), +\f[CR]parskip\f[R] (for better inter-paragraph spaces), \f[CR]xurl\f[R] +(for better line breaks in URLs), 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]docbook\f[R] (DocBook) +.IP \[bu] 2 +\f[CR]docx\f[R] (Word docx) +.IP \[bu] 2 +\f[CR]dokuwiki\f[R] (DokuWiki markup) +.IP \[bu] 2 +\f[CR]endnotexml\f[R] (EndNote XML bibliography) +.IP \[bu] 2 +\f[CR]epub\f[R] (EPUB) +.IP \[bu] 2 +\f[CR]fb2\f[R] (FictionBook2 e-book) +.IP \[bu] 2 +\f[CR]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less +accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only +if you need extensions not supported in \f[CR]gfm\f[R]. +.IP \[bu] 2 +\f[CR]haddock\f[R] (Haddock markup) +.IP \[bu] 2 +\f[CR]html\f[R] (HTML) +.IP \[bu] 2 +\f[CR]ipynb\f[R] (Jupyter notebook) +.IP \[bu] 2 +\f[CR]jats\f[R] (JATS XML) +.IP \[bu] 2 +\f[CR]jira\f[R] (Jira/Confluence wiki markup) +.IP \[bu] 2 +\f[CR]json\f[R] (JSON version of native AST) +.IP \[bu] 2 +\f[CR]latex\f[R] (LaTeX) +.IP \[bu] 2 +\f[CR]markdown\f[R] (Pandoc\[cq]s Markdown) +.IP \[bu] 2 +\f[CR]markdown_mmd\f[R] (MultiMarkdown) +.IP \[bu] 2 +\f[CR]markdown_phpextra\f[R] (PHP Markdown Extra) +.IP \[bu] 2 +\f[CR]markdown_strict\f[R] (original unextended Markdown) +.IP \[bu] 2 +\f[CR]mediawiki\f[R] (MediaWiki markup) +.IP \[bu] 2 +\f[CR]man\f[R] (roff man) +.IP \[bu] 2 +\f[CR]muse\f[R] (Muse) +.IP \[bu] 2 +\f[CR]native\f[R] (native Haskell) +.IP \[bu] 2 +\f[CR]odt\f[R] (ODT) +.IP \[bu] 2 +\f[CR]opml\f[R] (OPML) +.IP \[bu] 2 +\f[CR]org\f[R] (Emacs Org mode) +.IP \[bu] 2 +\f[CR]ris\f[R] (RIS bibliography) +.IP \[bu] 2 +\f[CR]rtf\f[R] (Rich Text Format) +.IP \[bu] 2 +\f[CR]rst\f[R] (reStructuredText) +.IP \[bu] 2 +\f[CR]t2t\f[R] (txt2tags) +.IP \[bu] 2 +\f[CR]textile\f[R] (Textile) +.IP \[bu] 2 +\f[CR]tikiwiki\f[R] (TikiWiki markup) +.IP \[bu] 2 +\f[CR]twiki\f[R] (TWiki markup) +.IP \[bu] 2 +\f[CR]typst\f[R] (typst) +.IP \[bu] 2 +\f[CR]vimwiki\f[R] (Vimwiki) +.IP \[bu] 2 +the path of a custom Lua reader, see Custom readers and writers below +.PP +Extensions can be individually enabled or disabled by appending +\f[CR]+EXTENSION\f[R] or \f[CR]-EXTENSION\f[R] to the format name. +See Extensions below, for a list of extensions and their names. +See \f[CR]--list-input-formats\f[R] and \f[CR]--list-extensions\f[R], +below. +.RE +.TP +\f[CR]-t\f[R] \f[I]FORMAT\f[R], \f[CR]-w\f[R] \f[I]FORMAT\f[R], \f[CR]--to=\f[R]\f[I]FORMAT\f[R], \f[CR]--write=\f[R]\f[I]FORMAT\f[R] +Specify output format. +\f[I]FORMAT\f[R] can be: +.RS +.IP \[bu] 2 +\f[CR]asciidoc\f[R] (modern AsciiDoc as interpreted by AsciiDoctor) +.IP \[bu] 2 +\f[CR]asciidoc_legacy\f[R] (AsciiDoc as interpreted by +\f[CR]asciidoc-py\f[R]). +.IP \[bu] 2 +\f[CR]asciidoctor\f[R] (deprecated synonym for \f[CR]asciidoc\f[R]) +.IP \[bu] 2 +\f[CR]beamer\f[R] (LaTeX beamer slide show) +.IP \[bu] 2 +\f[CR]bibtex\f[R] (BibTeX bibliography) +.IP \[bu] 2 +\f[CR]biblatex\f[R] (BibLaTeX bibliography) +.IP \[bu] 2 +\f[CR]chunkedhtml\f[R] (zip archive of multiple linked HTML files) +.IP \[bu] 2 +\f[CR]commonmark\f[R] (CommonMark Markdown) +.IP \[bu] 2 +\f[CR]commonmark_x\f[R] (CommonMark Markdown with extensions) +.IP \[bu] 2 +\f[CR]context\f[R] (ConTeXt) +.IP \[bu] 2 +\f[CR]csljson\f[R] (CSL JSON bibliography) +.IP \[bu] 2 +\f[CR]docbook\f[R] or \f[CR]docbook4\f[R] (DocBook 4) +.IP \[bu] 2 +\f[CR]docbook5\f[R] (DocBook 5) +.IP \[bu] 2 +\f[CR]docx\f[R] (Word docx) +.IP \[bu] 2 +\f[CR]dokuwiki\f[R] (DokuWiki markup) +.IP \[bu] 2 +\f[CR]epub\f[R] or \f[CR]epub3\f[R] (EPUB v3 book) +.IP \[bu] 2 +\f[CR]epub2\f[R] (EPUB v2) +.IP \[bu] 2 +\f[CR]fb2\f[R] (FictionBook2 e-book) +.IP \[bu] 2 +\f[CR]gfm\f[R] (GitHub-Flavored Markdown), or the deprecated and less +accurate \f[CR]markdown_github\f[R]; use \f[CR]markdown_github\f[R] only +if you need extensions not supported in \f[CR]gfm\f[R]. +.IP \[bu] 2 +\f[CR]haddock\f[R] (Haddock markup) +.IP \[bu] 2 +\f[CR]html\f[R] or \f[CR]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot +markup) +.IP \[bu] 2 +\f[CR]html4\f[R] (XHTML 1.0 Transitional) +.IP \[bu] 2 +\f[CR]icml\f[R] (InDesign ICML) +.IP \[bu] 2 +\f[CR]ipynb\f[R] (Jupyter notebook) +.IP \[bu] 2 +\f[CR]jats_archiving\f[R] (JATS XML, Archiving and Interchange Tag Set) +.IP \[bu] 2 +\f[CR]jats_articleauthoring\f[R] (JATS XML, Article Authoring Tag Set) +.IP \[bu] 2 +\f[CR]jats_publishing\f[R] (JATS XML, Journal Publishing Tag Set) +.IP \[bu] 2 +\f[CR]jats\f[R] (alias for \f[CR]jats_archiving\f[R]) +.IP \[bu] 2 +\f[CR]jira\f[R] (Jira/Confluence wiki markup) +.IP \[bu] 2 +\f[CR]json\f[R] (JSON version of native AST) +.IP \[bu] 2 +\f[CR]latex\f[R] (LaTeX) +.IP \[bu] 2 +\f[CR]man\f[R] (roff man) +.IP \[bu] 2 +\f[CR]markdown\f[R] (Pandoc\[cq]s Markdown) +.IP \[bu] 2 +\f[CR]markdown_mmd\f[R] (MultiMarkdown) +.IP \[bu] 2 +\f[CR]markdown_phpextra\f[R] (PHP Markdown Extra) +.IP \[bu] 2 +\f[CR]markdown_strict\f[R] (original unextended Markdown) +.IP \[bu] 2 +\f[CR]markua\f[R] (Markua) +.IP \[bu] 2 +\f[CR]mediawiki\f[R] (MediaWiki markup) +.IP \[bu] 2 +\f[CR]ms\f[R] (roff ms) +.IP \[bu] 2 +\f[CR]muse\f[R] (Muse) +.IP \[bu] 2 +\f[CR]native\f[R] (native Haskell) +.IP \[bu] 2 +\f[CR]odt\f[R] (OpenOffice text document) +.IP \[bu] 2 +\f[CR]opml\f[R] (OPML) +.IP \[bu] 2 +\f[CR]opendocument\f[R] (OpenDocument) +.IP \[bu] 2 +\f[CR]org\f[R] (Emacs Org mode) +.IP \[bu] 2 +\f[CR]pdf\f[R] (PDF) +.IP \[bu] 2 +\f[CR]plain\f[R] (plain text) +.IP \[bu] 2 +\f[CR]pptx\f[R] (PowerPoint slide show) +.IP \[bu] 2 +\f[CR]rst\f[R] (reStructuredText) +.IP \[bu] 2 +\f[CR]rtf\f[R] (Rich Text Format) +.IP \[bu] 2 +\f[CR]texinfo\f[R] (GNU Texinfo) +.IP \[bu] 2 +\f[CR]textile\f[R] (Textile) +.IP \[bu] 2 +\f[CR]slideous\f[R] (Slideous HTML and JavaScript slide show) +.IP \[bu] 2 +\f[CR]slidy\f[R] (Slidy HTML and JavaScript slide show) +.IP \[bu] 2 +\f[CR]dzslides\f[R] (DZSlides HTML5 + JavaScript slide show) +.IP \[bu] 2 +\f[CR]revealjs\f[R] (reveal.js HTML5 + JavaScript slide show) +.IP \[bu] 2 +\f[CR]s5\f[R] (S5 HTML and JavaScript slide show) +.IP \[bu] 2 +\f[CR]tei\f[R] (TEI Simple) +.IP \[bu] 2 +\f[CR]typst\f[R] (typst) +.IP \[bu] 2 +\f[CR]xwiki\f[R] (XWiki markup) +.IP \[bu] 2 +\f[CR]zimwiki\f[R] (ZimWiki markup) +.IP \[bu] 2 +the path of a custom Lua writer, see Custom readers and writers below +.PP +Note that \f[CR]odt\f[R], \f[CR]docx\f[R], \f[CR]epub\f[R], and +\f[CR]pdf\f[R] output will not be directed to \f[I]stdout\f[R] unless +forced with \f[CR]-o -\f[R]. +.PP +Extensions can be individually enabled or disabled by appending +\f[CR]+EXTENSION\f[R] or \f[CR]-EXTENSION\f[R] to the format name. +See Extensions below, for a list of extensions and their names. +See \f[CR]--list-output-formats\f[R] and \f[CR]--list-extensions\f[R], +below. +.RE +.TP +\f[CR]-o\f[R] \f[I]FILE\f[R], \f[CR]--output=\f[R]\f[I]FILE\f[R] +Write output to \f[I]FILE\f[R] instead of \f[I]stdout\f[R]. +If \f[I]FILE\f[R] is \f[CR]-\f[R], output will go to \f[I]stdout\f[R], +even if a non-textual format (\f[CR]docx\f[R], \f[CR]odt\f[R], +\f[CR]epub2\f[R], \f[CR]epub3\f[R]) is specified. +If the output format is \f[CR]chunkedhtml\f[R] and \f[I]FILE\f[R] has no +extension, then instead of producing a \f[CR].zip\f[R] file pandoc will +create a directory \f[I]FILE\f[R] and unpack the zip archive there +(unless \f[I]FILE\f[R] already exists, in which case an error will be +raised). +.TP +\f[CR]--data-dir=\f[R]\f[I]DIRECTORY\f[R] +Specify the user data directory to search for pandoc data files. +If this option is not specified, the default user data directory will be +used. +On *nix and macOS systems this will be the \f[CR]pandoc\f[R] +subdirectory of the XDG data directory (by default, +\f[CR]$HOME/.local/share\f[R], overridable by setting the +\f[CR]XDG_DATA_HOME\f[R] environment variable). +If that directory does not exist and \f[CR]$HOME/.pandoc\f[R] exists, it +will be used (for backwards compatibility). +On Windows the default user data directory is +\f[CR]%APPDATA%\[rs]pandoc\f[R]. +You can find the default user data directory on your system by looking +at the output of \f[CR]pandoc --version\f[R]. +Data files placed in this directory (for example, +\f[CR]reference.odt\f[R], \f[CR]reference.docx\f[R], +\f[CR]epub.css\f[R], \f[CR]templates\f[R]) will override pandoc\[cq]s +normal defaults. +(Note that the user data directory is not created by pandoc, so you will +need to create it yourself if you want to make use of it.) +.TP +\f[CR]-d\f[R] \f[I]FILE\f[R], \f[CR]--defaults=\f[R]\f[I]FILE\f[R] +Specify a set of default option settings. +\f[I]FILE\f[R] is a YAML file whose fields correspond to command-line +option settings. +All options for document conversion, including input and output files, +can be set using a defaults file. +The file will be searched for first in the working directory, and then +in the \f[CR]defaults\f[R] subdirectory of the user data directory (see +\f[CR]--data-dir\f[R]). +The \f[CR].yaml\f[R] extension may be omitted. +See the section Defaults files for more information on the file format. +Settings from the defaults file may be overridden or extended by +subsequent options on the command line. +.TP +\f[CR]--bash-completion\f[R] +Generate a bash completion script. +To enable bash completion with pandoc, add this to your +\f[CR].bashrc\f[R]: +.RS +.IP +.EX +eval \[dq]$(pandoc --bash-completion)\[dq] +.EE +.RE +.TP +\f[CR]--verbose\f[R] +Give verbose debugging output. +.TP +\f[CR]--quiet\f[R] +Suppress warning messages. +.TP +\f[CR]--fail-if-warnings[=true|false]\f[R] +Exit with error status if there are any warnings. +.TP +\f[CR]--log=\f[R]\f[I]FILE\f[R] +Write log messages in machine-readable JSON format to \f[I]FILE\f[R]. +All messages above DEBUG level will be written, regardless of verbosity +settings (\f[CR]--verbose\f[R], \f[CR]--quiet\f[R]). +.TP +\f[CR]--list-input-formats\f[R] +List supported input formats, one per line. +.TP +\f[CR]--list-output-formats\f[R] +List supported output formats, one per line. +.TP +\f[CR]--list-extensions\f[R][\f[CR]=\f[R]\f[I]FORMAT\f[R]] +List supported extensions for \f[I]FORMAT\f[R], one per line, preceded +by a \f[CR]+\f[R] or \f[CR]-\f[R] indicating whether it is enabled by +default in \f[I]FORMAT\f[R]. +If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown +are given. +.TP +\f[CR]--list-highlight-languages\f[R] +List supported languages for syntax highlighting, one per line. +.TP +\f[CR]--list-highlight-styles\f[R] +List supported styles for syntax highlighting, one per line. +See \f[CR]--highlight-style\f[R]. +.TP +\f[CR]-v\f[R], \f[CR]--version\f[R] +Print version. +.TP +\f[CR]-h\f[R], \f[CR]--help\f[R] +Show usage message. +.SS Reader options +.TP +\f[CR]--shift-heading-level-by=\f[R]\f[I]NUMBER\f[R] +Shift heading levels by a positive or negative integer. +For example, with \f[CR]--shift-heading-level-by=-1\f[R], level 2 +headings become level 1 headings, and level 3 headings become level 2 +headings. +Headings cannot have a level less than 1, so a heading that would be +shifted below level 1 becomes a regular paragraph. +Exception: with a shift of -N, a level-N heading at the beginning of the +document replaces the metadata title. +\f[CR]--shift-heading-level-by=-1\f[R] is a good choice when converting +HTML or Markdown documents that use an initial level-1 heading for the +document title and level-2+ headings for sections. +\f[CR]--shift-heading-level-by=1\f[R] may be a good choice for +converting Markdown documents that use level-1 headings for sections to +HTML, since pandoc uses a level-1 heading to render the document title. +.TP +\f[CR]--base-header-level=\f[R]\f[I]NUMBER\f[R] +\f[I]Deprecated. +Use \f[CI]--shift-heading-level-by\f[I]=X instead, where X = NUMBER - +1.\f[R] Specify the base level for headings (defaults to 1). +.TP +\f[CR]--indented-code-classes=\f[R]\f[I]CLASSES\f[R] +Specify classes to use for indented code blocks\[en]for example, +\f[CR]perl,numberLines\f[R] or \f[CR]haskell\f[R]. +Multiple classes may be separated by spaces or commas. +.TP +\f[CR]--default-image-extension=\f[R]\f[I]EXTENSION\f[R] +Specify a default extension to use when image paths/URLs have no +extension. +This allows you to use the same source for formats that require +different kinds of images. +Currently this option only affects the Markdown and LaTeX readers. +.TP +\f[CR]--file-scope[=true|false]\f[R] +Parse each file individually before combining for multifile documents. +This will allow footnotes in different files with the same identifiers +to work as expected. +If this option is set, footnotes and links will not work across files. +Reading binary files (docx, odt, epub) implies \f[CR]--file-scope\f[R]. +.RS +.PP +If two or more files are processed using \f[CR]--file-scope\f[R], +prefixes based on the filenames will be added to identifiers in order to +disambiguate them, and internal links will be adjusted accordingly. +For example, a header with identifier \f[CR]foo\f[R] in +\f[CR]subdir/file1.txt\f[R] will have its identifier changed to +\f[CR]subdir__file1.txt__foo\f[R]. +.PP +In addition, a Div with an identifier based on the filename will be +added around the file\[cq]s content, so that internal links to the +filename will point to this Div\[cq]s identifier. +.RE +.TP +\f[CR]-F\f[R] \f[I]PROGRAM\f[R], \f[CR]--filter=\f[R]\f[I]PROGRAM\f[R] +Specify an executable to be used as a filter transforming the pandoc AST +after the input is parsed and before the output is written. +The executable should read JSON from stdin and write JSON to stdout. +The JSON must be formatted like pandoc\[cq]s own JSON input and output. +The name of the output format will be passed to the filter as the first +argument. +Hence, +.RS +.IP +.EX +pandoc --filter ./caps.py -t latex +.EE +.PP +is equivalent to +.IP +.EX +pandoc -t json | ./caps.py latex | pandoc -f json -t latex +.EE +.PP +The latter form may be useful for debugging filters. +.PP +Filters may be written in any language. +\f[CR]Text.Pandoc.JSON\f[R] exports \f[CR]toJSONFilter\f[R] to +facilitate writing filters in Haskell. +Those who would prefer to write filters in python can use the module +\f[CR]pandocfilters\f[R], installable from PyPI. +There are also pandoc filter libraries in PHP, perl, and +JavaScript/node.js. +.PP +In order of preference, pandoc will look for filters in +.IP "1." 3 +a specified full or relative path (executable or non-executable), +.IP "2." 3 +\f[CR]$DATADIR/filters\f[R] (executable or non-executable) where +\f[CR]$DATADIR\f[R] is the user data directory (see +\f[CR]--data-dir\f[R], above), +.IP "3." 3 +\f[CR]$PATH\f[R] (executable only). +.PP +Filters, Lua-filters, and citeproc processing are applied in the order +specified on the command line. +.RE +.TP +\f[CR]-L\f[R] \f[I]SCRIPT\f[R], \f[CR]--lua-filter=\f[R]\f[I]SCRIPT\f[R] +Transform the document in a similar fashion as JSON filters (see +\f[CR]--filter\f[R]), but use pandoc\[cq]s built-in Lua filtering +system. +The given Lua script is expected to return a list of Lua filters which +will be applied in order. +Each Lua filter must contain element-transforming functions indexed by +the name of the AST element on which the filter function should be +applied. +.RS +.PP +The \f[CR]pandoc\f[R] Lua module provides helper functions for element +creation. +It is always loaded into the script\[cq]s Lua environment. +.PP +See the Lua filters documentation for further details. +.PP +In order of preference, pandoc will look for Lua filters in +.IP "1." 3 +a specified full or relative path, +.IP "2." 3 +\f[CR]$DATADIR/filters\f[R] where \f[CR]$DATADIR\f[R] is the user data +directory (see \f[CR]--data-dir\f[R], above). +.PP +Filters, Lua filters, and citeproc processing are applied in the order +specified on the command line. +.RE +.TP +\f[CR]-M\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]--metadata=\f[R]\f[I]KEY\f[R][\f[CR]:\f[R]\f[I]VAL\f[R]] +Set the metadata field \f[I]KEY\f[R] to the value \f[I]VAL\f[R]. +A value specified on the command line overrides a value specified in the +document using YAML metadata blocks. +Values will be parsed as YAML boolean or string values. +If no value is specified, the value will be treated as Boolean true. +Like \f[CR]--variable\f[R], \f[CR]--metadata\f[R] causes template +variables to be set. +But unlike \f[CR]--variable\f[R], \f[CR]--metadata\f[R] affects the +metadata of the underlying document (which is accessible from filters +and may be printed in some output formats) and metadata values will be +escaped when inserted into the template. +.TP +\f[CR]--metadata-file=\f[R]\f[I]FILE\f[R] +Read metadata from the supplied YAML (or JSON) file. +This option can be used with every input format, but string scalars in +the metadata file will always be parsed as Markdown. +(If the input format is Markdown or a Markdown variant, then the same +variant will be used to parse the metadata file; if it is a non-Markdown +format, pandoc\[cq]s default Markdown extensions will be used.) +This option can be used repeatedly to include multiple metadata files; +values in files specified later on the command line will be preferred +over those specified in earlier files. +Metadata values specified inside the document, or by using +\f[CR]-M\f[R], overwrite values specified with this option. +The file will be searched for first in the working directory, and then +in the \f[CR]metadata\f[R] subdirectory of the user data directory (see +\f[CR]--data-dir\f[R]). +.TP +\f[CR]-p\f[R], \f[CR]--preserve-tabs[=true|false]\f[R] +Preserve tabs instead of converting them to spaces. +(By default, pandoc converts tabs to spaces before parsing its input.) +Note that this will only affect tabs in literal code spans and code +blocks. +Tabs in regular text are always treated as spaces. +.TP +\f[CR]--tab-stop=\f[R]\f[I]NUMBER\f[R] +Specify the number of spaces per tab (default is 4). +.TP +\f[CR]--track-changes=accept\f[R]|\f[CR]reject\f[R]|\f[CR]all\f[R] +Specifies what to do with insertions, deletions, and comments produced +by the MS Word \[lq]Track Changes\[rq] feature. +\f[CR]accept\f[R] (the default) processes all the insertions and +deletions. +\f[CR]reject\f[R] ignores them. +Both \f[CR]accept\f[R] and \f[CR]reject\f[R] ignore comments. +\f[CR]all\f[R] includes all insertions, deletions, and comments, wrapped +in spans with \f[CR]insertion\f[R], \f[CR]deletion\f[R], +\f[CR]comment-start\f[R], and \f[CR]comment-end\f[R] classes, +respectively. +The author and time of change is included. +\f[CR]all\f[R] is useful for scripting: only accepting changes from a +certain reviewer, say, or before a certain date. +If a paragraph is inserted or deleted, \f[CR]track-changes=all\f[R] +produces a span with the class +\f[CR]paragraph-insertion\f[R]/\f[CR]paragraph-deletion\f[R] before the +affected paragraph break. +This option only affects the docx reader. +.TP +\f[CR]--extract-media=\f[R]\f[I]DIR\f[R] +Extract images and other media contained in or linked from the source +document to the path \f[I]DIR\f[R], creating it if necessary, and adjust +the images references in the document so they point to the extracted +files. +Media are downloaded, read from the file system, or extracted from a +binary container (e.g.\ docx), as needed. +The original file paths are used if they are relative paths not +containing \f[CR]..\f[R]. +Otherwise filenames are constructed from the SHA1 hash of the contents. +.TP +\f[CR]--abbreviations=\f[R]\f[I]FILE\f[R] +Specifies a custom abbreviations file, with abbreviations one to a line. +If this option is not specified, pandoc will read the data file +\f[CR]abbreviations\f[R] from the user data directory or fall back on a +system default. +To see the system default, use +\f[CR]pandoc --print-default-data-file=abbreviations\f[R]. +The only use pandoc makes of this list is in the Markdown reader. +Strings found in this list will be followed by a nonbreaking space, and +the period will not produce sentence-ending space in formats like LaTeX. +The strings may not contain spaces. +.TP +\f[CR]--trace[=true|false]\f[R] +Print diagnostic output tracing parser progress to stderr. +This option is intended for use by developers in diagnosing performance +issues. +.SS General writer options +.TP +\f[CR]-s\f[R], \f[CR]--standalone\f[R] +Produce output with an appropriate header and footer (e.g.\ a standalone +HTML, LaTeX, TEI, or RTF file, not a fragment). +This option is set automatically for \f[CR]pdf\f[R], \f[CR]epub\f[R], +\f[CR]epub3\f[R], \f[CR]fb2\f[R], \f[CR]docx\f[R], and \f[CR]odt\f[R] +output. +For \f[CR]native\f[R] output, this option causes metadata to be +included; otherwise, metadata is suppressed. +.TP +\f[CR]--template=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] +Use the specified file as a custom template for the generated document. +Implies \f[CR]--standalone\f[R]. +See Templates, below, for a description of template syntax. +If no extension is specified, an extension corresponding to the writer +will be added, so that \f[CR]--template=special\f[R] looks for +\f[CR]special.html\f[R] for HTML output. +If the template is not found, pandoc will search for it in the +\f[CR]templates\f[R] subdirectory of the user data directory (see +\f[CR]--data-dir\f[R]). +If this option is not used, a default template appropriate for the +output format will be used (see \f[CR]-D/--print-default-template\f[R]). +.TP +\f[CR]-V\f[R] \f[I]KEY\f[R][\f[CR]=\f[R]\f[I]VAL\f[R]], \f[CR]--variable=\f[R]\f[I]KEY\f[R][\f[CR]:\f[R]\f[I]VAL\f[R]] +Set the template variable \f[I]KEY\f[R] to the value \f[I]VAL\f[R] when +rendering the document in standalone mode. +If no \f[I]VAL\f[R] is specified, the key will be given the value +\f[CR]true\f[R]. +.TP +\f[CR]--sandbox[=true|false]\f[R] +Run pandoc in a sandbox, limiting IO operations in readers and writers +to reading the files specified on the command line. +Note that this option does not limit IO operations by filters or in the +production of PDF documents. +But it does offer security against, for example, disclosure of files +through the use of \f[CR]include\f[R] directives. +Anyone using pandoc on untrusted user input should use this option. +.RS +.PP +Note: some readers and writers (e.g., \f[CR]docx\f[R]) need access to +data files. +If these are stored on the file system, then pandoc will not be able to +find them when run in \f[CR]--sandbox\f[R] mode and will raise an error. +For these applications, we recommend using a pandoc binary compiled with +the \f[CR]embed_data_files\f[R] option, which causes the data files to +be baked into the binary instead of being stored on the file system. +.RE +.TP +\f[CR]-D\f[R] \f[I]FORMAT\f[R], \f[CR]--print-default-template=\f[R]\f[I]FORMAT\f[R] +Print the system default template for an output \f[I]FORMAT\f[R]. +(See \f[CR]-t\f[R] for a list of possible \f[I]FORMAT\f[R]s.) +Templates in the user data directory are ignored. +This option may be used with \f[CR]-o\f[R]/\f[CR]--output\f[R] to +redirect output to a file, but \f[CR]-o\f[R]/\f[CR]--output\f[R] must +come before \f[CR]--print-default-template\f[R] on the command line. +.RS +.PP +Note that some of the default templates use partials, for example +\f[CR]styles.html\f[R]. +To print the partials, use \f[CR]--print-default-data-file\f[R]: for +example, \f[CR]--print-default-data-file=templates/styles.html\f[R]. +.RE +.TP +\f[CR]--print-default-data-file=\f[R]\f[I]FILE\f[R] +Print a system default data file. +Files in the user data directory are ignored. +This option may be used with \f[CR]-o\f[R]/\f[CR]--output\f[R] to +redirect output to a file, but \f[CR]-o\f[R]/\f[CR]--output\f[R] must +come before \f[CR]--print-default-data-file\f[R] on the command line. +.TP +\f[CR]--eol=crlf\f[R]|\f[CR]lf\f[R]|\f[CR]native\f[R] +Manually specify line endings: \f[CR]crlf\f[R] (Windows), \f[CR]lf\f[R] +(macOS/Linux/UNIX), or \f[CR]native\f[R] (line endings appropriate to +the OS on which pandoc is being run). +The default is \f[CR]native\f[R]. +.TP +\f[CR]--dpi\f[R]=\f[I]NUMBER\f[R] +Specify the default dpi (dots per inch) value for conversion from pixels +to inch/centimeters and vice versa. +(Technically, the correct term would be ppi: pixels per inch.) +The default is 96dpi. +When images contain information about dpi internally, the encoded value +is used instead of the default specified by this option. +.TP +\f[CR]--wrap=auto\f[R]|\f[CR]none\f[R]|\f[CR]preserve\f[R] +Determine how text is wrapped in the output (the source code, not the +rendered version). +With \f[CR]auto\f[R] (the default), pandoc will attempt to wrap lines to +the column width specified by \f[CR]--columns\f[R] (default 72). +With \f[CR]none\f[R], pandoc will not wrap lines at all. +With \f[CR]preserve\f[R], pandoc will attempt to preserve the wrapping +from the source document (that is, where there are nonsemantic newlines +in the source, there will be nonsemantic newlines in the output as +well). +In \f[CR]ipynb\f[R] output, this option affects wrapping of the contents +of markdown cells. +.TP +\f[CR]--columns=\f[R]\f[I]NUMBER\f[R] +Specify length of lines in characters. +This affects text wrapping in the generated source code (see +\f[CR]--wrap\f[R]). +It also affects calculation of column widths for plain text tables (see +Tables below). +.TP +\f[CR]--toc[=true|false]\f[R], \f[CR]--table-of-contents[=true|false]\f[R] +Include an automatically generated table of contents (or, in the case of +\f[CR]latex\f[R], \f[CR]context\f[R], \f[CR]docx\f[R], \f[CR]odt\f[R], +\f[CR]opendocument\f[R], \f[CR]rst\f[R], or \f[CR]ms\f[R], an +instruction to create one) in the output document. +This option has no effect unless \f[CR]-s/--standalone\f[R] is used, and +it has no effect on \f[CR]man\f[R], \f[CR]docbook4\f[R], +\f[CR]docbook5\f[R], or \f[CR]jats\f[R] output. +.RS +.PP +Note that if you are producing a PDF via \f[CR]ms\f[R], the table of +contents will appear at the beginning of the document, before the title. +If you would prefer it to be at the end of the document, use the option +\f[CR]--pdf-engine-opt=--no-toc-relocation\f[R]. +.RE +.TP +\f[CR]--toc-depth=\f[R]\f[I]NUMBER\f[R] +Specify the number of section levels to include in the table of +contents. +The default is 3 (which means that level-1, 2, and 3 headings will be +listed in the contents). +.TP +\f[CR]--strip-comments[=true|false]\f[R] +Strip out HTML comments in the Markdown or Textile source, rather than +passing them on to Markdown, Textile or HTML output as raw HTML. +This does not apply to HTML comments inside raw HTML blocks when the +\f[CR]markdown_in_html_blocks\f[R] extension is not set. +.TP +\f[CR]--no-highlight\f[R] +Disables syntax highlighting for code blocks and inlines, even when a +language attribute is given. +.TP +\f[CR]--highlight-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R] +Specifies the coloring style to be used in highlighted source code. +Options are \f[CR]pygments\f[R] (the default), \f[CR]kate\f[R], +\f[CR]monochrome\f[R], \f[CR]breezeDark\f[R], \f[CR]espresso\f[R], +\f[CR]zenburn\f[R], \f[CR]haddock\f[R], and \f[CR]tango\f[R]. +For more information on syntax highlighting in pandoc, see Syntax +highlighting, below. +See also \f[CR]--list-highlight-styles\f[R]. +.RS +.PP +Instead of a \f[I]STYLE\f[R] name, a JSON file with extension +\f[CR].theme\f[R] may be supplied. +This will be parsed as a KDE syntax highlighting theme and (if valid) +used as the highlighting style. +.PP +To generate the JSON version of an existing style, use +\f[CR]--print-highlight-style\f[R]. +.RE +.TP +\f[CR]--print-highlight-style=\f[R]\f[I]STYLE\f[R]|\f[I]FILE\f[R] +Prints a JSON version of a highlighting style, which can be modified, +saved with a \f[CR].theme\f[R] extension, and used with +\f[CR]--highlight-style\f[R]. +This option may be used with \f[CR]-o\f[R]/\f[CR]--output\f[R] to +redirect output to a file, but \f[CR]-o\f[R]/\f[CR]--output\f[R] must +come before \f[CR]--print-highlight-style\f[R] on the command line. +.TP +\f[CR]--syntax-definition=\f[R]\f[I]FILE\f[R] +Instructs pandoc to load a KDE XML syntax definition file, which will be +used for syntax highlighting of appropriately marked code blocks. +This can be used to add support for new languages or to use altered +syntax definitions for existing languages. +This option may be repeated to add multiple syntax definitions. +.TP +\f[CR]-H\f[R] \f[I]FILE\f[R], \f[CR]--include-in-header=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] +Include contents of \f[I]FILE\f[R], verbatim, at the end of the header. +This can be used, for example, to include special CSS or JavaScript in +HTML documents. +This option can be used repeatedly to include multiple files in the +header. +They will be included in the order specified. +Implies \f[CR]--standalone\f[R]. +.TP +\f[CR]-B\f[R] \f[I]FILE\f[R], \f[CR]--include-before-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] +Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the +document body (e.g.\ after the \f[CR]\f[R] tag in HTML, or the +\f[CR]\[rs]begin{document}\f[R] command in LaTeX). +This can be used to include navigation bars or banners in HTML +documents. +This option can be used repeatedly to include multiple files. +They will be included in the order specified. +Implies \f[CR]--standalone\f[R]. +.TP +\f[CR]-A\f[R] \f[I]FILE\f[R], \f[CR]--include-after-body=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] +Include contents of \f[I]FILE\f[R], verbatim, at the end of the document +body (before the \f[CR]\f[R] tag in HTML, or the +\f[CR]\[rs]end{document}\f[R] command in LaTeX). +This option can be used repeatedly to include multiple files. +They will be included in the order specified. +Implies \f[CR]--standalone\f[R]. +.TP +\f[CR]--resource-path=\f[R]\f[I]SEARCHPATH\f[R] +List of paths to search for images and other resources. +The paths should be separated by \f[CR]:\f[R] on Linux, UNIX, and macOS +systems, and by \f[CR];\f[R] on Windows. +If \f[CR]--resource-path\f[R] is not specified, the default resource +path is the working directory. +Note that, if \f[CR]--resource-path\f[R] is specified, the working +directory must be explicitly listed or it will not be searched. +For example: \f[CR]--resource-path=.:test\f[R] will search the working +directory and the \f[CR]test\f[R] subdirectory, in that order. +This option can be used repeatedly. +Search path components that come later on the command line will be +searched before those that come earlier, so +\f[CR]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent +to \f[CR]--resource-path baz:bim:foo:bar\f[R]. +.TP +\f[CR]--request-header=\f[R]\f[I]NAME\f[R]\f[CR]:\f[R]\f[I]VAL\f[R] +Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when +making HTTP requests (for example, when a URL is given on the command +line, or when resources used in a document must be downloaded). +If you\[cq]re behind a proxy, you also need to set the environment +variable \f[CR]http_proxy\f[R] to \f[CR]http://...\f[R]. +.TP +\f[CR]--no-check-certificate[=true|false]\f[R] +Disable the certificate verification to allow access to unsecure HTTP +resources (for example when the certificate is no longer valid or self +signed). +.SS Options affecting specific writers +.TP +\f[CR]--self-contained[=true|false]\f[R] +\f[I]Deprecated synonym for +\f[CI]--embed-resources --standalone\f[I].\f[R] +.TP +\f[CR]--embed-resources[=true|false]\f[R] +Produce a standalone HTML file with no external dependencies, using +\f[CR]data:\f[R] URIs to incorporate the contents of linked scripts, +stylesheets, images, and videos. +The resulting file should be \[lq]self-contained,\[rq] in the sense that +it needs no external files and no net access to be displayed properly by +a browser. +This option works only with HTML output formats, including +\f[CR]html4\f[R], \f[CR]html5\f[R], \f[CR]html+lhs\f[R], +\f[CR]html5+lhs\f[R], \f[CR]s5\f[R], \f[CR]slidy\f[R], +\f[CR]slideous\f[R], \f[CR]dzslides\f[R], and \f[CR]revealjs\f[R]. +Scripts, images, and stylesheets at absolute URLs will be downloaded; +those at relative URLs will be sought relative to the working directory +(if the first source file is local) or relative to the base URL (if the +first source file is remote). +Elements with the attribute \f[CR]data-external=\[dq]1\[dq]\f[R] will be +left alone; the documents they link to will not be incorporated in the +document. +Limitation: resources that are loaded dynamically through JavaScript +cannot be incorporated; as a result, fonts may be missing when +\f[CR]--mathjax\f[R] is used, and some advanced features (e.g.\ zoom or +speaker notes) may not work in an offline \[lq]self-contained\[rq] +\f[CR]reveal.js\f[R] slide show. +.TP +\f[CR]--html-q-tags[=true|false]\f[R] +Use \f[CR]\f[R] tags for quotes in HTML. +(This option only has an effect if the \f[CR]smart\f[R] extension is +enabled for the input format used.) +.TP +\f[CR]--ascii[=true|false]\f[R] +Use only ASCII characters in output. +Currently supported for XML and HTML formats (which use entities instead +of UTF-8 when this option is selected), CommonMark, gfm, and Markdown +(which use entities), roff man and ms (which use hexadecimal escapes), +and to a limited degree LaTeX (which uses standard commands for accented +characters when possible). +.TP +\f[CR]--reference-links[=true|false]\f[R] +Use reference-style links, rather than inline links, in writing Markdown +or reStructuredText. +By default inline links are used. +The placement of link references is affected by the +\f[CR]--reference-location\f[R] option. +.TP +\f[CR]--reference-location=block\f[R]|\f[CR]section\f[R]|\f[CR]document\f[R] +Specify whether footnotes (and references, if \f[CR]reference-links\f[R] +is set) are placed at the end of the current (top-level) block, the +current section, or the document. +The default is \f[CR]document\f[R]. +Currently this option only affects the \f[CR]markdown\f[R], +\f[CR]muse\f[R], \f[CR]html\f[R], \f[CR]epub\f[R], \f[CR]slidy\f[R], +\f[CR]s5\f[R], \f[CR]slideous\f[R], \f[CR]dzslides\f[R], and +\f[CR]revealjs\f[R] writers. +In slide formats, specifying \f[CR]--reference-location=section\f[R] +will cause notes to be rendered at the bottom of a slide. +.TP +\f[CR]--markdown-headings=setext\f[R]|\f[CR]atx\f[R] +Specify whether to use ATX-style (\f[CR]#\f[R]-prefixed) or Setext-style +(underlined) headings for level 1 and 2 headings in Markdown output. +(The default is \f[CR]atx\f[R].) +ATX-style headings are always used for levels 3+. +This option also affects Markdown cells in \f[CR]ipynb\f[R] output. +.TP +\f[CR]--list-tables[=true|false]\f[R] +Render tables as list tables in RST output. +.TP +\f[CR]--top-level-division=default\f[R]|\f[CR]section\f[R]|\f[CR]chapter\f[R]|\f[CR]part\f[R] +Treat top-level headings as the given division type in LaTeX, ConTeXt, +DocBook, and TEI output. +The hierarchy order is part, chapter, then section; all headings are +shifted such that the top-level heading becomes the specified type. +The default behavior is to determine the best division type via +heuristics: unless other conditions apply, \f[CR]section\f[R] is chosen. +When the \f[CR]documentclass\f[R] variable is set to \f[CR]report\f[R], +\f[CR]book\f[R], or \f[CR]memoir\f[R] (unless the \f[CR]article\f[R] +option is specified), \f[CR]chapter\f[R] is implied as the setting for +this option. +If \f[CR]beamer\f[R] is the output format, specifying either +\f[CR]chapter\f[R] or \f[CR]part\f[R] will cause top-level headings to +become \f[CR]\[rs]part{..}\f[R], while second-level headings remain as +their default type. +.TP +\f[CR]-N\f[R], \f[CR]--number-sections\f[R] +Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB +output. +By default, sections are not numbered. +Sections with class \f[CR]unnumbered\f[R] will never be numbered, even +if \f[CR]--number-sections\f[R] is specified. +.TP +\f[CR]--number-offset=\f[R]\f[I]NUMBER\f[R][\f[CR],\f[R]\f[I]NUMBER\f[R]\f[CR],\f[R]\f[I]\&...\f[R]] +Offset for section headings in HTML output (ignored in other output +formats). +The first number is added to the section number for top-level headings, +the second for second-level headings, and so on. +So, for example, if you want the first top-level heading in your +document to be numbered \[lq]6\[rq], specify +\f[CR]--number-offset=5\f[R]. +If your document starts with a level-2 heading which you want to be +numbered \[lq]1.5\[rq], specify \f[CR]--number-offset=1,4\f[R]. +Offsets are 0 by default. +Implies \f[CR]--number-sections\f[R]. +.TP +\f[CR]--listings[=true|false]\f[R] +Use the \f[CR]listings\f[R] package for LaTeX code blocks. +The package does not support multi-byte encoding for source code. +To handle UTF-8 you would need to use a custom template. +This issue is fully documented here: Encoding issue with the listings +package. +.TP +\f[CR]-i\f[R], \f[CR]--incremental[=true|false]\f[R] +Make list items in slide shows display incrementally (one by one). +The default is for lists to be displayed all at once. +.TP +\f[CR]--slide-level=\f[R]\f[I]NUMBER\f[R] +Specifies that headings with the specified level create slides (for +\f[CR]beamer\f[R], \f[CR]s5\f[R], \f[CR]slidy\f[R], \f[CR]slideous\f[R], +\f[CR]dzslides\f[R]). +Headings above this level in the hierarchy are used to divide the slide +show into sections; headings below this level create subheads within a +slide. +Valid values are 0-6. +If a slide level of 0 is specified, slides will not be split +automatically on headings, and horizontal rules must be used to indicate +slide boundaries. +If a slide level is not specified explicitly, the slide level will be +set automatically based on the contents of the document; see Structuring +the slide show. +.TP +\f[CR]--section-divs[=true|false]\f[R] +Wrap sections in \f[CR]
\f[R] tags (or \f[CR]
\f[R] tags for +\f[CR]html4\f[R]), and attach identifiers to the enclosing +\f[CR]
\f[R] (or \f[CR]
\f[R]) rather than the heading +itself (see Heading identifiers, below). +This option only affects HTML output (and does not affect HTML slide +formats). +.TP +\f[CR]--email-obfuscation=none\f[R]|\f[CR]javascript\f[R]|\f[CR]references\f[R] +Specify a method for obfuscating \f[CR]mailto:\f[R] links in HTML +documents. +\f[CR]none\f[R] leaves \f[CR]mailto:\f[R] links as they are. +\f[CR]javascript\f[R] obfuscates them using JavaScript. +\f[CR]references\f[R] obfuscates them by printing their letters as +decimal or hexadecimal character references. +The default is \f[CR]none\f[R]. +.TP +\f[CR]--id-prefix=\f[R]\f[I]STRING\f[R] +Specify a prefix to be added to all identifiers and internal links in +HTML and DocBook output, and to footnote numbers in Markdown and Haddock +output. +This is useful for preventing duplicate identifiers when generating +fragments to be included in other pages. +.TP +\f[CR]-T\f[R] \f[I]STRING\f[R], \f[CR]--title-prefix=\f[R]\f[I]STRING\f[R] +Specify \f[I]STRING\f[R] as a prefix at the beginning of the title that +appears in the HTML header (but not in the title as it appears at the +beginning of the HTML body). +Implies \f[CR]--standalone\f[R]. +.TP +\f[CR]-c\f[R] \f[I]URL\f[R], \f[CR]--css=\f[R]\f[I]URL\f[R] +Link to a CSS style sheet. +This option can be used repeatedly to include multiple files. +They will be included in the order specified. +This option only affects HTML (including HTML slide shows) and EPUB +output. +It should be used together with \f[CR]-s/--standalone\f[R], because the +link to the stylesheet goes in the document header. +.RS +.PP +A stylesheet is required for generating EPUB. +If none is provided using this option (or the \f[CR]css\f[R] or +\f[CR]stylesheet\f[R] metadata fields), pandoc will look for a file +\f[CR]epub.css\f[R] in the user data directory (see +\f[CR]--data-dir\f[R]). +If it is not found there, sensible defaults will be used. +.RE +.TP +\f[CR]--reference-doc=\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R] +Use the specified file as a style reference in producing a docx or ODT +file. +.RS +.TP +Docx +For best results, the reference docx should be a modified version of a +docx file produced using pandoc. +The contents of the reference docx are ignored, but its stylesheets and +document properties (including margins, page size, header, and footer) +are used in the new docx. +If no reference docx is specified on the command line, pandoc will look +for a file \f[CR]reference.docx\f[R] in the user data directory (see +\f[CR]--data-dir\f[R]). +If this is not found either, sensible defaults will be used. +.RS +.PP +To produce a custom \f[CR]reference.docx\f[R], first get a copy of the +default \f[CR]reference.docx\f[R]: +\f[CR]pandoc -o custom-reference.docx --print-default-data-file reference.docx\f[R]. +Then open \f[CR]custom-reference.docx\f[R] in Word, modify the styles as +you wish, and save the file. +For best results, do not make changes to this file other than modifying +the styles used by pandoc: +.PP +Paragraph styles: +.IP \[bu] 2 +Normal +.IP \[bu] 2 +Body Text +.IP \[bu] 2 +First Paragraph +.IP \[bu] 2 +Compact +.IP \[bu] 2 +Title +.IP \[bu] 2 +Subtitle +.IP \[bu] 2 +Author +.IP \[bu] 2 +Date +.IP \[bu] 2 +Abstract +.IP \[bu] 2 +AbstractTitle +.IP \[bu] 2 +Bibliography +.IP \[bu] 2 +Heading 1 +.IP \[bu] 2 +Heading 2 +.IP \[bu] 2 +Heading 3 +.IP \[bu] 2 +Heading 4 +.IP \[bu] 2 +Heading 5 +.IP \[bu] 2 +Heading 6 +.IP \[bu] 2 +Heading 7 +.IP \[bu] 2 +Heading 8 +.IP \[bu] 2 +Heading 9 +.IP \[bu] 2 +Block Text [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]wkhtmltopdf\f[R] (other options: +\f[CR]prince\f[R], \f[CR]weasyprint\f[R], \f[CR]pagedjs-cli\f[R]; see +print-css.rocks for a good introduction to PDF generation from HTML/CSS) +.IP \[bu] 2 +\f[CR]-t ms\f[R]: \f[CR]pdfroff\f[R] +.IP \[bu] 2 +\f[CR]-t typst\f[R]: \f[CR]typst\f[R] +.RE +.TP +\f[CR]--pdf-engine-opt=\f[R]\f[I]STRING\f[R] +Use the given string as a command-line argument to the +\f[CR]pdf-engine\f[R]. +For example, to use a persistent directory \f[CR]foo\f[R] for +\f[CR]latexmk\f[R]\[cq]s auxiliary files, use +\f[CR]--pdf-engine-opt=-outdir=foo\f[R]. +Note that no check for duplicate options is done. +.SS Citation rendering +.TP +\f[CR]-C\f[R], \f[CR]--citeproc\f[R] +Process the citations in the file, replacing them with rendered +citations and adding a bibliography. +Citation processing will not take place unless bibliographic data is +supplied, either through an external file specified using the +\f[CR]--bibliography\f[R] option or the \f[CR]bibliography\f[R] field in +metadata, or via a \f[CR]references\f[R] section in metadata containing +a list of citations in CSL YAML format with Markdown formatting. +The style is controlled by a CSL stylesheet specified using the +\f[CR]--csl\f[R] option or the \f[CR]csl\f[R] field in metadata. +(If no stylesheet is specified, the \f[CR]chicago-author-date\f[R] style +will be used by default.) +The citation processing transformation may be applied before or after +filters or Lua filters (see \f[CR]--filter\f[R], +\f[CR]--lua-filter\f[R]): these transformations are applied in the order +they appear on the command line. +For more information, see the section on Citations. +.TP +\f[CR]--bibliography=\f[R]\f[I]FILE\f[R] +Set the \f[CR]bibliography\f[R] field in the document\[cq]s metadata to +\f[I]FILE\f[R], overriding any value set in the metadata. +If you supply this argument multiple times, each \f[I]FILE\f[R] will be +added to bibliography. +If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP. +If \f[I]FILE\f[R] is not found relative to the working directory, it +will be sought in the resource path (see \f[CR]--resource-path\f[R]). +.TP +\f[CR]--csl=\f[R]\f[I]FILE\f[R] +Set the \f[CR]csl\f[R] field in the document\[cq]s metadata to +\f[I]FILE\f[R], overriding any value set in the metadata. +(This is equivalent to \f[CR]--metadata csl=FILE\f[R].) +If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP. +If \f[I]FILE\f[R] is not found relative to the working directory, it +will be sought in the resource path (see \f[CR]--resource-path\f[R]) and +finally in the \f[CR]csl\f[R] subdirectory of the pandoc user data +directory. +.TP +\f[CR]--citation-abbreviations=\f[R]\f[I]FILE\f[R] +Set the \f[CR]citation-abbreviations\f[R] field in the document\[cq]s +metadata to \f[I]FILE\f[R], overriding any value set in the metadata. +(This is equivalent to +\f[CR]--metadata citation-abbreviations=FILE\f[R].) +If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP. +If \f[I]FILE\f[R] is not found relative to the working directory, it +will be sought in the resource path (see \f[CR]--resource-path\f[R]) and +finally in the \f[CR]csl\f[R] subdirectory of the pandoc user data +directory. +.TP +\f[CR]--natbib\f[R] +Use \f[CR]natbib\f[R] for citations in LaTeX output. +This option is not for use with the \f[CR]--citeproc\f[R] option or with +PDF output. +It is intended for use in producing a LaTeX file that can be processed +with \f[CR]bibtex\f[R]. +.TP +\f[CR]--biblatex\f[R] +Use \f[CR]biblatex\f[R] for citations in LaTeX output. +This option is not for use with the \f[CR]--citeproc\f[R] option or with +PDF output. +It is intended for use in producing a LaTeX file that can be processed +with \f[CR]bibtex\f[R] or \f[CR]biber\f[R]. +.SS Math rendering in HTML +The default is to render TeX math as far as possible using Unicode +characters. +Formulas are put inside a \f[CR]span\f[R] with +\f[CR]class=\[dq]math\[dq]\f[R], so that they may be styled differently +from the surrounding text if needed. +However, this gives acceptable results only for basic math, usually you +will want to use \f[CR]--mathjax\f[R] or another of the following +options. +.TP +\f[CR]--mathjax\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +Use MathJax to display embedded TeX math in HTML output. +TeX math will be put between \f[CR]\[rs](...\[rs])\f[R] (for inline +math) or \f[CR]\[rs][...\[rs]]\f[R] (for display math) and wrapped in +\f[CR]\f[R] tags with class \f[CR]math\f[R]. +Then the MathJax JavaScript will render it. +The \f[I]URL\f[R] should point to the \f[CR]MathJax.js\f[R] load script. +If a \f[I]URL\f[R] is not provided, a link to the Cloudflare CDN will be +inserted. +.TP +\f[CR]--mathml\f[R] +Convert TeX math to MathML (in \f[CR]epub3\f[R], \f[CR]docbook4\f[R], +\f[CR]docbook5\f[R], \f[CR]jats\f[R], \f[CR]html4\f[R] and +\f[CR]html5\f[R]). +This is the default in \f[CR]odt\f[R] output. +MathML is supported natively by the main web browsers and select e-book +readers. +.TP +\f[CR]--webtex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +Convert TeX formulas to \f[CR]\f[R] tags that link to an external +script that converts formulas to images. +The formula will be URL-encoded and concatenated with the URL provided. +For SVG images you can for example use +\f[CR]--webtex https://latex.codecogs.com/svg.latex?\f[R]. +If no URL is specified, the CodeCogs URL generating PNGs will be used +(\f[CR]https://latex.codecogs.com/png.latex?\f[R]). +Note: the \f[CR]--webtex\f[R] option will affect Markdown output as well +as HTML, which is useful if you\[cq]re targeting a version of Markdown +without native math support. +.TP +\f[CR]--katex\f[R][\f[CR]=\f[R]\f[I]URL\f[R]] +Use KaTeX to display embedded TeX math in HTML output. +The \f[I]URL\f[R] is the base URL for the KaTeX library. +That directory should contain a \f[CR]katex.min.js\f[R] and a +\f[CR]katex.min.css\f[R] file. +If a \f[I]URL\f[R] is not provided, a link to the KaTeX CDN will be +inserted. +.TP +\f[CR]--gladtex\f[R] +Enclose TeX math in \f[CR]\f[R] tags in HTML output. +The resulting HTML can then be processed by GladTeX to produce SVG +images of the typeset formulas and an HTML file with these images +embedded. +.RS +.IP +.EX +pandoc -s --gladtex input.md -o myfile.htex +gladtex -d image_dir myfile.htex +# produces myfile.html and images in image_dir +.EE +.RE +.SS Options for wrapper scripts +.TP +\f[CR]--dump-args[=true|false]\f[R] +Print information about command-line arguments to \f[I]stdout\f[R], then +exit. +This option is intended primarily for use in wrapper scripts. +The first line of output contains the name of the output file specified +with the \f[CR]-o\f[R] option, or \f[CR]-\f[R] (for \f[I]stdout\f[R]) if +no output file was specified. +The remaining lines contain the command-line arguments, one per line, in +the order they appear. +These do not include regular pandoc options and their arguments, but do +include any options appearing after a \f[CR]--\f[R] separator at the end +of the line. +.TP +\f[CR]--ignore-args[=true|false]\f[R] +Ignore command-line arguments (for use in wrapper scripts). +Regular pandoc options are not ignored. +Thus, for example, +.RS +.IP +.EX +pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1 +.EE +.PP +is equivalent to +.IP +.EX +pandoc -o foo.html -s +.EE +.RE +.SH EXIT CODES +If pandoc completes successfully, it will return exit code 0. +Nonzero exit codes have the following meanings: +.RS -14n +.IP +.EX + Code Error + ------ ------------------------------------- + 1 PandocIOError + 3 PandocFailOnWarningError + 4 PandocAppError + 5 PandocTemplateError + 6 PandocOptionError + 21 PandocUnknownReaderError + 22 PandocUnknownWriterError + 23 PandocUnsupportedExtensionError + 24 PandocCiteprocError + 25 PandocBibliographyError + 31 PandocEpubSubdirectoryError + 43 PandocPDFError + 44 PandocXMLError + 47 PandocPDFProgramNotFoundError + 61 PandocHttpError + 62 PandocShouldNeverHappenError + 63 PandocSomeError + 64 PandocParseError + 66 PandocMakePDFError + 67 PandocSyntaxMapError + 83 PandocFilterError + 84 PandocLuaError + 89 PandocNoScriptingEngine + 91 PandocMacroLoop + 92 PandocUTF8DecodingError + 93 PandocIpynbDecodingError + 94 PandocUnsupportedCharsetError + 97 PandocCouldNotFindDataFileError + 98 PandocCouldNotFindMetadataFileError + 99 PandocResourceNotFound +.EE +.RE +.SH DEFAULTS FILES +The \f[CR]--defaults\f[R] option may be used to specify a package of +options, in the form of a YAML file. +.PP +Fields that are omitted will just have their regular default values. +So a defaults file can be as simple as one line: +.IP +.EX +verbosity: INFO +.EE +.PP +In fields that expect a file path (or list of file paths), the following +syntax may be used to interpolate environment variables: +.IP +.EX +csl: ${HOME}/mycsldir/special.csl +.EE +.PP +\f[CR]${USERDATA}\f[R] may also be used; this will always resolve to the +user data directory that is current when the defaults file is parsed, +regardless of the setting of the environment variable +\f[CR]USERDATA\f[R]. +.PP +\f[CR]${.}\f[R] will resolve to the directory containing the defaults +file itself. +This allows you to refer to resources contained in that directory: +.IP +.EX +epub-cover-image: ${.}/cover.jpg +epub-metadata: ${.}/meta.xml +resource-path: +- . # the working directory from which pandoc is run +- ${.}/images # the images subdirectory of the directory + # containing this defaults file +.EE +.PP +This environment variable interpolation syntax \f[I]only\f[R] works in +fields that expect file paths. +.PP +Defaults files can be placed in the \f[CR]defaults\f[R] subdirectory of +the user data directory and used from any directory. +For example, one could create a file specifying defaults for writing +letters, save it as \f[CR]letter.yaml\f[R] in the \f[CR]defaults\f[R] +subdirectory of the user data directory, and then invoke these defaults +from any directory using \f[CR]pandoc --defaults letter\f[R] or +\f[CR]pandoc -dletter\f[R]. +.PP +When multiple defaults are used, their contents will be combined. +.PP +Note that, where command-line arguments may be repeated +(\f[CR]--metadata-file\f[R], \f[CR]--css\f[R], +\f[CR]--include-in-header\f[R], \f[CR]--include-before-body\f[R], +\f[CR]--include-after-body\f[R], \f[CR]--variable\f[R], +\f[CR]--metadata\f[R], \f[CR]--syntax-definition\f[R]), the values +specified on the command line will combine with values specified in the +defaults file, rather than replacing them. +.PP +The following tables show the mapping between the command line and +defaults file entries. +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + foo.md input-file: foo.md + + foo.md bar.md input-files: + - foo.md + - bar.md + +.EE +.RE +.PP +The value of \f[CR]input-files\f[R] may be left empty to indicate input +from stdin, and it can be an empty sequence \f[CR][]\f[R] for no input. +.SS General options +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --from markdown+emoji from: markdown+emoji + + reader: markdown+emoji + + to: markdown+hard_line_breaks + --to markdown+hard_line_breaks + + writer: markdown+hard_line_breaks + + --output foo.pdf output-file: foo.pdf + + --output - output-file: + + --data-dir dir data-dir: dir + + --defaults file defaults: + - file + + --verbose verbosity: INFO + + --quiet verbosity: ERROR + + --fail-if-warnings fail-if-warnings: true + + --sandbox sandbox: true + + --log=FILE log-file: FILE + +.EE +.RE +.PP +Options specified in a defaults file itself always have priority over +those in another file included with a \f[CR]defaults:\f[R] entry. +.PP +\f[CR]verbosity\f[R] can have the values \f[CR]ERROR\f[R], +\f[CR]WARNING\f[R], or \f[CR]INFO\f[R]. +.SS Reader options +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --shift-heading-level-by -1 shift-heading-level-by: -1 + + indented-code-classes: + --indented-code-classes python - python + + + --default-image-extension \[dq].jpg\[dq] default-image-extension: \[aq].jpg\[aq] + + --file-scope file-scope: true + + --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 + + --html-q-tags html-q-tags: true + + --ascii ascii: true + + --reference-links reference-links: true + + --reference-location block reference-location: block + + --markdown-headings atx markdown-headings: atx + + --list-tables list-tables: true + + --top-level-division chapter top-level-division: chapter + + --number-sections number-sections: true + + --number-offset=1,4 number-offset: \[rs][1,4\[rs]] + + --listings listings: true + + --incremental incremental: true + + --slide-level 2 slide-level: 2 + + --section-divs section-divs: true + + email-obfuscation: references + --email-obfuscation references + + --id-prefix ch1 identifier-prefix: ch1 + + --title-prefix MySite title-prefix: MySite + + --css styles/screen.css \[rs] css: + --css styles/special.css - styles/screen.css + - styles/special.css + + --reference-doc my.docx reference-doc: my.docx + + --epub-cover-image cover.jpg epub-cover-image: cover.jpg + + --epub-title-page=false epub-title-page: false + + --epub-metadata meta.xml epub-metadata: meta.xml + + epub-fonts: + --epub-embed-font special.otf \[rs] - special.otf + - headline.otf + --epub-embed-font headline.otf + + --split-level 2 split-level: 2 + + --chunk-template=\[dq]%i.html\[dq] chunk-template: \[dq]%i.html\[dq] + + --epub-subdirectory=\[dq]\[dq] epub-subdirectory: \[aq]\[aq] + + --ipynb-output best ipynb-output: best + + --pdf-engine xelatex pdf-engine: xelatex + + pdf-engine-opts: + --pdf-engine-opt=--shell-escape - \[aq]-shell-escape\[aq] + + + pdf-engine-opt: \[aq]-shell-escape\[aq] + +.EE +.RE +.SS Citation rendering +.RS -14n +.IP +.EX + + command line defaults file + --------------------------------- ---------------------------------- + --citeproc citeproc: true + + --bibliography logic.bib 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]pdf\f[R] output, customize the \f[CR]default.latex\f[R] +template (or the \f[CR]default.context\f[R] template, if you use +\f[CR]-t context\f[R], or the \f[CR]default.ms\f[R] template, if you use +\f[CR]-t ms\f[R], or the \f[CR]default.html\f[R] template, if you use +\f[CR]-t html\f[R]). +.IP \[bu] 2 +\f[CR]docx\f[R] and \f[CR]pptx\f[R] have no template (however, you can +use \f[CR]--reference-doc\f[R] to customize the output). +.PP +Templates contain \f[I]variables\f[R], which allow for the inclusion of +arbitrary information at any point in the file. +They may be set at the command line using the \f[CR]-V/--variable\f[R] +option. +If a variable is not set, pandoc will look for the key in the +document\[cq]s metadata, which can be set using either YAML metadata +blocks or with the \f[CR]-M/--metadata\f[R] option. +In addition, some variables are given default values by pandoc. +See Variables below for a list of variables used in pandoc\[cq]s default +templates. +.PP +If you use custom templates, you may need to revise them as pandoc +changes. +We recommend tracking the changes in the default templates, and +modifying your custom templates accordingly. +An easy way to do this is to fork the pandoc-templates repository and +merge in changes after each pandoc release. +.SS Template syntax +.SS Comments +Anything between the sequence \f[CR]$--\f[R] and the end of the line +will be treated as a comment and omitted from the output. +.SS Delimiters +To mark variables and control structures in the template, either +\f[CR]$\f[R]\&...\f[CR]$\f[R] or \f[CR]${\f[R]\&...\f[CR]}\f[R] may be +used as delimiters. +The styles may also be mixed in the same template, but the opening and +closing delimiter must match in each case. +The opening delimiter may be followed by one or more spaces or tabs, +which will be ignored. +The closing delimiter may be preceded by one or more spaces or tabs, +which will be ignored. +.PP +To include a literal \f[CR]$\f[R] in the document, use \f[CR]$$\f[R]. +.SS Interpolated variables +A slot for an interpolated variable is a variable name surrounded by +matched delimiters. +Variable names must begin with a letter and can contain letters, +numbers, \f[CR]_\f[R], \f[CR]-\f[R], and \f[CR].\f[R]. +The keywords \f[CR]it\f[R], \f[CR]if\f[R], \f[CR]else\f[R], +\f[CR]endif\f[R], \f[CR]for\f[R], \f[CR]sep\f[R], and \f[CR]endfor\f[R] +may not be used as variable names. +Examples: +.IP +.EX +$foo$ +$foo.bar.baz$ +$foo_bar.baz-bim$ +$ foo $ +${foo} +${foo.bar.baz} +${foo_bar.baz-bim} +${ foo } +.EE +.PP +Variable names with periods are used to get at structured variable +values. +So, for example, \f[CR]employee.salary\f[R] will return the value of the +\f[CR]salary\f[R] field of the object that is the value of the +\f[CR]employee\f[R] field. +.IP \[bu] 2 +If the value of the variable is a simple value, it will be rendered +verbatim. +(Note that no escaping is done; the assumption is that the calling +program will escape the strings appropriately for the output format.) +.IP \[bu] 2 +If the value is a list, the values will be concatenated. +.IP \[bu] 2 +If the value is a map, the string \f[CR]true\f[R] will be rendered. +.IP \[bu] 2 +Every other value will be rendered as the empty string. +.SS Conditionals +A conditional begins with \f[CR]if(variable)\f[R] (enclosed in matched +delimiters) and ends with \f[CR]endif\f[R] (enclosed in matched +delimiters). +It may optionally contain an \f[CR]else\f[R] (enclosed in matched +delimiters). +The \f[CR]if\f[R] section is used if \f[CR]variable\f[R] has a non-empty +value, otherwise the \f[CR]else\f[R] section is used (if present). +Examples: +.IP +.EX +$if(foo)$bar$endif$ + +$if(foo)$ + $foo$ +$endif$ + +$if(foo)$ +part one +$else$ +part two +$endif$ + +${if(foo)}bar${endif} + +${if(foo)} + ${foo} +${endif} + +${if(foo)} +${ foo.bar } +${else} +no foo! +${endif} +.EE +.PP +The keyword \f[CR]elseif\f[R] may be used to simplify complex nested +conditionals: +.IP +.EX +$if(foo)$ +XXX +$elseif(bar)$ +YYY +$else$ +ZZZ +$endif$ +.EE +.SS For loops +A for loop begins with \f[CR]for(variable)\f[R] (enclosed in matched +delimiters) and ends with \f[CR]endfor\f[R] (enclosed in matched +delimiters). +.IP \[bu] 2 +If \f[CR]variable\f[R] is an array, the material inside the loop will be +evaluated repeatedly, with \f[CR]variable\f[R] being set to each value +of the array in turn, and concatenated. +.IP \[bu] 2 +If \f[CR]variable\f[R] is a map, the material inside will be set to the +map. +.IP \[bu] 2 +If the value of the associated variable is not an array or a map, a +single iteration will be performed on its value. +.PP +Examples: +.IP +.EX +$for(foo)$$foo$$sep$, $endfor$ + +$for(foo)$ + - $foo.last$, $foo.first$ +$endfor$ + +${ for(foo.bar) } + - ${ foo.bar.last }, ${ foo.bar.first } +${ endfor } + +$for(mymap)$ +$it.name$: $it.office$ +$endfor$ +.EE +.PP +You may optionally specify a separator between consecutive values using +\f[CR]sep\f[R] (enclosed in matched delimiters). +The material between \f[CR]sep\f[R] and the \f[CR]endfor\f[R] is the +separator. +.IP +.EX +${ for(foo) }${ foo }${ sep }, ${ endfor } +.EE +.PP +Instead of using \f[CR]variable\f[R] inside the loop, the special +anaphoric keyword \f[CR]it\f[R] may be used. +.IP +.EX +${ for(foo.bar) } + - ${ it.last }, ${ it.first } +${ endfor } +.EE +.SS Partials +Partials (subtemplates stored in different files) may be included by +using the name of the partial, followed by \f[CR]()\f[R], for example: +.IP +.EX +${ styles() } +.EE +.PP +Partials will be sought in the directory containing the main template. +The file name will be assumed to have the same extension as the main +template if it lacks an extension. +When calling the partial, the full name including file extension can +also be used: +.IP +.EX +${ styles.html() } +.EE +.PP +(If a partial is not found in the directory of the template and the +template path is given as a relative path, it will also be sought in the +\f[CR]templates\f[R] subdirectory of the user data directory.) +.PP +Partials may optionally be applied to variables using a colon: +.IP +.EX +${ date:fancy() } + +${ articles:bibentry() } +.EE +.PP +If \f[CR]articles\f[R] is an array, this will iterate over its values, +applying the partial \f[CR]bibentry()\f[R] to each one. +So the second example above is equivalent to +.IP +.EX +${ for(articles) } +${ it:bibentry() } +${ endfor } +.EE +.PP +Note that the anaphoric keyword \f[CR]it\f[R] must be used when +iterating over partials. +In the above examples, the \f[CR]bibentry\f[R] partial should contain +\f[CR]it.title\f[R] (and so on) instead of \f[CR]articles.title\f[R]. +.PP +Final newlines are omitted from included partials. +.PP +Partials may include other partials. +.PP +A separator between values of an array may be specified in square +brackets, immediately after the variable name or partial: +.IP +.EX +${months[, ]}$ + +${articles:bibentry()[; ]$ +.EE +.PP +The separator in this case is literal and (unlike with \f[CR]sep\f[R] in +an explicit \f[CR]for\f[R] loop) cannot contain interpolated variables +or other template directives. +.SS Nesting +To ensure that content is \[lq]nested,\[rq] that is, subsequent lines +indented, use the \f[CR]\[ha]\f[R] directive: +.IP +.EX +$item.number$ $\[ha]$$item.description$ ($item.price$) +.EE +.PP +In this example, if \f[CR]item.description\f[R] has multiple lines, they +will all be indented to line up with the first line: +.IP +.EX +00123 A fine bottle of 18-year old + Oban whiskey. ($148) +.EE +.PP +To nest multiple lines to the same level, align them with the +\f[CR]\[ha]\f[R] directive in the template. +For example: +.IP +.EX +$item.number$ $\[ha]$$item.description$ ($item.price$) + (Available til $item.sellby$.) +.EE +.PP +will produce +.IP +.EX +00123 A fine bottle of 18-year old + Oban whiskey. ($148) + (Available til March 30, 2020.) +.EE +.PP +If a variable occurs by itself on a line, preceded by whitespace and not +followed by further text or directives on the same line, and the +variable\[cq]s value contains multiple lines, it will be nested +automatically. +.SS Breakable spaces +Normally, spaces in the template itself (as opposed to values of the +interpolated variables) are not breakable, but they can be made +breakable in part of the template by using the \f[CR]\[ti]\f[R] keyword +(ended with another \f[CR]\[ti]\f[R]). +.IP +.EX +$\[ti]$This long line may break if the document is rendered +with a short line length.$\[ti]$ +.EE +.SS Pipes +A pipe transforms the value of a variable or partial. +Pipes are specified using a slash (\f[CR]/\f[R]) between the variable +name (or partial) and the pipe name. +Example: +.IP +.EX +$for(name)$ +$name/uppercase$ +$endfor$ + +$for(metadata/pairs)$ +- $it.key$: $it.value$ +$endfor$ + +$employee:name()/uppercase$ +.EE +.PP +Pipes may be chained: +.IP +.EX +$for(employees/pairs)$ +$it.key/alpha/uppercase$. $it.name$ +$endfor$ +.EE +.PP +Some pipes take parameters: +.IP +.EX +|----------------------|------------| +$for(employee)$ +$it.name.first/uppercase/left 20 \[dq]| \[dq]$$it.name.salary/right 10 \[dq] | \[dq] \[dq] |\[dq]$ +$endfor$ +|----------------------|------------| +.EE +.PP +Currently the following pipes are predefined: +.IP \[bu] 2 +\f[CR]pairs\f[R]: Converts a map or array to an array of maps, each with +\f[CR]key\f[R] and \f[CR]value\f[R] fields. +If the original value was an array, the \f[CR]key\f[R] will be the array +index, starting with 1. +.IP \[bu] 2 +\f[CR]uppercase\f[R]: Converts text to uppercase. +.IP \[bu] 2 +\f[CR]lowercase\f[R]: Converts text to lowercase. +.IP \[bu] 2 +\f[CR]length\f[R]: Returns the length of the value: number of characters +for a textual value, number of elements for a map or array. +.IP \[bu] 2 +\f[CR]reverse\f[R]: Reverses a textual value or array, and has no effect +on other values. +.IP \[bu] 2 +\f[CR]first\f[R]: Returns the first value of an array, if applied to a +non-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]last\f[R]: Returns the last value of an array, if applied to a +non-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]rest\f[R]: Returns all but the first value of an array, if applied +to a non-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]allbutlast\f[R]: Returns all but the last value of an array, if +applied to a non-empty array; otherwise returns the original value. +.IP \[bu] 2 +\f[CR]chomp\f[R]: Removes trailing newlines (and breakable space). +.IP \[bu] 2 +\f[CR]nowrap\f[R]: Disables line wrapping on breakable spaces. +.IP \[bu] 2 +\f[CR]alpha\f[R]: Converts textual values that can be read as an integer +into lowercase alphabetic characters \f[CR]a..z\f[R] (mod 26). +This can be used to get lettered enumeration from array indices. +To get uppercase letters, chain with \f[CR]uppercase\f[R]. +.IP \[bu] 2 +\f[CR]roman\f[R]: Converts textual values that can be read as an integer +into lowercase roman numerals. +This can be used to get lettered enumeration from array indices. +To get uppercase roman, chain with \f[CR]uppercase\f[R]. +.IP \[bu] 2 +\f[CR]left n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +textual value in a block of width \f[CR]n\f[R], aligned to the left, +with an optional left and right border. +Has no effect on other values. +This can be used to align material in tables. +Widths are positive integers indicating the number of characters. +Borders are strings inside double quotes; literal \f[CR]\[dq]\f[R] and +\f[CR]\[rs]\f[R] characters must be backslash-escaped. +.IP \[bu] 2 +\f[CR]right n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders a +textual value in a block of width \f[CR]n\f[R], aligned to the right, +and has no effect on other values. +.IP \[bu] 2 +\f[CR]center n \[dq]leftborder\[dq] \[dq]rightborder\[dq]\f[R]: Renders +a textual value in a block of width \f[CR]n\f[R], aligned to the center, +and has no effect on other values. +.SS Variables +.SS Metadata variables +.TP +\f[CR]title\f[R], \f[CR]author\f[R], \f[CR]date\f[R] +allow identification of basic aspects of the document. +Included in PDF metadata through LaTeX and ConTeXt. +These can be set through a pandoc title block, which allows for multiple +authors, or through a YAML metadata block: +.RS +.IP +.EX +--- +author: +- Aristotle +- Peter Abelard +\&... +.EE +.PP +Note that if you just want to set PDF or HTML metadata, without +including a title block in the document itself, you can set the +\f[CR]title-meta\f[R], \f[CR]author-meta\f[R], and \f[CR]date-meta\f[R] +variables. +(By default these are set automatically, based on \f[CR]title\f[R], +\f[CR]author\f[R], and \f[CR]date\f[R].) +The page title in HTML is set by \f[CR]pagetitle\f[R], which is equal to +\f[CR]title\f[R] by default. +.RE +.TP +\f[CR]subtitle\f[R] +document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx +documents +.TP +\f[CR]abstract\f[R] +document summary, included in HTML, LaTeX, ConTeXt, AsciiDoc, and docx +documents +.TP +\f[CR]abstract-title\f[R] +title of abstract, currently used only in HTML, EPUB, and docx. +This will be set automatically to a localized value, depending on +\f[CR]lang\f[R], but can be manually overridden. +.TP +\f[CR]keywords\f[R] +list of keywords to be included in HTML, PDF, ODT, pptx, docx and +AsciiDoc metadata; repeat as for \f[CR]author\f[R], above +.TP +\f[CR]subject\f[R] +document subject, included in ODT, PDF, docx, EPUB, and pptx metadata +.TP +\f[CR]description\f[R] +document description, included in ODT, docx and pptx metadata. +Some applications show this as \f[CR]Comments\f[R] metadata. +.TP +\f[CR]category\f[R] +document category, included in docx and pptx metadata +.PP +Additionally, any root-level string metadata, not included in ODT, docx +or pptx metadata is added as a \f[I]custom property\f[R]. +The following YAML metadata block for instance: +.IP +.EX +--- +title: \[aq]This is the title\[aq] +subtitle: \[dq]This is the subtitle\[dq] +author: +- Author One +- Author Two +description: | + This is a long + description. + + It consists of two paragraphs +\&... +.EE +.PP +will include \f[CR]title\f[R], \f[CR]author\f[R] and +\f[CR]description\f[R] as standard document properties and +\f[CR]subtitle\f[R] as a custom property when converting to docx, ODT or +pptx. +.SS Language variables +.TP +\f[CR]lang\f[R] +identifies the main language of the document using IETF language tags +(following the BCP 47 standard), such as \f[CR]en\f[R] or +\f[CR]en-GB\f[R]. +The Language subtag lookup tool can look up or verify these tags. +This affects most formats, and controls hyphenation in PDF output when +using LaTeX (through \f[CR]babel\f[R] and \f[CR]polyglossia\f[R]) or +ConTeXt. +.RS +.PP +Use native pandoc Divs and Spans with the \f[CR]lang\f[R] attribute to +switch the language: +.IP +.EX +--- +lang: en-GB +\&... + +Text in the main document language (British English). + +::: {lang=fr-CA} +> Cette citation est écrite en français canadien. +::: + +More text in English. [\[aq]Zitat auf Deutsch.\[aq]]{lang=de} +.EE +.RE +.TP +\f[CR]dir\f[R] +the base script direction, either \f[CR]rtl\f[R] (right-to-left) or +\f[CR]ltr\f[R] (left-to-right). +.RS +.PP +For bidirectional documents, native pandoc \f[CR]span\f[R]s and +\f[CR]div\f[R]s with the \f[CR]dir\f[R] attribute (value \f[CR]rtl\f[R] +or \f[CR]ltr\f[R]) can be used to override the base direction in some +output formats. +This may not always be necessary if the final renderer (e.g.\ the +browser, when generating HTML) supports the Unicode Bidirectional +Algorithm. +.PP +When using LaTeX for bidirectional documents, only the +\f[CR]xelatex\f[R] engine is fully supported (use +\f[CR]--pdf-engine=xelatex\f[R]). +.RE +.SS Variables for HTML +.TP +\f[CR]document-css\f[R] +Enables inclusion of most of the CSS in the \f[CR]styles.html\f[R] +partial (have a look with +\f[CR]pandoc --print-default-data-file=templates/styles.html\f[R]). +Unless you use \f[CR]--css\f[R], this variable is set to \f[CR]true\f[R] +by default. +You can disable it with e.g.\ \f[CR]pandoc -M document-css=false\f[R]. +.TP +\f[CR]mainfont\f[R] +sets the CSS \f[CR]font-family\f[R] property on the \f[CR]html\f[R] +element. +.TP +\f[CR]fontsize\f[R] +sets the base CSS \f[CR]font-size\f[R], which you\[cq]d usually set to +e.g.\ \f[CR]20px\f[R], but it also accepts \f[CR]pt\f[R] (12pt = 16px in +most browsers). +.TP +\f[CR]fontcolor\f[R] +sets the CSS \f[CR]color\f[R] property on the \f[CR]html\f[R] element. +.TP +\f[CR]linkcolor\f[R] +sets the CSS \f[CR]color\f[R] property on all links. +.TP +\f[CR]monofont\f[R] +sets the CSS \f[CR]font-family\f[R] property on \f[CR]code\f[R] +elements. +.TP +\f[CR]monobackgroundcolor\f[R] +sets the CSS \f[CR]background-color\f[R] property on \f[CR]code\f[R] +elements and adds extra padding. +.TP +\f[CR]linestretch\f[R] +sets the CSS \f[CR]line-height\f[R] property on the \f[CR]html\f[R] +element, which is preferred to be unitless. +.TP +\f[CR]maxwidth\f[R] +sets the CSS \f[CR]max-width\f[R] property (default is 32em). +.TP +\f[CR]backgroundcolor\f[R] +sets the CSS \f[CR]background-color\f[R] property on the \f[CR]html\f[R] +element. +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +sets the corresponding CSS \f[CR]padding\f[R] properties on the +\f[CR]body\f[R] element. +.PP +To override or extend some CSS for just one document, include for +example: +.IP +.EX +--- +header-includes: | + +--- +.EE +.SS Variables for HTML math +.TP +\f[CR]classoption\f[R] +when using KaTeX, you can render display math equations flush left using +YAML metadata or with \f[CR]-M classoption=fleqn\f[R]. +.SS Variables for HTML slides +These affect HTML output when producing slide shows with pandoc. +.TP +\f[CR]institute\f[R] +author affiliations: can be a list when there are multiple authors +.TP +\f[CR]revealjs-url\f[R] +base URL for reveal.js documents (defaults to +\f[CR]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R]) +.TP +\f[CR]s5-url\f[R] +base URL for S5 documents (defaults to \f[CR]s5/default\f[R]) +.TP +\f[CR]slidy-url\f[R] +base URL for Slidy documents (defaults to +\f[CR]https://www.w3.org/Talks/Tools/Slidy2\f[R]) +.TP +\f[CR]slideous-url\f[R] +base URL for Slideous documents (defaults to \f[CR]slideous\f[R]) +.TP +\f[CR]title-slide-attributes\f[R] +additional attributes for the title slide of reveal.js slide shows. +See background in reveal.js, beamer, and pptx for an example. +.PP +All reveal.js configuration options are available as variables. +To turn off boolean flags that default to true in reveal.js, use +\f[CR]0\f[R]. +.SS Variables for Beamer slides +These variables change the appearance of PDF slides using +\f[CR]beamer\f[R]. +.TP +\f[CR]aspectratio\f[R] +slide aspect ratio (\f[CR]43\f[R] for 4:3 [default], \f[CR]169\f[R] for +16:9, \f[CR]1610\f[R] for 16:10, \f[CR]149\f[R] for 14:9, \f[CR]141\f[R] +for 1.41:1, \f[CR]54\f[R] for 5:4, \f[CR]32\f[R] for 3:2) +.TP +\f[CR]beameroption\f[R] +add extra beamer option with \f[CR]\[rs]setbeameroption{}\f[R] +.TP +\f[CR]institute\f[R] +author affiliations: can be a list when there are multiple authors +.TP +\f[CR]logo\f[R] +logo image for slides +.TP +\f[CR]navigation\f[R] +controls navigation symbols (default is \f[CR]empty\f[R] for no +navigation symbols; other valid values are \f[CR]frame\f[R], +\f[CR]vertical\f[R], and \f[CR]horizontal\f[R]) +.TP +\f[CR]section-titles\f[R] +enables \[lq]title pages\[rq] for new sections (default is true) +.TP +\f[CR]theme\f[R], \f[CR]colortheme\f[R], \f[CR]fonttheme\f[R], \f[CR]innertheme\f[R], \f[CR]outertheme\f[R] +beamer themes +.TP +\f[CR]themeoptions\f[R] +options for LaTeX beamer themes (a list). +.TP +\f[CR]titlegraphic\f[R] +image for title slide +.SS Variables for PowerPoint +These variables control the visual aspects of a slide show that are not +easily controlled via templates. +.TP +\f[CR]monofont\f[R] +font to use for code. +.SS Variables for LaTeX +Pandoc uses these variables when creating a PDF with a LaTeX engine. +.SS Layout +.TP +\f[CR]block-headings\f[R] +make \f[CR]\[rs]paragraph\f[R] and \f[CR]\[rs]subparagraph\f[R] (fourth- +and fifth-level headings, or fifth- and sixth-level with book classes) +free-standing rather than run-in; requires further formatting to +distinguish from \f[CR]\[rs]subsubsection\f[R] (third- or fourth-level +headings). +Instead of using this option, KOMA-Script can adjust headings more +extensively: +.RS +.IP +.EX +--- +documentclass: scrartcl +header-includes: | + \[rs]RedeclareSectionCommand[ + beforeskip=-10pt plus -2pt minus -1pt, + afterskip=1sp plus -1sp minus 1sp, + font=\[rs]normalfont\[rs]itshape]{paragraph} + \[rs]RedeclareSectionCommand[ + beforeskip=-10pt plus -2pt minus -1pt, + afterskip=1sp plus -1sp minus 1sp, + font=\[rs]normalfont\[rs]scshape, + indent=0pt]{subparagraph} +\&... +.EE +.RE +.TP +\f[CR]classoption\f[R] +option for document class, e.g.\ \f[CR]oneside\f[R]; repeat for multiple +options: +.RS +.IP +.EX +--- +classoption: +- twocolumn +- landscape +\&... +.EE +.RE +.TP +\f[CR]documentclass\f[R] +document class: usually one of the standard classes, \f[CR]article\f[R], +\f[CR]book\f[R], and \f[CR]report\f[R]; the KOMA-Script equivalents, +\f[CR]scrartcl\f[R], \f[CR]scrbook\f[R], and \f[CR]scrreprt\f[R], which +default to smaller margins; or \f[CR]memoir\f[R] +.TP +\f[CR]geometry\f[R] +option for \f[CR]geometry\f[R] package, e.g.\ \f[CR]margin=1in\f[R]; +repeat for multiple options: +.RS +.IP +.EX +--- +geometry: +- top=30mm +- left=20mm +- heightrounded +\&... +.EE +.RE +.TP +\f[CR]hyperrefoptions\f[R] +option for \f[CR]hyperref\f[R] package, e.g.\ \f[CR]linktoc=all\f[R]; +repeat for multiple options: +.RS +.IP +.EX +--- +hyperrefoptions: +- linktoc=all +- pdfwindowui +- pdfpagemode=FullScreen +\&... +.EE +.RE +.TP +\f[CR]indent\f[R] +if true, pandoc will use document class settings for indentation (the +default LaTeX template otherwise removes indentation and adds space +between paragraphs) +.TP +\f[CR]linestretch\f[R] +adjusts line spacing using the \f[CR]setspace\f[R] package, +e.g.\ \f[CR]1.25\f[R], \f[CR]1.5\f[R] +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +sets margins if \f[CR]geometry\f[R] is not used (otherwise +\f[CR]geometry\f[R] overrides these) +.TP +\f[CR]pagestyle\f[R] +control \f[CR]\[rs]pagestyle{}\f[R]: the default article class supports +\f[CR]plain\f[R] (default), \f[CR]empty\f[R] (no running heads or page +numbers), and \f[CR]headings\f[R] (section titles in running heads) +.TP +\f[CR]papersize\f[R] +paper size, e.g.\ \f[CR]letter\f[R], \f[CR]a4\f[R] +.TP +\f[CR]secnumdepth\f[R] +numbering depth for sections (with \f[CR]--number-sections\f[R] option +or \f[CR]numbersections\f[R] variable) +.TP +\f[CR]beamerarticle\f[R] +produce an article from Beamer slides +.SS Fonts +.TP +\f[CR]fontenc\f[R] +allows font encoding to be specified through \f[CR]fontenc\f[R] package +(with \f[CR]pdflatex\f[R]); default is \f[CR]T1\f[R] (see LaTeX font +encodings guide) +.TP +\f[CR]fontfamily\f[R] +font package for use with \f[CR]pdflatex\f[R]: TeX Live includes many +options, documented in the LaTeX Font Catalogue. +The default is Latin Modern. +.TP +\f[CR]fontfamilyoptions\f[R] +options for package used as \f[CR]fontfamily\f[R]; repeat for multiple +options. +For example, to use the Libertine font with proportional lowercase +(old-style) figures through the \f[CR]libertinus\f[R] package: +.RS +.IP +.EX +--- +fontfamily: libertinus +fontfamilyoptions: +- osf +- p +\&... +.EE +.RE +.TP +\f[CR]fontsize\f[R] +font size for body text. +The standard classes allow 10pt, 11pt, and 12pt. +To use another size, set \f[CR]documentclass\f[R] to one of the +KOMA-Script classes, such as \f[CR]scrartcl\f[R] or \f[CR]scrbook\f[R]. +.TP +\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R], \f[CR]CJKsansfont\f[R], \f[CR]CJKmonofont\f[R] +font families for use with \f[CR]xelatex\f[R] or \f[CR]lualatex\f[R]: +take the name of any system font, using the \f[CR]fontspec\f[R] package. +\f[CR]CJKmainfont\f[R] uses the \f[CR]xecjk\f[R] package. +.TP +\f[CR]mainfontoptions\f[R], \f[CR]sansfontoptions\f[R], \f[CR]monofontoptions\f[R], \f[CR]mathfontoptions\f[R], \f[CR]CJKoptions\f[R] +options to use with \f[CR]mainfont\f[R], \f[CR]sansfont\f[R], +\f[CR]monofont\f[R], \f[CR]mathfont\f[R], \f[CR]CJKmainfont\f[R] in +\f[CR]xelatex\f[R] and \f[CR]lualatex\f[R]. +Allow for any choices available through \f[CR]fontspec\f[R]; repeat for +multiple options. +For example, to use the TeX Gyre version of Palatino with lowercase +figures: +.RS +.IP +.EX +--- +mainfont: TeX Gyre Pagella +mainfontoptions: +- Numbers=Lowercase +- Numbers=Proportional +\&... +.EE +.RE +.TP +\f[CR]babelfonts\f[R] +a map of Babel language names (e.g.\ \f[CR]chinese\f[R]) to the font to +be used with the language: +.RS +.PP + * * * * * +.PP +babelfonts: chinese-hant: \[lq]Noto Serif CJK TC\[rq] russian: \[lq]Noto +Serif\[rq] \&... +.RE +.TP +\f[CR]microtypeoptions\f[R] +options to pass to the microtype package +.SS Links +.TP +\f[CR]colorlinks\f[R] +add color to link text; automatically enabled if any of +\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], +\f[CR]urlcolor\f[R], or \f[CR]toccolor\f[R] are set +.TP +\f[CR]boxlinks\f[R] +add visible box around links (has no effect if \f[CR]colorlinks\f[R] is +set) +.TP +\f[CR]linkcolor\f[R], \f[CR]filecolor\f[R], \f[CR]citecolor\f[R], \f[CR]urlcolor\f[R], \f[CR]toccolor\f[R] +color for internal links, external links, citation links, linked URLs, +and links in table of contents, respectively: uses options allowed by +\f[CR]xcolor\f[R], including the \f[CR]dvipsnames\f[R], +\f[CR]svgnames\f[R], and \f[CR]x11names\f[R] lists +.TP +\f[CR]links-as-notes\f[R] +causes links to be printed as footnotes +.TP +\f[CR]urlstyle\f[R] +style for URLs (e.g., \f[CR]tt\f[R], \f[CR]rm\f[R], \f[CR]sf\f[R], and, +the default, \f[CR]same\f[R]) +.SS Front matter +.TP +\f[CR]lof\f[R], \f[CR]lot\f[R] +include list of figures, list of tables +.TP +\f[CR]thanks\f[R] +contents of acknowledgments footnote after document title +.TP +\f[CR]toc\f[R] +include table of contents (can also be set using +\f[CR]--toc/--table-of-contents\f[R]) +.TP +\f[CR]toc-depth\f[R] +level of section to include in table of contents +.SS BibLaTeX Bibliographies +These variables function when using BibLaTeX for citation rendering. +.TP +\f[CR]biblatexoptions\f[R] +list of options for biblatex +.TP +\f[CR]biblio-style\f[R] +bibliography style, when used with \f[CR]--natbib\f[R] and +\f[CR]--biblatex\f[R] +.TP +\f[CR]biblio-title\f[R] +bibliography title, when used with \f[CR]--natbib\f[R] and +\f[CR]--biblatex\f[R] +.TP +\f[CR]bibliography\f[R] +bibliography to use for resolving references +.TP +\f[CR]natbiboptions\f[R] +list of options for natbib +.SS Variables for ConTeXt +Pandoc uses these variables when creating a PDF with ConTeXt. +.TP +\f[CR]fontsize\f[R] +font size for body text (e.g.\ \f[CR]10pt\f[R], \f[CR]12pt\f[R]) +.TP +\f[CR]headertext\f[R], \f[CR]footertext\f[R] +text to be placed in running header or footer (see ConTeXt Headers and +Footers); repeat up to four times for different placement +.TP +\f[CR]indenting\f[R] +controls indentation of paragraphs, e.g.\ \f[CR]yes,small,next\f[R] (see +ConTeXt Indentation); repeat for multiple options +.TP +\f[CR]interlinespace\f[R] +adjusts line spacing, e.g.\ \f[CR]4ex\f[R] (using +\f[CR]setupinterlinespace\f[R]); repeat for multiple options +.TP +\f[CR]layout\f[R] +options for page margins and text arrangement (see ConTeXt Layout); +repeat for multiple options +.TP +\f[CR]linkcolor\f[R], \f[CR]contrastcolor\f[R] +color for links outside and inside a page, e.g.\ \f[CR]red\f[R], +\f[CR]blue\f[R] (see ConTeXt Color) +.TP +\f[CR]linkstyle\f[R] +typeface style for links, e.g.\ \f[CR]normal\f[R], \f[CR]bold\f[R], +\f[CR]slanted\f[R], \f[CR]boldslanted\f[R], \f[CR]type\f[R], +\f[CR]cap\f[R], \f[CR]small\f[R] +.TP +\f[CR]lof\f[R], \f[CR]lot\f[R] +include list of figures, list of tables +.TP +\f[CR]mainfont\f[R], \f[CR]sansfont\f[R], \f[CR]monofont\f[R], \f[CR]mathfont\f[R] +font families: take the name of any system font (see ConTeXt Font +Switching) +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +sets margins, if \f[CR]layout\f[R] is not used (otherwise +\f[CR]layout\f[R] overrides these) +.TP +\f[CR]pagenumbering\f[R] +page number style and location (using \f[CR]setuppagenumbering\f[R]); +repeat for multiple options +.TP +\f[CR]papersize\f[R] +paper size, e.g.\ \f[CR]letter\f[R], \f[CR]A4\f[R], \f[CR]landscape\f[R] +(see ConTeXt Paper Setup); repeat for multiple options +.TP +\f[CR]pdfa\f[R] +adds to the preamble the setup necessary to generate PDF/A of the type +specified, e.g.\ \f[CR]1a:2005\f[R], \f[CR]2a\f[R]. +If no type is specified (i.e.\ the value is set to True, by e.g. +\f[CR]--metadata=pdfa\f[R] or \f[CR]pdfa: true\f[R] in a YAML metadata +block), \f[CR]1b:2005\f[R] will be used as default, for reasons of +backwards compatibility. +Using \f[CR]--variable=pdfa\f[R] without specified value is not +supported. +To successfully generate PDF/A the required ICC color profiles have to +be available and the content and all included files (such as images) +have to be standard-conforming. +The ICC profiles and output intent may be specified using the variables +\f[CR]pdfaiccprofile\f[R] and \f[CR]pdfaintent\f[R]. +See also ConTeXt PDFA for more details. +.TP +\f[CR]pdfaiccprofile\f[R] +when used in conjunction with \f[CR]pdfa\f[R], specifies the ICC profile +to use in the PDF, e.g.\ \f[CR]default.cmyk\f[R]. +If left unspecified, \f[CR]sRGB.icc\f[R] is used as default. +May be repeated to include multiple profiles. +Note that the profiles have to be available on the system. +They can be obtained from ConTeXt ICC Profiles. +.TP +\f[CR]pdfaintent\f[R] +when used in conjunction with \f[CR]pdfa\f[R], specifies the output +intent for the colors, +e.g.\ \f[CR]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If +left unspecified, \f[CR]sRGB IEC61966-2.1\f[R] is used as default. +.TP +\f[CR]toc\f[R] +include table of contents (can also be set using +\f[CR]--toc/--table-of-contents\f[R]) +.TP +\f[CR]urlstyle\f[R] +typeface style for links without link text, e.g.\ \f[CR]normal\f[R], +\f[CR]bold\f[R], \f[CR]slanted\f[R], \f[CR]boldslanted\f[R], +\f[CR]type\f[R], \f[CR]cap\f[R], \f[CR]small\f[R] +.TP +\f[CR]whitespace\f[R] +spacing between paragraphs, e.g.\ \f[CR]none\f[R], \f[CR]small\f[R] +(using \f[CR]setupwhitespace\f[R]) +.TP +\f[CR]includesource\f[R] +include all source documents as file attachments in the PDF file +.SS Variables for \f[CR]wkhtmltopdf\f[R] +Pandoc uses these variables when creating a PDF with +\f[CR]wkhtmltopdf\f[R]. +The \f[CR]--css\f[R] option also affects the output. +.TP +\f[CR]footer-html\f[R], \f[CR]header-html\f[R] +add information to the header and footer +.TP +\f[CR]margin-left\f[R], \f[CR]margin-right\f[R], \f[CR]margin-top\f[R], \f[CR]margin-bottom\f[R] +set the page margins +.TP +\f[CR]papersize\f[R] +sets the PDF paper size +.SS Variables for man pages +.TP +\f[CR]adjusting\f[R] +adjusts text to left (\f[CR]l\f[R]), right (\f[CR]r\f[R]), center +(\f[CR]c\f[R]), or both (\f[CR]b\f[R]) margins +.TP +\f[CR]footer\f[R] +footer in man pages +.TP +\f[CR]header\f[R] +header in man pages +.TP +\f[CR]section\f[R] +section number in man pages +.SS Variables for Typst +.TP +\f[CR]margin\f[R] +A dictionary with the fields defined in the Typst documentation: +\f[CR]x\f[R], \f[CR]y\f[R], \f[CR]top\f[R], \f[CR]bottom\f[R], +\f[CR]left\f[R], \f[CR]right\f[R]. +.TP +\f[CR]papersize\f[R] +Paper size: \f[CR]a4\f[R], \f[CR]us-letter\f[R], etc. +.TP +\f[CR]mainfont\f[R] +Name of system font to use for the main font. +.TP +\f[CR]fontsize\f[R] +Font size (e.g., \f[CR]12pt\f[R]). +.TP +\f[CR]section-numbering\f[R] +Schema to use for numbering sections, e.g.\ \f[CR]1.A.1\f[R]. +.TP +\f[CR]columns\f[R] +Number of columns for body text. +.SS Variables for ms +.TP +\f[CR]fontfamily\f[R] +\f[CR]A\f[R] (Avant Garde), \f[CR]B\f[R] (Bookman), \f[CR]C\f[R] +(Helvetica), \f[CR]HN\f[R] (Helvetica Narrow), \f[CR]P\f[R] (Palatino), +or \f[CR]T\f[R] (Times New Roman). +This setting does not affect source code, which is always displayed +using monospace Courier. +These built-in fonts are limited in their coverage of characters. +Additional fonts may be installed using the script +\f[CR]install-font.sh\f[R] provided by Peter Schaffter and documented in +detail on his web site. +.TP +\f[CR]indent\f[R] +paragraph indent (e.g.\ \f[CR]2m\f[R]) +.TP +\f[CR]lineheight\f[R] +line height (e.g.\ \f[CR]12p\f[R]) +.TP +\f[CR]pointsize\f[R] +point size (e.g.\ \f[CR]10p\f[R]) +.SS Variables set automatically +Pandoc sets these variables automatically in response to options or +document contents; users can also modify them. +These vary depending on the output format, and include the following: +.TP +\f[CR]body\f[R] +body of document +.TP +\f[CR]date-meta\f[R] +the \f[CR]date\f[R] variable converted to ISO 8601 YYYY-MM-DD, included +in all HTML based formats (dzslides, epub, html, html4, html5, revealjs, +s5, slideous, slidy). +The recognized formats for \f[CR]date\f[R] are: \f[CR]mm/dd/yyyy\f[R], +\f[CR]mm/dd/yy\f[R], \f[CR]yyyy-mm-dd\f[R] (ISO 8601), +\f[CR]dd MM yyyy\f[R] (e.g.\ either \f[CR]02 Apr 2018\f[R] or +\f[CR]02 April 2018\f[R]), \f[CR]MM dd, yyyy\f[R] +(e.g.\ \f[CR]Apr. 02, 2018\f[R] or +\f[CR]April 02, 2018),\f[R]yyyy[mm[dd]]\f[CR](e.g.\f[R]20180402, +\f[CR]201804\f[R] or \f[CR]2018\f[R]). +.TP +\f[CR]header-includes\f[R] +contents specified by \f[CR]-H/--include-in-header\f[R] (may have +multiple values) +.TP +\f[CR]include-before\f[R] +contents specified by \f[CR]-B/--include-before-body\f[R] (may have +multiple values) +.TP +\f[CR]include-after\f[R] +contents specified by \f[CR]-A/--include-after-body\f[R] (may have +multiple values) +.TP +\f[CR]meta-json\f[R] +JSON representation of all of the document\[cq]s metadata. +Field values are transformed to the selected output format. +.TP +\f[CR]numbersections\f[R] +non-null value if \f[CR]-N/--number-sections\f[R] was specified +.TP +\f[CR]sourcefile\f[R], \f[CR]outputfile\f[R] +source and destination filenames, as given on the command line. +\f[CR]sourcefile\f[R] can also be a list if input comes from multiple +files, or empty if input is from stdin. +You can use the following snippet in your template to distinguish them: +.RS +.IP +.EX +$if(sourcefile)$ +$for(sourcefile)$ +$sourcefile$ +$endfor$ +$else$ +(stdin) +$endif$ +.EE +.PP +Similarly, \f[CR]outputfile\f[R] can be \f[CR]-\f[R] if output goes to +the terminal. +.PP +If you need absolute paths, use e.g.\ \f[CR]$curdir$/$sourcefile$\f[R]. +.RE +.TP +\f[CR]curdir\f[R] +working directory from which pandoc is run. +.TP +\f[CR]pandoc-version\f[R] +pandoc version. +.TP +\f[CR]toc\f[R] +non-null value if \f[CR]--toc/--table-of-contents\f[R] was specified +.TP +\f[CR]toc-title\f[R] +title of table of contents (works only with EPUB, HTML, revealjs, +opendocument, odt, docx, pptx, beamer, LaTeX) +.SH EXTENSIONS +The behavior of some of the readers and writers can be adjusted by +enabling or disabling various extensions. +.PP +An extension can be enabled by adding \f[CR]+EXTENSION\f[R] to the +format name and disabled by adding \f[CR]-EXTENSION\f[R]. +For example, \f[CR]--from markdown_strict+footnotes\f[R] is strict +Markdown with footnotes enabled, while +\f[CR]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s +Markdown without footnotes or pipe tables. +.PP +The markdown reader and writer make by far the most use of extensions. +Extensions only used by them are therefore covered in the section +Pandoc\[cq]s Markdown below (see Markdown variants for +\f[CR]commonmark\f[R] and \f[CR]gfm\f[R]). +In the following, extensions that also work for other formats are +covered. +.PP +Note that markdown extensions added to the \f[CR]ipynb\f[R] format +affect Markdown cells in Jupyter notebooks (as do command-line options +like \f[CR]--markdown-headings\f[R]). +.SS Typography +.SS Extension: \f[CR]smart\f[R] +Interpret straight quotes as curly quotes, \f[CR]---\f[R] as em-dashes, +\f[CR]--\f[R] as en-dashes, and \f[CR]...\f[R] as ellipses. +Nonbreaking spaces are inserted after certain abbreviations, such as +\[lq]Mr.\[rq] +.PP +This extension can be enabled/disabled for the following formats: +.TP +input formats +\f[CR]markdown\f[R], \f[CR]commonmark\f[R], \f[CR]latex\f[R], +\f[CR]mediawiki\f[R], \f[CR]org\f[R], \f[CR]rst\f[R], \f[CR]twiki\f[R], +\f[CR]html\f[R] +.TP +output formats +\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R], +\f[CR]rst\f[R] +.TP +enabled by default in +\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]context\f[R] (both input +and output) +.PP +Note: If you are \f[I]writing\f[R] Markdown, then the \f[CR]smart\f[R] +extension has the reverse effect: what would have been curly quotes +comes out straight. +.PP +In LaTeX, \f[CR]smart\f[R] means to use the standard TeX ligatures for +quotation marks (\f[CR]\[ga]\[ga]\f[R] and \f[CR]\[aq]\[aq]\f[R] for +double quotes, \f[CR]\[ga]\f[R] and \f[CR]\[aq]\f[R] for single quotes) +and dashes (\f[CR]--\f[R] for en-dash and \f[CR]---\f[R] for em-dash). +If \f[CR]smart\f[R] is disabled, then in reading LaTeX pandoc will parse +these characters literally. +In writing LaTeX, enabling \f[CR]smart\f[R] tells pandoc to use the +ligatures when possible; if \f[CR]smart\f[R] is disabled pandoc will use +unicode quotation mark and dash characters. +.SS Headings and sections +.SS Extension: \f[CR]auto_identifiers\f[R] +A heading without an explicitly specified identifier will be +automatically assigned a unique identifier based on the heading text. +.PP +This extension can be enabled/disabled for the following formats: +.TP +input formats +\f[CR]markdown\f[R], \f[CR]latex\f[R], \f[CR]rst\f[R], +\f[CR]mediawiki\f[R], \f[CR]textile\f[R] +.TP +output formats +\f[CR]markdown\f[R], \f[CR]muse\f[R] +.TP +enabled by default in +\f[CR]markdown\f[R], \f[CR]muse\f[R] +.PP +The default algorithm used to derive the identifier from the heading +text is: +.IP \[bu] 2 +Remove all formatting, links, etc. +.IP \[bu] 2 +Remove all footnotes. +.IP \[bu] 2 +Remove all non-alphanumeric characters, except underscores, hyphens, and +periods. +.IP \[bu] 2 +Replace all spaces and newlines with hyphens. +.IP \[bu] 2 +Convert all alphabetic characters to lowercase. +.IP \[bu] 2 +Remove everything up to the first letter (identifiers may not begin with +a number or punctuation mark). +.IP \[bu] 2 +If nothing is left after this, use the identifier \f[CR]section\f[R]. +.PP +Thus, for example, +.RS -14n +.IP +.EX + Heading Identifier + ----------------------------- ----------------------------- + Heading identifiers in HTML heading-identifiers-in-html + Maître d\[aq]hôtel maître-dhôtel + *Dogs*?--in *my* house? dogs--in-my-house + [HTML], [S5], or [RTF]? html-s5-or-rtf + 3. Applications applications + 33 section +.EE +.RE +.PP +These rules should, in most cases, allow one to determine the identifier +from the heading text. +The exception is when several headings have the same text; in this case, +the first will get an identifier as described above; the second will get +the same identifier with \f[CR]-1\f[R] appended; the third with +\f[CR]-2\f[R]; and so on. +.PP +(However, a different algorithm is used if +\f[CR]gfm_auto_identifiers\f[R] is enabled; see below.) +.PP +These identifiers are used to provide link targets in the table of +contents generated by the \f[CR]--toc|--table-of-contents\f[R] option. +They also make it easy to provide links from one section of a document +to another. +A link to this section, for example, might look like this: +.IP +.EX +See the section on +[heading identifiers](#heading-identifiers-in-html-latex-and-context). +.EE +.PP +Note, however, that this method of providing links to sections works +only in HTML, LaTeX, and ConTeXt formats. +.PP +If the \f[CR]--section-divs\f[R] option is specified, then each section +will be wrapped in a \f[CR]section\f[R] (or a \f[CR]div\f[R], if +\f[CR]html4\f[R] was specified), and the identifier will be attached to +the enclosing \f[CR]
\f[R] (or \f[CR]
\f[R]) tag rather than +the heading itself. +This allows entire sections to be manipulated using JavaScript or +treated differently in CSS. +.SS Extension: \f[CR]ascii_identifiers\f[R] +Causes the identifiers produced by \f[CR]auto_identifiers\f[R] to be +pure ASCII. +Accents are stripped off of accented Latin letters, and non-Latin +letters are omitted. +.SS Extension: \f[CR]gfm_auto_identifiers\f[R] +Changes the algorithm used by \f[CR]auto_identifiers\f[R] to conform to +GitHub\[cq]s method. +Spaces are converted to dashes (\f[CR]-\f[R]), uppercase characters to +lowercase characters, and punctuation characters other than \f[CR]-\f[R] +and \f[CR]_\f[R] are removed. +Emojis are replaced by their names. +.SS Math Input +The extensions \f[CR]tex_math_dollars\f[R], \f[CR]tex_math_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] +.SS Extension: \f[CR]native_numbering\f[R] +Enables native numbering of figures and tables. +Enumeration starts at 1. +.PP +This extension can be enabled/disabled for the following formats: +.TP +output formats +\f[CR]odt\f[R], \f[CR]opendocument\f[R], \f[CR]docx\f[R] +.SS Extension: \f[CR]xrefs_name\f[R] +Links to headings, figures and tables inside the document are +substituted with cross-references that will use the name or caption of +the referenced item. +The original link text is replaced once the generated document is +refreshed. +This extension can be combined with \f[CR]xrefs_number\f[R] in which +case numbers will appear before the name. +.PP +Text in cross-references is only made consistent with the referenced +item once the document has been refreshed. +.PP +This extension can be enabled/disabled for the following formats: +.TP +output formats +\f[CR]odt\f[R], \f[CR]opendocument\f[R] +.SS Extension: \f[CR]xrefs_number\f[R] +Links to headings, figures and tables inside the document are +substituted with cross-references that will use the number of the +referenced item. +The original link text is discarded. +This extension can be combined with \f[CR]xrefs_name\f[R] in which case +the name or caption numbers will appear after the number. +.PP +For the \f[CR]xrefs_number\f[R] to be useful heading numbers must be +enabled in the generated document, also table and figure captions must +be enabled using for example the \f[CR]native_numbering\f[R] extension. +.PP +Numbers in cross-references are only visible in the final document once +it has been refreshed. +.PP +This extension can be enabled/disabled for the following formats: +.TP +output formats +\f[CR]odt\f[R], \f[CR]opendocument\f[R] +.SS Extension: \f[CR]styles\f[R] +When converting from docx, read all docx styles as divs (for paragraph +styles) and spans (for character styles) regardless of whether pandoc +understands the meaning of these styles. +This can be used with docx custom styles. +Disabled by default. +.TP +input formats +\f[CR]docx\f[R] +.SS Extension: \f[CR]amuse\f[R] +In the \f[CR]muse\f[R] input format, this enables Text::Amuse extensions +to Emacs Muse markup. +.SS Extension: \f[CR]raw_markdown\f[R] +In the \f[CR]ipynb\f[R] input format, this causes Markdown cells to be +included as raw Markdown blocks (allowing lossless round-tripping) +rather than being parsed. +Use this only when you are targeting \f[CR]ipynb\f[R] or a +markdown-based output format. +.SS Extension: \f[CR]citations\f[R] +When the \f[CR]citations\f[R] extension is enabled in \f[CR]org\f[R], +org-cite and org-ref style citations will be parsed as native pandoc +citations. +.PP +When \f[CR]citations\f[R] is enabled in \f[CR]docx\f[R], citations +inserted by Zotero or Mendeley or EndNote plugins will be parsed as +native pandoc citations. +(Otherwise, the formatted citations generated by the bibliographic +software will be parsed as regular text.) +.SS Extension: \f[CR]fancy_lists\f[R] +Some aspects of Pandoc\[cq]s Markdown fancy lists are also accepted in +\f[CR]org\f[R] input, mimicking the option +\f[CR]org-list-allow-alphabetical\f[R] in Emacs. +As in Org Mode, enabling this extension allows lowercase and uppercase +alphabetical markers for ordered lists to be parsed in addition to +arabic ones. +Note that for Org, this does not include roman numerals or the +\f[CR]#\f[R] placeholder that are enabled by the extension in +Pandoc\[cq]s Markdown. +.SS Extension: \f[CR]element_citations\f[R] +In the \f[CR]jats\f[R] output formats, this causes reference items to be +replaced with \f[CR]\f[R] elements. +These elements are not influenced by CSL styles, but all information on +the item is included in tags. +.SS Extension: \f[CR]ntb\f[R] +In the \f[CR]context\f[R] output format this enables the use of Natural +Tables (TABLE) instead of the default Extreme Tables (xtables). +Natural tables allow more fine-grained global customization but come at +a performance penalty compared to extreme tables. +.SS Extension: \f[CR]tagging\f[R] +Enabling this extension with \f[CR]context\f[R] output will produce +markup suitable for the production of tagged PDFs. +This includes additional markers for paragraphs and alternative markup +for emphasized text. +The \f[CR]emphasis-command\f[R] template variable is set if the +extension is enabled. +.SH PANDOC\[cq]S MARKDOWN +Pandoc understands an extended and slightly revised version of John +Gruber\[cq]s Markdown syntax. +This document explains the syntax, noting differences from original +Markdown. +Except where noted, these differences can be suppressed by using the +\f[CR]markdown_strict\f[R] format instead of \f[CR]markdown\f[R]. +Extensions can be enabled or disabled to specify the behavior more +granularly. +They are described in the following. +See also Extensions above, for extensions that work also on other +formats. +.SS Philosophy +Markdown is designed to be easy to write, and, even more importantly, +easy to read: +.RS +.PP +A Markdown-formatted document should be publishable as-is, as plain +text, without looking like it\[cq]s been marked up with tags or +formatting instructions. +\[en] John Gruber +.RE +.PP +This principle has guided pandoc\[cq]s decisions in finding syntax for +tables, footnotes, and other extensions. +.PP +There is, however, one respect in which pandoc\[cq]s aims are different +from the original aims of Markdown. +Whereas Markdown was originally designed with HTML generation in mind, +pandoc is designed for multiple output formats. +Thus, while pandoc allows the embedding of raw HTML, it discourages it, +and provides other, non-HTMLish ways of representing important document +elements like definition lists, tables, mathematics, and footnotes. +.SS Paragraphs +A paragraph is one or more lines of text followed by one or more blank +lines. +Newlines are treated as spaces, so you can reflow your paragraphs as you +like. +If you need a hard line break, put two or more spaces at the end of a +line. +.SS Extension: \f[CR]escaped_line_breaks\f[R] +A backslash followed by a newline is also a hard line break. +Note: in multiline and grid table cells, this is the only way to create +a hard line break, since trailing spaces in the cells are ignored. +.SS Headings +There are two kinds of headings: Setext and ATX. +.SS Setext-style headings +A setext-style heading is a line of text \[lq]underlined\[rq] with a row +of \f[CR]=\f[R] signs (for a level-one heading) or \f[CR]-\f[R] signs +(for a level-two heading): +.IP +.EX +A level-one heading +=================== + +A level-two heading +------------------- +.EE +.PP +The heading text can contain inline formatting, such as emphasis (see +Inline formatting, below). +.SS ATX-style headings +An ATX-style heading consists of one to six \f[CR]#\f[R] signs and a +line of text, optionally followed by any number of \f[CR]#\f[R] signs. +The number of \f[CR]#\f[R] signs at the beginning of the line is the +heading level: +.IP +.EX +## A level-two heading + +### A level-three heading ### +.EE +.PP +As with setext-style headings, the heading text can contain formatting: +.IP +.EX +# A level-one heading with a [link](/url) and *emphasis* +.EE +.SS Extension: \f[CR]blank_before_header\f[R] +Original Markdown syntax does not require a blank line before a heading. +Pandoc does require this (except, of course, at the beginning of the +document). +The reason for the requirement is that it is all too easy for a +\f[CR]#\f[R] to end up at the beginning of a line by accident (perhaps +through line wrapping). +Consider, for example: +.IP +.EX +I like several of their flavors of ice cream: +#22, for example, and #5. +.EE +.SS Extension: \f[CR]space_in_atx_header\f[R] +Many Markdown implementations do not require a space between the opening +\f[CR]#\f[R]s of an ATX heading and the heading text, so that +\f[CR]#5 bolt\f[R] and \f[CR]#hashtag\f[R] count as headings. +With this extension, pandoc does require the space. +.SS Heading identifiers +See also the \f[CR]auto_identifiers\f[R] extension above. +.SS Extension: \f[CR]header_attributes\f[R] +Headings can be assigned attributes using this syntax at the end of the +line containing the heading text: +.IP +.EX +{#identifier .class .class key=value key=value} +.EE +.PP +Thus, for example, the following headings will all be assigned the +identifier \f[CR]foo\f[R]: +.IP +.EX +# My heading {#foo} + +## My heading ## {#foo} + +My other heading {#foo} +--------------- +.EE +.PP +(This syntax is compatible with PHP Markdown Extra.) +.PP +Note that although this syntax allows assignment of classes and +key/value attributes, writers generally don\[cq]t use all of this +information. +Identifiers, classes, and key/value attributes are used in HTML and +HTML-based formats such as EPUB and slidy. +Identifiers are used for labels and link anchors in the LaTeX, ConTeXt, +Textile, Jira markup, and AsciiDoc writers. +.PP +Headings with the class \f[CR]unnumbered\f[R] will not be numbered, even +if \f[CR]--number-sections\f[R] is specified. +A single hyphen (\f[CR]-\f[R]) in an attribute context is equivalent to +\f[CR].unnumbered\f[R], and preferable in non-English documents. +So, +.IP +.EX +# My heading {-} +.EE +.PP +is just the same as +.IP +.EX +# My heading {.unnumbered} +.EE +.PP +If the \f[CR]unlisted\f[R] class is present in addition to +\f[CR]unnumbered\f[R], the heading will not be included in a table of +contents. +(Currently this feature is only implemented for certain formats: those +based on LaTeX and HTML, PowerPoint, and RTF.) +.SS Extension: \f[CR]implicit_header_references\f[R] +Pandoc behaves as if reference links have been defined for each heading. +So, to link to a heading +.IP +.EX +# Heading identifiers in HTML +.EE +.PP +you can simply write +.IP +.EX +[Heading identifiers in HTML] +.EE +.PP +or +.IP +.EX +[Heading identifiers in HTML][] +.EE +.PP +or +.IP +.EX +[the section on heading identifiers][heading identifiers in +HTML] +.EE +.PP +instead of giving the identifier explicitly: +.IP +.EX +[Heading identifiers in HTML](#heading-identifiers-in-html) +.EE +.PP +If there are multiple headings with identical text, the corresponding +reference will link to the first one only, and you will need to use +explicit links to link to the others, as described above. +.PP +Like regular reference links, these references are case-insensitive. +.PP +Explicit link reference definitions always take priority over implicit +heading references. +So, in the following example, the link will point to \f[CR]bar\f[R], not +to \f[CR]#foo\f[R]: +.IP +.EX +# Foo + +[foo]: bar + +See [foo] +.EE +.SS Block quotations +Markdown uses email conventions for quoting blocks of text. +A block quotation is one or more paragraphs or other block elements +(such as lists or headings), with each line preceded by a \f[CR]>\f[R] +character and an optional space. +(The \f[CR]>\f[R] need not start at the left margin, but it should not +be indented more than three spaces.) +.IP +.EX +> This is a block quote. This +> paragraph has two lines. +> +> 1. This is a list inside a block quote. +> 2. Second item. +.EE +.PP +A \[lq]lazy\[rq] form, which requires the \f[CR]>\f[R] character only on +the first line of each block, is also allowed: +.IP +.EX +> This is a block quote. This +paragraph has two lines. + +> 1. This is a list inside a block quote. +2. Second item. +.EE +.PP +Among the block elements that can be contained in a block quote are +other block quotes. +That is, block quotes can be nested: +.IP +.EX +> This is a block quote. +> +> > A block quote within a block quote. +.EE +.PP +If the \f[CR]>\f[R] character is followed by an optional space, that +space will be considered part of the block quote marker and not part of +the indentation of the contents. +Thus, to put an indented code block in a block quote, you need five +spaces after the \f[CR]>\f[R]: +.IP +.EX +> code +.EE +.SS Extension: \f[CR]blank_before_blockquote\f[R] +Original Markdown syntax does not require a blank line before a block +quote. +Pandoc does require this (except, of course, at the beginning of the +document). +The reason for the requirement is that it is all too easy for a +\f[CR]>\f[R] to end up at the beginning of a line by accident (perhaps +through line wrapping). +So, unless the \f[CR]markdown_strict\f[R] format is used, the following +does not produce a nested block quote in pandoc: +.IP +.EX +> This is a block quote. +>> Not nested, since \[ga]blank_before_blockquote\[ga] is enabled by default +.EE +.SS Verbatim (code) blocks +.SS Indented code blocks +A block of text indented four spaces (or one tab) is treated as verbatim +text: that is, special characters do not trigger special formatting, and +all spaces and line breaks are preserved. +For example, +.IP +.EX + if (a > 3) { + moveShip(5 * gravity, DOWN); + } +.EE +.PP +The initial (four space or one tab) indentation is not considered part +of the verbatim text, and is removed in the output. +.PP +Note: blank lines in the verbatim text need not begin with four spaces. +.SS Fenced code blocks +.SS Extension: \f[CR]fenced_code_blocks\f[R] +In addition to standard indented code blocks, pandoc supports +\f[I]fenced\f[R] code blocks. +These begin with a row of three or more tildes (\f[CR]\[ti]\f[R]) and +end with a row of tildes that must be at least as long as the starting +row. +Everything between these lines is treated as code. +No indentation is necessary: +.IP +.EX +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +if (a > 3) { + moveShip(5 * gravity, DOWN); +} +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +.EE +.PP +Like regular code blocks, fenced code blocks must be separated from +surrounding text by blank lines. +.PP +If the code itself contains a row of tildes or backticks, just use a +longer row of tildes or backticks at the start and end: +.IP +.EX +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +code including tildes +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +.EE +.SS Extension: \f[CR]backtick_code_blocks\f[R] +Same as \f[CR]fenced_code_blocks\f[R], but uses backticks +(\f[CR]\[ga]\f[R]) instead of tildes (\f[CR]\[ti]\f[R]). +.SS Extension: \f[CR]fenced_code_attributes\f[R] +Optionally, you may attach attributes to fenced or backtick code block +using this syntax: +.IP +.EX +\[ti]\[ti]\[ti]\[ti] {#mycode .haskell .numberLines startFrom=\[dq]100\[dq]} +qsort [] = [] +qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ + qsort (filter (>= x) xs) +\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti]\[ti] +.EE +.PP +Here \f[CR]mycode\f[R] is an identifier, \f[CR]haskell\f[R] and +\f[CR]numberLines\f[R] are classes, and \f[CR]startFrom\f[R] is an +attribute with value \f[CR]100\f[R]. +Some output formats can use this information to do syntax highlighting. +Currently, the only output formats that use this information are HTML, +LaTeX, Docx, Ms, and PowerPoint. +If highlighting is supported for your output format and language, then +the code block above will appear highlighted, with numbered lines. +(To see which languages are supported, type +\f[CR]pandoc --list-highlight-languages\f[R].) +Otherwise, the code block above will appear as follows: +.IP +.EX +
+  
+  ...
+  
+
+.EE +.PP +The \f[CR]numberLines\f[R] (or \f[CR]number-lines\f[R]) class will cause +the lines of the code block to be numbered, starting with \f[CR]1\f[R] +or the value of the \f[CR]startFrom\f[R] attribute. +The \f[CR]lineAnchors\f[R] (or \f[CR]line-anchors\f[R]) class will cause +the lines to be clickable anchors in HTML output. +.PP +A shortcut form can also be used for specifying the language of the code +block: +.IP +.EX +\[ga]\[ga]\[ga]haskell +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +This is equivalent to: +.IP +.EX +\[ga]\[ga]\[ga] {.haskell} +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +This shortcut form may be combined with attributes: +.IP +.EX +\[ga]\[ga]\[ga]haskell {.numberLines} +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +Which is equivalent to: +.IP +.EX +\[ga]\[ga]\[ga] {.haskell .numberLines} +qsort [] = [] +\[ga]\[ga]\[ga] +.EE +.PP +If the \f[CR]fenced_code_attributes\f[R] extension is disabled, but +input contains class attribute(s) for the code block, the first class +attribute will be printed after the opening fence as a bare word. +.PP +To prevent all highlighting, use the \f[CR]--no-highlight\f[R] flag. +To set the highlighting style, use \f[CR]--highlight-style\f[R]. +For more information on highlighting, see Syntax highlighting, below. +.SS Line blocks +.SS Extension: \f[CR]line_blocks\f[R] +A line block is a sequence of lines beginning with a vertical bar +(\f[CR]|\f[R]) followed by a space. +The division into lines will be preserved in the output, as will any +leading spaces; otherwise, the lines will be formatted as Markdown. +This is useful for verse and addresses: +.IP +.EX +| The limerick packs laughs anatomical +| In space that is quite economical. +| But the good ones I\[aq]ve seen +| So seldom are clean +| And the clean ones so seldom are comical + +| 200 Main St. +| Berkeley, CA 94718 +.EE +.PP +The lines can be hard-wrapped if needed, but the continuation line must +begin with a space. +.IP +.EX +| The Right Honorable Most Venerable and Righteous Samuel L. + Constable, Jr. +| 200 Main St. +| Berkeley, CA 94718 +.EE +.PP +Inline formatting (such as emphasis) is allowed in the content (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 +Note: continuation paragraphs in example lists must always be indented +four spaces, regardless of the length of the list marker. +That is, example lists always behave as if the +\f[CR]four_space_rule\f[R] extension is set. +This is because example labels tend to be long, and indenting content to +the first non-space character after the label would be awkward. +.SS Ending a list +What if you want to put an indented code block after a list? +.IP +.EX +- item one +- item two + + { my code block } +.EE +.PP +Trouble! +Here pandoc (like other Markdown implementations) will treat +\f[CR]{ my code block }\f[R] as the second paragraph of item two, and +not as a code block. +.PP +To \[lq]cut off\[rq] the list after item two, you can insert some +non-indented content, like an HTML comment, which won\[cq]t produce +visible output in any format: +.IP +.EX +- item one +- item two + + + + { my code block } +.EE +.PP +You can use the same trick if you want two consecutive lists instead of +one big list: +.IP +.EX +1. one +2. two +3. three + + + +1. uno +2. dos +3. tres +.EE +.SS Horizontal rules +A line containing a row of three or more \f[CR]*\f[R], \f[CR]-\f[R], or +\f[CR]_\f[R] characters (optionally separated by spaces) produces a +horizontal rule: +.IP +.EX +* * * * + +--------------- +.EE +.PP +We strongly recommend that horizontal rules be separated from +surrounding text by blank lines. +If a horizontal rule is not followed by a blank line, pandoc may try to +interpret the lines that follow as a YAML metadata block or a table. +.SS Tables +Four kinds of tables may be used. +The first three kinds presuppose the use of a fixed-width font, such as +Courier. +The fourth kind can be used with proportionally spaced fonts, as it does +not require lining up columns. +.SS Extension: \f[CR]table_captions\f[R] +A caption may optionally be provided with all 4 kinds of tables (as +illustrated in the examples below). +A caption is a paragraph beginning with the string \f[CR]Table:\f[R] (or +\f[CR]table:\f[R] or just \f[CR]:\f[R]), which will be stripped off. +It may appear either before or after the table. +.SS Extension: \f[CR]simple_tables\f[R] +Simple tables look like this: +.IP +.EX + Right Left Center Default +------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 + +Table: Demonstration of simple table syntax. +.EE +.PP +The header and table rows must each fit on one line. +Column alignments are determined by the position of the header text +relative to the dashed line below it: +.IP \[bu] 2 +If the dashed line is flush with the header text on the right side but +extends beyond it on the left, the column is right-aligned. +.IP \[bu] 2 +If the dashed line is flush with the header text on the left side but +extends beyond it on the right, the column is left-aligned. +.IP \[bu] 2 +If the dashed line extends beyond the header text on both sides, the +column is centered. +.IP \[bu] 2 +If the dashed line is flush with the header text on both sides, the +default alignment is used (in most cases, this will be left). +.PP +The table must end with a blank line, or a line of dashes followed by a +blank line. +.PP +The column header row may be omitted, provided a dashed line is used to +end the table. +For example: +.IP +.EX +------- ------ ---------- ------- + 12 12 12 12 + 123 123 123 123 + 1 1 1 1 +------- ------ ---------- ------- +.EE +.PP +When the header row is omitted, column alignments are determined on the +basis of the first line of the table body. +So, in the tables above, the columns would be right, left, center, and +right aligned, respectively. +.SS Extension: \f[CR]multiline_tables\f[R] +Multiline tables allow header and table rows to span multiple lines of +text (but cells that span multiple columns or rows of the table are not +supported). +Here is an example: +.IP +.EX +------------------------------------------------------------- + Centered Default Right Left + Header Aligned Aligned Aligned +----------- ------- --------------- ------------------------- + First row 12.0 Example of a row that + spans multiple lines. + + Second row 5.0 Here\[aq]s another one. Note + the blank line between + rows. +------------------------------------------------------------- + +Table: Here\[aq]s the caption. It, too, may span +multiple lines. +.EE +.PP +These work like simple tables, but with the following differences: +.IP \[bu] 2 +They must begin with a row of dashes, before the header text (unless the +header row is omitted). +.IP \[bu] 2 +They must end with a row of dashes, then a blank line. +.IP \[bu] 2 +The rows must be separated by blank lines. +.PP +In multiline tables, the table parser pays attention to the widths of +the columns, and the writers try to reproduce these relative widths in +the output. +So, if you find that one of the columns is too narrow in the output, try +widening it in the Markdown source. +.PP +The header may be omitted in multiline tables as well as simple tables: +.IP +.EX +----------- ------- --------------- ------------------------- + First row 12.0 Example of a row that + spans multiple lines. + + Second row 5.0 Here\[aq]s another one. Note + the blank line between + rows. +----------- ------- --------------- ------------------------- + +: Here\[aq]s a multiline table without a header. +.EE +.PP +It is possible for a multiline table to have just one row, but the row +should be followed by a blank line (and then the row of dashes that ends +the table), or the table may be interpreted as a simple table. +.SS Extension: \f[CR]grid_tables\f[R] +Grid tables look like this: +.IP +.EX +: Sample grid table. + ++---------------+---------------+--------------------+ +| Fruit | Price | Advantages | ++===============+===============+====================+ +| Bananas | $1.34 | - built-in wrapper | +| | | - bright color | ++---------------+---------------+--------------------+ +| Oranges | $2.10 | - cures scurvy | +| | | - tasty | ++---------------+---------------+--------------------+ +.EE +.PP +The row of \f[CR]=\f[R]s separates the header from the table body, and +can be omitted for a headerless table. +The cells of grid tables may contain arbitrary block elements (multiple +paragraphs, code blocks, lists, etc.). +.PP +Cells can span multiple columns or rows: +.IP +.EX ++---------------------+----------+ +| Property | Earth | ++=============+=======+==========+ +| | min | -89.2 °C | +| Temperature +-------+----------+ +| 1961-1990 | mean | 14 °C | +| +-------+----------+ +| | max | 56.7 °C | ++-------------+-------+----------+ +.EE +.PP +A table header may contain more than one row: +.IP +.EX ++---------------------+-----------------------+ +| Location | Temperature 1961-1990 | +| | in degree Celsius | +| +-------+-------+-------+ +| | min | mean | max | ++=====================+=======+=======+=======+ +| Antarctica | -89.2 | N/A | 19.8 | ++---------------------+-------+-------+-------+ +| Earth | -89.2 | 14 | 56.7 | ++---------------------+-------+-------+-------+ +.EE +.PP +Alignments can be specified as with pipe tables, by putting colons at +the boundaries of the separator line after the header: +.IP +.EX ++---------------+---------------+--------------------+ +| Right | Left | Centered | ++==============:+:==============+:==================:+ +| Bananas | $1.34 | built-in wrapper | ++---------------+---------------+--------------------+ +.EE +.PP +For headerless tables, the colons go on the top line instead: +.IP +.EX ++--------------:+:--------------+:------------------:+ +| Right | Left | Centered | ++---------------+---------------+--------------------+ +.EE +.PP +A table foot can be defined by enclosing it with separator lines that +use \f[CR]=\f[R] instead of \f[CR]-\f[R]: +.IP +.EX + +---------------+---------------+ + | Fruit | Price | + +===============+===============+ + | Bananas | $1.34 | + +---------------+---------------+ + | Oranges | $2.10 | + +===============+===============+ + | Sum | $3.44 | + +===============+===============+ +.EE +.PP +The foot must always be placed at the very bottom of the table. +.PP +Grid tables can be created easily using Emacs\[cq] table-mode +(\f[CR]M-x table-insert\f[R]). +.SS Extension: \f[CR]pipe_tables\f[R] +Pipe tables look like this: +.IP +.EX +| Right | Left | Default | Center | +|------:|:-----|---------|:------:| +| 12 | 12 | 12 | 12 | +| 123 | 123 | 123 | 123 | +| 1 | 1 | 1 | 1 | + + : Demonstration of pipe table syntax. +.EE +.PP +The syntax is identical to PHP Markdown Extra tables. +The beginning and ending pipe characters are optional, but pipes are +required between all columns. +The colons indicate column alignment as shown. +The header cannot be omitted. +To simulate a headerless table, include a header with blank cells. +.PP +Since the pipes indicate column boundaries, columns need not be +vertically aligned, as they are in the above example. +So, this is a perfectly legal (though ugly) pipe table: +.IP +.EX +fruit| price +-----|-----: +apple|2.05 +pear|1.37 +orange|3.09 +.EE +.PP +The cells of pipe tables cannot contain block elements like paragraphs +and lists, and cannot span multiple lines. +If any line of the markdown source is longer than the column width (see +\f[CR]--columns\f[R]), then the table will take up the full text width +and the cell contents will wrap, with the relative cell widths +determined by the number of dashes in the line separating the table +header from the table body. +(For example \f[CR]---|-\f[R] would make the first column 3/4 and the +second column 1/4 of the full text width.) +On the other hand, if no lines are wider than column width, then cell +contents will not be wrapped, and the cells will be sized to their +contents. +.PP +Note: pandoc also recognizes pipe tables of the following form, as can +be produced by Emacs\[cq] orgtbl-mode: +.IP +.EX +| One | Two | +|-----+-------| +| my | table | +| is | nice | +.EE +.PP +The difference is that \f[CR]+\f[R] is used instead of \f[CR]|\f[R]. +Other orgtbl features are not supported. +In particular, to get non-default column alignment, you\[cq]ll need to +add colons as above. +.SS Metadata blocks +.SS Extension: \f[CR]pandoc_title_block\f[R] +If the file begins with a title block +.IP +.EX +% title +% author(s) (separated by semicolons) +% date +.EE +.PP +it will be parsed as bibliographic information, not regular text. +(It will be used, for example, in the title of standalone LaTeX or HTML +output.) +The block may contain just a title, a title and an author, or all three +elements. +If you want to include an author but no title, or a title and a date but +no author, you need a blank line: +.IP +.EX +% +% Author +.EE +.IP +.EX +% My title +% +% June 15, 2006 +.EE +.PP +The title may occupy multiple lines, but continuation lines must begin +with leading space, thus: +.IP +.EX +% My title + on multiple lines +.EE +.PP +If a document has multiple authors, the authors may be put on separate +lines with leading space, or separated by semicolons, or both. +So, all of the following are equivalent: +.IP +.EX +% Author One + Author Two +.EE +.IP +.EX +% Author One; Author Two +.EE +.IP +.EX +% Author One; + Author Two +.EE +.PP +The date must fit on one line. +.PP +All three metadata fields may contain standard inline formatting +(italics, links, footnotes, etc.). +.PP +Title blocks will always be parsed, but they will affect the output only +when the \f[CR]--standalone\f[R] (\f[CR]-s\f[R]) option is chosen. +In HTML output, titles will appear twice: once in the document head +\[en] this is the title that will appear at the top of the window in a +browser \[en] and once at the beginning of the document body. +The title in the document head can have an optional prefix attached +(\f[CR]--title-prefix\f[R] or \f[CR]-T\f[R] option). +The title in the body appears as an H1 element with class +\[lq]title\[rq], so it can be suppressed or reformatted with CSS. +If a title prefix is specified with \f[CR]-T\f[R] and no title block +appears in the document, the title prefix will be used by itself as the +HTML title. +.PP +The man page writer extracts a title, man page section number, and other +header and footer information from the title line. +The title is assumed to be the first word on the title line, which may +optionally end with a (single-digit) section number in parentheses. +(There should be no space between the title and the parentheses.) +Anything after this is assumed to be additional footer and header text. +A single pipe character (\f[CR]|\f[R]) should be used to separate the +footer text from the header text. +Thus, +.IP +.EX +% PANDOC(1) +.EE +.PP +will yield a man page with the title \f[CR]PANDOC\f[R] and section 1. +.IP +.EX +% PANDOC(1) Pandoc User Manuals +.EE +.PP +will also have \[lq]Pandoc User Manuals\[rq] in the footer. +.IP +.EX +% PANDOC(1) Pandoc User Manuals | Version 4.0 +.EE +.PP +will also have \[lq]Version 4.0\[rq] in the header. +.SS Extension: \f[CR]yaml_metadata_block\f[R] +A YAML metadata block is a valid YAML object, delimited by a line of +three hyphens (\f[CR]---\f[R]) at the top and a line of three hyphens +(\f[CR]---\f[R]) or three dots (\f[CR]...\f[R]) at the bottom. +The initial line \f[CR]---\f[R] must not be followed by a blank line. +A YAML metadata block may occur anywhere in the document, but if it is +not at the beginning, it must be preceded by a blank line. +.PP +Note that, because of the way pandoc concatenates input files when +several are provided, you may also keep the metadata in a separate YAML +file and pass it to pandoc as an argument, along with your Markdown +files: +.IP +.EX +pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html +.EE +.PP +Just be sure that the YAML file begins with \f[CR]---\f[R] and ends with +\f[CR]---\f[R] or \f[CR]...\f[R]. +Alternatively, you can use the \f[CR]--metadata-file\f[R] option. +Using that approach however, you cannot reference content (like +footnotes) from the main markdown input document. +.PP +Metadata will be taken from the fields of the YAML object and added to +any existing document metadata. +Metadata can contain lists and objects (nested arbitrarily), but all +string scalars will be interpreted as Markdown. +Fields with names ending in an underscore will be ignored by pandoc. +(They may be given a role by external processors.) +Field names must not be interpretable as YAML numbers or boolean values +(so, for example, \f[CR]yes\f[R], \f[CR]True\f[R], and \f[CR]15\f[R] +cannot be used as field names). +.PP +A document may contain multiple metadata blocks. +If two metadata blocks attempt to set the same field, the value from the +second block will be taken. +.PP +Each metadata block is handled internally as an independent YAML +document. +This means, for example, that any YAML anchors defined in a block cannot +be referenced in another block. +.PP +When pandoc is used with \f[CR]-t markdown\f[R] to create a Markdown +document, a YAML metadata block will be produced only if the +\f[CR]-s/--standalone\f[R] option is used. +All of the metadata will appear in a single block at the beginning of +the document. +.PP +Note that YAML escaping rules must be followed. +Thus, for example, if a title contains a colon, it must be quoted, and +if it contains a backslash escape, then it must be ensured that it is +not treated as a YAML escape sequence. +The pipe character (\f[CR]|\f[R]) can be used to begin an indented block +that will be interpreted literally, without need for escaping. +This form is necessary when the field contains blank lines or +block-level formatting: +.IP +.EX +--- +title: \[aq]This is the title: it contains a colon\[aq] +author: +- Author One +- Author Two +keywords: [nothing, nothingness] +abstract: | + This is the abstract. + + It consists of two paragraphs. +\&... +.EE +.PP +The literal block after the \f[CR]|\f[R] must be indented relative to +the line containing the \f[CR]|\f[R]. +If it is not, the YAML will be invalid and pandoc will not interpret it +as metadata. +For an overview of the complex rules governing YAML, see the Wikipedia +entry on YAML syntax. +.PP +Template variables will be set automatically from the metadata. +Thus, for example, in writing HTML, the variable \f[CR]abstract\f[R] +will be set to the HTML equivalent of the Markdown in the +\f[CR]abstract\f[R] field: +.IP +.EX +

This is the abstract.

+

It consists of two paragraphs.

+.EE +.PP +Variables can contain arbitrary YAML structures, but the template must +match this structure. +The \f[CR]author\f[R] variable in the default templates expects a simple +list or string, but can be changed to support more complicated +structures. +The following combination, for example, would add an affiliation to the +author if one is given: +.IP +.EX +--- +title: The document title +author: +- name: Author One + affiliation: University of Somewhere +- name: Author Two + affiliation: University of Nowhere +\&... +.EE +.PP +To use the structured authors in the example above, you would need a +custom template: +.IP +.EX +$for(author)$ +$if(author.name)$ +$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$ +$else$ +$author$ +$endif$ +$endfor$ +.EE +.PP +Raw content to include in the document\[cq]s header may be specified +using \f[CR]header-includes\f[R]; however, it is important to mark up +this content as raw code for a particular output format, using the +\f[CR]raw_attribute\f[R] extension, or it will be interpreted as +markdown. +For example: +.IP +.EX +header-includes: +- | + \[ga]\[ga]\[ga]{=latex} + \[rs]let\[rs]oldsection\[rs]section + \[rs]renewcommand{\[rs]section}[1]{\[rs]clearpage\[rs]oldsection{#1}} + \[ga]\[ga]\[ga] +.EE +.PP +Note: the \f[CR]yaml_metadata_block\f[R] extension works with +\f[CR]commonmark\f[R] as well as \f[CR]markdown\f[R] (and it is enabled +by default in \f[CR]gfm\f[R] and \f[CR]commonmark_x\f[R]). +However, in these formats the following restrictions apply: +.IP \[bu] 2 +The YAML metadata block must occur at the beginning of the document (and +there can be only one). +If multiple files are given as arguments to pandoc, only the first can +be a YAML metadata block. +.IP \[bu] 2 +The leaf nodes of the YAML structure are parsed in isolation from each +other and from the rest of the document. +So, for example, you can\[cq]t use a reference link in these contexts if +the link definition is somewhere else in the document. +.SS Backslash escapes +.SS Extension: \f[CR]all_symbols_escapable\f[R] +Except inside a code block or inline code, any punctuation or space +character preceded by a backslash will be treated literally, even if it +would normally indicate formatting. +Thus, for example, if one writes +.IP +.EX +*\[rs]*hello\[rs]** +.EE +.PP +one will get +.IP +.EX +*hello* +.EE +.PP +instead of +.IP +.EX +hello +.EE +.PP +This rule is easier to remember than original Markdown\[cq]s rule, which +allows only the following characters to be backslash-escaped: +.IP +.EX +\[rs]\[ga]*_{}[]()>#+-.! +.EE +.PP +(However, if the \f[CR]markdown_strict\f[R] format is used, the original +Markdown rule will be used.) +.PP +A backslash-escaped space is parsed as a nonbreaking space. +In TeX output, it will appear as \f[CR]\[ti]\f[R]. +In HTML and XML output, it will appear as a literal unicode nonbreaking +space character (note that it will thus actually look +\[lq]invisible\[rq] in the generated HTML source; you can still use the +\f[CR]--ascii\f[R] command-line option to make it appear as an explicit +entity). +.PP +A backslash-escaped newline (i.e.\ a backslash occurring at the end of a +line) is parsed as a hard line break. +It will appear in TeX output as \f[CR]\[rs]\[rs]\f[R] and in HTML as +\f[CR]
\f[R]. +This is a nice alternative to Markdown\[cq]s \[lq]invisible\[rq] way of +indicating hard line breaks using two trailing spaces on a line. +.PP +Backslash escapes do not work in verbatim contexts. +.SS Inline formatting +.SS Emphasis +To \f[I]emphasize\f[R] some text, surround it with \f[CR]*\f[R]s or +\f[CR]_\f[R], like this: +.IP +.EX +This text is _emphasized with underscores_, and this +is *emphasized with asterisks*. +.EE +.PP +Double \f[CR]*\f[R] or \f[CR]_\f[R] produces \f[B]strong emphasis\f[R]: +.IP +.EX +This is **strong emphasis** and __with underscores__. +.EE +.PP +A \f[CR]*\f[R] or \f[CR]_\f[R] character surrounded by spaces, or +backslash-escaped, will not trigger emphasis: +.IP +.EX +This is * not emphasized *, and \[rs]*neither is this\[rs]*. +.EE +.SS Extension: \f[CR]intraword_underscores\f[R] +Because \f[CR]_\f[R] is sometimes used inside words and identifiers, +pandoc does not interpret a \f[CR]_\f[R] surrounded by alphanumeric +characters as an emphasis marker. +If you want to emphasize just part of a word, use \f[CR]*\f[R]: +.IP +.EX +feas*ible*, not feas*able*. +.EE +.SS Strikeout +.SS Extension: \f[CR]strikeout\f[R] +To strike out a section of text with a horizontal line, begin and end it +with \f[CR]\[ti]\[ti]\f[R]. +Thus, for example, +.IP +.EX +This \[ti]\[ti]is deleted text.\[ti]\[ti] +.EE +.SS Superscripts and subscripts +.SS Extension: \f[CR]superscript\f[R], \f[CR]subscript\f[R] +Superscripts may be written by surrounding the superscripted text by +\f[CR]\[ha]\f[R] characters; subscripts may be written by surrounding +the subscripted text by \f[CR]\[ti]\f[R] characters. +Thus, for example, +.IP +.EX +H\[ti]2\[ti]O is a liquid. 2\[ha]10\[ha] is 1024. +.EE +.PP +The text between \f[CR]\[ha]...\[ha]\f[R] or \f[CR]\[ti]...\[ti]\f[R] +may not contain spaces or newlines. +If the superscripted or subscripted text contains spaces, these spaces +must be escaped with backslashes. +(This is to prevent accidental superscripting and subscripting through +the ordinary use of \f[CR]\[ti]\f[R] and \f[CR]\[ha]\f[R], and also bad +interactions with footnotes.) +Thus, if you want the letter P with `a cat' in subscripts, use +\f[CR]P\[ti]a\[rs] cat\[ti]\f[R], not \f[CR]P\[ti]a cat\[ti]\f[R]. +.SS Verbatim +To make a short span of text verbatim, put it inside backticks: +.IP +.EX +What is the difference between \[ga]>>=\[ga] and \[ga]>>\[ga]? +.EE +.PP +If the verbatim text includes a backtick, use double backticks: +.IP +.EX +Here is a literal backtick \[ga]\[ga] \[ga] \[ga]\[ga]. +.EE +.PP +(The spaces after the opening backticks and before the closing backticks +will be ignored.) +.PP +The general rule is that a verbatim span starts with a string of +consecutive backticks (optionally followed by a space) and ends with a +string of the same number of backticks (optionally preceded by a space). +.PP +Note that backslash-escapes (and other Markdown constructs) do not work +in verbatim contexts: +.IP +.EX +This is a backslash followed by an asterisk: \[ga]\[rs]*\[ga]. +.EE +.SS Extension: \f[CR]inline_code_attributes\f[R] +Attributes can be attached to verbatim text, just as with fenced code +blocks: +.IP +.EX +\[ga]<$>\[ga]{.haskell} +.EE +.SS Underline +To underline text, use the \f[CR]underline\f[R] class: +.IP +.EX +[Underline]{.underline} +.EE +.PP +Or, without the \f[CR]bracketed_spans\f[R] extension (but with +\f[CR]native_spans\f[R]): +.IP +.EX +Underline +.EE +.PP +This will work in all output formats that support underline. +.SS Small caps +To write small caps, use the \f[CR]smallcaps\f[R] class: +.IP +.EX +[Small caps]{.smallcaps} +.EE +.PP +Or, without the \f[CR]bracketed_spans\f[R] extension: +.IP +.EX +Small caps +.EE +.PP +For compatibility with other Markdown flavors, CSS is also supported: +.IP +.EX +Small caps +.EE +.PP +This will work in all output formats that support small caps. +.SS Highlighting +To highlight text, use the \f[CR]mark\f[R] class: +.IP +.EX +[Mark]{.mark} +.EE +.PP +Or, without the \f[CR]bracketed_spans\f[R] extension (but with +\f[CR]native_spans\f[R]): +.IP +.EX +Mark +.EE +.PP +This will work in all output formats that support highlighting. +.SS Math +.SS Extension: \f[CR]tex_math_dollars\f[R] +Anything between two \f[CR]$\f[R] characters will be treated as TeX +math. +The opening \f[CR]$\f[R] must have a non-space character immediately to +its right, while the closing \f[CR]$\f[R] must have a non-space +character immediately to its left, and must not be followed immediately +by a digit. +Thus, \f[CR]$20,000 and $30,000\f[R] won\[cq]t parse as math. +If for some reason you need to enclose text in literal \f[CR]$\f[R] +characters, backslash-escape them and they won\[cq]t be treated as math +delimiters. +.PP +For display math, use \f[CR]$$\f[R] delimiters. +(In this case, the delimiters may be separated from the formula by +whitespace. +However, there can be no blank lines between the opening and closing +\f[CR]$$\f[R] delimiters.) +.PP +TeX math will be printed in all output formats. +How it is rendered depends on the output format: +.TP +LaTeX +It will appear verbatim surrounded by \f[CR]\[rs](...\[rs])\f[R] (for +inline math) or \f[CR]\[rs][...\[rs]]\f[R] (for display math). +.TP +Markdown, Emacs Org mode, ConTeXt, ZimWiki +It will appear verbatim surrounded by \f[CR]$...$\f[R] (for inline math) +or \f[CR]$$...$$\f[R] (for display math). +.TP +XWiki +It will appear verbatim surrounded by +\f[CR]{{formula}}..{{/formula}}\f[R]. +.TP +reStructuredText +It will be rendered using an interpreted text role \f[CR]:math:\f[R]. +.TP +AsciiDoc +For AsciiDoc output math will appear verbatim surrounded by +\f[CR]latexmath:[...]\f[R]. +For \f[CR]asciidoc_legacy\f[R] the bracketed material will also include +inline or display math delimiters. +.TP +Texinfo +It will be rendered inside a \f[CR]\[at]math\f[R] command. +.TP +roff man, Jira markup +It will be rendered verbatim without \f[CR]$\f[R]\[cq]s. +.TP +MediaWiki, DokuWiki +It will be rendered inside \f[CR]\f[R] tags. +.TP +Textile +It will be rendered inside \f[CR]\f[R] tags. +.TP +RTF, OpenDocument +It will be rendered, if possible, using Unicode characters, and will +otherwise appear verbatim. +.TP +ODT +It will be rendered, if possible, using MathML. +.TP +DocBook +If the \f[CR]--mathml\f[R] flag is used, it will be rendered using +MathML in an \f[CR]inlineequation\f[R] or \f[CR]informalequation\f[R] +tag. +Otherwise it will be rendered, if possible, using Unicode characters. +.TP +Docx and PowerPoint +It will be rendered using OMML math markup. +.TP +FictionBook2 +If the \f[CR]--webtex\f[R] option is used, formulas are rendered as +images using CodeCogs or other compatible web service, downloaded and +embedded in the e-book. +Otherwise, they will appear verbatim. +.TP +HTML, Slidy, DZSlides, S5, EPUB +The way math is rendered in HTML will depend on the command-line options +selected. +Therefore see Math rendering in HTML above. +.SS Raw HTML +.SS Extension: \f[CR]raw_html\f[R] +Markdown allows you to insert raw HTML (or DocBook) anywhere in a +document (except verbatim contexts, where \f[CR]<\f[R], \f[CR]>\f[R], +and \f[CR]&\f[R] are interpreted literally). +(Technically this is not an extension, since standard Markdown allows +it, but it has been made an extension so that it can be disabled if +desired.) +.PP +The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, +DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile +output, and suppressed in other formats. +.PP +For a more explicit way of including raw HTML in a Markdown document, +see the \f[CR]raw_attribute\f[R] extension. +.PP +In the CommonMark format, if \f[CR]raw_html\f[R] is enabled, +superscripts, subscripts, strikeouts and small capitals will be +represented as HTML. +Otherwise, plain-text fallbacks will be used. +Note that even if \f[CR]raw_html\f[R] is disabled, tables will be +rendered with HTML syntax if they cannot use pipe syntax. +.SS Extension: \f[CR]markdown_in_html_blocks\f[R] +Original Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of +HTML between balanced tags that are separated from the surrounding text +with blank lines, and start and end at the left margin. +Within these blocks, everything is interpreted as HTML, not Markdown; so +(for example), \f[CR]*\f[R] does not signify emphasis. +.PP +Pandoc behaves this way when the \f[CR]markdown_strict\f[R] format is +used; but by default, pandoc interprets material between HTML block tags +as Markdown. +Thus, for example, pandoc will turn +.IP +.EX + + + + + +
*one*[a link](https://google.com)
+.EE +.PP +into +.IP +.EX + + + + + +
onea link
+.EE +.PP +whereas \f[CR]Markdown.pl\f[R] will preserve it as is. +.PP +There is one exception to this rule: text between \f[CR] +HTML +\[dq]\[dq]\[dq]) +\[ga]\[ga]\[ga] + +## Image + +This image ![image](myimage.png) will be +included as a cell attachment. +.EE +.PP +If you want to add cell attributes, group cells differently, or add +output to code cells, then you need to include divs to indicate the +structure. +You can use either fenced divs or native divs for this. +Here is an example: +.IP +.EX +:::::: {.cell .markdown} +# Lorem + +**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus +bibendum felis dictum sodales. +:::::: + +:::::: {.cell .code execution_count=1} +\[ga]\[ga]\[ga] {.python} +print(\[dq]hello\[dq]) +\[ga]\[ga]\[ga] + +::: {.output .stream .stdout} +\[ga]\[ga]\[ga] +hello +\[ga]\[ga]\[ga] +::: +:::::: + +:::::: {.cell .code execution_count=2} +\[ga]\[ga]\[ga] {.python} +from IPython.display import HTML +HTML(\[dq]\[dq]\[dq] + +HTML +\[dq]\[dq]\[dq]) +\[ga]\[ga]\[ga] + +::: {.output .execute_result execution_count=2} +\[ga]\[ga]\[ga]{=html} + +HTML +hello +\[ga]\[ga]\[ga] +::: +:::::: +.EE +.PP +If you include raw HTML or TeX in an output cell, use the raw attribute, +as shown in the last cell of the example above. +Although pandoc can process \[lq]bare\[rq] raw HTML and TeX, the result +is often interspersed raw elements and normal textual elements, and in +an output cell pandoc expects a single, connected raw block. +To avoid using raw HTML or TeX except when marked explicitly using raw +attributes, we recommend specifying the extensions +\f[CR]-raw_html-raw_tex+raw_attribute\f[R] when translating between +Markdown and ipynb notebooks. +.PP +Note that options and extensions that affect reading and writing of +Markdown will also affect Markdown cells in ipynb notebooks. +For example, \f[CR]--wrap=preserve\f[R] will preserve soft line breaks +in Markdown cells; \f[CR]--markdown-headings=setext\f[R] will cause +Setext-style headings to be used; and \f[CR]--preserve-tabs\f[R] will +prevent tabs from being turned to spaces. +.SH SYNTAX HIGHLIGHTING +Pandoc will automatically highlight syntax in fenced code blocks that +are marked with a language name. +The Haskell library skylighting is used for highlighting. +Currently highlighting is supported only for HTML, EPUB, Docx, Ms, and +LaTeX/PDF output. +To see a list of language names that pandoc will recognize, type +\f[CR]pandoc --list-highlight-languages\f[R]. +.PP +The color scheme can be selected using the \f[CR]--highlight-style\f[R] +option. +The default color scheme is \f[CR]pygments\f[R], which imitates the +default color scheme used by the Python library pygments (though +pygments is not actually used to do the highlighting). +To see a list of highlight styles, type +\f[CR]pandoc --list-highlight-styles\f[R]. +.PP +If you are not satisfied with the predefined styles, you can use +\f[CR]--print-highlight-style\f[R] to generate a JSON \f[CR].theme\f[R] +file which can be modified and used as the argument to +\f[CR]--highlight-style\f[R]. +To get a JSON version of the \f[CR]pygments\f[R] style, for example: +.IP +.EX +pandoc --print-highlight-style pygments > my.theme +.EE +.PP +Then edit \f[CR]my.theme\f[R] and use it like this: +.IP +.EX +pandoc --highlight-style my.theme +.EE +.PP +If you are not satisfied with the built-in highlighting, or you want to +highlight a language that isn\[cq]t supported, you can use the +\f[CR]--syntax-definition\f[R] option to load a KDE-style XML syntax +definition file. +Before writing your own, have a look at KDE\[cq]s repository of syntax +definitions. +.PP +To disable highlighting, use the \f[CR]--no-highlight\f[R] option. +.SH CUSTOM STYLES +Custom styles can be used in the docx and ICML formats. +.SS Output +By default, pandoc\[cq]s docx and ICML output applies a predefined set +of styles for blocks such as paragraphs and block quotes, and uses +largely default formatting (italics, bold) for inlines. +This will work for most purposes, especially alongside a +\f[CR]reference.docx\f[R] file. +However, if you need to apply your own styles to blocks, or match a +preexisting set of styles, pandoc allows you to define custom styles for +blocks and text using \f[CR]div\f[R]s and \f[CR]span\f[R]s, +respectively. +.PP +If you define a \f[CR]div\f[R] or \f[CR]span\f[R] with the attribute +\f[CR]custom-style\f[R], pandoc will apply your specified style to the +contained elements (with the exception of elements whose function +depends on a style, like headings, code blocks, block quotes, or links). +So, for example, using the \f[CR]bracketed_spans\f[R] syntax, +.IP +.EX +[Get out]{custom-style=\[dq]Emphatically\[dq]}, he said. +.EE +.PP +would produce a docx file with \[lq]Get out\[rq] styled with character +style \f[CR]Emphatically\f[R]. +Similarly, using the \f[CR]fenced_divs\f[R] syntax, +.IP +.EX +Dickinson starts the poem simply: + +::: {custom-style=\[dq]Poetry\[dq]} +| A Bird came down the Walk--- +| He did not know I saw--- +::: +.EE +.PP +would style the two contained lines with the \f[CR]Poetry\f[R] paragraph +style. +.PP +For docx output, styles will be defined in the output file as inheriting +from normal text, if the styles are not yet in your reference.docx. +If they are already defined, pandoc will not alter the definition. +.PP +This feature allows for greatest customization in conjunction with +pandoc filters. +If you want all paragraphs after block quotes to be indented, you can +write a filter to apply the styles necessary. +If you want all italics to be transformed to the \f[CR]Emphasis\f[R] +character style (perhaps to change their color), you can write a filter +which will transform all italicized inlines to inlines within an +\f[CR]Emphasis\f[R] custom-style \f[CR]span\f[R]. +.PP +For docx output, you don\[cq]t need to enable any extensions for custom +styles to work. +.SS Input +The docx reader, by default, only reads those styles that it can convert +into pandoc elements, either by direct conversion or interpreting the +derivation of the input document\[cq]s styles. +.PP +By enabling the \f[CR]styles\f[R] extension in the docx reader +(\f[CR]-f docx+styles\f[R]), you can produce output that maintains the +styles of the input document, using the \f[CR]custom-style\f[R] class. +Paragraph styles are interpreted as divs, while character styles are +interpreted as spans. +.PP +For example, using the \f[CR]custom-style-reference.docx\f[R] file in +the test directory, we have the following different outputs: +.PP +Without the \f[CR]+styles\f[R] extension: +.IP +.EX +$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown +This is some text. + +This is text with an *emphasized* text style. And this is text with a +**strengthened** text style. + +> Here is a styled paragraph that inherits from Block Text. +.EE +.PP +And with the extension: +.IP +.EX +$ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown + +::: {custom-style=\[dq]First Paragraph\[dq]} +This is some text. +::: + +::: {custom-style=\[dq]Body Text\[dq]} +This is text with an [emphasized]{custom-style=\[dq]Emphatic\[dq]} text style. +And this is text with a [strengthened]{custom-style=\[dq]Strengthened\[dq]} +text style. +::: + +::: {custom-style=\[dq]My Block Style\[dq]} +> Here is a styled paragraph that inherits from Block Text. +::: +.EE +.PP +With these custom styles, you can use your input document as a +reference-doc while creating docx output (see below), and maintain the +same styles in your input and output files. +.SH CUSTOM READERS AND WRITERS +Pandoc can be extended with custom readers and writers written in Lua. +(Pandoc includes a Lua interpreter, so Lua need not be installed +separately.) +.PP +To use a custom reader or writer, simply specify the path to the Lua +script in place of the input or output format. +For example: +.IP +.EX +pandoc -t data/sample.lua +pandoc -f my_custom_markup_language.lua -t latex -s +.EE +.PP +If the script is not found relative to the working directory, it will be +sought in the \f[CR]custom\f[R] subdirectory of the user data directory +(see \f[CR]--data-dir\f[R]). +.PP +A custom reader is a Lua script that defines one function, Reader, which +takes a string as input and returns a Pandoc AST. +See the Lua filters documentation for documentation of the functions +that are available for creating pandoc AST elements. +For parsing, the lpeg parsing library is available by default. +To see a sample custom reader: +.IP +.EX +pandoc --print-default-data-file creole.lua +.EE +.PP +If you want your custom reader to have access to reader options +(e.g.\ the tab stop setting), you give your Reader function a second +\f[CR]options\f[R] parameter. +.PP +A custom writer is a Lua script that defines a function that specifies +how to render each element in a Pandoc AST. +See the djot-writer.lua for a full-featured example. +.PP +Note that custom writers have no default template. +If you want to use \f[CR]--standalone\f[R] with a custom writer, you +will need to specify a template manually using \f[CR]--template\f[R] or +add a new default template with the name +\f[CR]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[CR]templates\f[R] +subdirectory of your user data directory (see Templates). +.SH REPRODUCIBLE BUILDS +Some of the document formats pandoc targets (such as EPUB, docx, and +ODT) include build timestamps in the generated document. +That means that the files generated on successive builds will differ, +even if the source does not. +To avoid this, set the \f[CR]SOURCE_DATE_EPOCH\f[R] environment +variable, and the timestamp will be taken from it instead of the current +time. +\f[CR]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp +(specifying the number of seconds since midnight UTC January 1, 1970). +.PP +Some document formats also include a unique identifier. +For EPUB, this can be set explicitly by setting the +\f[CR]identifier\f[R] metadata field (see EPUB Metadata, above). +.SH ACCESSIBLE PDFS AND PDF ARCHIVING STANDARDS +PDF is a flexible format, and using PDF in certain contexts requires +additional conventions. +For example, PDFs are not accessible by default; they define how +characters are placed on a page but do not contain semantic information +on the content. +However, it is possible to generate accessible PDFs, which use tagging +to add semantic information to the document. +.PP +Pandoc defaults to LaTeX to generate PDF. +Tagging support in LaTeX is in development and not readily available, so +PDFs generated in this way will always be untagged and not accessible. +This means that alternative engines must be used to generate accessible +PDFs. +.PP +The PDF standards PDF/A and PDF/UA define further restrictions intended +to optimize PDFs for archiving and accessibility. +Tagging is commonly used in combination with these standards to ensure +best results. +.PP +Note, however, that standard compliance depends on many things, +including the colorspace of embedded images. +Pandoc cannot check this, and external programs must be used to ensure +that generated PDFs are in compliance. +.SS ConTeXt +ConTeXt always produces tagged PDFs, but the quality depends on the +input. +The default ConTeXt markup generated by pandoc is optimized for +readability and reuse, not tagging. +Enable the \f[CR]tagging\f[R] format extension to force markup that is +optimized for tagging. +This can be combined with the \f[CR]pdfa\f[R] variable to generate +standard-compliant PDFs. +E.g.: +.IP +.EX +pandoc --to=context+tagging -V pdfa=3a +.EE +.PP +A recent \f[CR]context\f[R] version should be used, as older versions +contained a bug that lead to invalid PDF metadata. +.SS WeasyPrint +The HTML-based engine WeasyPrint includes experimental support for PDF/A +and PDF/UA since version 57. +Tagged PDFs can created with +.IP +.EX +pandoc --pdf-engine=weasyprint \[rs] + --pdf-engine-opt=--pdf-variant=pdf/ua-1 ... +.EE +.PP +The feature is experimental and standard compliance should not be +assumed. +.SS Prince XML +The non-free HTML-to-PDf converter \f[CR]prince\f[R] has extensive +support for various PDF standards as well as tagging. +E.g.: +.IP +.EX +pandoc --pdf-engine=prince \[rs] + --pdf-engine-opt=--tagged-pdf ... +.EE +.PP +See the prince documentation for more info. +.SS Word Processors +Word processors like LibreOffice and MS Word can also be used to +generate standardized and tagged PDF output. +Pandoc does not support direct conversions via these tools. +However, pandoc can convert a document to a \f[CR]docx\f[R] or +\f[CR]odt\f[R] file, which can then be opened and converted to PDF with +the respective word processor. +See the documentation for Word and LibreOffice. +.SH RUNNING PANDOC AS A WEB SERVER +If you rename (or symlink) the pandoc executable to +\f[CR]pandoc-server\f[R], or if you call pandoc with \f[CR]server\f[R] +as the first argument, it will start up a web server with a JSON API. +This server exposes most of the conversion functionality of pandoc. +For full documentation, see the pandoc-server man page. +.PP +If you rename (or symlink) the pandoc executable to +\f[CR]pandoc-server.cgi\f[R], it will function as a CGI program exposing +the same API as \f[CR]pandoc-server\f[R]. +.PP +\f[CR]pandoc-server\f[R] is designed to be maximally secure; it uses +Haskell\[cq]s type system to provide strong guarantees that no I/O will +be performed on the server during pandoc conversions. +.SH RUNNING PANDOC AS A LUA INTERPRETER +Calling the pandoc executable under the name \f[CR]pandoc-lua\f[R] or +with \f[CR]lua\f[R] as the first argument will make it function as a +standalone Lua interpreter. +The behavior is mostly identical to that of the standalone +\f[CR]lua\f[R] executable, version 5.4. +However, there is no REPL yet, and the \f[CR]-i\f[R] option has no +effect. +For full documentation, see the pandoc-lua man page. +.SH A NOTE ON SECURITY +.IP "1." 3 +Although pandoc itself will not create or modify any files other than +those you explicitly ask it create (with the exception of temporary +files used in producing PDFs), a filter or custom writer could in +principle do anything on your file system. +Please audit filters and custom writers very carefully before using +them. +.IP "2." 3 +Several input formats (including HTML, Org, and RST) support +\f[CR]include\f[R] directives that allow the contents of a file to be +included in the output. +An untrusted attacker could use these to view the contents of files on +the file system. +(Using the \f[CR]--sandbox\f[R] option can protect against this threat.) +.IP "3." 3 +Several output formats (including RTF, FB2, HTML with +\f[CR]--self-contained\f[R], EPUB, Docx, and ODT) will embed encoded or +raw images into the output file. +An untrusted attacker could exploit this to view the contents of +non-image files on the file system. +(Using the \f[CR]--sandbox\f[R] option can protect against this threat, +but will also prevent including images in these formats.) +.IP "4." 3 +If your application uses pandoc as a Haskell library (rather than +shelling out to the executable), it is possible to use it in a mode that +fully isolates pandoc from your file system, by running the pandoc +operations in the \f[CR]PandocPure\f[R] monad. +See the document Using the pandoc API for more details. +(This corresponds to the use of the \f[CR]--sandbox\f[R] option on the +command line.) +.IP "5." 3 +Pandoc\[cq]s parsers can exhibit pathological performance on some corner +cases. +It is wise to put any pandoc operations under a timeout, to avoid DOS +attacks that exploit these issues. +If you are using the pandoc executable, you can add the command line +options \f[CR]+RTS -M512M -RTS\f[R] (for example) to limit the heap size +to 512MB. +Note that the \f[CR]commonmark\f[R] parser (including +\f[CR]commonmark_x\f[R] and \f[CR]gfm\f[R]) is much less vulnerable to +pathological performance than the \f[CR]markdown\f[R] parser, so it is a +better choice when processing untrusted input. +.IP "6." 3 +The HTML generated by pandoc is not guaranteed to be safe. +If \f[CR]raw_html\f[R] is enabled for the Markdown input, users can +inject arbitrary HTML. +Even if \f[CR]raw_html\f[R] is disabled, users can include dangerous +content in URLs and attributes. +To be safe, you should run all HTML generated from untrusted user input +through an HTML sanitizer. +.SH AUTHORS +Copyright 2006\[en]2022 John MacFarlane (jgm\[at]berkeley.edu). +Released under the GPL, version 2 or greater. +This software carries no warranty of any kind. +(See COPYRIGHT for full copyright and warranty notices.) +For a full list of contributors, see the file AUTHORS.md in the pandoc +source code. +.PP +The Pandoc source code may be downloaded +from or +. Further +documentation is available at . diff --git a/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: 0.1.1.1 +version: 3.1.10 build-type: Simple license: GPL-2.0-or-later license-file: COPYING.md @@ -11,13 +11,14 @@ stability: alpha homepage: https://pandoc.org category: Text -tested-with: GHC == 8.6.5, GHC == 8.8.4, GHC == 8.10.7, GHC == 9.0.2, - GHC == 9.2.5, GHC == 9.4.4 synopsis: Conversion between documentation formats description: Pandoc-cli provides a command-line executable that uses the pandoc library to convert between markup formats. -- data-files: --- extra-source-files: +extra-source-files: + man/pandoc.1 + man/pandoc-lua.1 + man/pandoc-server.1 source-repository head type: git location: git://github.com/jgm/pandoc.git @@ -67,7 +68,9 @@ hs-source-dirs: src main-is: pandoc.hs buildable: True - build-depends: pandoc >= 3.0, + -- Note: we always link to an exact version of pandoc, with the + -- same version as this package: + build-depends: pandoc == 3.1.10, text other-modules: PandocCLI.Lua , PandocCLI.Server @@ -86,7 +89,7 @@ if flag(lua) build-depends: hslua-cli >= 1.4.1 && < 1.5, - pandoc-lua-engine >= 0.2 && < 0.3, + pandoc-lua-engine >= 0.2.1 && < 0.3, temporary >= 1.1 && < 1.4 hs-source-dirs: lua else