pandoc PDF 可访问性设置：快速生成符合 WCAG 标准的无障碍 PDF 完整指南
【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc
pandoc 是一款强大的通用标记转换工具（Universal Markup Converter），能把 Markdown、HTML、LaTeX 等数十种格式互相转换。但默认生成的 PDF 只有"排版信息"，没有"语义信息"——屏幕阅读器读起来一塌糊涂。本文带你完成 pandoc PDF 可访问性设置，通过 PDF/UA 标签让文档真正符合 WCAG 无障碍标准，覆盖 5 种引擎方案。
为什么普通 PDF 对读屏用户"不友好"
PDF 本质上只描述"字符放在页面哪个位置"，并不包含标题、段落、表格等结构语义。因此：
- 🔊 屏幕阅读器无法正确朗读标题层级和阅读顺序
- 🔍 文本提取与搜索不可靠
- ♿ 不满足 WCAG 2.1 对文档型内容的基本要求
解决方案是带标签的 PDF（Tagged PDF），其工业标准是ISO 14289（PDF/UA）。pandoc 支持多种引擎生成 PDF/UA 文档。
方案一：LaTeX + LuaLaTeX（最主流的设置方式）
pandoc 默认使用 LaTeX 生成 PDF。较新的 LaTeX 内核提供\DocumentMetadata接口，pandoc 通过pdfstandard元数据变量来启用它。
一键启用 PDF/UA-2
pandoc -V pdfstandard=ua-2 --pdf-engine=lualatex doc.md -o doc.pdf要求：LuaLaTeX 引擎 + 新版 TeX Live（官方建议 TeX Live 2025，内核 2025-06-01 或更新版本）。旧版 LaTeX 需改用下面的其他引擎。
ua-2即 PDF/UA-2，是可访问性专用标准；a-2b、a-4f等则是 PDF/A 存档标准。
同时满足多个 PDF 标准
在 YAML 头中重复设置即可组合多个标准，pandoc 会自动推断所需的 PDF 版本：
--- pdfstandard: - ua-2 - a-4f ---pandoc 的常用标准支持清单：
| 类别 | 可选值 | 说明 |
|---|---|---|
| PDF/UA（无障碍） | ua-1、ua-2 | 可访问性标准，推荐 |
| PDF/A（长期存档） | a-1b、a-2b、a-3b、a-4f、a-3u等 | 数字保存标准 |
这套逻辑实现在src/Text/Pandoc/Writers/LaTeX.hs的processPdfStandard函数中：它会校验标准取值、自动推断 PDF 版本，并在需要时强制开启标签（tagging）。最终生成的\DocumentMetadata{...}代码块来自模板文件data/templates/document-metadata.latex。
方案二：ConTeXt + tagging 扩展
ConTeXt 引擎总是生成带标签的 PDF，但 pandoc 默认输出的标记偏向"阅读友好"而非"标签友好"。启用tagging格式扩展即可切换为标签优化模式：
pandoc -t context+tagging doc.md -o doc.pdf该扩展会为段落增加额外标记、改用强调文本的替代写法（见 MANUAL.txt 中 "Extension: tagging" 一节）。注意请使用较新版本的 ConTeXt，旧版存在 PDF 元数据无效的 bug。
方案三：HTML 引擎（WeasyPrint / Prince）
如果你的文档天然是 HTML 风格，可以用 HTML-to-PDF 引擎：
WeasyPrint（免费，57 版起实验性支持）
pandoc --pdf-engine=weasyprint \ --pdf-engine-opt=--pdf-variant=pdf/ua-1 \ doc.md -o doc.pdf⚠️ 该功能目前是实验性的，不要默认假定标准合规。
Prince XML（商业引擎，标准支持最完善）
pandoc --pdf-engine=prince \ --pdf-engine-opt=--tagged-pdf \ doc.md -o doc.pdf方案四：Typst 0.12 生成 PDF/A
轻量级排版引擎 Typst 0.12 已支持 PDF/A-2b：
pandoc --pdf-engine=typst --pdf-engine-opt=--pdf-standard=a-2b doc.md -o doc.pdf方案五：Word 系软件中转（LibreOffice / Word）
pandoc 不直接调用 Word/LibreOffice 生成 PDF，但可以走"两跳"路线：
- pandoc 将文档转为
docx或odt - 用 Word 或 LibreOffice 打开，再导出为带标签的 PDF
这条路线适合需要利用 Word 内置"文档检查器 - 无障碍性"功能反复调校的场景。
让 PDF 真正"无障碍"的 4 个细节
- 图片必加替代文本：Markdown 中写作
描述图片内容的文字，这段 alt 文本会进入 PDF 标签树，是 WCAG 1.1.1 的硬性要求。 - 表格用原生语法：管道表格、网格表格会被 pandoc 转成带表头角色的 PDF 表格；用空格对齐的"伪表格"则不行。
- 声明文档语言：
-V lang=en（或 YAML 中lang: zh），帮助读屏软件选择正确的发音引擎。 - 用外部工具验证：标准合规取决于很多因素（包括嵌入图片的颜色空间），pandoc 无法替你检查。请导出后用外部 PDF/UA 校验器验证最终文件。
五种方案快速对照表
| 引擎 | 关键设置 | 可得到的标准 | 备注 |
|---|---|---|---|
| LuaLaTeX | -V pdfstandard=ua-2 | PDF/UA + PDF/A | 最常用，需 TeX Live 2025 |
| ConTeXt | -t context+tagging | 始终带标签 | 用新版 ConTeXt |
| WeasyPrint | --pdf-variant=pdf/ua-1 | PDF/UA-1（实验性） | 免费 |
| Prince | --tagged-pdf | 多标准 | 商业 |
| Typst 0.12+ | --pdf-standard=a-2b | PDF/A-2b | 轻量 |
相关源码与文档路径
- 官方手册章节："Accessible PDFs and PDF archiving standards" ——
MANUAL.txt pdfstandard元数据文档：MANUAL.txt中 "Variables for LaTeX" 小节- 标准解析与校验逻辑：
src/Text/Pandoc/Writers/LaTeX.hs（processPdfStandard） \DocumentMetadata模板：data/templates/document-metadata.latex- 命令回归测试样例：
test/command/pdfstandard.md
想深入阅读源码？克隆仓库即可：
git clone https://gitcode.com/gh_mirrors/pa/pandoc小结：给文档加上 PDF/UA 标签，是成本最低、收益最大的无障碍改造。一条-V pdfstandard=ua-2，你的 pandoc 文档就能迈出符合 WCAG 标准的关键一步。
【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
