markitdown-cli

MarkItDown CLI 完全使用ガイド

用途は明確です。このスキルを基に、LLM が正しく、コピー＆ペーストできる markitdown コマンドライン呼び出しを生成できるようにします。

オフライン時の基準：markitdown コマンドの argparse（packages/markitdown/src/markitdown/__main__.py を参照）に基づきます。パラメーターが「存在するかどうか」の判断は、すべてソースコードを基準とします。この記事と公式 README の内容が食い違う場合は、公式の情報を優先してください。

---

このスキルを使う場面

✅ このスキルを使う場面（CLI／コマンドラインのみの質問）：

• ユーザーが「markitdown コマンドの使い方は？どんなパラメーターがある？」と尋ねたとき
• ユーザーが PDF／PPT／Word を一括で Markdown に変換したいとき
• ユーザーが stdin のストリーム（パイプ／curl の出力）を markitdown に渡したいとき
• ユーザーが「インストール済みのプラグインを一覧表示するには？」「プラグインを有効にするには？」と尋ねたとき
• ユーザーが Azure Document Intelligence／Content Understanding の CLI 設定について尋ねたとき
• ユーザーが「CLI の出力を stdout ではなくファイルに書き込むには？」と尋ねたとき

❌ このスキルを使わない場面：

• Python API を使いたい場合 → markitdown-awesome の references/api/python-api.md
• OCR（埋め込み画像／スキャン PDF／LLM Vision）を行いたい場合 → markitdown-ocr
• MarkItDown とは何か、どの形式をサポートしているかを知りたい場合 → markitdown-awesome
• ユーザーがすでに markitdown を使えていて、ベストプラクティスだけを尋ねている場合 → このスキルの説明に回らず、直接例を示します

⚠️ 判断が難しい場合：

• ユーザーが「OCR はどうすればよい？」と尋ねた場合 → デフォルトで markitdown-ocr を使います（現在の CLI は LLM パラメーターをサポートしていないため）。
• ユーザーが「PDF を変換するには？」と尋ね、用途を説明していない場合 → デフォルトで CLI の方法を案内します。ただし、スキャン文書の場合は Azure DI を推奨することも伝えます。

---

ワークフロー

CLI に関する質問に回答する際は、毎回次の手順を踏みます。

Step 1 — 入力と出力を確認する

• 入力：<file>／stdin／http(s)://… のどれですか？
• 出力：stdout／-o out.md／tee で再利用、のどれですか？
• 特別な形式について案内する必要はありますか（-x／-m）？

Step 2 — バックエンドを選択する（デフォルト／Azure DI／Azure CU）

• デフォルト（ローカル）：-d も --use-cu も指定しません
• 高品質な PDF／スキャン文書：-d -e <endpoint>
• マルチモーダル／構造化フィールド：--use-cu --cu-endpoint <endpoint>

Step 3 — プラグインを有効にするか選択する

• OCR（LLM Vision）→ -p を指定します。ただし、CLI に --llm-client／--llm-model はないため、Python でラッパーを作成する必要があります（markitdown-ocr を参照）。
• カスタムプラグイン → 同様に -p を指定するだけです

Step 4 — コマンドを組み立てて、自己チェックする

Validation 自己チェックリストに沿って確認します。

Step 5 — エラーに対処する

ユーザーから MissingDependencyException／UnsupportedFormatException などの例外が提示された場合は、§8 のトラブルシューティング早見表に進みます。

Step 6 — 次のステップを提案する

コマンドを出力した後、「一括処理／CI への統合／Docker が必要な場合は、examples/advanced/safe-batch-processing.md をご覧ください」と一言添えます。

---

Validation（自己チェックリスト）

コマンドを生成したら、毎回次の項目を確認します。

• -d と --use-cu を同時に指定していないか？
• -d を指定する場合、-e <endpoint> も必ず指定しているか？
• --use-cu を指定する場合、--cu-endpoint <endpoint> も必ず指定しているか？
• stdin から読み込み、ファイルに拡張子がない場合、-x または -m を追加しているか？
• HTTP URL を使用する場合、SSRF のリスクを考慮しているか？
• 出力に ASCII 以外の文字が含まれる場合、stdout ではなく -o out.md を推奨しているか？
• ユーザーがプラグインをインストール済みで有効にしていない場合、-p の追加を案内しているか？
• CLI に --llm-client がないことを踏まえ、OCR をコマンドラインから有効にできると誤って約束していないか？
• --list-plugins と「ファイル変換」を同じコマンドラインに含めていないか？

---

