将 PDF、Word (docx/doc)、Excel (xlsx/xls)、PPT (pptx/ppt)、图片等文件一键转换为 Markdown 或 JSON。 内置三大引擎:pandoc(DOCX 表格/Emoji/公式最强)、markitdown(微软开源,Excel/PPT/图片 OCR)、mammoth...
---
name: markitdown-file-converter
description: |
将 PDF、Word (docx/doc)、Excel (xlsx/xls)、PPT (pptx/ppt)、图片等文件一键转换为 Markdown 或 JSON。
内置三大引擎:pandoc(DOCX 表格/Emoji/公式最强)、markitdown(微软开源,Excel/PPT/图片 OCR)、mammoth(DOCX 纯文本兜底)。
首次使用自动安装全部依赖,无需手动配置。
支持数学公式 → LaTeX、表格 → Markdown 管道表格、图片自动提取并插入链接、base64 图片自动解码。
触发关键词:转markdown、转json、文档转换、pdf转md、word转markdown、docx转md、xlsx转md、
ppt转md、表格转md、图片转文字、ocr识别、批量转换文档。
---
# markitdown-file-converter
文档一键转 Markdown / JSON,整合 pandoc + markitdown + mammoth 三大引擎,首次使用自动安装依赖。
## 功能特性
- **依赖检查**:`python scripts/main.py --check` 检测环境依赖是否完整(pandoc、markitdown、mammoth、RapidOCR)
- **一键转换**:PDF / DOCX / DOC / XLSX / XLS / PPTX / PPT → Markdown 或 JSON
- **图片 OCR**:PNG / JPG / GIF / BMP → 文字识别(PaddleOCR Cloud 优先,RapidOCR 兜底)
- **公式 OCR**:PNG / JPG / GIF / BMP → LaTeX 公式识别(pix2tex/LaTeX-OCR)
- **PDF OCR**:扫描版 PDF → 自动转图片 + OCR(pdf2image + PaddleOCR Cloud/RapidOCR),逐页输出
- **数学公式**:自动转为 LaTeX 格式($E=mc^2$、$$\int$$)
- **表格保留**:pandoc grid table / simple table → 标准 Markdown 管道表格
- **图片提取**:DOCX / XLSX 中的嵌入图片自动提取到 `images/` 目录并插入 `` 链接
- **base64 解码**:自动将 base64 内嵌图片解码保存为文件
- **批量转换**:`--batch` 一次性转换整个目录
- **JSON 输出**:按标题分 section 输出结构化 JSON
- **进度反馈**:`-v/--verbose` 显示详细进度(PDF OCR 逐页输出)
- **超时控制**:`--timeout` 防止大文件卡死(默认 120 秒)
- **自动安装**:首次运行自动检测并安装缺少的依赖,零配置开箱即用
- **三引擎 OCR:RapidOCR(通用文字) + PaddleOCR Cloud(云端优先) + pix2tex(公式识别),自动降级
## 技能结构
```
markitdown-file-converter/
├── SKILL.md ← 本文件
└── scripts/
├── main.py ← 主入口
├── backends/ ← 转换后端
│ ├── pandoc.py
│ ├── markitdown.py
│ └── mammoth.py
├── ocr/ ← OCR 引擎
│ ├── engine.py ← OCR 调度器(智能引擎选择)
│ ├── rapidocr.py ← RapidOCR + pix2tex
│ └── selector.py ← 引擎选择策略
└── utils/ ← 工具模块
├── deps.py ← 依赖检测
├── deps_check.py ← 依赖检查工具
├── images.py ← 图片处理
├── table.py ← 表格美化
├── cleanup.py ← 输出清理(新增)
├── format_detector.py ← 格式检测(新增)
├── metadata.py ← 元数据提取(新增)
└── pptx_handler.py ← PPTX处理(新增)
```
## 支持的格式
| 类别 | 格式 | 后端 | 说明 |
|------|------|------|------|
| **Word** | .docx, .doc, .rtf, .odt | pandoc/markitdown/mammoth | 表格/Emoji/公式保留 |
| **Excel** | .xlsx, .xls, .csv, .ods | markitdown/pandoc | 数据+格式 |
| **PPT** | .pptx, .ppt, .odp | pandoc/markitdown | 幻灯片提取 |
| **PDF** | .pdf | markitdown/OCR | 文本提取+扫描识别 |
| **图片** | .png, .jpg, .gif, .bmp | OCR | 文字/公式识别 |
| **文本** | .md, .txt, .html | copy/pandoc | 直接复制/转换 |
| **数据** | .json, .xml, .yaml | copy/pandoc | 格式转换 |
| **电子书** | .epub, .mobi | pandoc | 电子书转换 |
| **音频** | .mp3, .wav | markitdown | 语音转录 |
## 依赖与安装
### 自动安装(推荐)
脚本在首次使用时自动检测并安装缺少的依赖,**无需手动操作**。
AI 调用时使用以下方式安装依赖(在当前 venv 环境中):
```bash
# 检测并安装 Python 包(mammoth, markitdown[all], beautifulsoup4)
uv pip install mammoth "markitdown[all]" beautifulsoup4 --python <venv_python_path>
# 检测并安装 pandoc(Windows)
winget install --accept-package-agreements --accept-source-agreements JohnMacFarlane.Pandoc
```
### 一键预装
```bash
python scripts/convert.py --install
```
该命令会依次安装 pandoc、markitdown、mammoth 三个后端。
### 各后端手动安装
| 后端 | 命令 | 说明 |
|------|------|------|
| **pandoc** | `winget install pandoc`(Win)/ `brew install pandoc`(Mac) | DOCX 表格/Emoji/公式保留最强 |
| **markitdown** | `pip install "markitdown[all]"` | 微软开源,Word/Excel/PPT/PDF |
| **rapidocr** | `pip install rapidocr-onnxruntime` | 图片 OCR(中英文识别),本地运行 |
| **pix2tex** | `pip install pix2tex` | LaTeX 公式 OCR(图片→LaTeX 代码) |
| **pdf2image** | `pip install pdf2image` + poppler | PDF OCR(扫描版 PDF → 图片 → OCR) |
| **mammoth** | `pip install mammoth` | DOCX → HTML → Markdown,纯文本兜底 |
> ⚠️ **PDF OCR 需要 poppler**:Windows 用户需安装 poppler(`winget install poppler` 或从 [Release 下载](https://github.com/oschwartz10612/poppler-windows/releases)),Mac 用户 `brew install poppler`。
> ⚠️ `markitdown[all]` 是一次性参数,不要拆成 `pip install markitdown` + `pip install all`。
## AI 使用指南
当用户请求文档转换时,按以下流程操作:
### 1. 确认环境
```bash
# 检查 Python venv 路径(示例)
# Windows: C:\Users\<user>\.qclaw\workspace\.uvenv\Scripts\python.exe
# macOS: ~/.qclaw/workspace/.uvenv/bin/python
```
### 2. 安装依赖(如尚未安装)
```bash
# Python 包
uv pip install mammoth "markitdown[all]" rapidocr-onnxruntime pix2tex pdf2image beautifulsoup4 --python <venv_python_path>
# poppler(PDF OCR 必需)
# Windows: winget install poppler
# Mac: brew install poppler
# Linux: sudo apt-get install poppler-utils
# pandoc(如未安装)
winget install pandoc
```
### 3. 执行转换
```bash
# 单文件转换(自动选择最佳后端)
python scripts/convert.py <input_file>
# 指定输出目录
python scripts/convert.py <input_file> -o <output_dir>
# 指定后端
python scripts/convert.py <input_file> -b pandoc
python scripts/convert.py <input_file> -b markitdown
python scripts/convert.py <input_file> -b mammoth
# PDF OCR(扫描版 PDF)
python scripts/convert.py scanned.pdf -b markitdown -v # -v 显示逐页进度
# 输出为 JSON(按标题分 section)
python scripts/convert.py <input_file> -f json
# 批量转换目录
python scripts/convert.py <input_dir> --batch -o <output_dir>
# 指定后端 + 批量
python scripts/convert.py <input_dir> --batch -b pandoc -o <output_dir>
# 大文件超时控制
python scripts/convert.py large.docx --timeout 300 # 5分钟超时
# 详细进度输出
python scripts/convert.py <input_file> -v
```
### 4. 读取输出
转换完成后,从输出目录读取 `.md` 或 `.json` 文件,将内容呈现给用户。
## CLI 完整参数
```
convert.py [input] [-f md|json] [-o <dir>] [-b pandoc|markitdown|mammoth|auto] [--batch] [--install] [-v] [--timeout SEC]
位置参数:
input 输入文件路径,或目录路径(配合 --batch)
可选参数:
-f, --format 输出格式:md(默认)/ json
-o, --output 输出目录(默认:<input_stem>_converted/)
-b, --backend 转换引擎(默认:auto):
auto 按文件类型自动选择最优后端
pandoc 全能王,DOCX 表格/Emoji/公式最强
markitdown 微软官方,Excel/PPT/PDF/图片 OCR
mammoth DOCX 纯文本兜底
--batch 批量模式:转换指定目录下所有支持的文件
--install 预装全部后端并退出
-v, --verbose 显示详细进度(PDF OCR 逐页输出)
--timeout SEC 单文件转换超时秒数(默认:120)
```
## 后端选择策略
### 自动选择逻辑(-b auto,默认)
按 `pandoc > markitdown > mammoth` 优先级,选择第一个已安装且支持该格式的后端。
如果所有后端均未安装,自动安装 markitdown。
| 文件类型 | 自动首选 | 原因 |
|---------|---------|------|
| `.docx` `.doc` | **pandoc** | 表格/Emoji/公式保留最佳 |
| `.xlsx` `.xls` | **markitdown** | pandoc/mammoth 不支持 Excel |
| `.pptx` `.ppt` | **markitdown** | markitdown PPT 支持更好 |
| `.pdf` | **pandoc** | 格式保留更完整 |
| `.png` `.jpg` ... | **markitdown** | 唯一支持 OCR 的后端 |
| `.html` `.csv` `.json` `.xml` `.zip` | **markitdown** | 唯一支持的后端 |
### 手动选择建议
- **DOCX 含复杂表格 / Emoji / 数学公式** → `-b pandoc`
- **Excel / PPT / 图片 OCR / 音频转录** → `-b markitdown`
- **DOCX 快速纯文本提取** → `-b mammoth`
- **不确定** → 不指定,使用默认 auto
## 三大后端对比
| 特性 | pandoc | markitdown | mammoth |
|------|--------|-----------|---------|
| PDF | ✅ | ✅ 基础 | ❌ |
| DOCX | ✅ 优秀 | ✅ 优秀 | ✅ 可用 |
| DOC | ✅ | ✅ | ✅ |
| XLSX / XLS | ❌ | ✅ 优秀 | ❌ |
| PPTX / PPT | ✅ 可用 | ✅ 优秀 | ❌ |
| 图片 OCR | ❌ | ✅ RapidOCR + PaddleOCR Cloud + pix2tex(三引擎,自动降级) | ❌ |
| PDF OCR(扫描版) | ❌ | ✅ pdf2image + RapidOCR 逐页识别 | ❌ |
| HTML / CSV / JSON / XML | ❌ | ✅ | ❌ |
| 音频转录 (.wav .mp3) | ❌ | ✅ | ❌ |
| 数学公式 → LaTeX | ✅ | ✅ | ✅ |
| 表格 → 管道表格 | ✅ grid→pipe | ✅ | ✅ |
| 图片自动提取 | ✅ | ✅ | ✅ |
| base64 图片解码 | ❌ | ✅ | ✅ |
| 纯 CPU 运行 | ✅ | ✅ | ✅ |
| 需联网下载 | ❌ | ❌ | ❌ |
## 输出结构
### Markdown 模式(默认)
```
<input_stem>_converted/
├── <input_stem>.md ← 转换后的 Markdown 文件
└── images/ ← 提取的图片(仅当源文件包含图片时生成)
├── image_0.png
├── image_1.jpg
└── ...
```
### JSON 模式(-f json)
与 Markdown 模式相同的目录结构,额外生成 JSON 文件:
```json
{
"source": "report.docx",
"sections": [
{
"heading": "第一章 概述",
"level": 1,
"content": "正文内容..."
},
{
"heading": "数据表格",
"level": 2,
"content": "| 姓名 | 成绩 |\n|------|------|\n| 小明 | 98 |"
}
]
}
```
## 注意事项
1. **pandoc 需加入 PATH**:winget 安装 pandoc 后,新开的终端会自动识别。如果脚本找不到 pandoc,请重启终端或手动将 `C:\Program Files\Pandoc` 加入 PATH。
2. **pandoc 表格处理**:pandoc 输出的 grid table(用 `---` 横线分隔的表格)会被脚本自动转换为标准 Markdown 管道表格格式。
3. **图片路径**:Markdown 中的图片使用相对路径 `images/image_0.png`,需要确保 `.md` 文件和 `images/` 目录保持相对位置不变。
4. **markitdown CLI 输出**:markitdown 默认输出 JSON(含 Unicode 转义),脚本已自动添加 `--format text` 参数以获取纯 Markdown。
5. **大型 PDF**:pandoc 对复杂排版(多栏、分栏、复杂页眉页脚)支持有限,转换效果可能不完美。
6. **OCR 质量**:使用 RapidOCR (ONNX Runtime) 作为图片文字识别引擎,支持中英文,对清晰截图效果优秀(准确率 >95%)。低分辨率、手写体、艺术字体效果有限。markitdown 原生图片转换依赖 LLM 描述(需配置 API key),未配置时自动降级到 RapidOCR。
7. **编码处理**:脚本强制使用 UTF-8 输出,确保中文等多语言内容正确显示。
8. **批量模式**:`--batch` 会为目录中每个文件创建独立子目录,避免文件名冲突。
9. **自动降级**:如果首选后端转换失败,脚本会自动尝试下一个可用后端(pandoc → markitdown → mammoth)。图片 OCR 的降级链为:markitdown LLM → RapidOCR → pix2tex(公式)→ 失败提示。
10. **PDF OCR 需要 poppler**:扫描版 PDF OCR 依赖 pdf2image + poppler。Windows 用户需安装 poppler(`winget install poppler` 或从 [GitHub Release](https://github.com/oschwartz10612/poppler-windows/releases) 下载并添加到 PATH)。Mac 用户 `brew install poppler`。
## Python API 使用示例
```python
from pathlib import Path
from convert import convert_file, batch_convert
# 单文件转换
md_path = convert_file(
Path("report.pdf"),
Path("output"),
fmt="md", # 或 "json"
backend="auto", # 或 "pandoc"/"markitdown"/"mammoth"
verbose=True, # 显示详细进度
timeout=120 # 超时秒数
)
print(f"输出文件: {md_path}")
# 批量转换
batch_convert(
Path("./docs"),
Path("./converted"),
fmt="md",
backend="auto",
verbose=False,
timeout=120
)
# PDF OCR(扫描版)
md_path = convert_file(
Path("scanned.pdf"),
Path("output"),
backend="markitdown", # PDF OCR 使用 markitdown 后端
verbose=True # 显示逐页进度
)
```
## 常见问题
**Q: 首次使用需要手动安装什么吗?**
A: 不需要。脚本会自动检测并安装缺少的依赖。如需提前安装,运行 `python scripts/convert.py --install`。
**Q: pandoc 和 markitdown 哪个更好?**
A: 视场景而定。DOCX 含表格/Emoji/公式推荐 pandoc;Excel/PPT/图片 OCR 推荐 markitdown。不确定时用默认 auto 即可。
**Q: 转换后表格丢失了?**
A: 已修复 pandoc grid table 中数据行间空行导致的表格丢失问题。如仍遇到,请指定 `-b markitdown` 或 `-b mammoth` 尝试其他后端。
**Q: 支持扫描版 PDF 吗?**
A: 支持。markitdown 后端现在支持扫描版 PDF OCR:PDF → 图片 → RapidOCR 逐页识别。需要安装 poppler(Windows: `winget install poppler`,Mac: `brew install poppler`)。使用 `-v` 参数可查看逐页进度。
**Q: PDF OCR 输出格式是什么?**
A: 按页面分节,每页一个 `## Page N` 标题,下方是该页 OCR 识别的文字。同时会在 `images/` 目录保存每页的截图(`page_1.png`、`page_2.png` 等)。
**Q: 图片 OCR 支持中文吗?**
A: 是的。使用 RapidOCR (rapidocr-onnxruntime) 作为 OCR 引擎,支持中英文混合识别,准确率通常 >95%(清晰截图)。markitdown 原生的图片转换依赖 LLM 描述(需配置 OpenAI API key),未配置时会自动降级到 RapidOCR。
**Q: 可以识别图片中的数学公式并转为 LaTeX 吗?**
A: 是的。使用 pix2tex (LaTeX-OCR) 作为公式识别引擎。自动降级策略:RapidOCR 先识别文字,如果结果很短(<15 字符)且不含中文,则尝试 pix2tex 识别公式。输出格式为 `$$\n...LaTeX...\n$$`。注意:pix2tex 对真实截图的公式识别效果较好,对纯文本图片(如照片)可能产生误识别。
**Q: 转换结果有错误怎么办?**
A: 如果发现转换结果存在错误,请直接指出错误内容并要求修正。Skill 会立即修正错误,同时自动记录本次错误信息到学习系统,避免后续重复出现同类问题。例如:"表格第三行数据丢失了,请修复"或"公式识别错误,应该是 E=mc² 不是 E=mc2"。
**Q: 输出 JSON 的 section 是怎么分的?**
A: 按 Markdown 标题(`#` ~ `######`)分割,每个标题及其下内容组成一个 section。未在标题下的内容归入 `heading: null` 的 section。
### PaddleOCR Cloud (可选,默认已配置)
如需使用 PaddleOCR 云端增强识别,需配置环境变量:
```bash
# 设置 API URL(文档版面分析)⚠️ 请替换为你自己申请的接口地址
set PADDLEOCR_DOC_PARSING_API_URL=https://c474r929pea0qa6c.aistudio-app.com/layout-parsing
# 设置 Access Token ⚠️ 请替换为你自己的 Token
set PADDLEOCR_ACCESS_TOKEN=86b3f40ddd719dad76e496472d341f1ba89085e3
```
> ⚠️ **注意**:示例中的 API URL 和 Token 仅供测试。如需生产环境使用,请前往 [百度智能云](https://login.bce.baidu.com/) 或 [AI Studio](https://aistudio.baidu.com/) 申请自己的 PaddleOCR Cloud 服务。
配置后,图片 OCR 会优先使用 PaddleOCR Cloud 作为第一引擎(若失败则自动降级到 RapidOCR)。don't have the plugin yet? install it then click "run inline in claude" again.