用Python实现Word转Markdown:从python-docx到样式映射的完整实践

DOCX转Markdownpython-docxWord转换
于 2026-10-29 08:29:31 修改
·本内容遵循CC 4.0 BY-SA版权协议

1. 先想明白:把 Word 搬进 Markdown,搬的到底是什么

1.1 转换的本质是“视觉格式”到“语义结构”的翻译

先说一个最容易让人产生误解的地方。很多人以为 DOCX 转 Markdown 就是把 Word 里的文本“提取”出来,再套上几个 # 号。我一开始也这么想,直到遇到第一份带三级目录的文档,才意识到问题没那么简单。

Word 里的标题,在视觉上可能是“黑体加粗、字号 16、段前段后间距 18 磅、自动编号”,而 Markdown 里的标题只是 # 到 ###### 六个层级。把一个视觉样式翻译成语义标记,需要搞清楚“这个段落为什么被设计成这种样子”,而不是“它看起来是什么样子”。换句话说,转换的过程是一次从视觉语言到结构语言的翻译,翻译的质量取决于你对 Word 文档内在结构的理解程度。

python-docx 读取段落文本只需要一行代码,但要把段落正确地写成 ## 二级标题,你得先判断它的 paragraph.style.name 是不是 Heading 2,或者它的样式层级到底继承自哪套模板。很多从 WPS 转存过来的文档,样式名是一堆乱码或者中文自定义名,靠默认映射根本猜不出来。

1.2 不同使用场景对转换质量的要求天差地别

随着深入,我逐渐发现“DOCX 转 Markdown”这个需求在不同的工作流里,对质量的宽容度完全不一样。我把它大致分成四类:

  • 博客搬家:往往只要求正文、标题、代码块、图片能完整搬过去,表格丢了都能忍,反正博客排版还会再调。
  • 知识库入库:要求就高很多。标题层级必须准确,否则检索系统拿到的文档结构与目录树是错位的;列表要能正确嵌套,否则片段切分后语义混乱。
  • Git 版本管理:最关心的是“可读性”,同一份文档每次改动之后,Git 的 diff 要足够小、足够清晰,这就要求转换结果稳定、确定,不能每次跑出来都不一样。
  • RAG 语料预处理:需要尽量保留表格、列表、层级关系,因为这些都是后续分块和向量化的锚点;图片大部分场景可以丢弃。

我这次的实际场景属于知识库入库加 Git 版本管理,要求恰好处于“不能太糊弄”的档次。如果你的场景只是临时转一篇博客,完全可以只上现成工具,没必要折腾自己写的转换器。

1.3 动手前的预期管理:哪些必须保,哪些可以扔

凡是做过一轮真实文档转换的人,都会得出同一个结论:DOCX 到 Markdown 是一个有损转换,别指望 100% 还原。关键是你自己心里要有一份“保留清单”和“放弃清单”。

我给自己定的保留清单是:标题层级、列表层级、加粗斜体、代码块、表格内容、图片文件、超链接地址。放弃清单是:字间距和行间距、页面边距与分页符、页眉页脚、水印、批注和修订痕迹。Word 里那些为了“好看”而存在的布局信息,转换到 Markdown 之后会变成一堆无意义的空行或换行,反而干扰阅读。我在批量处理前先把这份清单跟需求方对了一下,后面所有代码都是按这份清单来取舍的。这一步看着不起眼,实际上能省掉后期大量“这个怎么没转出来”的扯皮。

2. 现成工具实测:pandoc、mammoth、markitdown 谁更适合中文文档

2.1 三种方案的定位:通用转换器、专业转换器、多格式中转站

在我自己写代码之前,先把市面上的现成方案都跑了一遍。这里主要说三个:pandoc、mammoth,以及微软开源的 markitdown。这三个的定位其实差异很大。

pandoc 是文档转换界的瑞士军刀,支持格式多到数不清,DOCX 转 Markdown 只是它的日常功能之一。它转换时非常讲究“排版完整性”,会尽量保留 Word 里的章节顺序、列表、引用块等结构,但要注意它默认输出的 Markdown 带了很多 pandoc 自己的扩展语法,比如隐式标题层级转换和各类 div 标记,这些在你自己的知识库系统里未必兼容。

mammoth 是专门为了“把 DOCX 转成干净的 HTML 或 Markdown”而生的 Python 库。它的理念是:文档的视觉效果不重要,语义结构才重要。所以它默认就会把 Word 里的标题、粗体、列表等语义元素提取出来,丢掉大部分页面布局信息,输出非常干净。对于绝大多数普通文档,mammoth 转换出来的 Markdown 比 pandoc 更接近我想要的“人类可读”状态。

markitdown 是微软最近开源的多格式转换工具,定位更广:PDF、Word、Excel、PPT、图片都能转 Markdown,设计思路是给 AI 应用统一喂语料。它的 DOCX 转换内部也是走语义提取路线,但项目相对年轻,输出稳定性和对中文的支持还在迭代中。

2.2 实测输出:同样的 docx,三个工具给的结果长什么样

我拿同一份带有一级二级标题、一段加粗文字、一个无序列表、一张表格、一张图片的中文 docx 分别跑了一遍,简单记录一下体感:

