mcpField
T
to-markdown

to-markdown

github.com/mathews-tomドキュメント337102 回インストール2 日前に更新
リポジトリ

to-markdown について

to-markdown は、MarkItDown でファイル、URL、HTML を Markdown に変換するスキルです。URL の取得手順に加え、抽出品質や既知の制限を確認します。

主な機能

  1. 01ファイルと HTML の Markdown 変換
  2. 02trafilatura による静的ページ取得
  3. 03Playwright による描画済み・認証ページ取得
  4. 04YouTube の字幕抽出
  5. 05出力構造と抽出品質の確認

活用シーン

  1. 01PDF を Markdown に変換
  2. 02URL から記事本文を抽出
  3. 03複数ファイルを個別の Markdown に変換

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mathews-tom/armory --skill to-markdown

インストール後、Claude Code で/to-markdownを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
cases.yaml
references/
fetch.md
formats.md
install.md

詳細

Markdown への変換

変換エンジンとして MarkItDown を使用し、URL 用の軽量な取得レイヤーを組み合わせて、あらゆるファイルや URL をクリーンな Markdown に変換します。

リファレンスファイル

ファイル目的
references/formats.md形式ごとの処理に関する注意事項、内部エンジン、既知の制限
references/fetch.mdURL 取得レイヤー：trafilatura + Playwright の戦略
references/install.mdすべてのバリエーション向けの依存関係インストールガイド

判断フロー

ツールを使う前に、入力の種類を判定してください。

Input type?
  Local file path        -> markitdown directly
  URL
    YouTube URL          -> markitdown directly (transcript extraction built-in)
    Static page          -> trafilatura fetch -> markitdown on HTML result
    JS-rendered / auth   -> Playwright fetch -> markitdown on result
  Pasted HTML string     -> markitdown directly on string

URL には web_fetch や WebFetch を使用しないでください。変換パイプラインを維持するため、references/fetch.md で説明されている取得レイヤーを経由してください。

基本的な変換ワークフロー

ステップ 1：依存関係を確認する
uv pip show markitdown || uv pip install 'markitdown[all]' trafilatura

選択的なインストール方法と依存関係の全一覧については、references/install.md を参照してください。

ステップ 2：変換する
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("path/to/file.pdf")
print(result.text_content)
ステップ 3：ワークフロー
  1. 入力の種類（ファイルパス、URL、生の HTML）を検出します。
  2. URL の場合は、最初に取得レイヤーを実行します（references/fetch.md を参照）。
  3. ローカルファイルまたは取得したコンテンツに対して、markitdown の変換を実行します。
  4. 必要に応じて後処理します（定型部分を取り除く、主要なコンテンツに絞るなど）。
  5. 以下の出力規約に従って、出力を書き込むかインラインで返します。

出力規約

コンテキスト出力動作
単一ファイル、ユーザーがファイルを希望<input_stem>.md を同じディレクトリに書き込みます
単一ファイル、インラインでのリクエストMarkdown を会話内で返します
バッチ（複数ファイル）各ファイルを <stem>.md に書き込み、生成したものを要約します
URL<slug>.md を現在のディレクトリに書き込むか、インラインで返します
別のワークフローへのパイプ入力result.text_content 文字列のみを返します

デフォルト：「このファイルを変換して」ならファイルを書き込みます。「これを読んで」や「何が書いてある？」ならインラインで返します。

出力例

ソース（表を含む2段組 PDF）：

Annual Report 2024                    Financial Highlights
Revenue grew 12% year-over-year...    | Metric   | 2023  | 2024  |
                                      | Revenue  | $4.2B | $4.7B |
                                      | EBITDA   | $1.1B | $1.3B |

変換後の Markdown：

# Annual Report 2024

Revenue grew 12% year-over-year...

## Financial Highlights

| Metric  | 2023  | 2024  |
| ------- | ----- | ----- |
| Revenue | $4.2B | $4.7B |
| EBITDA  | $1.1B | $1.3B |

複数段組のレイアウトは、直線的なフローに統合されます。表は Markdown の表として保持されます。見出しはフォントサイズや太さから推定されます。

LLM による画像の説明（オプトイン）

