Pandoc 文档转换速查指南：Quick Reference 项目详解安装、LaTeX 转 Word 与常用命令-港品优选

Pandoc 文档转换速查指南：Quick Reference 项目详解安装、LaTeX 转 Word 与常用命令

【免费下载链接】reference面向开发者的技术速查清单（Cheat Sheets）集合，整理常见技术、工具与开发流程，帮助快速查阅关键信息，提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference

Pandoc 是一款功能强大的命令行文档转换器，只需一条命令即可在 Markdown、LaTeX、HTML、Docx、PDF、AsciiDoc 等数十种格式之间自由切换。本指南以 Quick Reference 仓库中的 Pandoc 备忘清单为核心骨架，完整覆盖多平台安装方式、LaTeX 转 Word 的引文与交叉引用实战、目录生成与过滤器等高频用法，读完后你可以直接照抄命令完成日常文档转换任务。

Pandoc 是什么：一个命令行文档转换器

Pandoc 是一个文档转换器（Document Converter），它的典型使用方式是在终端中执行一条pandoc命令，把"源文件"转换成"目标文件"，而具体转换为什么格式，通常由输出文件的扩展名自动决定。这让它成为写作、排版、学术论文与博客发布流程中的"瑞士军刀"级工具。

本仓库将其收录在 README.md 的"命令"分类下（见 Pandoc 条目），与ffmpeg、jq、sed等命令工具并列，定位为一份"随查随用"的命令速查表。下文将逐条展开备忘清单中的命令，并补充参数含义与适用前提，方便你理解而非死记。

基本语法：一条命令完成转换

Pandoc 最基本的调用形式如下：

$ pandoc -s [source file] -o [output file]

其中两个核心参数：

-s/--standalone：生成独立文档（standalone document），即包含完整文档头（title、metadata、完整的<html>结构等）的成品；省略时默认输出的是"片段"（fragment），适合嵌入其他文档的场景。
-o/--output：指定输出文件名，输出格式由文件扩展名推断。例如-o out.docx输出 Word 文档、-o out.html输出网页、-o out.pdf输出 PDF。

这一条语法是后续所有示例的共同基础——变换的是输入输出文件，以及附加的各种行为选项。

安装 Pandoc：覆盖主流操作系统

备忘清单给出了不同平台的安装命令，汇总如下：

在 Linux 各主流发行版上，Pandoc 已进入官方软件源，可直接用包管理器安装：

Debian / Ubuntu

$ sudo apt-get update $ sudo apt-get install pandoc

先执行apt-get update刷新软件源索引，再安装，可避免因索引过期导致的安装失败。

Fedora

$ sudo dnf install pandoc

Arch Linux

$ sudo pacman -S pandoc

需要注意的适用前提：不同发行版软件源中的 Pandoc 版本可能滞后于最新版，若需要--citeproc、新格式支持等较新特性，建议查阅 Pandoc 官方文档了解各平台最新安装方式；通过包管理器安装后，可运行pandoc --version验证安装结果与版本号。

实战：将 LaTeX 转换为 MS Word

LaTeX（.tex）与 Word（.docx）互转是 Pandoc 的高频场景，备忘清单给出了四种由浅入深的用法。

1. 简单的`.tex`到`.docx`转换

$ pandoc -s file.tex -o file.docx

-s生成包含文档结构的独立 Word 文档，标题、章节、公式与表格会被转换为 Word 原生元素，转换后可在 Word 中直接编辑。

2. 使用默认引文（Citation）处理

$ pandoc -s file.tex --citeproc --bibliography=bib_library.bib -o file.docx

--citeproc：启用内置引文处理器，把文中的[@key]等引文标记渲染为规范的引用文本与参考文献列表。
--bibliography=bib_library.bib：指定参考文献数据库，Pandoc 原生支持 BibTeX（.bib）等常见格式。

这一组合适合论文、专著等需要文献管理场景的 LaTeX 文档，转换后文末会自动生成参考文献列表。

3. 指定具体引文样式（CSL）