工具 标题解析 列表解析 表格解析 图片处理 输出风格
pandoc 准确,但默认输出带扩展语法 支持嵌套列表 基本准确,合并单元格会折叠 导出到 media 目录,路径可用 排版信息保留多,偏重“还原”
mammoth 准确,输出干净的 # 支持嵌套列表 合并单元格会有重复 自动提取图片到指定目录 干净,偏重“语义”
markitdown 准确,但样式命名简单粗暴 常见列表没问题 简单表格可以,复杂表格易乱 提取图片,路径可配置 面向语料,极简

需要说明的是,这只是我抽取的一批样本的体感,不是严谨的基准测试。三个工具对“用原生 Word 列表样式”的文档表现都很好,真正拉开差距的是那些“手打编号、手打空格对齐”的野路子文档。我遇到的一份文档里,所有列表项都是普通正文样式,只是人工在行首敲了“1.”和 Tab 键。pandoc 和 mammoth 把它们全部当成普通段落,markitdown 靠启发式勉强识别了一部分,但还是会把“1.11 子节”和“1.9 子节”的顺序弄错。这种情况你就是把整套工具链换一遍也解决不了,因为它们不可能比你更懂你公司文档的历史习惯。

2.3 什么时候可以停用轮子,什么时候必须自己写

那到底要不要自己写?我给自己定了几条判断标准,也分享给你参考。

如果你的文档来源单一、样式规范、不使用复杂的表格合并和图片排版,直接用 mammoth 就够了,代码量不超过二十行,转换结果稳定可靠。

如果文档来源乱七八糟,样式像是几代人接力维护的,但你对输出质量要求不高(比如只是备份归档),也可以继续用现成工具,接受部分内容错乱。

如果出现下面三种情况,就别继续修轮子了,直接考虑自己写:一是你需要批量控制转换细节,比如图片统一放到某个目录、代码块要按固定规则保留、列表要自动补齐层级;二是文档里有大量自定义样式名,比如“项目符号一级”“正文缩进加粗”,工具自带映射表完全猜不出你的业务含义;三是你需要把转换逻辑嵌入到定时任务里,且要求失败率和异常可控。我这次就是第三条路,因为要把上千份文档纳入 Git,我需要的是能够明确报错、可中断、可重跑、可回归的转换流程,而不是“大部分转出来就行”的批处理脚本。

3. 拆开 DOCX 看真相:一个带了一屋子附件的 ZIP 文件夹

3.1 三步解剖一个最小 DOCX 文件

如果只用 python-docx 做转换,不深究 DOCX 内部结构其实也能跑通,但一旦遇到疑难杂症,你会发现所有问题最终都要回到文件结构层面去找答案。与其到时候再补课,不如先花五分钟把它看明白。

DOCX 本质上就是一个 ZIP 压缩包,只是改了扩展名和内部协议。随便找一个最小的 docx,用解压命令打开:

BASH
unzip -o demo.docx -d demo_xml

你会看到类似这样的目录结构:

TEXT
demo_xml/
├── [Content_Types].xml
├── _rels/
│ └── .rels
├── word/
│ ├── document.xml
│ ├── styles.xml
│ ├── numbering.xml
│ ├── media/
│ │ └── image1.png
│ ├── rels/
│ │ └── document.xml.rels
│ └── theme/
│ └── theme1.xml

简单说,word/document.xml 是正文,word/media/ 是文档里嵌的所有图片,word/styles.xml 是这个文档用到的样式定义,word/numbering.xml 是列表编号规则,word/rels/document.xml.rels 则负责把正文里引用的图片、超链接等资源与真实文件对应起来。你写转换器时 90% 的时间都在跟这几个文件打交道。

3.2 document.xml 里最核心的四层嵌套标签

打开 document.xml,你会看到一堆带着 w: 前缀的标签,这是 WordprocessingML 的命名空间。对转换器来说,核心其实只有四层嵌套关系:

  • w:p 表示一个段落,对应 Markdown 里的一个块元素的基础单位。
  • w:pPr 是段落的属性,里面记着段落的样式 ID、编号属性、对齐方式等。标题级别的判断主要看这里的 w:pStyle。
  • w:r 是段落里的一个片段(run),对应你看到的连续文本和它携带的字符格式。
  • w:t 是 run 里真正的文本内容,所有文字最终都落在这一层。

举个例子,一个简单的“加粗的 Hello”在 XML 里大概长这样:

XML
<w:p>
<w:pPr>
<w:pStyle w:val="Normal"/>
</w:pPr>
<w:r>
<w:rPr><w:b/></w:rPr>
<w:t>Hello</w:t>
</w:r>
</w:p>

理解了这一层,后面你在写转换器时看到 python-docx 返回的对象结构就不会发懵。之所以有 w:r 这一层,是因为 Word 允许一个词甚至一个字拆成多个 run,每个 run 各自带不同的字符格式。这也是加粗斜体转换里最经典的坑,后面我会单独讲。

3.3 为什么建议用 python-docx 而不是直接解析 XML

既然 DOCX 就是 XML,那我能不能直接用 ElementTree 硬写一个解析器?能,但我强烈建议不要。原因有三个:

第一,命名空间太啰嗦。一个标签名写完整是 {http://schemas.openxmlformats.org/wordprocessingml/2006/main}p,你每次都要写 qn() 转一下,代码全是噪音。

第二,样式继承很复杂。一个段落表面上是 Normal 样式,但它可能从文档默认样式、主题字体、直接格式里面继承了好几层属性。python-docx 已经把常用样式属性封装成 paragraph.style.name、run.bold 这样的接口,虽然不完全,但覆盖了 90% 的需求。

第三,图片关系需要跨文件查找。你从 document.xml 里看到一个 <w:drawing>,里面只存了 rId,真正的图片文件在哪,要去 document.xml.rels 里查,然后还要去 [Content_Types].xml 确认类型,最后再到 zip 包里去取文件。这一套关系解析自己写很容易出错,python-docx 的 document.part.rels 已经帮你把手脚接好了。

所以我的结论是:直接解析 XML 只适合两种场景,一是 python-docx 本身支持不了的极端格式,二是你想做一个不依赖第三方库的轻量工具。常规情况下,站在 python-docx 的肩膀上,遇到特殊问题再深入到 XML 层面去处理,是效率最高的组合方式。

4. 从 python-docx 起步:段落遍历、样式映射与 run 级格式救火

4.1 环境准备:依赖、编码和“控制台中文乱码”的第一道坎

开始写代码前,先把环境准备好。我建议在干净的虚拟环境里操作,Python 3.8 以上都可以:

BASH
python -m venv docx2md_env
source docx2md_env/bin/activate # Windows 下是 docx2md_env\Scripts\activate
pip install python-docx

装好后先跑一个最简单的读取脚本,确认 Python 能正常读取你的测试文档:

PYTHON
from docx import Document
 
doc = Document("sample.docx")
for para in doc.paragraphs:
print(para.style.name, "|", para.text)

很多人在这里就会遇到第一道坎:终端打印中文时输出乱码,或者直接抛 UnicodeEncodeError。这不是 python-docx 的问题,而是 Windows 控制台默认编码在作怪。如果你用的是 Windows,建议在脚本最前面加上:

PYTHON
import sys
sys.stdout.reconfigure(encoding="utf-8")

或者在写入文件、打印日志时统一使用 UTF-8 编码。我见过不少人卡在“只说乱码,不说具体报错”的阶段,其实把编码理顺之后,后面一切都会顺很多。

4.2 段落级转换:标题、正文、列表的映射逻辑

python-docx 的 doc.paragraphs 只包含文档顶层的段落,不包括表格里面的段落。如果你直接拿它遍历,表格内容会整个消失。所以我用了一个经典的迭代器,按文档流顺序把段落和表格都找出来:

PYTHON
from docx.document import Document as DocumentType
from docx.oxml.ns import qn
from docx.table import Table
from docx.text.paragraph import Paragraph
 
 
def iter_block_items(parent):
if isinstance(parent, DocumentType):
parent_elm = parent.element.body
elif isinstance(parent, Table):
parent_elm = parent._element
else:
raise ValueError("Unsupported parent type")
 
for child in parent_elm.iterchildren():
if child.tag == qn("w:p"):
yield Paragraph(child, parent)
elif child.tag == qn("w:tbl"):
yield Table(child, parent)

如果你需要递归处理表格内部的嵌套段落,把 cell 作为 parent 再次调用 iter_block_items 即可。拿到一个段落之后,核心就是按样式名做映射。我的大致规则是这样的:

PYTHON
def paragraph_to_markdown(para):
text = para.text.strip()
if not text:
return ""
 
style = para.style.name
 
if style == "Title":
return f"# {text}\n"
if style.startswith("Heading"):
level = int(style.split()[-1])
return f"{'#' * level} {text}\n"
if style.startswith("List Bullet"):
return f"- {text}\n"
if style.startswith("List Number"):
return f"1. {text}\n"
if style == "Quote" or style.startswith("Intense Quote"):
return f"> {text}\n"
return f"{text}\n"

注意这里面有几个业务决策点。一是“标题级别”到底取哪个数字,不同模板可能把一级标题命名为 Heading 1,也可能命名为 标题 1,更复杂的还有 Heading 1 Char 这种字符样式。稳妥的做法是先跑一遍统计出这个文档集里实际出现过的样式名,再写映射表,而不是在代码里硬编码几种英文名。二是列表项,python-docx 会把手动编号按普通正文读出来,我们在这一层只处理用原生样式标记的列表,手动编号的“假列表”放到后面单独清理。

4.3 run 级细节:加粗斜体在 Word 内部的“分身术”

段落文本用 para.text.strip() 拿很快,但这样拿到的文本丢掉了加粗、斜体等行内格式。要想在 Markdown 里恢复 **加粗** 和 *斜体*,必须深入到 run 级别去处理。

这里最容易踩的第一个坑,就是 Word 会把一个视觉上连续的加粗句子拆成多个 run。比如“这是加粗的标题”这个短语,可能第一个 run 是“这是”,后面因为拼写检查或样式继承,第二个 run 才是“加粗的标题”,每个 run 都有加粗属性,但从代码角度看它们是两个东西。如果仅仅按 run 单独判断、单独输出,你最终会得到类似 **这是****加粗的标题** 这种断裂的标记,渲染出来虽然看着差不多,但一旦中间插了空格或换行,就非常难看。

我的处理思路是:遍历 run 时先记录每个 run 的格式特征,把相邻且格式相同的 run 合并成一个逻辑片段,再统一包裹标记:

PYTHON
def format_run(text, bold, italic, code=False):
if code:
return f"`{text}`"
if bold and italic:
return f"***{text}***"
if bold:
return f"**{text}**"
if italic:
return f"*{text}*"
return text
 
 
def paragraph_runs_to_markdown(para):
chunks = []
cur_chunk = ""
cur_bold = False
cur_italic = False
cur_code = False
 
for run in para.runs:
bold = bool(run.bold)
italic = bool(run.italic)
is_code = run.font.name in ("Consolas", "Courier New") or (run.style and "Code" in run.style.name)
 
if cur_chunk and (bold, italic, is_code) != (cur_bold, cur_italic, cur_code):
chunks.append(format_run(cur_chunk, cur_bold, cur_italic, cur_code))
cur_chunk = ""
cur_bold, cur_italic, cur_code = bold, italic, is_code
cur_chunk += run.text
 
if cur_chunk:
chunks.append(format_run(cur_chunk, cur_bold, cur_italic, cur_code))
return "".join(chunks)

这个函数不复杂,但能解决绝大多数行内格式问题。还有一点要注意:run.bold 可能是 None,表示继承段落或文档的样式定义,不要简单显式地把它当 False 处理,否则继承的加粗会丢。如果文档里大量依赖样式继承,那就要先把段落样式里的加粗属性也合并进来,再往下传到 run 处理。

4.4 超链接与特殊段落:不是每次都能走捷径

python-docx 里处理超链接比较绕,因为它把超链接的显示文本放在 <w:hyperlink> 标签内部的 w:r 里,而 para.runs 默认不包含这些 run。我一开始直接用 para.text 拿链接文本,发现链接文字还在,但链接地址完全拿不到。

正确的方式是通过 para.hyperlinks 访问:

PYTHON
for hyperlink in para.hyperlinks:
print(hyperlink.text, hyperlink.address)

但由于普通 run 和 hyperlink 中的 run 是分离的,要把“这一段里既有普通文字又有超链接”完整拼出来,需要自己维护顺序。我采取的是一种简单粗暴但有效的方法:遍历 para._element 的直接子元素,判断是 w:r 还是 w:hyperlink,分别处理。这个过程代码量不大,却很容易被忽略,我这里就不展开完整实现了,你只需要记住“链接文本和普通文本要按 XML 子元素顺序合并”,后面遇到对应问题就不会懵。

5. 表格、图片、代码块:三个最容易让转换器破功的元素

5.1 表格:Markdown 语法要求每行等宽,而 Word 表格是自由的

Markdown 表格语法很严格,每一行用 | 分隔的单元格数量必须一致,否则渲染器直接摆烂。而 Word 表格从来不拘小节:可以合并单元格,可以某一行的列数比别人多,还可以嵌套表格。这两个工具之间的落差,是表格转换最核心的矛盾。

对于没有合并单元格的简单表格,转换逻辑很直接:

PYTHON
def table_to_markdown(table):
lines = []
for row_idx, row in enumerate(table.rows):
cells = [cell.text.strip().replace("\n", "<br>") for cell in row.cells]
if row_idx == 0:
lines.append("| " + " | ".join(cells) + " |")
lines.append("| " + " | ".join(["---"] * len(cells)) + " |")
else:
lines.append("| " + " | ".join(cells) + " |")
return "\n".join(lines)

但一旦遇到合并单元格,这个方法就会出问题:python-docx 遍历 row.cells 时,纵向合并的单元格会在多行里反复出现,导致同一段文本在 Markdown 表格里被复制粘贴好几遍;横向合并的单元格则会让某一行的列数比其他行少,直接破坏表格结构。

我的处理方式是先过滤重复的单元格。用 cell._tc 这个底层 XML 元素作为去重键,只保留第一次出现的实例:

PYTHON
def table_to_markdown(table):
lines = []
for row_idx, row in enumerate(table.rows):
cells = []
seen = set()
for cell in row.cells:
if cell._tc in seen:
continue
seen.add(cell._tc)
text = cell.text.strip().replace("\n", "<br>")
cells.append(text)
if row_idx == 0:
lines.append("| " + " | ".join(cells) + " |")
lines.append("| " + " | ".join(["---"] * len(cells)) + " |")
else:
lines.append("| " + " | ".join(cells) + " |")
return "\n".join(lines)

这样处理后,纵向合并的文本不会重复,横向合并后的空缺在 Markdown 里没法完美表达,但至少不会把整张表搞乱。如果你的表格里有更复杂的合并逻辑,我的建议是:把这张表降级为纯文本形式,保留单元格内容顺序,放弃表格结构,总比转出一张渲染错乱的表格要强。

5.2 图片:把 media 导出到本地,再改引用路径

Word 里的图片管理逻辑是:正文中通过 rId 引用一个资源,真正的图片文件存在 word/media/ 下。python-docx 可以把图片 blob 取出来,但更稳定、更简单的做法是直接用 zipfile 读取整个 docx,把 word/media/ 下的文件全部导出到目标目录:

PYTHON
import zipfile
from pathlib import Path
 
 
def extract_images(docx_path, output_dir):
output_dir = Path(output_dir)
output_dir.mkdir(parents=True, exist_ok=True)
with zipfile.ZipFile(docx_path) as zf:
for name in zf.namelist():
if name.startswith("word/media/"):
data = zf.read(name)
filename = Path(name).name
(output_dir / filename).write_bytes(data)

为什么推荐这样而不是遍历 doc.part.rels?因为纯 zipfile 操作不依赖 python-docx 对关系的加载,遇到异常文档时容错更好;而且 DOCX 体积通常不大,把 media 整个目录抽出来是很快的。

图片导出之后,还需要在 Markdown 里给每个引用位置拼正确的路径。最简单的方式是在转换正文时,遇到 <w:drawing> 就解析出它的 rId,再通过关系表找到对应的图片文件名,输出 ![图片说明](assets/images/xxx.png)。解析 drawing 的简要思路是:

PYTHON
from docx.oxml.ns import qn
 
def extract_image_r_ids(paragraph):
r_ids = []
for drawing in paragraph._element.findall(qn("w:drawing")):
for blip in drawing.findall(".//" + qn("a:blip")):
r_id = blip.get(qn("r:embed"))
if r_id:
r_ids.append(r_id)
return r_ids

拿到 rId 后,用 doc.part.related_parts[r_id] 就能拿到对应的图片 part,进而取得文件名和 blob。这条路一开始看起来繁琐,但一旦走通,所有图片引用都会变得非常可靠。

还要提醒一个特别容易踩的坑:Word 文档里的图片不一定是 PNG 或 JPEG,很多老文档嵌的是 EMF、WMF 这种矢量格式。Markdown 阅读器大多数不支持直接渲染,转换后你需要先把它们批量转成 PNG。我这边是用 LibreOffice 命令行批量处理:

BASH
soffice --headless --convert-to png --outdir assets/images assets/images/xxx.emf

Windows 上如果装了 LibreOffice,soffice 在安装目录的 program 文件夹里,记得把它加到 PATH 里再跑。

5.3 代码块:从样式名和字体特征去识别,而不是猜语言

DOCX 里其实没有“代码块”这种语义概念,只有“应用了某种样式或某种字体的一段文字”。所以我识别代码块用的是两条规则的组合:

  • 段落样式名里包含 Code、Source、源码、代码 这类关键词;
  • 段落使用的字体名是 Consolas、Courier New 或其他等宽字体。

命中其中一条,我就把这个段落输出为围栏代码块:

PYTHON
CODE_STYLE_KEYWORDS = ("code", "source", "源码", "代码")
 
 
def is_code_paragraph(para):
style_name = para.style.name.lower()
if any(k in style_name for k in CODE_STYLE_KEYWORDS):
return True
for run in para.runs[:5]:
font_name = (run.font.name or "").lower()
if font_name in ("consolas", "courier new"):
return True
return False

注意,Word 里没有记录代码的语言类型,转出来的代码块默认不带高亮语言标识。如果文档集里代码语言很固定(比如全是 SQL),你可以通过文件名、上下文关键词做简单猜测;否则就统一输出成无语言的围栏代码块,让后续编辑时人工补。千万别尝试在转换器里用一堆正则去猜语言,样本一多必然误判,代码块渲染出来比不渲染还难受。

6. 真实业务文档里踩过的四个坑,以及完整的排查思路

6.1 坑一:连续空段落把 Markdown 挤成一坨空白

我跑完第一批五十份文档后,打开生成的 Markdown 文件,发现好多地方出现大段空白,有的地方隔着十几行空行才看到下一段正文。一开始以为是转换器 bug,后来一查才发现罪魁祸首是原文里就连着七八个空段落。

Word 里很多人习惯用空段落“撑开”排版距离,这属于常见操作。但空段落到了 Markdown 里就是空行,一两处还行,七八处连在一起就直接把内容顶散了。我的解决办法是:在输出时压缩连续空行,合并成一个段落分隔符;同时在每份文档内部设定“连续空白超过三行就截断”的规则。

排查思路也分享给你:遇到空白异常,先别急着改代码,把生成的 md 和原 docx 并排打开,看空白是均匀分布在页面底部,还是固定在某个结构元素之后。后者通常意味着是表格或者图片后面的空段落被原样输出了,处理起来更有针对性。

6.2 坑二:手动编号加制表符造成的“假列表”

第二份样本让我更头疼。文档里大面积出现这种内容:

TEXT
1. 需求分析
1.1 背景说明
1.2 目标用户
2. 技术方案

看起来是有序列表,但实际上每个段落都是普通正文样式,只是行首输入了“1.”“1.1”“2.”,以及一串手打的空格或制表符。python-docx 里它们的 style 全是 Normal,所以我的转换器把它们全部输出成了普通段落,列表层级信息在 Markdown 里完全丢失。

这个问题没有特别简单的库函数能解决,必须写启发式逻辑。我最终采用的规则是:

  • 如果段落文本以数字加 . 或 、 开头,再跟空格,视为有序列表项;
  • 判断该段落与前一段的文本缩进情况,如果前一段顶部空格更多,则视为子列表;
  • 如果段落以 -、•、* 加空格开头,视为无序列表项;
  • 开头符号后面如果跟着的完全是中文且没有编号递增规律,降低识别置信度,宁可当普通段落也不要误判。

启发式规则没法做到 100% 准确,所以我在转换器里加了一个“不确定列表”日志,专门把命中低置信度规则的段落打印出来,人工扫一遍再决定要不要调整阈值。这种做法在批量场景里比追求完美算法更务实。

6.3 坑三:Windows 下文件编码导致的乱码

这其实不是 DOCX 特有的坑,但在 Windows 环境下批量转换时特别容易碰到。我在一台 Windows 服务器上跑批处理,输出日志里中文乱码,生成的 md 文件用记事本打开没事,但用某些脚本读取时却报编码错误。

排查链路是这样的:先看 Python 进程的输出编码,发现控制台默认用 GBK,重新配置成 UTF-8 后日志正常了;再看写入文件时是否指定编码,我最初用 open(md_path, "w") 没有指定 encoding,Python 会按 locale 默认编码写入,在中文 Windows 上就是 GBK。后来全部改成:

PYTHON
with open(md_path, "w", encoding="utf-8") as f:

同时把读文件的代码也统一加上 encoding="utf-8",问题就彻底消失了。这里有个经验:处理文本文件时,读写两侧都要显式指定编码,不要依赖默认值。你的脚本在 Linux 上默认 UTF-8 没问题,一跨到 Windows 就翻车,基本全是这个原因。

6.4 坑四:合并单元格在表格里反复“分身”

表格合并的问题我在 5.1 里提过,这里说一个更隐蔽的情况。有些文档的合并单元格在 python-docx 里重复出现不是简单的“同一行里两次”,而是纵向合并后每一行都会遍历到同一个 _tc。我最初发现输出的 Markdown 表格里某列内容反复出现,比如“总计 100 元”出现了四行,还以为是文本提取错了,差点去查 python-docx 的源码。

后来在调试过程中我打印了每个单元格对象的内存地址,发现合并单元格在 row.cells 里本来就是同一个对象重复返回。明白了这一点,解决方案就很清晰:用 cell._tc 做全局去重键,第一次遇到就输出,后面遇到跳过。这个 bug 的启示是:遇到“内容重复”的问题,不要先怀疑文本解析,先检查是不是元素引用关系导致的重复遍历,这个方向能帮你省下不少时间。

跑完这一千多份文档之后,我对“用 Python 把 DOCX 转成 Markdown”这件事有了完全不同的理解:真正的难点从来不在转换算法本身,而在于面对不可控的文档格式时,你能不能把问题拆成“可逆的结构问题”和“不可逆的录入习惯问题”两类。前者用代码解决,后者用规则和人工抽检解决。我最后再分享一个很实用的经验:给转换器配一套回归样本。我从全部文档里挑出十份格式差异最大的样本,每次改动转换逻辑后都跑一遍,对比输出 diff,确保“修好一个新问题”的同时不会“搞坏两个旧场景”。这套做法看起来笨,但在一千份文档的批量场景里,比什么都管用。如果你也要做同类项目,建议从第一天就把它加进你的流程里。

基于Python+Open CV的手势识别算法设计
伴随着人工智能时代的到来,人机交互的领域也逐渐成为研究的一大方向;其中,手势识别是人机交互领域的一项关键技术,自此手势识别也迎来了一波高潮,近几年无论是在消费领域、电子领域、数码领域、家电领域甚至汽车领域上,都能或多或少的见到手势识别的身影。 手势识别在设计智能高效的人机界面方面具有至关重要的作用, 目前手势识别已应用到手语识别、智能监控、到虚拟现实等各个领域,手势识别的原理都是利用各种传感器(例如红外、摄像头等)对手部的形态进行捕捉并进行建模,形成一个模型信息的序列帧,而后将这些信息序列转换为机器能够识别的相对应指令(例如打开、切换菜单、移动等)来完成控制。 采用Python的集成开发环境Pycharm进行本次课程设计,在Pycharm中进行需要库(模块)的下载,调取电脑摄像头,按帧读取摄像头采集到的头像,形态学处理,图像旋转(由于摄像头采集到的图像是镜像,需要用cv2.flip将摄像头采集到的图像进行处理),选取图片中固定位置作为手势输入,用红线画出手势识别框,基于hsv的肤色检测,进行高斯滤波,找出轮廓,求出图像中手势的凹凸点,手指间角度求取。
努力学习前端的小陈
ArcGIS Pro入门制图教程
地理信息系统 (GIS) 是一种使用地图显示和分析数据的方式。在本教程中,您将学习桌面 GIS 应用程序 ArcGIS Pro 的基础知识。新加坡的一家旅行社希望制作一款宣传册,用于向游客介绍距离市中心热门目的地最近的火车站。该宣传册将与带有文本信息的地图相结合,并在城市的自助设备中出售。您将帮助该旅行社绘制旅游景点的地图,分析其与火车站的距离以及更改地图的外观以使其在视觉上更具吸引力。在 ArcGIS Pro 中,地图和数据通常被组织在一个工程中。开始制作地图之前,您将创建一个工程。
科研online
ArcGIS Pro 布局创建与地图加载全流程解析
本文详细解析了ArcGIS Pro中布局创建与地图加载的全流程。针对从ArcMap转来的用户,重点阐述了布局与地图解耦的核心设计理念,并提供了从新建布局、设置参考比例尺、加载地图框到深度控制与精细化排版的实用技巧,帮助用户高效制作专业地图。
您的账号已被封禁
ArcGIS PRO布局视图避坑指南:地图框添加与专题图制作的5个关键步骤
本文针对ArcGIS PRO用户在布局视图中制作专题图时遇到的常见问题,提供了地图框添加与专题图制作的5个关键步骤避坑指南。从理解布局视图思维、数据框预处理、地图元素协同配置,到深化视觉层次与最终输出检查,系统讲解了如何高效产出严谨美观的专业地图,帮助用户跨越从数据分析到地图输出的最后一公里。
冰炭不同炉
ROS-CV-ImageConverter:将ROS图像转换为OpenCV(cv :: Mat)类型的图像
ROS-CV图像转换器 依存关系 cv_bridge(ROS软件包)
Willis Wang
计算机视觉图像处理-CV2与图像插值算法
用最近邻插值与双线性插值原理完成图像缩放 最近邻插值,是指将目标图像中的点,对应到源图像中后,找到最相邻的整数点,作为插值后的输。缺点:使用最近邻插值算法处理图像放大时,在图象中可能出现明显的块状效应 双线性插值,在两个方向上做三次线性插值。使用双线性插值算法处理图像放大时,在图象中可能出现马赛克 代码 import cv2 img = cv2.imread(’./xiabang.jpg’, cv2.IMREAD_UNCHANGED) #缩放比例 scale_percent = 0.3 width = int(img.shape[1] * scale_percent) height = int
weixin_38697274
基于水平集CV模型的图像分割(Matlab代码)
基于水平集CV模型的图像分割(Matlab代码),全套代码
小宇QAQ
导向滤波(guide_filter)的python实现
导向滤波(guide_filter)的python实现,可以结合暗通道;理论实现比较好的图像去噪效果。
zachzhan_g
ArcGIS Pro 如何新建布局
你是否已经习惯了在ArcGIS中数据视图和布局视图之间来回切换,到了ArcGIS Pro中却找不到二者之间切换的按钮,即使新建布局后却发现地图怎么却是一片空白。从上面的图中可以看到,虽然新建了布局,但是地图还是空白的,如果想要显示地图还需要加载一下,将地图加载进来。在新建的布局上绘制一个框,作为地图显示的范围,绘制后可以看到地图已经完成加载,如下图所示。在菜单栏上选择插入,点击新建布局下拉箭头,选择一个合适的尺寸,如下图所示。点击后完成布局的新建,新建的布局如下图所示。
水经注GIS
ArcGIS Pro数据修复与图层管理实战指南
本文是ArcGIS Pro数据修复与图层管理的实战指南。针对数据源丢失导致的“红色叹号”问题,详细讲解了一键批量修复和进阶手动修复策略,并分享了使用相对路径、打包工程等防患于未然的黄金法则。同时,深入介绍了如何利用图层组进行高效的地图内容组织、比例尺控制与批量操作,帮助用户构建清晰、智能的专业地图,大幅提升GIS项目管理效率。
Tomato
ArcGIS Pro布局设计实战:从空白页面到专业地图输出的完整工作流
本文详细解析了ArcGIS Pro中从“新建布局”开始,到输出专业地图的完整工作流。内容涵盖布局哲学、地图框深度运用、制图元素集成及视觉排版等核心环节,旨在帮助中级用户掌握项目驱动的现代化制图方法,实现从数据到出版级地图的精准转化。
AnjneyMidha
ArcGIS PRO布局视图避坑指南:地图框添加与坐标系设置的5个常见错误
本文针对ArcGIS PRO用户在布局视图中常遇的难题,重点解析了地图框添加与坐标系设置的5个常见错误。从地图框的创建逻辑、坐标系冲突的根源剖析,到地图范围控制、元素联动更新以及打印导出设置,提供了一套完整的避坑指南与实战解决方案,帮助用户高效、精准地完成地图制图与输出工作。
重离子猫猫
ArcGIS Pro布局设计避坑指南:为什么你的地图总是显示空白?
本文深入解析ArcGIS Pro布局设计中地图显示空白的常见问题,提供从基础操作到高级排错的完整解决方案。重点讲解地图框的正确使用方法、布局元素配置技巧,以及多地图框协同工作等进阶功能,帮助用户快速掌握专业地图制作的核心技术。
习翔宇
CV算法(MATLAB)
chan 和 vese 提出的经典CV模型
beastLOVE
GrabCut:使用opencv-python cv2.grabCut交互式剪切图像
GrabCut 使用opencv-python cv2.grabCut交互式剪切图像
Aaron Gary
Opencv-Python图像透视变换cv2.warpPerspective的示例
今天小编就为大家分享一篇关于Opencv-Python图像透视变换cv2.warpPerspective的示例,小编觉得内容挺不错的,现在分享给大家,具有很好的参考价值,需要的朋友一起跟随小编来看看吧
weixin_38711369
leetcodecv-Kylin:CV算法岗面经&LeetCode刷题总结
leetcode cv Kylin CV算法岗面经 & LeetCode刷题总结 不断更新中。。。。 面试&笔试经验 LeetCode
weixin_38499553
基恩士CV-X系列相机控制器用户手册CV-X Series Users Manual_CHS.pdf
基恩士CV-X系列相机控制器用户手册CV-X Series Users Manual_CHS真的很不错,
weixin_43905342
ArcGIS布局视图方向调整与优化技巧
地图布局方向是GIS制图的基础设置,直接影响空间数据的可视化效果。横向(Landscape)和竖向(Portrait)布局通过调整页面长宽比例,可优化不同地理要素的展示方式。在ArcGIS等专业制图软件中,方向设置会联动影响比例尺、图例等核心元素的自动适配逻辑。本文以A4纸张为例,详解通过页面设置、Python脚本批处理等技术手段实现布局方向的高效调整,并针对比例尺失准、图例溢出等典型问题提供工程解决方案。特别适用于带状区域地图制作等需要最大化利用版面空间的场景,可提升40%以上的图面利用率。
塞音菩光
ArcGIS Pro 3.4必学新功能:符号系统与布局视图的可见性联动(含省时技巧)
ArcGIS Pro 3.4引入了符号系统与布局视图的可见性联动功能,通过唯一值符号化和复选框控制,实现原子级要素显示/隐藏。这一创新极大提升了制图效率,支持在符号系统窗格、内容窗格和布局视图中同步操作,特别适合城市规划、环境监测等需要动态展示的场景。
t8u9v0
ArcGIS Pro 布局创建与地图加载全攻略
本文详细解析了ArcGIS Pro中布局与地图分离的设计哲学,并提供了从新建布局到加载地图的完整操作指南。重点介绍了如何通过“插入”选项卡新建布局、选择合适的页面尺寸,以及使用地图框工具将项目中的地图动态链接至布局。文章还涵盖了地图范围控制、比例尺锁定、图例添加等深度定制技巧,帮助用户高效创建专业地图并导出为高质量成果。
milk8
ArcGIS多图布局实战:从数据框管理到批量导出的完整指南
在地理信息系统(GIS)制图领域,将多张地图高效整合到单一版面是提升分析报告专业性与表现力的关键技术。其核心原理在于理解并运用数据框与布局视图的分离机制,通过独立的数据框承载不同区域或专题的地理数据,并在统一的布局视图中进行精确排版与视觉整合。这项技术的核心价值在于实现了制图流程的标准化与自动化,避免了传统拼图方式带来的效率低下与更新困难问题,尤其适用于区域对比、时间序列分析、综合评估报告等需要多视角、多维度展示地理信息的应用场景。本文聚焦于ArcGIS Pro平台,深入剖析了多图布局中数据框范围联动、地图
aaa1231722
monolithic-cv:CV算法的集合
单片-cv 计算机视觉算法转储
晨曦姜
改进的cv图像分割
改进的cv图像分割,对学习cv模型有帮助
a904235765
C++实现基于暗通道与导向滤波的图像去雾算法
资源下载链接为: https://pan.quark.cn/s/1bfadf00ae14 在图像处理领域,图像去雾技术用于消除大气散射导致的模糊,提升图像清晰度和视觉质量。本文将介绍一种基于暗通道和导向滤波的图像去雾算法,并探讨如何使用C++和OpenCV库实现。 暗通道理论由Jia等人于2006年提出。他们发现自然场景中存在一些低亮度像素,通常位于无直射光区域。这些像素被称为暗通道像素,可用于估计大气散射模型中的透射率。具体方法是将图像分块,在每块中找到最暗像素值作为暗通道像素。 大气散射模型是图像去雾的基础,描述了光线在大气中传播时的散射影响。模型公式为: I(x)=T(x)×J(x)+A×(1−T(x)) 其中,T(x)是透射率,J(x)是无雾图像亮度,A是全局大气光。透射率与散射程度成反比,无雾图像亮度反映物体本身色彩。 利用暗通道先验,可以近似估计透射率。假设D(x)为暗通道像素,透射率T(x)可通过迭代公式计算: T k+1 (x)= max(D)+ϵ D(x) +(1− max(D)+ϵ D(x) )×T k (x) 其中,k是迭代次数,ϵ是小常数,用于避免除零。 估计透射率后,使用导向滤波器平滑透射率图,减少噪声和边缘失真。导向滤波是一种自适应局部滤波方法,可保持图像边缘细节,同时进行平滑处理。在图像去雾中,它根据图像梯度信息指导滤波过程,更好地恢复图像清晰度。 通过大气散射模型,可得到去雾后的图像: J out (x)= T(x) I(x)−A×(1−T(x)) +A 在C++中,可借助OpenCV库处理图像数据。首先读取输入图像,然后提取暗通道,估计透射率,应用导向滤波,最终恢复无雾图像。OpenCV提供了丰富的图像处理函数,如cv::split用于分离通道,cv::min用于找最小值,cv::filter2D用于导向滤波,cv::imwrite用于保存
KaiyuanCode
cv模型图像分割matlab源程序
cv模型 matlab 图像分割源码,逻辑清晰,注释详尽。
phoenix01
CV图像分割
从pud找到的CV图像分割代码,代码的通过较少的迭代次数就可以实现图像的分割,对学习CV分割有帮助。
a904235765
ArcGIS Pro 3.0 布局视图实战:5分钟搞定专业地图的图例、比例尺与指北针
本文详细介绍了ArcGIS Pro 3.0布局视图的实战技巧,帮助用户在5分钟内高效添加图例、比例尺与指北针,打造专业地图。通过智能图例、动态比例尺和现代化指北针设计,提升制图效率与美观度,特别适合GIS初学者和从ArcMap迁移的用户。
weixin_30652491
ArcGIS Pro界面突然消失?3种恢复方法+自定义布局技巧
本文针对ArcGIS Pro用户常见的操作界面元素突然消失问题,提供了三种核心恢复方法:通过“视图”功能区一键唤回、利用“重置窗格”命令恢复默认布局,以及通过应用程序设置进行深度恢复。文章还深入讲解了如何通过停靠、分组窗格以及自定义功能区等技巧,打造高效个性化的操作界面,帮助用户从被动解决问题转向主动优化工作环境。
nnn11
【机电杂谈2】BLDC和PMSM的特点和区别
在日常生活中,小到电动玩具,大到电动汽车,永磁电机的身影可以说是无处不在。有刷直流电机、无刷直流电机、永磁同步电机由于其结构和输出特定的不同也被应用到不同的场合。如果你经常拆一些玩具和家电,就会看到大量的有刷直流电机和无刷直流电机,而永磁同步电机主要应用在高精度的工业伺服和电动汽车领域。本文就从电机的结构和控制方面,对这几种常见的永磁电机做简单的梳理和归纳。
硬件狗