本文介绍如何使用 Microsoft 开源库 markitdown 将含批注（Comments）的 .docx 文件完整转换为 Markdown，关键在于通过自定义 style_map 启用对 Word 批注的支持。
本文介绍如何使用 microsoft 开源库 `markitdown` 将含批注（comments）的 `.docx` 文件完整转换为 markdown，关键在于通过自定义 `style_map` 启用对 word 批注的支持。
markitdown 是 Microsoft 推出的轻量级 Python 库，用于将 Office 文档（如 .docx）高质量地转换为 Markdown。其底层依赖 mammoth 库完成 DOCX → HTML 的解析，再将 HTML 渲染为 Markdown。但需注意：默认情况下，mammoth 会忽略 Word 中的所有批注（Comments），因此直接调用 MarkItDown().convert() 会导致批注信息完全丢失。
要保留批注，必须显式配置 style_map 参数，告知 mammoth 如何处理批注标记。根据 mammoth 官方文档，Word 批注在 DOCX 的 XML 结构中以 <commentreference></commentreference> 元素表示，对应样式名是 comment-reference。只需为其指定一个 HTML 表示方式（如 <sup></sup> 上标），markitdown 即可将其纳入后续 Markdown 转换流程。
以下是完整、可运行的解决方案：
from markitdown import MarkItDown
# 启用批注支持：将 comment-reference 映射为 <sup> 标签
style_map = "comment-reference => sup"
md = MarkItDown(style_map=style_map)
result = md.convert("my_doc.docx")
with open("my_doc.md", "w", encoding="utf-8") as f:
f.write(result.text_content)</sup>
✅ 效果说明：
Convert Chinese patent PDFs/DOCX/DOCs to structured Markdown. Supports patent publications (A/B/U) and office action documents (审查意见通知书/驳回决定/复审决定书/无效宣告请求审查决定书). Uses MinerU for high-quality OCR text extraction (falls back to Tesseract), Python scripts for
- Word 中的批注（如作者“张三”添加的“此处需核实数据来源”）将被转换为类似
[^1]的上标标记，并在 Markdown 文件末尾自动生成脚注区（如[^1]: 此处需核实数据来源）。 - 若文档含多个批注，
mammoth会自动编号并维护顺序，无需手动干预。
⚠️ 注意事项：
- 必须使用 Python 3.10 或更高版本 ——
markitdown在 3.9 及以下版本存在兼容性问题； -
style_map是字符串格式，不支持字典或列表；多条映射可用换行或分号分隔（如"comment-reference => sup; emphasis => em"）； - 批注内容本身不支持富文本（如加粗/颜色），仅以纯文本形式导出；
- 若需自定义脚注样式（如改为括号内联
（批注：…）），需在转换后对result.text_content进行正则后处理，markitdown本身不提供该钩子。
综上，启用批注仅需一行 style_map 配置，却能显著提升技术文档、审阅稿等场景下的转换完整性。建议在项目初始化时统一设置该参数，避免遗漏。
