convert-markdown

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

## 概述

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

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

## 快速开始

### 1. 环境准备

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

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

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

### 2. 安装 MarkItDown

```bash
# 安装完整功能（推荐）
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. 基本使用

#### 命令行方式

转换单个文件：
```bash
markitdown document.pdf > document.md
markitdown presentation.pptx -o slides.md
```

批量处理目录：
```bash
# 转换当前目录所有支持文件
markitdown *.pdf *.docx *.pptx

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

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

#### Python API 方式

```python
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 格式，便于建立搜索索引：

```bash
# 创建输出目录
mkdir converted_docs

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

# convert-markdown

文档转换技能 - 基于 Microsoft MarkItDown 的多格式文档转 Markdown 工具。

## 简介

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

## 功能特性

- **多格式支持**：PDF、DOCX、PPTX、XLSX、图片、音频、HTML、CSV、JSON、ZIP、EPub、YouTube URLs 等
- **结构化保留**：保持标题、列表、表格、链接等重要文档结构
- **批量处理**：支持目录递归处理和批量转换
- **OCR 能力**：图片和扫描 PDF 的文本识别
- **音频转录**：音频文件的语音转文本

## 安装

### 环境要求

- Python 3.10 或更高版本

### 安装步骤

```bash
# 创建虚拟环境（推荐）
python -m venv .venv

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

# 安装完整功能
pip install 'markitdown[all]'

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

## 使用方法

### 命令行方式

```bash
# 转换单个文件
markitdown document.pdf > document.md
markitdown presentation.pptx -o slides.md

# 批量处理目录
markitdown ./docs/ --recursive -o ./output/
```

### Python API 方式

```python
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)
```

## 目录结构

```
convert-markdown/
├── scripts/               # 可执行脚本
│   ├── batch_convert.py   # 批量转换脚本
│   ├── convert_markonverter.py
│   └── kb_index_generator.py
├── references/            # 参考文档
│   ├── API_REFERENCE.md   # API 参考
│   ├── FORMATS.md         # 支持格式列表
│   └── PDF_CONFIG.md      # PDF 配置指南
└── SKILL.md               # 详细技能文档
```

## 快速示例

### 批量转换知识库文档

```bash
mkdir converted_docs
markitdown ./source_documents/ --recursive -o ./converted_docs/
```

### 处理扫描版 PDF

```bash
pip install 'markitd...