markitdown

markitdown

Microsoft の markitdown を使って、ドキュメントを整った Markdown に変換します。 構造（見出し、表、リスト、リンク、スライドのノート、シート名）を保持するため、単なるテキストの抽出とは異なり、LLM への入力に適しています。

ファイルに すでに含まれている テキストを抽出します。OCR は行いません。スキャンした PDF や写真は空の結果になります（下記の「画像のみのコンテンツ」を参照してください）。

セットアップ

markitdown --version   # expect 0.1.x or later

インストールされていない場合は、分離されたツールとしてインストールしてください。Python 3.10 以降が必要です。

uv tool install "markitdown[all]"      # preferred
pipx install "markitdown[all]"         # alternative

macOS のシステム Python（3.9）で pip install をそのまま使うのは避けてください。pip が古い markitdown 0.0.1a1 を黙って解決してしまい、[all] エクストラも正常に動作する CLI もありません。インストール時に 0.0.1a1 または "does not provide the extra 'all'" と表示された場合は、インタープリターが古すぎます。uv tool install または uv venv -p 3.12 を使用してください。

[all] を指定すると、すべてのオプションのコンバーターがインストールされます。必要なものだけをインストールする場合は、pdf、docx、pptx、xlsx、xls、outlook、audio-transcription、youtube-transcription、az-doc-intel、az-content-understanding のエクストラを選べます。不足しているエクストラは MissingDependencyException に表示されます。

環境でグローバルインストールが禁止されている場合は、一時的な venv を使い、<venv>/bin/markitdown を直接呼び出してください。

単一ファイル

markitdown report.pdf -o report.md      # write to a file
markitdown report.pdf                    # stdout — good for piping into a prompt
curl -sL "$URL" | markitdown -x html     # stdin: add -x/-m hints for reliable detection

便利なフラグ（全一覧：markitdown --help）：

フラグ	用途
-o FILE	標準出力の代わりに出力ファイルを指定します
-x EXT / -m MIME / -c CHARSET	形式のヒントです。主に標準入力で使用します
--keep-data-uris	インラインの base64 画像を保持します（デフォルトでは切り詰められます）
-p / --list-plugins	インストール済みのサードパーティ製プラグインを使用／一覧表示します
-d -e URL	Azure Document Intelligence（クラウド OCR）。参考資料を参照してください
--use-cu --cu-endpoint URL	Azure Content Understanding。参考資料を参照してください

ファイルがない場合や未対応の形式の場合、終了ステータスは 0 以外になります。ただし、画像のみのコンテンツでは、出力が空でも終了ステータスは0です。そのため、結果が空でないことを必ず確認してください。

一括変換

ディレクトリを変換する場合は、ループを自作せず、同梱のスクリプトを使用してください。

bash <skill-dir>/scripts/batch_convert.sh SRC_DIR [OUT_DIR]
# MARKITDOWN=/path/to/markitdown   if it isn't on PATH
# EXTENSIONS="pdf docx"             to narrow the file types

スクリプトは再帰的に処理し、ディレクトリ構造を OUT_DIR に再現します（または各ソースファイルの隣に出力します）。出力ファイル名は <file>.<ext>.md となるため、report.pdf と report.docx が競合しません。再実行時には最新の出力をスキップし、最後に EMPTY（OCR が必要）、FAILED（エラー内容を表示）、LEGACY（.doc／.ppt）のファイルを示す概要を出力します。該当ファイルは、判断が必要なものとしてユーザーに伝えてください。別の命名規則（例：report.md）を希望する場合は、スクリプトを書き換えるのではなく、dest= の行を調整してください。

変換に適した形式

入力	結果
.docx	見出し、リスト、表、リンク。最初の行が Word のヘッダー行として指定されていない表では、空の | | | ヘッダーが作られ、実際のヘッダーは最初のデータ行になります。表が重要な場合は修正してください
.pptx	スライドごとに 1 つのセクション（``）、発表者ノートは ### Notes: の下に配置されます
.xlsx / .xls	シートごとに、表を含む ## SheetName セクションが 1 つ作られます
PDF（デジタル）	テキストと、pdfplumber で抽出した表。複雑な複数列レイアウトでは順序が乱れる場合があります
HTML、RSS/Atom、Wikipedia、Bing の検索結果	メインコンテンツを Markdown として出力します
CSV / JSON / XML / .ipynb	表／テキスト／ノートブックのセル
EPUB、Outlook .msg	章／ヘッダーと本文
ZIP	対応する各ファイルを ## File: name の下に出力します
音声（.wav .mp3 .m4a .mp4）	メタデータと、Google の無料 Web Speech API による文字起こし。音声をアップロードします。ネットワークが必要です
YouTube URL	タイトル、説明、利用可能な場合は文字起こし
画像（.jpg .png）	EXIF メタデータ（exiftool が必要）と、任意の LLM によるキャプションのみ。OCR は行いません

旧形式の .doc／.ppt は未対応です（UnsupportedFormatException）。先に変換してください。 macOS では textutil -convert docx memo.doc を使うか、LibreOffice で soffice --headless --convert-to docx memo.doc を実行してから、markitdown を実行してください。

画像のみのコンテンツ（スキャン、写真）

PDF や画像から空、またはほぼ空の出力が得られる場合、テキストは文字ではなくピクセルです。ユーザーにそのことをはっきり伝えたうえで、次の方法を選んでください。

1. 自分で読み取る。 画像や PDF（例：Read ツール）を表示できる場合は、ファイルを開いて書き起こします。数ページなら、これが最も手早い方法であることがよくあります。これは markitdown の出力ではなく、自分で書き起こしたものだと伝えてください。
2. ローカル OCR（インストール済みの場合）：ocrmypdf scan.pdf out.pdf を実行してから out.pdf を markitdown に渡すか、画像の場合は tesseract scan.png - を実行します。
3. クラウド OCR：Azure Document Intelligence（-d -e ...）を使います。ドキュメントが Azure に送信されるため、ユーザーの同意を得た場合に限ります。

変換に成功したかのように、空の .md を決して返さないでください。

Python API

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("report.pdf")   # path, URL, or binary file-like object
text = result.markdown              # the Markdown string (alias: .text_content)
title = result.title                # may be None

ストリーム、エラー処理、LLM による画像のキャプション、Azure、プラグインについては、references/python-api.md をご覧ください。

結果を渡す前に

• 出力を確認してください。 head で表示するか、内容を読みます。表が正しく変換されていること、テキストが文字化けしたり空になったりしていないことを確認し、問題がある場合はその旨を伝えてください。
• プライバシー。 オフライン変換ではデータはローカルにとどまりますが、音声の文字起こし、YouTube、LLM によるキャプション、Azure ではコンテンツが外部に送信されます。機密ファイルをこれらの方法で処理する前に許可を求め、キー（OPENAI_API_KEY、Azure の認証情報）はコードに記述せず、環境変数に設定してください。
• 出力が大きい場合。 長い PDF からは、数 MB の Markdown が生成されることがあります。すべてを会話に出力するのではなく、ファイルに書き込み、必要な部分を読み込むか grep してください。