最近在翻开源社区动态的时候，看到一个用 Rust 写的网页转 Markdown 小工具 Sol，顺手就点进去试了试，结果比预想的顺手不少。这个工具解决的问题其实很具体：把任意网页的正文内容，干净地转换成 Markdown 格式，方便本地存档、二次编辑，或者塞给 AI 做进一步处理。以前想要干这件事儿，要么靠在线服务（还得担心隐私和数据安全），要么装一堆浏览器插件，要么自己写爬虫脚本去解析 HTML。而 Sol 走的是另一条路——直接用 Rust 把整个流程打包成一个简易、独立的二进制工具，没那么多花活，却正好解决实际痛点。
作为平时经常要处理网页资料、做技术笔记、整理 RSS 订阅内容的人，我对这类工具的要求比较挑剔：首先转换格式要准，其次对网页正文的识别要稳，最后最好能简单集成进命令行流程。Sol 在这几个点上的完成度都还不错。本文会从工具的实际用法、底层转换思路、Rust 实现上的设计取舍，再到实际使用中的坑位排查，把一个命令行网页转 Markdown 工具从里到外说透，也算是对我自己折腾各类转换工具的一次系统梳理。
1. 为什么需要网页转 Markdown：不只是“复制粘贴”那么简单
很多人觉得网页转文字这事儿，直接全选复制再粘贴到笔记软件里不就行了？实际干过这活儿的人都知道，网页正文里塞着的导航链接、广告区块、推荐阅读、页脚信息，甚至各种跟踪脚本生成的无意义文本，全都会被一起复制进来，最后得到的是一堆需要手动清洗半天的垃圾内容。而 Markdown 转换工具的核心价值，不是完成“HTML 到 Markdown”这种格式层面的映射，而是在保留正文结构的同时，把干扰项尽量过滤干净。
1.1 内容归档与二次创作的需求场景
我个人最常用的场景是整理技术文章摘要。看到一篇有价值的深度好文，我想把正文存下来，做成带标题层级、代码块、引用块、链接的 Markdown 文件，放入自己的知识库。这样后续不管是写总结、做译稿，还是喂给本地大模型做语义索引，都比拿着一堆 HTML 页面要方便得多。Sol 这种工具能直接在命令行下把 URL 拉进来，输出一份干净的 .md 文件，配合脚本还能批量处理一批链接，这个体验比打开浏览器、逐个复制、手工排版快出好几倍。
另一个典型场景是文档快照。线上文档经常面临改版、下线、权限变动，曾经收藏过的好内容可能某天就突然打不开了。用 Sol 趁早把网页转成 Markdown 存到本地仓储里，相当于做了一个轻量级的网页备份。由于 Markdown 是纯文本格式，后续用 Git 管理还能对比历史版本差异，这是 PDF 快照或者 HTML 整页保存都很难做到的。
1.2 传统工具链的痛点与 Rust 方案的定位
过去我尝试过不少同类方案，各有各的别扭。基于 Node.js 生态的工具通常依赖一堆 npm 包，环境安装麻烦，跑起来内存占用也不小；用 Python 写的话，处理编码和依赖问题会比较头疼，发行给其他人的时候还得考虑 Python 环境是否兼容；浏览器插件方案又太重，为了一个简单的转换功能不得不常驻一个浏览器进程。Sol 这种用 Rust 编译成单个二进制文件的方案，在“工具”这个定位上天然有优势——不需要运行时，拷贝到哪都能用，启动快，内存占用低。对于命令行重度用户或者需要批量处理网页内容的脚本场景，这种轻量属性是很实在的加分项。
1.3 对内容质量的要求：不仅仅是格式转换
我对网页转 Markdown 工具还有一个隐性要求：转换结果是否“干净”。很多工具做出来的 Markdown，要么带着一堆样式相关的 class 残留，要么把很多无意义 div 强行套上列表符号，要么把代码块里的 HTML 实体转换得乱七八糟。Sol 的定位虽然是轻量工具，但它需要在“精确还原内容结构”和“过滤页面噪音”之间找到平衡点。判断一个转换工具是否合格，我一般拿一篇包含标题、列表、代码块、引用、表格的复杂技术文章去测试，如果输出能直接作为一篇可读性良好的 Markdown 文档，才算达到可用标准。Sol 在这方面的表现我会在后文逐步拆解。
2. Sol 的核心技术思路：HTML 语义解析与 DOM 遍历映射
网页转 Markdown 这件事，本质上可以拆成两个步骤：第一步是把原始 HTML 解析成一棵可操作的结构化文档树（DOM 树），第二步是遍历这棵树的节点，根据每个节点的语义标签，把它映射成对应的 Markdown 语法。很多初学爬虫的人喜欢用正则表达式直接去抠 HTML 文本，这种做法在结构稳定的网页上或许能用，但稍微遇到复杂嵌套就会出现匹配错乱，属于典型的本末倒置。Sol 之所以可靠，关键就在于它严格走“解析 DOM + 语义映射”的规范路线，而不是和字符串较劲。
2.1 HTML 解析：rust 生态里的 html5ever 方案
Rust 生态里做 HTML 解析，绕不开 html5ever 这个库。它是 Servo 引擎的解析组件，按照 HTML5 规范实现解析算法。用 html5ever 解析 HTML，能正确处理标签隐式闭合、嵌套错误、实体转义、残缺标签这些历史上的“脏乱差”问题——这些东西恰恰是正则表达式最容易翻车的地方。
Sol 在解析层面的做法是，在可配置的 DOM 树消费后使用RcDom这种低成本数据格式拿到文档对象模型。RcDom是一种基于引用计数的 DOM 树表示方法，节点之间的父子关系靠Rc<Node>的共享所有权来串联。这种设计带来一个好处：遍历多个子树时不需要深拷贝节点，树结构可以同时被多个操作安全引用，内存开销上比完全克隆要小得多。对一个小工具来说，这种实现既节约内存，又保持了架构上的简洁性。
实现层面，标准做法类似这样：
use html5ever::parse_document; use html5ever::rcdom::{Handle, NodeData, RcDom}; use tendril::TendrilSink; let dom = parse_document(RcDom::default(), Default::default()) .from_utf8() .read_from(&mut html.as_bytes()) .expect("failed to parse html");解析完之后，dom.document就是 DOM 树的根节点，后续所有转换逻辑都从这颗根节点开始向下遍历。当面对不规范 HTML 时，html5ever 的容错机制会自动修正标签结构，这也意味着之后的操作能够在相对规范的树上进行。
2.2 DOM 遍历与节点语义判断
拿到 DOM 树之后，核心工作就进入了转换阶段。通俗地讲，这是一次深度优先的森林遍历：从根节点出发，逐个访问子节点，根据节点的NodeData::Element里的标签名和属性，来决定怎么把节点内容映射成 Markdown。
遍历时几个重要的判断分支：
h1~h6标题标签：输出对应数量的#符号，生成标题语法。p段落标签：作为普通段落输出，并在段落前后补上空行。pre和code代码块标签：保留换行和缩进，必要时标注代码语言。a链接标签：需要同时拿到 href 属性与文本内容，合成[文本](链接)格式。ul/ol/li列表标签：根据嵌套层级生成不同缩进深度的-或1.前缀。img图片标签：根据 src 属性生成[图片描述](图片地址)结构，并兼顾 alt 文本。blockquote引用标签：在每行开头加上>前缀。table表格标签：收集行列数据，最终拼成 Markdown 表格语法。
Sol 的转换逻辑并不需要像浏览器渲染那样精确计算布局，只需“理解”每个标签在 Markdown 语境中应该扮演什么角色即可。这种思想其实很接近信息的重新编码，而不是字符串到字符串的简单替换。
2.3 正文提取策略：为什么需要净化 noise 节点
整个转换流程里最容易影响体验的坎，是页面上那些和正文无关的干扰节点。常见的有导航栏菜单、侧边栏推荐、页脚版权声明、分享按钮、评论区占位符等。如果直接遍历整棵 DOM 树，这些干扰项也会被转换成 Markdown，最后输出的文件里就会充斥着一堆无用碎片。
Sol 在架构设计上提供了一种两阶段机制：先在整个文档里定位真正的“正文容器”，再只对这个容器内做详细转换。定位正文容器时，可以优先考虑<article>、<main>这两个语义标签——它们就是为了承载主要页面内容而存在的。如果没有这些标签，则可以按统计算法寻找文本密度最高的区域，类似复杂的文本提取算法思路。这样既能保留文章本身的完整结构，又能将噪音节点排除在转换范围之外。
Sol 在遍历时也加入了“黑名单”概念：像<script>、<style>、<nav>、<footer>、<aside>这类标签，直接整棵子树跳过。处理流程中先净化再转换，能大幅提高最终 Markdown 的可用度。这里有个容易忽略的操作细节：净化阶段的判断顺序最好在元素类型判断之前。否则，等到生成完列表项之后再发现它位于<nav>里需要回退删除，逻辑复杂度会成倍增加。
3. 从零上手 Sol：安装、编译与基础用法
Sol 的定位很清楚——面向开发者、极客和命令行用户的工具。因此它的安装方式也延续了 Rust 社区的惯例，基本围绕 Cargo 展开。下面从头走一遍流程。
3.1 通过 Cargo 安装和编译
如果你的机器上已经装好了 Rust 工具链，最简单的方式就是直接从 crates.io 拉取安装：
cargo install sol-cli这条命令会帮你把 crate 源码拉下来，本地编译链接后，把可执行文件安装到 Cargo 的 bin 目录下。这个目录一般位于~/.cargo/bin，如果之后提示“找不到 sol 命令”，先检查一下这个目录有没有加入PATH。
如果不想用 crates.io 版本，也可以直接拉取仓库源码编译：
git clone https://example.com/sol.git cd sol cargo build --release编译产物会出现在target/release/目录下，名字通常就是sol。我个人建议优先用--release参数做发布构建，不然 debug 模式下的运行速度在解析大网页时会感觉明显偏慢。另外，Rust 工具的编译耗时一般可控，基本几十秒到几分钟之内能完成，取决于依赖数量。
3.2 命令行参数速查
Sol 的命令行设计很克制，没有铺一堆复杂参数，常用的就几个：
# 将一个 URL 转换为 Markdown 并输出到 stdout sol https://example.com/article # 指定输出文件 sol https://example.com/article -o output.md # 从本地 HTML 文件读取内容并转换 sol ./saved_page.html -o article.md # 指定正文选择器，手动告诉 Sol 正文位于哪个区域 sol https://example.com/article --selector "article.main-content" # 输出详细日志，方便调试转换结果 sol https://example.com/article -v-o参数会把结果写入文件，方便后续直接用编辑器查看；不指定时默认打印到终端，这样就可以配合管道做后续加工，比如sol https://example.com | wc -l快速统计一下转换结果的行数。
3.3 引入到 Rust 项目中使用
如果不想局限于命令行调用，也可能需要把 Sol 的转换能力集成进自己的 Rust 程序。作为库使用时，关键 API 很简单。以下是一段核心示意的 Rust 代码：
use sol_core::{html_to_markdown, ConversionOptions}; let options = ConversionOptions::default(); let md = html_to_markdown(html_str, &options)?; println!("{}", md);这里有个取舍设计：当作为库使用时，调用者传入的是 HTML 字符串而不是 URL，这意味着网络请求逻辑是独立的，工具更倾向于“接收 HTML 输入，输出 Markdown 字符串”。这样设计的好处是职责清晰——网络请求怎么发、超时怎么设置、重试几次，这些完全由调用方自己决定，转换库本身保持纯粹和可复用。
3.4 验证安装是否成功
安装完成后，可以用一个小页面做冒烟测试。比如直接用一个本地 HTML 文件：
<html> <head><title>测试页面</title></head> <body> <nav>导航链接A</nav> <article> <h1>Hello World</h1> <p>This is a <strong>test</strong> paragraph.</p> <pre><code>let x = 1;</code></pre> <a href="https://example.com">Example</a> </article> </body> </html>执行：
sol ./test.html理论上应该输出：
# Hello World This is a **test** paragraph.let x = 1;
[Example](https://example.com)如果输出和预期一致，Sol 的基础链路就通了。这里<nav>里面的导航链接没有被输出，说明净化逻辑起作用了。这一步很关键，可以快速验证整个工具链是否工作正常。
4. 核心转换细节深挖：不同要素的处理逻辑
Sol 真正强大的地方在于对各种 Markdown 元素的细致转换处理。接下来我对几个容易出问题的点展开拆解，这些也是平时使用转换工具时最容易踩坑的地方。
4.1 标题与段落：基础要素的稳健处理
标题转换相对直接，根据h1到h6的层级生成对应数量的#。这里有个处理细节：Markdown 规范要求标题行的井号后面通常会跟一个空格，写成# 标题而不是#标题，这会影响某些渲染器的兼容性。Sol 在这个细节上处理得很规范。
段落处理需要注意的是换行策略。HTML 中<p>标签内部的换行和空格会被压缩成单个空格（在渲染时），但 DOM 树里原本的空白文本节点如果处理不当，会让 Markdown 里出现多余的空白行。Sol 的做法是：在段落内将文本节点拼接时剔除多余的空白符，统一在段落前空一行。这个策略保证了最终输出的 Markdown 在视觉结构上整洁。
还有一个容易忽略的点：某些页面用<br>强行换行，这在 Markdown 里没有完全对应的原生语法。Sol 的常见处理策略是把<br>转换成两个空格加换行符，也就是 Markdown 列表内软换行或者硬换行的作法，这样至少在多数编辑器中仍能显示出换行效果。
4.2 链接、图片与引用文本的处理
链接转换是相对容易出错的部分。不只是获取href属性，还需要决定链接文字用什么。Sol 优先取标签内的文本，如果文本为空，就退而使用 URL 本身作为链接文字。同时，Sol 也会对 URL 做基础清洗，比如截断空白字符。
图片转换规则和链接类似，但额外要考虑alt属性。alt作为 Markdown 图片的说明性文字，直接关系着无障碍访问和后续检索的友好度。Sol 的处理顺序是：先看alt属性，再退到title属性，两者都没有，则留空。
引用文本的处理要复杂一些。blockquote标签内可能混杂着段落、列表、代码块甚至嵌套引用。Sol 的做法是整体递归处理内部节点，然后在生成的每一行前加上>前缀。这种递归思路保证了嵌套引用也能正确转换。实际操作中很容易出现的 bug 是：只给第一行加了>，后续行没有加，导致引用块在渲染时断裂。Sol 的处理策略是在遍历时逐行检查，确保多行引用的形式完整性。
4.3 代码块的识别与格式化
网页代码展示方式主要有两种：一种是经典结构<pre><code>，另一种是 GitHub 风格的代码高亮容器<div class="highlight"><pre>...。Sol 对这两种都有专门处理。
对<pre><code>结构，Sol 会将外层<pre>和内存<code>视为一个整体，保留内部换行和缩进，生成 fenced code block。如果页面上通过类似class="language-rust"标明了代码语言，Sol 能将其提取为代码块的注释语言，方便渲染器做高亮。
```rust fn main() { println!("hello"); }对 `<div class="highlight">` 这种结构，一眼能看到 `<pre>` 且 class 带有语言标识，Sol 也会做类似兜底处理。因为这类结构在前端框架生成的文档站点中太常见了，如果只认 `<pre><code>` 一种形式，很多网站的转换效果自然不理想。 ### 4.4 表格转换与复杂文档结构的适配 HTML 表格转成 Markdown 表格，是转换工作中较繁琐的一项。要正确处理：表头行（`thead`）、表格主体（`tbody`）、跨行跨列属性（`rowspan`、`colspan`）。Sol 的基础实现能把规整的表格转成相对标准的 Markdown 表格，对合并单元格的处理目前看还是比较直接，水平合并会以空列占位，垂直合并的能力支持有限。这种取舍对于那些需要保真还原复杂表格的文档来说，算是一个已知边界。使用的时候如果遇到非常复杂的合并单元格，一定要对转换结果做人工检查。 ### 4.5 额外细节：HTML 实体的解码 HTML 里经常会出现 `&`、`<`、` ` 这类实体引用。直接按文本字面输出到 Markdown，会发现链接里的 `&` 变成了 `&`，代码块里的小于号变成了 `<`。Sol 在遍历文本节点时，会利用 html5ever 的 tokenizer 机制专门解码实体，确保文本内容还原成人类可读的原始字符。 这个细节不复杂，但特别影响成品质量。很多用正则或手写解析器的转换工具，往往就是在这个环节翻车，导致生成的文章里满是实体编码。Sol 依托规范的 HTML5 解析器，从根源上规避了这类问题。 ## 5. 实战记录：结合真实网页场景测试 Sol 理论拆解不少了，接下来用一个贴近实际的场景做完整测试。我选了一个常见的个人博客文章页面，包含标题、段落、代码块、列表、引用、链接、图片这些基本元素，还故意让页面上带着导航栏、侧边栏和页脚三大噪音区块，看看 Sol 的真实输出水准。 ### 5.1 测试页面的选取与预期结果 测试页面结构示意如下：Rust 异步编程入门
异步编程是... 了解更多
为什么选择 async/await
- 任务并发
- 资源利用
异步并不等于并行。
async fn main() {}延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
