批量把 Markdown 转成 PDF：浏览器 ZIP、CLI、Pandoc 与 CI
在浏览器中一次批量导出最多 15 个 Markdown 文件并下载 ZIP，或用 CLI 自动生成独立 PDF、用 Pandoc 合并章节；同时说明配额、错误文件与 CI 工作流。保留章节排序、图片路径和字体检查方法，分清批量打包与合成一本书。
三种常见批量任务：
- 一个 Markdown → 一个 PDF，重复多个文件：
md-to-pdf *.md（npm CLI）。 - 多个 Markdown → 一个合并 PDF（一本书、多章报告）：
pandoc chapter*.md -o book.pdf。 - 多个 Markdown → 每次提交输出一份 PDF：GitHub Actions + npm CLI。
也有浏览器批量路径：无需安装 CLI，打开批量导出即可生成独立输出。/markdown-to-pdf 单文档页面仍适合一份文件。请按交付物选择浏览器批量、本地自动化或合成一份 PDF。
打开批量导出，上传最多 15 个 Markdown 文件，选择 PDF 与统一渲染设置，然后运行导出。支持的输出格式有 PNG、JPEG、WebP、PDF 和 DOCX。这是付费功能，Creator 每月包含 20 次批量运行。
ZIP 中每个成功的输入对应一个输出。文件失败时，请查看对应的 .error.txt 说明，不要默认整批全部成功。只要至少一个文件成功，这次任务就会消耗一次批量运行。装着 15 份 PDF 的 ZIP 仍然是 15 份独立文档，不是一本 15 章的 PDF。
把下方示例作为其中一个输入文件，对照标题、清单与末尾说明，检查预览和可下载 PDF，然后逐一检查其他输出。
# Chapter 01: export checks
## Scope
This sample represents one source file in a multi-file export.
- Keep one output per input file
- Check every generated file
- Inspect the ZIP for error notes
> A ZIP of PDFs is different from one merged PDF.
最简单的情况。你有 chapter01.md、chapter02.md，要生成 chapter01.pdf、chapter02.pdf …
npm install -g md-to-pdf
md-to-pdf 'chapters/*.md'
完事—默认会在每个 .md 旁边写一个 .pdf。加主题控制外观：
md-to-pdf 'chapters/*.md' --stylesheet ./style.css
几百个文件要并行：
find chapters -name '*.md' -print0 | xargs -0 -P 4 -I {} md-to-pdf '{}'
从较低并发开始，并在观察 CPU 与内存后逐步调高；每个工作进程都可能启动浏览器。
适用于书、技术报告、多文件入职文档。
pandoc chapter01.md chapter02.md chapter03.md -o book.pdf
坋：文件名顺序重要。Pandoc 按参数顺序拼接，不是字母顺序。谨慎使用 shell 展开：
pandoc chapter*.md -o book.pdf # alphabetical order, fine if you've zero-padded
生成目录：
pandoc chapter*.md --toc -o book.pdf
选择章节级结构，然后检查兼容的 PDF 引擎与模板：
pandoc chapter*.md --toc --top-level-division=chapter -o book.pdf
不想装 Pandoc，先拼接：
: > combined.md
for f in chapter*.md; do
cat "$f" >> combined.md
printf '\n\n<div style="page-break-before: always;"></div>\n\n' >> combined.md
done
md-to-pdf combined.md
插入的 HTML 是给这里的 HTML/Chromium 渲染路径使用的分页提示。请检查生成的 PDF；不同 Markdown 工具对原始 HTML 与打印 CSS 的处理并不完全相同。
一个在每次 push 到 main 时生成 PDF 的 GitHub Actions：
# .github/workflows/build-pdfs.yml
name: Build PDFs
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
- run: npm install -g md-to-pdf
- run: md-to-pdf 'docs/**/*.md'
- uses: actions/upload-artifact@v4
with:
name: pdfs
path: 'docs/**/*.pdf'
对 docs/ 下所有 Markdown 运行 md-to-pdf，PDF 作为构建产物上传。改成 tag push 触发，可以附加到 Release。
- 合并 PDF 中图片路径出错。 如果
chapter01.md引用了./images/a.png，拼接后路径会坏。要么重写为绝对路径，要么嵌入为 data URI，要么用 Pandoc 的--resource-path=.加查找路径。 - front-matter。 Pandoc 的后一个 YAML 元数据块会覆盖前面块中的同名字段。请统一整本文档的元数据，参见元数据规则。
- 页码。
--top-level-division=chapter改变标题层级类型，不控制页码策略。请在所选引擎与模板中配置分页，并检查 PDF，参见章节选项。 - Unicode / CJK 字体。 Pandoc 配 XeLaTeX 时应显式指定已安装字体，例如
--pdf-engine=xelatex -V mainfont:"Source Han Serif CN"。本地 Chromium 工具使用运行环境内的字体；托管渲染则要用实际字符测试服务端字体覆盖。 - 大批量任务的内存。 基于浏览器的转换会消耗较多资源。限制并发、监控内存，并把超大任务拆成可恢复的小批次。
- 一份文档 →
/markdown-to-pdf。 - 最多 15 个文件、统一设置 → 付费批量导出。
- 每次提交都重建 → CI 中运行 CLI。
- 按顺序合成一本书 → Pandoc 配合
--top-level-division=chapter --toc。 - 已有不同版式的 PDF → 用
pdfunite或qpdf合并。
更多各工具权衡看 Markdown 转 PDF 方法对比 与 PDF 中代码高亮深入。
如果已有独立 PDF，请根据保留内容的要求选择页面拼接工具或 PDF 重写工具：
# pdfunite (poppler-utils)
pdfunite chapter01.pdf chapter02.pdf chapter03.pdf book.pdf
# or qpdf
qpdf --empty --pages chapter*.pdf -- book.pdf
# or ghostscript
gs -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=book.pdf chapter*.pdf
页面拼接可用 pdfunite 或 qpdf。Ghostscript 的 pdfwrite 会生成新 PDF，不能视为无损拼接。处理后检查字体、链接、书签与图片压缩，详见设备文档。
可以在浏览器中批量导出吗？
多文件请打开批量导出：这是付费工具，每次最多接收 15 个 Markdown 文件，下载的 ZIP 中每个输入对应一个输出。Creator 每月含 20 次运行。选择 PDF 可得到多份独立 PDF；需要合成一份文档时使用 Pandoc。
批量模式里怎么保留代码高亮？
CLI 用 --stylesheet 传入的主题会被所有文件继承。一致使用同一主题。详见 Markdown 转 PDF 保留代码高亮。
单个合并 PDF 的上限是多少？
不存在统一的页数上限：内存、图片、字体、渲染器和 PDF 阅读器都会影响结果。应测试代表性大文档、设置 CI 超时，并把超大手册拆卷。
Pandoc 批量模式里保留 Mermaid 图表吗？
不要默认 Mermaid 代码围栏会自动变成图表，应检查所选渲染器。使用本地命令时，可先把图表导出成图片资源，或配置受支持的预处理。最终仍需检查 PDF 是否缺图或裁切。
选什么批量工具看你要出什么：
- ZIP 中的独立文件 → 付费批量导出。
- 脚本逐文件生成 PDF →
md-to-pdf '*.md'。 - 多章合成一本书 →
pandoc chapter*.md --toc -o book.pdf。 - 持续构建 → GitHub Actions + CLI。
- 已有 PDF →
pdfunite或qpdf。
偶尔处理一组文件时，可从浏览器批量工具开始，并检查 ZIP。它不会把多份 PDF 合并成一份文档。若交付物必须是一份 PDF，请使用上方按顺序输入的 Pandoc 命令，或用专用工具合并已有 PDF。
上文的产品限制与命令已按以下当前一手资料核对：
打开 MarkdownToImage 渲染 Markdown，再按工作流选择输出格式。批量自动化前，先用一份有代表性的文档验证。