MarkItDown 可把 PDF、Word 等文件轉成 Markdown,適合整理檔案給 AI 閱讀的人;從本機指令開始,但轉換成功不代表文字與表格完整。
安裝與執行環境
工具版本 0.1.9;官方文件查閱日 2026-11-16。套件版本與官方文件快照分別固定,不把文件 commit 宣稱為套件發行 commit。
先用 python -m venv .venv 建專案虛擬環境,依自己的 shell 啟用後安裝。既有 Python 實測為 Linux/Python 3.12,其他作業系統未本地驗證。
python -m pip install "markitdown[pdf,docx]==0.1.9"
markitdown --help
markitdown report.pdf -o report.md
這個安裝路線是 CLI/Python 函式庫,安裝後不會自動變成 MCP server。先在專案環境執行範例,再把輸出檔交給 AI。
- Claude Code: 在專案開啟對話,指定範例程式或產物檔名,執行前核對 Python 路徑。
- Codex: 開啟相同工作區,指定程式/輸出檔,請它檢查或依本機允許範圍執行。
- Cursor: 選專案的 Python interpreter,在終端執行指令,再把輸出檔附到對話。
這是檔案與終端工作流程,不宣稱有專用整合;三個客戶端介面未本地實測。
三個實際用途
1. 把 PDF 轉成可讀文字
markitdown report.pdf -o report.md
預期結果:打開 report.md,確認主要段落與數字;影像 PDF 可能沒有文字。
2. 整理 Word 會議紀錄
markitdown meeting.docx -o meeting.md
預期結果:應得到 Markdown;表格要逐欄核對。
3. 交給 AI 做有依據的摘要
讀取 meeting.md,整理決策、負責人、期限,各項附原文引句;原文沒寫的欄位填「未提供」,先列出疑似轉換錯誤。
預期結果:應看到可回查原文的清單,不替缺漏內容補答案。
實測發現:哪些已確認,哪些還沒測
0.1.9 的四種隔離轉換中,可選取文字的 PDF 保留句子;沒有文字層的 PDF 雖回傳成功,只有空白輸出。HTML 表頭保留,Word 範例欄名落在資料列。OCR、Azure 與其他格式未測。
測試由 Codex 以合成資料執行,不宣稱站長親測或審稿。上方新增操作若未落在上述範圍,均為依官方文件整理、未本地實測。
常見錯誤與解法
輸出空白但沒有報錯
先確認 PDF 有可選取文字;需要 OCR 時另走支援 OCR 的流程,並加上非空與已知句檢查。
Word 欄名跑到資料列
檢查原始 Word 表格設定與輸出;後續會解析欄位時改用結構化工具並保留原檔。
缺少轉換器或相依套件
只安裝基本套件不包含所有格式;依官方 extras 加裝需要的格式,並在同一 Python 環境執行。
限制、費用與授權
MIT。此本機路線不需要模型 API;選用雲端辨識或模型功能時,其帳戶、資料傳送與費用另計。Markdown 並非原版面重建,圖片與複雜表格需人工或程式驗收。
何時改用其他工具
-
需要文件層級與結構化表格:Docling。
-
只處理 PDF 並要 Python API:PyMuPDF4LLM。
常見問答
MarkItDown 是 Microsoft 的嗎?
是,本文指官方 microsoft/markitdown 開源專案。
MarkItDown 本身是 MCP 嗎?
本頁先用核心 CLI;MCP 是另一個包裝與部署路線,不能把裝好 CLI 當成已接 MCP。
可以不用上傳文件嗎?
可以,本頁基本轉換在本機執行;不要啟用需要外部 API 的選配功能。
官方來源
若表格結構會影響後續程式,可比較 Docling 的表格保留方式;PDF 輸入可另看 PyMuPDF4LLM 的解析流程。