MarkItDown - 微软开源文件转Markdown工具，支持PDF/Word/PPT/图像OCR/音频转录

markitdown by davila7/claude-code-templates

600 周安装量

23,500 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/davila7/claude-code-templates --skill markitdown

AI/机器学习开发自动化

🇨🇳中文介绍

MarkItDown - 文件转 Markdown 转换工具

概述

MarkItDown 是微软开发的一款 Python 工具，用于将各种文件格式转换为 Markdown。它特别适用于将文档转换为适合大语言模型（LLM）处理的文本格式，因为 Markdown 格式令牌效率高，且现代语言模型对其理解良好。

主要优势：

将文档转换为干净、结构化的 Markdown
为 LLM 处理提供令牌高效的格式
支持 15 种以上的文件格式
可选的 AI 增强图像描述
支持图像和扫描文档的 OCR
支持音频文件的语音转录

使用科学示意图增强视觉效果

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

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

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

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

如何生成示意图：

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

AI 将自动：

创建格式正确的出版物质量图像
通过多次迭代进行审查和优化
确保可访问性（色盲友好、高对比度）
将输出保存在 figures/ 目录中

何时添加示意图：

文档转换工作流程图
文件格式架构示意图

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

格式	描述	备注
PDF	便携式文档格式	完整文本提取
DOCX	Microsoft Word	保留表格、格式
PPTX	PowerPoint	包含备注的幻灯片
XLSX	Excel 电子表格	表格和数据
图像	JPEG, PNG, GIF, WebP	EXIF 元数据 + OCR
音频	WAV, MP3	元数据 + 转录
HTML	网页	干净转换
CSV	逗号分隔值	表格格式
JSON	JSON 数据	结构化表示
XML	XML 文档	结构化格式
ZIP	归档文件	遍历内容
EPUB	电子书	完整文本提取
YouTube	视频 URL	获取转录文本

1. AI 增强图像描述

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

from markitdown import MarkItDown
from openai import OpenAI

# 初始化 OpenRouter 客户端（兼容 OpenAI 的 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-sonnet-4.5",  # 推荐用于科学视觉
    llm_prompt="详细描述此图像以用于科学文档"
)

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

2. Azure Document Intelligence

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

# 命令行
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)

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

# 列出已安装的插件
markitdown --list-plugins

# 启用插件
markitdown --use-plugins file.pdf -o output.md

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

控制您支持的文件格式：

# 安装特定格式
pip install 'markitdown[pdf, docx, pptx]'

# 所有可用选项：
# [all]                  - 所有可选依赖项
# [pptx]                 - PowerPoint 文件
# [docx]                 - Word 文档
# [xlsx]                 - Excel 电子表格
# [xls]                  - 旧版 Excel 文件
# [pdf]                  - PDF 文档
# [outlook]              - Outlook 邮件
# [az-doc-intel]         - Azure Document Intelligence
# [audio-transcription]  - WAV 和 MP3 转录
# [youtube-transcription] - YouTube 视频转录

1. 将科学论文转换为 Markdown

from markitdown import MarkItDown

md = MarkItDown()

# 转换 PDF 论文
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")

# 结果将以 Markdown 表格格式呈现
print(result.text_content)

3. 处理多个文档

from markitdown import MarkItDown
import os
from pathlib import Path

md = MarkItDown()

# 处理目录中的所有 PDF
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"已转换: {pdf_file.name}")

4. 使用 AI 描述转换 PowerPoint

from markitdown import MarkItDown
from openai import OpenAI

