markdown-fetch

Markdown Fetch

使用 markdown.new 服务，高效地将网页内容提取为干净的 Markdown。

为什么使用此工具

• 比原始 HTML 减少 80% 的 Token
• 上下文窗口中可容纳 5 倍的内容
• 无需外部依赖或解析库
• 三级转换（优先使用 Markdown、AI 回退、浏览器渲染）

触发条件

在以下情况下，此技能应自动触发：

• 用户提供 URL（例如，“读取 https://example.com”）
• 用户要求提取／获取／分析网页内容
• 用户要求总结网页
• 用户需要处理文章／博客／文档 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...

使用场景

• 提取文章、文档或博客文章
• 使用网页内容构建 RAG 流水线
• 总结网页
• 获取内容以供分析
• 将网站转换为 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 内容（表情符号、重音符号、中日韩字符）

根本原因：

• 页面标头中声明的字符集与实际内容不符
• 服务未遵循 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 方法只获取 HTML 框架，不执行 JS
• 内容在页面渲染后加载（延迟加载、无限滚动）
• 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

最佳实践： 对现代 Web 应用、新闻网站以及过去 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