Markdown 代码

代码块是技术文档的灵魂——README、教程、API 文档都离不开它。Markdown 提供了两种写代码的方式：行内的短代码用单反引号，多行代码块用三反引号围栏。这一章把所有相关语法讲透，包括最容易踩坑的"代码块里包含反引号"。

1. 行内代码（Inline Code）

单个反引号包裹的内容会渲染为等宽字体（HTML 的 <code> 标签），常用于变量名、函数名、命令、文件名：

行内代码用单个反引号：`let x = 1` 渲染为等宽字体。

在句子中：调用 `printf("hi")` 函数。

包含反引号的情况：用双反引号包裹
``这里有一个 ` 反引号``

行内代码里所有 Markdown 符号都失效——*、_、# 都会原样显示。这是转义特殊字符的"快捷方式"。

2. 围栏代码块（Fenced Code Block）

三个反引号 ``` 开头和结尾，中间是代码内容。开头那行可以在反引号后面紧跟语言名，触发语法高亮：

```javascript
function hello() {
  console.log("Hello, Markdown!");
}
```

```python
def hello():
    print("Hello, Markdown!")
```

3. 支持的语言标识

常见的语言标识（GitHub、VS Code、PrismJS 都支持）：

围栏后面紧跟语言标识，触发语法高亮：

```javascript / js
```typescript / ts
```python / py
```java
```go / golang
```rust / rs
```c / cpp
```html
```css
```json
```yaml / yml
```bash / sh / shell
```sql
```markdown / md
```text / txt （不高亮，纯文本）

不同引擎支持的语言列表略有差异，但主流语言通用。如果不确定，可以省略语言标识，代码会以纯文本显示（仍然有边框和等宽字体）。

4. 嵌套代码块（代码里有反引号）

当代码内容本身就要展示三反引号时（比如写 Markdown 教程！）——外层用更多反引号：

当代码内容本身包含三反引号时，
外层用 4 个或更多反引号：

````
代码里有 ``` 三反引号
也没问题
````

规则：外层反引号数量必须大于内层。

规则很简单：外层反引号数量必须大于内层最多的一组。四反引号围栏内可以放三反引号；五反引号内可以放四反引号。

5. diff 高亮

展示代码变更时，用 diff 语言标识，- 开头的行变红、+ 开头的行变绿：

```diff
- 删除的行（红色）
+ 新增的行（绿色）
  上下文（默认色）
@@ -1,3 +1,4 @@
```

GitHub、GitLab 支持 diff 语法高亮。

6. 代码块内不需要转义

这是代码块最大的好处：里面所有 Markdown 符号都按字面显示：

代码块内<strong>不需要</strong>转义任何 Markdown 符号：

```
**这不是粗体**，*这不是斜体*
[这不是链接](url)
# 这不是标题
```

代码块内一切原样显示，包括反引号外的符号。

所以当你需要展示一段包含 *、#、[ 等符号的原始内容时，放进代码块是最简单的办法，比逐个转义方便得多。

7. 缩进式代码块（不推荐）

早期 Markdown 还有另一种代码块语法——行首缩进 4 个空格：

    缩进 4 个空格也表示代码块
    这是另一种写法（不推荐）

缺点：
- 不能指定语言
- 不够显眼
- 容易和列表嵌套冲突

这种写法不推荐：不能指定语言、容易和列表嵌套冲突、视觉上不明显。现代文档统一用围栏式。

8. 强调命令的写法

写文档时，$ 开头的代码块表示"这是终端命令"，约定俗成：

这种小约定让读者一眼分辨"该输入什么"和"该写到哪个文件"。

9. 常见坑

小结

代码块是 Markdown 对程序员最友好的特性——记住行内单反引号、块级三反引号、嵌套用更多反引号这三条，就能应对 99% 的场景。下一篇讲表格，把数据组织起来。

← 上一篇 链接与图片

下一篇 表格 →

✈️💬