markitdown

MarkItDown - ファイルから Markdown への変換

概要

MarkItDown は、Microsoft が開発した、さまざまなファイル形式を Markdown に変換するための Python ツールです。Markdown はトークン効率が高く、現代の言語モデルにもよく理解されるため、ドキュメントを LLM に適したテキスト形式に変換する用途で特に役立ちます。

主な利点:

• ドキュメントを、整理された clean な Markdown に変換
• LLM 処理に適したトークン効率の高い形式
• 15 以上のファイル形式に対応
• 任意で AI による画像説明の強化
• 画像およびスキャンされたドキュメントに対する OCR
• 音声ファイルの音声文字起こし

Scientific Schematics による視覚的強化

このスキルでドキュメントを作成する際は、視覚的な伝達を高めるために、必ず科学的な図やダイアグラムの追加を検討してください。

ドキュメントにまだ図やダイアグラムが含まれていない場合:

• scientific-schematics スキルを使用して、AI による出版品質の図を生成します
• 必要な図を自然言語で説明するだけでかまいません
• Nano Banana Pro が、図の生成、レビュー、洗練を自動的に行います

新規ドキュメントの場合: テキストで説明された主要な概念、ワークフロー、アーキテクチャ、関係性を視覚的に表すために、科学的な図をデフォルトで生成する必要があります。

図の生成方法:

python scripts/generate_schematic.py "your diagram description" -o figures/output.png

AI は自動的に以下を行います:

• 適切な書式で出版品質の画像を作成
• 複数の反復を通じてレビューと洗練を実施
• アクセシビリティを確保(色覚多様性に配慮し、高コントラスト)
• 出力を figures/ ディレクトリに保存

図を追加するタイミング:

• ドキュメント変換のワークフロー図
• ファイル形式のアーキテクチャ図
• OCR 処理パイプラインの図
• 統合ワークフローの可視化
• システムアーキテクチャ図
• データフロー図
• 可視化によって理解が深まる複雑な概念すべて

図の作成に関する詳細なガイダンスについては、scientific-schematics スキルのドキュメントを参照してください。

---

対応形式

形式	説明	備考
PDF	Portable Document Format	全文抽出
DOCX	Microsoft Word	表や書式を保持
PPTX	PowerPoint	ノート付きのスライド
XLSX	Excel スプレッドシート	表とデータ
画像	JPEG, PNG, GIF, WebP	EXIF メタデータ + OCR
音声	WAV, MP3	メタデータ + 文字起こし
HTML	Web ページ	クリーンな変換
CSV	カンマ区切り値	表形式
JSON	JSON データ	構造化された表現
XML	XML ドキュメント	構造化形式
ZIP	アーカイブファイル	内容を順に処理
EPUB	電子書籍	全文抽出
YouTube	動画 URL	文字起こしを取得

クイックスタート

インストール

# Install with all features
pip install 'markitdown[all]'

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

コマンドラインでの使用

# Basic conversion
markitdown document.pdf > output.md

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

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

# Enable plugins
markitdown --list-plugins  # List available plugins
markitdown --use-plugins document.pdf -o output.md

Python API

from markitdown import MarkItDown

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

# Convert from stream
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    print(result.text_content)

高度な機能

1. AI による画像説明の強化

OpenRouter 経由で LLM を使用し、詳細な画像説明を生成します(PPTX および画像ファイル向け):

from markitdown import MarkItDown
from openai import OpenAI

# Initialize OpenRouter client (OpenAI-compatible API)
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",  # recommended for scientific vision
    llm_prompt="Describe this image in detail for scientific documentation"
)

result = md.convert("presentation.pptx")
print(result.text_content)

2. Azure Document Intelligence

Microsoft Document Intelligence による PDF 変換の強化:

# Command line
markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"

# Python API
from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("complex_document.pdf")
print(result.text_content)

3. プラグインシステム

MarkItDown は、機能を拡張するためのサードパーティ製プラグインをサポートしています:

# List installed plugins
markitdown --list-plugins

# Enable plugins
markitdown --use-plugins file.pdf -o output.md

GitHub で #markitdown-plugin のハッシュタグを使ってプラグインを検索できます。

オプションの依存関係

サポートするファイル形式を制御します:

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

# All available options:
# [all]                  - All optional dependencies
# [pptx]                 - PowerPoint files
# [docx]                 - Word documents
# [xlsx]                 - Excel spreadsheets
# [xls]                  - Older Excel files
# [pdf]                  - PDF documents
# [outlook]              - Outlook messages
# [az-doc-intel]         - Azure Document Intelligence
# [audio-transcription]  - WAV and MP3 transcription
# [youtube-transcription] - YouTube video transcription

一般的なユースケース

1. 科学論文を Markdown に変換する

from markitdown import MarkItDown

md = MarkItDown()

# Convert PDF paper
result = md.convert("research_paper.pdf")
with open("paper.md", "w") as f:
    f.write(result.text_content)

2. 分析のために Excel からデータを抽出する

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.xlsx")

# Result will be in Markdown table format
print(result.text_content)

3. 複数のドキュメントを処理する

from markitdown import MarkItDown
import os
from pathlib import Path

md = MarkItDown()

# Process all PDFs in a directory
pdf_dir = Path("papers/")
output_dir = Path("markdown_output/")
output_dir.mkdir(exist_ok=True)

