markitdown-awesome

MarkItDown — 概要

入口となる Skill：MarkItDown とは何か、どのような問題を解決するのか、どのようなサブ機能があるのか、そして「次にどの Skill に進めばよいか」を説明します。

オフラインでの基準：microsoft/markitdown リポジトリの main ブランチ（2026-08 時点）に基づきます。何らかの形式がサポートされているか、あるパラメーターがまだ存在するかといった質問への最終的な根拠は、以下に示す公式リポジトリ README と公式 PyPI です。

---

この Skill を使う場面

✅ この Skill を使う場面（読み取り専用の概要、ナビゲーションに関する質問）：

• ユーザーが「MarkItDown とは何ですか？どの形式に対応していますか？アーキテクチャはどのようなものですか？」と知りたがっている
• 複数のツールの中から選ぼうとしている：markitdown / textract / unstructured / pandoc / docling
• markitdown をインストールしたばかりで、詳細を決める前に全体のアーキテクチャを理解したい
• 「MarkItDown のプラグイン／カスタム DocumentConverter を自作する方法」を尋ねている
• Azure Document Intelligence と Content Understanding の違いを尋ねている

❌ この Skill を使わない場面（関連する別の Skill に引き継ぎます）：

• 具体的な CLI コマンドの組み立て方や、パラメーターの渡し方 → markitdown-cli
• 埋め込み画像の OCR、スキャン PDF の処理、LLM Vision の設定 → markitdown-ocr
• ユーザーが「markitdown を使うことは決めていて、コマンドを 1 つ実行したいだけです」と明言している → markitdown-cli

⚠️ 判断が難しい場合：

• ユーザーが「OCR はどうすればよいですか」と尋ねているものの、画像かどうかが不明 → まず markitdown-ocr で判断します。通常の PDF から MD への変換に失敗しているだけなら、markitdown-cli の「-d/--use-docintel」に切り替えます。

---

ワークフロー

ユーザーの「概要／選定／ナビゲーション」に関する質問には、次の順序で回答します。

Step 1 — ユーザーの目的を確認する（分類）

• A 類：「これは何か」という質問（機能、位置付け、アーキテクチャ）→ §1–§4 に進みます
• B 類：「どれを選ぶか」という質問（ほかのツールとの比較）→ §5 + ecosystem/alternatives.md に進みます
• C 類：「使い方」に関する質問（具体的な API／コマンド）→ markitdown-cli に引き継ぎます
• D 類：「OCR／画像」に関する質問 → markitdown-ocr に引き継ぎます

Step 2 — 該当するセクションを案内する

• A 類 → §1 の一文での位置付け + §2 の対応形式一覧 + §3 の 3 経路の判断ツリーを提示します
• B 類 → ecosystem/alternatives.md の判断ツリー + おすすめを提示します
• C/D 類 → 関連する別の Skill の入口リンクを直接提示し、詳細には立ち入りません

Step 3 — 「次に進む先」を案内する

ユーザーの発言	次の Skill
「わかりました。インストールしてコマンドを実行したいです」	markitdown-cli
「スキャン文書／埋め込み画像の OCR を使いたいです」	markitdown-ocr
「RAG 用に一括でデータベースに登録したいです」	markitdown-cli + Python のループを自作（advanced/batch-rag-pipeline.md を参照）
「カスタムコンバーターを作りたいです」	api/converter-lifecycle.md を読む

Step 4 — 仕上げ：公式資料へのリンクを案内する

パラメーターがまだ存在するかどうかについて疑問がある場合は、公式リポジトリ README を参照してください。この Skill の内容はオフラインでの基準となるスナップショットであり、最終的な公式情報と見なすべきではありません。

Step 5 — セキュリティを確認する

URL／data URI／ファイルパスが関係する場合は毎回、まず §6 のセキュリティに関する注意を確認し、SSRF や未許可のパスへのアクセスを避けるようユーザーに伝えます。

Step 6 — プライバシーに関する声明

外部向けに出力する前に、返信の末尾に「この Skill はユーザーデータを収集、保存、送信しません」と記載します。

---

検証（セルフチェックリスト）

回答する前に、毎回次の項目を照合します。

