⚡

文档转Markdown工具Skill markitdown

MarkItDown是一个Python文件转换工具，支持将PDF、DOCX、图像等15多种格式转换为Markdown，集成OCR和AI功能，适用于数据提取、LLM处理和科学工作流，关键词包括文件转换、Markdown、OCR、AI、数据处理。

AI应用 0 次安装 0 次浏览 更新于 3/22/2026

名称: markitdown 描述: “将文件和办公文档转换为Markdown。支持PDF、DOCX、PPTX、XLSX、图像（带OCR）、音频（带转录）、HTML、CSV、JSON、XML、ZIP、YouTube URL、EPub等。” 允许工具: [读取, 写入, 编辑, Bash] 许可证: MIT 来源: https://github.com/microsoft/markitdown

MarkItDown - 文件转Markdown转换

概述

MarkItDown是Microsoft开发的Python工具，用于将各种文件格式转换为Markdown。它特别适用于将文档转换为LLM友好的文本格式，因为Markdown是令牌高效且被现代语言模型良好理解的。

主要优势:

  • 将文档转换为干净、结构化的Markdown
  • 令牌高效格式，适用于LLM处理
  • 支持15+文件格式
  • 可选AI增强图像描述
  • 图像和扫描文档的OCR
  • 音频文件的语音转录

科学示意图的视觉增强

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

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

  • 使用scientific-schematics技能生成AI驱动的出版质量图表
  • 只需用自然语言描述所需的图表
  • Nano Banana Pro将自动生成、审查和精修示意图

对于新文档: 应默认生成科学示意图，以视觉表示文本中描述的关键概念、工作流、架构或关系。

如何生成示意图:

python scripts/generate_schematic.py "您的图表描述" -o figures/output.png

AI将自动：

  • 创建出版质量图像，具有适当格式
  • 通过多次迭代审查和精修
  • 确保可访问性（色盲友好、高对比度）
  • 保存输出在figures/目录中

何时添加示意图:

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

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

支持格式

格式 描述 备注
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 获取转录

快速开始

安装

# 安装所有功能
pip install 'markitdown[all]'

# 或从源码安装
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

命令行使用

# 基本转换
markitdown document.pdf > output.md

# 指定输出文件
markitdown document.pdf -o output.md

# 管道内容
cat document.pdf | markitdown > output.md

# 启用插件
markitdown --list-plugins  # 列出可用插件
markitdown --use-plugins document.pdf -o output.md

Python API

from markitdown import MarkItDown

# 基本使用
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

# 从流转换
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    print(result.text_content)

高级功能

1. AI增强图像描述

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

from markitdown import MarkItDown
from openai import OpenAI

# 初始化OpenRouter客户端（与OpenAI兼容的API）
client = OpenAI(
    api_key="您的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

用于增强PDF转换与Microsoft Document Intelligence：

# 命令行
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支持第三方插件以扩展功能：

# 列出已安装插件
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="您的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使用

# 构建镜像
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'
{3,}', '

', result.text_content)
clean_text = clean_text.strip()

print(clean_text)

与科学工作流集成

转换文献用于综述

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# 转换文献文件夹中的所有论文
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}

"
    content += f"**来源**: {paper.name}

"
    content += "---

"
    content += result.text_content
    
    output_file.write_text(content)

# 用于AI增强转换与图表
from openai import OpenAI

client = OpenAI(
    api_key="您的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)

故障排除

常见问题

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

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

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

    with open("file.pdf", "rb") as f:  # 注意 "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增强转换示例

资源