PDF 丟進 LLM 前要先做什麼？轉文字。Word 呢？也是轉文字。PowerPoint？一樣。問題來了：轉成純文字會丟掉所有結構——標題層級沒了、表格扁平化了、清單變成一坨散文。LLM 拿到這種東西，理解力直接打折。

微軟的 MarkItDown 就是為了解決這個前處理痛點而生的。一行指令，把幾乎任何格式的檔案轉成 Markdown，保留標題、表格、清單的結構。97K+ stars，MIT 授權，三行 code 就能用。

為什麼是 Markdown 而不是純文字

主流 LLM 的訓練資料裡大量包含 Markdown。對模型來說，收到一份有 ## 標題和 | 表格的 Markdown，比收到一坨沒結構的純文字好懂太多，token 數也不會明顯增加。

MarkItDown 的定位很明確：不做高保真的文件格式互轉（那是 Pandoc 的事），專門為 LLM 管線設計的前處理工具。犧牲排版的視覺還原度，換取語意結構的完整保留。

支援哪些格式

覆蓋面有夠廣：

  • 文件類：PDF、Word（.docx）、PowerPoint（.pptx）、Excel（.xlsx / .xls）
  • 網頁與資料：HTML、CSV、JSON、EPub
  • 多媒體：圖片（JPEG / PNG，搭配 LLM 做圖片描述）、音訊（WAV / MP3，語音轉文字）、YouTube（自動抓字幕）
  • 其他：ZIP（遞迴處理內部所有檔案）、Outlook MSG、Jupyter Notebook、Wikipedia URL

另外還能接 Azure Document Intelligence 處理 OCR 和公式提取，共 9 種格式。

三種使用方式

CLI：最直接

1
2
3
4
5
6
7
8
# 一行搞定
markitdown report.pdf > report.md

# 指定輸出
markitdown presentation.pptx -o slides.md

# 管道輸入也行
cat document.docx | markitdown

Python API：三行就能用

1
2
3
4
5
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("report.pdf")
print(result.text_content)

沒有什麼設定要調，沒有什麼 config 要寫。裝完就是能用。

MCP Server：讓 Claude 直接讀各種檔案

這是跟 Claude Code / Claude Desktop 搭配最方便的用法。裝完 MCP server 套件後，跟 Claude 說「幫我分析這份 PDF」，它會自動透過 MCP 把 PDF 轉成 Markdown 再處理。

1
pip install markitdown-mcp

提供一個 convert_to_markdown(uri) 工具，支援 STDIO、Streamable HTTP、SSE 三種模式。

LLM 圖片描述整合

處理 PowerPoint 投影片時，裡面的截圖和圖表怎麼辦？MarkItDown 可以接一個 OpenAI 相容的 client，自動用 LLM 生成圖片描述：

1
2
3
4
5
6
7
8
9
10
11
12
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="用繁體中文描述這張圖片的內容"
)

# PPTX 裡的圖片也會被描述
result = md.convert("quarterly-review.pptx")

不限定 OpenAI，任何符合 chat completion API 介面的 client 都能用——Ollama、vLLM、Azure OpenAI 都行。

Plugin 機制

用 Python 標準的 entry_points 做 plugin 發現。想支援新格式？寫一個 converter 註冊就好。

官方已有的 plugin：

  • markitdown-ocr — 用 LLM Vision 做 OCR，能提取 PDF 和 PPTX 裡內嵌圖片的文字
  • markitdown-sample-plugin — 開發範本

Plugin 預設停用，需要明確啟用：

1
markitdown --use-plugins document.pdf

架構設計

整個轉換流程很直觀：輸入檔案 → StreamInfo 猜測格式（副檔名 + MIME + Magika AI）→ 按優先級遍歷 Converter → accepts() 回 true 就執行 convert() → 輸出 Markdown。

每個 converter 只要實作 accepts() 和 convert() 兩個方法。Plugin 可以用較低的優先級數字搶先內建 converter，比如 markitdown-ocr 就是這樣取代內建的 PDF converter。

跟其他工具比一下

特性 MarkItDown Pandoc Docling
定位 LLM 前處理 通用格式互轉 文件理解平台
輸出 僅 Markdown 數十種格式 Markdown / JSON
LLM 整合 原生支援 無 有
MCP Server 有（官方套件） 無 無
重點 結構保留 + token 效率 高保真格式互轉 深度文件理解

要高保真格式互轉選 Pandoc，要深度文件理解選 Docling，要快速把檔案餵給 LLM——MarkItDown 就對了。

實際使用情境

RAG 前處理是最常見的場景。把各種格式的知識庫文件統一轉成 Markdown，再做 chunking 和 embedding。ZIP converter 可以遞迴處理整個壓縮檔，裡面混合 PDF、DOCX、PPTX 都沒問題。

投影片內容提取也很實用。PPTX 轉 Markdown 時會保留投影片編號、標題、表格和圖表數據。搭配 LLM 圖片描述，連投影片裡的截圖都能「讀懂」。

MCP 整合的 AI 助手——透過 markitdown-mcp，讓 Claude Desktop 或 Claude Code 直接讀取任何格式的檔案，你只要說「幫我分析這份報告」就行。

安裝

1
2
3
4
5
# 一次裝全部格式支援
pip install 'markitdown[all]'

# 或者只裝你需要的
pip install 'markitdown[pdf,docx,pptx,xlsx]'

需要 Python >= 3.10。音訊轉寫另外裝 ffmpeg，EXIF 提取裝 exiftool。

限制

幾個要注意的地方。PDF 複雜排版（多欄、浮動圖片）可能丟失結構，最壞情況只能提取純文字。不支援舊版 .doc 格式，只吃 .docx。圖片僅 JPEG/PNG，WebP 和 SVG 不行。數學公式支援不完整。目前沒有 async API，大量檔案處理得自己管併發。

不過對大多數「把文件餵給 LLM」的場景來說，這些限制幾乎碰不到。三行 code 就能解決 80% 的文件前處理需求，這個投入產出比很划算。

原文來源：MarkItDown GitHub Repo
參考來源：MarkItDown MCP Server (PyPI)