$ pandoc -s file.tex --citeproc --bibliography=bib_library.bib --csl=apa.csl -o file.docx

--csl=apa.csl：通过 CSL（Citation Style Language）样式文件控制引用与参考文献的排版风格。上例使用 APA 样式（apa.csl），换成其他.csl文件即可切换为 IEEE、Chicago、GB/T 7714 等不同期刊或机构要求的引用格式。当目标期刊对引用格式有硬性要求时，这一步必不可少。

4. 带交叉引用的转换

$ pandoc -s file.tex --filter pandoc-crossref -o file.docx

--filter pandoc-crossref：调用pandoc-crossref外部过滤器处理交叉引用（对图表、公式、章节进行编号与交叉引用，如"见图 3"）。pandoc-crossref是独立于 Pandoc 的第三方可执行程序，需要单独安装，安装后放到 PATH 中即可被--filter调用。

常用转换场景：从 Markdown 到各种格式

转换文件格式：Markdown 转 PDF

$ pandoc input.md -o output.pdf

以input.md为源、输出为 PDF。适用前提：Pandoc 本身不直接渲染 PDF，而是把文档转换为中间格式（默认是 LaTeX）后交给 LaTeX 引擎（如pdflatex）编译。因此本命令要求系统中已安装可用的 LaTeX 发行版；若无 LaTeX 环境，则需要配置其他 PDF 引擎（如--pdf-engine=weasyprint、--pdf-engine=wkhtmltopdf）。

支持的输入格式：纯文本转 HTML

$ pandoc -s input.txt -o output.html

-s在此处的作用是把input.txt转换并包装为一份完整的 HTML 文档（含<html>、<head>、<body>结构），可直接用浏览器打开。Pandoc 的输入格式非常丰富，除了 Markdown、纯文本，还包括 HTML、LaTeX、reStructuredText、Org-mode、Docx、EPUB 等。

自定义输出格式：显式指定`--to`

$ pandoc input.md --to=latex -o output.tex

--to=latex（可简写为-t latex）显式声明输出格式，不依赖输出文件扩展名推断。同样的源文件，将--to换成html、docx、markdown等即可输出对应格式，适用于"扩展名无法表达格式意图"或需要强制指定格式的场景。

添加元数据：标题、作者与日期

$ pandoc input.md -o output.pdf --metadata title="My Document"

--metadata title="My Document"在文档头中注入键值对元数据。除了title，常见的还有author、date等，它们会被模板渲染到文档的标题区、页眉或元信息中。也可以使用--metadata-file=meta.yaml从 YAML 文件批量加载元数据，适合元数据较多的文档。

从 URL 直接转换

$ pandoc https://example.com/document.md -o output.pdf

Pandoc 可以直接把 URL 作为输入源，抓取远程的 Markdown 文档并转换。适用前提：命令执行时所在主机需要能正常访问该 URL（注意网络可达性与代理设置）。

生成幻灯片

$ pandoc input.md -t beamer -o output.pdf

-t beamer使用 LaTeX 的 Beamer 文档类生成 PDF 幻灯片。适用前提：需要本地具备 LaTeX 环境。Beamer 幻灯片中，Markdown 里的二级标题（##）通常对应每一页幻灯片的标题，配合 Pandoc 的 YAML 头信息即可控制主题、字体等幻灯片外观。

合并多个文件

$ pandoc file1.md file2.md -o output.pdf

Pandoc 接受多个输入文件，按命令行给出的顺序依次合并后统一转换，常用于把分散的章节文件拼装成一篇完整文档。

指定样式文件

$ pandoc input.md -o output.pdf --css=style.css

--css=style.css为支持 CSS 的输出格式（如 HTML、EPUB）指定外部样式表。需要说明的是，默认的 PDF（LaTeX 引擎）路径下 CSS 不生效，CSS 主要作用于 HTML / EPUB 输出；若确需用 CSS 控制 PDF 外观，应搭配--pdf-engine=weasyprint等基于浏览器的 PDF 引擎。

