html2text：HTML 转 Markdown 的轻量 Python 工具

html2text 是一个将 HTML 页面转为纯文本的 Python 工具，在 GitHub 上收获了 2,154 颗 Star：

它的输出是干净的 ASCII 文本，同时也是合法的 Markdown。这个项目最初由 Aaron Swartz 编写，以 GPLv3 协议开源。

功能定位

html2text 只做一件事：把 HTML 转成 Markdown。没有多余的包装，输入 HTML 字符串或文件，得到结构清晰的 Markdown 文本。

命令行调用方式很直接：

html2text [filename [encoding]]

支持的选项包括：

选项	说明
--ignore-links	不保留链接格式
--escape-all	转义所有特殊字符，输出可读性降低，但能避免格式问题
--reference-links	使用引用式链接替代内联链接
--mark-code	用 [code]...[/code] 标记代码块

完整的选项列表可参考项目文档。

Python API

html2text 可以直接在 Python 中导入使用。最简单的调用方式：

import html2text

print(html2text.html2text("<p><strong>Zed's</strong> dead baby, <em>Zed's</em> dead.</p>"))

输出：

**Zed's** dead baby, _Zed's_ dead.

如果需要更细粒度的控制，可以实例化 HTML2Text 类：

import html2text

h = html2text.HTML2Text()
h.ignore_links = True
print(h.handle("<p>Hello, <a href='https://www.google.com/earth/'>world</a>!"))

这段代码会输出纯文本 Hello, world!，链接被剥离。

将 ignore_links 改回 False，链接会以 Markdown 格式保留：

h.ignore_links = False
print(h.handle("<p>Hello, <a href='https://www.google.com/earth/'>world</a>!"))

输出为：

Hello, [world](https://www.google.com/earth/)!

安装

html2text 已发布到 PyPI，安装命令如下：

pip install html2text

开发测试

项目使用 tox 管理测试环境：

tox

生成覆盖率报告：

coverage html

之后用浏览器打开 ./htmlcov/index.html 查看结果。

CI 流程包含 mypy 类型检查、Flake8 代码风格检查和 Black 格式化。提交代码前建议运行：

tox -e pre-commit

确保所有检查项通过后再推送到仓库。

html2text 代码量不大，接口设计简洁。对于需要将 HTML 内容提取为 Markdown 的场景，它是一个直接可用的选择。

pre-commit

确保所有检查项通过后再推送到仓库。

html2text 代码量不大，接口设计简洁。对于需要将 HTML 内容提取为 Markdown 的场景，它是一个直接可用的选择。