alterlab-markitdown

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

概要

MarkItDown は、ドキュメント、メディア、Web コンテンツを Markdown に変換し、LLM やテキスト分析のパイプラインで利用するための Microsoft 製 Python パッケージおよび CLI です。モデルにとって重要な構造（見出し、リスト、表、リンク）を保持しますが、人間が読むことを目的とした高忠実度のドキュメント変換には適していません。このスキルの対象は markitdown 0.1.x です（現行リリースは 0.1.8、2026 年 9 月時点。Python 3.10–3.14）。

このスキルを使う場面

次のような場合にこのスキルを使います。

• PDF、Word、PowerPoint、Excel、EPUB、HTML、Outlook ファイルを、LLM プロンプト、RAG インデックス、またはテキスト分析用の Markdown に変換する
• 異なる形式のドキュメントが混在するフォルダーを一括変換する
• YouTube の文字起こしや音声の文字起こしを Markdown で取得する
• LLM が作成した画像の説明を追加する、またはスキャンや埋め込み画像から OCR テキストを取得する
• markitdown-mcp サーバーを介して、ファイル変換をエージェントに提供する

対象外

シナリオ	代わりに使うもの
チャット、検索、ポッドキャスト機能を備えたセルフホストのノートブックに多数のソースを取り込む	alterlab-open-notebook
1 つの PDF に含まれる各セクション、図、表を横断して質問に回答する	alterlab-pdf-explore
多数の PDF から論文ごとに 1 行のエビデンステーブルを作成する	alterlab-pdf-extract
参考文献、DOI、BibTeX ライブラリを管理する	alterlab-pyzotero

対応形式

形式	説明	備考
PDF	Portable Document Format	テキストレイヤーを抽出（[pdf]）。スキャンには OCR が必要です（後述）
DOCX	Microsoft Word	見出し、リスト、表（[docx]）
PPTX	PowerPoint	スライドのテキスト、表、ノート。オプションで LLM による画像の説明を追加
XLSX / XLS	Excel スプレッドシート	シートごとに Markdown の表を 1 つ作成（[xlsx]、[xls]）
画像	JPEG、PNG	EXIF メタデータ（exiftool が必要）と、llm_client が設定されている場合の LLM による説明
音声	WAV、MP3、M4A、MP4	メタデータと音声の文字起こし（[audio-transcription]）
HTML	Web ページ	整形して変換します。Wikipedia と Bing の検索結果ページには専用の処理を適用します
CSV / JSON / XML	テキストベースのデータ	CSV は表に変換します。JSON、JSONL、XML はテキストとしてそのまま処理し、RSS/Atom フィードは解析します
ZIP	アーカイブファイル	内容を順に処理します
EPUB	電子書籍	全文を抽出します
Outlook MSG	メールメッセージ	ヘッダーと本文（[outlook]）
Jupyter	.ipynb ノートブック	Markdown セルとコードセル
YouTube	動画 URL	文字起こしを取得します（[youtube-transcription]）

クイックスタート

インストール

# Install with all features (uv-first; uv pip works inside an active venv)
uv pip install 'markitdown[all]'

# Or run the CLI ad hoc without installing into the project env
uvx --from 'markitdown[all]' markitdown document.pdf -o output.md

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

コマンドラインの使い方

# Basic conversion
markitdown document.pdf > output.md

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

# Pipe content (give a type hint when reading from stdin)
cat document.pdf | markitdown -x pdf > output.md

# Keep embedded images as data URIs instead of truncating them
markitdown slides.pptx --keep-data-uris -o slides.md

# Plugins
markitdown --list-plugins          # list installed plugins
markitdown --use-plugins document.pdf -o output.md

Python API

from markitdown import MarkItDown, StreamInfo

md = MarkItDown()
result = md.convert("document.pdf")
print(result.markdown)            # result.text_content is a soft-deprecated alias
print(result.title)               # may be None

# Local files only (narrower than convert(), which also fetches URIs)
result = md.convert_local("document.pdf")

# From a binary stream; stream_info replaces the deprecated file_extension= keyword
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f, stream_info=StreamInfo(extension=".pdf"))

高度な機能

1. AI による画像の説明

OpenRouter 経由で LLM を使って画像を説明します（組み込みのサポートは画像ファイルと PPTX 内の画像に対応しています）。

import os
from markitdown import MarkItDown
from openai import OpenAI

