學習路線

從「裝起來」到「讀懂源碼」的五層路徑——每層都是可點卡片
L0 · 裝好 安裝與環境 5 分鐘
pip extraspip install 'markitdown[all]' 一次裝滿；或按格式選配 [pdf] [docx] [pptx] [xlsx]… uv / conda / sourceuv tool install markitdown、conda create、git clone 後 pip install -e 的三種途徑。 Dockerdocker build -t markitdown:latest . 後以 stdin 管道餵檔。 周邊套件markitdown-mcp（MCP Server）與 markitdown-ocr（OCR 外掛）的安裝。
L1 · 跑起來 CLI 與 Python API 15 分鐘
CLI 基本用法markitdown file.pdf > out.md、-o 輸出檔、stdin 管道輸入。 CLI 進階旗標-x / -m / -c 提示型別、-d 與 --use-cu 雲端轉換、-p 開外掛。 Python APIMarkItDown().convert() 一行轉換，result.markdown / text_content 取結果。 5 個 convert_*convert / convert_local / convert_stream / convert_uri / convert_response 的取捨。
L2 · 玩轉格式 22 個轉換器全覽 30 分鐘
Office 家族DOCX（mammoth+OMML 數學）、XLSX/XLS（pandas）、PPTX（python-pptx）的輸出結構。 PDF 家族pdfminer.six + pdfplumber 分工；表格抽取與限制。 Web / 網址HTML、RSS、Wikipedia、YouTube、Bing SERP——直接餵 URL。 Media / 封裝圖片（EXIF+LLM 描述）、音訊（EXIF+轉錄）、ZIP、EPUB、CSV、JSON、iPython、Outlook。 實作案例本站以 markitdown 0.1.7 實跑 11 種格式的真實前後對照。
L3 · 讀原理 調度管線與設計 1 小時
調度管線StreamInfo 猜測 → magika 內容偵測 → priority 排序 → accepts → convert → 標準化。 容錯鏈converter 失敗被記錄為 FailedConversionAttempt，最後統一拋 FileConversionException。 外掛系統entry-point 群組 markitdown.plugin + register_converters()，如何攔截/取代內建 converter。 安全模型I/O 權限等同目前程序、Sanitize inputs、只用最窄的 convert_* 函數。 MCP 整合markitdown-mcp 用 convert_to_markdown(uri) 把工具接到任何 MCP agent。
L4 · 讀源碼 逐函數程式碼對照 自行安排
MarkItDown 類別_markitdown.py：註冊、_get_stream_info_guesses、_convert 調度核心。 Converter 協定DocumentConverter / accepts / convert 介面與轉換器目錄。 Office 轉換器docx（converter_utils 含 OMML→LaTeX）、xlsx、pptx 內部。 PDF 轉換器pdfminer/pdfplumber 分工與 masterformat 表格處理。 OCR / 外掛套件markitdown-ocr 的 LLMVisionOCRService 與 sample-plugin 開發範本。