markdown-fetch

Markdown Fetch

markdown.new サービスを使用して、Web コンテンツをクリーンな Markdown として効率的に取得します。

このツールを使う理由

• 生の HTML と比べてトークンを 80% 削減
• コンテキストウィンドウに 5 倍のコンテンツを収容
• 外部依存関係や解析ライブラリが不要
• 3 段階の変換（Markdown 優先、AI によるフォールバック、ブラウザーでのレンダリング）

起動条件

次の場合に、このスキルが自動的に起動します。

• ユーザーが URL を指定した場合（例：「https://example.com を読んで」）
• Web コンテンツの抽出、取得、分析を依頼された場合
• Web ページの要約を依頼された場合
• 記事、ブログ、ドキュメントの URL を処理する必要がある場合

クイックスタート

# Fetch any URL
scripts/fetch.sh "https://example.com"

# Use browser rendering for JS-heavy sites
scripts/fetch.sh "https://example.com" --method browser

# Retain images in output
scripts/fetch.sh "https://example.com" --retain-images

一般的な使用パターン

ユーザーが次のように依頼した場合：

• 「この記事を読んでください：https://...」→ このスキルを使ってコンテンツを取得します
• 「https://... を要約してください」→ まずこのスキルで取得し、その後に要約します
• 「このページには何が書かれていますか：https://...」→ コンテンツを取得します
• 「https://... からテキストを抽出してください」→ このスキルを使います

変換方法

auto（デフォルト） - Markdown 優先で試し、必要に応じて AI またはブラウザーにフォールバックします
ai - Cloudflare Workers AI を使用して変換します
browser - JavaScript を多用するコンテンツをブラウザーで完全にレンダリングします

オプション

--method <auto|ai|browser> - 変換方法
--retain-images - 出力に画像参照を保持します
--output <file> - 標準出力ではなくファイルに保存します

出力

メタデータ付きのクリーンな Markdown を返します。

---
title: Page Title
url: https://example.com
method: auto
duration_ms: 725
fetched_at: 2026-03-07T12:00:00Z
---

# Content here...

使用する場面

• 記事、ドキュメント、ブログ投稿の抽出
• Web コンテンツを使った RAG パイプラインの構築
• Web ページの要約
• 分析用のコンテンツ取得
• サイトの Markdown 形式への変換

実装に関するメモ

このサービスは次の処理を行います。

• コンテンツネゴシエーション（Accept: text/markdown）
• Cloudflare Workers AI による変換
• 動的コンテンツのブラウザーでのレンダリング
• 方法間の自動フォールバック

よくある問題

HTML の解析に失敗する

症状： 出力が空になる、コンテンツが途中で切れる、または「Error: No content in response」が表示される

主な原因：

• ページレイアウトの変更によって CSS セレクターが機能しなくなっている
• 動的コンテンツがデフォルトでレンダリングされない（--method browser を使用）
• ページ構造に一般的でない HTML パターンが使われている（iframe、shadow DOM、Web Components）

デバッグと回避策：

# 1. Check if the page loads at all
curl -s "https://example.com" | head -c 500

# 2. Try browser rendering (handles JS-heavy sites)
scripts/fetch.sh "https://example.com" --method browser

# 3. Check what the service is getting
scripts/fetch.sh "https://example.com" 2>&1 | head -20

# 4. If still empty, the page may use iframes or require auth

ベストプラクティス： シングルページアプリ、ソーシャルプラットフォーム、またはコンテンツ量の多いダッシュボードでは、必ず --method browser を使用してください。

---

レート制限と IP ブロック

症状： HTTP 429（リクエストが多すぎます）、403（アクセス禁止）、または接続タイムアウト

主な原因：

• 同じドメインへの短時間での複数リクエスト
• 対象サイトによってサービスの IP アドレスがブラックリストに登録されている
• ボット検出が作動している（User-Agent ヘッダー、リクエストパターン）
• Cloudflare/WAF によるブロック（トラフィックの多いサイトでよく発生）

デバッグと回避策：

# 1. Check HTTP status code
curl -s -w "\n%{http_code}\n" -o /dev/null "https://example.com"

# 2. Test with curl directly (bypasses service)
curl -H "User-Agent: Mozilla/5.0" "https://example.com" | head -c 500

# 3. Add delays between requests (if fetching multiple URLs)
for url in url1 url2 url3; do
  scripts/fetch.sh "$url"
  sleep 5  # Wait 5 seconds between requests
done

# 4. If blocked, try from different IP or use residential proxy
# For markdown.new service: no built-in proxy rotation; consider mirror services

ベストプラクティス： 複数のページを処理する場合は、サイトの robots.txt を尊重し、適切なリクエスト間隔を設けてください。一部のサイトでは Retry-After ヘッダーが必要です。

---

エンコーディングの問題

症状： 文字化け、判読できない文字、ASCII 以外のコンテンツ（絵文字、アクセント記号、CJK）の欠落

主な原因：

• ページのヘッダーで宣言された文字セットと実際のコンテンツが一致していない
• サービスが Content-Type の文字セット宣言を尊重していない
• UTF-8 と Latin-1 の不一致
• 変換中に絵文字や特殊記号が削除されている

デバッグと回避策：

# 1. Check the page's declared charset
curl -sI "https://example.com" | grep -i "charset"

# 2. Save raw HTML and inspect encoding
curl -s "https://example.com" > raw.html
file raw.html
head -c 200 raw.html | od -c  # Show raw bytes

