markitdown-skill

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]'

オプションの依存関係

オプション	説明
[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/