Markdown To Image | 批量把多个 Markdown 文件转换为 PDF 的几种方法

30 秒给答案

三种常见批量任务：

一个 Markdown → 一个 PDF，重复多个文件：md-to-pdf *.md（npm CLI）。
多个 Markdown → 一个合并 PDF（一本书、多章报告）：pandoc chapter*.md -o book.pdf。
多个 Markdown → 每次提交输出一份 PDF：GitHub Actions + npm CLI。

浏览器版 /markdown-to-pdf 是单文件的；批量任务需要 CLI。本文走一遍三个场景，有可复制粘贴的命令与常见陷阱。

场景 1 —— N → N（一个 Markdown 一个 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 与内存后逐步调高；每个工作进程都可能启动浏览器。

场景 2 —— N → 1（多个 `.md` 合成一个 PDF）

适用于书、技术报告、多文件入职文档。

Pandoc（适合有序章节）

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

章节间加 LaTeX 分页：

pandoc chapter*.md --toc --top-level-division=chapter -o book.pdf

拼接+转换（适用任何 Markdown→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

<div> 在章之间插入分页。初级但可靠。

场景 3 —— CI/CD（每次提交生 PDF）

一个在每次 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 冲突。 每个 .md 可能有自己的 YAML front-matter。Pandoc 取第一个；md-to-pdf 逐文件模式读各自的。如果冲突，拼接前先去掉。
页码在章间重置。 Pandoc 用 --top-level-division=chapter 处理；拼接路径不会，页码连续（书里通常这个是你要的）。
Unicode / CJK 字体。 Pandoc 配 XeLaTeX 时应显式指定已安装字体，例如 --pdf-engine=xelatex -V mainfont:"Source Han Serif CN"。本地 Chromium 工具使用运行环境内的字体；托管渲染则要用实际字符测试服务端字体覆盖。
大批量任务的内存。 基于浏览器的转换会消耗较多资源。限制并发、监控内存，并把超大任务拆成可恢复的小批次。

什么时候用网页工具 vs CLI

偶尔单文件 → /markdown-to-pdf。打开页面比装 npm 快。
同一模板、十几个文件、一次性 → md-to-pdf CLI。
同一模板、多文件、每次提交 → CI 里的 CLI。
书、报告、多章节 → Pandoc + --top-level-division=chapter --toc。
每章不同模板 → 先逐文件生 PDF（场景 1），后用 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

合并不会重新渲染，因此可保留原有内容质量；耗时取决于文件数量、大小、存储与所选工具。

常见问题

能用网页 /markdown-to-pdf 做批量吗？

网页工具是单文件的。批量请用 CLI；一次性请用网页。有人跑完 CLI 后手工打包一下。

批量模式里怎么保留代码高亮？

CLI 用 --stylesheet 传入的主题会被所有文件继承。一致使用同一主题。详见 Markdown 转 PDF 保留代码高亮。

单个合并 PDF 的上限是多少？

不存在统一的页数上限：内存、图片、字体、渲染器和 PDF 阅读器都会影响结果。应测试代表性大文档、设置 CI 超时，并把超大手册拆卷。

Pandoc 批量模式里保留 Mermaid 图表吗？

不原生支持。需要 pandoc-mermaid-filter 或者先把 Mermaid 转 SVG 再引用。npm CLI 批量也需要 markdown-it Mermaid 插件。

写在最后

选什么批量工具看你要出什么：

1对 1 PDF → md-to-pdf '*.md'
多对 1 书 → pandoc chapter*.md --toc -o book.pdf
持续构建 → GitHub Actions + npm CLI
合并现有 PDF → pdfunite 或 qpdf

如果是一次性批量且以上都没装，摩擦最小路径是：用网页 /markdown-to-pdf 逐文件跳标签页跱一遍，最后 pdfunite 拼上。

本次更新核对的资料

上文的产品限制与命令已按以下当前一手资料核对：

现在试一下

打开 MarkdownToImage 渲染 Markdown，再按工作流选择输出格式。批量自动化前，先用一份有代表性的文档验证。