for pdf_file in pdf_dir.glob("*.pdf"):
    result = md.convert(str(pdf_file))
    output_file = output_dir / f"{pdf_file.stem}.md"
    output_file.write_text(result.text_content)
    print(f"Converted: {pdf_file.name}")

4. AI による説明付きで PowerPoint を変換する

from markitdown import MarkItDown
from openai import OpenAI

# Use OpenRouter for access to multiple AI models
client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",  # recommended for presentations
    llm_prompt="Describe this slide image in detail, focusing on key visual elements and data"
)

result = md.convert("presentation.pptx")
with open("presentation.md", "w") as f:
    f.write(result.text_content)

5. 異なる形式をまとめて変換する

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Files to convert
files = [
    "document.pdf",
    "spreadsheet.xlsx",
    "presentation.pptx",
    "notes.docx"
]

for file in files:
    try:
        result = md.convert(file)
        output = Path(file).stem + ".md"
        with open(output, "w") as f:
            f.write(result.text_content)
        print(f"✓ Converted {file}")
    except Exception as e:
        print(f"✗ Error converting {file}: {e}")

6. YouTube 動画の文字起こしを抽出する

from markitdown import MarkItDown

md = MarkItDown()

# Convert YouTube video to transcript
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

Docker での使用

# Build image
docker build -t markitdown:latest .

# Run conversion
docker run --rm -i markitdown:latest < ~/document.pdf > output.md

ベストプラクティス

1. 適切な変換方法を選ぶ

• シンプルなドキュメント: 基本的な MarkItDown() を使用
• 複雑な PDF: Azure Document Intelligence を使用
• 視覚的なコンテンツ: AI による画像説明を有効化
• スキャンされたドキュメント: OCR の依存関係がインストールされていることを確認

2. エラーを適切に処理する

from markitdown import MarkItDown

md = MarkItDown()

try:
    result = md.convert("document.pdf")
    print(result.text_content)
except FileNotFoundError:
    print("File not found")
except Exception as e:
    print(f"Conversion error: {e}")

3. 大きなファイルを効率的に処理する

from markitdown import MarkItDown

md = MarkItDown()

# For large files, use streaming
with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    
    # Process in chunks or save directly
    with open("output.md", "w") as out:
        out.write(result.text_content)

4. トークン効率を最適化する

Markdown 出力はそれ自体がトークン効率に優れていますが、次のような対応も可能です。

• 過剰な空白を削除する
• 類似したセクションをまとめる
• 不要であればメタデータを取り除く

from markitdown import MarkItDown
import re

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

# Clean up extra whitespace
clean_text = re.sub(r'\n{3,}', '\n\n', result.text_content)
clean_text = clean_text.strip()

print(clean_text)

科学ワークフローとの連携

文献をレビュー用に変換する

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Convert all papers in literature folder
papers_dir = Path("literature/pdfs")
output_dir = Path("literature/markdown")
output_dir.mkdir(exist_ok=True)

for paper in papers_dir.glob("*.pdf"):
    result = md.convert(str(paper))
    
    # Save with metadata
    output_file = output_dir / f"{paper.stem}.md"
    content = f"# {paper.stem}\n\n"
    content += f"**Source**: {paper.name}\n\n"
    content += "---\n\n"
    content += result.text_content
    
    output_file.write_text(content)

# For AI-enhanced conversion with figures
from openai import OpenAI

client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md_ai = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",
    llm_prompt="Describe scientific figures with technical precision"
)

分析用に表を抽出する

from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("data_tables.xlsx")

# Markdown tables can be parsed or used directly
print(result.text_content)

トラブルシューティング

よくある問題

1. 依存関係が不足している: 機能固有のパッケージをインストールしてください

   pip install 'markitdown[pdf]'  # For PDF support
   

2. バイナリファイルのエラー: ファイルをバイナリモードで開いていることを確認してください

   with open("file.pdf", "rb") as f:  # Note the "rb"
       result = md.convert_stream(f, file_extension=".pdf")
   

3. OCR が動作しない: tesseract をインストールしてください

   # macOS
   brew install tesseract
   
   # Ubuntu
   sudo apt-get install tesseract-ocr
   

パフォーマンスに関する考慮事項

• PDF ファイル: 大きな PDF は処理に時間がかかる場合があります。サポートされている場合はページ範囲の指定を検討してください
• 画像の OCR: OCR 処理は CPU 負荷が高くなります
• 音声の文字起こし: 追加の計算リソースが必要です
• AI による画像説明: API 呼び出しが必要です (料金が発生する場合があります)

次のステップ

• 完全な API ドキュメントは references/api_reference.md を参照してください
• フォーマット固有の詳細は references/file_formats.md を確認してください
• 自動化の例については scripts/batch_convert.py を確認してください
• AI を活用した変換については scripts/convert_with_ai.py を確認してください

リソース

• MarkItDown GitHub: https://github.com/microsoft/markitdown
• PyPI: https://pypi.org/project/markitdown/
• OpenRouter: https://openrouter.ai (AI を活用した変換用)
• OpenRouter API キー: https://openrouter.ai/keys
• OpenRouter モデル: https://openrouter.ai/models
• MCP サーバー: markitdown-mcp (Claude Desktop 連携用)
• プラグイン開発: packages/markitdown-sample-plugin を参照してください