Markdown转Word使用教程

一、功能介绍

Markdown转Word用于把一个文件夹中的 Markdown 文档批量转换为 Word DOCX 文件。适合将说明文档、知识库文章、课程资料或项目文档整理成可在 Microsoft Word、WPS Office 等软件中打开的文件。

插件支持：

• 识别 .md 和 .markdown 文件，扩展名不区分大小写。

• 扫描当前文件夹，或同时扫描所有子文件夹。

• 拖入 Markdown 文件或文件夹后加载。

• 按顺序逐个转换，并显示等待中、处理中、已完成、失败和已取消状态。

• 暂停领取下一份文档、继续转换或取消整个批次。

• 在输出文件夹中保留来源文件的相对目录结构。

• 转换常用标题、粗体、斜体、列表、任务列表、表格、引用、代码块、链接、脚注、基础公式和本地图片。

插件不会修改或删除原 Markdown 文件。

二、使用前准备

1. 安装并启用“Markdown转Word”插件。

2. 确保插件所需的 Pandoc 资源已随插件正确安装。正常从应用商店安装时，工具箱会处理已绑定资源。

3. 准备一个存放 Markdown 文件的来源文件夹。

4. 准备一个用于保存 Word 文件的输出文件夹。建议不要把输出文件夹放在来源文件夹内部，避免后续整理时混淆。

5. 如果 Markdown 使用本地图片，请确认图片文件仍位于 Markdown 引用的相对位置。

如果开始转换时提示“未找到后台绑定的 pandoc.exe 资源”，说明插件资源尚未正确绑定或下载，请联系软件管理员处理后重试。

三、界面说明

1. Markdown文件夹

选择来源文件夹。插件只读取其中的 .md 和 .markdown 文件。

可以使用以下任一方式设置：

• 点击右侧“选择”按钮，在系统窗口中选择文件夹。

• 把来源文件夹拖到输入区域。

• 把一个或多个 Markdown 文件拖到文件列表区域，插件会按这些文件的共同目录加载。

2. Word保存文件夹

选择生成 DOCX 文件的保存位置。可以点击“选择”，也可以把目标文件夹拖到输出区域。

3. 包含子文件夹

• 关闭：只加载 Markdown 文件夹第一层中的文件。

• 开启：同时加载所有下级文件夹中的 Markdown 文件。

切换后会重新扫描当前来源文件夹。

4. 操作按钮

• 加载文件：重新扫描当前来源文件夹。

• 开始转换：按文件列表顺序逐个生成 DOCX。

• 暂停：当前正在转换的文件继续完成，完成后不再领取下一份文件。

• 继续：从等待队列继续转换。

• 取消：终止当前 Pandoc 进程，并把尚未完成的文件标记为“已取消”。

• 清空：清空当前文件列表，不删除磁盘中的任何文件。

5. 文件列表与状态

列表显示文件的相对路径、处理进度和状态。顶部标签可以筛选全部、等待中、成功、失败和已取消文件。右键单个列表项可在任务未运行时将其从列表移除。

四、标准操作步骤

1. 打开“Markdown转Word”。

2. 在“Markdown文件夹”处选择来源文件夹。

3. 根据需要开启或关闭“包含子文件夹”。

4. 检查文件列表，确认待转换文档完整且没有误选。

5. 在“Word保存文件夹”处选择输出位置。

6. 点击“开始转换”。

7. 等待列表中的文件变为“已完成”。

8. 打开输出文件夹，使用 Word 或 WPS 检查生成结果。

转换过程中可以暂停、继续或取消。任务运行时返回插件列表、切换插件或退出工具箱，工具箱会提示仍有未完成任务；确认离开后会强制终止当前任务。

五、输入与输出规则

支持的输入

• .md

• .markdown

• 大小写扩展名均可，例如 .MD、.MARKDOWN

输出文件名

扩展名会改为 .docx，原文件名保持不变：

来源：教程.md
输出：教程.docx

子目录规则

开启“包含子文件夹”后，输出目录会保留相对结构：

来源文件夹\产品\安装说明.markdown
Word保存文件夹\产品\安装说明.docx

