md-to-pdf

Markdown 转 PDF 转换器

将 Markdown 文件转换为采用专业样式的 PDF，完整呈现 Mermaid 图表、LaTeX 数学公式（通过 KaTeX）、表格、语法高亮代码块以及所有标准 Markdown 功能。

架构

Input .md file
     │
     ├─ Step 1: Extract ```mermaid blocks → render to SVG via mmdc (Mermaid CLI + Puppeteer)
     │          Replace mermaid code blocks with inline <svg> in the markdown source
     │
     ├─ Step 2: pandoc converts modified markdown → standalone HTML5
     │          (--katex flag preserves raw LaTeX in <span class="math ..."> elements)
     │
     ├─ Step 3: Node.js KaTeX server-side rendering
     │          Replaces math spans with fully rendered KaTeX HTML (no client-side JS needed)
     │
     ├─ Step 4: CSS injection
     │          KaTeX stylesheet (with local font paths) + professional document styles + optional custom CSS
     │
     └─ Step 5: Playwright (headless Chromium) prints final HTML → PDF
                 ↓
           Output .pdf file

支持的功能

功能	渲染引擎	备注
Mermaid 图表	通过 Puppeteer 使用 mmdc（mermaid-cli）	流程图、时序图、类图、状态图、ER 图、甘特图、饼图、Git 图、思维导图等
LaTeX 数学公式（行内）	KaTeX 服务端	$E=mc^2$ 语法
LaTeX 数学公式（显示）	KaTeX 服务端	$$\int f(x) dx$$ 语法
表格	pandoc + CSS	全面支持 GFM 管道表格，并采用专业样式
代码块	pandoc + CSS	通过 pandoc 实现语法高亮，采用等宽字体样式
图片	pandoc + Playwright	本地 file:// 和远程 https:// 图片
链接	pandoc	渲染为带样式的文本
列表 / 引用块	pandoc	有序、无序、嵌套列表及引用块
YAML frontmatter	pandoc	将 title 用作 PDF 标题元数据
脚注	pandoc + CSS	[^1] 语法，呈现在页面底部
定义列表	pandoc + CSS	术语 / 定义对
删除线	pandoc	~~deleted~~ 语法
水平分隔线	pandoc + CSS	--- 渲染为带样式的分隔线

前置条件

首次使用前运行设置检查器：

bash <SKILL_DIR>/scripts/setup.sh

此操作会验证所有必需工具是否已安装并正常运行。标准的 Claude 电脑操作环境已预装所有内容。对于其他环境，所需组件如下：

依赖项	用途	安装
pandoc	Markdown → HTML	apt install pandoc
mmdc (@mermaid-js/mermaid-cli)	Mermaid → SVG	npm install -g @mermaid-js/mermaid-cli
katex (npm)	LaTeX → HTML	npm install -g katex
playwright (Python)	HTML → PDF	pip install playwright && playwright install chromium
Chrome/Chromium	浏览器引擎	由 Playwright 或 Puppeteer 安装

用法

基本用法

python3 <SKILL_DIR>/scripts/md_to_pdf.py <input.md> <output.pdf>

完整选项

python3 <SKILL_DIR>/scripts/md_to_pdf.py <input.md> <output.pdf> [OPTIONS]

参数	默认值	说明
input	(必需)	输入 Markdown 文件的路径
output	(必需)	输出 PDF 文件的路径
--format	A4	页面尺寸：A4、Letter、Legal、A3
--margin	0.75in	页边距——单个值（统一设置）或 top,right,bottom,left
--no-mermaid	false	跳过 Mermaid 渲染（保留原始代码块）
--no-math	false	跳过 KaTeX 数学公式渲染
--css	(无)	要叠加在默认样式之上的自定义 CSS 文件路径
--landscape	false	横向排版
--header-footer	false	在页脚显示页码（当前页 / 总页数）

示例

# Standard A4 conversion
python3 scripts/md_to_pdf.py report.md report.pdf

# US Letter, landscape, with page numbers
python3 scripts/md_to_pdf.py report.md report.pdf --format Letter --landscape --header-footer

# Custom margins and extra CSS
python3 scripts/md_to_pdf.py report.md report.pdf --margin "1in,0.75in,1in,0.75in" --css brand.css

# Plain mode (skip Mermaid + math for speed)
python3 scripts/md_to_pdf.py report.md report.pdf --no-mermaid --no-math

Claude 工作流

当用户要求将 Markdown 转换为 PDF 时：

1. 确定输入文件路径（上传的文件或用户指定的路径）
2. 如果这是本次会话中的首次使用，则运行设置检查：

   bash <SKILL_DIR>/scripts/setup.sh
   

3. 执行转换：

   python3 <SKILL_DIR>/scripts/md_to_pdf.py /path/to/input.md /path/to/output.pdf [OPTIONS]
   

4. 将输出文件提供给用户

故障处理

现象	可能原因	解决方法
Mermaid 步骤中出现 "mmdc FAILED"	Mermaid 语法无效	检查图表语法；mmdc stderr 中包含解析错误
PDF 中显示原始 LaTeX	KaTeX 无法解析表达式	检查 LaTeX 语法；KaTeX 会优雅地回退
出现 "No Chrome binary found"	缺少 Puppeteer/Playwright Chromium	运行 playwright install chromium
图表空白或缺失	SVG 过大或过于复杂	尝试使用 --no-mermaid，并单独渲染图表

自定义

自定义 CSS

传入 --css path/to/custom.css，即可在默认样式之后注入样式。自定义规则优先级更高。

示例——深色主题覆盖：

body {
  background: #1a1a2e;
  color: #e0e0e0;
}
h1,
h2,
h3 {
  color: #e0e0e0;
  border-color: #444;
}
table th {
  background: #2a2a4a;
}
pre {
  background: #0d0d1a;
  border-color: #333;
}

Mermaid 主题设置

将 MERMAID_CONFIG 环境变量设为 JSON 配置文件：

MERMAID_CONFIG=/path/to/.mermaidrc python3 scripts/md_to_pdf.py input.md output.pdf

.mermaidrc 示例：

{
  "theme": "neutral",
  "themeVariables": {
    "primaryColor": "#e1f5fe",
    "lineColor": "#333"
  }
}

限制

• Mermaid 图表渲染需要通过网络访问基于 CDN 的 mmdc，或在本地安装 @mermaid-js/mermaid-cli。离线环境必须使用 --no-mermaid 并单独渲染图表。
• 大型文档（100 页以上或包含许多高分辨率图像）可能会触及 Playwright 的内存限制。请将文档拆分成多个输入文件，再合并生成的 PDF。
• 自定义 CSS 在不同 PDF 查看器中的渲染效果可能不完全一致——布局由渲染时的 Chromium 决定；Acrobat Reader、Preview 和浏览器对同一个 PDF 的显示效果可能不同。
• 分页符需要显式的 CSS 标记（page-break-before: always 或 break-before: page），或在源文件中手动添加 <div style="page-break-before: always">。Pandoc 不会根据标题结构自动推断分页符。
• KaTeX 覆盖范围很广，但并不完整——KaTeX 支持列表中没有的冷门 LaTeX 宏或宏包将无法渲染，并回退为原始 LaTeX。

文件结构

md-to-pdf/
├── SKILL.md                    # This file — skill documentation
├── LICENSE.txt                 # MIT license
├── README.md                   # Distribution / standalone usage docs
├── scripts/
│   ├── md_to_pdf.py            # Main conversion pipeline (Python)
│   ├── katex_render.js         # Server-side KaTeX math renderer (Node.js)
│   └── setup.sh                # Dependency checker / installer
└── tests/
    └── test_document.md        # Comprehensive test covering all features