mistral-pdf-to-markdown

Mistral PDF から Markdown への変換ツール

Mistral の OCR API を使って、PDF ドキュメントを Markdown 形式に変換します。テキスト、書式、画像を自動的に抽出します。

使用する場面

• 論文やドキュメントを Markdown に変換する
• スキャンした PDF からテキストを抽出する（OCR 機能）
• ヘッダーや書式を含むドキュメントの構造を保持する
• PDF に埋め込まれた画像を抽出する

クイックスタート

このスキルのディレクトリにある変換スクリプトを使います。

# Convert entire PDF
python scripts/convert_pdf_to_markdown.py input.pdf output.md

# Convert specific pages
python scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1-5"
python scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1,3,5"

出力構造

Output/PDFConversions/
├── document.md          # Markdown with text and image references
└── images/
    ├── img-0.jpeg      # Extracted images
    ├── img-1.jpeg
    └── ...

コードでの使用方法

from pathlib import Path
import subprocess

# Run conversion script
result = subprocess.run([
    "python",
    ".claude/skills/mistral-pdf-to-markdown/scripts/convert_pdf_to_markdown.py",
    "input.pdf",
    "Output/PDFConversions/output.md",
    "--pages", "1-10"
], capture_output=True, text=True)

print(result.stdout)

主な機能

• Markdown の書式設定：ヘッダー、リスト、構造を保持します
• 画像の抽出：画像を自動的に images/ サブフォルダーに保存します
• ページの選択：特定のページや範囲を抽出します
• スキャンした PDF のサポート：画像ベースの PDF に対応する本格的な OCR 機能
• 相対パス：画像参照には ![...](images/img-X.jpeg) を使用します

必要条件

スクリプトを実行するには、次が必要です。

• Notes/.env にある Mistral API キー（2 行目：mistral_api_key=...）
• Python パッケージ：mistralai、python-dotenv、pypdf

よくある使用例

論文を変換する

python scripts/convert_pdf_to_markdown.py \
  "Data/papers/research.pdf" \
  "Notes/Paper Markdown/research.md"

特定のセクションを抽出する

# Extract pages 10-20 (introduction and methods)
python scripts/convert_pdf_to_markdown.py \
  "paper.pdf" \
  "Notes/Paper Markdown/intro_methods.md" \
  --pages "10-20"

図のみを抽出する

# Extract pages with figures
python scripts/convert_pdf_to_markdown.py \
  "paper.pdf" \
  "Notes/Paper Markdown/figures.md" \
  --pages "25,27,30,35"

エラー処理

API キーが見つからない場合：

Error: Mistral API key not found in Notes/.env

→ Notes/.env の 2 行目に mistral_api_key=YOUR_KEY を追加してください

ページ範囲が無効な場合：

Warning: Page 100 out of range, skipping

→ PDF のページ数を確認し、ページの選択を調整してください

API のレート制限： → 少し待ってから再試行するか、リクエストごとのページ数を減らしてください

注意事項

• 画像は images/ サブフォルダーに JPEG ファイルとして保存されます
• Markdown の画像参照は images/img-X.jpeg に自動的に更新されます
• API の制限により、大きな PDF は処理に時間がかかる場合があります
• OCR を使わずにテキストだけを抽出する場合は、代わりに pdf スキルの使用を検討してください
• スキャンした PDF では、このスキルの OCR 機能が特に役立ちます

関連項目

• pdf スキル — API 呼び出しを使わずにローカルで PDF を操作する場合
• reference.md — Mistral OCR API の詳細