1.5 代码块与语法高亮

1.5 代码块与语法高亮

行内代码用单反引号包裹，多行代码用三反引号围栏，围栏开头还可以标注语言名触发高亮。写技术文档的人会用得比加粗还多，这节把边角细节一次练完。

行内代码：两个反引号夹一个

用 `npm run build` 触发构建，配置读自 `.env` 文件。
​

行内代码内的所有 Markdown 记号都会失效——星号就是星号，井号就是井号，天然免疫格式干扰。上一节的翻车案例（乘法星号被吞）用行内代码包住就根治了。

一个冷门但救命的知识点：当代码本身含反引号时，用更多反引号做定界符：

``代码里有 ` 反引号，外层用两个``
​

定界符长度只要大于内容里连续反引号的长度即可。

围栏代码块

三个反引号（或三个波浪线 ~~~）单独成行开启和关闭：

```python
def fib(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a
```
````

语言名紧跟开栏反引号（如 `python`、`js`、`yaml`），高亮器据此着色。语言名不影响语义，写错顶多不高亮。展示**无语言文本**时可以用 `text` 或干脆不写。

> ⚠️ 常见坑：代码内容里包含三反引号（比如你正在写一篇讲 Markdown 的教程）时，外层围栏升级为四个反引号。上面那个例子正是这么做的。

## 缩进式代码块：老写法，认识即可

标准语法里，缩进四个空格的行也会被当作代码块。现代写作基本不用它——和嵌套列表的缩进规则打架，编辑器里也没法自动对齐。见到旧文档里的"莫名变成等宽字"基本就是它，把缩进去掉或改成围栏即可。

## 高亮语言怎么选

| 场景 | 建议标注 | 效果 |
| --- | --- | --- |
| 通用伪代码 | `text` | 不高亮，等宽 |
| 命令行操作 | `bash` / `sh` | 命令着色 |
| 配置样例 | `yaml` / `json` / `toml` | 键值着色 |
| 前端片段 | `html` / `css` / `js` | 标签/选择器着色 |
| Markdown 本身 | `markdown` | 符号淡化 |

我的习惯：拿不准就先不写语言名，发布前统一补——多数编辑器对无语言块显示为普通等宽，不会报错。

## 本节要点回顾

- **行内 `单反引号`，多行三反引号围栏，语言名跟在开栏后**。
- **定界符升级规则**：内容含反引号/三反引号时，外层加长。
- **缩进四空格的老式代码块**：不用，但要知道它存在以便读懂旧文档。
- **行内代码是最强的"去格式化"工具**，讲符号本身时优先用它。

## 代码块的内容纪律

代码块的高亮与围栏只是外壳，读者真正消费的是里面的代码。技术文档里代码块的第一纪律：**可运行或可验证**。教程里的示例要么是能原样粘贴执行的完整片段，要么明确标注"节选"并交代省略了什么。最坑读者的写法是"半截代码假装完整"——看起来能跑，实际依赖上下文里没给出的变量，读者复制后报错，对文档的信任立刻清零。命令行示例的纪律是给出预期输出：命令与输出之间用注释分隔，读者执行后能自行比对结果是否符合预期，这比任何文字描述都有说服力。

第二纪律是**最小可复现**。示例代码只保留与要讲的点直接相关的行，无关的错误处理、日志、配置全部删掉。一段三十行的示例只为了演示一个两行的配置写法，读者的注意力成本完全不成比例。第三纪律与提示词有关：占位符统一用尖括号加说明（如 `<你的域名>`），不要用 `xxx`、`foo` 之类看似具体实为占位的写法——读者分不清 `example.com` 是示例还是必须替换的值时，出错率显著上升。团队协作里还可以约定在代码块的第一行注释里写"本块来源与适用版本"，文档迭代时能快速判断哪段示例已随版本过时，这是长生命周期文档里最实用的习惯之一。

## 围栏代码块里的转义真空区

围栏代码块有一个常被误解的性质：**块内是转义真空区**。反斜杠、星号、尖括号都按字面输出，因此不需要也无法转义。这带来一个实际问题——块内无法嵌入 Markdown 记号，想给代码加行内注释式的强调（比如让某一行"高亮出来"），只能依赖平台扩展。常见方案对比：

````markdown
```js
function retry(fn, times = 3) {  // 重点在这行的默认值
  return fn().catch(() => times-- > 0 ? retry(fn, times) : Promise.reject());
}
```
````

标准做法是像上面这样用代码注释承载说明；而一些平台（如 docsify、部分 VuePress 主题）支持 `{1,2}` 行高亮语法或 `// [!code highlight]` 标注，这类都属于方言，换平台即失效。给团队的取舍建议：**说明进注释，强调靠上下文文字**，方言增强只做锦上添花。

波浪线围栏 `~~~` 与反引号围栏还有一个实用分工：当代码内容里出现三反引号但内容外层不想套四层时，可以直接换波浪线开栏，视觉上更干净。两种围栏可以互相嵌套——反引号围栏包波浪线围栏，或反之——这正是"在 Markdown 教程里展示 Markdown 示例"的标准手法。另外注意围栏关闭行的长度必须与开启行一致或更长（四反引号开的栏不能只用三个关），且关闭行后面不能跟内容，否则整块降级为普通段落。

长代码块的阅读体验还有一个容易改进的点：**超过一屏的代码块要给结构路标**。在块内用注释把代码分成两三段并编号，正文叙述引用编号（"见第 2 段的循环"），读者来回滚动时不会迷路。演示输出变化的"前后对照"示例则优先拆成两个独立代码块、块前各加一句"修改前/修改后"，比一大块里塞两版代码可读得多。

> 下一节处理两类"指向外部"的记号：链接与图片。

### 语言别名与高亮失败排查

标注语言名后不高亮，通常不是写错，而是**别名问题**：高亮器（一般是 highlight.js 或 Shiki）认的语言名与你想的不可能完全一致。常见别名差异：`js`/`javascript` 等价、`sh`/`bash`/`shell` 基本等价、`yml` 是 `yaml` 的别名、`dockerfile` 有的平台要求写 `docker`。排查方法是看目标平台所走高亮库的语言列表；文档发布前用无预览环境（如 CI 构建）过一遍，把"本地高亮、线上素颜"的块统一修掉。另一个细节：语言名大小写不敏感，但写成 `Python` 在个别严格的解析器里被当作**代码块元信息**而非语言名处理，统一小写最省心。
​