• 提示したコマンド／パラメーターは、__main__.py の argparse にまだ存在していますか？
• 提示した API は、_markitdown.py に存在するメソッドに対応していますか？
• 相互に排他的な 2 つのバックエンド（docintel_* と cu_*）を混同していませんか？
• 「オプション機能」をすすめた場合、pip install 'markitdown[特性]' も併せて案内しましたか？
• ユーザーが URL を渡す場合、SSRF のリスクについて注意を促しましたか？
• ユーザーのファイルに機密情報が含まれる場合、プライベートなバックエンドを使うよう案内しましたか？

---

注意点

初心者がよくつまずくポイントを、発生頻度の高い順に示します。

1. プラグインはデフォルトで無効です — MarkItDown() で enable_plugins=True を指定しないと、markitdown-ocr などのプラグインは有効になりません。ただし、--list-plugins ではインストール済みのプラグインを引き続き一覧表示できます。必ず enable_plugins=True または CLI の -p を指定してください。
2. --list-plugins と「ファイル変換」は併用できません — __main__.py はプラグインを一覧表示するとすぐに sys.exit(0) を実行するため、「一覧表示 + 変換」は 2 つのコマンドに分けて実行する必要があります。
3. オプションの依存関係が未インストールだと MissingDependencyException が発生します — "dependencies needed" というメッセージが表示された場合は、extras が不足しています。形式に応じて pip install 'markitdown[特性]' を実行し、追加してください。
4. CLI には現時点で --llm-client / --llm-model がありません — コマンドラインから OCR を有効にするには、Python のラッパーを作成する必要があります（markitdown-ocr Skill の CLI の章を参照）。
5. HTTP URL を直接 convert() に渡すと、実際に GET が実行されます — convert_uri("https://…") はデフォルトで内蔵の requests.Session を使います。本番環境では必ず先に requests.get() を実行して自身で管理し、その後 convert_response() を使ってください。
6. file: URI はローカルマシン以外の netloc に対応していません — convert_uri("file://server/share/x.pdf") は Unsupported file URI 例外を直接発生させます。先にファイルを cp でローカルマシンにコピーしてください。
7. Azure Document Intelligence と Content Understanding は併用できません — docintel_endpoint= と cu_endpoint= を同時に渡すと、後者が前者を上書きします（__main__.py の argparse mutually_exclusive_group）。
8. PPTX/DOCX に埋め込まれた画像の OCR は自動実行されません — markitdown-ocr プラグインをインストールし、llm_client + llm_model を設定する必要があります。詳しくは markitdown-ocr を参照してください。
9. 大きな PDF の変換ではメモリ使用量がピークに達します — convert_local は open(path, "rb") で一度にすべてを読み込みます。convert_stream は 4 KiB のチャンクバッファーを使います。メモリ使用量に制約がある場合は、自分で分割して読み込み、convert_stream を複数回呼び出してください。
10. CLI の出力で日本語が文字化けします — ターミナルの LANG が UTF-8 でない場合は、標準出力ではなく -o out.md を使ってファイルに保存してください。

---

1. 一言で言うと

MarkItDown は Python で書かれた軽量ツールで、さまざまなファイルや Office 文書を構造化 Markdown に変換します。「LLM に渡す前に、文書をきれいに構造化する」ことを目的としています。位置付けは textract / unstructured に似ていますが、プレーンテキストを出力するのではなく、意味構造（見出し、リスト、表、リンク）の保持を優先します。

適しています：RAG の前処理、LLM に渡す文書の準備、検索可能なナレッジベースの構築、長いコンテキストの整理。
適していません：ピクセル単位の忠実な再現が必要な場合や、スキャン文書のレイアウトを高精度で OCR 復元する必要がある場合（専用の OCR バックエンドを使ってください）。

2. 主な機能と対応形式

カテゴリ	具体的な形式	内蔵コンバーター
Office ドキュメント	PDF、PowerPoint(.pptx)、Word(.docx)、Excel(.xlsx/.xls)	_pdf_converter.py / _pptx_converter.py / _docx_converter.py / _xlsx_converter.py
メディア	画像(EXIF + オプションの LLM キャプション)、音声(wav/mp3、オプションの依存関係が必要)	_image_converter.py / _audio_converter.py
ウェブとテキスト	HTML、CSV、JSON、XML、プレーンテキスト、RSS、Wikipedia、Bing SERP、YouTube URL	_html_converter.py / _csv_converter.py / _youtube_converter.py …
圧縮ファイル/電子書籍	ZIP(再帰的に展開)、EPUB、Outlook .msg、Jupyter .ipynb	_zip_converter.py / _epub_converter.py / _outlook_msg_converter.py / _ipynb_converter.py

