文档结构化实战：从 Markdown/PDF 到 Word

Thu, 04 Jun 2026 12:00:00 +0800

纸上得来终觉浅，绝知此事要躬行。本文记录文档结构化转换的实战经验，重点攻克 LaTeX 公式渲染、表格提取等难点。

背景

写学术论文时，常有两类需求：

Markdown → Word：用 Markdown 写内容，一键套用学术模板生成 Word
PDF → Word：把 PDF 论文转成可编辑的 Word 文档

本文基于 kritidocx-demo 项目，总结实战中踩过的坑和解决方案。

一、Markdown 转 Word

1.1 方案选择

方案	优点	缺点
KritiDocX	功能完整，支持模板	依赖外部库
python-docx + BeautifulSoup	纯 Python，可控性强	需要自己实现解析逻辑

本项目采用 python-docx + BeautifulSoup 方案，自己掌控每一行代码。

1.2 核心流程

Markdown (内容)
 ↓
HTML (markdown 库解析)
 ↓
模板 HTML (插入变量)
 ↓
Word (python-docx 生成)

1.3 LaTeX 公式 → Word OMML

这是最复杂的部分。Word 使用 OMML (Office Math Markup Language) 存储数学公式，需要把 LaTeX 语法转换为 OMML XML。

实现思路

def parse_latex_to_omml(latex: str) -> OxmlElement:
 """将 LaTeX 转换为 Word OMML 结构"""
 math = create_element("oMath")

 # 处理分数 \frac{分子}{分母}
 frac_match = re.search(r"\\frac\{([^}]+)\}\{([^}]+)\}", latex)
 if frac_match:
 frac = create_element("f")
 # ... 构建 oMath 分数结构

 return math

关键点

命名空间：OMML 使用 m: 前缀的命名空间

def create_element(tag: str, text: str = None, **attrs) -> OxmlElement:
 elem = OxmlElement(f"m:{tag}") # m:oMath, m:f, m:num...
 for key, val in attrs.items():
 elem.set(qn(f"m:{key}"), val)
 return elem

分数结构：

oMath
└── f (fraction)
 ├── fPr (fraction properties)
 │ └── ctrlPr → ctrl: "on"
 ├── num (numerator)
 └── den (denominator)

文本模式：\text{...} 需要转换为纯文本 run

latex = re.sub(r"\\text\{([^}]+)\}", r"\1", latex)

1.4 模板系统

预置三种学术模板：论文(paper)、会议(conference)、报告(report)，通过 HTML 模板定义格式：

<!-- templates/paper.html 片段 -->
<header>
 <h1>$TITLE$</h1>
 <p class="author">$AUTHOR$</p>
</header>
<div class="abstract">
 <h2>摘要</h2>
 <p>$ABSTRACT$</p>
</div>
<main></main>

运行时替换 $TITLE$ 、 $AUTHOR$ 等变量，将 Markdown 解析后的 HTML 插入 <main></main>。

1.5 效果

md2latex demo/sample.md --template paper -o output.docx

生成的 Word 包含：

标题居中、作者信息
摘要样式
LaTeX 公式渲染为可编辑的 OMML
表格、图片自动插入

二、PDF 转 Word

2.1 方案选择

库	用途	特点
pyMuPDF	提取文本、图像	速度快，支持布局分析
pdfplumber	提取表格	专门优化表格检测
python-docx	生成 Word	跨平台 API 友好

本项目采用 pyMuPDF + pdfplumber + python-docx 三件套。

2.2 文本提取

pyMuPDF 的 page.get_text("dict") 可以获取详细的文本块信息，包括字体大小、位置：

def extract_text_with_layout(page: fitz.Page) -> list[tuple[str, float]]:
 """提取文本，保留布局信息"""
 text_dict = page.get_text("dict")

 items = []
 for block in text_dict.get("blocks", []):
 if block.get("type") != 0: # 只处理文本块
 continue

 block_lines = []
 for line in block.get("lines", []):
 line_texts = []
 for span in line.get("spans", []):
 text = span.get("text", "")
 if text.strip():
 line_texts.append(text)

 if line_texts:
 line_text = " ".join(line_texts)
 block_lines.append(line_text)

 if block_lines:
 spans = block.get("lines", [[]])[0].get("spans", [])
 size = sum(s.get("size", 10) for s in spans) / len(spans) if spans else 10
 items.append((block_bbox[1], "\n".join(block_lines), size))

 return sorted(items, key=lambda x: x[0]) # 按 y 坐标排序

2.3 标题识别

根据字体大小判断标题级别：

def detect_heading(text: str, size: float) -> tuple[bool, str]:
 """判断文本是否为标题"""
 text_stripped = text.strip()

 # 特殊关键词
 if text_stripped.lower() in ["abstract", "摘要"]:
 return True, "Heading 2"

 # 编号标题（如 "1. Introduction"）
 section_match = re.match(r"^(\d+\.?\d*)\s+[A-Z][a-z]", text_stripped)
 if section_match and len(text_stripped) < 80:
 return True, "Heading 2"

 # 字体大小判断
 if size >= 14:
 return True, "Heading 1"
 if size >= 12:
 return True, "Heading 2"

 return False, "Normal"

