HTML转Markdown：何时转换以及会失去什么

如果您曾经在网络上处理过内容，您可能遇到过面对一堆HTML，希望它是Markdown的时刻。或者反过来。这两种格式在开发者世界中以一种不安稳的关系共存——HTML是网络的语言，Markdown是为网络写作的人的语言。

本指南讲述的是这种转换：什么时候有意义，您在交换什么，以及如何高效地完成它。

什么是Markdown以及开发者为什么热爱它

Markdown由John Gruber和Aaron Swartz在2004年创建，目标很简单：创建一种本身阅读自然，但也可以转换为干净HTML的纯文本格式。

它取得了巨大成功。今天Markdown驱动着GitHub READMEs、GitLab wikis、Notion页面、Obsidian vaults、文档站点以及无数博客平台。如果您曾在文本编辑器中输入 **粗体** 或 # 标题，您就写过Markdown。

它的吸引力是真实的。比较用原始HTML写作：

<h2>入门指南</h2>
<p>使用 <code>npm install my-package</code> 安装包，然后导入它：</p>
<ul>
  <li>导入默认导出</li>
  <li>调用 <code>init()</code> 函数</li>
</ul>

与Markdown相比：

## 入门指南

使用 `npm install my-package` 安装包，然后导入它：

- 导入默认导出
- 调用 `init()` 函数

相同的信息。Markdown版本写起来更快，原始形式更易读，出错更少（没有忘记的关闭标签）。对于文档和散文，通常是更好的选择。

什么情况下您实际想要将HTML转换为Markdown

转换通常出现在几种特定情况下。

从CMS迁移到静态站点生成器

这是最大的场景。您有一个WordPress站点，或Wix站点，或者将内容以HTML存储在数据库中的自定义CMS。您想迁移到Gatsby、Hugo、Jekyll或Astro——这些都原生支持Markdown文件。

内容仍然存在；只是格式不对。与其手动重写数百篇文章，不如导出HTML并批量转换为Markdown。

编写GitHub READMEs和文档

GitHub漂亮地渲染Markdown，但有时您的源材料以HTML形式存在。与其将HTML混乱复制粘贴到README中，不如先转换为干净的Markdown。

归档或重新利用网络内容

假设您爬取或下载了一个网页，想以可读、可编辑的格式归档其内容。带有所有class、ID、脚本和追踪像素的HTML是噩梦般的阅读体验。去除这些噪音的Markdown干净且可移植。

清理富文本粘贴

这经常发生：您从网页或Google文档复制文本并粘贴到编辑器中，最终得到隐藏的HTML或富文本格式，引发各种问题。将其转换为Markdown可以得到干净、可预测的内容。

转换中会失去什么

CSS样式消失了。 字体大小、颜色、自定义间距、边框、背景——这些都无法保留。

复杂表格支持是部分的。 Markdown通过GitHub Flavored Markdown扩展支持基本表格，但只是简单的。多行标题、合并单元格、colspan/rowspan在Markdown中不存在。

除href和src之外的HTML属性被删除。 data-*属性、class、id、style、aria-*——链接和图像的Markdown等效物不携带这些。

自定义组件和嵌入。 iFrames、视频嵌入、自定义HTML元素——Markdown没有等效物。

反向是无损的。 Markdown转HTML是完整转换。反向方向是有损的。在转换前保留备份。

转换实际上是如何工作的

在底层，HTML-to-Markdown转换器通过将HTML解析成DOM树，然后遍历每个元素，将其转换为Markdown等效物来工作：

• <h1> 到 <h6> 变成 # 到 ######
• <p> 变成周围有空白行的段落
• <strong> 和 <b> 变成 **粗体**
• <em> 和 <i> 变成 *斜体*
• <a href="..."> 变成 [文本](url)
• <img src="..."> 变成 ![alt](src)
• <ul> 和 <ol> 变成Markdown列表
• <code> 变成反引号包裹的代码
• &lt;pre><code> 块变成围栏代码块

使用我们的免费HTML转Markdown工具

我们的HTML转Markdown转换器无需任何安装或配置即可处理最常见的转换场景。

使用方法：

1. 将HTML粘贴到左侧的输入面板
2. Markdown输出立即出现在右侧
3. 检查转换中是否有任何看起来不对的地方
4. 复制Markdown并在需要的地方使用

如果您想在使用前预览Markdown的渲染效果，Markdown预览工具可以让您并排查看渲染的HTML输出。

手动转换vs自动化工具

手动转换给您完全控制。您可以做判断，结果正是您想要的。但它无法扩展。

自动化工具处理批量转换并且很快。输出是一致的。但您几乎总是需要清理步骤，特别是对于：

• 包含在转换中的导航元素
• 样板文本（Cookie通知、时事通讯CTA）
• 来自复杂CSS布局的奇怪格式伪影
• 已转换但需要简化的表格

值得了解的专用工具和库

Turndown.js（JavaScript）是Node.js生态系统中使用最广泛的HTML-to-Markdown库。它积极维护，可配置。

const TurndownService = require('turndown');
const turndownService = new TurndownService();
const markdown = turndownService.turndown('<h1>Hello World</h1>');

Pandoc是文档转换的瑞士军刀。它在数十种格式之间转换：HTML、Markdown、Word、PDF、LaTeX等等。

html2text（Python）是一个轻量级Python库，非常适合爬虫和内容提取管道。

Markdownify是另一个专注于干净HTML-to-Markdown输出的Python选项。

干净转换的最佳实践

转换前清理HTML。 如果可能，先删除导航、页脚、侧边栏和其他样板内容。

检查标题结构。 如果源HTML有不一致的标题级别，转换后的Markdown会有同样的问题。

仔细处理链接。 相对链接在您的新Markdown文件中可能不工作。绝对链接对迁移内容更安全。

检查图片路径。 Markdown中的图片引用需要指向可访问的URL或本地文件路径。

转换后测试渲染。 将转换后的Markdown粘贴到Markdown预览中并与原始内容比较。

实用迁移工作流

1. 从源CMS导出内容
2. 通过使用Turndown.js或pandoc的批量转换器运行HTML文件
3. 进行初步审查——寻找明显的转换伪影
4. 更新任何损坏的图片路径和链接
5. 检查标题结构并修复任何层次问题
6. 通过预览工具运行最终文件进行健全性检查
7. 导入到新站点并验证实时输出

不应该转换的情况

如果页面有复杂的交互组件（JavaScript驱动的标签页、手风琴、动态内容），转换HTML外壳为Markdown会删除使页面工作的东西。

如果精确的视觉格式至关重要（落地页、营销材料），Markdown缺乏样式控制使其不适合。

最终想法

HTML和Markdown服务于不同的目的。HTML是为浏览器的。Markdown是为那些写终会出现在浏览器中的内容的人的。

它们之间的转换是一个已解决的问题——工具存在，它们很好，而且是免费的。真正的技能是知道转换何时增加价值，以及知道如何清理输出使其真正可用。

对于快速的一次性转换，我们的HTML转Markdown工具是最快的路径。对于较大的迁移，将其与程序化方法配对。

无论哪种方式，一旦您的内容在Markdown中，您可能会想知道为什么您曾经将它保留在HTML中。