markitdown

MarkItDown 技能

Microsoft 用于将各种文件格式转换为 Markdown 的 Python 工具，适用于大模型和文本分析工作流。

概述

MarkItDown 转换文档时会保留结构（标题、列表、表格、链接）。它针对大模型处理进行了优化，而非面向人类阅读的输出。

支持的格式

类别	格式
文档	PDF、Word（DOCX）、PowerPoint（PPTX）、Excel（XLSX、XLS）
媒体	图像（EXIF + OCR）、音频（WAV、MP3 转录）
Web	HTML、YouTube URL、Wikipedia、RSS/Atom 订阅源
数据	CSV、JSON、XML、Jupyter 笔记本（.ipynb）
归档文件	ZIP（遍历内容）、EPub
电子邮件	Outlook MSG 文件

快速开始

安装

# Full installation (recommended)
pip install 'markitdown[all]'

# Minimal with specific formats
pip install 'markitdown[pdf,docx,pptx]'

# Using uv
uv pip install 'markitdown[all]'

可选依赖项

附加项	说明
[all]	所有可选依赖项
[pdf]	PDF 文件支持
[docx]	Word 文档
[pptx]	PowerPoint 演示文稿
[xlsx]	Excel 电子表格
[xls]	旧版 Excel 文件
[outlook]	Outlook MSG 文件
[az-doc-intel]	Azure Document Intelligence
[audio-transcription]	WAV/MP3 转录
[youtube-transcription]	YouTube 视频转录文本

命令行用法

# Basic conversion
markitdown document.pdf > output.md

# Specify output file
markitdown document.pdf -o output.md

# Pipe input
cat document.pdf | markitdown > output.md

# With Azure Document Intelligence
markitdown document.pdf -o output.md -d -e "<endpoint>"

Python API

from markitdown import MarkItDown

# Basic conversion
md = MarkItDown()
result = md.convert("document.xlsx")
print(result.text_content)

# With LLM for image descriptions
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail"
)
result = md.convert("image.jpg")
print(result.text_content)

# With Azure Document Intelligence
md = MarkItDown(docintel_endpoint="<your-endpoint>")
result = md.convert("complex-document.pdf")
print(result.text_content)

常见用例

批量转换目录

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()
input_dir = Path("./documents")
output_dir = Path("./markdown")
output_dir.mkdir(exist_ok=True)

for file in input_dir.glob("*"):
    if file.is_file():
        try:
            result = md.convert(str(file))
            output_file = output_dir / f"{file.stem}.md"
            output_file.write_text(result.text_content)
            print(f"Converted: {file.name}")
        except Exception as e:
            print(f"Failed: {file.name} - {e}")

为大模型上下文处理内容

from markitdown import MarkItDown

def prepare_for_llm(file_path: str) -> str:
    """Convert document to LLM-ready markdown."""
    md = MarkItDown()
    result = md.convert(file_path)

    # Add source reference
    content = f"# Source: {file_path}\n\n{result.text_content}"
    return content

# Use with your LLM
context = prepare_for_llm("report.pdf")

提取 YouTube 转录文本

# CLI
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" > transcript.md

# Python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

使用 AI 描述进行图像 OCR

from markitdown import MarkItDown
from openai import OpenAI

# Initialize with LLM support
client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o"
)

# Convert image with AI description
result = md.convert("screenshot.png")
print(result.text_content)

转换 Jupyter 笔记本

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("analysis.ipynb")
print(result.text_content)  # Code cells, outputs, markdown

提取 Wikipedia 内容

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://en.wikipedia.org/wiki/Python")
print(result.text_content)  # Main article content only

解析 RSS 订阅源

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://example.com/feed.xml")
print(result.text_content)  # Feed entries as markdown

插件系统

MarkItDown 支持第三方插件以扩展功能。

# List installed plugins
markitdown --list-plugins

# Enable plugins during conversion
markitdown --use-plugins document.pdf

# Enable plugins in Python
md = MarkItDown(enable_plugins=True)
result = md.convert("document.pdf")

在 GitHub 上搜索 #markitdown-plugin，查找可用插件。

MCP 服务集成

MarkItDown 提供 MCP（Model Context Protocol）服务，可与 Claude Desktop 等大模型应用集成。

# Install MCP server
pip install markitdown-mcp

# Or from source
git clone https://github.com/microsoft/markitdown.git
cd markitdown/packages/markitdown-mcp
pip install -e .

配置详情请参阅 markitdown-mcp。

Docker 用法

# Build image
docker build -t markitdown:latest .

# Convert file
docker run --rm -i markitdown:latest < document.pdf > output.md

故障排除

问题	解决方案
缺少依赖项	使用 pip install 'markitdown[all]' 安装
PDF 提取失败	对于复杂 PDF，尝试使用 Azure Document Intelligence
未提取图像文本	确保已安装 OCR 依赖项，或使用大模型模式
大文件超时	分块处理或使用流式处理
未找到插件	运行 markitdown --list-plugins 验证安装情况

常见错误

# ModuleNotFoundError for specific format
pip install 'markitdown[pdf]'  # Install missing dependency

# Azure authentication
export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="<endpoint>"
export AZURE_DOCUMENT_INTELLIGENCE_KEY="<key>"

要求

• Python >= 3.10
• 建议使用虚拟环境

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Install
pip install 'markitdown[all]'

参考资料

• references/cli-reference.md - 完整的 CLI 选项
• references/api-reference.md - Python API 详情
• references/examples.md - 更多示例
• references/advanced-features.md - 自定义转换器、URI 处理
• GitHub：https://github.com/microsoft/markitdown
• PyPI：https://pypi.org/project/markitdown/

---

注意事项

• 带嵌入图像的 DOCX：图像会提取到单独的文件中；Markdown 使用绝对路径 — 只移动 Markdown 文件会导致图像引用失效。
• PDF OCR 置信度不会显示 — 低置信度文本会像确定无误一样返回；下游大模型可能会自信地给出错误结果。
• XLSX 合并单元格会被提取为单独的单元格，非锚点位置的值为空 — 透视报表的列分组会在不知不觉中丢失。
• HTML 转 Markdown 会丢失由 CSS 控制的布局 — 按列定位的表格会折叠为按行排列的线性输出；复杂表格会变得无法解析。
• 如果没有 OPENAI_API_KEY，图像描述的 --use-llm 标志会静默回退到文件名 — 输出看似完整，实际却不包含真实描述。