MarkDown转Word

要解决的具体问题

在撰写本地技术文章或笔记时，Markdown 通常是首选格式，但在需要交付或存档的场景下，往往仍需将其转换为标准的 Word 文档（.docx 或 .doc）。

当输入源是 Obsidian 或微信公众号导出的 Markdown 时，转换经常遇到格式崩坏：

• 排版错乱：Markdown 列表前若缺少空行，转成 Word 后无法正确识别为列表样式。
• 无效占位符：文章中未上传成功的图片链接（如 ![Uploading file...]()）会在 Word 中生成难看的空标签。
• 元数据丢失：文件头部的 YAML frontmatter（标题、作者、日期）难以自动映射为 Word 的文档属性。

核心能力与关键步骤

该技能通过调用内置脚本与 Pandoc，将 .md 源文件转换为结构良好的 Word 文档，输出路径通常为 output/doc/。

脚本在转换过程中重点处理了以下细节：

• 元数据保留：解析 YAML frontmatter，将其提取为 Word 文档的标题块和核心元数据属性。
• 图片过滤与嵌入：在转换前剔除空的图片节点节点，仅保留有效本地或远程图片并嵌入文档。
• 列表容错：利用 pandoc 的 lists_without_preceding_blankline 扩展语法，确保源文件缺少空行的列表也能被正确渲染。

转换后的执行流程并非一步了之，脚本会返回一个 JSON 摘要，其中包含渲染状态。如果 rendered_docx 或 rendered_doc 标记为 false，则需要排查原因并重新执行。

验证与渲染检查

为了确保转换质量，脚本内部执行了多项校验：

• 验证 .docx 的 ZIP 文件结构完整性。
• 提取纯文本并进行内容完整性抽查（涵盖开头、中部和结尾内容）。
• 若系统安装了 LibreOffice，会自动将 .docx 转换为 .doc，并渲染为 PDF 以供视觉检查。

如果对版面质量有较高要求，可以重新运行脚本并使用 --keep-render 参数，脚本会生成一张分页预览图（Contact Sheet），方便直接检查每一页的渲染效果。

适用边界与注意点

• 依赖环境：需要本地安装 Pandoc。若需生成旧版 .doc 文件或使用 PDF 预览功能，则必须安装 LibreOffice。
• 格式选项：默认会同时尝试生成 .docx 与 .doc。如果仅需 .docx，可在命令中添加 --no-doc 参数。
• 占位符处理：脚本会主动移除空的上传占位符，这意味着那些无法访问的损坏图片链接不会出现在最终交付的文档中。