# OpenRouter takes the dotted slug of an Anthropic model ID (claude-opus-5-5 -> anthropic/claude-opus-5.5);
# scripts/convert_with_ai.py derives it from $ALTERLAB_MODEL (skills/core/shared/model_env.md).
model = "anthropic/claude-opus-5.5"

# Initialize OpenRouter client (OpenAI-compatible API)
client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model=model,  # recommended for scientific vision
    llm_prompt="Describe this image in detail for scientific documentation"
)

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

2. スキャンと埋め込み画像の OCR

MarkItDown にローカル OCR エンジンはありません。コンバーターは既存のテキストレイヤーを読み取ります。対応している 2 つの方法で OCR を追加できます。

• markitdown-ocr プラグイン（Microsoft、0.1.x）：PDF、DOCX、PPTX、XLSX 内の画像に対する LLM ビジョン OCR と、スキャンした PDF の全ページ OCR に対応しています。画像の説明と同じ llm_client / llm_model を再利用します。クライアントがない場合は、通常のコンバーターに自動的にフォールバックします。

  uv pip install markitdown-ocr openai
  

  md_ocr = MarkItDown(enable_plugins=True, llm_client=client, llm_model=model)  # client/model as above
  result = md_ocr.convert("scanned_paper.pdf")
  

• Azure Document Intelligence（クラウド OCR とレイアウト分析）— 次のセクションを参照してください。

完全にローカルで OCR を行うには、まずテキストレイヤーを追加します（例：ocrmypdf scan.pdf searchable.pdf。Tesseract を使用します）。その後、結果を変換します。

3. Azure Document Intelligence と Content Understanding

# Document Intelligence (endpoint on the command line or in MARKITDOWN_DOCINTEL_ENDPOINT)
markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"

# Content Understanding (documents, images, audio, video; needs the [az-content-understanding] extra)
markitdown recording.mp4 --use-cu --cu-endpoint "<content_understanding_endpoint>"

from markitdown import MarkItDown

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

認証では、AZURE_API_KEY 環境変数が設定されていればそれを使用し、設定されていなければ DefaultAzureCredential（Azure CLI ログイン、マネージド ID など）を使用します。明示的に指定するには docintel_credential= を渡します。どちらのサービスもドキュメントを Azure に送信するため、変換するデータについてそれが許可されていることを確認してください。

4. プラグインシステム

プラグインはデフォルトで無効になっています。CLI で --use-plugins を指定するか、Python で MarkItDown(enable_plugins=True) を指定して有効にします。GitHub のハッシュタグ #markitdown-plugin でサードパーティ製プラグインを探せます。プラグインの作成方法については、references/api_reference.md をご覧ください。

5. MCP サーバー

markitdown-mcp（0.0.1 alpha series）は、http:, https:, file:, data: URI に対応する単一のツール convert_to_markdown(uri) を公開します。

uv pip install markitdown-mcp
markitdown-mcp                                   # STDIO transport (default)
markitdown-mcp --http --host 127.0.0.1 --port 3001  # Streamable HTTP + SSE on localhost

# Register with Claude Code
claude mcp add markitdown -- uvx markitdown-mcp

インストール済みのプラグインを使用するには、サーバー環境で MARKITDOWN_ENABLE_PLUGINS=true を設定します。サーバーには認証がなく、ユーザーがアクセスできるすべてのファイルを読み取れるため、localhost でのみ実行してください（上流では Claude Desktop 用に Docker イメージを推奨しています）。

オプションの依存関係

サポートするファイル形式を指定します。

# Install specific formats (no spaces inside the bracket — pip parses 'pdf, docx' as bad names)
uv 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
# [az-content-understanding]  - Azure Content Understanding
# [audio-transcription]       - WAV and MP3 transcription
# [youtube-transcription]     - YouTube video transcription

よくあるユースケース

1. 論文のフォルダーを変換する

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown()
pdf_dir, output_dir = Path("papers/"), Path("markdown_output/")
output_dir.mkdir(exist_ok=True)

for pdf_file in pdf_dir.glob("*.pdf"):
    try:
        result = md.convert_local(pdf_file)
    except Exception as e:  # keep going; report failures at the end
        print(f"✗ {pdf_file.name}: {e}")
        continue
    (output_dir / f"{pdf_file.stem}.md").write_text(result.markdown)

ログ記録や並列処理が必要な大規模なジョブには、scripts/batch_convert.py を使用します。

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

from markitdown import MarkItDown

result = MarkItDown().convert("data.xlsx")
print(result.markdown)  # one Markdown table per sheet

