微軟 MarkItDown 使用教學：文件轉 Markdown，做 AI 知識庫更方便

微軟的 microsoft/markitdown 是一個把多種檔案轉換成 Markdown 的 Python 工具。它的目標不是做高保真排版還原，而是把文件、表格、網頁、圖片、音訊等資料變成更適合 LLM、RAG、搜尋索引和文字處理流程使用的 Markdown。

專案地址：

https://github.com/microsoft/markitdown

如果你經常需要把 PDF、Word、Excel、PowerPoint、網頁、圖片或壓縮檔裡的資料交給大模型分析，MarkItDown 很適合放在預處理環節。它輸出的是純文字 Markdown，比直接把二進位檔案塞進流程裡更容易除錯、切分、檢索和存檔。

MarkItDown 支援什麼

根據官方 README，MarkItDown 支援的輸入類型包括：

PDF
PowerPoint
Word
Excel
圖片，包括 EXIF 元資料和 OCR
音訊，包括 EXIF 元資料和語音轉寫
HTML
CSV、JSON、XML
ZIP 檔案，會遍歷其中內容
YouTube URL
EPUB

它的定位很明確：把檔案轉換成 Markdown，方便下游的 LLM 和文字工作流使用。不要把它當成一個嚴格保留版式的文件轉換器。對於履歷、合約、掃描件、產品資料、會議錄音、網頁快照這類素材，重點通常不是還原每個像素，而是提取出能被模型穩定理解的文字結構。

安裝命令

最簡單的安裝方式是直接用 pip：

1

pip install markitdown

如果需要使用全部可選功能，可以安裝 all 額外依賴：

1

pip install 'markitdown[all]'

如果只想安裝特定格式支援，也可以按需安裝 extra。例如 PDF、DOCX、PPTX：

1

pip install 'markitdown[pdf,docx,pptx]'

如果想從原始碼安裝：

1
2
3


git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

命令列用法

安裝後可以直接使用 markitdown 命令。最基礎的用法是把檔案轉換到標準輸出：

1

markitdown path-to-file.pdf

儲存為 Markdown 檔案：

1

markitdown path-to-file.pdf -o output.md

轉換 Office 文件：

1
2
3


markitdown report.docx -o report.md
markitdown slides.pptx -o slides.md
markitdown data.xlsx -o data.md

轉換網頁：

1

markitdown https://example.com -o page.md

轉換 YouTube URL：

1

markitdown https://www.youtube.com/watch?v=VIDEO_ID -o video.md

處理 ZIP 檔案：

1

markitdown archive.zip -o archive.md

這些命令適合先手動驗證效果。確認輸出結構符合預期後，再把它放進自動化腳本、知識庫匯入流程或 RAG pipeline。

Python API 用法

MarkItDown 也可以作為 Python 函式庫使用。官方 README 給出的基本方式是建立 MarkItDown 實例，然後呼叫 convert：

1
2
3
4
5


from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

如果要接入 OpenAI 客戶端做圖片描述，可以把客戶端傳給 MarkItDown：

1
2
3
4
5
6
7


from openai import OpenAI
from markitdown import MarkItDown

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

這個能力適合處理圖片型資料，例如截圖、掃描圖片、包含圖表的頁面。實際使用時要注意成本、隱私和網路請求，尤其是處理內部文件時。

Docker 用法

如果不想污染本機 Python 環境，可以用 Docker 執行。官方 README 提供了映像建置方式：

1

docker build -t markitdown:latest .

然後把目前目錄掛載到容器裡執行轉換：

1

docker run --rm -v .:/workdir markitdown:latest path-to-file.pdf -o output.md

這種方式適合伺服器、CI 或臨時批次處理環境。缺點是除錯依賴會比本機 Python 環境稍慢一點。

外掛機制

MarkItDown 支援外掛，但預設不會啟用第三方外掛。查看外掛：

1

markitdown --list-plugins

啟用外掛：

1

markitdown --use-plugins path-to-file.foo -o output.md

在 Python 中啟用外掛：

1
2
3
4
5


from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)
result = md.convert("example.foo")
print(result.text_content)

外掛適合擴展私有格式、內部文件格式或特定業務系統匯出的檔案。需要注意的是，外掛本質上是執行額外程式碼，來源不可信時不要隨便啟用。

適合放在哪些流程裡

我更推薦把 MarkItDown 放在這些場景：

把 PDF、DOCX、PPTX、XLSX 統一轉成 Markdown，再進入知識庫。
把網頁、YouTube、EPUB 等資料轉成可檢索文字。
做 RAG 前的文件預處理，先得到更容易切分的 Markdown。
把資料轉換結果提交給 Codex、Claude Code、Cursor 這類工具閱讀。
批次整理歷史文件，生成統一的 .md 中間格式。

一個簡單流程可以是：

1
2


mkdir -p markdown
markitdown input.pdf -o markdown/input.md

如果要批次處理目錄，可以先用腳本枚舉檔案，再逐個呼叫 markitdown。轉換後建議人工抽查幾份輸出，尤其是表格、掃描件、複雜版式 PDF 和多欄文件。

使用邊界

MarkItDown 很實用，但要注意幾個邊界：

複雜 PDF 的閱讀順序不一定完美，特別是多欄、註腳、頁首頁尾很多的檔案。
OCR 和圖片描述依賴額外元件或 LLM，效果和成本都要單獨評估。
Markdown 適合表達文字結構，但不適合保留精確排版。
外掛和 LLM 處理內部檔案時，要注意資料安全。
轉換結果最好作為中間產物，不要預設等同於原文。

如果目標是「讓大模型讀懂資料」，MarkItDown 的方向是對的：先把各種檔案變成統一的 Markdown，再做清洗、切分、索引和問答。它不是萬能轉換器，但作為 LLM 文件入口工具，已經足夠清晰、輕量，也方便接進現有 Python 工作流。