什么是 HTML 转 Markdown 转换？

HTML 转 Markdown 转换是将 HTML 标记转化为 Markdown 的过程。Markdown 是一种轻量级纯文本格式语法，由 John Gruber 于 2004 年创建。Markdown 的设计目标是不经渲染也能直接阅读。HTML 需要开闭标签（如 <strong> 和 <a href="">），而 Markdown 使用简写字符：**粗体**、[链接](url) 和 # 标题。将 HTML 转换为 Markdown 所生成的文件，比原始 HTML 更易阅读、编辑和进行版本控制。

转换过程将 HTML 元素映射为对应的 Markdown 语法。<h2> 变为 ##，<ul><li> 变为 - 列表项，<a> 标签变为 [文本](url)。部分 HTML 元素在 Markdown 中没有对应语法，例如 <div>、<span> 或自定义数据属性。转换器通常会根据配置去除这些标签，或将其作为原始 HTML 直接传递。

Markdown 已成为开发者文档（GitHub、GitLab、Bitbucket）、静态网站生成器（Hugo、Jekyll、Astro）、笔记应用（Obsidian、Notion）和技术博客的标准写作格式。将现有 HTML 内容转换为 Markdown，是网站迁移、导入 CMS 内容或以可移植格式归档网页时的常见步骤。与 HTML 不同，Markdown 文件在版本控制中能产生清晰的差异对比，使文档变更的代码审查切实可行。

为什么使用 HTML 转 Markdown 转换器？

手动将 HTML 改写为 Markdown 既耗时又容易出错，尤其是含有嵌套列表、表格或大量链接的页面。自动化转换器能即时且一致地完成结构映射。

⚡

在浏览器中即时转换

粘贴 HTML，毫秒级获得 Markdown 输出。无需服务器往返，无需等待处理队列。转换完全在浏览器中使用 JavaScript 运行。

🔒

保护数据隐私

您的 HTML 不会离开本机。所有处理均在客户端完成，无需上传，无日志记录，第三方无法访问您的内容。

📝

保留文档结构

标题、列表、链接、图片、代码块和表格均映射为对应的 Markdown 语法。嵌套结构和行内格式以递归方式处理。

🔀

无需账号或安装

打开工具即可开始转换。无需安装任何软件，无需配置 API 密钥，无需注册账号。在任何支持现代浏览器的设备上均可使用。

HTML 转 Markdown 使用场景

前端开发者：CMS 迁移

将 WordPress、Drupal 或无头 CMS 中的博客文章或页面导出为 HTML，再转换为 Markdown，用于 Next.js、Astro 或 Hugo 等静态网站生成器。

后端工程师：API 文档

将自动生成的 HTML API 文档转换为与源代码共存的 Markdown 文件。Markdown 文档可与 GitHub 渲染集成，并可与所描述的代码一起进行版本控制。

运维工程师：运行手册转换

将以 HTML 导出的内部 Wiki 页面（Confluence、SharePoint）转换为 Markdown 运行手册，存储在 Git 仓库中，与其所描述的基础设施代码并存。

QA 工程师：测试用例文档

将 Web 工具导出的 HTML 测试报告或手动测试计划转换为 Markdown 文件，以便在 Pull Request 中与所验证的代码变更一起审查。

数据工程师：网页抓取清理

去除抓取网页中的 HTML 模板代码，生成干净的 Markdown 文本。该过程在保留文章内容和结构的同时，去除导航、广告和布局标记。

学生：整理研究笔记

复制网页资源中的内容，将 HTML 转换为 Markdown，导入 Obsidian、Notion 或任何基于 Markdown 的笔记系统。标题、链接和格式均可保留。

HTML 转 Markdown 元素对照参考

下表展示了常见 HTML 元素与对应 Markdown 语法的映射关系。该映射遵循 GitHub-Flavored Markdown（GFM）规范，GFM 在 CommonMark 规范基础上扩展了表格、删除线和任务列表。未在此列出的元素（如 <div>、<form> 或自定义 Web 组件）在 Markdown 中没有对应语法，将被去除或作为原始 HTML 直接传递。

HTML 元素	Markdown 语法	说明
<h1>...<h6>	# ... ######	ATX headings, level matches tag number
<p>	Blank line separation	Double newline between paragraphs
<strong>, <b>	text	Bold / strong emphasis
<em>, <i>	text	Italic / emphasis
<a href="url">	[text](url)	Inline link with optional title
<img src="url">	![alt](url)	Image with alt text
<ul><li>	- item	Unordered list with dash or asterisk
<ol><li>	1. item	Ordered list, numbers restart per block
<blockquote>	> text	Block quote, nestable with >>
<code>	`code`	Inline code span
<pre><code>	```lang\ncode\n```	Fenced code block with optional language
<hr>	---	Horizontal rule (three dashes)
<table>	\| col \| col \|	GFM table syntax with alignment
<del>, <s>	~~text~~	Strikethrough (GFM extension)

Markdown 方言：GFM vs CommonMark vs 原始规范

并非所有 Markdown 都相同。输出格式很重要，因为不同平台对 Markdown 的解析方式存在差异。最常见的三种方言是 GitHub-Flavored Markdown（GFM）、CommonMark 和 Gruber 的原始 Markdown。

GitHub-Flavored Markdown（GFM）

