第 6 章：代码

技术文档中，代码示例是最核心的内容。Markdown 提供了优雅的代码展示方式，让你的技术文档真正「专业」。

---

学习目标

• 掌握行内代码与代码块的语法
• 熟练使用语法高亮（指定语言）
• 了解代码块内特殊字符的处理
• 学会在代码块中书写 Markdown 语法的转义技巧

---

6.1 行内代码

用单反引号（`）包裹：

请使用 `console.log()` 输出调试信息。

配置文件路径为 `/etc/nginx/nginx.conf`。

渲染：请使用 console.log() 输出调试信息。配置文件路径为 /etc/nginx/nginx.conf。

何时使用行内代码

✅ 应该使用	❌ 不应使用
变量名、函数名	普通英文词汇
文件路径	强调某个概念（用粗体）
命令名称	书名、文章标题（用斜体或链接）
配置项名称	不涉及代码的普通文本
端口号、版本号	日期、人名等元数据

行内代码中包含反引号

如果代码本身包含反引号，用双反引号包裹：

`` 这里有一个 ` 反引号 ``

渲染：这里有一个 ` 反引号

---

6.2 代码块（Fenced Code Blocks）

用三个反引号（```）或三个波浪线（~~~）包裹多行代码：

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

语法解析

```语言标识符
代码内容

- **开头三个反引号** + 可选的语言名称
- **代码内容**
- **结尾三个反引号**（独立一行）

> 推荐使用反引号 `` ``` `` 而非波浪线 `~~~`，这是更通用的写法。

---

## 6.3 语法高亮

在开头的三个反引号后面指定语言名称，解析器会自动应用该语言的语法高亮：

```python
def greet(name):
    """向用户打招呼"""
    return f"Hello, {name}!"

const greet = (name) => {
  // 向用户打招呼
  return `Hello, ${name}!`;
};

server:
  port: 8080
  host: 0.0.0.0
  database:
    url: jdbc:mysql://localhost:3306/mydb

# 安装依赖
npm install

# 启动开发服务器
npm run dev

常用语言标识符

语言	标识符
Python	python 或 py
JavaScript	javascript 或 js
TypeScript	typescript 或 ts
Java	java
Go	go
Rust	rust
C / C++	c / cpp
HTML	html
CSS	css
JSON	json
YAML	yaml 或 yml
SQL	sql
Shell / Bash	bash 或 sh
Dockerfile	dockerfile
Markdown	markdown 或 md
纯文本	text 或不写

---

6.4 代码块的实践技巧

在 Markdown 中书写代码块示例

当你的代码示例本身要展示 Markdown 语法时（例如你在写一本 Markdown 教程），需要做转义：

```markdown
# 这是一级标题

这是**粗体**文字。
```

如果要在代码块里展示「三个反引号」，外层用更多反引号：

````markdown
```python
print("Hello")
```
````

💡 技巧：外层反引号数量 > 内层反引号数量即可。

代码块中的空白行

代码块内的空行不需要特殊处理，直接留空即可：

def process_data(data):
    """处理数据"""

    # 前面的空行是正常的代码风格
    if not data:
        return None

    return data.strip()

代码块标题（部分平台支持）

部分 Markdown 编辑器支持给代码块添加标题：

```python title="fibonacci.py"
def fib(n):
    return n if n <= 1 else fib(n-1) + fib(n-2)
```

⚠️ 代码块标题不是 GFM 标准语法，在 GitHub 上可能不生效。如需在 GitHub 上展示文件名，建议用注释：

# fibonacci.py
def fib(n):
    return n if n <= 1 else fib(n-1) + fib(n-2)

---

6.5 代码块 vs 列表中的代码块

在列表中嵌套代码块，需要比列表多缩进：

1.  安装依赖：

    ```bash
    npm install
    ```

2.  启动服务：

    ```bash
    npm start
    ```

---

6.6 代码块的常见错误

错误 1：忘记关闭代码块

```python
def hello():
    print("Hello")

这是正文了，但解析器可能还在等 ` ``` `

错误 2：代码块内有冲突的 ``` 序列

如果代码内容包含三个反引号，外层用更多反引号包裹。

错误 3：语言标识符后有空格

``` python     ← 错误：空格可能导致高亮失效
```python      ← 正确

错误 4：行内代码中包含反引号未处理

`npm run `build``     ← 错误：反引号冲突
`` npm run `build` `` ← 正确：用双反引号包裹

---

6.7 语法速查

语法	写法	说明
行内代码	`代码`	单反引号包裹
含反引号的行内代码	含反引号	双反引号包裹
代码块	``` + 语言 + 代码 + ```	三反引号，推荐
语法高亮	```python	指定语言标识符
纯文本代码块	```text 或 ```	不指定语言
代码块中的 Markdown	外层更多反引号	````markdown

---

本章小结

要点	说明
行内代码	` 包裹，适合短代码片段、文件名、命令
代码块	``` 包裹多行代码
语法高亮	```language 指定语言
嵌套展示	外层反引号 > 内层反引号
常见错误	忘关闭、语言后空格、反引号冲突

---

下一章预告

代码块让你的文档有了「硬核」内容。但如果要展示结构化数据呢？接下来学习 Markdown 中「最难掌握但又最实用」的语法——表格。

👉 第 7 章：表格