微软开源 MarkItDown：文件转 Markdown 的轻量级 Python 工具

時光2026-07-292026-07-29

最近在处理一些文档转 Markdown 的需求时，发现了微软开源的 microsoft/markitdown 工具，用起来非常顺手，记录分享一下。

工具简介

MarkItDown 是微软开源的一款轻量级 Python 工具，可以将多种文件格式转换为 Markdown。它的设计初衷是为 LLM（大语言模型）和文本分析管道提供结构化的文档内容，而不是追求高保真的人工阅读体验。

目前已获得 169K+ 的 GitHub Star，非常活跃。

支持格式

MarkItDown 支持的文件格式相当丰富：

格式	说明
PDF	提取文本内容，保留基本结构
Word (.docx)	保留标题、列表、表格等结构
Excel (.xlsx)	转换为 Markdown 表格
PowerPoint (.pptx)	提取幻灯片内容
HTML	转换为纯文本 Markdown
图片	通过 OCR 提取文字（需额外依赖）
音频	语音转文字（需额外依赖）
Markdown	直接返回原内容

安装方式

方式一：pip 安装（推荐）

1	pip install 'markitdown[all]'

如果只需要基础功能（不支持图片 OCR 和音频转文字）：

1	pip install markitdown

方式二：从源码安装

1
2
3

git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

使用方法

命令行使用

最基本的用法，直接转换文件并输出到标准输出：

1	markitdown <你的文件路径>

例如转换一个 PDF 文件：

1	markitdown document.pdf

输出内容可以直接重定向到文件：

1	markitdown document.pdf > output.md

分页提取（v0.1.2+）

如果需要按页提取内容（支持 PDF、PPTX、DOCX）：

1	markitdown document.pdf --extract-pages --pages-json

Python 代码调用

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("<你的文件路径>")

print(result.text_content)

批量转换

写个简单的脚本批量转换目录下的所有文件：

import os
from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown()
input_dir = Path("<你的文档目录>")
output_dir = Path("<输出目录>")
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, encoding="utf-8")
            print(f"已转换: {file.name}")
        except Exception as e:
            print(f"转换失败: {file.name}, 错误: {e}")

实际体验

转换效果示例，以一个包含标题、列表和表格的 Word 文档为例：

# 项目周报

## 本周进展

- 完成了用户模块开发
- 修复了登录页面的 bug
- 优化了查询性能

## 下周计划

| 任务 | 负责人 | 预计完成时间 |
|------|--------|-------------|
| 接口联调 | 张三 | 2025-01-27 |
| 单元测试 | 李四 | 2025-01-28 |
| 文档编写 | 王五 | 2025-01-29 |

整体转换效果不错，基本保留了文档的结构信息。

与同类工具对比

MarkItDown 的定位和 textract 类似，但侧重点不同：

对比项	MarkItDown	textract
输出格式	Markdown	纯文本
结构保留	保留标题、列表、表格	仅提取文本
依赖数量	较少	较多
维护状态	活跃（微软维护）	一般