技能介绍

为什么需要它

Markdown 写文档很顺手，但到了评审、归档、交给非技术同事确认的环节，Word 仍然是绕不开的交付格式。手工复制粘贴的代价是：标题层级、代码块底纹、表格边框、引用块样式全部丢失，中英文字体混排还常常退化成默认宋体。这个技能用一个独立的 Python 脚本 scripts/md_to_docx.py，把「写完 Markdown 就能交稿」变成现实。

它是怎么工作的

核心思路是两步转换：

Markdown → HTML：基于 python-markdown 解析，处理标题、列表、链接、代码块、任务列表等元素；
HTML → .docx：用 python-docx 构建文档，并套用一套偏专业审美的默认样式——标题配色、代码块灰底、表格网格线、引用块边框。

几个关键的实现细节：

CJK 字体：每个 run 都显式设置 w:eastAsia 属性，中日韩字符使用指定字体渲染，而不是回退到默认值；
删除线：python-markdown 本身不支持 ~~text~~，脚本在转换前把它预处理成 <del> 标签；
嵌套列表：自动识别 2 空格缩进并归一化为 4 空格，GFM 风格和标准 Markdown 的嵌套写法都能正确渲染；
图片处理：本地路径相对 Markdown 文件所在目录解析，远程 URL 会临时下载；装有 Pillow 时，小图不会被强行放大到超过原始尺寸；
容错：图片缺失时插入 [Image not found: ...] 占位文本，而不是让整个转换崩溃。

适用边界与注意点

运行环境需要预先装好 python-markdown 和 python-docx，Pillow 是可选依赖，缺失时脚本会优雅降级；
样式是「开箱即用的专业默认值」，想做深度定制需要改脚本本身，而不是调命令行参数；
远程图片每次运行都会重新下载，在无外网或外链不稳定的场景里需要谨慎；
除命令行外，脚本也可以作为库调用：MarkdownToDocx 类提供 convert_file() 与 convert_string() 两个入口，方便嵌入自动化流程。