3. AI による説明を付けて PowerPoint を変換する

import os
from markitdown import MarkItDown
from openai import OpenAI

# OpenRouter takes the dotted slug of an Anthropic model ID (claude-opus-5-5 -> anthropic/claude-opus-5.5);
# scripts/convert_with_ai.py derives it from $ALTERLAB_MODEL (skills/core/shared/model_env.md).
model = "anthropic/claude-opus-5.5"

# Use OpenRouter for access to multiple AI models
client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model=model,  # 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.markdown)

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

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.markdown)

Docker の使用方法

# Build image (from the repository root)
docker build -t markitdown:latest .

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

ベストプラクティス

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

• シンプルなドキュメント：基本的な MarkItDown() を使用します
• 複雑なレイアウトやスキャンした PDF：Azure Document Intelligence、または markitdown-ocr プラグインを使用します
• 視覚的なコンテンツ：AI による画像説明を有効にします
• 信頼できない入力：convert() ではなく、convert_local() または convert_stream() を使用します

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

from markitdown import MarkItDown, FileConversionException, UnsupportedFormatException

md = MarkItDown()

try:
    result = md.convert_local("document.pdf")
    print(result.markdown)
except FileNotFoundError:
    print("File not found")
except UnsupportedFormatException:
    print("No converter for this format (is the matching extra installed?)")
except FileConversionException as e:
    print(f"Conversion error: {e}")

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

Markdown 出力はすでにトークン効率に優れていますが、空行をまとめたり、不要なメタデータを削除したりできます。

import re

clean_text = re.sub(r"\n{3,}", "\n\n", result.markdown).strip()

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

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

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.markdown
    
    output_file.write_text(content)

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

# Model ID via the ALTERLAB_MODEL convention (skills/core/shared/model_env.md).
model = "anthropic/claude-opus-5.5"  # OpenRouter slug of the ALTERLAB_MODEL default (skills/core/shared/model_env.md)

client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1"
)

md_ai = MarkItDown(
    llm_client=client,
    llm_model=model,
    llm_prompt="Describe scientific figures with technical precision"
)

セキュリティ

MarkItDown は、現在のプロセスの権限でファイルを読み取り、URL にアクセスします。入力の一部でも信頼できないユーザーに由来する場合（ホストされたツールや、Web コンテンツを扱うエージェントなど）は、先にパスと URL を検証し、プライベートアドレスやメタデータサービスのアドレスをブロックしてください。また、convert() ではなく、より範囲を限定したメソッド（convert_local()、convert_stream()、または自分で取得したレスポンスに対する convert_response()）を呼び出してください。

トラブルシューティング

よくある問題

1. 依存関係が不足している（MissingDependencyException）：機能用の追加依存関係をインストールします

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

2. バイナリファイルのエラー：convert_stream() にはバイナリストリームが必要です

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

3. スキャンした PDF や画像から出力が得られない：MarkItDown がテキストレイヤーを見つけられませんでした。markitdown-ocr プラグインまたは Azure Document Intelligence を使用するか、変換前に ocrmypdf でローカルにテキストレイヤーを追加してください。Tesseract をインストールしただけでは、MarkItDown で OCR が有効になりません。

4. 画像や音声の EXIF メタデータがない：exiftool をインストールします（または EXIFTOOL_PATH にそのパスを指定します）。

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

• PDF ファイル：大きな PDF の処理には時間がかかります。ページ範囲を指定するオプションはないため、必要に応じて非常に大きなファイルは事前に分割してください
• 複数のファイルで 1 つの MarkItDown() インスタンスを再利用する：インスタンスの作成時にファイル形式検出器が読み込まれます
• 音声の文字起こし：speech_recognition パッケージを介して音声を Google の Web Speech API に送信します（ネットワーク接続が必要で、長いファイルでは時間がかかります）。倫理審査の承認でサードパーティによる処理が許可されていない限り、参加者へのインタビューなど、機密性の高い研究録音には使用しないでください
• AI による画像説明／OCR プラグイン：画像ごとに 1 回の 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/（`markitdown-ocr`、`markitdown-mcp` もあります）
• OpenRouter: https://openrouter.ai（AI による拡張変換用）
• OpenRouter API Keys: https://openrouter.ai/keys
• OpenRouter Models: https://openrouter.ai/models
• プラグイン開発: MarkItDown リポジトリの packages/markitdown-sample-plugin をご覧ください

AlterLab Academic Skills スイートの一部です。