md-to-pdf

Category: Docs & Knowledge | Uploader: 523926245 | Downloads: 0 | Version: v2.0（Latest）
将Markdown文件转换为PDF文档，支持中英文显示，采用puppeteer渲染保证显示效果
Changelog: 更新chrome环境变量设置
Directory Structure

Current level: md-to-pdf/
📄 SKILL.md 6.8 KB
📄 verify_pdf.py 5.3 KB
SKILL.md

---
name: md-to-pdf
description: 将Markdown文件转换为PDF文档，支持中英文显示，采用puppeteer渲染保证显示效果
license: MIT
compatibility: opencode
metadata:
  audience: developers
  category: utility
---

# Markdown 转 PDF 工具

## 什么情况下使用

当需要将Markdown文档转换为PDF文件时使用本技能，特别适合：
- 转换技术文档为PDF格式
- 生成中英文混排的PDF报告
- 导出项目文档为可分享的PDF文件

## 前置要求

本技能依赖以下环境：
1. **Node.js** - 版本 >= 16.15.0
2. **pnpm** 或 **npm** - 包管理器
3. **Chrome/Chromium** - md2pdf 使用 puppeteer 进行渲染

如果尚未安装 `@mofanx/md2pdf`，请先安装：

```bash
npm install -g @mofanx/md2pdf
# 或
pnpm add -g @mofanx/md2pdf
```

## 使用场景

### 1. 单文件转换

将单个 Markdown 文件转换为 PDF：

```
转换 test.md 为 test.pdf
```

命令行：
```bash
md2pdf test.md test.pdf
```

### 2. 批量转换目录

将整个目录下的所有 Markdown 文件转换为 PDF：

```
将 docs 目录下的所有 md 文件转为 pdf
```

命令行：
```bash
md2pdf ./docs ./out
```

### 3. 指定输出目录

```
将 D:\Study\readme.md 转换为 PDF 并输出到 D:\Study\output\
```

命令行：
```bash
md2pdf D:/Study/readme.md D:/Study/output/readme.pdf
```

## 执行步骤

### 第一步：检查环境

确认 md2pdf 已安装：

```bash
md2pdf --version
```

如果未安装，先执行安装：
```bash
npm install -g @mofanx/md2pdf
```

### 第二步：执行转换（重要：先设置 Chrome 路径）

**Windows 用户特别说明**：

由于 md2pdf 依赖 Puppeteer 渲染 PDF，首次使用需要先配置 Chrome 路径。使用以下命令：

```bash
# 方法1：每次转换前设置环境变量（MINGW/Git Bash）
export PUPPETEER_EXECUTABLE_PATH="/c/Program Files/Google/Chrome/Application/chrome.exe"
md2pdf <输入文件.md> <输出文件.pdf>

# 方法2：使用简化命令（推荐添加到 shell 配置）
alias md2pdf='export PUPPETEER_EXECUTABLE_PATH="/c/Program Files/Google/Chrome/Application/chrome.exe" && md2pdf'
# 然后直接使用
md2pdf test.md test.pdf
```

**单文件转换**：
```bash
md2pdf test.md test.pdf
```

**批量转换**：
```bash
md2pdf ./docs ./out
```

### 第三步：验证 PDF 内容

转换完成后，需要验证 PDF 内容是否正确显示：

1. **检查文件是否生成**：
   ```bash
   ls -la <输出文件.pdf>
   ```

2. **验证 PDF 可读性**（使用 pdftotext 或类似工具）：
   ```bash
   # 安装 poppler-utils (如果需要)
   # Windows: choco install poppler
   # Linux: apt install poppler-utils
   
   pdftotext <输出文件.pdf> -  # 输出文本内容到终端
   ```

3. **检查中文显示**：
   - 确认输出的文本中包含正确的中文字符
   - 如果出现方块或乱码，说明字体渲染有问题

4. **使用 Python 验证**（推荐）：
   ```python
   import subprocess
   
   # 使用 pdfminer 提取文本
   from pdfminer.high_level import extract_text
   
   text = extract_text('output.pdf')
   print(text)  # 检查中英文是否正常显示
   ```

## 字体说明

md2pdf 已内置中文字体支持，但如果遇到字体问题：

