← 文件教學

架構總覽

四個套件 + 一條調度鏈

套件組成

repo 用 monorepo 結構，packages/ 下有四組獨立套件（都可各自 pip 安裝）：

套件PyPI 名稱職責
packages/markitdown/markitdown核心：MarkItDown 類別 + 22 個內建轉換器 + CLI
packages/markitdown-mcp/markitdown-mcpMCP Server：把核心包成 convert_to_markdown(uri) 工具
packages/markitdown-ocr/markitdown-ocrOCR 外掛：LLM Vision 抽取 PDF/DOCX/PPTX/XLSX 內嵌圖片文字
packages/markitdown-sample-plugin/markitdown-sample-plugin外掛開發範本：RtfConverter 完整範例

核心類別職責表

類別 / 模組檔名職責
MarkItDown_markitdown.py對外入口：註冊 converter、5 個 convert_* 方法、調度核心 _convert()、StreamInfo 猜測
DocumentConverter_base_converter.py所有轉換器的抽象父類：定義 accepts() / convert() 協定與 priority
DocumentConverterResult_base_converter.py轉換結果：markdown / text_content / title
ConverterRegistration_markitdown.pyconverter + priority 的註冊資料（frozen dataclass）
StreamInfo_stream_info.py檔案的「線索卡」：mimetype / extension / charset / filename / url
converters/converters/*.py22 個內建轉換器，各自實作 accepts/convert
converter_utils/converter_utils/docx/*DOCX 前處理工具：OMML（Office Math）→ LaTeX
__main__.py__main__.pyCLI：argparse 解析 → 建 MarkItDown → 呼叫 convert
_exceptions.py_exceptions.py例外層：FileConversionException / UnsupportedFormatException / MissingDependencyException

依賴方向

CLI (__main__) ──→ MarkItDown ──→ converters/（22 個）──→ 第三方函式庫（mammoth / pdfminer / openpyxl…）
                        │  └──→ _stream_info / magika / charset-normalizer（型別猜測）
                        └──→ plugin entry-point（markitdown.plugin）──→ markitdown-ocr 等外掛
markitdown-mcp ──→ MarkItDown（convert_to_markdown 工具）
markitdown-ocr ──→ MarkItDown（在 priority -1.0 註冊 OCR 增強 converter）

模組結構速查

packages/markitdown/ ├── src/markitdown/ │ ├── __main__.py CLI（argparse） │ ├── _markitdown.py MarkItDown 類別（核心） │ ├── _base_converter.py DocumentConverter / DocumentConverterResult │ ├── _stream_info.py StreamInfo │ ├── _uri_utils.py data:/file: URI 解析 │ ├── _exceptions.py 例外層 │ ├── converters/ 22 個內建轉換器 │ │ ├── _plain_text_converter.py │ │ ├── _html_converter.py / _markdownify.py │ │ ├── _pdf_converter.py │ │ ├── _docx_converter.py │ │ ├── _xlsx_converter.py │ │ ├── _pptx_converter.py │ │ ├── _image_converter.py / _llm_caption.py / _exiftool.py │ │ ├── _audio_converter.py / _transcribe_audio.py │ │ ├── _zip_converter.py / _epub_converter.py / _outlook_msg_converter.py │ │ ├── _csv_converter.py / _ipynb_converter.py │ │ ├── _rss_converter.py / _wikipedia_converter.py / _youtube_converter.py / _bing_serp_converter.py │ │ └── _doc_intel_converter.py / _cu_converter.py（Azure） │ └── converter_utils/docx/ OMML 數學前處理（latex_dict.py / omml.py） └── tests/ 測試

設計要點