lee/pandoc
1
0
Fork 0
mirror of https://github.com/jgm/pandoc.git synced 2026-08-26 10:16:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update manual date and regenerate man pages.

Browse Source
This commit is contained in:
John MacFarlane
2026-07-21 23:20:21 +02:00
parent e86b71aca2
commit ee69867122
4 changed files with 159 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MANUAL.txt
+1 -1
View File
@@ -1,7 +1,7 @@
---
title: Pandoc User's Guide
author: John MacFarlane
date: 2026-06-03
date: 2026-07-21
---
# Synopsis
pandoc-cli/man/pandoc-lua.1
+2 -2
View File
@@ -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
pandoc-cli/man/pandoc-server.1
+2 -2
View File
@@ -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
pandoc-cli/man/pandoc.1
+154 -57
View File
@@ -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.