跳到主要内容

HTML 转 Markdown 完全指南:标签映射、表格代码块与脏 HTML 清理

讲清楚 HTML 转 Markdown 的真实用途,网页摘录、CMS 迁移、笔记归档各怎么用,标签如何映射,代码块表格链接怎样不丢,以及怎么把脏 HTML 洗干净。

发布于 作者 李雷
#HTML #Markdown #转换器 #内容迁移

HTML 转 Markdown 完全指南:从网页摘录到 CMS 迁移

HTML 描述的是「页面长什么样」,Markdown 描述的是「内容是什么结构」。把前者转成后者,不是格式翻译那么简单,而是一次有损取舍:你主动丢掉颜色、字号、对齐这些视觉信息,换来一份能进 Git、能丢进笔记软件、能喂给模型的纯文本。这篇文章把这件事的几个真实场景、标签映射规则、代码块表格链接的处理细节,以及脏 HTML 的清理思路逐一讲清楚。

三类最常见的用途

第一类是网页摘录。你从一篇文章里「查看源代码」或用爬虫抓下正文,结果正文外面裹着两百行导航 div 和埋点 span。把正文那段 HTML 贴进转换器,留下来的就是段落、引用和那张参数表格,一份三十行的笔记可以直接丢进 Obsidian 或 Notion。

第二类是 CMS 迁移。团队要把几十篇文章从 WordPress 搬到 Docusaurus 或 VitePress,逐篇复制渲染后的 HTML,拿到标题、链接、代码围栏都完好的 Markdown,WordPress 吐出的那一堆内联样式被剥掉,.md 直接进版本库,不用再手工清洗。

第三类是给模型喂料。裸 HTML 会把 token 浪费在标签上,先转一遍,同样内容能缩小四到六成,因为每个 <p class="..."> 都塌成一个空行。模型读标题和列表,也比读嵌套 div 稳。

标签是怎么映射的

转换的核心是遍历解析后的 DOM 树,给每种语义标签找一个 Markdown 对应写法:

  • <h1> 到 <h6> 映射成 # 到 ######。
  • <strong> / <b> 变 **粗体**,<em> / <i> 变 *斜体*。
  • <a href> 变 [文字](链接),<img> 变 ![alt](图片地址)。
  • <ul> / <ol> 变无序与有序列表,嵌套按每层两空格缩进。
  • <blockquote> 变 >,<hr> 变 ---,<br> 变行尾换行。

没有语义、只管样式的标签(比如 <span style="color:red">、<font>、纯排版用的 <div>)不会有对应写法,它们的文字被保留,外壳被丢弃。这正是 Markdown 的设计取向:CommonMark 规范明确只定义结构性元素,把样式留给渲染端的 CSS,所以「颜色丢失」不是 bug,是规范本身就不表达这个维度。

代码块、表格、链接这三个易错点

代码是最怕被破坏的内容。行内 <code> 变成反引号包裹,块级的 <pre><code> 变成三反引号围栏,围栏里的尖括号、引号、&amp; 这类实体会被还原成原字符,不能再当 HTML 转义,否则贴进编辑器就跑不通。

表格走管道语法,带一行表头分隔。单元格里的行内 HTML(链接、加粗)会翻译成对应 Markdown;但如果某个单元格里塞了块级内容,比如一个完整列表,管道表格表达不了,这时会降级成转义文本。需要手搓或校验表格结构时,可以配合 Markdown 表格生成器 来对齐列宽。

链接要注意相对路径。源页面里的 <a href="/docs/intro"> 转出来还是 /docs/intro,搬到新站点如果目录结构变了,这些相对链接会指向错误位置,迁移后要统一替换前缀。

一段真实的输入输出

下面这段从某产品文档复制来的 HTML:

<h2>安装</h2>
<p>用 <code>npm</code> 安装,见 <a href="/guide">指南</a>:</p>
<pre><code>npm i toolora</code></pre>
<ul><li>支持 <strong>Node 20</strong></li><li>零依赖</li></ul>

转换后得到的 Markdown:

## 安装

用 `npm` 安装,见 [指南](/guide):

​```
npm i toolora
​```

- 支持 **Node 20**
- 零依赖

注意 <code>npm</code> 进了反引号,代码块进了围栏,<strong> 变成了 **Node 20**,链接保持相对路径不变。整段从五个嵌套标签塌成了一份能直接进版本库的纯文本。

怎么把脏 HTML 洗干净

我自己迁移文档时踩过的最大的坑,是图省事把整页 HTML(连 <head>、<nav>、<footer> 一起)贴进去,结果菜单项和 cookie 提示都被当成标题转了出来。正确做法是只复制文章正文那一段。

第二个坑是 Word 和 Google Docs 的粘贴内容。它们吐出的 HTML 带几百条内联样式和 MSO 专属标签,列表序号藏在 mso-list 样式里,Markdown 没有对应写法,直接转会丢结构。这类内容建议先从 Word 另存为 .html,清理后再贴。

第三个坑是指望内联 style="color:red" 或 text-align 能留下来。它们一定会被丢掉,因为 Markdown 不表达样式。如果视觉样式比可移植更重要,那就别转,继续留在 HTML 里。

想做来回转换的话,反方向可以用 Markdown 转 HTML,在支持的子集内输出是稳定可逆的;子集之外的裸 HTML、脚注、数学公式不会幸存。需要把这套转换跑在自己的内容上,直接打开 HTML 转 Markdown 贴一段试试,全程在浏览器本地完成,粘贴的内容不上传也不写进 URL,内部文档也能放心贴。

Made by Toolora · Updated 2026-06-13