WordPress 网站运营了十年的任何人都最终会这样, 我以迁移内容为生, 当我将一批旧帖子从页面构建器中移出并移入基于 Markdown 的文档系统时, 我发现了 "clean HTML" 在野外真正意味着什么: <p> 带有内联样式的标签,空的 <span>S包裹单字, <div>s 三个层次深深地围绕着一段,以及偶尔根本就没有关闭的标签,将其粘贴到 Markdown 字段中,让我看到了一面字面角度括号的墙。复制粘贴 渲染 text 丢失了每一个链接、标题和列表,两个快捷方式都不行,最后我手洗了一下午的文章才懂事。
变得明智意味着将 HTML 到 Markdown 视为它:具有一组清晰规则的结构化转换,而不是复制粘贴。标题元素变成了 # 线。大胆变 **.一个链接变成 [text](url).一张表变成一张管道表,一旦你有了那些映射和一个足够宽容的解析器,能够生存到现实世界的标记中,那么转换就是无聊和可靠的- 这正是你想要的我构建的 Toolz.dev 并放置基于浏览器的 HTML 到 Markdown 转换器 在那里应用了这些规则,但本指南是关于规则本身的,因此您可以了解输出应该是什么样子以及原因。
TL;博士: HTML 转换为 Markdown,请将块元素映射到其 Markdown 等效项 (
<h2>→##、<ul><li>→-、<blockquote>→>、<pre><code>→ 围栏块),映射内联元素(<strong>→**、<em>→*、<a>→[text](href)、<img>→),转动<table>github 调味的 Markdown 管道表中,将 HTML 实体解码回真实字符,然后掉落<script>/<style>。使用容忍未关闭标签的解析器,并在浏览器中执行此操作,以便您的内容永远不会上传。
为什么要将 HTML 转换为 Markdown?
Markdown是现代开发者网络的便携式格式。README文件,文档网站,静态博客(雨果,杰基尔,Astro,Next。js内容),注意应用程序,如黑曜石和熊,GitHub问题,以及越来越多我们馈送到AI模型的提示和上下文 - 所有这些都说Markdown。it's纯文本,它在Git中干净利落地不同,它从一个系统移动到另一个系统,而不会拖动一堆演示标记随之而来。
HTML,相比之下,就是你 结束与 每当内容通过浏览器或所见即所得编辑器时。从网页复制一个部分,从 CMS 导出,从 API 中拉出文章正文,或从富文本字段中抓取格式化的文本,您就会获得 HTML - 通常杂乱无章的 HTML,充满了包装元素和内联样式您不't想要在干净的文档中。转换是从"被困在演示标记中的内容"到"内容的桥梁我可以在任何地方版本、编辑和重新发布。"
一旦您注意到场景,场景就会不断重复。将博客从 WordPress 或 Medium 上迁移。从旧的 HTML 帮助系统中提取文档。将刮下的文章转换为 Markdown 注释。将电子邮件通讯 's HTML 转换为 Markdown 草案。将网页 's 内容作为干净的上下文提供给 LLM,而不是浪费令牌的原始 HTML <div> soup。inevery case 手动替代品 - 重新打字,或复制粘贴渲染的文本和重建格式的手 - 是缓慢而有损的。基于规则的转换器既不是。
HTML 如何映射到 Markdown?
映射自然地分为两层:块级结构和内联格式化。
块元素 定义文档's骨架,并且每个都有直接的markdown对应项:
<h1>,<h6>变成#通过######标题行。<p>成空行分隔的段落。<ul>/<li>变成-项目符号列表;<ol>/<li>变成1.编号列表和嵌套列表缩进两个空格。<blockquote>每行前缀为>。<hr>变成---。<pre><code>成为一个带有三重回击的围栏代码块。<table>成为 GitHub 风味 Markdown 管桌。
内联元素 装饰这些块内的文本:
<strong>並<b>变成**bold**。<em>並<i>变成*italic*。<code>变成`inline code`。<a href="...">变成[link text](href),保持title存在时的属性。<img>变成。<del>並<s>变成~~strikethrough~~(GitHub 调味 Markdown 扩展)。<br>成为硬线断路器 - 换行线之前的两个尾随空间。
HTML 的一个真实块上运行那些规则, 结构完好无损地保存下来, 给定这个输入:
<article>
<h1>Getting Started</h1>
<p>Convert <strong>HTML</strong> into clean <em>Markdown</em>.</p>
<ul>
<li>Paste from a CMS</li>
<li>Get portable output</li>
</ul>
<pre><code class="language-js">const md = convert(html)</code></pre>
</article>
你得到:
# Getting Started
Convert **HTML** into clean *Markdown*.
- Paste from a CMS
- Get portable output
```js
const md = convert(html)
```
该输出中的两个细节值得一提,首先, <article> 包装工什么也没贡献--结构容器之类的 <article>、 <section>、和 <div> 是透明的;转换器递归到它们中,并把它们的孩子呈现为块。其次,代码栏捡起 js 作为它的语言。那个's因为 <code> 携带元素 class="language-js"、惯例语法 highlighters 使用,一个好的转换器读取那个类来标记栅栏。它's 一个小东西,它使在您的 docs 网站上突出显示的代码块与不显示的代码块之间的区别't。
是什么让转换器在现实世界的 HTML 中幸存下来?
上面的规则是容易的部分,手卷正则转换器失败的原因- 还有I've写了一对,扔掉了一对- 就是真正的HTML不断打破假设,三个问题一再出现。
未关闭的标签。 浏览器是著名的宽容: <p>one<p>two 渲染为两个段落,因为 a <p> 当另一个块元素打开时隐式关闭,并且 <li>a<li>b 是出于同样的原因的两个列表项。只关闭显式上的元素的朴素解析器 </p> will将第二段嵌套在第一个内部,并破坏下游的所有内容一个强大的转换器应用相同的隐含-结束-标签规则HTML spec定义:打开一个块级元素关闭一个打开的段落;打开一个 <li> closes 上一个,我的转换器就是这样做的,这就是为什么粘贴草率的 CMS 输出通常只是起作用的原因。
<script> 並 <style> 块。 这些包含代码和 CSS,而不是内容,并且其内容必须逐字记录(a) < javascript内部不是一个标签),然后完全掉落。忘记特殊情况它们,你就会让javascript源流血进入你的markdown。
HTML 实体。 Web内容中散落着 &、 ©、 —、 以及数字参考 ’。在Markdown- 这是纯文本- 你想要实际的字符: &、 ©、 —,以及一个真正的撇号。解码命名和数字实体不是可选的;跳过它,你的干净的 Markdown 读取就像 view-source 一样。
这就是为什么我不再尝试用查找和替换来转换 HTML,而是构建了一个适当的宽容解析器。它将 HTML 标记为一棵树 - 处理注释,像这样的空元素 <br> 並 <img>、大写标签名称和未引用的属性 - 然后走那棵树发出 Markdown。值得注意的是,它不't依赖于浏览器's DOM,这意味着相同的逻辑也在服务器上运行,但对你的实际回报很简单:它不't抛出真正网站是由混乱的标记组成的。
如何使用转换器?
论 Toolz.dev/tools/html 到 markdown、将您的 HTML 粘贴到左侧窗格中,当您键入时,右侧会出现 Markdown - there's 无上传,无转换按钮可搜索如果您想同时查看每个支持的构造,请加载示例。
几个选项涵盖了常见的偏好。选择你的子弹角色(-、 *、或者 +)用于无序列表以匹配您的项目's风格保持GitHub风味标记为表格和删除线,或者关闭,如果您的目标仅接受CommonMark。当您想要散文而不是URL时切换"保持链接"关闭 - 方便将链接重量的文章转换为干净的阅读文本 - 和"保持图像"关闭以完全剥离图像。stats行显示单词,标题,链接,图像,代码块和估计的阅读时间,这是一种快速的理智检查,在您将结果粘贴到某个地方之前,结构会遇到。
Site上的所有内容一样,转换是100%客户端的,解析器是普通的JavaScript在你的浏览器中运行,所以粘贴的页面,内部文档和未发布的草稿永远不会发送到任何地方。that's内容工作的正确默认值-你应该't必须将草稿上传到陌生人's服务器只是为了重新格式化它-这意味着该工具一直离线工作。我更深入地探讨为什么浏览器端处理在 数据隐私工具指南。
HTML 与 Markdown:何时使用哪个
它们之间的转换很容易;知道你想要什么才是真正的决定。
| 方面 | HTML | 降价 |
|---|---|---|
| 主要目的 | 在浏览器中渲染 | 编写和存储文本 |
| 可读性作为来源 | 差(标签重) | 优(读为纯文本) |
| Git 差异 | 吵闹 | 潔 |
| 跨系统的便携性 | 低 | 高 |
| 精确的布局控制 | 满满的 | 受设计限制 |
| 它住在哪里 | 网页、所见即所得输出 | README、文档、注释、静态站点 |
| 学习曲线 | 陡峭 | 分钟 |
Markdown故意交易布局控制以求简单,这就是为什么它会为你编写的内容、版本和移动而获胜,并在你需要像素级演示时失败。将HTML转换为Markdown当你're捕获或迁移 内容;当你're构建一个时保持html 页码。 当您需要采取相反的方式时 - 将 Markdown 输入 CMS 字段或电子邮件模板的 HTML - 标记到 HTML 转换器 是这个工具的镜像,并且共享相同的约定,因此对于共同的结构,两个往返是干净的。
这适合内容工作流程
格式转换很少是整个作业;it's一步。我将一篇文章转换为Markdown后I'll通常通过a运行文本 词计数器 要检查目标长度,以及源是否具有需要为其他目的地进行编码的 HTML 实体, HTML实体编码器/解码器 challeres反面处理当i'm在转换前清理手写的html时,一个 HTML 迷你程序 先剥去噪音。这些小工具将它们连在一起形成一个可重复的管道,这就是我对基于浏览器的工具包的思考背后的全部想法 - 我在 中阐述了这种理念 web开发人员工具包指南 而且范围更广 编码工具指南。
将 HTML 转换为 Markdown 的常见错误
复制粘贴渲染的文本而不是转换 HTML。 您丢失链接、标题和列表 - 所有结构。转换实际标记。
忽略代码语言类。 如果您的围栏块在没有语言的情况下出现并且没有't突出显示,转换器会丢弃 class="language-x" 提示。一个好人读了它。
假设 CommonMark 和 GFM 相同。 Tables 和 strikethrough 是 GitHub 风味 Markdown 扩展,而不是核心 CommonMark。如果您的目的地是严格的 CommonMark,则表格获胜't 渲染 - 关闭 GFM 进行转换并以另一种方式处理表格。
信任上传内容的转换器。 大量"免费"在线转换器将您的 HTML 发布到服务器。对于任何未发布或内部的内容,that's 泄漏。使用客户端工具。
常问问题
如何将 HTML 转换为 Markdown？
HTML粘贴到编辑器中,Markdown立即出现-没有文件上传,也没有转换按钮按下。如果您喜欢,调整项目符号样式或链接处理,然后复制Markdown或下载为。md文件。
转换器是否处理表格？
是的。启用 GitHub Flavored Markdown 后,就会出现 HTML <table> 成markdown管桌:第一行成为头,插入分隔行,其余行成为主体,单元格内的管字符逃逸,这样就不会打破桌子。
链接和图像会发生什么？
锚成为 [link text](href) 形象就变成了 ,在场时保留标题属性,如果关闭"保留链接"锚文本保留但URL掉落,关闭"保留图像"完全删除图像-当你只想要散文时有用。
是否保留了代码块和内联代码？
是的。 A <pre><code> block变成一个有围栏的代码块,如果代码元素携带一个类,如语言-js,那么该语言被添加到围栏中。内联 <code> span 包裹在回溯中,代码文本本身永远不会转义或重新格式化,因此片段完全按照编写方式保留。
它可以在从网站复制的凌乱的html上工作吗？
That is what it is build for。parser is tolerant of unclosed tags, uppercase element names, unquoted attributes and stray com 和<style>块。复制好的CMS或所见即所得输出通常可以干净地转换,尽管非常不寻常的嵌套结构可能需要一个小的手动整洁。</p><h3>这是否会将Markdown反转为HTML工具?</h3><p>对于常见的构造,是的。这个转换器是Markdown反转为HTML工具,因此通过该工具运行Markdown,通过这个工具返回的结果通常会再现原始文档。Whitespace和一些仅限HTML的功能是通常的小差异来源。</p><h3>我的内容是否在任何地方上传?</h3><p>No。转换完全在您的浏览器中使用普通的JavaScript运行 - 您粘贴的任何内容都不会发送到服务器,记录或存储。这使得它对于内部页面,未发布的草稿和任何您宁愿不上传的内容都是安全的,并且它可以在没有网络连接的情况下继续工作。</p><h3>HTML到Markdown转换器是免费的吗?</h3><p>是。没有注册,没有使用限制,没有水印,没有上传。转换发生在您的浏览器本地,并且页面一旦加载后继续离线工作。</p><hr><pre><code class="language-json">{"@context":"https://schema。org","@type":"常见问题页面","mainEntity":[{"@type":"问题","名称":"我如何将HTML转换为Markdown?","接受答案":{"@type":"答案","文本":"将您的HTML粘贴到编辑器中,Markdown立即出现—没有文件要上传,也没有转换按钮要按。 调整子弹样式或链接处理(如果您喜欢),然后复制 Markdown 或将其下载为。md 文件。" } }, {"@type": "问题", "名称": "转换器处理表格吗?", "已接受答案": {"@type": "答案", "文本": "是的。启用 GitHub 调味标记后,一个 HTML <table> 变成 Markdown 管道表:第一行成为标头,插入分隔行,其余行成为主体。单元格内的管道字符会转义,这样它们就不会破坏表格。" } }, {"@type": "问题", "名称": "链接和图像会发生什么?", "已接受答案": {"@type": "答案", "文本": "锚点变成 [链接文本](href),图像变成,在出现时保留标题属性。 关 \"保留链接 \" 锚文本保留但网址掉落,并关闭 \"保留图像 \" 完全删除图像—在只想要散文时有用。" } }, {"@type": "问题", "名称": "代码块和内联代码是否保留了?", "已接受答案": {"@type": "答案", "文本": "是的。A <pre><code>块变成了围栏代码块,如果代码元素带有像 \"language-js\" 这样的类被添加到围栏中。内联<code>跨度用回抽打包裹,代码文本本身从未转义或重新格式化,因此片段完全按照编写的方式保留。" } }, {"@type": "问题", "名称": "它是否适用于从网站复制的混乱的HTML?", "已接受答案": {"@type": "答案", "文本": "就是它构建的目的。解析器对未封闭标签、大写元素名称、未引用属性和杂散注释是宽容的,它会剥离<脚本>和<样式>块。复制的CMS或所见即所得输出通常转换干净,尽管非常不寻常的嵌套结构可能需要一个小手动整洁。" } }, {"@type": "问题", "名称": "这是否会将Markdown反转为HTML工具?", "已接受答案": {"@type": "答案", "文本": "对于常见的构造,是的。 Markdown到HTML工具的逆转换器,所以通过该工具运行Markdown,通过这个工具返回的结果一般都会复制原始文档。Whitespace和一些仅限HTML的功能是通常的小差异来源。" } }, {"@type": "Question", "name": "我的内容是否在任何地方上传?", "已接受答案": {"@type": "Answer", "text": "No。转换完全在浏览器中使用普通的JavaScript运行—您粘贴的任何内容都不会发送到服务器,记录或存储。这使得它对于内部页面,未发布的草稿和任何您宁愿不上传的内容都是安全的,并且它一直在工作,没有网络连接。" } }, {"@type": "Question", "name": "HTML到Markdown转换器是免费的吗?", "已接受答案": {"@type": "Answer", "text": "是。没有注册,没有使用限制,没有水印,也没有上传。转换发生在浏览器本地,页面一旦加载后继续离线工作。" } } 〕 } </code></pre><
