From ee698671224ecc123d76a47c2c7fa4aabd34cb68 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Tue, 21 Jul 2026 23:20:21 +0200 Subject: [PATCH] Update manual date and regenerate man pages. --- MANUAL.txt | 2 +- pandoc-cli/man/pandoc-lua.1 | 4 +- pandoc-cli/man/pandoc-server.1 | 4 +- pandoc-cli/man/pandoc.1 | 211 ++++++++++++++++++++++++--------- 4 files changed, 159 insertions(+), 62 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index f393c3a11..322ef2305 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -1,7 +1,7 @@ --- title: Pandoc User's Guide author: John MacFarlane -date: 2026-06-03 +date: 2026-07-21 --- # Synopsis diff --git a/pandoc-cli/man/pandoc-lua.1 b/pandoc-cli/man/pandoc-lua.1 index 09db4414d..c97c8ff31 100644 --- a/pandoc-cli/man/pandoc-lua.1 +++ b/pandoc-cli/man/pandoc-lua.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.10 +.\" Automatically generated by Pandoc 3.10.1 .\" -.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.10" "Pandoc User\[cq]s Guide" +.TH "pandoc-lua" "1" "September 22, 2022" "pandoc 3.10.1" "Pandoc User\[cq]s Guide" .SH NAME pandoc\-lua \- Lua interface to pandoc API .SH SYNOPSIS diff --git a/pandoc-cli/man/pandoc-server.1 b/pandoc-cli/man/pandoc-server.1 index 267b118ba..e23f02b88 100644 --- a/pandoc-cli/man/pandoc-server.1 +++ b/pandoc-cli/man/pandoc-server.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.10 +.\" Automatically generated by Pandoc 3.10.1 .\" -.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.10" "Pandoc User\[cq]s Guide" +.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.10.1" "Pandoc User\[cq]s Guide" .SH NAME pandoc\-server \- web server exposing pandoc API .SH SYNOPSIS diff --git a/pandoc-cli/man/pandoc.1 b/pandoc-cli/man/pandoc.1 index e025b91cd..48b653fcf 100644 --- a/pandoc-cli/man/pandoc.1 +++ b/pandoc-cli/man/pandoc.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.10 +.\" Automatically generated by Pandoc 3.10.1 .\" -.TH "pandoc" "1" "2026\-06\-03" "pandoc 3.10" "Pandoc User\[cq]s Guide" +.TH "pandoc" "1" "2026\-07\-21" "pandoc 3.10.1" "Pandoc User\[cq]s Guide" .SH NAME pandoc - general markup converter .SH SYNOPSIS @@ -152,12 +152,13 @@ included with all recent versions of TeX Live): \f[CR]amsfonts\f[R], \f[CR]amsmath\f[R], \f[CR]lm\f[R], \f[CR]unicode\-math\f[R], \f[CR]iftex\f[R], \f[CR]listings\f[R] (if the \f[CR]\-\-listings\f[R] option is used), \f[CR]fancyvrb\f[R], \f[CR]longtable\f[R], -\f[CR]booktabs\f[R], \f[CR]multirow\f[R] (if the document contains a -table with cells that cross multiple rows), \f[CR]graphicx\f[R] (if the -document contains images), \f[CR]bookmark\f[R], \f[CR]xcolor\f[R], -\f[CR]soul\f[R], \f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] -variable set), \f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and -\f[CR]babel\f[R] (with \f[CR]lang\f[R]). +\f[CR]caption\f[R], \f[CR]booktabs\f[R], \f[CR]multirow\f[R] (if the +document contains a table with cells that cross multiple rows), +\f[CR]graphicx\f[R] (if the document contains images), +\f[CR]bookmark\f[R], \f[CR]xcolor\f[R], \f[CR]soul\f[R], +\f[CR]geometry\f[R] (with the \f[CR]geometry\f[R] variable set), +\f[CR]setspace\f[R] (with \f[CR]linestretch\f[R]), and \f[CR]babel\f[R] +(with \f[CR]lang\f[R]). If \f[CR]CJKmainfont\f[R] is set, \f[CR]xeCJK\f[R] is needed if \f[CR]xelatex\f[R] is used, else \f[CR]luatexja\f[R] is needed if \f[CR]lualatex\f[R] is used. @@ -446,6 +447,8 @@ markup) .IP \(bu 2 \f[CR]textile\f[R] (Textile) .IP \(bu 2 +\f[CR]t2t\f[R] (txt2tags) +.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) @@ -522,8 +525,8 @@ 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 will be added if \f[I]FILE\f[R] lacs an -extension. +If \f[I]FILE\f[R] lacks an extension, pandoc will also try adding the +\f[CR].yaml\f[R] extension if \f[I]FILE\f[R] is not found. 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. @@ -952,6 +955,11 @@ default) \f[CR]groff\f[R] as a \f[CR]\-\-pdf\-engine\f[R], the table of contents will appear at the end of the document. If you would prefer it to be at the beginning of the document, before the title, you can use \f[CR]\-\-pdf\-engine=pdfroff\f[R]. +.PP +Because the entries in a table of contents need heading identifiers to +link to, this option forces the \f[CR]auto_identifiers\f[R] extension on +for the input format, even when it is off by default (as it is for +\f[CR]typst\f[R]). .RE .TP \f[CR]\-\-toc\-depth=\f[R]\f[I]NUMBER\f[R] @@ -3497,6 +3505,10 @@ 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 for RTF +.TP +\f[CR]fontsize\f[R] +font size for body text, e.g.\ \f[CR]12pt\f[R] or \f[CR]12.5pt\f[R]. .SS Variables set automatically Pandoc sets these variables automatically in response to options or document contents; users can also modify them. @@ -3643,7 +3655,8 @@ 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], \f[CR]man\f[R] +\f[CR]mediawiki\f[R], \f[CR]textile\f[R], \f[CR]man\f[R], +\f[CR]typst\f[R] .TP output formats \f[CR]markdown\f[R], \f[CR]muse\f[R] @@ -3861,13 +3874,15 @@ output formats \f[CR]docx\f[R], \f[CR]odt\f[R], \f[CR]opendocument\f[R], \f[CR]html\f[R], \f[CR]latex\f[R] .SS Extension: \f[CR]native_numbering\f[R] -Enables native numbering of figures and tables. -Enumeration starts at 1. -.PP +Enables numbering of figures and tables via counter fields specific to +the target format. 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] +.PP +If this extension is not enabled, tables and figures in these formats +will not be numbered. .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 @@ -4557,6 +4572,11 @@ used as an ordered list marker in place of a numeral: .PP Note: the `\f[CR]#\f[R]' ordered list marker doesn\(cqt work with \f[CR]commonmark\f[R]. +.PP +As with \f[CR]commonmark\f[R], ordered sublists must start with +\f[CR]1\f[R] or the equivalent (e.g., \f[CR]i\f[R] or \f[CR]a\f[R]). +This helps avoid unintentional lists caused by things like parenthesized +dates. .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 @@ -4626,7 +4646,7 @@ two spaces. .PP A term may have multiple definitions, and each definition may consist of one or more indented block elements (paragraph, code block, list, etc.). -The blocks in the definition shoud be indented to the column of the +The blocks in the definition should be indented to the column of the first non\-space content after the \f[CR]:\f[R] or \f[CR]\(ti\f[R] marker, or (if the \f[CR]four_space_rule\f[R] extension is enabled) four spaces or one tab stop. @@ -4771,10 +4791,11 @@ 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 +The first three kinds (simple, multiline, and grid) require lining up +columns and thus 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. +The fourth kind (pipe tables) 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). @@ -5041,6 +5062,31 @@ caption. .EX : Here\(aqs the caption. {#ident .class key=\(dqvalue\(dq} .EE +.SS Table placement in LaTeX +By default, pandoc will render tables in LaTeX using the +\f[CR]longtable\f[R] environment. +The tables will not \(lqfloat\(rq and they can span page boundaries. +If you prefer standard \(lqfloating\(rq tables (which are limited to +what can fit on one page), add the \f[CR]float\f[R] class to the +table\(cqs attributes (which can be specified after the caption). +Optionally, the \f[CR]latex\-placement\f[R] attribute may be used to +pass parameters affecting the float placement: +.IP +.EX +: The caption of the table. {#ident .float latex\-placement=\(dqht\(dq} +.EE +.PP +Note that \f[CR]longtable\f[R] does not work with two\-column layouts, +so if you are producing a two\-column document using LaTeX, you will +need to specify the \f[CR]float\f[R] class on every table, or use this +small Lua filter to add it automatically: +.IP +.EX +\f[B]function\f[R] Table(el) + el.classes:insert(\(dqfloat\(dq) + \f[B]return\f[R] el +\f[B]end\f[R] +.EE .SS Metadata blocks .SS Extension: \f[CR]pandoc_title_block\f[R] If the file begins with a title block @@ -5510,7 +5556,7 @@ 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 +Markdown, Emacs Org mode, ConTeXt, Txt2Tags, ZimWiki It will appear verbatim surrounded by \f[CR]$...$\f[R] (for inline math) or \f[CR]$$...$$\f[R] (for display math). .TP @@ -5575,8 +5621,8 @@ 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. +DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, Textile, and +Txt2Tags 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. @@ -5881,7 +5927,8 @@ slide shows and EPUB), LaTeX, and ConTeXt. .SS Images A link immediately preceded by a \f[CR]!\f[R] will be treated as an image. -The link text will be used as the image\(cqs alt text: +The link text (the part in square brackets) will be used as the +image\(cqs alt text: .IP .EX ![la lune](lalune.jpg \(dqVoyage to the moon\(dq) @@ -7414,7 +7461,9 @@ creator: text: Sarah Jones identifier: \- scheme: DOI - text: doi:10.234234.234/33 + text: \(aqurn:doi:10.234234.234/33\(aq +\- scheme: ISBN\-13 + text: \(aqurn:isbn:9780000000000\(aq publisher: My Press rights: © 2007 John Smith, CC BY\-NC ibooks: @@ -7425,8 +7474,8 @@ ibooks: The following fields are recognized: .TP \f[CR]identifier\f[R] -Either a string value or an object with fields \f[CR]text\f[R] and -\f[CR]scheme\f[R]. +Either a string value, or an object with fields \f[CR]text\f[R] and +\f[CR]scheme\f[R] (optional), or a list of such objects. Valid values for \f[CR]scheme\f[R] are \f[CR]ISBN\-10\f[R], \f[CR]GTIN\-13\f[R], \f[CR]UPC\f[R], \f[CR]ISMN\-10\f[R], \f[CR]DOI\f[R], \f[CR]LCCN\f[R], \f[CR]GTIN\-14\f[R], @@ -7436,17 +7485,22 @@ Valid values for \f[CR]scheme\f[R] are \f[CR]ISBN\-10\f[R], \f[CR]OLCC number\f[R], \f[CR]JP Magazine ID\f[R], \f[CR]UPC\-12+5\f[R], \f[CR]BNF Control number\f[R], \f[CR]ISSN\-13\f[R], \f[CR]ARK\f[R], \f[CR]Digital file internal version number\f[R]. +In the \f[CR]text\f[R] field, it is advisable to specify a URN as in the +examples above. +Note that quotes are needed around a YAML field containing a colon. .TP \f[CR]title\f[R] -Either a string value, or an object with fields \f[CR]file\-as\f[R] and -\f[CR]type\f[R], or a list of such objects. +Either a string value, or an object with fields \f[CR]text\f[R], +\f[CR]file\-as\f[R] (optional) and \f[CR]type\f[R] (optional), or a list +of such objects. Valid values for \f[CR]type\f[R] are \f[CR]main\f[R], \f[CR]subtitle\f[R], \f[CR]short\f[R], \f[CR]collection\f[R], \f[CR]edition\f[R], \f[CR]extended\f[R]. .TP \f[CR]creator\f[R] -Either a string value, or an object with fields \f[CR]role\f[R], -\f[CR]file\-as\f[R], and \f[CR]text\f[R], or a list of such objects. +Either a string value, or an object with fields \f[CR]text\f[R], +\f[CR]role\f[R] (optional), and \f[CR]file\-as\f[R] (optional), or a +list of such objects. Valid values for \f[CR]role\f[R] are MARC relators, but pandoc will attempt to translate the human\-readable versions (like \(lqauthor\(rq and \(lqeditor\(rq) to the appropriate marc relators. @@ -7465,7 +7519,8 @@ Pandoc will default to the local language if nothing is specified. .TP \f[CR]subject\f[R] Either a string value, or an object with fields \f[CR]text\f[R], -\f[CR]authority\f[R], and \f[CR]term\f[R], or a list of such objects. +\f[CR]authority\f[R] (optional), and \f[CR]term\f[R] (optional), or a +list of such objects. Valid values for \f[CR]authority\f[R] are either a reserved authority value (currently \f[CR]AAT\f[R], \f[CR]BIC\f[R], \f[CR]BISAC\f[R], \f[CR]CLC\f[R], \f[CR]DDC\f[R], \f[CR]CLIL\f[R], \f[CR]EuroVoc\f[R], @@ -8273,39 +8328,81 @@ principle do anything on your file system. Please audit filters and custom writers very carefully before using them. .IP "2." 3 +If you want to use pandoc in a web application that accepts untrusted +user input, you should be aware that running pandoc in this context +requires special precautions, or you risk exfiltration of the contents +of local files, or worse. +In particular: +.RS 4 +.IP \(bu 2 Several input formats (including LaTeX, Org, RST, and Typst) support \f[CR]include\f[R] directives that allow the contents of a file to be included in the output. An untrusted attacker could use these to view the contents of files on the file system. -(Using the \f[CR]\-\-sandbox\f[R] option can protect against this -threat.) -.IP "3." 3 +Using the \f[CR]\-\-sandbox\f[R] option will protect against this +threat. +.IP \(bu 2 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 +Using the \f[CR]\-\-sandbox\f[R] option will protect against this +threat, but will also prevent including images in these formats. +.IP \(bu 2 In reading HTML files, pandoc will attempt to include the contents of \f[CR]iframe\f[R] elements by fetching content from the local file or URL specified by \f[CR]src\f[R]. If untrusted HTML is processed on a server, this has the potential to -reveal anything readable by the process running the server. -Using the \f[CR]\-f html+raw_html\f[R] will mitigate this threat by -causing the whole \f[CR]iframe\f[R] to be parsed as a raw HTML block. -Using \f[CR]\-\-sandbox\f[R] will also protect against the threat. -.IP "5." 3 -If your application uses pandoc as a Haskell library (rather than -shelling out to the executable), it is possible to use it in a mode that -fully isolates pandoc from your file system, by running the pandoc -operations in the \f[CR]PandocPure\f[R] monad. -See the document Using the pandoc API for more details. -(This corresponds to the use of the \f[CR]\-\-sandbox\f[R] option on the -command line.) -.IP "6." 3 +reveal anything readable by the process running the server or to enable +server\-side request forgery (SSRF) attacks (CVE\-2025\-51591). +To mitigate such attacks, use \f[CR]\-\-sandbox\f[R] or +\f[CR]\-f html+raw_html\f[R] (which causes the whole \f[CR]iframe\f[R] +to be parsed as a raw HTML block). +.IP \(bu 2 +Using pandoc with \f[CR]\-\-pdf\-engine\f[R] introduces additional +risks, which cannot be mitigated by using \f[CR]\-\-sandbox\f[R]. +For example, in \f[CR]wkhtmltopdf\f[R] the \f[CR]footer\-html\f[R] and +\f[CR]header\-html\f[R] metadata fields will be passed directly to +\f[CR]wkhtmltopdf\f[R] as \f[CR]\-\-footer\-html\f[R] and +\f[CR]\-\-header\-html\f[R] arguments, and by using a \f[CR]file:\f[R] +URIs with these, one could exfiltrate local files. +In addition, using \f[CR]\-\-pdf\-engine=wkhtmltopdf\f[R] with +\f[CR]\-f html+raw_html\f[R] enables an SSRF vulnerability in +wkhtmltopdf (CVE\-2022\-35583). +Note that [\f[CR]wkhtmltopdf\f[R]) is deprecated and its authors +recommend not to use it with any untrusted input. +However, there may be similar issues with other pdf\-engines. +Anyone including a pdf\-engine in a pandoc command run on untrusted +input should audit the engine carefully and carefully control the use of +\f[CR]\-\-pdf\-engine\-opt\f[R]. +.PP +Here are some alternatives for safe use of pandoc in a web application: +.IP \(bu 2 +Use \f[CR]pandoc server\f[R] to spin up a local web server, and have +your application make requests to it. +The server runs in sandboxed mode and will not be able to read files or +use filters. +.IP \(bu 2 +Use the WASM version of pandoc. +This allows the use of Lua filters, but everything runs in an isolated +WASM sandbox. +.IP \(bu 2 +Use \f[CR]pandoc \-\-sandbox\f[R]. +However, be aware that the sandbox function only affects readers and +writers, and security issues can arise if you use it together with +\f[CR]\-\-filter\f[R] or \f[CR]\-\-pdf\-engine\f[R]. +.RE +.IP "3." 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. +.IP "4." 3 Pandoc\(cqs parsers can exhibit pathological performance on some corner cases. It is wise to put any pandoc operations under a timeout, to avoid DOS @@ -8317,14 +8414,14 @@ Note that the \f[CR]commonmark\f[R] parser (including \f[CR]commonmark_x\f[R] and \f[CR]gfm\f[R]) is much less vulnerable to pathological performance than the \f[CR]markdown\f[R] parser, so it is a better choice when processing untrusted input. -.IP "7." 3 -The HTML generated by pandoc is not guaranteed to be safe. -If \f[CR]raw_html\f[R] is enabled for the Markdown input, users can -inject arbitrary HTML. -Even if \f[CR]raw_html\f[R] is disabled, users can include dangerous -content in URLs and attributes. -To be safe, you should run all HTML generated from untrusted user input -through an HTML sanitizer. +.IP "5." 3 +If your application uses pandoc as a Haskell library (rather than +shelling out to the executable), it is possible to use it in a mode that +fully isolates pandoc from your file system, by running the pandoc +operations in the \f[CR]PandocPure\f[R] monad. +See the document Using the pandoc API for more details. +(This corresponds to the use of the \f[CR]\-\-sandbox\f[R] option on the +command line.) .SH AUTHORS Copyright 2006\(en2024 John MacFarlane (jgm\(atberkeley.edu). Released under the GPL, version 2 or greater.