Markdown: Markdown 代码语法与代码块
代码是技术文档的核心——Markdown 提供了优雅的方式来呈现它，让读者既能阅读也能复制运行。
1. 你将学到
- 行内代码的语法和使用场景
- 围栏代码块与语法高亮
- 代码块语言标签的规范写法
- 代码块内的转义和特殊处理
- 在列表和引用中嵌入代码
2. 一个开发者的真实故事
(1) 痛点：读者复制代码后报错
Nina 在技术博客上发布了 Python 教程，读者反馈复制代码运行就报错。调查发现，博客平台的代码块没有语法高亮，逗号和句点看起来一样，有些人把 ( 复制成了 （（全角括号）。更糟的是，有些代码块没有标注语言，导致代码颜色没有区分。
(2) 解法：规范代码块格式
Nina 改用围栏代码块并标注语言标签，所有代码在发布前在真实环境中测试运行一遍。她还添加了"复制代码"按钮。之后读者反馈报错的邮件减少了 90%。她的博客因为代码可复制性高，被多家技术媒体推荐。
3. 行内代码
(1) 基本语法
用单个反引号 ` 包裹文字，表示行内代码：
MARKDOWN
使用 `print()` 函数输出文本。
在终端中运行 `npm install express`。
`<div>` 标签是 HTML 中最基本的容器。
| 场景 | 写法 | 效果 |
|---|---|---|
| 函数名 | 调用 `calculateTotal()` 函数 |
调用 calculateTotal() 函数 |
| 快捷键 | 按 `Ctrl+S` 保存 |
按 Ctrl+S 保存 |
| 文件名 | 编辑 `.env` 文件 |
编辑 .env 文件 |
| 命令 | 运行 `git status` |
运行 git status |
(2) 行内代码中的特殊字符
反引号本身用双反引号包裹：
MARKDOWN
用 `` ` `` 表示反引号字符。
在一段文字中使用 `代码` 和 `` `反引号` ``。
💡 提示： 行内代码主要用于提及函数名、变量名、文件路径、快捷键和简短命令。大段代码请使用代码块。
▶ 示例：行内代码的正确用法
TEXT
📖 仅展示
在 utils/helpers.py 文件中，定义了一个 format_date() 函数。
使用时传入 datetime 对象，返回格式化字符串。
快捷键 F5 刷新页面。
💡 提示： 行内代码中的文字保持原样——即使你用
** 也不会加粗。这确保了代码原文的准确呈现。
4. 围栏代码块
(1) 基本语法
用三个反引号 ``` 包裹代码块，可以指定语言标签实现语法高亮：
MARKDOWN
```python
def greet(name):
return f"Hello, {name}!"
print(greet("Alice"))
```
⚠️ 注意： 代码块前后必须有空行，否则某些解析器可能无法正确识别。这是一条写文档时最容易忽略的规则。
(2) 语言标签的作用
| 标签 | 语言 | 示例文件名 |
|---|---|---|
python |
Python | main.py |
javascript |
JavaScript | app.js |
html |
HTML | index.html |
css |
CSS | style.css |
bash |
终端命令 | （无文件） |
json |
JSON | package.json |
markdown |
Markdown | README.md |
text |
纯文本输出 | （无高亮） |
PYTHON
# Python 代码，有语法高亮
def fibonacci(n):
"""计算斐波那契数列的第 n 项"""
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
print(fibonacci(10)) # 输出 55
5. 缩进代码块
除了围栏式，Markdown 还支持缩进式代码块。行首缩进 4 个空格或 1 个 Tab：
MARKDOWN
这是一段文字。
// 缩进 4 个空格后成为代码块
function hello() {
console.log("Hello!");
}
继续写普通文字。
⚠️ 注意： 缩进代码块不支持语法高亮，也没有语言标签。推荐始终使用围栏代码块（
```），它功能更强大、更清晰。
▶ 示例：围栏代码块 vs 缩进代码块
TEXT
📖 仅展示
围栏代码块使用三个反引号包裹，支持语言标签和语法高亮。
缩进代码块使用行首 4 个空格，兼容性好但不支持语法高亮。
推荐使用围栏代码块。
6. 代码块中的特殊处理
(1) 代码块中转义反引号
如果代码本身包含三个反引号，用更多数量的反引号包裹：
MARKDOWN
````text
```python
print("Hello")
```
````
💡 提示： 外层用
````（四个反引号），内层 ``` 就会被当作普通文字显示。
(2) 长代码换行
MARKDOWN
# 推荐：保持每行在 80 字符以内
const result = await api.getUserData(userId)
.then(data => processData(data))
.catch(error => handleError(error));
# 避免：不换行的超长行
const result = await api.getUserData(userId).then(data => processData(data)).catch(error => handleError(error));
▶ 示例：代码块中的常见错误标记
TEXT
📖 仅展示
❌ 错误写法：
没有语言标签的代码块显示为白底黑字
✅ 正确写法：
标注了 python 语言标签后显示彩色语法高亮
⚠️ 注意： 不加语言标签的代码块会被 Prism.js 等语法高亮工具忽略，显示为白底黑字，不便于阅读。
7. 在列表和引用中嵌入代码
(1) 列表中的代码块
列表中的代码块需要额外缩进 8 个空格或两个 Tab：
MARKDOWN
- 运行测试：
npm test -- --coverage
- 检查格式：
npx eslint src/ --fix
💡 提示： 列表中的代码块也可以用围栏式，但需要在代码块前后空一行并保持缩进一致。
(2) 引用中的代码块
MARKDOWN
> **关键实现：**
>
> ```python
> def process_data(df):
> return df.dropna().groupby("category").sum()
> ```
>
> 以上代码会清洗空值后分组汇总。
8. 完整示例：一份代码文档
TEXT
📖 仅展示
数据处理脚本说明
安装依赖：pip install pandas numpy matplotlib
load_data() 函数：从 CSV 文件加载数据
clean_data() 函数：移除空值和重复行
完整使用流程：
1. 加载数据 - load_data("sales.csv")
2. 清洗 - clean_data(data)
3. 输出统计 - 打印行数和列名
预期效果：一份清晰的技术文档，代码与说明交替呈现，语言标签正确，行内代码与代码块分工明确。
❓ 常见问题
Q 行内代码和代码块怎么选？
A 2-3 个单词内用行内代码；超过一行的代码用代码块。函数名、变量名、文件名、快捷键用行内代码；多行程序、配置、命令用代码块。
Q 代码块为什么不显示语法高亮？
A 最常见原因——没有加语言标签。检查代码块开头是否标注了语言名称如 python、javascript。
Q 代码块内的文字可以用 Markdown 格式吗？
A 不能。代码块内的所有内容都按原始文字显示，星号不会变成加粗，井号不会变成标题。
Q 如何在代码块中显示反引号？
A 用更多数量的反引号作为外层包裹。例如显示三个反引号时用四个反引号包裹即可。
Q 代码块的行首空格会保留吗？
A 会。代码块中的缩进完全保留原样。这是故意的——Python、YAML 等语言依赖缩进。
📖 小节
- 行内代码用单个反引号，代码块用三个反引号包裹
- 代码块必须标注语言标签才能触发语法高亮
- 缩进代码块（4 空格）已不推荐，优先用围栏式
- 列表中的代码块需要额外缩进
- 转义代码块中的反引号用更多反引号包裹
- 代码块的缩进和空白完全保留
📝 作业
-
基础题：写一段 Markdown，包含 3 处行内代码（文件名、函数名、快捷键）和 1 个带语言标签的代码块。
-
进阶题：在你的 Markdown 文档中创建一个嵌套结构——在无序列表项中嵌入一个代码块，在引用块中嵌入一个代码块。
-
挑战题：写一段包含三层反引号嵌套的 Markdown（演示如何在文档中展示代码块的代码块），并用四个反引号包裹以保证正确渲染。
