技能介绍

解决什么问题

团队的知识库、个人笔记和文档归档迟早会遇到一件事：把网上的一篇好文章完整搬进 Markdown。用浏览器「另存为」会得到满屏的 nav、广告和脚本残留；复制粘贴正文则会丢失图片、表格和代码块，而那些图片往往还是远程链接，过段时间就 404 了。手工整理一篇带十张图的长文，通常要花十几分钟，还得逐个下载重命名。

url2markdown 就是针对这个场景的小工具：输入一个网页 URL，输出一篇干净的 Markdown 文件，图片全部落到本地，正文结构原样保留。

它如何工作

整个流程可以拆成七步：

抓取：用浏览器风格的 User-Agent 请求页面，降低被反爬拦截的概率
解析元数据：提取标题、描述、作者、日期，写成 YAML frontmatter
定位正文：优先找 <main>、<article> 或 content 容器，把导航和广告剥离出去
提取图片：遍历 img 标签，并处理 srcset，优先拿高分辨率版本
下载图片：按顺序编号存进本地 images/ 目录
转 Markdown：标题、段落、列表、代码块、表格、引用、分隔线都有对应映射
生成成品：frontmatter、正文、图片相对路径引用、带来源 URL 的页脚

输出目录默认是 ./output，也可以用第二个参数指定路径。首次运行时会自动安装 requests 和 beautifulsoup4，需要 Python 3.6+。

适用边界

几件事值得提前知道：

JS 渲染的页面抓不全。SPA/React/Vue 站点的内容如果是客户端渲染的，抓到的 HTML 可能只有骨架。这种情况建议从浏览器开发者工具里找真实 API 响应，或换无头浏览器方案
图片多的页面会慢。脚本会跳过失败的图片继续跑，但总耗时会上去
链接只保留文字。为保持整洁，Markdown 里的超链接会被去掉，只留锚文本
网络错误会直接退出，图片缺失只会告警跳过，无效 URL 会自动补上 https:// 前缀