オプションの依存関係をインストールする:

pip install 'markitdown[all]'                 # 全部
pip install 'markitdown[pdf,docx,pptx]'        # 按需
pip install 'markitdown[az-doc-intel]'        # Azure Document Intelligence
pip install 'markitdown[az-content-understanding]'  # Azure Content Understanding

オプション機能キーの完全な一覧は、ecosystem/optional-features.md を参照してください。

3. 3 つの利用方法(すばやく判断するためのフローチャート)

要把"某种文件"转成 Markdown ──┐
                              │
        ┌─────────────────────┼──────────────────────┐
        ▼                     ▼                      ▼
   只想跑 CLI 命令      想嵌入 Python 代码         文件里有图片要 OCR
   ──────────────      ──────────────────         ─────────────────
   ↓ 跳到 markitdown-cli  ↓ 用 MarkItDown() 类    ↓ 跳到 markitdown-ocr
     命令/参数/管道/插件    convert() / convert_stream()
                          / convert_uri() / convert_local()

この Skill を使う場面(概要を読むだけの場合):

• ユーザーが「MarkItDown でできること、できないこと」を知りたい
• ユーザーが複数のツール(markitdown vs textract vs unstructured vs pandoc)から選ぼうとしている
• ユーザーが markitdown をインストールしたばかりで、詳細を決める前に全体のアーキテクチャを把握したい
• ユーザーが「MarkItDown プラグインを自分で作る方法」を尋ねている

関連 Skill に移る場面:

ユーザーの要望	移動先
「markitdown コマンドの使い方は？引数は？パイプで渡すには？」	markitdown-cli
「PDF/PPT に埋め込まれたスキャン画像を OCR するには？」「GPT-4o を OCR に統合するには？」	markitdown-ocr
「markitdown プラグインを自分で作りたい」	公式プラグインのサンプル と _base_converter.py を直接読む

4. アーキテクチャの概要(LLM がコード生成時に適切な API を選ぶための情報)

ソースのコアパッケージ:packages/markitdown/src/markitdown/

markitdown/
├── __init__.py         # 暴露 MarkItDown / DocumentConverter / 异常 / 优先级常量
├── _markitdown.py      # 核心类 MarkItDown(注册表、转换分发、插件加载)
├── _base_converter.py  # DocumentConverter 基类 + DocumentConverterResult
├── _stream_info.py     # StreamInfo(mimetype/extension/charset/filename/…)
├── _exceptions.py      # MarkItDownException / MissingDependencyException / …
├── __main__.py         # CLI 入口(argparse)
└── converters/         # 25 个内置转换器(每个文件一个)

2 つの主要な定数(優先度の数値が小さいほど先に試されます):

PRIORITY_SPECIFIC_FILE_FORMAT = 0.0   # 精确格式: .docx / .pdf / .xlsx …
PRIORITY_GENERIC_FILE_FORMAT  = 10.0  # 兜底: 文本类、HTML 类

プラグインは負の優先度(たとえば markitdown-ocr の -1.0)を指定して、内蔵コンバーターより先に処理できます。

メインエントリーポイントの MarkItDown クラスの主要メソッド(api/python-api.md を参照):

メソッド	入力	用途
convert(source)	str/Path/Response/BinaryIO	ローカルパスか URI かを自動判定
convert_local(path)	ローカルファイル	最も安全で、ネットワーク要求を一切発行しません
convert_stream(stream, stream_info=…)	BinaryIO + StreamInfo	メモリ/パイプのストリーム
convert_uri(uri)	file: / data: / http(s): URI	リモートリソース
convert_url(url)	HTTP(S) URL	convert_uri の別名
convert_response(response)	requests.Response	HTTP リクエストを自分で制御
register_converter(converter, priority=…)	DocumentConverter	カスタムコンバーター/プラグインを登録

