文档转换技能 (convert-markdown)

---

name: convert-markdown

version: 1.0.3

description: 文档处理与转换技能，基于 MarkItDown 工具。支持将 PDF、Word、PowerPoint、Excel、图片、音频等多种格式文件批量转换为 Markdown。适用于文档数字化、知识库构建、内容提取等场景。

---

# 文档转换技能 (convert-markdown)

概述

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

快速开始

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]'

可选依赖组说明：

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 命令说明：**

| 命令 | 说明 | 参数 |

|------|------|------|

| `convert` | 转换文件或目录 | `--input`, `--output`, `--overwrite` |

| `batch` | 批量转换目录 | `--source`, `--target`, `--include`, `--exclude` |

#### 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, output_dir):
    """批量转换目录中的所有支持文件"""
    md = MarkItDown()
    input_path = Path(input_dir)
    output_path = Path(output_dir)
    output_path.mkdir(exist_ok=True)

    for file_path in input_path.rglob("*"):
        if file_path.is_file():
            try:
                result = md.convert(str(file_path))
                rel_path = file_path.relative_to(input_path)
                output_file = output_path / rel_path.with_suffix('.md')
                output_file.parent.mkdir(parents=True, exist_ok=True)
                output_file.write_text(result.text_content, encoding='utf-8')
                print(f"✓ {file_path} -> {output_file}")
            except Exception as e:
                print(f"✗ {file_path}: {e}")

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

高级配置

自定义转换选项

from markitdown import MarkItDown, StreamConverter

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

插件系统

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

from markitdown import DocumentConverter

class CustomConverter(DocumentConverter):
    def convert(self, file_stream, **kwargs):
        # 实现自定义转换逻辑
        pass

# 注册插件
md = MarkItDown(converters=[CustomConverter()])

MCP 服务器集成

MarkItDown 提供 Model Context Protocol (MCP) 服务器，可与 Claude Desktop 等 LLM 应用集成：

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

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

最佳实践

1. **安装策略**：生产环境推荐 `[all]` 以确保格式兼容性；资源受限环境可按需安装

2. **内存管理**：处理超大文件时使用 `convert_stream()` 避免内存溢出

3. **错误处理**：转换可能失败（损坏文件、不支持的格式），应捕获异常并记录

4. **编码统一**：始终使用 UTF-8 编码读写 Markdown 文件

5. **文件组织**：输出目录结构与输入目录保持一致，便于维护和追踪

6. **性能优化**：批量转换时可并行处理（多进程/多线程）提高效率

故障排除

| 问题 | 可能原因 | 解决方案 |

|------|----------|----------|

| `ModuleNotFoundError` | 依赖未安装 | 重新运行 `pip install 'markitdown[all]'` |

| OCR 不工作 | 缺少 Tesseract | 安装 Tesseract OCR 引擎 |

| 图片转换失败 | PIL/Pillow 缺失 | `pip install pillow` |

| YouTube 失败 | yt-dlp 未安装 | `pip install yt-dlp` |

| 内存不足 | 文件太大 | 使用 `convert_stream()` 或分批处理 |

资源目录说明

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

相关链接

更新日志

- 修复：修正 CLI 脚本中指向 convert_markonverter.py 的路径错误

- 优化：更新版本号，保持与 package.json 一致

- 维护：清理冗余的 Node.js 包装器配置