David-Li0406/meta-skill-evloving

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

概要

MarkItDownは、Microsoftが開発した、さまざまなファイル形式をMarkdownに変換するためのPythonツールです。Markdownはトークン効率が高く、現代の言語モデルによく理解されるため、ドキュメントをLLMにとって扱いやすいテキスト形式に変換するのに特に便利です。

主な利点:

• ドキュメントをクリーンで構造化されたMarkdownに変換
• LLM処理に適したトークン効率の良い形式
• 15以上のファイル形式をサポート
• オプションのAI強化画像説明
• 画像やスキャン文書向けのOCR
• 音声ファイルの音声文字起こし

科学的な回路図による視覚的強化

このスキルで文書を作成する際は、科学的なダイアグラムや回路図を追加して、視覚的なコミュニケーションを強化することを常に検討してください。

文書に回路図やダイアグラムがまだ含まれていない場合:

• scientific-schematicsスキルを使用して、AI駆動の出版品質のダイアグラムを生成します
• 自然言語で希望のダイアグラムを説明するだけです
• Nano Banana Proが自動的に回路図を生成、レビュー、改良します

新しい文書の場合: 科学的な回路図は、テキストで説明されている主要な概念、ワークフロー、アーキテクチャ、または関係性を視覚的に表現するために、デフォルトで生成されるべきです。

回路図を生成する方法:

python scripts/generate_schematic.py "あなたのダイアグラムの説明" -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	文字起こしを取得

クイックスタート

インストール

# すべての機能を含めてインストール
pip install 'markitdown[all]'

# またはソースからインストール
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

コマンドラインでの使用

# 基本変換
markitdown document.pdf > output.md

# 出力ファイルを指定
markitdown document.pdf -o output.md

# パイプで内容を渡す
cat document.pdf | markitdown > output.md

# プラグインを有効にする
markitdown --list-plugins  # 利用可能なプラグインを一覧表示
markitdown --use-plugins document.pdf -o output.md

Python API

from markitdown import MarkItDown

# 基本的な使い方
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

# ストリームから変換
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

# OpenRouterクライアントの初期化（OpenAI互換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",  # 科学的な視覚分析に推奨
    llm_prompt="科学的なドキュメントのためにこの画像を詳細に説明してください"
)

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

2. Azure Document Intelligence

Microsoft Document Intelligenceを使用した拡張PDF変換:

# コマンドライン
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は、機能を拡張するためのサードパーティプラグインをサポートしています:

# インストール済みプラグインの一覧表示
markitdown --list-plugins

# プラグインを有効にする
markitdown --use-plugins file.pdf -o output.md

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

オプションの依存関係

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

# 特定の形式をインストール
pip install 'markitdown[pdf, docx, pptx]'

# 利用可能なすべてのオプション:
# [all]                  - すべてのオプション依存関係
# [pptx]                 - PowerPointファイル
# [docx]                 - Word文書
# [xlsx]                 - Excelスプレッドシート
# [xls]                  - 古いExcelファイル
# [pdf]                  - PDF文書
# [outlook]              - Outlookメッセージ
# [az-doc-intel]         - Azure Document Intelligence
# [audio-transcription]  - WAVおよびMP3の文字起こし
# [youtube-transcription] - YouTube動画の文字起こし

一般的なユースケース

1. 科学論文をMarkdownに変換

from markitdown import MarkItDown

md = MarkItDown()

# PDF論文を変換
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")

# 結果はMarkdownテーブル形式になります
print(result.text_content)

3. 複数の文書を処理

from markitdown import MarkItDown
import os
from pathlib import Path

md = MarkItDown()

# ディレクトリ内のすべてのPDFを処理
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"変換完了: {pdf_file.name}")

4. AI説明付きPowerPointを変換

from markitdown import MarkItDown
from openai import OpenAI

# 複数のAIモデルにアクセスするためにOpenRouterを使用
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",  # プレゼンテーションに推奨
    llm_prompt="このスライド画像を詳細に説明し、主要な視覚要素とデータに焦点を当ててください"
)

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 = [
    "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"✓ 変換完了: {file}")
    except Exception as e:
        print(f"✗ 変換エラー: {file}: {e}")

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

from markitdown import MarkItDown

md = MarkItDown()

# YouTube動画を文字起こしに変換
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

Dockerでの使用

# イメージをビルド
docker build -t markitdown:latest .

# 変換を実行
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("ファイルが見つかりません")
except Exception as e:
    print(f"変換エラー: {e}")

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

from markitdown import MarkItDown

md = MarkItDown()

# 大きなファイルの場合は、ストリーミングを使用
with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    
    # チャンクで処理するか、直接保存
    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_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()

# literatureフォルダ内のすべての論文を変換
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))
    
    # メタデータとともに保存
    output_file = output_dir / f"{paper.stem}.md"
    content = f"# {paper.stem}\n\n"
    content += f"**ソース**: {paper.name}\n\n"
    content += "---\n\n"
    content += result.text_content
    
    output_file.write_text(content)

# 図を含むAI強化変換用
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="科学的な図を技術的な精度で説明してください"
)

分析用のテーブルを抽出

from markitdown import MarkItDown
import re

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

# Markdownテーブルは解析するか、そのまま使用できます
print(result.text_content)

トラブルシューティング

一般的な問題

1. 依存関係の欠落: 機能固有のパッケージをインストール

   pip install 'markitdown[pdf]'  # PDFサポート用
   

2. バイナリファイルエラー: ファイルがバイナリモードで開かれていることを確認

   with open("file.pdf", "rb") as f:  # "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 Keys: https://openrouter.ai/keys
• OpenRouter Models: https://openrouter.ai/models
• MCP Server: markitdown-mcp (Claude Desktop統合用)
• プラグイン開発: packages/markitdown-sample-plugin を参照