OmniDoc技术文档转Word，代码块怎么保持整齐
技术文档用 Markdown 写、导出 Word 后，代码缩进错乱、等宽字体丢失、长行被折断是常见问题。本文讲清原因，给出导出前的准备、转换步骤和逐项核对方法。
如果你用 Markdown 写技术文档，最后却要交一份 Word 给评审、客户或同事，代码块通常是首先出问题的地方。缩进变成了空白段落，多行命令被挤成一行，等宽字体变回普通字体，引号还被换成了弯引号。对读者来说，少了一个空格的 Python 缩进或被替换的符号，就可能让整段代码无法运行。
这篇文章写给需要把含代码的技术文档转成 Word 的工程师和技术写作者，包括写 API 说明、部署手册和课程讲义的人。读完后你会知道代码块在转换中为什么会乱，导出前要做哪些准备，怎样完成转换，以及交付前怎样逐项核对。
Markdown 代码转 Word 的难点在于两种格式的假设不同。Markdown 用反引号界定代码，空格和换行原样保留；Word 则默认按段落排版，还会自动替换符号。只要中间环节有一步没处理好，代码的样子就会变。下面的做法不依赖某一款特定软件，适用于大多数转换场景。
Markdown 代码转 Word，怎么保持缩进和等宽不乱？一句话结论
结论是：代码块要在转换前就规范好源文本，转换时选用能保留 Markdown 结构的工具，导出后再逐块核对，而不是导出后再手工修补。
| 你的情况 | 推荐做法 | 原因 |
|---|---|---|
| 代码只有几行，偶尔需要给同事看 | 把代码段手动设为等宽字体放入 Word | 操作简单，不依赖转换 |
| 文档多、代码块多，还要反复更新 | 在 Markdown 源文件中维护，导出 Word 后逐块核对 | 修改源文件后可重新导出，避免重复修版 |
| 代码含大量缩进（Python、YAML、Makefile） | 缩进统一用空格，导出前关闭自动替换 | 制表符和自动转换容易改变层级 |
| 代码行很长（长 URL、JSON、命令参数） | 导出前拆行，或缩小字号、改用横向页面 | 长行折断会打乱阅读和复制 |
| 文档同时含公式、流程图和代码 | 用支持 Markdown 与 Word 往返的编辑器，代码块单独核对 | 只检查图表容易忽略代码 |
开始之前：先确认这几点
- 代码块是否带语言标记。 在开头的三个反引号后写上语言名（如 python、bash），既方便阅读，也便于转换时识别代码范围。没有标记的代码块更容易被当成普通段落，空格和换行可能被合并。
- 缩进用的是空格还是制表符。 同一份代码混用两者，在 Word 中的显示宽度就会不一致。写作阶段统一用空格（常见为 2 或 4 个），可以避免导出后层级错位。
- 代码里有没有会被自动替换的符号。 直角引号、连字符、省略号在 Word 的自动更正下，可能被改成弯引号或长破折号。这类改动在屏幕上不易察觉，但复制到终端时会直接报错。
- 读者是要复制运行，还是只是阅读。 如果读者要把代码粘贴去运行，原始字符比美观更重要，样式应尽量简单；如果只是阅读，可以加浅色底纹和适当行距，让代码段与正文区分开。
- 交付后在什么设备上打开。 Courier New 在 Windows 和 macOS 上较为通用，Consolas 随 Office 安装，但不一定在所有设备上都有。字体缺失时，代码对齐会被打乱，交付前尽量在另一台机器上打开检查。
在 Word 中完成代码块转换的步骤
- 整理 Markdown 源文件，确认每个代码块都有开始和结束的三个反引号，并补上语言标记。
- 删除代码块前后多余的空行，确保每个代码块前后各有一个空行，避免导出后出现大段空白。
- 检查缩进，确认全部使用空格；如发现制表符，用编辑器统一替换为空格，再保存源文件。
- 对超长代码行，先在源文件中按语义拆行，例如在参数之间断开并用续行符连接，避免依赖 Word 自动折行。
- 使用支持 Markdown 与 Word 往返的编辑器打开源文件，例如 UniDoc 网页编辑器（app.unidoc.top），让代码块以原样显示在编辑区。
- 导出为 Word 格式，保存为新文件，不覆盖原始 Markdown 文件，方便之后修改源文件后重新导出。
- 在 Word 中打开导出文件，为代码段统一设置等宽字体和较小字号，并加上浅色段落底纹；中文注释的字体单独设置，避免中文字形缺失。
- 按下一节的检查项逐块核对，确认无误后再交付。
做完后逐项核对
| 检查项 | 怎么看 | 有问题怎么办 |
|---|---|---|
| 缩进层级 | 与源文件逐块对照，重点看 Python、YAML 的层级 | 回到源文件修正缩进，重新导出 |
| 引号和符号 | 查找弯引号和长破折号，尤其是命令和字符串中的 | 关闭自动替换后重新导出；或只在代码段内做查找替换 |
| 字体 | 代码段是否都是等宽字体，中文注释是否显示正常 | 选中代码段统一设置，检查其他设备是否缺字体 |
| 换行和截断 | 长行是否被折断，是否超出页面边界 | 在源文件中拆行，或缩小字号、改用横向页面 |
| 首尾空行 | 代码块上下是否多出空行 | 删除源文件中的多余空行后重新导出 |
| 复制测试 | 从 Word 复制一段代码到终端或编辑器运行 | 若报错，说明有字符被改动，回到前面各项排查 |
📊 核心对比
常见的代码块转 Word 做法有三种，各自适合的场景不同。
| 做法 | 适合场景 | 注意事项 |
|---|---|---|
| 从 Markdown 预览页直接复制 | 只有一两个代码块，且结构简单 | 缩进和符号容易丢失，必须逐块检查 |
| 在 Word 中手动设置等宽字体段落 | 代码较少，不需要频繁更新 | 代码多时维护成本高，源文件变动后要重做 |
| 通过支持 Markdown 的编辑器导出整份 Word | 代码块多、文档需要反复修订 | 导出后仍需核对，源文件规范是前提 |
❓ 常见问题（FAQ）
1. 技术文档用什么工具写比较合适？
取决于读者和交付形式。需要版本管理、频繁修改的文档适合用 Markdown 写源文件；需要给非技术读者审阅或批注的，导出 Word 更方便。挑选时可以看三点：能否保留代码块格式，能否与 Word 往返编辑，能否导出 PDF 或 Word。
2. 代码块导出后出现多余空行怎么办？
通常是源文件中代码块前后空行过多，或段落之间的换行被当成了分段。删除多余空行，确保代码块前后各一个空行，再重新导出即可。
3. 代码里的中文注释显示异常，是什么原因？
多数情况是等宽字体不包含中文字形，或者整段都用了同一种字体。可以为中文注释单独设置中文字体，英文和代码部分使用等宽字体，两者分开设置。
4. 免费的在线转换网站能用来转带代码的文档吗？
可以试，但要重点看三点：文件大小限制、导出文件是否带水印、是否保留代码块的字体和缩进。涉及未公开代码或客户资料时，还要看平台的隐私说明。无论用什么工具，转换后都需要按本文的核对表逐项检查。
📝 总结
Markdown 代码转 Word 的关键，是在源文件阶段就规范语言标记、缩进和长行，转换后再按缩进、符号、字体和换行逐项核对。把这几步固定为流程，代码块在 Word 中就能保持整齐。建议先用一份短文档试跑，确认无误后再用于正式交付。