各 convert* は DocumentConverterResult(text_content=…, markdown=…) を返します。デフォルトのプロパティ markdown は実際の Markdown 文字列です。ほとんどのコンバーターでは text_content は markdown と同じですが、プラグインでは text_content のみを設定することもできます。

5. 3 種類の「拡張バックエンド」の比較(OCR/複雑な PDF の処理方法を決めるための情報)

バックエンド	有効化方法	適した用途	制限
Azure Document Intelligence	MarkItDown(docintel_endpoint=…) / CLI -d -e <endpoint>	高品質な PDF/スキャン文書、表の抽出	Azure サブスクリプションが必要、ページ単位の課金
Azure Content Understanding	MarkItDown(cu_endpoint=…) / CLI --use-cu --cu-endpoint <endpoint>	マルチモーダル(ドキュメント/画像/音声/動画)、構造化フィールド、アナライザーの自動選択	Azure サブスクリプションが必要。--cu-analyzer でカスタマイズ可能
LLM Vision(ローカル/OpenAI 互換)	MarkItDown(llm_client=…, llm_model="gpt-4o") または markitdown-ocr プラグインをインストール	画像内のテキスト、スキャン PDF、クラウドをまたいだ柔軟な利用	トークン単位の課金、利用可能な vision モデルが必要

Azure Document Intelligence と Content Understanding は相互排他的です(__main__.py で mutually_exclusive_group によって強制されます)。LLM Vision はこれらとは独立しており、併用できます。

6. セキュリティ上の注意(必読)

MarkItDown は現在のプロセス権限で I/O を実行します。攻撃対象領域を最小限に抑えるため、次の 3 点を推奨します。

1. 入力をサニタイズする:信頼できないパスをそのまま convert() に渡さないでください。http(s): や file: URI が処理される可能性があります。
2. アクセスを制限する:URL を処理する必要がある場合は、自分で requests.get() を使ってレスポンスを取得し、その後 convert_response() を呼び出してください。
3. 最も用途の限定された API を使う:
   • ローカルファイルだけを処理する → convert_local()
   • URI の処理を制御する必要がある → convert_response()
   • バイトストリームを完全に制御する → convert_stream()

7. この Skill を使う場面(該当するケースの全一覧)

✅ 適しています:

• 「MarkItDown とは？どの形式に対応していますか？」
• 「markitdown、textract、unstructured、pandoc はどう選べばよいですか？」
• 「MarkItDown プラグインを作りたいのですが、どのファイルを見ればよいですか？」
• 「Azure Document Intelligence と Content Understanding の違いは何ですか？」
• 「RAG パイプラインで PDF を Markdown に変換したいのですが、注意点はありますか？」

❌ 適していません(関連 Skill を利用してください):

• 具体的な CLI コマンドの組み立て方や、引数の渡し方 → markitdown-cli
• 埋め込み画像の OCR、スキャン PDF の処理、LLM Vision の設定 → markitdown-ocr
• markitdown を使うことは決まっていて、コマンドを 1 つ実行したいだけ → markitdown-cli

8. 离线示例代码(默认 Base API)

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("report.pdf")
print(result.markdown)

# 安全模式:只允许本地文件,不发起任何网络请求
md = MarkItDown(requests_session=None)  # 但注意 requests_session 默认非 None
md_local = md.convert_local("report.pdf")
print(md_local.markdown)

更深入的 Python API 模式见 api/python-api.md; 常见场景示例(批处理、URL 抓取、错误处理)见 basic/common-scenarios.md; Docker/CI 集成见 integration/docker-usage.md; RAG 批量入库见 advanced/batch-rag-pipeline.md; 首次上手 5 步走见 basic/first-conversion.md。

9. 官方资料(每次回答前都应交叉核对)

• 仓库 README: https://github.com/microsoft/markitdown
• PyPI: https://pypi.org/project/markitdown/
• OCR 插件 README: https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/README.md
• 插件示例: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-sample-plugin
• MCP 服务端: https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp

10. 隐私策略

本 Skill 仅提供本地知识、文档引用与代码示例,不收集、存储或传输任何用户数据。访问上述 GitHub/PyPI 链接需遵守用户网络访问要求。