scraping-html-to-markdown

用途

crawlberg scrape <url> 适用于用户只关注单个页面的场景。它返回 Markdown 以及完整的结构化负载（元数据、链接、图片、JSON-LD、HTTP 响应信息）。

输出 Markdown 或 JSON 两种格式。
JSON 模式返回顶层 ScrapeResult，包含 final_url（重定向后）、status_code、content_type、body_size、detected_charset。
markdown 字段包含 content、fit_content、tables、warnings；fit_content 是面向 LLM 优化的精简变体，tables 单独保留结构化表格数据。
metadata 包含 Open Graph（扁平 og_title/og_description/og_image）、Twitter Card、Dublin Core、文章标签、标题（H1–H6）、favicon、hreflang。
links 为扁平数组，每项带 link_type 判别字段（internal、external、anchor、document），可用 .links[] | select(.link_type=="external") 过滤。
images 覆盖 <img>、<picture>、srcset、og:image。
feeds、json_ld 为顶层数组，分别存放发现的 feed 与 JSON-LD 条目。
response_meta 提供 HTTP 头元数据（server、etag、cache-control 等）。

快速示例：

crawlberg scrape https://example.com/article --format markdown

JSON 形式（默认，下游需要元数据时）：

crawlberg scrape https://example.com/article --format json

参数说明：

脚本中读取 Markdown 字符串应使用 result.markdown.content。

抓取文章作为下游 LLM 上下文：crawlberg scrape https://blog.example.com/post-123 --format markdown > /tmp/article.md
使用代理与自定义 UA：crawlberg scrape https://example.com --proxy http://proxy.internal:3128 --user-agent "crawlberg (research@example.com)" --format json
仅提取 OG 元数据：crawlberg scrape https://example.com --format json | jq '.metadata | {title: .og_title, description: .og_description, image: .og_image}'

空内容或占位内容：静态抓取返回 JS 外壳时，JSON 输出中 markdown.content 很短或只含导航/页脚，markdown.warnings 提示 JS-render-required，metadata.headings 为空。可改用 --browser-mode always。
WAF 拦截：auto 模式可检测 8 家 WAF 厂商并自动通过无头 Chrome 重试；若强制 --browser-mode never，WAF 响应会直接返回。检查 .status_code，403/406/503 且带 WAF 头（server: cloudflare、x-amz-cf-id 等）即为迹象。
robots.txt 阻止抓取：若设置 --respect-robots-txt 且路径被禁止，抓取返回错误而非部分内容。仅在自己拥有或已获授权的站点上取消该标志。
字符集错误：多数页面声明 UTF-8，声明错误的页面可能在 markdown.content 中出现乱码。crawlberg 未提供编码覆盖选项（CrawlConfig 中没有 force_encoding/charset 字段，--config 会拒绝未知键），声明错误的字符集属于服务端缺陷，遇到时可重新获取原始字节并在下游转码。