# 使用 OpenRouter 访问多个 AI 模型
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",  # 推荐用于演示文稿
    llm_prompt="详细描述此幻灯片图像，重点关注关键视觉元素和数据"
)

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 = [
    "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"✓ 已转换 {file}")
    except Exception as e:
        print(f"✗ 转换 {file} 时出错: {e}")

6. 提取 YouTube 视频转录文本

from markitdown import MarkItDown

md = MarkItDown()

# 将 YouTube 视频转换为转录文本
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

# 构建镜像
docker build -t markitdown:latest .

# 运行转换
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("文件未找到")
except Exception as e:
    print(f"转换错误: {e}")

3. 高效处理大文件

from markitdown import MarkItDown

md = MarkItDown()

# 对于大文件，使用流式处理
with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    
    # 分块处理或直接保存
    with open("output.md", "w") as out:
        out.write(result.text_content)

4. 优化令牌效率

Markdown 输出已经是令牌高效的，但您可以：

移除多余的空格
合并相似部分
如果不需要，则剥离元数据

from markitdown import MarkItDown import re

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

清理多余空格

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()

# 转换 literature 文件夹中的所有论文
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))
    
    # 保存元数据
    output_file = output_dir / f"{paper.stem}.md"
    content = f"# {paper.stem}\n\n"
    content += f"**来源**: {paper.name}\n\n"
    content += "---\n\n"
    content += result.text_content
    
    output_file.write_text(content)

# 用于带插图的 AI 增强转换
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-sonnet-4.5",
    llm_prompt="以技术精度描述科学插图"
)

提取表格进行分析

from markitdown import MarkItDown
import re

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

# Markdown 表格可以直接解析或使用
print(result.text_content)

缺少依赖项 : 安装特定功能包

pip install 'markitdown[pdf]'  # 用于 PDF 支持

二进制文件错误 : 确保以二进制模式打开文件

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

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 密钥 : https://openrouter.ai/keys
OpenRouter 模型 : https://openrouter.ai/models
MCP 服务器 : markitdown-mcp（用于 Claude Desktop 集成）
插件开发 : 参见 packages/markitdown-sample-plugin

🇺🇸English

MarkItDown - File to Markdown Conversion

Overview

MarkItDown is a Python tool developed by Microsoft for converting various file formats to Markdown. It's particularly useful for converting documents into LLM-friendly text format, as Markdown is token-efficient and well-understood by modern language models.

Key Benefits :

Convert documents to clean, structured Markdown
Token-efficient format for LLM processing
Supports 15+ file formats
Optional AI-enhanced image descriptions
OCR for images and scanned documents
Speech transcription for audio files

Visual Enhancement with Scientific Schematics

When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.

If your document does not already contain schematics or diagrams:

Use the scientific-schematics skill to generate AI-powered publication-quality diagrams
Simply describe your desired diagram in natural language
Nano Banana Pro will automatically generate, review, and refine the schematic

For new documents: Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.

How to generate schematics:

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

The AI will automatically:

Create publication-quality images with proper formatting
Review and refine through multiple iterations
Ensure accessibility (colorblind-friendly, high contrast)
Save outputs in the figures/ directory

When to add schematics:

Document conversion workflow diagrams
File format architecture illustrations
OCR processing pipeline diagrams
Integration workflow visualizations
System architecture diagrams
Data flow diagrams
Any complex concept that benefits from visualization

For detailed guidance on creating schematics, refer to the scientific-schematics skill documentation.

Supported Formats

Format	Description	Notes
PDF	Portable Document Format	Full text extraction
DOCX	Microsoft Word	Tables, formatting preserved
PPTX	PowerPoint	Slides with notes
XLSX	Excel spreadsheets	Tables and data
Images	JPEG, PNG, GIF, WebP	EXIF metadata + OCR
Audio	WAV, MP3	Metadata + transcription
HTML	Web pages	Clean conversion
CSV	Comma-separated values

Quick Start

Installation

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

Command-Line Usage

# 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)

Advanced Features

1. AI-Enhanced Image Descriptions

Use LLMs via OpenRouter to generate detailed image descriptions (for PPTX and image files):

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-sonnet-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

For enhanced PDF conversion with Microsoft Document Intelligence:

# 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. Plugin System

MarkItDown supports 3rd-party plugins for extending functionality:

# List installed plugins
markitdown --list-plugins

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

Find plugins on GitHub with hashtag: #markitdown-plugin

Optional Dependencies

Control which file formats you support:

# 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

Common Use Cases

1. Convert Scientific Papers to 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. Extract Data from Excel for Analysis

from markitdown import MarkItDown

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

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

3. Process Multiple Documents

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. Convert PowerPoint with AI Descriptions

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-sonnet-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. Batch Convert with Different Formats

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. Extract YouTube Video Transcription

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 Usage

# Build image
docker build -t markitdown:latest .

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