Markitdown は、PPTX ファイルや画像ファイルの画像を説明するための llm_client に対応しています。デフォルトでは有効にしないでください。コストや遅延が発生し、予期しない API 呼び出しが行われるためです。まずユーザーに確認してください：「このファイルには画像が含まれています。Claude を使って画像を説明しますか？追加の API 呼び出しが発生します。」

import anthropic
from markitdown import MarkItDown

client = anthropic.Anthropic()
md = MarkItDown(llm_client=client, llm_model="claude-sonnet-4-6")
result = md.convert("presentation.pptx")

Opus 4.7 の画像認識の上限： Opus 4.7 は、長辺が最大 2,576 ピクセル（約 3.75 MP）の画像を受け付けます。これは従来の Claude モデルのおよそ 3 倍です。画像の多いドキュメントを llm_model="claude-opus-4-7" に渡す場合は、事前にダウンサンプリングせず、高解像度の元画像を保持してください。以前は OCR が必要だったスクリーンショットや図表内のテキストも、直接読み取れる場合があります。

エラー処理

重大度条件対応
Terminal対応していない形式（コンバーターが存在しない）直ちにユーザーに報告し、再試行しない
Terminalパスワードで保護された Office ファイルユーザーに報告する。プログラムによる回避策はない
Terminalファイルが見つからない／パスが無効正確なパスを報告し、ユーザーに確認を依頼する
RecoverPDF の出力が空スキャン文書の可能性があります。references/formats.md の OCR 手順に進む
Recoverオプションの依存関係が不足（例：playwright）依存関係をインストールしてから、変換を再試行する
RecoverURL の取得でペイウォールページが返される取得の制限を報告し、再試行や回避を試みない
Recovertrafilatura の結果が空references/fetch.md に従い、Playwright による取得方法に進む
result = md.convert(path)
if not result.text_content.strip():
    raise ValueError(f"No text extracted from {path}. See references/formats.md for OCR options.")

Markdown が空のまま返されることがないようにしてください。失敗の重大度と、関連する参照ファイルへの案内を明示してください。

既知の不足とエスカレーション

  • HTML の忠実度：markitdown は内部で html2text を使用するため、複雑なレイアウトでは構造が失われます。DOM 構造が重要で、高い忠実度が求められる HTML 変換には、Node のサブプロセス経由で Turndown を使うことを提案してください。
  • 厳しいペイウォール：取得レイヤーはコンテンツではなく、アクセス制限ページを返します。これは変換の問題ではなく、取得の制限です。
  • スキャンされた PDF（画像のみで、テキストレイヤーがないもの）：markitdown の出力はほぼ空になります。OCR ワークフロー（Azure Document Intelligence または Tesseract）に進んでください。references/formats.md を参照してください。
  • 保護された Office ファイル：パスワードで保護された DOCX／XLSX は失敗します。ユーザーに知らせてください。

調整ルール

  1. 変換後の出力には、原文書のページごとに少なくとも 10 語を含める必要があります。このしきい値を下回る場合は、抽出結果が空と見なし、エラー処理表に従ってエスカレーションしてください。
  2. 原文書の表は、出力でも Markdown の表として表示する必要があります。原文に表があるのに変換後に欠落している場合は、ユーザーに知らせてください。
  3. 原文書の見出し階層（H1 > H2 > H3）を維持する必要があります。構造化された文書が見出しのない平坦な出力になる場合は、変換品質の問題を示しています。
  4. URL の変換結果に、ナビゲーション要素、Cookie バナー、フッターの定型文を含めてはいけません。含まれている場合は、include_tables=True を指定して trafilatura で再処理し、定型文を除去してください。
  5. 複数シートの XLSX では、シートごとに明確な見出しを付けたセクションを出力する必要があります。シートが欠落している場合は、一部のみの変換として、抽出されたシートを報告してください。

制限事項

  • ペイウォールの回避はできません。試みずに、その旨を記録してください。
  • Turndown の統合機能は組み込まれていません。実行環境が異なります（Node.js）。
  • スケジュール実行／一括クロールには対応していません。1 回の呼び出しにつき変換は 1 件です。
  • Markdown 以外の出力形式には対応していません。
  • 自動生成された YouTube の字幕には、専門用語の誤りが含まれることがあります。
  • スキャンされた PDF には外部 OCR が必要です。markitdown 単体では出力が空になります。

コメント

Markdown 対応