# MarkItDown 安裝與使用筆記

## 基本資訊

- **專案**: https://github.com/microsoft/markitdown
- **版本**: 0.1.5
- **作者**: Microsoft
- **授權**: MIT
- **需求**: Python 3.10+
- **安裝日期**: 2026-04-15

## 安裝

```bash
# 基本安裝
pip install markitdown

# 完整安裝（所有格式支援）
pip install 'markitdown[all]'
```

### 個別功能模組

```bash
pip install 'markitdown[pdf]'                    # PDF
pip install 'markitdown[docx]'                   # Word
pip install 'markitdown[pptx]'                   # PowerPoint
pip install 'markitdown[xlsx]'                   # Excel（新版）
pip install 'markitdown[xls]'                    # Excel（舊版）
pip install 'markitdown[outlook]'                # Outlook 郵件
pip install 'markitdown[audio-transcription]'    # 音訊轉文字
pip install 'markitdown[youtube-transcription]'  # YouTube 字幕
pip install 'markitdown[az-doc-intel]'           # Azure Document Intelligence
```

## 支援的檔案格式

| 格式 | 說明 |
|------|------|
| PDF | PDF 文件 |
| DOCX | Word 文件 |
| PPTX | PowerPoint 簡報 |
| XLSX / XLS | Excel 試算表 |
| HTML | 網頁 |
| CSV / JSON / XML | 文字結構化資料 |
| 圖片 | EXIF 元資料 + OCR |
| 音訊 | 元資料 + 語音轉文字 |
| ZIP | 自動解壓處理內容 |
| EPUB | 電子書 |
| YouTube URL | 影片字幕擷取 |

## CLI 使用

```bash
# 基本轉換
markitdown document.pdf > output.md

# 指定輸出檔
markitdown document.pdf -o output.md

# 從 stdin 讀取
cat document.pdf | markitdown

# 搭配 Azure Document Intelligence
markitdown file.pdf -o output.md -d -e "<endpoint>"

# 外掛管理
markitdown --list-plugins
markitdown --use-plugins file.pdf
```

## Python API

### 基本用法

```python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)
```

### 搭配 LLM 做圖片描述

```python
from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("photo.jpg")
print(result.text_content)
```

### 搭配 Azure Document Intelligence

```python
md = MarkItDown(docintel_endpoint="<endpoint>")
result = md.convert("scan.pdf")
```

## 外掛系統

外掛預設關閉，需明確啟用。

### markitdown-ocr 外掛

用 LLM vision 對 PDF、DOCX、PPTX、XLSX 做 OCR，不需額外 ML 套件：

```bash
pip install markitdown-ocr openai
```

第三方外掛可在 GitHub 搜尋 `#markitdown-plugin` 找到。

## MCP 整合

MarkItDown 提供 MCP server，可整合到 Claude Desktop 等 LLM 應用：

```bash
pip install markitdown-mcp
```

## Docker

```bash
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < file.pdf > output.md
```