markitdown

MarkItDown スキル

LLM やテキスト分析のパイプライン向けに、さまざまなファイル形式を Markdown に変換する Microsoft の Python ユーティリティです。

概要

MarkItDown は、構造（見出し、リスト、表、リンク）を保持したままドキュメントを変換します。人間が読みやすい出力ではなく、LLM が利用しやすい出力に最適化されています。

対応形式

カテゴリ	形式
ドキュメント	PDF、Word（DOCX）、PowerPoint（PPTX）、Excel（XLSX、XLS）
メディア	画像（EXIF + OCR）、音声（WAV、MP3 の文字起こし）
Web	HTML、YouTube URL、Wikipedia、RSS/Atom フィード
データ	CSV、JSON、XML、Jupyter ノートブック（.ipynb）
アーカイブ	ZIP（内容を順に処理）、EPub
メール	Outlook MSG ファイル

クイックスタート

インストール

# Full installation (recommended)
pip install 'markitdown[all]'

# Minimal with specific formats
pip install 'markitdown[pdf,docx,pptx]'

# Using uv
uv pip install 'markitdown[all]'

オプションの依存関係

Extra	説明
[all]	すべてのオプションの依存関係
[pdf]	PDF ファイルのサポート
[docx]	Word ドキュメント
[pptx]	PowerPoint プレゼンテーション
[xlsx]	Excel スプレッドシート
[xls]	旧形式の Excel ファイル
[outlook]	Outlook MSG ファイル
[az-doc-intel]	Azure Document Intelligence
[audio-transcription]	WAV/MP3 の文字起こし
[youtube-transcription]	YouTube 動画の文字起こし

コマンドラインの使用方法

# Basic conversion
markitdown document.pdf > output.md

# Specify output file
markitdown document.pdf -o output.md

# Pipe input
cat document.pdf | markitdown > output.md

# With Azure Document Intelligence
markitdown document.pdf -o output.md -d -e "<endpoint>"

Python API

from markitdown import MarkItDown

# Basic conversion
md = MarkItDown()
result = md.convert("document.xlsx")
print(result.text_content)

# With LLM for image descriptions
from openai import OpenAI

client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Describe this image in detail"
)
result = md.convert("image.jpg")
print(result.text_content)

# With Azure Document Intelligence
md = MarkItDown(docintel_endpoint="<your-endpoint>")
result = md.convert("complex-document.pdf")
print(result.text_content)

一般的なユースケース

ディレクトリの一括変換

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()
input_dir = Path("./documents")
output_dir = Path("./markdown")
output_dir.mkdir(exist_ok=True)

for file in input_dir.glob("*"):
    if file.is_file():
        try:
            result = md.convert(str(file))
            output_file = output_dir / f"{file.stem}.md"
            output_file.write_text(result.text_content)
            print(f"Converted: {file.name}")
        except Exception as e:
            print(f"Failed: {file.name} - {e}")

LLM コンテキスト向けの処理

from markitdown import MarkItDown

def prepare_for_llm(file_path: str) -> str:
    """Convert document to LLM-ready markdown."""
    md = MarkItDown()
    result = md.convert(file_path)

    # Add source reference
    content = f"# Source: {file_path}\n\n{result.text_content}"
    return content

# Use with your LLM
context = prepare_for_llm("report.pdf")

YouTube の文字起こしを抽出

# CLI
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" > transcript.md

# Python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

AI による説明付きの画像 OCR

from markitdown import MarkItDown
from openai import OpenAI

# Initialize with LLM support
client = OpenAI()
md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o"
)

# Convert image with AI description
result = md.convert("screenshot.png")
print(result.text_content)

Jupyter ノートブックの変換

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("analysis.ipynb")
print(result.text_content)  # Code cells, outputs, markdown

Wikipedia のコンテンツを抽出

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://en.wikipedia.org/wiki/Python")
print(result.text_content)  # Main article content only

RSS フィードの解析

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://example.com/feed.xml")
print(result.text_content)  # Feed entries as markdown

プラグインシステム

MarkItDown は、機能を拡張するサードパーティ製プラグインに対応しています。

# List installed plugins
markitdown --list-plugins

# Enable plugins during conversion
markitdown --use-plugins document.pdf

# Enable plugins in Python
md = MarkItDown(enable_plugins=True)
result = md.convert("document.pdf")

GitHub で #markitdown-plugin を検索すると、利用可能なプラグインを見つけられます。

MCP サーバーとの統合

MarkItDown は、Claude Desktop などの LLM アプリケーションと統合するための MCP（Model Context Protocol）サーバーを提供しています。

# Install MCP server
pip install markitdown-mcp

# Or from source
git clone https://github.com/microsoft/markitdown.git
cd markitdown/packages/markitdown-mcp
pip install -e .

設定の詳細は、markitdown-mcp を参照してください。

Docker の使用方法

# Build image
docker build -t markitdown:latest .

# Convert file
docker run --rm -i markitdown:latest < document.pdf > output.md

トラブルシューティング

問題	解決策
依存関係が不足している	pip install 'markitdown[all]' でインストールしてください
PDF の抽出に失敗する	複雑な PDF には Azure Document Intelligence をお試しください
画像内のテキストが抽出されない	OCR の依存関係がインストールされていることを確認するか、LLM モードを使用してください
大きなファイルがタイムアウトする	チャンクに分けて処理するか、ストリーミングを使用してください
プラグインが見つからない	markitdown --list-plugins を実行して、インストールを確認してください

よくあるエラー

# ModuleNotFoundError for specific format
pip install 'markitdown[pdf]'  # Install missing dependency

# Azure authentication
export AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT="<endpoint>"
export AZURE_DOCUMENT_INTELLIGENCE_KEY="<key>"

要件

• Python >= 3.10
• 仮想環境の使用を推奨

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Install
pip install 'markitdown[all]'

参考資料

• references/cli-reference.md - CLI オプションの全一覧
• references/api-reference.md - Python API の詳細
• references/examples.md - 発展的な例
• references/advanced-features.md - カスタムコンバーター、URI の処理
• GitHub: https://github.com/microsoft/markitdown
• PyPI: https://pypi.org/project/markitdown/

---

注意点

• 埋め込み画像を含む DOCX：画像は別ファイルに抽出され、Markdown では絶対パスが使用されます — Markdown ファイルだけを移動すると、画像参照が壊れます。
• PDF OCR の信頼度は出力されません — 信頼度の低いテキストも確実な情報であるかのように返されるため、後続の LLM 利用で誤りを確信を持って出力するおそれがあります。
• XLSX の結合セルは、アンカー以外の位置が空の値を持つ個別のセルとして抽出されます — ピボット形式のレポートでは、列グループが気付かないうちに失われます。
• HTML から Markdown への変換では、CSS によるレイアウトが失われます — 列の位置で配置された表は行優先の直線的な出力に変わり、複雑な表は解析できなくなります。
• 画像の説明に使う --use-llm フラグは、OPENAI_API_KEY がない場合にファイル名へ暗黙にフォールバックします — 出力は埋まっているように見えますが、実際の説明は含まれません。