让我给你讲个故事。几年前，我正卡在一个项目里，得处理成千上万的网页——满眼都是乱糟糟的 HTML、内联样式，还有数不清的 <div>。我的目标是什么？把这些内容整理成干净、好读的格式，放进团队的内部 Wiki 里，而这个 Wiki 和很多现代工具一样，用的都是 Markdown。我得说，一开始我也想走老路：复制、粘贴，然后默默祈祷一切别出岔子。但在喝到第三杯咖啡、修到第五个坏掉的表格之后，我就知道，这事儿肯定还有更好的解法。
后来我发现，遇到这个问题的人不止我一个。无论你是在搭文档、准备给 AI 模型训练的数据，还是单纯想让笔记别再像一锅意大利面，而是像一份清清楚楚的购物清单，把 HTML 转成 Markdown，都是商业用户很值得掌握的一项“超能力”。那 Python 呢？它就像这件事上的瑞士军刀：上手不难、灵活度高，而且有一堆库能把整个过程变得（几乎）有趣。这篇指南里，我会带你看看为什么要做、怎么做，以及在 Python 里做 html to markdown 时那些最容易踩坑的奇怪边角情况，同时也会分享一些实战经验。
什么是 HTML 转 Markdown？
先拆开来说：HTML（超文本标记语言）是网页的底层骨架。它很适合浏览器，但如果你想直接阅读或编辑内容，它就没那么友好了——除非你很享受盯着一屏幕尖括号猜意思。Markdown 就不一样了，它是一种轻量级的纯文本格式语法，读写都很顺手。你不用写 <h1>Title</h1>，直接写 # Title 就行；不用写 <strong>bold</strong>，写 **bold** 就够了。它清楚到连非技术同事也能很快上手编辑。
HTML 转 Markdown，说白了就是把 HTML 标签转换成对应的 Markdown 语法。比如：
<h1>This is a Heading</h1>
<p>This is a paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
<a href="https://example.com">This is a link</a>
会变成：
# This is a Heading
This is a paragraph with **bold** and *italic* text.
[This is a link](https://example.com)
这个过程其实和 Markdown 最初的设计方向是反过来的（Markdown 转 HTML），但它已经成了现代工作流里的刚需，尤其是在 Markdown 越来越受商业团队和技术团队欢迎的今天（Google Developer Docs）。
顺带一提：如果你反过来要把 Markdown 转成 HTML，Python 当然也没问题。不过这部分我们后面再讲。
为什么要把 HTML 转成 Markdown？对业务有什么价值？
那为什么还要费劲把 HTML 转 Markdown 呢？一句话：Markdown 更简洁、更易读，也更好维护。但具体来说，下面这些场景里，这种转换会直接帮你提效：
| 使用场景 | 为什么要转成 Markdown？ |
|---|---|
| 技术文档 | Markdown 文件是纯文本，非常适合版本控制、协作和快速编辑。再也不用为一堆零散的 <div> 标签引发合并冲突了 (Document360). |
| 笔记与知识库 | Markdown 就算是原始文本也很好读，能在 Notion、Obsidian 等应用之间自由迁移，不会被某种封闭格式锁死 (Markdown Guide). |
| 内容迁移 | 如果你要把旧版 HTML（老博客、内网页面）迁到现代系统里，Markdown 能让迁移更顺，也方便后续更新 (cantoni.org). |
| AI 训练数据准备 | LLM 和 NLP 模型更喜欢干净、结构化的文本。Markdown 能去掉 HTML 的冗余噪音，留下更适合“喂给模型”的内容 (Apify). |
| 内容编辑与协作 | Markdown 语法对非开发者也很直观——再也不会出现“等等，这个 <span> 到底在哪儿结束？”这种让人头大的瞬间。它更耐用，也能在任何文本编辑器里轻松修改 (Markdown Guide). |
顺带说个有意思的点：Markdown 之所以能流行起来，很大原因就是它足够简单，所以它慢慢成了从 README 文件到内部 Wiki 的默认选择之一 (Google Developer Docs)。可以说，它就是那种“写一次，到处用”的格式。
Python 中用于 HTML 转 Markdown 的工具概览
Python 一直是我做这类文本转换任务时的首选语言，而它在 html to markdown 这件事上也已经很成熟了。主力工具大致有这些：
| 工具 / 库 | 类型 | 优点 | 局限 / 备注 |
|---|---|---|---|
| markdownify | Python 库 | 易用、可定制、能保留结构（标题、表格、图片、链接）、可扩展 | 可能会漏掉一些复杂 HTML，通常需要 BeautifulSoup 配合使用 |
| html2text | Python 库 | 简单、对格式不规范的 HTML 容错强、输出简洁、可设置很多忽略选项 | 表格可能会被压成普通文本，对高级格式控制较弱 |
| Pandoc | 独立工具（可配合 Python 包装器使用） | 能处理复杂 HTML，支持多种 Markdown 风格，适合批量处理 | 需要单独安装，小任务里可能有点“杀鸡用牛刀” |
| Aspose.HTML for Python via .NET | 商业 Python/.NET 库 | 企业级能力，支持多种 Markdown 风格，提供高级选项 | 需要付费授权，配置也更重一些 |
下面我们再展开讲讲。
对比 Python 库：哪个更适合你的需求？
markdownify
- 适合场景： 大多数业务用户、文档转换，以及希望 Markdown 尽量保留原始 HTML 结构的情况。
- 优点： API 很简单、可定制性强（比如标题样式、去掉某些标签等）、支持图片、链接和表格处理 (GitHub).
- 缺点： 如果 HTML 层级特别深，或者结构很奇怪，可能会漏掉部分内容 (Reddit).
html2text
- 适合场景： 需要快速转换、想从乱七八糟的网页里提取可读文本，并且更看重简洁而不是结构完整的情况。
- 优点： 对格式不规范的 HTML 兼容性不错，能轻松忽略链接和图片，输出风格也很干净 (GitHub).
- 缺点： 表格不一定能转成标准 Markdown 表格，对输出样式的控制也比较少。
Pandoc
- 适合场景： 大规模转换、批处理、复杂文档，或者你需要特定 Markdown 风格的时候。
- 优点： 基本上什么都能转，支持扩展，表格、脚注、数学公式都能处理 (cantoni.org).
- 缺点： 需要单独安装，通常通过命令行或 Python 封装来调用。
Aspose.HTML for Python via .NET
- 适合场景： 企业环境，需要高级功能，或者要和其他 Aspose 产品一起集成。
- 优点： 支持多种 Markdown 风格，还可以通过保存选项进行定制 (Aspose Docs).
- 缺点： 需要商业授权，配置流程也更复杂。
我的建议： 对大多数日常需求，先从 markdownify 或 html2text 开始。如果你遇到复杂表格、脚注，或者需要 GitHub Flavored Markdown，那就让 Pandoc 上场。
分步指南：在 Python 中把 HTML 转成 Markdown
接下来进入实操部分。哪怕你不是开发者，也能照着做。下面我会给你两个示例：一个用 markdownify，一个用 html2text。
示例：使用 markdownify 把 HTML 转成 Markdown
先安装库：
pip install markdownify
假设你有下面这段 HTML：
<h2>Example Title</h2>
<p>This is a <strong>bold</strong> word and an <em>italic</em> word.</p>
<p>Visit <a href="http://example.com">our site</a> for more info.</p>
对应的 Python 代码如下：
from markdownify import markdownify as md
html_content = """
<h2>Example Title</h2>
<p>This is a <strong>bold</strong> word and an <em>italic</em> word.</p>
<p>Visit <a href="http://example.com">our site</a> for more info.</p>
"""
markdown_text = md(html_content, heading_style="ATX")
print(markdown_text)
生成的 Markdown：
## Example Title
This is a **bold** word and an *italic* word.
Visit [our site](http://example.com) for more info.
- 标题会变成
##，粗体和斜体会被转换，链接会变成[文本](URL)的格式。 - 图片（
<img>）会变成。 - 表格会被转换成 Markdown 表格（用竖线和横线表示）。
你还可以调整 markdownify 的行为。比如，去掉 <style> 和 <script> 标签：
markdown_text = md(html_content, strip=['style', 'script'])
如果需求更高级，你甚至可以继承转换器，自定义某些标签的处理方式 (GitHub Docs).
示例：使用 html2text 把 HTML 转成 Markdown
先安装库：
pip install html2text
下面还是用同样的 HTML：
import html2text
html_content = """
<h2>Example Title</h2>
<p>This is a <b>bold</b> word and an <i>italic</i> word.</p>
<p>Visit <a href="http://example.com">our site</a> for more info.</p>
"""
converter = html2text.HTML2Text()
converter.ignore_links = False # 保留链接
markdown_text = converter.handle(html_content)
print(markdown_text)
生成的 Markdown：
## Example Title
This is **bold** word and an *italic* word.
Visit [our site](http://example.com) for more info.
- 默认情况下，html2text 会按 78 个字符自动换行（如果你不想换行，可以设置
converter.body_width = 0）。 - 你可以忽略图片（
converter.ignore_images = True），或者把链接输出成引用式。 - 表格不一定会被格式化成 Markdown 表格——如果表格对你很重要，一定要先测试。
进阶选项：自定义 HTML 转 Markdown 的转换过程
有时候，你需要的不只是“直接转换”。比如你想排除某些 HTML 标签、处理内联样式，或者输出某种特定 Markdown 风格，比如 GitHub Flavored Markdown。
排除或转换特定 HTML 元素
- markdownify： 可以用
strip参数移除标签，或者继承转换器来做自定义处理 (GitHub). - html2text： 使用忽略开关（
ignore_links、ignore_images）。如果想做更复杂的筛选，可以先用 BeautifulSoup 预处理 HTML。 - Pandoc： 通过命令行参数或过滤器来控制转换过程。
- Aspose： 通过保存选项选择 Markdown 风格 (Aspose Docs).
处理内联样式和脚本
- 大多数转换器都会丢掉
<style>和<script>标签，因为 Markdown 本身不支持这些内容 (Aspose Docs). - 如果你要保留代码片段，记得让它们包在
<pre><code>标签里；这样转换器通常会把它们转成 Markdown 代码块。
选择 Markdown 风格
- Pandoc： 可以指定输出风格，比如
-to=gfm表示 GitHub 风格，-to=commonmark等。 - Aspose： 使用
MarkdownSaveOptions来选择风格。 - markdownify： 没有明确的风格切换，但你可以通过微调输出，让它更贴近你的需求。
处理边缘情况
- 嵌入媒体： Markdown 不支持视频嵌入；你可能只能保留链接，或者直接保留原始 HTML。
- Base64 图片： 有些转换器会把 base64 数据直接塞进 Markdown，这会让文件变得特别大；更好的做法是提取图片并改成链接 (Reddit).
- 复杂表格： 如果表格里有合并单元格或嵌套元素，Markdown 可能没法完整保留结构——这时候就得测试并按情况调整。
处理图片、链接和表格
图片：
<img src="logo.png" alt="Logo">会变成。- 如果你不想保留图片，可以用
ignore_images或strip=['img']。
链接：
<a href="url">text</a>会变成[text](url)。- 内联式和引用式：markdownify 默认用内联式；html2text 可以输出引用式。
- 如果是 AI 训练数据，你也许会想去掉 URL，只保留锚文本。
表格：
- markdownify 和 Pandoc 可以把 HTML 表格转成 Markdown 表格（用竖线和横线）。
- html2text 可能只输出纯文本形式的表格。
- 对于复杂表格，务必检查结果，再按需要调整。
反过来：在 Python 中把 Markdown 转成 HTML
有时候你需要把 Markdown 再转回 HTML——比如要在网站上展示内容。Python 做这件事也很轻松。
使用 Python-Markdown：
import markdown
md_text = "# Hello\nThis is **Markdown**."
html_output = markdown.markdown(md_text)
print(html_output)
结果：
<h1>Hello</h1>
<p>This is <strong>Markdown</strong>.</p>
其他可选工具还有 Mistune 和 markdown2。当然，Pandoc 也支持双向转换。
HTML 转 Markdown 的局限与最佳实践
说实话，HTML 转 Markdown 并不是十全十美的。下面这些点你得特别留意，它们也能帮你拿到更好的结果。
局限性
- 并不是所有内容都能顺利转换： 脚本、样式、表单和交互元素通常会被丢掉 (Aspose Docs).
- 可能需要手动清理： 有时候你得自己整理生成的 Markdown，比如修正换行、调整表格，或者把残留的 HTML 清掉。
- 不同 Markdown 风格有差异： 并不是所有渲染器都支持同样的功能，比如表格、脚注等。一定要在目标环境里测试输出。
最佳实践
- 先清洗 HTML： 可以先用 BeautifulSoup 或可读性提取工具，把真正需要的内容提出来 (cantoni.org).
- 大项目尽量自动化： 写脚本批量转换文件，并把它接进网页抓取或文档流程里。
- 测试并迭代： 先拿样本跑一遍，在目标工具里检查 Markdown，再根据结果调整流程。
- 优雅处理错误： 如果遇到格式不规范的 HTML，先清洗或修复，再去转换。
结论与核心要点
不管你是在写文档、准备 AI 训练数据，还是只是想让笔记别那么“硬核”，在 Python 里把 HTML 转 Markdown 都是一项很实用、也很有价值的技能。下面快速回顾一下：
- 为什么重要： Markdown 比 HTML 更简洁、更易读，也更好管理。它已经成了现代文档和笔记场景里的通用语言之一 (Markdown Guide).
- 最佳工具： 对大多数人来说，先用 markdownify 或 html2text。复杂任务交给 Pandoc。要是你需要企业级功能，Aspose 也值得考虑。
- 怎么做： 安装你选的库，跑一个简单脚本，就能得到干净的 Markdown 输出；需要时再做定制。
- 局限性： 可能还是要做一些手动整理，而且不是所有 HTML 特性都有对应的 Markdown 表达方式。
- 下一步： 把示例代码用到你自己的 HTML 上。批量转换旧网页。把转换流程接到业务工作流里。如果你想再往前一步，也可以去看看 Pandoc 的高级功能，或者 Python-Markdown 的扩展。
Markdown 的核心价值，就是让内容更便携、更易读，也更能跟上未来的变化。只要有 Python 和合适的工具，你甚至能把最乱的 HTML 变成团队和未来的你都会感谢的内容。
祝你转换顺利！如果你还想了解更多自动化技巧、AI 驱动的数据抓取，或者单纯想看看数据工作流的“硬核玩法”，欢迎去看看 Thunderbit Blog，里面有更多实战指南和一线经验分享。
常见问题
1. 对商业用户来说，把 HTML 转成 Markdown 有什么好处？
把 HTML 转成 Markdown 能提升内容的可读性、可移植性和可维护性。它特别适合文档、笔记、AI 训练数据，以及把旧内容迁到支持 Markdown 的现代工具中。
2. Python 中哪些工具最适合 HTML 转 Markdown？
常见工具包括 markdownify（适合结构化输出）、html2text（适合快速、简洁的转换）、Pandoc（适合复杂文档），以及 Aspose.HTML（企业级商业方案）。
3. 我该怎么用 Python 把 HTML 转成 Markdown？
你可以用 markdownify 或 html2text 这类库。先用 pip 安装库，把 HTML 内容传进去，工具就会返回 Markdown。每个库都支持一些定制选项，比如去标签、控制输出格式等。
4. HTML 转 Markdown 有哪些限制？
有。像脚本、表单这类交互元素通常没法很好转换，复杂表格或嵌入式媒体也可能需要手动调整。另外，不同 Markdown 风格之间也有细微差别，这会影响最终渲染结果。
5. 我可以用 Python 把 Markdown 再转回 HTML 吗？
当然可以。像 markdown、mistune 和 markdown2 这样的库都能把 Markdown 渲染成 HTML，很容易集成到网页或其他基于 HTML 的系统中。
延伸阅读：