# 3. Try the markdown.new service and check output
scripts/fetch.sh "https://example.com" | file -  # Check output encoding

# 4. If output is garbled, convert explicitly
scripts/fetch.sh "https://example.com" | iconv -f UTF-8 -t UTF-8 > fixed.md

ベストプラクティス： 出力が有効な UTF-8 であることを必ず確認してください。文字化けが発生した場合は、ページの文字セットが一致していない可能性があります。サイトの管理者に連絡するか、より堅牢な --method browser を使用してください。

---

JavaScript でレンダリングされるコンテンツ

症状： ページは返されますが、コンテンツが表示されない、空の状態で読み込まれる、またはデータの代わりに読み込み中のスピナーが表示されます

根本原因：

• ページがクライアントサイドの JavaScript を使用してコンテンツをレンダリングしています（React、Vue、Angular など）
• デフォルトの auto メソッドでは、JS を実行せずに HTML の骨格だけを取得します
• ページのレンダリング後にコンテンツが読み込まれます（遅延読み込み、無限スクロール）
• JavaScript の実行に認証または API キーが必要です

デバッグと回避策：

# 1. Fetch with browser rendering (executes JS)
scripts/fetch.sh "https://example.com" --method browser

# 2. Check what the auto method returns
scripts/fetch.sh "https://example.com" --method auto

# 3. Inspect page source to confirm JS-rendering
curl -s "https://example.com" | grep -i "react\|vue\|angular\|<div id=\"app\""

# 4. If content still missing, page may require interaction
# (e.g., clicking buttons, scrolling) — no workaround in current service

ベストプラクティス： 最新のウェブアプリ、ニュースサイト、過去 5 年以内に構築されたサイトでは、デフォルトで --method browser を使用してください。auto メソッドは高速ですが、JS でレンダリングされるコンテンツを取得できません。

---

認証とペイウォールコンテンツ

症状： コンテンツの代わりにログインページが返される、「続きを読むには購読してください」と表示される、または HTTP 401/403 が返されます

根本原因：

• ページの閲覧にログイン／認証が必要です
• コンテンツがペイウォールの内側にあります（購読、会員登録）
• IP ベースのアクセス制限があります（地域制限）
• セッションベースの認証に必要な情報（Cookie）が提供されていません

デバッグと回避策：

# 1. Check if curl can access without auth
curl -s "https://example.com/article" | head -c 300

# 2. Identify authentication method
curl -sI "https://example.com" | grep -i "auth\|set-cookie\|www-authenticate"

# 3. Try public/preview version if available
# For paywalled sites, look for preview URLs or RSS feeds
curl -s "https://example.com/rss" | head -c 500

# 4. Check for paywall indicators
curl -s "https://example.com/article" | grep -i "paywall\|subscribe\|login required"

# 5. If member-only, request your credentials in the conversation
# (Don't embed in scripts — use prompt)

ベストプラクティス： このスキルは、設計上、認証やペイウォールを回避できません。保護されたコンテンツについては、次の方法を試してください：

• 利用可能であれば、公開プレビューリンクを使用する
• 認証済みのアクセスをユーザーに依頼する
• RSS フィードを試す（ペイウォールがなく、要約が掲載されていることがよくあります）
• アーカイブサービス（archive.org、ペイウォールコンテンツ向けの 12ft.io）を別途確認する

---

サービス側の障害

症状： HTTP エラーコード（5xx）、タイムアウト、または不正な JSON レスポンスが返されます

根本原因：

• markdown.new サービスが停止しているか、過負荷になっています
• リクエスト本文の形式が正しくありません（無効な URL、必須フィールドの不足）
• サービスのレスポンスが破損しているか、不完全です
• Cloudflare Workers がタイムアウトしています（10MB を超えるページ、または応答の遅いサーバー）

デバッグと回避策：

# 1. Check service health
curl -s "https://markdown.new/health" 2>&1 | head

# 2. Verify request format
jq -n --arg url "https://example.com" --arg method "auto" \
  '{url: $url, method: $method, retain_images: false}' | jq .

# 3. Retry with exponential backoff
for attempt in {1..3}; do
  result=$(scripts/fetch.sh "https://example.com" 2>&1)
  if [[ $? -eq 0 ]]; then
    echo "$result"
    break
  fi
  sleep $((2 ** attempt))  # 2s, 4s, 8s
done

# 4. If service is down, no workaround available
# — try again later or use alternative (curl, browser, etc.)

ベストプラクティス： このサービスはステートレスで、通常は安定して動作します。障害が続く場合は、代わりに curl を直接使用するか、別の情報源をユーザーに尋ねてください。

---

トラブルシューティングの判断フロー

No content returned?
  ├─ Check if site requires JavaScript
  │   └─ YES → Use --method browser
  │   └─ NO → Continue
  ├─ Check if site requires authentication
  │   └─ YES → Use authenticated request (see Paywall section)
  │   └─ NO → Continue
  ├─ Check for encoding issues
  │   └─ YES → Garbled text → likely site charset mismatch
  │   └─ NO → Continue
  └─ Service may be down → Wait and retry

Getting rate-limited (HTTP 429)?
  ├─ Add delays between requests (5-10 seconds)
  └─ If persistent, try different time or request fewer pages

Truncated or broken output?
  └─ Try --method browser (more robust but slower)

Can't access paywalled content?
  └─ No workaround — try public preview, RSS, or archive services