Microsoft MarkItDown 入門：文書を Markdown に変換して AI ナレッジベースを作りやすくする

Microsoft の microsoft/markitdown は、さまざまなファイルを Markdown に変換する Python ツールです。目的はレイアウトを高精度に再現することではなく、文書、表計算、Web ページ、画像、音声などの資料を、LLM、RAG、検索インデックス、テキスト処理で扱いやすい Markdown に変換することです。

プロジェクト：

https://github.com/microsoft/markitdown

PDF、Word、Excel、PowerPoint、Web ページ、画像、圧縮ファイルなどを AI モデルに読ませたい場面が多いなら、MarkItDown は前処理に向いています。出力はプレーンな Markdown なので、バイナリファイルをそのまま処理するより、デバッグ、チャンク分割、検索、保存がしやすくなります。

MarkItDown が対応するもの

公式 README によると、MarkItDown は次の入力形式に対応しています。

PDF
PowerPoint
Word
Excel
画像、EXIF メタデータと OCR を含む
音声、EXIF メタデータと音声文字起こしを含む
HTML
CSV、JSON、XML
ZIP ファイル、中身をたどって処理
YouTube URL
EPUB

位置づけは明確です。ファイルを Markdown に変換し、後段の LLM やテキスト処理ワークフローで使いやすくするツールです。厳密にレイアウトを保つ文書変換ツールとして見るべきではありません。履歴書、契約書、スキャン文書、製品資料、会議録音、Web ページのスナップショットでは、重要なのはピクセル単位の再現ではなく、モデルが安定して理解できるテキスト構造を取り出すことです。

インストールコマンド

最も簡単なインストール方法は pip です。

1

pip install markitdown

すべての任意機能を使いたい場合は、all extra をインストールします。

1

pip install 'markitdown[all]'

特定形式だけを使う場合は、必要な extra だけを入れることもできます。たとえば PDF、DOCX、PPTX の場合：

1

pip install 'markitdown[pdf,docx,pptx]'

ソースからインストールする場合：

1
2
3


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

コマンドラインでの使い方

インストール後は markitdown コマンドを直接使えます。最も基本的な使い方は、ファイルを標準出力へ変換する方法です。

1

markitdown path-to-file.pdf

Markdown ファイルとして保存します。

1

markitdown path-to-file.pdf -o output.md

Office 文書を変換します。

1
2
3


markitdown report.docx -o report.md
markitdown slides.pptx -o slides.md
markitdown data.xlsx -o data.md

Web ページを変換します。

1

markitdown https://example.com -o page.md

YouTube URL を変換します。

1

markitdown https://www.youtube.com/watch?v=VIDEO_ID -o video.md

ZIP ファイルを処理します。

1

markitdown archive.zip -o archive.md

まずはこれらのコマンドで手動確認するのがよいです。出力構造が期待どおりであることを確認してから、自動化スクリプト、ナレッジベースの取り込み処理、RAG pipeline に組み込みます。

Python API の使い方

MarkItDown は Python ライブラリとしても使えます。公式 README の基本形は、MarkItDown インスタンスを作成し、convert を呼び出す方法です。

1
2
3
4
5


from markitdown import MarkItDown

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

画像説明のために OpenAI クライアントを接続したい場合は、クライアントを MarkItDown に渡します。

1
2
3
4
5
6
7


from openai import OpenAI
from markitdown import MarkItDown

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

これはスクリーンショット、スキャン画像、グラフを含むページなど、画像ベースの資料に向いています。実際に使うときは、特に内部文書を処理する場合、コスト、プライバシー、ネットワーク送信に注意が必要です。

Docker での使い方

ローカルの Python 環境を汚したくない場合は、Docker で実行できます。公式 README では、次のイメージビルド方法が示されています。

1

docker build -t markitdown:latest .

現在のディレクトリをコンテナにマウントして変換します。

1

docker run --rm -v .:/workdir markitdown:latest path-to-file.pdf -o output.md

この方法はサーバー、CI、一時的なバッチ処理環境に向いています。欠点は、依存関係のデバッグがローカル Python 環境より少し遅くなりやすいことです。

プラグイン機構

MarkItDown はプラグインに対応していますが、サードパーティープラグインはデフォルトでは有効になりません。プラグイン一覧を確認します。

1

markitdown --list-plugins

プラグインを有効にします。

1

markitdown --use-plugins path-to-file.foo -o output.md

Python でプラグインを有効にします。

1
2
3
4
5


from markitdown import MarkItDown

md = MarkItDown(enable_plugins=True)
result = md.convert("example.foo")
print(result.text_content)

プラグインは、独自形式、社内文書形式、特定の業務システムから出力されたファイルを扱うときに便利です。ただし、プラグインは追加コードを実行する仕組みなので、信頼できないものを安易に有効化しないほうが安全です。

どんな流れに入れるとよいか

MarkItDown は次のような場面に向いています。

PDF、DOCX、PPTX、XLSX を Markdown に統一してからナレッジベースに入れる。
Web ページ、YouTube、EPUB などの資料を検索可能なテキストにする。
RAG 前の文書前処理として、チャンク分割しやすい Markdown を得る。
変換した資料を Codex、Claude Code、Cursor のようなツールに読ませる。
過去の文書をまとめて整理し、統一された .md の中間形式を作る。

簡単な流れは次のようになります。

1
2


mkdir -p markdown
markitdown input.pdf -o markdown/input.md

ディレクトリをまとめて処理する場合は、スクリプトでファイルを列挙し、それぞれに markitdown を呼び出します。変換後は、表、スキャン文書、複雑なレイアウトの PDF、複数カラムの文書を中心に、いくつかの出力を目視確認することをおすすめします。

使うときの注意点

MarkItDown は便利ですが、いくつか注意点があります。

複雑な PDF の読み取り順序は完璧とは限りません。特に複数カラム、脚注、ヘッダー、フッターが多い文書では注意が必要です。
OCR や画像説明は追加コンポーネントや LLM に依存するため、品質とコストを別途評価する必要があります。
Markdown はテキスト構造の表現には向いていますが、正確なレイアウト保持には向きません。
プラグインや LLM で内部ファイルを処理する場合は、データセキュリティに注意してください。
変換結果は中間生成物として扱い、元ファイルと完全に同等だと決めつけないほうがよいです。

目的が「大模型に資料を読ませる」ことであれば、MarkItDown の方向性は理にかなっています。まず各種ファイルを統一された Markdown に変換し、その後でクリーニング、チャンク分割、インデックス化、質問応答に進めます。万能変換ツールではありませんが、LLM 向けの文書入口ツールとしては十分にわかりやすく、軽量で、既存の Python ワークフローにも組み込みやすいです。