同名文件规则

如果输出位置已经存在同名 DOCX，插件会在开始前显示覆盖确认。只有点击“确认覆盖”才会继续。

转换先写入临时 DOCX，并验证文件结构后再替换最终文件。因此：

• 转换成功时，同名旧 DOCX 被新文件替换。

• 转换失败或取消时，已有 DOCX 保持不变。

• 说明.md 与 说明.markdown 会生成同一个 说明.docx，两者不能放在同一批次中；插件会拒绝启动并提示冲突。

六、内容支持与限制

常用内容

Pandoc 通常可以转换以下 Markdown 内容：

• 多级标题和正文段落

• 粗体、斜体、删除线等常用行内格式

• 有序列表、无序列表和任务列表

• 表格、引用和代码块

• 超链接和脚注

• $...$ 或 $$...$$ 形式的基础数学公式

• 本地相对图片和本地绝对图片

本地图片

推荐把图片放在 Markdown 文件附近并使用相对路径，例如：

![产品界面](images/screenshot.png)

转换时插件以每个 Markdown 文件所在目录为本地资源查找基准。图片文件缺失、路径写错或没有读取权限时，该文件可能转换失败或图片无法写入 Word。

远程内容

首版不保证下载或嵌入网络图片。请先把图片保存到本地，再改为本地路径。普通网页链接仍可作为超链接写入 Word。

排版差异

Markdown 与 Word 的排版模型不同。复杂 HTML、自定义 CSS、特定 Markdown 编辑器扩展、动态图、脚本和交互组件可能无法原样转换。生成后应抽查标题层级、表格宽度、公式、代码块和图片大小。

七、实际示例

来源目录：

D:\文档\知识库
├─ 首页.md
└─ 使用说明
   ├─ 安装.md
   └─ images
      └─ setup.png

输出目录选择 D:\文档\Word结果，并开启“包含子文件夹”。转换后得到：

D:\文档\Word结果
├─ 首页.docx
└─ 使用说明
   └─ 安装.docx

安装.md 中引用的 images/setup.png 会按 Markdown 文件所在目录查找并嵌入 DOCX；图片原文件不会复制到输出目录。

八、常见问题

1. 文件列表为空

检查以下项目：

• 是否选择了正确来源文件夹。

• 文件扩展名是否为 .md 或 .markdown。

• 文件是否只位于子文件夹，而“包含子文件夹”尚未开启。

• 当前账号是否有来源文件夹读取权限。

2. 提示缺少 Pandoc

插件依赖后台绑定的 pandoc.exe，不会使用系统 PATH 中自行安装的 Pandoc，也不能选择任意 EXE。请让软件管理员检查插件资源绑定与下载状态。

3. 单个文件失败，后面的文件是否继续

会。单个文件失败会记录错误，队列继续处理后续文件。把鼠标移到失败状态或进度区域可查看错误说明。

4. 为什么暂停后当前文件仍在处理

暂停只阻止领取下一份文件，不中断当前转换。这可以避免当前 DOCX 写到一半。当前文件完成后，队列保持暂停。

5. 为什么开始前要求确认覆盖

输出目录中已有同名 DOCX。确认后才会覆盖；取消确认不会启动任何转换。

6. 本地图片没有显示

检查 Markdown 中的图片路径、文件是否存在、大小写是否一致以及读取权限。建议使用相对于 Markdown 文件的路径。

7. Word 排版与 Markdown 预览不同

这是两种格式的排版规则差异。Pandoc 会转换文档结构，但不会复制 Markdown 编辑器的主题或自定义 CSS。请在 Word 中进行最终排版检查。

九、风险与注意事项

• 覆盖确认后，同名 DOCX 会被新结果替换。重要文件请先备份。

• 不要在转换时移动、改名或删除来源 Markdown、本地图片、输出目录或 Pandoc 资源。

• 取消、强制离开或退出工具箱会终止当前转换，未完成文件不会生成可用结果。

• 处理大量文件前，建议先用少量代表性文档验证表格、公式、代码块和图片效果。

• 插件只处理本机文件，不提供在线同步、多人协作或云端转换功能。