1. **Windows** - 确保系统已安装以下字体：
   - 微软雅黑 (Microsoft YaHei)
   - 宋体 (SimSun)
   - 黑体 (SimHei)

2. **Linux** - 安装 CJK 字体：
   ```bash
   sudo apt install fonts-noto-cjk
   ```

3. **macOS** - 通常已预装中文字体

## 常见问题

### Q: 转换失败，提示找不到 Chrome？

A: md2pdf 需要 Chrome/Chromium 浏览器。有两种解决方式：

**方式一：使用环境变量指定系统 Chrome（推荐）**

```bash
# Windows MINGW/Git Bash 环境
export PUPPETEER_EXECUTABLE_PATH="/c/Program Files/Google/Chrome/Application/chrome.exe"
md2pdf test.md test.pdf

# Windows PowerShell 环境
$env:PUPPETEER_EXECUTABLE_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"
md2pdf test.md test.pdf

# Linux/macOS 环境
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/google-chrome"
md2pdf test.md test.pdf
```

**方式二：自动下载 Chromium**

```bash
# 使用 puppeteer 自动下载
npx puppeteer browsers install chrome
```

### Q: 中文显示为方块？

A: 字体问题。确保系统安装了中文字体，或使用自定义字体配置。

### Q: 图片无法显示？

A: md2pdf 已自动将本地图片转为 base64 嵌入 PDF。如仍有问题，检查图片路径是否为绝对路径。

### Q: 代码块显示不全？

A: md2pdf 已优化代码块样式，自动换行。如仍有问题，可调整 PDF 边距。

## 输出格式

完成后报告：
- 转换输入文件路径
- 转换输出文件路径
- PDF 文件大小
- 验证结果（PDF是否可读、内容是否正确）

**推荐验证命令**：
```bash
# 使用内置验证脚本
python ~/.config/opencode/skills/md-to-pdf/verify_pdf.py <PDF文件路径>
```

---

## Windows 一键转换命令

为了避免每次输入环境变量，可以创建一个快捷命令：

### 方法1：添加到 .bashrc（推荐）

```bash
# 将以下内容添加到 ~/.bashrc 或 ~/.zshrc
md2pdf() {
    export PUPPETEER_EXECUTABLE_PATH="/c/Program Files/Google/Chrome/Application/chrome.exe"
    command md2pdf "$@"
}

# 然后重新加载配置
source ~/.bashrc
```

### 方法2：创建批处理文件

创建 `md2pdf.bat` 放在 PATH 中：
```batch
@echo off
set PUPPETEER_EXECUTABLE_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe
md2pdf %*
```

---

## 故障排除快速检查表

- [ ] md2pdf 已安装：`md2pdf --version`
- [ ] Chrome 路径正确：检查路径是否存在
- [ ] 环境变量已设置：`echo $PUPPETEER_EXECUTABLE_PATH`
- [ ] 转换时无报错：查看错误信息定位问题

---

## 验证脚本使用说明

本技能附带了一个 Python 验证脚本 `verify_pdf.py`，用于验证转换后的 PDF 内容是否正确。

### 安装验证依赖

```bash
# 建议安装以下依赖（至少选择一个）
pip install pdfminer.six pypdf
```

### 使用方法

```bash
# 基本用法
python ~/.config/opencode/skills/md-to-pdf/verify_pdf.py <PDF文件路径>

# 示例
python ~/.config/opencode/skills/md-to-pdf/verify_pdf.py test.pdf
```

### 验证内容

脚本会检查：
1. PDF 文件是否存在
2. PDF 文件是否有内容
3. 是否包含中文字符
4. 是否包含英文字母
5. 提取文本预览（前500字符）

### 输出示例

```
==================================================
PDF 验证报告
==================================================
文件路径: test.pdf
文件存在: ✓ 是
有文本内容: ✓ 是
包含中文: ✓ 是
包含英文: ✓ 是
验证通过: ✓ 是
==================================================
```

### 常见问题

- **导入错误**: 运行 `pip install pdfminer.six pypdf` 安装依赖
- **中文检测失败**: 检查 PDF 是否正确嵌入字体
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
md-to-pdf

Directory Structure

SKILL.md

Report

Notice
