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 以获取完整的版权和保修声明。）