使用最广泛的方言。在基础语法上新增了表格（管道语法）、删除线（~~文本~~）、任务列表（- [x]）和自动链接 URL。被 GitHub、GitLab 及大多数开发者工具所采用。本转换器默认输出兼容 GFM 的 Markdown。

CommonMark

一种严格的规范，解决了原始 Markdown 语法中的歧义问题。为列表延续、强调解析和块级嵌套定义了精确规则。被 GFM 和众多静态网站生成器用作基础规范。

原始 Markdown

John Gruber 于 2004 年制定的规范。不支持表格、围栏代码块或删除线。大多数现代工具将其视为 CommonMark 的子集。如今已极少作为目标格式使用。

代码示例

以下为 JavaScript（Turndown）、Python（markdownify 和 html2text）、Go 以及命令行 Pandoc 的实用示例。

JavaScript (Turndown)

import TurndownService from 'turndown'

const turndown = new TurndownService({ headingStyle: 'atx' })
const html = '<h1>Title</h1><p>A <strong>bold</strong> paragraph.</p>'
const md = turndown.turndown(html)
console.log(md)
// → "# Title\n\nA **bold** paragraph."

Python (markdownify)

from markdownify import markdownify

html = '<h2>Section</h2><ul><li>First</li><li>Second</li></ul>'
md = markdownify(html, heading_style='ATX')
print(md)
# → "## Section\n\n- First\n- Second"

Python (html2text)

import html2text

converter = html2text.HTML2Text()
converter.body_width = 0  # disable line wrapping

html = '<p>Visit <a href="https://example.com">Example</a> for details.</p>'
md = converter.handle(html)
print(md)
# → "Visit [Example](https://example.com) for details."

Go (html-to-markdown)

package main

import (
	"fmt"
	md "github.com/JohannesKaufmann/html-to-markdown"
)

func main() {
	converter := md.NewConverter("", true, nil)
	html := `<h3>Go Example</h3><p>Code: <code>fmt.Println()</code></p>`
	markdown, _ := converter.ConvertString(html)
	fmt.Println(markdown)
	// → "### Go Example\n\nCode: `fmt.Println()`"
}

CLI (Pandoc)

# Convert an HTML file to Markdown
pandoc input.html -f html -t markdown -o output.md

# Pipe HTML from stdin
echo '<p>Hello <em>world</em></p>' | pandoc -f html -t markdown
# → Hello *world*

# Use GitHub-Flavored Markdown output
pandoc input.html -f html -t gfm -o output.md

常见问题

哪些 HTML 元素无法转换为 Markdown？

Markdown 没有 <div>、<span>、<form>、<input>、<iframe> 或任何带有自定义 CSS 类和样式的元素的对应语法。大多数转换器会去除这些标签，仅保留内部文本。部分转换器可以将不支持的 HTML 原样传递，这是合法的，因为 Markdown 规范明确允许内联 HTML。如需保留这些元素，请将转换器配置为保留原始 HTML，而非去除标签。

HTML 表格如何转换为 Markdown？

HTML 表格映射为 GFM 管道表格语法：| 标题 | 标题 |，并带有分隔行 | --- | --- |。GFM 表格不支持 colspan、rowspan 或单元格级别的样式。含合并单元格的复杂表格会被扁平化处理，可能导致结构信息丢失。对于简单的数据表格，转换是无损的。

HTML 转 Markdown 是无损转换吗？

不是。Markdown 是 HTML 的子集，因此转换过程中必然会丢失部分信息。CSS 类、行内样式、数据属性、表单元素以及 <article> 或 <section> 等语义标签在 Markdown 中没有对应语法。文本内容和基本结构（标题、列表、链接、强调）可被准确保留。对于大多数文档和内容迁移工作流而言，保留的元素正是关键所在。

HTML 转 Markdown 与 HTML 转纯文本有什么区别？

HTML 转纯文本会去除所有格式，生成无结构的原始文本。HTML 转 Markdown 则保留文档结构：标题保持为标题，链接保留 URL，列表保持列表形式，强调格式得以保留。Markdown 输出可以渲染回具有相同逻辑结构的 HTML。

Markdown 可以转换回 HTML 吗？

可以。所有 Markdown 处理器（marked、markdown-it、Python-Markdown、goldmark）均可将 Markdown 转换为 HTML。这种双向转换正是 Markdown 广受欢迎的原因之一：您以可读格式编写，再渲染为 HTML 发布到网络。由于 HTML 转 Markdown 会丢弃不支持的元素，两者之间的往返转换并非完全对称。

转换器如何处理含行内 CSS 或 JavaScript 的 HTML？

行内 CSS（style 属性）和 <style> 块在转换时会被去除，因为 Markdown 没有样式语法。JavaScript（<script> 标签和 onclick 等事件处理器）也会被移除。转换器仅提取文档内容和结构。这使得 HTML 转 Markdown 成为将不可信 HTML 内容导入文档时的一个有效清理步骤。

我的项目应该使用哪种 Markdown 方言？

如果内容将在 GitHub、GitLab 或大多数文档平台上查看，请使用 GitHub-Flavored Markdown（GFM）。如果需要严格的规范兼容性和在不同渲染器之间的可预期解析行为，请使用 CommonMark。原始 Markdown 仅适用于遗留系统。GFM 是大多数项目最安全的默认选择。

HTML to Markdown