MarkItDown

Various files → Markdown（LLM・テキスト解析パイプライン向け）

1 — 概要

位置づけ

MarkItDown は Microsoft が公開している軽量な Python ユーティリティで、PDF・Office・HTML・画像・音声など多様な入力を Markdown に揃えて出力する。人間向けの高忠実度変換よりも、見出し・リスト・表・リンクなどの構造を残しつつ LLM が扱いやすいテキストを優先する設計（microsoft/markitdown）。

3.10+Python

CLIstdin / -o

APIMarkItDown クラス

MCPmarkitdown-mcp

textract に近い「なんでもテキスト化」だが、出力は Markdown 中心。GPT 系モデルが Markdown を強く理解しているという前提に沿い、トークン効率も意識されている。

Breaking（0.0.1 → 0.1.0 付近）: 依存は optional グループに整理（後述の pip install 'markitdown[all]' 推奨）。convert_stream() は バイナリの file-like のみ。DocumentConverter はパスではなく ストリームから読む インターフェイスに変更され、プラグイン実装者は要確認。

2 — 対応形式

入力

コアパッケージは PDF・PowerPoint・Word・Excel・画像（EXIF / OCR）・音声（EXIF / 文字起こし）・HTML・CSV/JSON/XML・ZIP（中身を列挙）・YouTube URL・EPub などを Markdown へ変換する。出力は LLM やテキスト解析パイプライン向けで、人間向けの高忠実度変換を最優先する設計ではない。

カテゴリ	例
ドキュメント	PDF, DOCX, PPTX, XLSX/XLS, EPub
ウェブ・テキスト	HTML, CSV, JSON, XML, RSS, Wikipedia
メディア	画像（メタデータ・OCR）, 音声（文字起こし）, YouTube
その他	ZIP（中身を順次変換）, Outlook MSG, Bing SERP

3 — インストール

前提・導入

Python 3.10 以上。仮想環境の利用を推奨。

python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'

ソースから入れる場合:

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

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

4 — 変換パイプライン

ざっくり流れ

MarkItDown.convert() はローカルパス・URL・requests.Response・バイナリストリームを受け取り、内部で Magika 等による内容推定と StreamInfo の候補リストを作り、登録済み DocumentConverter を優先度順に試す。

入力 → StreamInfo 推定 → コンバータ選択 → Markdown 文字列

優先度: 具体的な拡張子・MIME 向けコンバータ（PRIORITY_SPECIFIC_FILE_FORMAT）が汎用（PlainTextConverter など）より先に試されるよう、後から登録したものほど優先というスタック順（コメントより: より専用なコンバータをリストの下側に）。
Azure Document Intelligence: エンドポイントを渡した場合のみ DocumentIntelligenceConverter が追加登録され、PDF 等の処理に使える。
プラグイン: entry_points(group="markitdown.plugin") で読み込み、enable_plugins=True で各プラグインがコンバータを登録。

HTTP 取得時のヘッダ

デフォルトの requests.Session は Accept: text/markdown, text/html;q=0.9, ... を付与し、サーバが Markdown を返せる場合にそれを優先する（README の Cloudflare 記事リンク参照）。

5 — CLI・Python API

CLI

markitdown path-to-file.pdf > document.md
markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown

プラグイン一覧: markitdown --list-plugins。有効化: markitdown --use-plugins path-to-file.pdf。

Python（最小）

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

LLM で画像説明（例: 画像・pptx）

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)

6 — Azure 連携

Document Intelligence

スキャン PDF や複雑なレイアウト向け。CLI では -d -e <endpoint>、Python では docintel_endpoint を渡す。

from markitdown import MarkItDown

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

Content Understanding

音声・動画、構造化フィールド（YAML front matter）、カスタムアナライザーなど、ビルトインや Document Intelligence では足りないケース向け。各 convert() は課金 API 呼び出しになり得る。

能力	ビルトイン	Doc Intel	Content Understanding
ドキュメント変換	オフライン・形式別	クラウドレイアウト	クラウド多モーダル
構造化フィールド	なし	本統合では未露出	YAML front matter
音声・動画	基本音声のみ	非対応	対応
コスト	ローカル計算	Azure 従量	Azure 従量

from markitdown import MarkItDown

md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # documents
result = md.convert("meeting.mp4")  # video
print(result.markdown)

Extra: pip install 'markitdown[az-content-understanding]'。CLI: markitdown file.pdf --use-cu --cu-endpoint "<endpoint>"

7 — モノレポ構成

packages/

パッケージ	役割
`markitdown`	コアライブラリ・CLI
`markitdown-mcp`	MCP サーバ（Claude Desktop 等との連携）
`markitdown-ocr`	PDF/DOCX/PPTX/XLSX 内画像の OCR（LLM Vision 利用）
`markitdown-sample-plugin`	サードパーティプラグインのサンプル（`#markitdown-plugin` で検索）

8 — オプション依存・拡張

pip extras（抜粋）

Extra	内容
`[all]`	従来互換に近い「全部入り」
`[pdf]` `[docx]` `[pptx]` `[xlsx]` `[xls]`	各オフィス／PDF 系依存
`[outlook]`	Outlook メッセージ
`[az-doc-intel]`	Azure Document Intelligence
`[az-content-understanding]`	Azure Content Understanding
`[audio-transcription]`	wav/mp3 の文字起こし
`[youtube-transcription]`	YouTube 字幕取得

markitdown-ocr: 組み込み画像説明と同じ llm_client / llm_model パターン。クライアント未設定時は OCR はスキップされ通常コンバータにフォールバック。

Document Intelligence（CLI）

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

markitdown-ocr プラグイン

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)

9 — セキュリティ

入力の扱い

MarkItDown は open() や requests.get() と同様、プロセスがアクセスできるリソースに I/O する。信頼できない入力をそのまま渡さないこと。

サーバー側利用ではパス・URI スキーム・ネットワーク先を制限し、入力を検証する。
用途に合わせて最も狭い API を選ぶ: ローカルファイルのみなら convert_local()、HTTP は自前で requests.get() して convert_response()、最大制御なら convert_stream()。
convert() はパス・URL・ストリームを広く受け付けるため、制御が必要な環境では避ける。

10 — 参考リンク

公式

GitHub: microsoft/markitdown — 本体・Issue・PR
PyPI: markitdown
markitdown-mcp — MCP パッケージ
Azure Content Understanding
Azure Document Intelligence