markitdown-skill by julianobarbosa/claude-code-skills
npx skills add https://github.com/julianobarbosa/claude-code-skills --skill markitdown-skill微软推出的 Python 工具,用于将各种文件格式转换为 Markdown,适用于 LLM 和文本分析流水线。
MarkItDown 在转换文档的同时保留其结构(标题、列表、表格、链接)。它针对 LLM 消费而非人类可读输出进行了优化。
| 类别 | 格式 |
|---|---|
| 文档 | PDF, Word (DOCX), PowerPoint (PPTX), Excel (XLSX, XLS) |
| 媒体 | 图像 (EXIF + OCR), 音频 (WAV, MP3 转录) |
| 网页 | HTML, YouTube 网址, Wikipedia, RSS/Atom 订阅源 |
| 数据 | CSV, JSON, XML, Jupyter 笔记本 (.ipynb) |
| 归档文件 | ZIP (遍历内容), EPub |
| 邮件 | Outlook MSG 文件 |
# 完整安装 (推荐)
pip install 'markitdown[all]'
# 最小化安装,包含特定格式支持
pip install 'markitdown[pdf,docx,pptx]'
# 使用 uv
uv pip install 'markitdown[all]'
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 额外项 | 描述 |
|---|
[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 视频字幕 |
# 基本转换
markitdown document.pdf > output.md
# 指定输出文件
markitdown document.pdf -o output.md
# 管道输入
cat document.pdf | markitdown > output.md
# 使用 Azure Document Intelligence
markitdown document.pdf -o output.md -d -e "<endpoint>"
from markitdown import MarkItDown
# 基本转换
md = MarkItDown()
result = md.convert("document.xlsx")
print(result.text_content)
# 使用 LLM 生成图像描述
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)
# 使用 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:
"""将文档转换为可供 LLM 使用的 Markdown 格式。"""
md = MarkItDown()
result = md.convert(file_path)
# 添加来源引用
content = f"# Source: {file_path}\n\n{result.text_content}"
return content
# 与你的 LLM 一起使用
context = prepare_for_llm("report.pdf")
# 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)
from markitdown import MarkItDown
from openai import OpenAI
# 初始化,支持 LLM
client = OpenAI()
md = MarkItDown(
llm_client=client,
llm_model="gpt-4o"
)
# 转换图像并生成 AI 描述
result = md.convert("screenshot.png")
print(result.text_content)
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("analysis.ipynb")
print(result.text_content) # 代码单元格、输出、markdown
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("https://en.wikipedia.org/wiki/Python")
print(result.text_content) # 仅主文章内容
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("https://example.com/feed.xml")
print(result.text_content) # 订阅源条目以 markdown 格式呈现
MarkItDown 支持第三方插件以扩展功能。
# 列出已安装的插件
markitdown --list-plugins
# 在转换过程中启用插件
markitdown --use-plugins document.pdf
# 在 Python 中启用插件
md = MarkItDown(enable_plugins=True)
result = md.convert("document.pdf")
在 GitHub 上搜索
#markitdown-plugin以查找可用插件。
MarkItDown 提供了一个 MCP (Model Context Protocol) 服务器,用于与 Claude Desktop 等 LLM 应用程序集成。
# 安装 MCP 服务器
pip install markitdown-mcp
# 或从源代码安装
git clone https://github.com/microsoft/markitdown.git
cd markitdown/packages/markitdown-mcp
pip install -e .
配置详情请参阅 markitdown-mcp。
# 构建镜像
docker build -t markitdown:latest .
# 转换文件
docker run --rm -i markitdown:latest < document.pdf > output.md
| 问题 | 解决方案 |
|---|---|
| 缺少依赖项 | 使用 pip install 'markitdown[all]' 安装 |
| PDF 提取失败 | 对于复杂的 PDF,尝试使用 Azure Document Intelligence |
| 图像文本未提取 | 确保已安装 OCR 依赖项或使用 LLM 模式 |
| 大文件超时 | 分块处理或使用流式处理 |
| 插件未找到 | 运行 markitdown --list-plugins 以验证安装 |
# 特定格式的 ModuleNotFoundError
pip install 'markitdown[pdf]' # 安装缺失的依赖项
# Azure 身份验证
export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="<endpoint>"
export AZURE_DOCUMENT_INTELLIGENCE_KEY="<key>"
Python >= 3.10
推荐使用虚拟环境
python -m venv .venv source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows
pip install 'markitdown[all]'
references/cli-reference.md - 完整的 CLI 选项references/api-reference.md - Python API 详情references/examples.md - 扩展示例references/advanced-features.md - 自定义转换器、URI 处理每周安装量
76
仓库
GitHub 星标数
44
首次出现
Jan 20, 2026
安全审计
安装于
cursor67
opencode67
gemini-cli65
codex61
github-copilot57
claude-code54
Microsoft's Python utility for converting various file formats to Markdown for LLM and text analysis pipelines.
MarkItDown converts documents while preserving structure (headings, lists, tables, links). It's optimized for LLM consumption rather than human-readable output.
| Category | Formats |
|---|---|
| Documents | PDF, Word (DOCX), PowerPoint (PPTX), Excel (XLSX, XLS) |
| Media | Images (EXIF + OCR), Audio (WAV, MP3 transcription) |
| Web | HTML, YouTube URLs, Wikipedia, RSS/Atom feeds |
| Data | CSV, JSON, XML, Jupyter notebooks (.ipynb) |
| Archives | ZIP (iterates contents), EPub |
| Outlook MSG files |
# Full installation (recommended)
pip install 'markitdown[all]'
# Minimal with specific formats
pip install 'markitdown[pdf,docx,pptx]'
# Using uv
uv pip install 'markitdown[all]'
| Extra | Description |
|---|---|
[all] | All optional dependencies |
[pdf] | PDF file support |
[docx] | Word documents |
[pptx] | PowerPoint presentations |
[xlsx] | Excel spreadsheets |
[xls] | Legacy Excel files |
# 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>"
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")
# 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)
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)
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("analysis.ipynb")
print(result.text_content) # Code cells, outputs, markdown
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("https://en.wikipedia.org/wiki/Python")
print(result.text_content) # Main article content only
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("https://example.com/feed.xml")
print(result.text_content) # Feed entries as markdown
MarkItDown supports third-party plugins for extended functionality.
# 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")
Search GitHub for
#markitdown-pluginto find available plugins.
MarkItDown offers an MCP (Model Context Protocol) server for integration with LLM applications like 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 .
See markitdown-mcp for configuration details.
# Build image
docker build -t markitdown:latest .
# Convert file
docker run --rm -i markitdown:latest < document.pdf > output.md
| Issue | Solution |
|---|---|
| Missing dependencies | Install with pip install 'markitdown[all]' |
| PDF extraction fails | Try Azure Document Intelligence for complex PDFs |
| Image text not extracted | Ensure OCR dependencies installed or use LLM mode |
| Large file timeout | Process in chunks or use streaming |
| Plugin not found | Run markitdown --list-plugins to verify installation |
# 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
Virtual environment recommended
python -m venv .venv source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows
pip install 'markitdown[all]'
references/cli-reference.md - Complete CLI optionsreferences/api-reference.md - Python API detailsreferences/examples.md - Extended examplesreferences/advanced-features.md - Custom converters, URI handlingWeekly Installs
76
Repository
GitHub Stars
44
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubWarnSocketPassSnykWarn
Installed on
cursor67
opencode67
gemini-cli65
codex61
github-copilot57
claude-code54
AI 代码实施计划编写技能 | 自动化开发任务分解与 TDD 流程规划工具
50,900 周安装
Vuetify0 无头组件库 - Vue 3 组合式函数与无样式UI构建块
219 周安装
AWS Serverless 开发指南:Lambda 函数与 API Gateway 集成模式最佳实践
216 周安装
Simplify代码简化工具 - 提升代码清晰度、一致性和可维护性的AI助手
222 周安装
GitHub CLI (gh) 使用指南:高效管理仓库、PR、议题与API调用
212 周安装
Cheerio HTML解析教程:Node.js网页抓取与DOM操作指南
214 周安装
资深前端开发工程师AI助手 - 精通React/NextJS/TypeScript/TailwindCSS
216 周安装
[outlook]| Outlook MSG files |
[az-doc-intel] | Azure Document Intelligence |
[audio-transcription] | WAV/MP3 transcription |
[youtube-transcription] | YouTube video transcripts |