程式碼對照 · 網頁與封裝家族 · MarkItDown 繁中教學站

大方向

這家族分兩種：URL 專用 converter（YouTube / Wikipedia / RSS）在 accepts 裡看 stream_info.url 決定接單，只取正文/標題/字幕；容器 converter （ZIP / EPUB / Outlook .msg）把一包東西拆開遞迴處理。

1. YouTubeConverter — URL 專用

accepts / convert / _get / _findKey / _retry_operation YouTube抓影片標題、描述、字幕，輸出 Markdown。

accepts 看 URL 是否 youtube.com / youtu.be。convert 用 youtube-transcript-api 抓字幕（需要 [youtube-transcription] extra），並抓頁面 meta 取標題/描述。有趣的工程細節：

_findKey(json, key) — 遞迴搜尋 YouTube 嵌入 JSON 的巢狀 key。
_retry_operation — 對容易失敗的網路操作做 3 次重試、延遲 2 秒。

2. WikipediaConverter — 只取正文

accepts / convert Wikipedia對 wikipedia.org 頁面只取「主文內容」。

URL 以 wikipedia.org/wiki/ 開頭才接；convert 抓頁面後只保留正文節點，丟掉導覽/側欄/頁尾——這是「專用 converter 為何存在」的最佳例子。

3. RssConverter — XML 雙格式

accepts / _check_xml / _feed_type / convert / _parse_atom_type / _parse_rss_type / _parse_content / _get_data_by_tag_name RSS/Atom用 defusedxml 安全解析 RSS 或 Atom feed。

_check_xml 先偷讀串流前幾個位元組確認是 <?（XML）； _feed_type 依 root element 判斷 rss 或 feed（Atom），再分派到 _parse_rss_type / _parse_atom_type，輸出各項目標題/連結/內容。

4. ZipConverter — 遞迴容器

__init__(markitdown) / accepts / convert ZIP解壓到暫存目錄，用同一 MarkItDown 實例逐檔遞迴轉換。

constructor 接收 markitdown 本身（拿來遞迴轉換子檔）；accepts 看 application/zip / .zip。輸出以 ## File: <路徑> 分節、維持原始結構、結束後清理暫存目錄（tempfile.TemporaryDirectory）。

5. EpubConverter（繼承 HtmlConverter）

accepts / convert / _get_text_from_node / _get_all_texts_from_nodes EPUBcontainer.xml → content.opf → spine 逐章轉換。

用 defusedxml.minidom 安全解析：META-INF/container.xml 找 content.opf 路徑 → 解析 metadata（title/authors/language…）與 manifest/spine → 依 spine 順序把每章 XHTML 用內部的 HtmlConverter 轉 Markdown。輸出最前面插入 **Title:** ... 中繼資料。

6. OutlookMsgConverter — 會偷讀串流的 converter

accepts / convert / _get_stream_data Outlook .msg用 olefile 讀 .msg 的郵件標頭與內文。

docstring 特別提到它是「accepts 需要讀 stream 才能判斷」的例子——判斷 .msg 的 OLE 結構後 務必把 stream 位置復原。輸出 From/To/Subject 標頭 + 內文。