注意点

発生頻度の高い順です。

1. -d と --use-cu は併用できません — argparse が mutually_exclusive_group を強制するため、両方を指定するとエラーになります。
2. -d には -e の指定が必要です — 指定しない場合、__main__.py が _exit_with_error("Document Intelligence Endpoint is required …") を実行します。
3. --use-cu には --cu-endpoint の指定が必要です — 同様のロジックです。
4. CLI に --llm-client／--llm-model はありません — OCR をコマンドラインから有効にするには、Python でラッパーを作成する必要があります（詳しくは markitdown-ocr を参照）。存在しないフラグを作らないでください。
5. --list-plugins を指定すると sys.exit(0) が実行されます — 「ファイル変換」と同じコマンドラインに含めても、変換処理は実行されません。
6. stdin から読み込み、拡張子がない場合は -x または -m が必要です — 指定しないと accepts() がすべて False になり、UnsupportedFormatException が発生します。
7. -c の charset は codecs.lookup で検証されます — 間違えると _exit_with_error("Invalid charset: …") が実行されます。一般的に使用できる値は utf-8、utf-16、latin-1、gbk（システムの codecs に登録されている必要があります）です。
8. CLI の出力で日本語が文字化けする場合 — ターミナルの LANG != *UTF-8 のときは、-o out.md を追加してファイルに保存します。
9. --keep-data-uris はデフォルトでは保持されません — 出力内の base64 画像は切り詰められます。画像が必要な場合は --keep-data-uris を使用します。
10. HTTP URL には実際の GET リクエストが送信されます — convert_uri 内部でリクエストが行われるため、SSRF のリスクは呼び出し側が負います。本番環境では Python の requests.get() と convert_response() の使用を推奨します。
11. 大きなファイルはメモリのピーク使用量に注意してください — convert_local は open(path, "rb") でファイル全体を一度に読み込むため、数百 MB の PDF ではメモリが不足することがあります。ストリーミングが必要な場合は convert_stream を使用します。
12. オプションの依存関係が不足している場合 — MissingDependencyException が発生したら、形式に応じて pip install 'markitdown[<extra>]' で追加します。角括弧を省略しないでください。
13. Azure の認証情報 — DI／CU はデフォルトで既定の認証情報チェーンを使用します。CLI にはキーを明示的に渡すオプションがありません。認証情報は環境／SDK によって決まります。
14. --cu-file-types はカンマ区切りの文字列を受け付けます — ファイルタイプ名が間違っていると _exit_with_error("Unknown file type: …") が実行されます。ContentUnderstandingFileType の列挙型に合わせてください。
15. パイプが切断されると BrokenPipeError が発生します — markitdown f.pdf | head を実行すると、MarkItDown は Markdown 全体を書き込んだ後、print で EPIPE が発生します。結果には影響しませんが、head の終了コードが非ゼロになるため、set -o pipefail は失敗します。

---

1. 最も基本的な形式

markitdown <file>            # 转 stdout
markitdown <file> -o out.md  # 写文件
cat <file> | markitdown      # 从 stdin 读
markitdown < <file>          # 等价写法

<file> は省略できます。省略した場合は stdin から読み込みます。 注意：stdin から読み込む場合、MarkItDown は実際の拡張子を認識できないため、-x または -m で指定する必要があります。

2. 完全なパラメーター一覧

短いオプション	長いオプション	型	説明
-v	--version	flag	バージョンを表示して終了
-o	--output	str	出力ファイル。省略時は stdout に書き込みます
-x	--extension	str	拡張子のヒント（先頭の . は省略可能）。例：-x pdf
-m	--mime-type	str	MIME のヒント。例：-m application/pdf
-c	--charset	str	文字セットのヒント。例：-c utf-8
-d	--use-docintel	flag	Azure Document Intelligence バックエンドを使用します。-e も同時に指定する必要があります
-e	--endpoint	str	Document Intelligence endpoint URL
—	--use-cu / --use-content-understanding	flag	Azure Content Understanding を使用します。--cu-endpoint が必要です
—	--cu-endpoint	str	Content Understanding endpoint
—	--cu-analyzer	str	カスタム analyzer ID。省略時はファイルの種類に応じて自動選択します
—	--cu-file-types	str	カンマ区切りで指定します。例：--cu-file-types pdf,jpeg,mp4
-p	--use-plugins	flag	markitdown.plugin エントリーポイントで検出されるサードパーティ製プラグインを有効にします
—	--list-plugins	flag	インストール済みプラグインを一覧表示して終了します
—	--keep-data-uris	flag	出力に data:image/...;base64,… URI を保持します（デフォルトでは切り詰められます）

