documentation-scraper

slurp-ai を使用したドキュメントのスクレイピング

概要

slurp-ai はドキュメントサイトをスクレイピングし、AI エージェントのコンテキストに最適化された単一の Markdown ファイルにまとめます。軽量で高速かつ決定的に動作します。スクレイピングに AI は使用せず、AI に読み込ませるためのツールです。

重要：サンドボックスの外で実行

このスキルのコマンドはすべてサンドボックスの外で実行する必要があります。 以下を含むすべての Bash コマンドで dangerouslyDisableSandbox: true を使用してください。

• which slurp（インストールの確認）
• node analyze-sitemap.js（サイトマップの分析）
• slurp（スクレイピング）
• ファイルの確認コマンド（wc、head、cat など）

サンドボックスでは、Web スクレイピングに必要なネットワークアクセスとファイル操作がブロックされます。

事前確認：インストールの確認

スクレイピングを始める前に、slurp-ai がインストールされていることを確認してください。

which slurp || echo "NOT INSTALLED"

インストールされていない場合は、次を実行するようユーザーに依頼してください。

npm install -g slurp-ai

必要条件： Node.js v20 以降

slurp-ai がインストールされていることを確認するまで、スクレイピングを進めないでください。

コマンド

コマンド	用途
slurp <url>	取得とコンパイルを一度に実行
slurp fetch <url> [version]	ドキュメントをダウンロードし、partials のみに保存
slurp compile	partials を単一ファイルにコンパイル
slurp read <package> [version]	ローカルのドキュメントを読み込む

出力： slurp_partials/ 内の partials から slurp_compiled/compiled_docs.md を作成します。

重要：最初にサイトマップを分析

slurp を実行する前に、必ずサイトマップを分析してください。 サイト全体の構造を把握でき、--base-path と --max の設定に役立ちます。

手順 1：サイトマップ分析を実行

付属の analyze-sitemap.js スクリプトを使用します。

node analyze-sitemap.js https://docs.example.com

次の情報が出力されます。

• ページの総数（--max の設定に役立ちます）
• セクションごとにグループ化された URL（--base-path の設定に役立ちます）
• 適切なフラグを指定した slurp コマンドの提案
• 命名パターンを把握するための URL の例

手順 2：出力を解釈

出力例：

📊 Total URLs in sitemap: 247

📁 URLs by top-level section:
   /docs                          182 pages
   /api                            45 pages
   /blog                           20 pages

🎯 Suggested --base-path options:
   https://docs.example.com/docs/guides/     (67 pages)
   https://docs.example.com/docs/reference/  (52 pages)
   https://docs.example.com/api/             (45 pages)

💡 Recommended slurp commands:

   # Just "/docs/guides" section (67 pages)
   slurp https://docs.example.com/docs/guides/ --base-path https://docs.example.com/docs/guides/ --max 80

手順 3：分析結果に基づいて範囲を選択

サイトマップの内容	対応
合計 50 ページ未満	サイト全体をスクレイピング：slurp <url> --max 60
50～200 ページ	--base-path を指定して関連セクションに範囲を絞る
200 ページ以上	範囲を絞る必要があります。特定のサブセクションを選択してください
サイトマップが見つからない	--max 30 で開始し、partials を確認して調整

手順 4：slurp コマンドを組み立てる

サイトマップのデータを基に、適切なパラメーターを設定できるようになりました。

# From sitemap: /docs/api has 45 pages
slurp https://docs.example.com/docs/api/intro \
  --base-path https://docs.example.com/docs/api/ \
  --max 55

重要なポイント： 開始 URL はクロールを開始する場所です。ベースパスは、たどるリンクを絞り込みます。両者は異なっていてもかまいません（ベースパス自体が 404 を返す場合に便利です）。

よくあるスクレイピングのパターン

ライブラリのドキュメント（バージョン指定）

# Express.js 4.x docs
slurp https://expressjs.com/en/4x/api.html --base-path https://expressjs.com/en/4x/

# React docs (latest)
slurp https://react.dev/learn --base-path https://react.dev/learn

API リファレンスのみ

slurp https://docs.example.com/api/introduction --base-path https://docs.example.com/api/

ドキュメントサイト全体

slurp https://docs.example.com/

CLI オプション

フラグ	デフォルト	用途
--max <n>	20	スクレイピングするページの最大数
--concurrency <n>	5	ページリクエストの並列数
--headless <bool>	true	ヘッドレスブラウザーを使用
--base-path <url>	start URL	このプレフィックスに一致するリンクに絞り込む
--output <dir>	./slurp_partials	partials の出力ディレクトリ
--retry-count <n>	3	リクエスト失敗時の再試行回数
--retry-delay <ms>	1000	再試行の間隔
--yes	-	確認プロンプトをスキップ

コンパイルオプション

フラグ	デフォルト	用途
--input <dir>	./slurp_partials	入力ディレクトリ
--output <file>	./slurp_compiled/compiled_docs.md	出力ファイル
--preserve-metadata	true	メタデータブロックを保持
--remove-navigation	true	ナビゲーション要素を削除
--remove-duplicates	true	重複を排除
--exclude <json>	-	除外する正規表現パターンの JSON 配列

ヘッドレスモードを無効にする場合

次の場合は --headless false を使用してください。

• 静的 HTML のドキュメントサイト
• JavaScript のレンダリングが不要で、スクレイピングを高速化したい場合

デフォルトはヘッドレス（true）です。 SPA を含む最新のドキュメントサイトのほとんどで動作します。

出力構造

slurp_partials/              # Intermediate files
  └── page1.md
  └── page2.md
slurp_compiled/              # Final output
  └── compiled_docs.md       # Compiled result

クイックリファレンス

# 1. ALWAYS analyze sitemap first
node analyze-sitemap.js https://docs.example.com

# 2. Scrape with informed parameters (from sitemap analysis)
slurp https://docs.example.com/docs/ --base-path https://docs.example.com/docs/ --max 80

# 3. Skip prompts for automation
slurp https://docs.example.com/ --yes

# 4. Check output
cat slurp_compiled/compiled_docs.md | head -100

よくある問題

問題	原因	解決策
--max の値が正しくない	ページ数を推測している	まず analyze-sitemap.js を実行します
スクレイピングされるページが少なすぎる	--max の制限（デフォルトは20）	サイトマップの分析結果に基づいて --max を設定します
コンテンツが欠落している	JavaScript がレンダリングされていない	--headless true（デフォルト）になっていることを確認します
クロールが停止する／遅い	レート制限	--concurrency 3 に減らします
セクションが重複している	類似したコンテンツ	--remove-duplicates（デフォルト）を使用します
対象外のページが含まれている	ベースパスが広すぎる	サイトマップを使って正しい --base-path を特定します
プロンプトが自動化を妨げている	対話モード	--yes フラグを追加します

スクレイピング後の使用方法

出力される Markdown は、AI のコンテキスト注入用に設計されています。

# Check file size (context budget)
wc -c slurp_compiled/compiled_docs.md

# Preview structure
grep "^#" slurp_compiled/compiled_docs.md | head -30

# Use with Claude Code - reference in prompt or via @file

使用しない場合

• OpenAPI／Swagger の API 仕様書：代わりに専用のパーサーを使用します
• GitHub の README：raw.githubusercontent.com から直接取得します
• npm パッケージのドキュメント：ソースコードと README を読むほうが適していることがよくあります
• 頻繁に更新されるドキュメント：キャッシュ戦略を検討します