文档转换技能 (convert-markdown)

概述

MarkItDown 是 Microsoft 开发的多功能文档转换工具，能够将各种文件格式高质量转换为 Markdown 格式。本技能提供完整的文档处理工作流，包括：

• 多格式支持：PDF、DOCX、PPTX、XLSX、图片、音频、HTML、CSV、JSON、ZIP、EPub、YouTube URLs 等
• 结构化保留：保持标题、列表、表格、链接等重要文档结构
• 批量处理：支持目录递归处理和批量转换
• OCR 能力：图片和扫描 PDF 的文本识别
• 音频转录：音频文件的语音转文本
• 可扩展性：可选依赖组按需安装，适配不同需求场景

快速开始

1. 环境准备

确保已安装 Python 3.10 或更高版本。建议使用虚拟环境：

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

2. 安装 MarkItDown

# 安装完整功能（推荐）
pip install 'markitdown[all]'

# 或按需安装特定格式支持
pip install 'markitdown[pdf,docx,pptx]'

可选依赖组说明：

• [all] - 所有格式支持（PDF、Office、图片、音频、HTML 等）
• [pdf] - PDF 处理（包含 OCR）
• [docx] - Word 文档
• [pptx] - PowerPoint
• [xlsx] - Excel
• [image] - 图片 EXIF 和 OCR
• [audio] - 音频转录
• [html] - HTML 转换
• [ytdlp] - YouTube 下载

3. 基本使用

NPX CLI 方式（推荐）

本技能提供 NPX CLI 工具，可直接通过 npx 命令调用：

# 查看帮助
npx convert-markdown

# 转换单个文件
npx convert-markdown convert --input document.pdf --output document.md

# 转换目录
npx convert-markdown convert --input ./docs --output ./markdown

# 批量转换（指定格式）
npx convert-markdown batch --source ./docs --target ./markdown --include .pdf,.docx

# 覆盖已存在文件
npx convert-markdown convert --input document.pdf --output document.md --overwrite

CLI 命令说明：

MarkItDown 命令行方式

转换单个文件：

markitdown document.pdf > document.md
markitdown presentation.pptx -o slides.md

批量处理目录：

# 转换当前目录所有支持文件
markitdown *.pdf *.docx *.pptx

# 递归处理子目录
markitdown ./docs/ --recursive

# 输出到指定目录
markitdown ./source/ -o ./output/

Python API 方式

from markitdown import MarkItDown

# 创建转换器实例
md = MarkItDown()

# 转换文件
result = md.convert("document.pdf")
print(result.text_content)

# 转换并保存
with open("output.md", "w", encoding="utf-8") as f:
    f.write(result.text_content)

常见任务

任务 1: 批量转换知识库文档

将大量文档批量转换为 Markdown 格式，便于建立搜索索引：

# 创建输出目录
mkdir converted_docs

# 批量转换并保存
markitdown ./source_documents/ --recursive -o ./converted_docs/

任务 2: 处理扫描版 PDF

对于扫描的 PDF 文件，需要安装 OCR 依赖：

pip install 'markitdown[pdf]'  # 包含 OCR 功能
markitdown scanned_document.pdf -o text.md

任务 3: 提取表格数据

MarkItDown 能够保留原始表格结构：

markitdown financial_report.xlsx > report.md
# 输出中的表格将保持 Markdown 表格格式

任务 4: 处理多媒体文件

支持图片 OCR 和音频转录：

# 提取图片中的文字
markitdown screenshot.png > extracted_text.md

# 转换音频为文字记录
markitdown podcast.mp3 > transcript.md

任务 5: 集成到自动化流程

在 Python 脚本中使用：

from pathlib import Path
from markitdown import MarkItDown

def convert_directory(input_dir, o...