排他グループ：-d（--use-docintel）と --use-cu は相互に排他的で、どちらか一方のみ選択できます。

3. 入出力マトリックス

用途	コマンドテンプレート	使用する場面
単一ファイル → stdout	markitdown a.pdf	他のツールに直接パイプで渡したい場合
単一ファイル → ファイル	markitdown a.pdf -o a.md	最も一般的な「ファイルに出力」する方法
stdin → stdout	cat a.pdf | markitdown	プログラムから呼び出し、中間ファイルを作成しない場合
stdin → ファイル	cat a.pdf | markitdown -o a.md	shell コマンドを連結する場合
stdin + ヒント	cat blob | markitdown -x pdf	ファイルに拡張子がない場合、または拡張子が誤っている場合
stdin + MIME	curl … | markitdown -m application/pdf	リモートから取得して変換する場合
HTTP URL	markitdown https://example.com/doc.html	CLI に URL を直接渡すと URI として解析されます

CLI に -i/--input パラメーターは現在ありません。stdin または <file> プレースホルダーを使用してください。

4. 出力の制御

• stdout のエンコーディング処理：_handle_output() は sys.stdout.encoding と errors="replace" を使用して書き込むため、端末のエンコーディングが原因でクラッシュすることはありません。
• 大きな出力：MarkItDown はデフォルトで print(result.markdown) によって一度に出力します。ログファイルに出力しないでください。-o の指定をおすすめします。
• 画像の data URI：--keep-data-uris で、出力 Markdown に data:image/...;base64,… を保持するかどうかを制御します（デフォルトではサイズ削減のために切り捨てられます）。

5. プラグインの管理

# 看装了哪些插件
markitdown --list-plugins
# 输出类似:
# Installed MarkItDown 3rd-party Plugins:
#   * ocr              (package: markitdown_ocr)
#   * my-plugin        (package: my_pkg)
# 若没有:打印 "  * No 3rd-party plugins installed."

# 启用插件
markitdown scanned.pdf -p
# 加 LLM 参数配合 markitdown-ocr:
markitdown scanned.pdf -p --llm-client openai --llm-model gpt-4o

⚠️ markitdown --list-plugins と -p/--use-plugins は競合しません。ただし、__main__.py では --list-plugins が実行されると直ちに sys.exit(0) を呼び出すため、「ファイル変換」と同じコマンドラインで組み合わせることはできません。

5.1 環境変数による OpenAI 互換クライアントの設定（markitdown-ocr と併用）

export OPENAI_API_KEY=sk-...
markitdown scanned.pdf -p --llm-client openai --llm-model gpt-4o

⚠️ 注意：現在、__main__.py の argparse には --llm-client と --llm-model オプションが登録されていません（これらは Python API の MarkItDown(llm_client=…, llm_model=…) でのみ使用できます）。CLI から OCR を有効にするには、現時点では 3 行の Python ラッパーを作成する方法が最も確実です（markitdown-ocr skill を参照）。今後、公式に CLI オプションが追加された場合は、公式の説明に従ってください。

6. Azure バックエンドの切り替え

6.1 Document Intelligence（-d -e）

markitdown scan.pdf -d -e "https://<resource>.cognitiveservices.azure.com/"

用途：高品質な PDF、スキャン文書、表の抽出。pip install 'markitdown[az-doc-intel]' が必要です。また、環境からこの endpoint にアクセスできる必要があります（Azure の認証情報はデフォルトのチェーンを使用します）。

6.2 Content Understanding（--use-cu --cu-endpoint）

# 自动选 analyzer(按文件类型:documentSearch/videoSearch/audioSearch)
markitdown report.pdf --use-cu --cu-endpoint "https://<cu>.services.ai.azure.com/"

# 自定义 analyzer
markitdown invoice.pdf --use-cu \
  --cu-endpoint "https://<cu>.services.ai.azure.com/" \
  --cu-analyzer "my-invoice-analyzer"

# 仅对部分类型启用 CU
markitdown mixed_files/ --use-cu \
  --cu-endpoint "https://<cu>.services.ai.azure.com/" \
  --cu-file-types pdf,jpeg,mp4

用途：マルチモーダル（文書／画像／音声／動画）、構造化された YAML front matter が必要な場合、カスタム分析器を使用する場合。

詳細な対応関係（CLI ↔ Python API ↔ サービス endpoint）は azure/endpoint-matrix.md を参照してください。実践用スクリプトは examples/azure/azure-backends.md を参照してください。

