jb-docs-scraper

文档爬取工具

将任意文档网站爬取为本地 Markdown 文件。使用 crawl4ai 进行异步网页爬取。

快速开始

# Scrape any documentation URL
uv run --with crawl4ai python ./references/scrape_docs.py <URL>

# Examples
uv run --with crawl4ai python ./references/scrape_docs.py https://mediasoup.org/documentation/v3/
uv run --with crawl4ai python ./references/scrape_docs.py https://docs.rombo.co/tailwind

默认将输出保存到 ./docs/<auto-detected-name>/。

前置条件（仅首次运行时需要）

uv run --with crawl4ai playwright install

用法

uv run --with crawl4ai python ./references/scrape_docs.py <URL> [OPTIONS]

选项

选项	描述	默认值
-o, --output PATH	输出目录	./docs/<auto-detected-name>
--max-depth N	最大链接深度	6
--max-pages N	要爬取的最大页面数	500
--url-pattern PATTERN	URL 过滤器（glob）	自动检测
-q, --quiet	禁止输出详细信息	False

示例

# Basic - scrape to ./docs/documentation_v3/
uv run --with crawl4ai python ./references/scrape_docs.py \
  https://mediasoup.org/documentation/v3/

# Custom output directory
uv run --with crawl4ai python ./references/scrape_docs.py \
  https://docs.rombo.co/tailwind \
  --output ./my-tailwind-docs

# Limit crawl scope
uv run --with crawl4ai python ./references/scrape_docs.py \
  https://tanstack.com/start/latest/docs/framework/react/overview \
  --max-pages 50 \
  --max-depth 3

# Custom URL pattern filter
uv run --with crawl4ai python ./references/scrape_docs.py \
  https://example.com/docs/api/v2/ \
  --url-pattern "*api/v2/*"

工作原理

1. 自动检测输入 URL 的域名和 URL 模式
2. 使用 BFS（广度优先搜索）策略爬取
3. 过滤内容，确保范围不超出文档专区
4. 将页面转换为整洁的 Markdown
5. 按照与 URL 路径相对应的目录结构保存

输出结构

docs/<name>/
  index.md           # Root page
  getting-started.md
  api/
    overview.md
    client.md
  guides/
    installation.md

故障排除

问题	解决方案
Playwright browser binaries are missing	运行 uv run --with crawl4ai playwright install
输出为空	检查 URL 模式是否匹配实际文档 URL。试试 --url-pattern
页面缺失	增大 --max-depth 或 --max-pages
爬取了错误的页面	使用更严格的 --url-pattern

提示

1. 先测试——使用 --max-pages 10，在完整爬取前验证配置
2. 检查输出名称——脚本会根据 URL 路径段自动检测
3. 可安全重新运行——文件会被覆盖，重复项会被跳过