Python使用mammoth和markdownify实现Word转Markdown

七月

发布时间：2026-10-14 | 3人浏览过

原创

本文介绍如何使用Python将Word文档转换为Markdown格式。通过结合mammoth库将DOCX转为HTML，再利用markdownify将HTML转为Markdown，实现文档格式转换。文中详细讲解了处理Word中图片的自定义逻辑，并提供了完整的代码示例及运行结果分析，帮助开发者快速集成该功能。

随着SaaS服务的普及，越来越多的用户倾向于在各平台上编写文档、制作表格并进行分享。

与此同时，Markdown语法逐渐流行，许多平台开始集成支持这种简洁的标记语言，以确保用户文档样式的统一性。

然而，在某些场景下，我们仍需在本地Office软件中撰写大量文档，或面临历史遗留的本地文档处理需求。

若需将这些文档上传至各大平台，直接复制粘贴往往会导致内容结构和样式丢失。因此，我们需要将其转换为Markdown语法。

许多桌面软件（如Typora）提供了导入Word文件的功能，这类功能通常通过Pandoc软件扩展实现。

Pandoc是一款全能型文档格式转换工具，能够将多种文档格式转换为各类常见格式。具体的文档格式转换关系如下图所示（来源于官网）：

Pandoc如同瑞士军刀，能较好地处理各类文档格式转换。但如果我们需要自行编写程序调用Pandoc，则需额外安装Pandoc，且自定义功能较为不便。

幸运的是，Python中存在许多第三方模块提供此类文档格式转换功能。今天，我们将实现较为常用的Word文档转Markdown文档的功能。

转换逻辑

Word文档到Markdown文档的转换总体分为两步实现：

第一步，将Word文档转换为HTML文档；
第二步，将HTML文档转换为Markdown文档；

依赖模块

要实现此功能，我们需要借助Python的两个第三方模块：

mammoth
markdownify

mammoth是一个用于将Word文档转换为HTML的模块，支持在Python、JavaScript、Java、.Net等平台使用。而markdownify则是将HTML转换为Markdown文档的模块。

处理Word图片

由于Word文档中不可避免地包含大量图片，为确保转换后的文档能正确显示图片，我们需要自定义Word文档内图片的处理方式。默认情况下，mammoth会将图片转换为base64编码字符串，虽无需生成额外的本地图片文件，但会使文档体积显著增大。因此，我们选择将图片另存为本地图片：


# 转存Word文档内的图片
def convert_img(image):
  with image.open() as image_bytes:
    file_suffix = image.content_type.split("/")[1]
    path_file = "./img/{}.{}".format(str(time.time()),file_suffix)
    with open(path_file, 'wb') as f:
      f.write(image_bytes.read())

  return {"src":path_file}

正式转换

在此，我们以州的先生早期编写的《Python爬虫实战与机器学习应用》（需此书者可微信私聊）的Word文档为例进行演示。

代码如下所示：


# 读取Word文件
with open(r"F:\自媒体\Python爬虫实战与机器学习应用.docx" ,"rb") as docx_file:
  # 转化Word文档为HTML
  result = mammoth.convert_to_html(docx_file,convert_image=mammoth.images.img_element(convert_img))
  # 获取HTML内容
  html = result.value
  # 转化HTML为Markdown
  md = markdownify(html,heading_style="ATX")
  print(md)
  with open("./docx_to_html.html",'w',encoding='utf-8') as html_file,open("./docx_to_md.md","w",encoding='utf-8') as md_file:
    html_file.write(html)
    md_file.write(md)
  messages = result.messages

运行程序后，最终生成2个文件：