2.4 表格提取

pdfplumber 的 extract_words() 返回单词级别的位置信息，可以基于 y 坐标分组重建表格：

def extract_mmlu_table(page: pdfplumber.pdf.Page) -> list[list[str]]:
 """提取特定表格（MMLU 语言能力对比表）"""
 words = page.extract_words()

 rows_dict = defaultdict(list)
 for w in words:
 y = round(w['top'] / 10) * 10 # 按 10px 分组
 text = w['text'].strip()
 if text and len(text) < 30:
 rows_dict[y].append({'text': text, 'x0': w['x0']})

 table_data = []
 for y in sorted(rows_dict.keys()):
 row_items = sorted(rows_dict[y], key=lambda w: w['x0'])
 texts = [item['text'] for item in row_items]
 x_positions = [item['x0'] for item in row_items]
 x_spread = max(x_positions) - min(x_positions)

 # 判断是否为表格行
 if x_spread > 250 and len(texts) >= 2:
 table_data.append(texts[:3])

 return table_data if len(table_data) >= 10 else []

2.5 图像提取

pyMuPDF 可以直接提取嵌入图片：

def extract_images(page: fitz.Page, output_path: Path) -> None:
 """提取页面中的图片"""
 for img in page.get_images(full=True):
 xref = img[0]
 base_image = page.parent.extract_image(xref)
 img_bytes = base_image["image"]
 ext = base_image["ext"]

 temp_path = output_path.parent / f"temp_{xref}.{ext}"
 with open(temp_path, "wb") as f:
 f.write(img_bytes)

 # 插入 Word
 run.add_picture(str(temp_path), width=Inches(5))
 temp_path.unlink() # 用完删除

2.6 效果

python -m md2latex.pdf2docx demo/sample_paper.pdf -o output.docx

生成的 Word 包含：

按阅读顺序排列的段落
自动识别的标题层级
检测到的表格
页面中的嵌入图片

三、踩坑记录

3.1 LaTeX 公式渲染失败

问题：复杂的 LaTeX 公式（如矩阵、多行公式）转换后 Word 显示异常。

原因：只实现了分数、文本等简单结构，复杂的 \begin{pmatrix}、\begin{align} 等未处理。

解决：

简化 LaTeX 输入，避免使用多行公式
或降级为图片渲染：先用 LaTeX 生成图片，再插入 Word

3.2 表格跨页断开

问题：PDF 中跨页的表格被拆成两个独立表格。

原因：pdfplumber 按页提取，不跨页合并。

解决：维护一个跨页表格 buffer，检测到表头后开始收集，直到遇到非表格内容再写入 Word。

3.3 字体大小与标题级别不匹配

问题：有些 PDF 使用非标准字体，检测到的字体大小与实际视觉大小不符。

原因：PDF 内部字体大小与渲染大小可能不同（缩放因子）。

解决：结合字体名判断（如 “Times-Bold” 通常是标题）和字号双重判断。

3.4 图片尺寸过大

问题：提取的图片在 Word 中显示过大或过小。

原因：未指定尺寸时，python-docx 使用图片原始尺寸。

解决：

run.add_picture(str(img_path), width=Inches(5.0)) # 固定宽度 5 英寸

四、关键代码片段

4.1 插入 OMML 数学公式

def insert_omml_paragraph(doc: Document, latex: str, center: bool = False) -> None:
 """将 LaTeX 公式插入为 Word OMML"""
 para = doc.add_paragraph()
 if center:
 para.alignment = WD_ALIGN_PARAGRAPH.CENTER

 math_para = create_omml_math(latex)
 para._element.append(math_para)

4.2 清理 PDF 提取的文本

def clean_text(text: str, preserve_spaces: bool = False) -> str:
 """清理控制字符"""
 text = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', '', text)

 if preserve_spaces:
 text = text.replace('\r\n', '\n').replace('\r', '\n')
 text = re.sub(r'\n\s*\n', '\n\n', text)
 else:
 text = re.sub(r'\s+', ' ', text)

 return text.strip()

4.3 创建 Word 表格

def create_table(doc: Document, table_data: list[list[str]]) -> None:
 """创建带边框的 Word 表格"""
 max_cols = max(len(row) for row in table_data)
 table = doc.add_table(rows=len(table_data), cols=max_cols)
 table.style = "Table Grid"

 for row_idx, row_data in enumerate(table_data):
 for col_idx, cell_text in enumerate(row_data):
 if col_idx < max_cols:
 cell = table.rows[row_idx].cells[col_idx]
 cell.text = clean_text(cell_text, False)

五、实战项目

完整的实现代码见：kritidocx-demo

kritidocx-demo/
├── md2latex/ # Markdown → Word
│ ├── converter.py # 核心转换逻辑
│ ├── templates/ # HTML 模板
│ └── pdf2docx/ # PDF → Word
└── demo/ # 示例文件

持续更新中…

OMML on Zata-砸它