markitdown

MarkItDown - 文件转 Markdown 转换

概述

MarkItDown 是由 Microsoft 开发的 Python 工具，用于将各种文件格式转换为 Markdown。它特别适合将文档转换为对大模型友好的文本格式，因为 Markdown 具有较高的 token 效率，并且能被现代语言模型很好地理解。

主要优势：

• 将文档转换为干净、结构化的 Markdown
• 适合大模型处理的 token 高效格式
• 支持 15+ 种文件格式
• 可选的 AI 增强图像描述
• 面向图像和扫描文档的 OCR
• 面向音频文件的语音转写

使用科学示意图进行视觉增强

使用此技能创建文档时，请始终考虑添加科学图表和示意图，以增强视觉传达。

如果你的文档尚未包含示意图或图表：

• 使用 scientific-schematics 技能生成 AI 驱动的出版级图表
• 只需用自然语言描述你想要的图表
• Nano Banana Pro 将自动生成、审查并优化示意图

对于新文档： 默认应生成科学示意图，以直观呈现文本中描述的关键概念、工作流、架构或关系。

如何生成示意图：

python scripts/generate_schematic.py "your diagram description" -o figures/output.png

AI 将自动：

• 创建具有正确格式的出版级图像
• 通过多轮迭代审查并优化
• 确保可访问性（对色盲友好、高对比度）
• 将输出保存到 figures/ 目录

何时添加示意图：

• 文档转换工作流图
• 文件格式架构插图
• OCR 处理流水线图
• 集成工作流可视化
• 系统架构图
• 数据流图
• 任何受益于可视化的复杂概念

有关创建示意图的详细指导，请参阅 scientific-schematics 技能文档。

---

支持的格式

格式	描述	说明
PDF	可移植文档格式	全文提取
DOCX	Microsoft Word	保留表格和格式
PPTX	PowerPoint	带备注的幻灯片
XLSX	Excel 电子表格	表格和数据
Images	JPEG、PNG、GIF、WebP	EXIF 元数据 + OCR
Audio	WAV、MP3	元数据 + 转写
HTML	网页	干净转换
CSV	逗号分隔值	表格格式
JSON	JSON 数据	结构化表示
XML	XML 文档	结构化格式
ZIP	归档文件	遍历内容
EPUB	电子书	全文提取
YouTube	视频 URL	获取转写文本

快速开始

安装

# Install with all features
pip install 'markitdown[all]'

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

命令行用法

# Basic conversion
markitdown document.pdf > output.md

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

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

# Enable plugins
markitdown --list-plugins  # List available plugins
markitdown --use-plugins document.pdf -o output.md

Python API

from markitdown import MarkItDown

# Basic usage
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

# Convert from stream
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    print(result.text_content)

高级功能

1. AI 增强图像描述

通过 OpenRouter 使用大模型生成详细的图像描述（适用于 PPTX 和图像文件）：

from markitdown import MarkItDown
from openai import OpenAI

# Initialize OpenRouter client (OpenAI-compatible API)
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-opus-4.5",  # recommended for scientific vision
    llm_prompt="Describe this image in detail for scientific documentation"
)

result = md.convert("presentation.pptx")
print(result.text_content)

2. Azure Document Intelligence

使用 Microsoft Document Intelligence 进行增强的 PDF 转换：

# Command line
markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"

# Python API
from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("complex_document.pdf")
print(result.text_content)

3. 插件系统

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

# List installed plugins
markitdown --list-plugins

# Enable plugins
markitdown --use-plugins file.pdf -o output.md

在 GitHub 上使用话题标签查找插件：#markitdown-plugin

可选依赖

控制你支持哪些文件格式：

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

# All available options:
# [all]                  - All optional dependencies
# [pptx]                 - PowerPoint files
# [docx]                 - Word documents
# [xlsx]                 - Excel spreadsheets
# [xls]                  - Older Excel files
# [pdf]                  - PDF documents
# [outlook]              - Outlook messages
# [az-doc-intel]         - Azure Document Intelligence
# [audio-transcription]  - WAV and MP3 transcription
# [youtube-transcription] - YouTube video transcription

常见用例

1. 将科学论文转换为 Markdown

from markitdown import MarkItDown

md = MarkItDown()

# Convert PDF paper
result = md.convert("research_paper.pdf")
with open("paper.md", "w") as f:
    f.write(result.text_content)

2. 从 Excel 提取数据用于分析

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.xlsx")

# Result will be in Markdown table format
print(result.text_content)

3. 处理多个文档

from markitdown import MarkItDown
import os
from pathlib import Path

md = MarkItDown()

# Process all PDFs in a directory
pdf_dir = Path("papers/")
output_dir = Path("markdown_output/")
output_dir.mkdir(exist_ok=True)

