JSPM

md-to-pdf-converter

1.2.1
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 9
    • Score
      100M100P100Q72657F

    Convert Markdown files (batch) or merge via _sidebar.md to PDF with Puppeteer and pdf-lib bookmarks.

    Package Exports

      This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (md-to-pdf-converter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

      Readme

      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