文档整理技能 (convert-markdown)

文档转换技能 (convert-markdown) 概述

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

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

• 环境准备

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

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

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

• 安装 MarkItDown

# 或按需安装特定格式支持 pip 安装 '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 下载

• 基本使用

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

# 查看帮助 npx convert-markdown

# 转换单个文件 npx convert-markdown convert --输入 document.pdf --输出 document.md

# 转换目录 npx convert-markdown convert --输入 ./docs --输出 ./markdown

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

# 覆盖已存在文件 npx convert-markdown convert --输入 document.pdf --输出 document.md --overwrite

命令行工具 命令说明：

命令 说明 参数 convert 转换文件或目录 --输入, --输出, --overwrite batch 批量转换目录 --source, --tar获取, --include, --exclude MarkItDown 命令行方式

转换单个文件：

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

批量处理目录：

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

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

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

Python API 方式 from markitdown 导入 MarkItDown

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

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

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

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

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

# 创建输出目录 mkdir converted_docs

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

任务 2: 处理扫描版 PDF

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

pip 安装 'markitdown[pdf]' # 包含 OCR 功能 markitdown 扫描ned_document.pdf -o text.md

任务 3: 提取表格数据

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

markitdown financial_报告.xlsx > 报告.md # 输出中的表格将保持 Markdown 表格格式

任务 4: 处理多媒体文件

支持图片 OCR 和音频转录：

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

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

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

在 Python 脚本中使用：

from pathlib 导入 Path from markitdown 导入 MarkItDown

def convert_directory(输入_dir, 输出_dir): """批量转换目录中的所有支持文件""" md = MarkItDown() 输入_path = Path(输入_dir) 输出_path = Path(输出_dir) 输出_path.mkdir(exist_ok=True)

for file_path in 输入_path.rglob(""): if file_path.is_file(): try: 结果 = md.convert(str(file_path)) rel_path = file_path.relative_to(输入_path) 输出_file = 输出_path / rel_path.with_suffix('.md') 输出_file.parent.mkdir(parents=True, exist_ok=True) 输出_file.write_text(结果.text_content, encoding='utf-8') print(f"✓ {file_path} -> {输出_file}") except 异常 as e: print(f"✗ {file_path}: {e}")

# 使用示例 convert_directory("./raw_docs/", "./markdown_docs/")

高级配置 自定义转换选项 from markitdown 导入 MarkItDown, 流转换器

# 使用流式转换（处理大文件） with open("large_file.pdf", "rb") as f: md = MarkItDown() 结果 = md.convert_流(f) print(结果.text_content)

插件系统

MarkItDown 支持自定义转换器插件。如需扩展支持特殊格式，可开发自定义 Document转换器：

from markitdown 导入 Document转换器

class Custom转换器(Document转换器): def convert(self, file_流, **kwargs): # 实现自定义转换逻辑 pass

# 注册插件 md = MarkItDown(转换器s=[Custom转换器()])

MCP 服务器集成

MarkItDown 提供 模型 上下文 Protocol (MCP) 服务器，可与 Claude 桌面 等 LLM 应用集成：

# 安装 MCP 服务器 pip 安装 markitdown[all,mcp]

# 配置 Claude 桌面 使用 # 在 claude_桌面_config.json 中添加： # "mcpServers": { # "markitdown": { # "command": "python", # "args": ["-m", "markitdown.mcp"] # } # }

最佳实践 安装策略：生产环境推荐 [all] 以确保格式兼容性；资源受限环境可按需安装 内存管理：处理超大文件时使用 convert_流() 避免内存溢出 错误处理：转换可能失败（损坏文件、不支持的格式），应捕获异常并记录 编码统一：始终使用 UTF-8 编码读写 Markdown 文件 文件组织：输出目录结构与输入目录保持一致，便于维护和追踪 性能优化：批量转换时可并行处理（多进程/多线程）提高效率 故障排除 问题 可能原因 解决方案 模块NotFoundError 依赖未安装 重新运行 pip 安装 'markitdown[all]' OCR 不工作 缺少 Tesseract 安装 Tesseract OCR 引擎 图片转换失败 PIL/Pillow 缺失 pip 安装 pillow YouTube 失败 yt-dlp 未安装 pip 安装 yt-dlp 内存不足 文件太大 使用 convert_流() 或分批处理 资源目录说明

本技能包含以下资源目录：

scripts/ - 可执行脚本（示例和工具） references/ - 参考文档和详细 API as设置s/ - 模板和配置文件（当前为空） 相关链接 MarkItDown PyPI GitHub 仓库 MCP 服务器文档 更新日志

2026-03-12 - v1.0.3 版本：

修复：修正 命令行工具 脚本中指向 convert_markonverter.py 的路径错误 优化：更新版本号，保持与 package.json 一致 维护：清理冗余的 Node.js 包装器配置

2026-03-09 - 初始版本，基于 MarkItDown 0.1.0+ 创建技能模板