---
name: web-to-markdown
description: 將網頁（單頁或多頁爬取）轉換為乾淨的 Markdown 格式，方便 AI 分析理解。支援單頁模式和爬蟲模式（追蹤連結、同域抓取）。
---

# Web to Markdown Skill

將任意網頁轉換成結構清晰的 Markdown，讓 AI 能更有效率讀取網頁內容。適合用於：
- 分析競品功能頁、定價頁
- 爬取文件站點（docs site）
- 將整個網站的主要頁面轉換為 AI 可讀格式

## 前置需求

使用前先確認 Python 套件已安裝：

```bash
pip install requests beautifulsoup4 html2text lxml
```

## 兩種使用模式

### 模式一：單頁轉換

```bash
python claude/skills/web-to-markdown/scripts/web_to_md.py \
  --url "https://example.com/features" \
  --output "scraped/features.md"
```

### 模式二：爬蟲模式（追蹤同域連結）

```bash
python claude/skills/web-to-markdown/scripts/web_to_md.py \
  --url "https://example.com" \
  --crawl \
  --depth 2 \
  --output-dir "scraped/example-com/"
```

參數說明：
- `--url`：起始 URL（必填）
- `--crawl`：啟用爬蟲模式，追蹤同域連結
- `--depth N`：爬蟲深度，預設為 2（首頁=0，首頁連結的頁面=1，以此類推）
- `--same-path`：只爬取相同路徑前綴下的連結（例如只爬 `/docs/` 目錄下的頁面）
- `--output`：單頁模式的輸出檔案路徑
- `--output-dir`：爬蟲模式的輸出目錄，每個頁面存成獨立 `.md` 檔
- `--max-pages N`：最多爬取 N 頁，防止無限爬取（預設 50）
- `--delay N`：每次請求間隔秒數，避免對伺服器造成壓力（預設 1.0）
- `--exclude`：排除含有特定關鍵字的 URL（可多次使用）

## 在 Agent 中使用

當 pm-competitor-analyst 需要分析競品網站時：

```python
# 1. 先用爬蟲模式抓取競品網站
Bash: python .claude/skills/web-to-markdown/scripts/web_to_md.py \
      --url "https://competitor.com" \
      --crawl --depth 2 \
      --output-dir "docs/prd/drafts/competitor-site/" \
      --exclude "/blog" --exclude "/login" --exclude "/signup"

# 2. 讀取轉換好的 Markdown 檔案進行分析
Read: docs/prd/drafts/competitor-site/index.md
Read: docs/prd/drafts/competitor-site/features.md
Read: docs/prd/drafts/competitor-site/pricing.md
```

## 輸出格式說明

每個轉換後的 Markdown 文件開頭包含：
```
---
title: [頁面標題]
url: [原始 URL]
crawled_at: [抓取時間]
---
```

接著是清理過的正文 Markdown，包含：
- 標題層級（H1-H6）
- 段落文字
- 連結（保留為 `[文字](URL)`）
- 列表
- 表格（轉為 Markdown 表格）
- 移除：廣告、導航列、頁腳、Cookie 提示等雜訊

## 注意事項

- 爬蟲只抓取**同一域名**下的連結（不會跨到外部網站）
- 自動跳過圖片、PDF、ZIP 等非 HTML 資源
- 遇到 JavaScript 渲染的 SPA 網站，部分內容可能無法抓到（這個腳本使用靜態 HTTP 請求）
- 有些網站會封鎖爬蟲，遇到 403/429 時請手動儲存網頁後用 `--file` 模式
- 請遵守網站的 robots.txt 和使用條款