Markdown 转 PDF 工具

两种方式将 Markdown 转换为 PDF：

• 批量转换：将每个 .md 文件转换为对应的 .pdf 文件
• 合并转换：根据 _sidebar.md 将多个文档合并为单个 PDF，包含目录、分隔页和 PDF 书签

安装

# 使用 npm 全局安装
npm install -g md-to-pdf-converter
# 或使用 pnpm
pnpm add -g md-to-pdf-converter
# 或作为开发依赖本地安装
npm install -D md-to-pdf-converter

本工具内置 Puppeteer。如果您希望使用系统的 Chrome/Chromium，请设置 PUPPETEER_EXECUTABLE_PATH 环境变量或使用 --chrome 参数。

命令行工具

本包提供两个命令行工具：

• mlpdf：根据 _sidebar.md 合并 Markdown 文件为单个 PDF，包含可点击目录和 PDF 书签
• md2pdf-batch：批量转换当前目录下的所有 Markdown 文件为 PDF

根据 _sidebar.md 合并文档 (mlpdf)

# 基本用法 - 在包含 _sidebar.md 的文档根目录运行
mlpdf

# 带选项的使用方法
mlpdf \
  --sidebar _sidebar.md \
  --out 输出文档.pdf \
  --style styles/自定义.css \
  --chrome "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --fast-bookmarks \
  --no-clean

选项说明

• -s, --sidebar <文件> - 指定 _sidebar.md 路径 (默认: _sidebar.md)
• --toc - 启用可点击目录页 (默认启用)
• --no-toc - 禁用目录页
• -o, --out <文件> - 输出 PDF 路径 (默认: 文档合并_by_sidebar.pdf)
• --chrome <路径> - Chrome/Chromium 可执行文件路径 (备选: 环境变量 PUPPETEER_EXECUTABLE_PATH)
• --style <文件> - 自定义 CSS 样式表路径 (默认: 内置 styles/md-pdf.css)
• --fast-bookmarks - 跳过精确的 H2 书签页码计算，加快处理速度
• --no-clean - 不清理 md2pdf-batch 生成的 PDF 临时文件
• -h, --help - 显示帮助信息

_sidebar.md 格式

• 使用 - [标题](路径/文件.md) 格式的行
• 每个层级缩进 2 个空格；深度 1 和 2 会生成 PDF 书签
• 示例：

  - [介绍](intro.md)
    - [快速开始](intro/getting-started.md)
  - [高级主题](advanced.md)
    - [配置](advanced/config.md)
    - [性能优化](advanced/performance.md)

输出结果

生成单个 PDF 文件 (默认 文档合并_by_sidebar.pdf)，包含：

• 可点击的目录
• 深度 1 章节的分隔页
• 侧边书签/大纲，便于导航
• 章节间自动分页

批量转换所有 Markdown 文件 (md2pdf-batch)

# 基本用法 - 递归转换当前目录下的所有 .md 文件
md2pdf-batch

# 带选项的使用方法
md2pdf-batch \
  --style styles/自定义.css \
  --chrome "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

选项说明

• --style <文件> - 自定义 CSS 样式表路径 (默认: 内置 styles/md-pdf.css)
• --chrome <路径> - Chrome/Chromium 可执行文件路径 (备选: 环境变量 PUPPETEER_EXECUTABLE_PATH)
• -h, --help - 显示帮助信息

编程方式使用

本包主要作为命令行工具使用。您也可以通过 node 直接执行脚本：

node scripts/generate_pdfs.mjs --style custom.css
node scripts/merge_from_sidebar.mjs --sidebar _sidebar.md --out out.pdf --fast-bookmarks

CSS 样式定制

默认样式表：styles/md-pdf.css (A4 页面、边距、代码/表格样式、章节分隔页)。

您可以通过 --style 参数提供自定义样式：

• 绝对路径直接使用
• 相对路径从当前工作目录解析
• 默认内置样式表提供：
  • A4 页面格式和适当边距
  • 优化的中英文字体栈
  • 代码块和表格样式
  • 章节分隔页设计
  • 适合打印的颜色和间距

性能优化建议

• 对于大型文档使用 --fast-bookmarks 选项，牺牲书签精度换取速度
• 设置 PUPPETEER_EXECUTABLE_PATH 或使用 --chrome 参数使用系统 Chrome 而非内置 Chromium
• 对于超大文档集，考虑分批处理

高级功能

错误处理

• _sidebar.md 中缺失的文件会自动跳过并显示警告
• 单个文件转换失败不会停止批量处理
• 详细的错误信息帮助识别问题

路径处理

• 相对引用的图片和链接路径在合并时自动重写，确保从项目根目录正常工作
• 保留跨文档引用
• 支持 Markdown 和 HTML 图片语法

书签生成

• 精确模式 (默认)：渲染每个 H2 章节以计算准确页面位置
• 快速模式 (--fast-bookmarks)：使用近似计算加快处理速度
• 支持中文/Unicode 字符的书签名称
• 两级层次结构：H1 章节和 H2 子章节

注意事项

• 推荐使用 Node.js >= 18
• 批量处理时会排除常见开发目录 (node_modules, .git 等)
• 生成的 PDF 包含适当的元数据，针对打印进行了优化
• --no-clean 选项可防止在合并模式下自动清理单文件 PDF

输出示例

mlpdf 输出示例：

🚀 开始生成 PDF 文档...
📚 发现 15 个 Markdown 文件待处理

📖 第 1/4 步: 读取和处理 Markdown 文件...
📊 [██████████████████████████████] 100% (15/15) - 正在处理: API 参考

📄 第 2/4 步: 计算页面数量...
📑 目录将占用 2 页
🎯 精确模式: 正在渲染 15 个章节...
📊 [██████████████████████████████] 100% (15/15) - 高级主题 (8页, 2个二级标题)

🔖 第 3/4 步: 计算书签并生成最终 PDF...
📋 文档将包含 125 页，45 个书签
🖨️  正在渲染最终 PDF...

✨ 第 4/4 步: 添加书签并完成最终处理...
📌 正在添加 PDF 书签...
🧹 正在清理临时文件...

🎉 生成完成！输出文件: documentation.pdf
   📄 总共 125 页，包含 45 个书签
   📋 目录已保存至: 文档合并_目录.txt
   🔗 PDF 包含可点击目录、章节分隔页和侧边书签导航

md2pdf-batch 输出示例：

🚀 发现 23 个 Markdown 文件待转换

📝 正在转换 docs/intro.md -> docs/intro.pdf
✅ 转换完成: docs/intro.pdf

📊 转换进度: 15/23 (65%) - ✅ 成功: 14 ❌ 失败: 1

🎉 批量转换完成！✅ 成功 22 个，❌ 失败 1 个

许可证

MIT