Pandoc User’s Guide (April 7, 2024)

• 语言: 英语
• 格式: .pdf
• 来源: www.pandoc.org

摘要

Pandoc is a Haskell library and command-line tool for converting between markup formats, including Markdown, HTML, LaTeX, and Word docx. It uses readers to parse input into an abstract syntax tree (AST) and writers to convert the AST to output formats. The guide covers usage, options, templates, and security considerations. Security notes warn that filters or custom writers can access the file system, include directives in input formats may expose files, and output formats like HTML or EPUB can embed images. The --sandbox option mitigates these risks. Pandoc's Markdown supports tables, footnotes, citations, and math. Conversions from expressive formats may be lossy. The guide also details template variables, EPUB metadata fields, and extensions like mark, attributes, and old_dashes.

AI总结

Pandoc 是一个 Haskell 库和命令行工具，用于在不同标记格式之间进行转换，支持 Markdown、HTML、LaTeX、Word docx 等多种格式。它通过读取器解析输入格式生成抽象语法树（AST），再由写入器将 AST 转换为目标格式。

用户可通过 `-o` 指定输出文件，默认输出到 stdout；使用 `-s` 或 `--standalone` 生成完整文档。Pandoc 支持从 Web 读取、PDF 生成（需 LaTeX 或 wkhtmltopdf 等引擎），并可通过 `--from` 和 `--to` 指定输入/输出格式。

文档详细列出了各类选项，包括通用选项、读取器选项、写入器选项、特定格式选项（如 PDF、HTML、EPUB）、引用渲染、数学公式渲染及包装脚本选项。退出码用于指示运行状态。

模板系统支持变量插值、条件、循环、部分嵌套和管道。自动设置的变量包括 `body`、`date-meta`、`header-includes`、`toc`、`pandoc-version` 等。EPUB 元数据变量如 `creator`、`contributor`、`date`、`lang`、`subject` 等也受支持。

安全方面需注意：过滤器可能执行任意操作；输入格式中的包含指令可能泄露文件；输出格式可能嵌入非图像文件；解析器在极端情况下性能不佳（CommonMark 解析器更稳健）；生成的 HTML 可能不安全，需通过 HTML 清理器处理。`--sandbox` 选项可增强安全性。

扩展功能包括：`mark`（高亮文本）、`attributes`（为元素附加属性）、`old_dashes`（旧版破折号解析）、`angle_brackets_escapable`（允许转义尖括号）、`lists_without_preceding_blankline`（列表紧跟段落）、`four_space_rule`（旧版列表缩进规则）。