程式碼對照 · converters/ 概覽 · MarkItDown 繁中教學站

大方向

converters/ 每個檔都實作 accepts() + convert()。本頁看「最簡單的範例」（PlainText / Csv / Ipynb）與「被很多 converter 共用的 _markdownify」； Office / PDF / Web / Media / Azure 的細節在各自專頁。

1. PlainTextConverter — 最簡協定範例

accepts() / convert() PlainTextanything with content type text/plain。

用 stream_info.mimetype 前綴 text/plain（或 text/*）判斷； convert 用 charset-normalizer 解碼 bytes → 回傳 Markdown 原文。這是「兜底」converter——裝 [all] 後所有純文字檔都會落回它。

2. CsvConverter

__init__ / accepts / convert CSV把 CSV 讀成 Markdown 表格。

constructor 用 csv.Sniffer 猜分隔符（逗號/分號/Tab…）；accepts 看 mimetype 含 text/csv 或 extension .csv；convert 讀全部列，首列當表頭、其餘當資料列輸出 | a | b | 表格。

3. IpynbConverter — 懂 JSON 的 converter

accepts / convert / _convert(notebook_content) Jupyter把 .ipynb（JSON）解析成 cells 的 Markdown。

用 json.load 讀 notebook，依 cell type（markdown/code）輸出； code cell 顯示原始碼與執行結果。示範了「檔案格式其實是 JSON，直接用 json 模組解析」的做法。

4. _markdownify.py — HTML→Markdown 的客製引擎

_CustomMarkdownify(markdownify.MarkdownConverter) 共用覆寫 markdownify 的標題/連結/圖片/checkbox 轉換規則。

markdownify 是 HTML→Markdown 函式庫，這裡覆寫四個行為：

convert_hn — 標題保留為 #（含 lang 屬性處理）。
convert_a — 保留連結，但移除 javascript: 連結、轉義 URI。
convert_img — 圖片輸出 ![alt](src)，處理 data URI（可截斷）。
convert_input — checkbox 轉成 [x]/[ ]。
convert_soup — 整個 soup 的轉換入口。

HtmlConverter 與所有繼承它的 converter（Docx、Epub…）都共用這套規則。