obsidian-importのMarkItDown変換を実ファイルでテストした

以前の記事で紹介したyoutube-to-obsidianは、その後PDFやスライドも同じ流れでノート化したくなり、MicrosoftのMarkItDownを組み込んで対応した。YouTube専用ではなくなったのでリポジトリ名もobsidian-importに改名している。

これで長い論文のPDFや100枚超えのスライド、長編のブログ記事、TEDのトークなんかを、全部読んだり観たりしなくてもObsidianに要約ノートとして取り込めるようになった。1時間の動画を観なくても、整理されたノートを数分で読めば済む。インプットの効率がまるで違う。

とはいえ機能を組み込んだ時点ではモックテストしか書いておらず、実際のPDFやPPTXを食わせての動作確認はやっていなかった。今回はその検証を潰した話。

PDFで早速エラー

手元にあったPDFを食わせてみたら、こうなった。

変換エラー: PdfConverter recognized the input as a potential .pdf file,
but the dependencies needed to read .pdf files have not been installed.

MarkItDownはPDF処理にpdfminerを使うが、これはオプション依存になっていて pip install markitdown だけでは入らない。pip install markitdown[pdf] か markitdown[all] が必要だった。

install.shでは素の markitdown しかインストールしていなかったので、markitdown[all] に修正した。DOCX・PPTX・XLSX等も同様にオプション依存があるので、全形式をサポートするなら最初からallを入れておくのが無難だ。

各形式のテスト結果

依存を直した後、手元のファイルとダミーデータで一通り試した。

形式素材結果
PDF履歴書・職務経歴書日本語テキスト抽出OK。FontBBox警告が大量に出るが変換結果に影響なし
DOCXダミー文書見出し・段落がMarkdownに正しく変換
PPTXダミースライドスライド番号付きで変換
XLSXダミー表Markdownテーブルに変換
URLexample.comHTML→Markdown変換OK
画像JPG/PNGテキストが無いため最小文字数チェックで弾かれる（仕様通り）

PDFのFontBBox警告はpdfminerの既知の問題で、フォント情報が不完全なPDFで出る。stderrに大量に流れて焦るが、変換結果には影響しない。

重複スキップも確認

同じURLを2回変換してみると、2回目はちゃんとスキップされた。

[1/1] https://example.com
  スキップ（処理済み）

convert.pyはソースのMD5ハッシュでファイル名を決めていて、.transcripts/ に同名ファイルがあればスキップする。ここは既にモックテストで検証済みだったが、実際に動かしても問題なかった。

修正した箇所

変更は依存パッケージの指定を3箇所直しただけ。README.mdやCLAUDE.mdにもMarkItDownの記載はあるが、ツール名としての言及だけなので修正不要だった。

ファイル変更内容
install.shmarkitdown → markitdown[all]
SKILL.md同上
~/.claude/commands/obsidian-import.md同上（SKILL.mdのコピー）

自分で使わないと見つからない

今回の問題はモックテストでは見つけられない類のものだった。MarkItDown().convert() の戻り値をモックしている以上、依存パッケージが足りなくてインポート時に落ちるかどうかはテストできない。

CIで markitdown[all] の全依存を入れると重くなるし、PDFやPPTXの実ファイルをリポジトリに含めるのも微妙だ。モックテストはそのまま残して、実ファイルでのインテグレーション検証は手元で手動実行する運用にした。

結局、自分のツールは自分で使ってみないとわからない。テストが全部通っていても、実際にPDFを投げた瞬間に落ちる。前回の記事でも字幕優先への変更は講義動画を実際に試して初めて見えたボトルネックだった。モックやCIで品質を担保しつつ、最後は自分がユーザーとして使い倒すのが一番早い。