markitdown

ドキュメントから Markdown への変換

概要

Microsoft の MarkItDown ツールを使って、さまざまなドキュメント形式を読みやすい Markdown に変換します。LLM による処理、コンテンツ抽出、ドキュメント分析のワークフローに最適化されています。

対応形式：PDF、Word（.docx）、PowerPoint（.pptx）、Excel（.xlsx/.xls）、画像（OCR/LLM 対応）、HTML、音声（文字起こし対応）、CSV、JSON、XML、ZIP アーカイブ、EPub

クイックスタート

基本的な使い方

from markitdown import MarkItDown

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

コマンドライン

# Convert single file
markitdown document.pdf > output.md
markitdown document.pdf -o output.md

# Pipe input
cat document.pdf | markitdown

🔒 セキュリティに関する考慮事項

本番環境で使用する前に：

• ✅ ファイルの種類を検証する（拡張子ではなく MIME）
• ✅ ファイルサイズを制限する（DoS を防ぐ）
• ✅ ファイルパスをサニタイズする（パストラバーサルを防ぐ）
• ✅ API キーを保護する（ハードコードしない）
• ✅ データのプライバシーを考慮する（外部サービス）

実装の詳細については、patterns.md を参照してください。

API キーのセキュリティ

❌ 絶対に行わないこと：

• キーをコードにハードコードする
• .env ファイルを git にコミットする
• 環境変数をログに記録する

✅ 必ず行うこと：

• 環境変数を使用する：export OPENAI_API_KEY="sk-..." # pragma: allowlist secret
• シークレット管理を使用する（AWS Secrets Manager、Azure Key Vault）
• キーを定期的にローテーションする

よくあるパターン

PDF ドキュメント

# Basic PDF conversion
md = MarkItDown()
result = md.convert("report.pdf")

# With Azure Document Intelligence (better quality)
md = MarkItDown(docintel_endpoint="<your-endpoint>")
result = md.convert("report.pdf")

Office ドキュメント

# Word documents - preserves structure
result = md.convert("document.docx")

# Excel - converts tables to markdown tables
result = md.convert("spreadsheet.xlsx")

# PowerPoint - extracts slide content
result = md.convert("presentation.pptx")

説明付きの画像

# ✅ SECURE: Using environment variables for API keys
import os
from openai import OpenAI

api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise RuntimeError("OPENAI_API_KEY not set")

client = OpenAI(api_key=api_key)
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("diagram.jpg")  # Gets AI-generated description

バッチ処理

from pathlib import Path

md = MarkItDown()
documents = Path(".").glob("*.pdf")

for doc in documents:
    result = md.convert(str(doc))
    output_path = doc.with_suffix(".md")
    output_path.write_text(result.text_content)

インストール

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

# Selective features
pip install 'markitdown[pdf, docx, pptx]'

要件：Python 3.10 以上

主な機能

• 構造の保持：見出し、リスト、表、リンクを保持します
• プラグインシステム：カスタムコンバーターで拡張できます
• Docker 対応：コンテナー化されたデプロイに対応します
• MCP 連携：LLM アプリ向けの Model Context Protocol サーバー

関連ファイルを読むタイミング

• reference.md - 次の情報が必要な場合に参照してください：

  • API リファレンス全体とすべての設定オプション
  • Azure Document Intelligence の連携に関する詳細
  • プラグイン開発ガイド
  • Docker と MCP サーバーのセットアップ
  • トラブルシューティングとエラー処理

• examples.md - 次の情報が必要な場合に参照してください：

  • 特定のファイル形式を扱う実用的な例
  • バッチ処理のワークフロー
  • エラー処理のパターン
  • 既存のパイプラインとの連携

• patterns.md - 次の情報が必要な場合に参照してください：

  • 本番環境へのデプロイパターン
  • パフォーマンス最適化の方法
  • セキュリティに関する考慮事項
  • 避けるべきアンチパターン

クイックリファレンス

ファイル形式	用途	コマンド
PDF	レポート、論文	md.convert("file.pdf")
Word	ドキュメント	md.convert("file.docx")
Excel	データテーブル	md.convert("file.xlsx")
PowerPoint	プレゼンテーション	md.convert("file.pptx")
画像	OCR 対応の図	md = MarkItDown(llm_client=client); md.convert("img.jpg")
HTML	ウェブページ	md.convert("page.html")
ZIP	アーカイブ	md.convert("archive.zip") - 内容を処理

⚠️ 避けるべきよくある間違い

アンチパターン 1：API キーのハードコード

# ❌ NEVER DO THIS
md = MarkItDown(llm_client=OpenAI(api_key="sk-hardcoded-key"))

# ✅ ALWAYS DO THIS
api_key = os.getenv("OPENAI_API_KEY")
md = MarkItDown(llm_client=OpenAI(api_key=api_key))

アンチパターン 2：未検証のファイルパス

# ❌ Vulnerable to path traversal
user_input = "../../../etc/passwd"
md.convert(user_input)

# ✅ Validate and sanitize
from pathlib import Path
safe_path = Path(user_input).resolve()
if not safe_path.is_relative_to(allowed_dir):
    raise ValueError("Invalid path")
md.convert(str(safe_path))

アンチパターン 3：ファイルサイズ制限の無視

# ❌ Can cause DoS
md.convert("huge_file.pdf")  # No size check

# ✅ Check size first
max_size = 50 * 1024 * 1024  # 50MB
if Path("file.pdf").stat().st_size > max_size:
    raise ValueError("File too large")

よくある問題

インポートエラー：Python >= 3.10 であること、および markitdown がインストールされていることを確認してください
依存関係の不足：pip install 'markitdown[all]' でインストールしてください
画像の説明が機能しない：LLM クライアント（OpenAI または互換クライアント）が必要です

詳しいトラブルシューティングについては、reference.md を参照してください。