Best Practices

1. Choose the Right Conversion Method

Simple documents : Use basic MarkItDown()
Complex PDFs : Use Azure Document Intelligence
Visual content : Enable AI image descriptions
Scanned documents : Ensure OCR dependencies are installed

2. Handle Errors Gracefully

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. Process Large Files Efficiently

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. Optimize for Token Efficiency

Markdown output is already token-efficient, but you can:

Remove excessive whitespace
Consolidate similar sections
Strip metadata if not needed

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)

Integration with Scientific Workflows

Convert Literature for Review

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-sonnet-4.5",
    llm_prompt="Describe scientific figures with technical precision"
)

Extract Tables for Analysis

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)

Troubleshooting

Common Issues

Missing dependencies : Install feature-specific packages
```
pip install 'markitdown[pdf]'  # For PDF support
```

Binary file errors : Ensure files are opened in binary mode

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

OCR not working : Install tesseract

# macOS
brew install tesseract

# Ubuntu
sudo apt-get install tesseract-ocr

Performance Considerations

PDF files : Large PDFs may take time; consider page ranges if supported
Image OCR : OCR processing is CPU-intensive
Audio transcription : Requires additional compute resources
AI image descriptions : Requires API calls (costs may apply)

Next Steps

See references/api_reference.md for complete API documentation
Check references/file_formats.md for format-specific details
Review scripts/batch_convert.py for automation examples
Explore scripts/convert_with_ai.py for AI-enhanced conversions

Resources

MarkItDown GitHub : https://github.com/microsoft/markitdown
PyPI : https://pypi.org/project/markitdown/
OpenRouter : https://openrouter.ai (for AI-enhanced conversions)
OpenRouter API Keys : https://openrouter.ai/keys
OpenRouter Models : https://openrouter.ai/models
MCP Server : markitdown-mcp (for Claude Desktop integration)
Plugin Development : See packages/markitdown-sample-plugin

Weekly Installs

448

Repository

davila7/claude-…emplates

GitHub Stars

22.6K

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubFail SocketFail SnykWarn

Installed on

opencode364

gemini-cli343

claude-code333

codex329

cursor306

github-copilot296

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

136,300 周安装

MarkItDown - 微软开源文件转Markdown工具，支持PDF/Word/PPT/图像OCR/音频转录

🇨🇳中文介绍

MarkItDown - 文件转 Markdown 转换工具

概述

使用科学示意图增强视觉效果

相关 Skills

支持的格式

快速开始

安装

命令行使用

Python API

高级功能

1. AI 增强图像描述

2. Azure Document Intelligence

3. 插件系统

可选依赖项

常见用例

1. 将科学论文转换为 Markdown

2. 从 Excel 提取数据进行分析

3. 处理多个文档

4. 使用 AI 描述转换 PowerPoint

5. 批量转换不同格式

6. 提取 YouTube 视频转录文本

Docker 使用

最佳实践

1. 选择正确的转换方法

2. 优雅地处理错误

3. 高效处理大文件

4. 优化令牌效率

清理多余空格

与科学工作流程集成

转换文献以供审阅

提取表格进行分析

故障排除

常见问题

性能考虑

后续步骤

资源

🇺🇸English

MarkItDown - File to Markdown Conversion

Overview

Visual Enhancement with Scientific Schematics

Supported Formats

Quick Start

Installation

Command-Line Usage

Python API

Advanced Features

1. AI-Enhanced Image Descriptions

2. Azure Document Intelligence

3. Plugin System

Optional Dependencies

Common Use Cases

1. Convert Scientific Papers to Markdown

2. Extract Data from Excel for Analysis

3. Process Multiple Documents

4. Convert PowerPoint with AI Descriptions

5. Batch Convert with Different Formats

6. Extract YouTube Video Transcription

Docker Usage

Best Practices

1. Choose the Right Conversion Method

2. Handle Errors Gracefully

3. Process Large Files Efficiently

4. Optimize for Token Efficiency

Clean up extra whitespace

Integration with Scientific Workflows

Convert Literature for Review

Extract Tables for Analysis

Troubleshooting

Common Issues

Performance Considerations

Next Steps

Resources

最新 Skills