for pdf_file in pdf_dir.glob("*.pdf"):
    result = md.convert(str(pdf_file))
    output_file = output_dir / f"{pdf_file.stem}.md"
    output_file.write_text(result.text_content)
    print(f"Converted: {pdf_file.name}")

4. 使用 AI 描述转换 PowerPoint

from markitdown import MarkItDown
from openai import OpenAI

# Use OpenRouter for access to multiple AI models
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-opus-4.5",  # recommended for presentations
    llm_prompt="Describe this slide image in detail, focusing on key visual elements and data"
)

result = md.convert("presentation.pptx")
with open("presentation.md", "w") as f:
    f.write(result.text_content)

5. 批量转换不同格式

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Files to convert
files = [
    "document.pdf",
    "spreadsheet.xlsx",
    "presentation.pptx",
    "notes.docx"
]

for file in files:
    try:
        result = md.convert(file)
        output = Path(file).stem + ".md"
        with open(output, "w") as f:
            f.write(result.text_content)
        print(f"✓ Converted {file}")
    except Exception as e:
        print(f"✗ Error converting {file}: {e}")

6. 提取 YouTube 视频转写文本

from markitdown import MarkItDown

md = MarkItDown()

# Convert YouTube video to transcript
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

Docker 用法

# Build image
docker build -t markitdown:latest .

# Run conversion
docker run --rm -i markitdown:latest < ~/document.pdf > output.md

最佳实践

1. 选择正确的转换方法

• 简单文档：使用基本的 MarkItDown()
• 复杂 PDF：使用 Azure Document Intelligence
• 视觉内容：启用 AI 图像描述
• 扫描文档：确保已安装 OCR 依赖

2. 妥善处理错误

from markitdown import MarkItDown

md = MarkItDown()

try:
    result = md.convert("document.pdf")
    print(result.text_content)
except FileNotFoundError:
    print("File not found")
except Exception as e:
    print(f"Conversion error: {e}")

3. 高效处理大型文件

from markitdown import MarkItDown

md = MarkItDown()

# For large files, use streaming
with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    
    # Process in chunks or save directly
    with open("output.md", "w") as out:
        out.write(result.text_content)

4. 优化 Token 效率

Markdown 输出本身已具有较高的 Token 效率，但你还可以：

• 删除多余的空白
• 合并相似的部分
• 在不需要时移除元数据

from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("document.pdf")

# Clean up extra whitespace
clean_text = re.sub(r'\n{3,}', '\n\n', result.text_content)
clean_text = clean_text.strip()

print(clean_text)

与科学工作流集成

转换文献以供审阅

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Convert all papers in literature folder
papers_dir = Path("literature/pdfs")
output_dir = Path("literature/markdown")
output_dir.mkdir(exist_ok=True)

for paper in papers_dir.glob("*.pdf"):
    result = md.convert(str(paper))
    
    # Save with metadata
    output_file = output_dir / f"{paper.stem}.md"
    content = f"# {paper.stem}\n\n"
    content += f"**Source**: {paper.name}\n\n"
    content += "---\n\n"
    content += result.text_content
    
    output_file.write_text(content)

# For AI-enhanced conversion with figures
from openai import OpenAI

client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md_ai = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-opus-4.5",
    llm_prompt="Describe scientific figures with technical precision"
)

提取表格以供分析

from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("data_tables.xlsx")

# Markdown tables can be parsed or used directly
print(result.text_content)

故障排除

常见问题

1. 缺少依赖项：安装特定功能所需的软件包

   pip install 'markitdown[pdf]'  # For PDF support
   

2. 二进制文件错误：确保以二进制模式打开文件

   with open("file.pdf", "rb") as f:  # Note the "rb"
       result = md.convert_stream(f, file_extension=".pdf")
   

3. OCR 无法正常工作：安装 tesseract

   # macOS
   brew install tesseract
   
   # Ubuntu
   sudo apt-get install tesseract-ocr
   

性能注意事项

• PDF 文件：大型 PDF 可能需要一些时间；如果支持，请考虑指定页面范围
• 图像 OCR：OCR 处理会占用大量 CPU 资源
• 音频转录：需要额外的计算资源
• AI 图像描述：需要调用 API（可能会产生费用）

后续步骤

• 查看 references/api_reference.md，了解完整的 API 文档
• 查看 references/file_formats.md，了解特定格式的详细信息
• 查看 scripts/batch_convert.py，了解自动化示例
• 探索 scripts/convert_with_ai.py，了解 AI 增强转换

资源

• MarkItDown GitHub：https://github.com/microsoft/markitdown
• PyPI：https://pypi.org/project/markitdown/
• OpenRouter：https://openrouter.ai（用于 AI 增强转换）
• OpenRouter API Keys：https://openrouter.ai/keys
• OpenRouter Models：https://openrouter.ai/models
• MCP 服务：markitdown-mcp（用于集成 Claude Desktop）
• 插件开发：参见 packages/markitdown-sample-plugin