Pandoc 服务器
概要
pandoc-server [options]
介绍
pandoc-server
是一个 Web 服务器,可以执行 pandoc 转换。它可以作为运行中的服务器使用,也可以作为 CGI 程序使用。
要将 pandoc-server
作为 CGI 程序使用,需要将其重命名(或创建符号链接)为 pandoc-server.cgi
。(注意:如果创建符号链接,可能需要调整 Web 服务器的配置以允许 CGI 脚本跟随符号链接。)
所有的 pandoc 功能都在 PandocPure 单子中运行,这确保了它们不能在服务器上执行 I/O 操作。这应该能提供高度的安全性。然而,这种安全性也带来了一定的限制:
- 无法生成 PDF 文件。
- 不支持过滤器。
- 无法通过 HTTP 获取资源。
- 任何文档转换所需的图片、包含文件或其他资源都必须明确地包含在请求中,通过
files
字段(参见下面的 API 部分)。
选项
--port NUM
服务器运行的 HTTP 端口。默认值:3030。
--timeout SECONDS
超时秒数,超过该时间后将终止转换。默认值:2。
当 pandoc-server
作为 CGI 程序运行时,此选项可以通过 PANDOC_SERVER_TIMEOUT
环境变量设置。
--help
打印此帮助信息。
--version
打印版本信息。
API
根端点
根路径( /
)端点仅接受 POST
请求。
响应
返回的文档将以以下格式之一呈现(按优先级顺序),具体取决于 Accept
头:
application/octet-stream
text/plain
application/json
如果结果是二进制格式(如 epub
或 docx
),并且内容以纯文本或 JSON 形式返回,则二进制内容会被 base64
编码。
如果给出 JSON 响应,其格式将是以下形式之一。如果转换不成功:
{
"error": "错误消息字符串"
}
如果转换成功:
{
"output": "文本或 base64 编码的二进制输出字符串",
"base64": "布尔值(true 表示 'output' 已被 base64 编码)",
"messages": "消息对象数组(参见下文)"
}
“messages” 数组中的每个元素将具有以下格式:
{
"message": "消息字符串",
"verbosity": "字符串('WARNING' 或 'INFO')"
}
请求
POST 请求的正文应该是一个 JSON 对象,包含以下字段。其中只有 text
字段是必需的;其他所有字段都可以省略以使用默认值。当有多个字符串选项时,给出的第一个选项是默认值。
text
(字符串)待转换的文档。注意:如果输入格式是二进制格式(如
epub
或docx
),则text
应该是文档的 base64 编码。from
(字符串,默认为"markdown"
)输入格式,可能带有扩展,就像在 pandoc 命令行中指定的一样。
to
(字符串,默认为"html"
)输出格式,可能带有扩展,就像在 pandoc 命令行中指定的一样。
shift-heading-level-by
(整数,默认为0
)增加或减少所有标题的级别。
indented-code-classes
(字符串数组)应用于缩进 Markdown 代码块的类列表。
default-image-extension
(字符串)应用于缺少扩展名的图像源的扩展名(例如
.jpg
)。metadata
(JSON 映射)字符串值元数据。
tab-stop
(整数,默认为4
)Tab 停顿(每 Tab 的空格数)。
track-changes
("accept" | "reject" | "all")指定如何处理由 MS Word “Track Changes” 功能产生的插入、删除和注释。仅影响
docx
输入。abbreviations
(文件路径)在解析 Markdown 时被视为缩写的字符串列表。详情请参阅 pandoc(1) 中的
--abbreviations
选项。standalone
(布尔值,默认为false
)如果为
true
,则会使用默认模板或通过template
指定的自定义模板生成独立文档。如果为false
,则生成文档片段。template
(字符串)文档模板的字符串内容(有关格式详情,请参阅 pandoc(1) 中的 “Templates” 部分)。
variables
(JSON 映射)用于在模板中插值的变量。(详情请参阅 pandoc(1) 中的 “Templates” 部分。)
dpi
(整数,默认为96
)用于像素和其他度量单位之间转换的每英寸点数(用于图像尺寸)。
wrap
("auto" | "preserve" | "none")文本换行选项:可以是
"auto"
(自动硬换行以适应列宽),"preserve"
(在源代码中已有换行符的地方插入新行),或者"none"
(不插入任何不必要的新行)。columns
(整数,默认为72
)列宽(影响纯文本格式中的文本换行和表格列宽计算)。
table-of-contents
(布尔值,默认为false
)包含目录(在支持的格式中)。
toc-depth
(整数,默认为3
)目录中包含的章节深度。
strip-comments
(布尔值,默认为false
)导致在 Markdown 或 Textile 源代码中移除 HTML 注释,而不是传递到输出格式中。
highlight-style
(字符串,如果不设置则无高亮)指定用于代码语法高亮的样式。标准样式包括 "pygments"(默认)、"kate"、"monochrome"、"breezeDark"、"espresso"、"zenburn"、"haddock" 和 "tango"。或者,也可以使用带有 KDE 语法主题的
.theme
文件路径(在这种情况下,相关文件的内容也必须包含在files
中,见下文)。embed-resources
使用数据 URI 将图像、脚本、样式和其他资源嵌入到 HTML 文档中。请注意,除非所有外部资源的内容都包含在
files
下,否则这将不起作用。html-q-tags
(布尔值,默认为false
)在 HTML 中使用
<q>
元素代替实际的引号标记。ascii
(布尔值,默认为false
)在可能的情况下使用实体和转义序列来避免输出中的非 ASCII 字符。
reference-links
(布尔值,默认为false
)在 Markdown 输出中创建参考链接而非内联链接。
reference-location
("document" | "section" | "block")决定链接参考和脚注是在文档末尾、节末尾还是块(例如段落)末尾放置,在某些格式中。详情请参阅 pandoc(1) 中的
--reference-location
选项。setext-headers
(布尔值,默认为false
)在 Markdown 输出中使用 Setext(下划线)标题而非 ATX(以 # 开头)标题。
top-level-division
("default" | "part" | "chapter" | "section")决定 LaTeX、ConTeXt、DocBook 和 TEI 中顶级标题的解释方式。“default” 值试图根据启发式算法选择最佳解释。
number-sections
(布尔值, 默认为false
)自动编号章节(在支持的格式中)。
number-offset
(整数数组)添加到章节编号各部分的偏移量。例如,
[1]
将导致第一个章节被编号为“2”,第一个子章节为“2.1”;[0,1]
将导致第一个章节被编号为“1”,第一个子章节为“1.2”。html-math-method
("plain"|"webtex"|"gladtex"|"mathml"|"mathjax"|"katex")确定数学公式在 HTML 中的表现形式。
listings
(布尔值, 默认为false
)在 LaTeX 输出中使用
listings
包来格式化代码。incremental
(布尔值, 默认为false
)如果设置为
true
,则幻灯片中的列表将默认逐项显示。slide-level
(整数)在幻灯片中决定幻灯片分割的标题级别。默认是选择最高标题级别下有正文文本的级别。
section-divs
(布尔值, 默认为false
)根据标题将文档组织成嵌套的章节结构。
email-obfuscation
("none"|"references"|"javascript")确定 HTML 中电子邮件地址如何被混淆。
identifier-prefix
(字符串)添加到所有自动生成的标识符前缀。
title-prefix
(字符串)添加到 HTML 标题中的前缀。
reference-doc
(文件路径)用于创建
docx
或odt
或pptx
的参考文档。请参见 pandoc(1) 中关于--reference-doc
的详细信息。文件的内容必须包含在files
目录下。split-level
(整数, 默认为 1)在 EPUB 或分块 HTML 中拆分文档的标题级别。
epub-cover-image
(文件路径)EPUB 的封面图片。文件的内容必须包含在
files
目录下。epub-metadata
(文件路径)包含用于 EPUB 元数据的 Dublin Core XML 元素的文件路径。文件的内容必须包含在
files
目录下。epub-subdirectory
(字符串, 默认为 “EPUB”)EPUB 容器中内容子目录的名称。
epub-fonts
(文件路径数组)要在 EPUB 中包含的字体。字体本身必须包含在
files
目录下(见下文)。ipynb-output
("best"|"all"|"none")决定如何处理 ipynb 输出单元格。"all" 表示保留原始文件中包含的所有数据格式。"none" 表示省略数据单元格的内容。"best" 让 pandoc 尝试从每个输出单元格中选择与输出格式兼容的最丰富的数据块。
citeproc
(布尔值, 默认为false
)使用 citeproc 处理引用。详情请参阅 pandoc(1) 中的 “Citations” 部分。
bibliography
( 文件路径数组 )包含书目数据的文件。文件的内容必须包含在
files
目录下。csl
( 文件路径 )CSL 样式文件。文件的内容必须包含在
files
目录下。cite-method
( "citeproc" | "natbib" | "biblatex" )决定 LaTeX 输出中如何格式化引用。
files
( JSON 文件路径到 Base64 编码字符串的映射 )转换所需的任何文件,包括文档源中引用的图像,都应在这里列出。二进制数据必须使用 Base64 编码。文本数据可以保持原样,除非它也是有效的 Base64 数据,在这种情况下,它将按这种方式解释。
/batch
端点
/batch
端点的行为类似于根端点,但有以下两点不同:
- 它接受一个 JSON 数组,数组中的每个元素都是一个 JSON 对象,类似于根端点所期望的对象。
- 它返回一个 JSON 结果数组。
此端点可用于在一个请求中转换一系列小片段。
/version
端点
/version
端点接受 GET 请求,并根据 Accept
头部的不同返回 pandoc 版本信息作为纯文本或 JSON 编码的字符串。
/babelmark
端点
/babelmark
端点接受带有以下查询参数的 GET 请求:
text
(必需的字符串)from
(可选的字符串,默认值为 "markdown")to
(可选的字符串,默认值为 "html")standalone
(可选的布尔值,默认值为false
)
该端点返回一个包含 html
和 version
字段的 JSON 对象。此端点旨在支持 Babelmark 网站。
作者
版权所有 2022 年 John MacFarlane (jgm@berkeley.edu)。依据 GNU 通用公共许可证( GPL )第 2 版或更高版本发布。本软件不附带任何形式的保修。(请参见 COPYRIGHT 以获取完整的版权和保修声明。)