tuzi-url-to-markdown

URL から Markdown へ

Chrome CDP を使用して任意の URL を取得し、HTML をクリーンな Markdown に変換します。

スクリプトディレクトリ

重要：すべてのスクリプトは、このスキルの scripts/ サブディレクトリにあります。

エージェントの実行手順：

1. この SKILL.md ファイルのディレクトリパスを SKILL_DIR として特定します
2. スクリプトのパス = ${SKILL_DIR}/scripts/<script-name>.ts
3. このドキュメント内のすべての ${SKILL_DIR} を実際のパスに置き換えます

スクリプトリファレンス：

スクリプト	用途
scripts/main.ts	URL 取得用の CLI エントリーポイント

設定（EXTEND.md）

優先順位に従って、Bash を使用して EXTEND.md の有無を確認します：

# Check project-level first
test -f .tuzi-skills/tuzi-url-to-markdown/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.tuzi-skills/tuzi-url-to-markdown/EXTEND.md" && echo "user"

┌────────────────────────────────────────────────────────┬───────────────────┐ │ パス │ 場所 │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ .tuzi-skills/tuzi-url-to-markdown/EXTEND.md │ プロジェクトディレクトリ │ ├────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.tuzi-skills/tuzi-url-to-markdown/EXTEND.md │ ユーザーのホームディレクトリ │ └────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ 結果 │ アクション │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 見つかった │ 読み込んで解析し、設定を適用します │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 見つからない │ 必ず 初回セットアップを実行します（下記参照）。デフォルトを黙って作成してはいけません │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md で設定可能な項目：メディアをデフォルトでダウンロード | デフォルトの出力ディレクトリ | デフォルトのキャプチャモード | タイムアウト設定

初回セットアップ（ブロッキング）

重要：EXTEND.md が見つからない場合、EXTEND.md を作成する前に、必ず AskUserQuestion を使用してユーザーに設定を尋ねてください。確認せずにデフォルト設定で EXTEND.md を作成してはいけません。これはブロッキング操作です。セットアップが完了するまで、変換を進めてはいけません。

1 回の呼び出しですべての質問を含めて、AskUserQuestion を使用します：

質問 1 — ヘッダー：「メディア」、質問：「ページ内の画像や動画をどのように扱いますか？」

• 「毎回確認（推奨）」 — Markdown を保存した後、メディアをダウンロードするか尋ねます
• 「常にダウンロード」 — メディアを imgs/ および videos/ ローカルディレクトリに常にダウンロードします
• 「ダウンロードしない」 — Markdown 内の元のリモート URL を保持します

質問 2 — ヘッダー：「出力」、質問：「デフォルトの出力ディレクトリはどこですか？」

• 「url-to-markdown（推奨）」 — ./url-to-markdown/{domain}/{slug}.md に保存します
• （ユーザーは「その他」を選択してカスタムパスを入力できます）

質問 3 — ヘッダー：「保存」、質問：「設定をどこに保存しますか？」

• 「ユーザー（推奨）」 — ~/.tuzi-skills/（すべてのプロジェクト）
• 「プロジェクト」 — .tuzi-skills/（このプロジェクトのみ）

ユーザーの回答後、選択した場所に EXTEND.md を作成し、「設定を [path] に保存しました」と確認してから続行します。

完全なリファレンス：references/config/first-time-setup.md

対応キー

キー	デフォルト	値	説明
download_media	ask	ask / 1 / 0	ask = 毎回確認、1 = 常にダウンロード、0 = ダウンロードしない
default_output_dir	空	パスまたは空	デフォルトの出力ディレクトリ（空 = ./url-to-markdown/）

値の優先順位：

1. CLI 引数（--download-media、-o）
2. EXTEND.md
3. スキルのデフォルト設定

機能

• JavaScript を完全にレンダリングする Chrome CDP
• 2 つのキャプチャモード：自動またはユーザー待機
• メタデータ付きのクリーンな Markdown 出力
• 待機モードにより、ログインが必要なページにも対応
• 画像や動画をローカルディレクトリにダウンロード

使用方法

# Auto mode (default) - capture when page loads
npx -y bun ${SKILL_DIR}/scripts/main.ts <url>

# Wait mode - wait for user signal before capture
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --wait

# Save to specific file
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> -o output.md

# Download images and videos to local directories
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --download-media

オプション

オプション	説明
<url>	取得する URL
-o <path>	出力ファイルのパス（デフォルト：自動生成）
--wait	キャプチャ前にユーザーの合図を待機します
--timeout <ms>	ページの読み込みタイムアウト（デフォルト：30000）
--download-media	画像／動画アセットをローカルの imgs/ と videos/ にダウンロードし、Markdown のリンクをローカルの相対パスに書き換えます

キャプチャモード

モード	動作	使用する場面
Auto（デフォルト）	ネットワークがアイドル状態になったらキャプチャします	公開ページ、静的コンテンツ
Wait（--wait）	準備ができたことをユーザーが知らせます	ログインが必要なページ、遅延読み込み、ペイウォール

Wait モードのワークフロー：

1. --wait を指定して実行 → スクリプトに「準備ができたら Enter キーを押してください」と表示されます
2. ページの準備ができたかユーザーに確認します
3. 標準入力に改行を送信してキャプチャを開始します

出力形式

url、title、description、author、published、captured_at フィールドを含む YAML フロントマターの後に、変換された Markdown コンテンツが続きます。

出力ディレクトリ

url-to-markdown/<domain>/<slug>.md

• <slug>：ページタイトルまたは URL パスから生成します（kebab-case、2～6 語）
• 名前が競合する場合：タイムスタンプ <slug>-YYYYMMDD-HHMMSS.md を追加します

--download-media が有効な場合：

• 画像は Markdown ファイルと同じ場所の imgs/ に保存されます
• 動画は Markdown ファイルと同じ場所の videos/ に保存されます
• Markdown 内のメディアリンクはローカルの相対パスに書き換えられます

メディアのダウンロードワークフロー

EXTEND.md の download_media 設定に基づきます：

設定	動作
1（常に）	--download-media フラグを指定してスクリプトを実行します
0（なし）	--download-media フラグを指定せずにスクリプトを実行します
ask（デフォルト）	以下の毎回確認するフローに従います

毎回確認するフロー

1. --download-media を指定せずにスクリプトを実行します → Markdown が保存されます
2. 保存された Markdown にリモートメディアの URL（画像／動画リンク内の https://）がないか確認します
3. リモートメディアが見つからない場合 → 完了です。確認は不要です
4. リモートメディアが見つかった場合 → AskUserQuestion を使用します：
   • header：「Media」、question：「N 個の画像／動画をローカルファイルにダウンロードしますか？」
   • 「Yes」— ローカルディレクトリにダウンロードします
   • 「No」— リモート URL のままにします
5. ユーザーが承認した場合 → --download-media を指定してスクリプトを再度実行します（Markdown をローカルパスに書き換えて上書きします）

環境変数

変数	説明
URL_CHROME_PATH	カスタム Chrome 実行ファイルのパス
URL_DATA_DIR	カスタムデータディレクトリ
URL_CHROME_PROFILE_DIR	カスタム Chrome プロファイルディレクトリ

トラブルシューティング：Chrome が見つからない場合 → URL_CHROME_PATH を設定します。タイムアウトする場合 → --timeout の値を大きくします。複雑なページの場合 → --wait モードを試します。

拡張機能のサポート

EXTEND.md を使用して設定をカスタマイズできます。パスとサポートされているオプションについては、Preferences セクションを参照してください。