markitdown 5 分钟上手：把任意办公文件丢进命令行，出来就是 Markdown

正文

还在手动复制 PDF 文字？还在用 Word 的"另存为 HTML"凑合？微软开源的这个工具，能把 PDF、Word、Excel、PPT 一次性转成干净的 Markdown，一行命令搞定。

你能学到什么

• ✅ 用一条命令把 PDF/Word/Excel/PPT 转成 Markdown
• ✅ 批量转换整个文件夹，一键归档
• ✅ 保留表格、代码块、标题层级结构
• ✅ 用 Python API 集成到自己的脚本里

背景与痛点

写技术文档的时候，最烦的不是写本身，而是把已有的内容迁移过来。

• 甲方丢来一份 50 页的 PDF 规范，你得手工复制每个段落
• 同事发来一个 Excel 配置表，你想把它转成 Markdown 放进 GitHub README
• 产品经理传了一个 PPT，里面有你要的结构化信息

这些场景的共同点是：原始文件不是 Markdown，而你需要 Markdown。

常见解法：

• 在线转换网站（要上传文件、含广告、有限制）
• pandoc（转换质量不错，但配置复杂）
• 手动复制（效率低、格式丢失）

markitdown 是微软开源的文件转 Markdown 工具，以上问题全干掉。

核心概念

markitdown 本质是一个格式桥接器：

PDF / Word / Excel / PPT / HTML / 图片(PDF) → markitdown → Markdown

它底层调用了多种解析库（pdfminer、python-docx、openpyxl 等），输出统一的 Markdown 格式，表格用 GFM 语法，代码块保留语言标识，标题层级对应原始文档结构。

实操步骤

第一步：安装

pip install markitdown

或升级到最新版：

pip install --upgrade markitdown

验证安装成功：

markitdown --version
# 输出类似：markitdown version 1.x.x

第二步：单文件转换（30 秒）

把一个 PDF 转成 Markdown：

markitdown 技术规范.pdf -o 技术规范.md

把 Word 文档转成 Markdown：

markitdown 产品需求.docx -o 产品需求.md

支持的输入格式：pdf、docx、doc、xlsx、xls、pptx、html、txt

第三步：批量转换整个文件夹

想把一个目录里所有文件都转成 Markdown：

# 递归转换 input/ 目录下所有支持的文件
markitdown ./文档库/ --recursive -o ./文档库-md/

输出目录不存在时会自动创建，已有的 .md 文件不会覆盖（加 --force 强制覆盖）。

第四步：只看文字，不看图片

有些场景你只需要纯文本，不要嵌入的图片：

markitdown 汇报.pdf --no-images -o 汇报纯文字.md

图片会以 URL 形式保留在 Markdown 里（）。

第五步：Python 脚本集成

如果你想在自动化流程里调用 markitdown，用 Python API：

from markitdown import MarkItDown

# 初始化转换器
converter = MarkItDown()

# 转换单个文件
result = converter.convert("技术规范.pdf")
print(result.text_content)  # 输出 Markdown 字符串

# 转换后写入文件
with open("技术规范.md", "w", encoding="utf-8") as f:
    f.write(result.text_content)

批量处理一个文件夹：

import os
from markitdown import MarkItDown

converter = MarkItDown()
input_dir = "./文档库"
output_dir = "./文档库-md"
os.makedirs(output_dir, exist_ok=True)

for filename in os.listdir(input_dir):
    if filename.endswith(('.pdf', '.docx', '.xlsx')):
        input_path = os.path.join(input_dir, filename)
        result = converter.convert(input_path)
        output_path = os.path.join(output_dir, filename.rsplit('.', 1)[0] + '.md')
        with open(output_path, "w", encoding="utf-8") as f:
            f.write(result.text_content)
        print(f"✅ 已转换：{filename}")

第六步：查看详细输出（含调试信息）

转换失败或者想看处理过程：

markitdown 文档.pdf --verbose -o 输出.md

效果对比

以一份含表格和代码块的 PDF 为例：

| 维度 | 手动复制 | markitdown | |------|----------|------------| | 操作时间 | 5-10 分钟 | 3 秒 | | 表格保留 | ❌ 要重新画 | ✅ GFM 表格 | | 代码块 | ❌ 纯文本 | ✅ 有语言标识 | | 标题层级 | ❌ 全是正文 | ✅ # / ## 层级对应 | | 图片处理 | ❌ 截图另存 | ✅ 自动嵌入路径 |

适用场景和局限

适用：

• 技术文档迁移（PDF → Markdown 进 GitHub）
• 批量归档（整个文件夹一口气转）
• 自动化流水线（接入 Python 脚本）

局限：

• 扫描版 PDF（图片转 PDF）无法提取文字，需要 OCR（如 pytesseract）
• 复杂排版（多栏、图文混排）的还原度不如 Word/HTML 原生格式
• 单次超过 100 页的大文件处理速度较慢（约 10-20 秒）

快速上手资源

• GitHub：microsoft/markitdown (https://github.com/microsoft/markitdown)
• PyPI：pip install markitdown
• 延伸工具：pandoc（更通用的格式转换，支持更多输入格式）

有问题或想看其他工具的实测，可以在评论区留言～