Pandoc中.docx输出文档标题与副标题样式丢失问题分析

问题背景

在使用Pandoc生成.docx格式文档时，用户发现从3.1.12版本升级到3.5版本后，自定义的标题(Title)和副标题(Subtitle)样式在输出文档中失效。虽然内容正确显示，但样式被还原为Word默认格式，而非用户通过reference.docx模板定义的样式。

问题重现与测试

多位用户在不同环境下重现了此问题：

1. 用户创建自定义reference.docx模板，修改了Title和Subtitle样式（如设置背景色、字体颜色等）
2. 使用Pandoc 3.1.12时，输出文档能正确应用自定义样式
3. 升级到Pandoc 3.5后，输出文档的标题和副标题恢复为默认样式
4. 测试发现该问题从Pandoc 3.2.1版本开始出现

技术分析

样式识别机制变更

Pandoc在3.2版本前后对样式识别机制进行了调整：

1. 早期版本通过styleId识别样式
2. 3.1.12.2版本后改为通过样式名称(name)识别（因styleId会随Word本地化而变化）
3. 3.2.1版本引入了OpenXML模板支持

本地化问题

测试发现，当使用非英语版Word时：

1. Word界面显示的样式名称会被本地化（如德文版显示"Titel"而非"Title"）
2. 但实际保存的.docx文件中，样式名称仍为英文（如"Title"）
3. 不同版本Pandoc对本地化名称的处理存在差异

样式继承关系

Pandoc 3.2.1对默认reference.docx进行了清理：

1. 副标题样式改为继承自Title而非Normal
2. 移除了副标题的默认颜色设置
3. 增加了"Title Char"和"Subtitle Char"字符样式

解决方案

临时解决方案

1. 降级使用Pandoc 3.1.12或3.2版本
2. 手动修改.docx文件中的styleId为"Title"和"Subtitle"

长期建议

1. 确保reference.docx中的样式使用标准英文名称
2. 修改样式时直接编辑Word内置的Title和Subtitle样式，而非创建新样式
3. 检查并设置"Title Char"和"Subtitle Char"字符样式

技术总结

该问题本质上是Pandoc样式识别机制与Word本地化特性的兼容性问题。随着Pandoc对OpenXML模板支持的增强，样式处理逻辑发生了变化，导致在某些环境下无法正确匹配用户自定义样式。建议用户在跨版本升级时，特别注意样式相关的变更说明，并在非英语环境下测试输出结果。

对于开发者而言，这提示我们需要更全面地考虑国际化场景下的样式处理逻辑，确保在不同本地化环境下都能正确识别和应用用户定义的样式模板。