7. 代表的なワークフローの例

7.1 ディレクトリ内の PDF を一括で Markdown に変換する

find ./inbox -name '*.pdf' -print0 | while IFS= read -r -d '' f; do
  out="./md/$(basename "${f%.pdf}").md"
  markitdown "$f" -o "$out"
done

7.2 xargs と組み合わせて並列処理する（慎重に使用してください）

find ./inbox -name '*.pdf' -print0 \
  | xargs -0 -n1 -P4 -I{} sh -c 'markitdown "{}" -o "./md/$(basename "{}" .pdf).md"'

⚠️ PDF によっては、処理中に大量のメモリとネットワーク IO を使用します。並列度は CPU 数を超えないようにしてください。

7.3 jq／grep と組み合わせて後続のフィルタリングを行う

# 把 PDF 转 Markdown,然后保留所有 "##" 开头的章节
markitdown report.pdf | grep -E '^##' > outline.md

7.4 取得したウェブページを Markdown として保存する

curl -sL "https://example.com/article.html" \
  | markitdown -m text/html \
  > article.md

7.5 Docker を 1 行のコマンドで実行する

Dockerfile を参照してください（docker build -t markitdown:latest . の実行後）。

docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
# 等价于:
docker run --rm -v "$PWD":/data markitdown:latest /data/your-file.pdf -o /data/output.md

一括処理／CI／Docker の実践例については、examples/advanced/workflows.md と examples/advanced/safe-batch-processing.md を参照してください。

8. トラブルシューティング早見表

現象	確認コマンド／方法
MissingDependencyException が発生する	pip install 'markitdown[对应特性]' を実行します（例：[pdf]／[docx]／[pptx]）
UnsupportedFormatException	file <path> で実際の種類を確認し、-x／-m でヒントを指定します。または、対応する extras がインストールされていることを確認します
出力の日本語が文字化けする	端末の LANG=*UTF-8* を確認するか、-o out.md を追加して端末のエンコーディングの問題を回避します
-d を使用すると endpoint が見つからないというエラーが発生する	CLI では -e が必須です。それでも「endpoint required」と表示される場合は、-p も同時に指定していないか確認してください。場合によっては、パラメーターの順序を入れ替える必要があります
--use-cu を使用すると analyzer が存在しないというエラーが発生する	まずデフォルトの自動選択を使用し（--cu-analyzer を指定しない）、endpoint にアクセスできることを確認してください
出力から data:image… がすべて消えている	--keep-data-uris を追加します
プラグインをインストールしたのに convert が機能しない	markitdown --list-plugins でプラグインが認識されていることを確認し、次に -p を追加したことを確認します
OCR がまったく実行されない	markitdown-ocr skill を使用してください。llm_client の注入には Python API を使う必要があります

9. 安全上の注意

• MarkItDown は現在のプロセス権限で I/O を実行します。任意の URL を markitdown https://... に直接渡さないでください。そうした場合、SSRF のリスクは呼び出し側が負うことになります。
• コンテナー環境では、必ず --user と --read-only のボリュームマウントを制限してください。

10. 関連 Skill に切り替えるタイミング

ユーザーの質問	切り替え先
"MarkItDown とは何ですか、どの形式をサポートしていますか、アーキテクチャはどのように構成しますか?"	markitdown-awesome
"LLM（GPT-4o / Azure OpenAI）を使って OCR、スキャン PDF、埋め込み画像の OCR を行うにはどうすればよいですか?"	markitdown-ocr
"CLI ではなく Python API を使うにはどうすればよいですか?"	markitdown-awesome の references/api/python-api.md

11. プライバシーポリシー

この Skill はローカルのドキュメントとサンプルのみを提供し、ユーザーデータを収集、保存、送信することはありません。コマンドの実行と Azure エンドポイントとの通信は、ユーザー自身の環境から行われます。プライバシーに関する責任はユーザーが負います。

12. 参考リンク

• 公式 README
• 公式 argparse ソースコード
• Dockerfile
• パラメーター早見表：このリポジトリ内の references/cli/cheatsheet.md
• 関連 Skill：markitdown-awesome — npx skills add full-stack-skills/document-skills --skill markitdown-awesome でインストールした後、skill 名で指定します
• 関連 Skill：markitdown-ocr — npx skills add full-stack-skills/document-skills --skill markitdown-ocr でインストールした後、skill 名で指定します
• 完全インストール：npx skills add full-stack-skills/document-skills（全 11 個の skill を一度にインストールします）