path: root/pandoc-cli/man/pandoc-server.1

.\" Automatically generated by Pandoc 3.8.2
.\"
.TH "pandoc-server" "1" "August 15, 2022" "pandoc 3.8.2" "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\(cqs
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
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
{ \(dqerror\(dq: string with the error message }
.EE
.PP
If the conversion is successful:
.IP
.EX
{ \(dqoutput\(dq: string with textual or base64\-encoded binary output,
  \(dqbase64\(dq: boolean (true means the \(dqoutput\(dq is base64\-encoded),
  \(dqmessages\(dq: array of message objects (see below) }
.EE
.PP
Each element of the \(lqmessages\(rq array will have the format
.IP
.EX
{ \(dqmessage\(dq: string,
  \(dqverbosity\(dq: string (either \(dqWARNING\(dq or \(dqINFO\(dq) }
.EE
.SS Request
The body of the POST request should be a JSON object, with the following
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]\(dqmarkdown\(dq\f[R])
The input format, possibly with extensions, just as it is specified on
the pandoc command line.
.TP
\f[CR]to\f[R] (string, default \f[CR]\(dqhtml\(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]\(dqaccept\(dq|\(dqreject\(dq|\(dqall\(dq\f[R])
Specifies what to do with insertions, deletions, and comments produced
by the MS Word \(lqTrack 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]\(dqauto\(dq|\(dqpreserve\(dq|\(dqnone\(dq\f[R])
Text wrapping option: either \f[CR]\(dqauto\(dq\f[R] (automatic
hard\-wrapping to fit within a column width),
\f[CR]\(dqpreserve\(dq\f[R] (insert newlines where they are present in
the source), or \f[CR]\(dqnone\(dq\f[R] (don\(cqt insert any unnecessary
newlines at all).
.TP
\f[CR]columns\f[R] (integer, default 72)
Column width (affects text wrapping and calculation of table column
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]list\-of\-figures\f[R] (boolean, default false)
Include a list of figures (in supported formats).
.TP
\f[CR]list\-of\-tables\f[R] (boolean, default false)
Include a list of tables (in supported formats).
.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]syntax\-highlighting\f[R] (\f[CR]\(dqdefault\(dq|\(dqnone\(dq|\(dqidiomatic\(dq|style\f[R])
The method used for code syntax highlighting.
Setting a specific \f[I]style\f[R] causes highlighting to be performed
with the internal highlighting engine, using KDE syntax definitions and
styles.
The \f[CR]\(dqidiomatic\(dq\f[R] method uses a format\-specific
highlighter if one is available, or the default style if the target
format has no idiomatic highlighting method.
Setting this option to \f[CR]none\f[R] disables all syntax highlighting.
The \f[CR]\(dqdefault\(dq\f[R] method uses a format\-specific default.
.RS
.PP
Standard styles are \f[CR]\(dqpygments\(dq\f[R] (the default),
\f[CR]\(dqkate\(dq\f[R], \f[CR]\(dqmonochrome\(dq\f[R],
\f[CR]\(dqbreezeDark\(dq\f[R], \f[CR]\(dqespresso\(dq\f[R],
\f[CR]\(dqzenburn\(dq\f[R], \f[CR]\(dqhaddock\(dq\f[R], and
\f[CR]\(dqtango\(dq\f[R].
Alternatively, the path of a \f[CR].theme\f[R] with a KDE syntax theme
may be used (in this case, the relevant file contents must also be
included in \f[CR]files\f[R], see below).
.PP
The default for HTML, EPUB, Docx, Ms, Man, and LaTeX output is to use
the internal highlighter with the default style; Typst output relies on
Typst\(cqs own syntax highlighting system by default.
.RE
.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]<q>\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]\(dqdocument\(dq|\(dqsection\(dq|\(dqblock\(dq\f[R])
Determines whether link references and footnotes are placed at the end
of the document, the end of the section, or the end of the block
(e.g.\ paragraph), in certain formats.
(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]\(dqdefault\(dq|\(dqpart\(dq|\(dqchapter\(dq|\(dqsection\(dq\f[R])
Determines how top\-level headings are interpreted in LaTeX, ConTeXt,
DocBook, and TEI.
The \f[CR]\(dqdefault\(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
\(lq2\(rq and the first subsection \(lq2.1\(rq; \f[CR][0,1]\f[R] will
cause the first section to be numbered \(lq1\(rq and the first
subsection \(lq1.2.\(rq
.TP
\f[CR]html\-math\-method\f[R] (\f[CR]\(dqplain\(dq|\(dqwebtex\(dq|\(dqgladtex\(dq|\(dqmathml\(dq|\(dqmathjax\(dq|\(dqkatex\(dq\f[R])
Determines how math is represented in HTML.
.TP
\f[CR]listings\f[R] (boolean, default false)
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]\(dqnone\(dq|\(dqreferences\(dq|\(dqjavascript\(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 \(lqEPUB\(rq)
Name of content subdirectory in the EPUB container.
.TP
\f[CR]epub\-fonts\f[R] (array of file paths)
Fonts to include in the EPUB.
The fonts themselves must be included in \f[CR]files\f[R] (see below).
.TP
\f[CR]ipynb\-output\f[R] (\f[CR]\(dqbest\(dq|\(dqall\(dq|\(dqnone\(dq\f[R])
Determines how ipynb output cells are treated.
\f[CR]all\f[R] means that all of the data formats included in the
original are preserved.
\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]\(dqciteproc\(dq|\(dqnatbib\(dq|\(dqbiblatex\(dq\f[R])
Determines how citations are formatted in LaTeX output.
.TP
\f[CR]files\f[R] (JSON mapping of file paths to base64\-encoded strings)
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]\(dqmarkdown\(dq\f[R])
.IP \(bu 2
\f[CR]to\f[R] (optional string, default is \f[CR]\(dqhtml\(dq\f[R])
.IP \(bu 2
\f[CR]standalone\f[R] (optional boolean, default is \f[CR]false\f[R])
.PP
It returns a JSON object with fields \f[CR]html\f[R] and
\f[CR]version\f[R].
This endpoint is designed to support the Babelmark website.
.SH AUTHORS
Copyright 2022 John MacFarlane (jgm\(atberkeley.edu).
Released under the GPL, version 2 or greater.
This software carries no warranty of any kind.
(See COPYRIGHT for full copyright and warranty notices.)
.PP
The Pandoc source code may be downloaded
from <https://hackage.haskell.org/package/pandoc> or
<https://github.com/jgm/pandoc/releases>.  Further
documentation is available at <https://pandoc.org>.