Python 实战：将 HTML 批量转换为 Markdown

在日常开发中，我们经常遇到需要将网页内容或 HTML 格式的文档转换为 Markdown 的场景。无论是将旧博客迁移到静态站点生成器，还是为技术文档建立版本控制，Markdown 凭借其纯文本特性和简洁语法，往往比 HTML 更适合作为中间存储格式。手动复制粘贴不仅效率低下，还容易丢失结构信息。本文以 Spire.Doc for Python 为例，介绍如何通过代码完成 HTML 到 Markdown 的转换，涵盖文件转换、字符串处理以及批量操作等常见需求。

环境准备

Spire.Doc for Python 是一个独立的文档处理库，无需在系统中安装 Microsoft Word 或其他办公软件即可运行。它支持包括 HTML、Markdown、DOCX 在内的多种格式互转。首先通过 pip 完成安装：

bash 复制代码

pip install spire.doc

在脚本中引入所需的模块：

python 复制代码

from spire.doc import *

将 HTML 文件转换为 Markdown

最直接的使用场景是处理已保存为 .html 文件的网页或文档。整个转换过程仅需四步：创建文档对象、加载 HTML 文件、另存为 Markdown 格式、释放资源。

python 复制代码

from spire.doc import *

doc = Document()
doc.LoadFromFile("input.html", FileFormat.Html)
doc.SaveToFile("output.md", FileFormat.Markdown)
doc.Close()

这段代码会将 input.html 转换为 output.md。在转换过程中，HTML 中的标题标签会被映射为 Markdown 的 # 层级，段落、列表、链接和图片等元素也会尽可能保留其原始结构。LoadFromFile 的第二个参数 FileFormat.Html 明确告知库以 HTML 解析器读取文件，显式指定可以避免依赖扩展名推断带来的歧义。

处理 HTML 字符串

有时 HTML 内容并非来自文件，而是通过 API 响应或网页抓取动态获得。此时直接操作字符串比先写入临时文件更为高效。Spire.Doc 提供了 AppendHTML 方法，允许将 HTML 片段追加到文档的段落中，再整体导出为 Markdown。

python 复制代码

from spire.doc import *

doc = Document()
section = doc.AddSection()
paragraph = section.AddParagraph()

html_content = """
<h1>示例标题</h1>
<p>这是一个包含 <strong>加粗</strong> 和 <em>斜体</em> 的段落。</p>
<ul>
    <li>列表项一</li>
    <li>列表项二</li>
</ul>
"""

paragraph.AppendHTML(html_content)
doc.SaveToFile("string_output.md", FileFormat.Markdown)
doc.Close()

需要留意的是，调用 AppendHTML 之前必须先添加 Section 和 Paragraph，否则会抛出异常。这种方式适合处理结构相对简单的 HTML 片段。如果 HTML 字符串体量较大或包含复杂的嵌套结构，建议仍先保存为文件再执行转换，以便于排查解析过程中可能出现的异常。

批量转换多个文件

当需要迁移整个目录下的 HTML 文档时，结合 os 模块遍历文件即可实现批量处理。以下脚本会将 html_files 目录中所有 .html 文件转换为同名 .md 文件，并存入 markdown_files 目录。

python 复制代码

import os
from spire.doc import *

input_folder = "html_files"
output_folder = "markdown_files"

os.makedirs(output_folder, exist_ok=True)

for filename in os.listdir(input_folder):
    if filename.endswith(".html"):
        doc = Document()
        doc.LoadFromFile(os.path.join(input_folder, filename), FileFormat.Html)
        
        output_name = filename.replace(".html", ".md")
        output_path = os.path.join(output_folder, output_name)
        doc.SaveToFile(output_path, FileFormat.Markdown)
        doc.Close()

批量操作时，每次循环都创建新的 Document 对象并在使用后调用 Close() 是必要的。如果在循环外复用同一个对象而不清理状态，后续文件可能会继承前一次转换的残留内容，导致输出异常。

转换中的限制与注意事项

Markdown 的语法表达能力远不及 HTML。HTML 中的 CSS 样式、多栏布局、表格的合并单元格、页眉页脚等元素，在 Markdown 中没有对应的原生语法。转换工具通常会将这类复杂结构简化为纯文本或基础 Markdown 元素，部分格式信息会不可避免地丢失。因此，在执行批量转换前，建议先选取一两个具有代表性的文件进行试转换，检查关键内容是否按预期保留。

此外，源 HTML 本身的规范性也会影响输出结果。如果 HTML 中存在未闭合的标签或嵌套错误，解析过程可能产生不完整的 Markdown。在转换前使用 HTML 校验工具清理源文件，有助于提高输出质量。

结语

通过 Spire.Doc for Python 实现 HTML 到 Markdown 的转换，核心逻辑集中在 LoadFromFile 与 SaveToFile 两个方法上，配合 FileFormat 枚举指定源格式和目标格式即可完成单文件处理。字符串转换和批量脚本则在此基础上扩展，分别应对动态内容和多文件场景。对于格式复杂的大型 HTML 文档，转换后仍需人工抽查关键段落，以确保 Markdown 输出的可读性和结构完整性。