いろんなファイルをMarkdownに変換する「MarkItDown」を試す
以前からチラホラとは見かけていたが、2025/04のTechnology Radar Volume 32で、Language & Frameworks に "Trial"として挙がっていたのが「MarkItDown」。
いろんなフォーマットをMarkdownに変換するツール。この手のツールは過去色々触ってきたが、MarkItDownが果たしてどういう独自性を持っているか?を確認してみたい。
GitHubレポジトリ
MarkItDown
MarkItDownは、LLMや関連するテキスト分析パイプラインで使用するための、様々なファイルをMarkdownに変換する軽量Pythonユーティリティです。この点では、textractに最も似ていますが、重要な文書構造とコンテンツをMarkdownとして保持することに重点を置いています(見出し、リスト、テーブル、リンクなどを含む)。出力は人間にとっても適度に読みやすく親しみやすいものですが、これはテキスト分析ツールによって消費されることを目的としており、人間による消費のための高忠実度の文書変換に最適なオプションではないかもしれません。
現在、MarkItDownは以下をサポートしています:
- PowerPoint
- Word
- Excel
- 画像(EXIFメタデータとOCR)
- 音声(EXIFメタデータと音声文字起こし)
- HTML
- テキストベースの形式(CSV、JSON、XML)
- ZIPファイル(内容を反復処理)
- YouTube URL
- EPub
- ...その他多数!
なぜMarkdownなのか?
Markdownは非常にプレーンテキストに近く、マークアップやフォーマットは最小限ですが、重要な文書構造を表現する方法を提供します。OpenAIのGPT-4oなどの主流のLLMは、ネイティブにMarkdownを"話し"、しばしばプロンプトなしでMarkdownを応答に組み込みます。これは、大量のMarkdownフォーマットのテキストで訓練されており、それをよく理解していることを示唆しています。副次的な利点として、Markdownの規則はトークン効率も非常に高いです。
インストール
ざっと見た感じ、MarkItDownのインストール・利用方法は以下
- Pythonパッケージをインストール(PyPi or ソース)してCLIで。
- Azure Document Intelligence経由
- Python API経由
- Dockerイメージをコマンドラインから実行
Dockerなら環境を汚さずに使えてよさそうに思うが、今回はPythonパッケージで試してみる。
ローカルのMacで。
uvでプロジェクト作成
uv init -p 3.12.9 markitdown-work && cd markitdown-work
パッケージを追加するのだが、extrasが色々用意されている。
オプションの依存関係
MarkItDownには、様々なファイル形式を有効にするためのオプションの依存関係があります。このドキュメントの前半では、
[all]
オプションですべてのオプション依存関係をインストールしました。ただし、より細かい制御のために個別にインストールすることもできます。例えば:pip install 'markitdown[pdf, docx, pptx]'
これにより、PDF、DOCX、およびPPTXファイルの依存関係のみがインストールされます。
現在、以下のオプション依存関係が利用可能です:
[all]
すべてのオプション依存関係をインストール[pptx]
PowerPointファイル用の依存関係をインストール[docx]
Wordファイル用の依存関係をインストール[xlsx]
Excelファイル用の依存関係をインストール[xls]
古いExcelファイル用の依存関係をインストール[pdf]
PDFファイル用の依存関係をインストール[outlook]
Outlookメッセージ用の依存関係をインストール[az-doc-intel]
Azure Document Intelligence用の依存関係をインストール[audio-transcription]
wavおよびmp3ファイルの音声文字起こし用の依存関係をインストール[youtube-transcription]
YouTubeビデオの文字起こし取得用の依存関係をインストール
今回はall
で。
uv add "markitdown[all]"
+ markitdown==0.1.1
Usageを見てみる。
uv run markitdown --help
usage: SYNTAX:
markitdown <OPTIONAL: FILENAME>
If FILENAME is empty, markitdown reads from stdin.
EXAMPLE:
markitdown example.pdf
OR
cat example.pdf | markitdown
OR
markitdown < example.pdf
OR to save to a file use
markitdown example.pdf -o example.md
OR
markitdown example.pdf > example.md
Convert various file formats to markdown.
positional arguments:
filename
options:
-h, --help show this help message and exit
-v, --version show the version number and exit
-o OUTPUT, --output OUTPUT
Output file name. If not provided, output is written to stdout.
-x EXTENSION, --extension EXTENSION
Provide a hint about the file extension (e.g., when reading from stdin).
-m MIME_TYPE, --mime-type MIME_TYPE
Provide a hint about the file's MIME type.
-c CHARSET, --charset CHARSET
Provide a hint about the file's charset (e.g, UTF-8).
-d, --use-docintel Use Document Intelligence to extract text instead of offline conversion. Requires a valid Document Intelligence
Endpoint.
-e ENDPOINT, --endpoint ENDPOINT
Document Intelligence Endpoint. Required if using Document Intelligence.
-p, --use-plugins Use 3rd-party plugins to convert files. Use --list-plugins to see installed plugins.
--list-plugins List installed 3rd-party plugins. Plugins are loaded when using the -p or --use-plugin option.
--keep-data-uris Keep data URIs (like base64-encoded images) in the output. By default, data URIs are truncated.
CLI
Usageは上にある通り、基本的にはMarkdownに変換したいファイルを指定するだけって感じ。
サンプルとして、神戸市が公開している観光に関する統計・調査資料のうち、「令和5年度 神戸市観光動向調査結果について」のPDFを使用させていただく。
PDFの特徴
- サイズ: 1.8MB
- ページ数: 21
- 縦長レイアウト
- 文字は横書き
- 表・グラフ等含む
参考までに一部抜粋。
ではMarkdownに変換してみる。
uv run markitdown r5_doukou.pdf > r5_doukou.md
なお、上記は以下のような書き方もできる
# -oで出力先Markdownファイルを指定
markitdown r5_doukou.pdf -o r5_doukou.md
# パイプでmarkitdownに渡す
cat r5_doukou.pdf | markitdown
で、実行すると、なんか色々出た・・・
Cannot set gray non-stroke color because /'P1' is an invalid float value
Cannot set gray non-stroke color because /'P2' is an invalid float value
Cannot set gray non-stroke color because /'P1' is an invalid float value
Cannot set gray non-stroke color because /'P2' is an invalid float value
(snip)
が、一応ファイルは出力できてるため、1ページ目と4ページ目の箇所を見てみる。
1ページ目
令和5年度 神戸市観光動向調査結果について
本調査は,来神観光客の特質と神戸市内の観光動向を把握し,今後の観光行政の参考とす
調 査 目 的
ることを目的に実施。
調査員が対面にてアンケート項目を聞き取りする形で実施。
調 査 方 法
調 査 日
① 令和5年 5月 13 日(土)・20 日(土)※
② 令和5年 9月 9日(土)
③ 令和5年 11 月 25 日(土)/12 月2日(土)※
④ 令和6年 2月 10 日(土)・17 日(土)・24 日/3月 30 日(土)※
※雨天等により、一部の調査地点については延期して実施。
調 査 地 点
地区
北野
市街地
神戸港
六甲・摩耶
有馬
須磨・舞子
西北神
調査地点
NO
1 北野町広場
2 北野工房のまち
3 南京町広場
4 総合インフォメーションセンター
5 旧居留地
6 神戸布引ロープウェイハーブ園山麓駅
7 白鶴酒造資料館内
8 王子動物園内
9 県立美術館前
10 さんちか夢広場
11 神戸空港屋上階展望ロビー
12 IKEA神戸
13 能福寺(兵庫大仏)
14 兵庫津ミュージアム
15 神戸海洋博物館前及び周辺
16 中突堤中央ターミナル周辺
17 umie モザイク
18 ハーバーランド総合インフォメーション前
19 六甲天覧台
20 摩耶山掬星台広場
21 六甲山牧場内
22 六甲ガーデンテラス内
23 有馬温泉観光総合案内所前
24 金の湯前
25 六甲有馬ロープウェイ有馬温泉駅
26 須磨離宮公園
27 舞子公園(舞子海上プロムナード)
28 神戸ワイナリー(農業公園)
29 神戸フルーツ・フラワーパーク大沢園内
30 神戸三田プレミアム・アウトレット
サンプル数
246
154
218
198
201
203
205
235
217
208
212
192
147
204
200
208
201
213
209
200
215
211
214
216
232
202
230
235
209
215
6,250
合計
4ページ目
分析の詳細
(1)性別構成
●性別構成としては、全市では「男性」が43.5%、「女性」が56.5%となっている。
●地区別にみると、『六甲・摩耶』を除いた地区で女性の占める割合が高いが、『北野』では「女
性」が30.0ポイント高く、差が大きくなっている。
【図表1 性別構成】
(2)年齢構成
●年齢構成としては、全市では「60歳以上」が24.3%で最も高く、次いで「50歳代」(19.8%)、
「40歳代」(18.0%)、「20歳代」(16.9%)、「30歳代」(16.2%)の順となっており、40歳代以
上が6割を超える。
●地区別にみると、『須磨・舞子』では「60歳以上」(35.9%)が他の地区と比較して高くなっ
ている。
【図表2 年齢構成】
3
どうやら表は維持してくれず、画像も無視される模様。オプションにもこれらをカスタマイズするようなものは見当たらない。
このあたりは使用するファイルによっても変わってきそうなので、各自のファイルで実際に試すことをオススメ。
手元のファイルでいくつか試してみた。基本的にすべて日本語のもの、
- Word: OK
- Excel: OK
- PowerPoint: OK
- HTML: OK
- 音声ファイル(WAV): NG → 何も出力されなかった。
- 画像ファイル(PNG): NG → 何も出力されなかった。
- YouTube: NG → URLを指定すればよいようだが、文字起こしの言語が日本語にできずエラー
Office系ドキュメントはそれなりのMarkdownで出力される印象。あと、その他についてはドキュメントがないので使い方が正しいのかわからない、オプションもほとんど無いので不明・・・
プラグイン
MarkItDownにはサードパーティのプラグインシステムがある。
インストールされているプラグインの一覧を確認。
uv run markitdown --list-plugins
デフォルトだと何もプラグインはインストールされていない。
Installed MarkItDown 3rd-party Plugins:
* No 3rd-party plugins installed.
Find plugins by searching for the hashtag #markitdown-plugin on GitHub.
プラグインは GitHubで#markitdown-plugin
ハッシュタグで検索するらしいのだが・・・自分が調べた限り、それっぽいものは見当たらなかった。
まとめ
とりあえずめちゃめちゃ手軽で簡単ではあるのだけど、他のソリューションに比べると、できることはそんなになさそう。自分の観測範囲だとOffice系ドキュメントならまあいけるのかも?というところで、他のフォーマットについては確認できなかった。というかドキュメントが無いのでなんともかんとも・・・・
でもまあ、精度はめちゃめちゃ高いが誰でも簡単に構築して普段遣いできる、みたいなツールもそうそうないような気もするので、これぐらいのシンプルさが落とし所としては必要なのかなーという気もしなくもない。あとは英語だとそこまで問題にならないとかはありそう。
実際に試してみてユースケースに合うかを確認するのが良いと思う。お手軽はお手軽です。
一応過去にはこういうのも試している。他にもありそうだけど。興味があれば。