Markdown 的六个渲染陷阱：表格被拆、代码块错位、链接断掉

2026-11-10 #markdown#writing#documentation#cheatsheet

Markdown 语法很简单，但"写出来是好的、渲染出来是坏的"的情况不少。下面六个都是真实踩过的，附最小复现和修法。

1. 表格单元格里的竖线

| 命令 | 说明 |
|---|---|
| `a | b` | 管道 |

渲染出来表格会多出一列，因为反引号里的 | 照样被当成列分隔符。修法是转义：

| `a \| b` | 管道 |

这个问题在写 shell 管道、正则、SQL || 拼接时特别常见。

````markdown

echo hi

````

上面的写法会让代码块跳出列表，编号也断掉。正确做法是给代码块加缩进，与列表内容对齐：

````markdown

   echo hi

````

不同渲染器对缩进要求略有差异，但 3 个空格通常安全。

title: 部署：从零到上线

YAML 会把第二个冒号当成分隔符，解析失败或截断。值里含冒号、井号、引号时，一律加引号：

title: '部署：从零到上线'

同理，summary 里出现 # 也要引号包裹，否则被当成注释。

从网页或 IDE 复制中文内容时，很容易带进全角空格（U+3000）或零宽空格（U+200B）。它们肉眼看不见，但会让 grep 搜不到、代码块复制出去报错。

检查方法（Windows PowerShell）：

Select-String -Path .\doc.md -Pattern "[\u3000\u200b\ufeff]"

用 <div> 包裹内容

很多渲染器会把 <div> 当 HTML 标签吃掉，读者看到的只有"用包裹内容"。要么放进反引号，要么转义：

用 `<div>` 包裹内容

写前端文档、XML 配置、泛型（List<T>）时都会碰到。

[文档](my notes/readme.md)

路径含空格会断链。两种修法：

[文档](<my notes/readme.md>)
[文档](my%20notes/readme.md)

尖括号写法更易读，但并非所有解析器都支持，GitHub 与多数静态站生成器支持。

六个问题里，前三个（竖线、缩进、冒号）属于语法层面的坑，后三个（不可见字符、尖括号、空格）属于"看得见但想不到"。它们的共同点是：源文件看起来完全正常。

最省事的防线是发布前跑一次机器检查：围栏配平、表格列数、不可见字符。这三项能挡掉大部分渲染事故，人工只需检查内容本身。

检索时间 2026-11-10。

来源	URL	对应数据
CommonMark 规范	https://spec.commonmark.org/0.31.2/	表格外的块级语法、列表与代码块的缩进规则、HTML 块的处理方式
GitHub Docs《Basic writing and formatting syntax》	https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax	表格中竖线的转义、代码块围栏、链接中空格的写法
YAML 规范 1.2	https://yaml.org/spec/1.2.2/	标量中含冒号、井号时的引号要求