MarkItDown 的非官方繁體中文教學站。把整個 repo （程式碼、轉換器、CLI、外掛、MCP、Azure、測試）做成中英對照的解說內容，並收錄本站實際用 markitdown 產出的真實轉換輸出與用 graphify 掃描源碼的互動知識圖譜。
免責聲明：本站為第三方社群教學站，與 Microsoft / AutoGen Team 無關，不代表 MarkItDown 官方立場。 MarkItDown 為 Microsoft Corporation 的商標，本站僅在描述性／教學語境下使用該名稱。
上線網站：https://shumingyang-opencode.github.io/markitdown-zh-tw/
- 中英對照 — 中文口語解說為主文，英文原文與程式碼保留上游原貌。文件頁用「可展開的英文原文」，程式碼頁用「附中文註解的原始碼」。
- Python 逐函數講解 — 核心
_markitdown.py、CLI、converter 協定、Office/PDF/Web/Media 轉換器、OMML 數學、外掛與 MCP 套件，每個函數一個<details>收縮塊。 - 策展式教學而非鏡像 — 不逐檔翻譯，聚焦 22 個轉換器、調度管線、外掛系統、Azure 整合、MCP。
- 真實轉換輸出 — 本站用 markitdown 0.1.7 實跑 11 種格式（DOCX/XLSX/PPTX/PDF/HTML/CSV/JSON/圖片/音訊/ZIP/EPUB）的前後對照，含一次真實的失敗示範。
- meta 示範 — 用 markitdown 轉 markitdown 自己（dogfooding），並用 graphify 掃描源碼出互動知識圖譜（EN/ZH 雙版本）。
- 版本釘選 — 上游對齊
main @ fd239d5（發行版 v0.1.7）；所有實測數字為本站實際運行取得，可追溯。
純靜態站（HTML + CSS + JS），GitHub Pages 部署於 main 根目錄。
markitdown-zh-tw/
├── index.html 首頁：MarkItDown 是什麼、三大亮點、入口卡、版本徽章
├── map.html 概念地圖：converter/priority/StreamInfo/magika/plugin/MCP/Azure
├── learning-path.html 學習路線 L0→L4：可點卡片
├── install.html 安裝指南：pip extras、uv、conda、source、Docker、疑難排解
├── about.html 授權、方法、免責聲明
├── docs/
│ ├── index.html 文件教學入口（hub）
│ ├── how-it-works.html 運作原理（調度管線：猜測→排序→accepts→convert→標準化）
│ ├── architecture.html 架構總覽（4 套件 + 核心類別職責表）
│ ├── converters.html 22 個轉換器全覽表
│ ├── cli.html CLI 指令參考
│ ├── python-api.html Python API（5 個 convert_* + StreamInfo）
│ ├── plugins.html 外掛系統（entry-point + markitdown-ocr + sample-plugin）
│ ├── mcp.html markitdown-mcp（STDIO/HTTP/SSE、Docker、Claude Desktop、安全）
│ ├── cloud.html Azure Document Intelligence vs Content Understanding
│ ├── docker.html Docker 用法
│ ├── security.html 安全模型（I/O 權限、Sanitize、最窄 convert_*）
│ ├── worked.html 實作案例入口
│ ├── case/ 五個案例頁
│ └── code/ 程式碼對照（13 頁，逐函數 <details>）
│ ├── index.html 入口
│ ├── core.html _markitdown.py（MarkItDown 類別）
│ ├── cli.html __main__.py（argparse）
│ ├── base.html _base_converter.py（converter 協定）
│ ├── stream-info.html _stream_info/_uri_utils/_exceptions
│ ├── converters.html 協定實作 + 文字家族 + _markdownify
│ ├── office.html docx（含 OMML 數學）/ xlsx / pptx
│ ├── pdf.html _pdf_converter.py
│ ├── web.html youtube/wikipedia/rss/zip/epub/outlook
│ ├── media.html image/audio + exiftool/llm_caption/transcribe_audio
│ ├── cloud.html _doc_intel / _cu
│ ├── mcp.html markitdown-mcp 套件
│ └── ocr.html markitdown-ocr + markitdown-sample-plugin
├── worked/
│ ├── conversions/ 11 種格式的輸入樣本檔 + 轉換輸出 + README（含指令）
│ ├── dogfood/ MarkItDown 轉自己（README/pyproject/Dockerfile/GitHub 頁/PyPI 頁）
│ └── markitdown-source/ graphify 互動圖（graph.html + graph-zh.html）+ GRAPH_REPORT.md
├── scripts/
│ ├── generate-samples.py 產生各格式樣本輸入檔
│ └── localize-graph.py graph.html → graph-zh.html（UI 中文化）
├── assets/ site.css / favicon.svg
└── LICENSE / NOTICE / GITHUB_META.md / .github/workflows/check-upstream.yml
每個案例都是「中文解說 + 真實輸出 + 本站跑的數字 + 重現步驟」。
| 案例 | 內容 | 來源方式 | 本站數字/結果 |
|---|---|---|---|
| Office 轉換 | DOCX / XLSX / PPTX | 本站實跑 0.1.7 | 標題/清單/表格全保留；Excel 合併列會併入表格 |
| PDF + 網頁 | PDF / HTML / CSV / JSON | 本站實跑 0.1.7 | PDF 抽取順序依版面；HTML 最擅長 |
| 媒體 + 封裝 | 圖片 / 音訊 / ZIP / EPUB | 本站實跑 0.1.7 + exiftool 13.59 | 圖片 EXIF ✅；音訊純音調 → UnknownValueError（真實失敗示範） |
| Dogfood | README / pyproject / Dockerfile / GitHub 頁 / PyPI 頁 | 本站實跑 0.1.7 | 純文字近乎無損；通用 HTML 會帶導覽雜訊 |
| graphify 掃描 | markitdown 源碼（77 程式檔） | 本站實跑 graphify 0.9.40 --code-only |
907 節點 / 1,967 邊 / 71 社群 |
所有案例都是真實工具產出，不是示意圖。這是「用轉換工具分析轉換工具、用知識圖譜工具分析轉換工具」的 meta 示範。
# 0. 建立 uv 虛擬環境，從對齊 commit 的源碼安裝
uv venv .venv --python 3.12
uv pip install -p .venv -e "<markitdown>/packages/markitdown[all]"
# 1. 產生樣本輸入檔（python-docx / openpyxl / python-pptx / reportlab / Pillow / piexif）
.venv/Scripts/python scripts/generate-samples.py
# 2. 逐一轉換（以 docx 為例）
.venv/Scripts/markitdown worked/conversions/office/sample-report.docx -o out.md
# 3. 圖片/音訊中繼資料需 exiftool（以 EXIFTOOL_PATH 指定）
EXIFTOOL_PATH=/path/to/exiftool .venv/Scripts/markitdown worked/conversions/media/photo.jpg -o out.md.venv/Scripts/markitdown "https://raw.githubusercontent.com/microsoft/markitdown/fd239d5d2be43d9b68329730206b9312c7d5a388/README.md" -o worked/dogfood/readme.md
.venv/Scripts/markitdown <markitdown>/packages/markitdown/pyproject.toml -o worked/dogfood/pyproject.md
.venv/Scripts/markitdown https://github.com/microsoft/markitdown -o worked/dogfood/github-page.mdgit clone https://github.com/microsoft/markitdown.git
git -C markitdown checkout fd239d5d2be43d9b68329730206b9312c7d5a388
mkdir -p raw/corpus && cp -R markitdown/packages raw/corpus/ && cp markitdown/Dockerfile raw/corpus/
graphify extract raw/corpus --code-only --no-gitignore # raw/ 在 .gitignore 故需 --no-gitignore
graphify cluster-only raw/corpus --no-label # → graph.html + GRAPH_REPORT.md
cp raw/corpus/graphify-out/graph.html worked/markitdown-source/
cp raw/corpus/graphify-out/GRAPH_REPORT.md worked/markitdown-source/
python scripts/localize-graph.py # → graph-zh.html（中文化界面）- 本站內容以 MIT License 釋出（與上游相同），並照抄上游的授權檔：
- 商標：MarkItDown 與 Microsoft 為 Microsoft Corporation 或其關聯公司之商標。MIT 授權不含商標授權； 本站僅在「描述性／教學」語境使用該名稱，並於全站 footer 標示「與 Microsoft 無關」。
- graphify 產出：
worked/markitdown-source/的互動圖與報告由 graphify（Apache-2.0）產生，案例頁已標註出處。 - 不做二進位散布：本站不含官方二進位，僅引述實際運行輸出；樣本輸入檔為本站自製，轉換輸出以 markitdown 實跑取得。
- 本站對齊上游分支
main，釘選 commitfd239d5（發行版 v0.1.7）。 .github/workflows/check-upstream.yml每月自動（每月 1 日 00:00 UTC + 手動觸發）檢查上游最新 SHA，並更新首頁的版本徽章。
靜態站，純 HTML + CSS + JS，無框架、無建置步驟。
python -m http.server 8000 # 本機預覽assets/site.css— 全站樣式（深色 × 霓虹設計語言，承襲 codegraph-zh-tw / graphify-zh-tw）- 每個 HTML 頁都是自含檔案（head 引入 site.css + Google Fonts）
worked/<slug>/— 案例資產與說明
- 準備樣本：
python scripts/generate-samples.py（或自備檔案）。 - 轉換：
markitdown <file> -o out.md實跑（可加-x/-m/-c提示）。 - 收錄：輸入檔 + 輸出
.md放進worked/conversions/<group>/。 - 建案例頁：依
docs/case/*.html模板（中文解說 + 輸入/輸出對照 + 本站觀察 + 重現步驟）。 - 更新
docs/worked.html的案例卡與「實作案例總覽」表。
- 圖片/音訊：EXIF 需要 exiftool；描述/OCR 需要
llm_client + llm_model；音訊轉錄需要真人語音 + 網路 + Google API。缺任一條件會「空輸出」或「失敗降級」——見媒體案例。 - PDF：無語意結構，抽取順序依版面；掃描檔/複雜表格是弱點，高品質需求請用 Azure Content Understanding。
- 通用 HTML：沒有專用 converter 的網站（如 GitHub/PyPI 頁）會帶入導覽雜訊——見dogfood 案例。
- Azure：兩條雲端路徑需資源與計費，本站不實跑，僅翻譯對照官方文件。
- graphify 社群命名：本機無 LLM key，社群名稱保留「社群 N」placeholder。
相關連結
- 上游 repo：microsoft/markitdown（MIT）
- PyPI：
markitdown·markitdown-mcp·markitdown-ocr·markitdown-sample-plugin - 本站 repo：shumingyang-opencode/markitdown-zh-tw
- 本站上線：shumingyang-opencode.github.io/markitdown-zh-tw
- 學習路徑建議服務：learning-path-advisor — 依角色推薦教學網站學習路徑