Markdown 代码块转 Word 后格式错乱？围栏、缩进与长行排查指南

Markdown 编辑器中的代码块看起来完全正常，转换到 Word 后却可能出现缩进错位、长命令超出页面、语言标签失效，或者代码与后续正文混在一起的问题。

这类问题大多从 Markdown 源文件开始。一个适合转换的代码块，需要完整匹配的围栏、准确的语言标识、稳定的缩进，以及适合固定页面宽度的代码行。

为什么 Markdown 代码块转 Word 后会变形

代码块属于按原样处理的文本区域。正确解析后，星号、下划线、中括号和井号等字符应继续作为代码，而不是被识别成强调、链接或标题。

• 结束围栏缺失，或反引号数量少于开始围栏。
• 语言标签拼写错误，或者混入说明文字。
• Tab 与空格混用。
• URL、令牌、命令或 JSON 字符串过长，无法安全换行。
• 操作说明被写进代码块。
• 文档依赖 IDE 配色，而 Word 无法完全复现。

目标不是让 Word 变成代码编辑器，而是保留代码原文、层级、缩进、可读行宽，以及足够清楚的视觉区分。

使用完整的围栏代码块

围栏代码块以至少三个连续反引号或波浪线开始，并用相同类型的围栏结束。同一个代码块不要混用反引号和波浪线。

推荐写法

```python
def calculate_total(items):
    return sum(item.price for item in items)
```

缺少结束围栏

```python
def calculate_total(items):
    return sum(item.price for item in items)

这里已经是下一段正文。

缺少结束围栏时，后续正文、列表、表格或标题都可能被当成代码。一个遗漏就可能影响 Word 中连续多页内容。

添加准确的语言标签

开始围栏后的第一个单词通常用来标识代码语言。标准语言标识可以帮助转换程序选择语法高亮规则。

语言标识保持简洁。文件名、章节说明和用途介绍应放在代码块外或题注中。

把说明文字放在代码块外

代码块中应只保留需要复制、检查、比较或执行的内容。操作说明、警告和结果解释应使用普通段落。

```bash
请使用管理员权限运行下面的命令：
docker compose up -d
等待所有容器进入健康状态。
```

更清晰的写法是先说明，再单独给出命令：

```bash
docker compose up -d
```

命令执行完成后，再用普通正文说明如何检查容器状态。

统一缩进策略

Tab 没有统一显示宽度。一个编辑器可能显示为两个空格，另一个显示为四个，而 Word 还可能使用不同制表位。

• 遵循目标语言或配置格式的缩进规范。
• 同一个代码块不要混用 Tab 和空格。
• 视觉对齐重要时，将 Tab 统一转换为空格。
• 重点检查 YAML 和 Python，因为缩进会影响实际含义。

在长命令撑破页面之前主动拆行

Word 页面通常比代码编辑器窗口窄。很长的命令、URL、哈希、令牌和镜像名称，可能进入页边距或迫使模板使用过小字号。

docker run --name documentation-service --restart unless-stopped --env-file /opt/docucraftbox/config/production.env -p 127.0.0.1:3001:3001 example/documentation-service:2026.07.18

docker run \
  --name documentation-service \
  --restart unless-stopped \
  --env-file /opt/docucraftbox/config/production.env \
  -p 127.0.0.1:3001:3001 \
  example/documentation-service:2026.07.18

只能按照目标 Shell 或语言支持的规则拆行。错误位置上的换行，可能把原本可执行的命令变成无效命令。

只在确实需要时添加行号

行号适用于代码审查、课堂讲解、审计意见和需要引用具体位置的技术说明。如果读者主要需要复制代码，行号反而可能造成干扰。

Word 文档级行号与代码块内部行号不是同一功能。应确认最终文档只给目标代码区域编号。

不要只依赖语法颜色

语法颜色可能受到模板、Word 版本、转换引擎、打印设置和无障碍模式影响。即使黑白打印，代码也应保持可理解。

• 使用清楚的语言或文件名标签。
• 使用统一等宽字体。
• 保证代码块背景与文字具有足够对比。
• 用题注说明示例用途。
• 需要表达差异时使用 diff 标记或注释。

转换前检查流程

1. 查找每个开始围栏。确认存在匹配的结束围栏。
2. 检查语言标签。使用受支持且简洁的标识。
3. 分离说明与代码。警告和解释放在代码块外。
4. 统一缩进。清理混用的 Tab 和空格。
5. 检查超长行。只在语法允许的位置拆分。
6. 决定是否需要行号。只有读者需要引用行时才添加。
7. 先测试代表性代码块。大文档应先测试最长、最复杂的示例。

在最终 DOCX 中检查代码

常见现象与处理方式

常见问题

最终检查清单