代码块
代码块是技术文档的核心元素。Markdown 提供行内代码和代码块两种形式，支持语法高亮显示。
行内代码
行内代码用于在句子中嵌入短代码片段，使用反引号包围。
基本语法
使用 `git status` 查看仓库状态。
渲染效果：使用 git status 查看仓库状态。
包含反引号的代码
如果代码本身包含反引号，使用双反引号包围：
``代码中有 ` 反引号``
渲染效果：代码中有 ` 反引号
转义特殊字符
行内代码内的特殊字符会被原样显示，不会被解析为 Markdown 语法：
在代码中 `**不会** 变成粗体`。
渲染效果：在代码中 **不会** 变成粗体。
代码块
代码块用于展示多行代码，有围栏式和缩进式两种写法。
围栏式代码块
使用三个反引号或波浪线包围代码：
```
function hello() {
console.log("Hello, World!");
}
```
或使用波浪线：
~~~
function hello() {
console.log("Hello, World!");
}
~~~
两种写法效果相同。
语法高亮
在开头的反引号后指定语言，实现语法高亮：
```javascript
function hello() {
console.log("Hello, World!");
}
```
渲染效果：
function hello() {
console.log("Hello, World!");
}
支持的语言
常见的语言标识符：
| 语言 | 标识符 |
|---|---|
| JavaScript | javascript, js |
| Python | python, py |
| Java | java |
| C | c |
| C++ | cpp, c++ |
| Go | go |
| Rust | rust |
| HTML | html |
| CSS | css |
| SQL | sql |
| Shell | shell, bash, sh |
| JSON | json |
| YAML | yaml, yml |
| Markdown | markdown, md |
显示文件名
部分渲染器支持在语言标识后添加文件名：
```javascript hello.js
function hello() {
console.log("Hello, World!");
}
```
或使用注释方式：
```javascript
// hello.js
function hello() {
console.log("Hello, World!");
}
```
高亮特定行
部分渲染器支持高亮特定行：
```javascript {2,4-5}
function hello() {
console.log("Hello, World!"); // 高亮
return;
console.log("这行也高亮");
console.log("这行也高亮");
}
```
缩进式代码块
缩进式是原始 Markdown 语法，每行缩进 4 个空格或 1 个制表符：
function hello() {
console.log("Hello, World!");
}
这种写法不支持语法高亮，现在较少使用。
代码块中的反引号
当代码块内容包含三个反引号时，可以使用更多反引号包围：
````markdown
```
这里有三个反引号
```
````
外层使用四个反引号，内层三个反引号会被正确显示。
代码块与其他元素
代码块中的空行
代码块中的空行会被保留：
```
第一行
第三行（中间有空行）
```
代码块与列表
在列表中插入代码块需要额外缩进：
1. 第一步，创建文件：
echo "hello" > hello.txt
2. 第二步，查看内容：
cat hello.txt
注意代码块需要缩进 8 个空格（列表缩进 4 个 + 代码块缩进 4 个）。
代码块中的 Markdown
代码块内的内容会被原样显示，Markdown 语法不会生效：
```
# 这不是标题
**这不是粗体**
[这不是链接](https://example.com)
```
代码注释技巧
行内注释
在代码中添加注释说明：
```python
def calculate(x, y):
# 计算两数之和
return x + y
```
代码块后的说明
代码块后添加详细解释：
```python
def calculate(x, y):
return x + y
```
上面的函数接收两个参数 `x` 和 `y`，返回它们的和。
对比示例
展示正确和错误的写法：
正确写法：
```python
def hello():
print("Hello")
```
错误写法：
```python
def hello()
print("Hello") # 缺少冒号
```
Diff 格式
展示代码变更时，使用 diff 语言标识：
```diff
function hello() {
- console.log("Hello");
+ console.log("Hello, World!");
}
```
渲染效果：
function hello() {
- console.log("Hello");
+ console.log("Hello, World!");
}
- 开头的行显示为红色（删除），+ 开头的行显示为绿色（添加）。
终端命令
展示终端命令时，使用 shell 或 bash：
```bash
# 安装依赖
npm install
# 启动项目
npm start
```
命令前加 $ 符号表示命令行提示符：
```bash
$ npm install
$ npm start
```
最佳实践
选择正确的语言标识
使用正确的语言标识可以获得更好的语法高亮：
推荐：
```json
{"name": "markdown"}
```
不推荐：
```
{"name": "markdown"}
```
保持代码简洁
代码示例应该简洁明了，突出重点：
```python
# 好的示例：简洁清晰
def add(a, b):
return a + b
result = add(1, 2)
print(result) # 输出: 3
```
添加必要注释
代码中的注释应该解释"为什么"而非"是什么"：
```python
# 使用二分查找提高搜索效率，时间复杂度 O(log n)
def binary_search(arr, target):
left, right = 0, len(arr) - 1
while left <= right:
mid = (left + right) // 2
if arr[mid] == target:
return mid
elif arr[mid] < target:
left = mid + 1
else:
right = mid - 1
return -1
```
小结
本章学习了代码块的使用方法：
- 行内代码：使用反引号包围短代码
- 代码块：使用三个反引号包围多行代码
- 语法高亮：指定语言获得更好的显示效果
- Diff 格式：展示代码变更
- 最佳实践：简洁、有注释、正确的语言标识
练习
- 创建一个包含行内代码的段落
- 创建一个带语法高亮的 JavaScript 代码块
- 创建一个展示代码变更的 diff 代码块
- 在列表中插入代码块