---
title: "Markdown 的六个渲染陷阱：表格被拆、代码块错位、链接断掉"
date: 2026-11-10
slug: markdown-rendering-pitfalls
canonical: https://kernelranch.com/blog/2026/11/markdown-rendering-pitfalls
markdown_url: https://kernelranch.com/blog/2026/11/markdown-rendering-pitfalls.md
tags: ["markdown", "writing", "documentation", "cheatsheet"]
---Markdown 语法很简单，但"写出来是好的、渲染出来是坏的"的情况不少。下面六个都是真实踩过的，附最小复现和修法。

## 1. 表格单元格里的竖线

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

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

```markdown
| `a \| b` | 管道 |
```

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

## 2. 列表里的代码块

````markdown
1. 第一步：

```bash
echo hi
```
````

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

````markdown
1. 第一步：

   ```bash
   echo hi
   ```
````

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

## 3. front-matter 里的冒号

```yaml
title: 部署：从零到上线
```

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

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

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

## 4. 全角空格与零宽字符

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

检查方法（Windows PowerShell）：

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

## 5. 尖括号被当成 HTML

```markdown
用 <div> 包裹内容
```

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

```markdown
用 `<div>` 包裹内容
```

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

## 6. 链接里的空格与中文

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

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

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

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

## 一份自检清单

| 检查 | 命令或方法 |
|---|---|
| 表格列数是否一致 | 数每行 `\|` 的数量 |
| 代码块围栏是否成对 | 统计 ``` 出现次数，应为偶数 |
| 是否有不可见字符 | 正则搜 `\u3000`、`\u200b`、`\ufeff` |
| front-matter 能否解析 | 用任意 YAML 解析器读一遍 |
| 链接是否可达 | 渲染后点一遍，或跑链接检查脚本 |

## 小结

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

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

## 数据来源与检索时间

检索时间 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/ | 标量中含冒号、井号时的引号要求 |

## 核验说明

- 六个现象都在本机写这批文档时真实遇到过，第 1 条（竖线被拆）在本批 Markdown 的自动改写过程中造成过实际损坏，事后逐篇修复。
- 不同渲染器（GitHub、静态站生成器、编辑器预览）对缩进与尖括号的处理不完全一致，文中给的是多数实现共同的行为；未逐一对每个渲染器做对照测试。