转换为 AsciiDoc

$ pandoc input.md -o output.asciidoc

输出扩展名asciidoc自动触发 AsciiDoc 格式，适合需要把 Markdown 内容迁移到 AsciiDoc 文档体系（如部分文档站点、书籍出版管线）的场景。

转换为 Docx 格式

$ pandoc input.md -o output.docx

把 Markdown 直接转为 Word 文档，是"写作用 Markdown、交付用 Word"工作流的典型用法，转换后可继续用 Word 审阅与批注。

高级加工：Lua 过滤器与目录控制

执行 Lua 过滤器

$ pandoc input.md --lua-filter=custom-filter.lua -o output.pdf

--lua-filter=custom-filter.lua加载并执行一个 Lua 脚本过滤器。Lua 过滤器是 Pandoc 强大的可编程扩展机制：在文档转换过程中，过滤器可以遍历并修改内部的元素树（如给所有代码块加边框、自动替换特定文本、对表格做后处理等）。适用前提：需本地安装 Lua 解释器，且过滤器脚本语法与当前 Pandoc 版本兼容。

自动生成目录（TOC）

$ pandoc input.md -o output.pdf --toc

--toc自动根据文档标题层级生成目录（Table of Contents），并按标题结构为正文生成编号。

控制目录深度

$ pandoc input.md -o output.pdf --toc --toc-depth=2

--toc-depth=2指定目录包含的标题层级数：--toc-depth=2只收录一级与二级标题；默认值为 3（收录到三级标题）。层级越深，目录越细；文档较长时，收敛到 2 级目录更清爽，这也是"禁用/收敛目录编号"的常用手段。

调试与能力查询

显示详细信息

$ pandoc input.md -o output.pdf -v

-v/--verbose输出详细的处理日志，包括格式探测、过滤器调用、底层引擎执行情况等，排查转换失败或行为不符合预期时非常有用。

查看支持的输出格式

$ pandoc --list-output-formats

--list-output-formats列出当前 Pandoc 版本支持的全部输出格式名称，是确认"目标格式是否可用"最直接的方式。类似的，--list-input-formats可查看支持的输入格式清单。安装完 Pandoc 后先执行这两条命令，就能清楚掌握本机版本的格式能力边界。

关键参数速查表

将本文涉及的核心参数汇总如下，便于快速检索：

在 Quick Reference 仓库中的定位与扩展阅读

清单本体：docs/pandoc.md 是本文的原始出处，所有命令均可在其中逐条核对；该文件属于仓库 docs 目录下的备忘清单之一。
首页导航：README.md 的"命令"分类中以"Pandoc"卡片链接到本文档，标注其为"文档转换器"工具。
写作输入搭配：Pandoc 最常见的源格式是 Markdown，可配合仓库中的 Markdown 备忘清单掌握标题、列表、块引用、任务列表等语法，再交给 Pandoc 转换成目标格式，形成"Markdown 写作 → Pandoc 排版"的完整链路。
生成机制：本仓库通过refs-cli把docs/*.md编译为静态 HTML 速查页（见 package.json 中的build/start脚本），每篇备忘清单的排版与渲染均由此管线处理，贡献与扩展方式可参考 CONTRIBUTING.md。

注意事项与适用前提

PDF 输出依赖外部引擎：默认走 LaTeX 引擎，需预装 LaTeX 发行版；无 LaTeX 时可改用--pdf-engine=weasyprint/wkhtmltopdf等（此时--css才会生效）。
引文处理：--citeproc为内置引文处理器，老版本 Pandoc 需要--filter pandoc-citeproc的写法，具体以当前pandoc --version的说明为准。
过滤器为外部组件：pandoc-crossref、Lua 过滤器脚本均需自行安装与维护，与 Pandoc 主程序版本可能存在兼容性要求。
URL 转换依赖网络：从 URL 抓取内容时需保证网络可达。
版本差异：各发行版包管理器提供的 Pandoc 版本与特性集可能不同，执行前可用pandoc --list-output-formats快速确认本机能力。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析