正文

Markdown代码块写法大全：从基础到进阶，解决缩进混乱格式错乱等常见问题

/0 浏览量
1004

Markdown代码块写法大全：从基础到进阶，解决缩进混乱格式错乱等常见问题

先把代码块搞明白

你知道吗？Markdown里最让人头疼的往往不是语法本身，而是那些让人抓狂的缩进问题。我曾经花了一个小时排查为什么代码块渲染不出来，最后发现只是多敲了一个空格或少敲了一个Tab——这种时候真的想摔键盘。

代码块在Markdown里主要有两种形态：行内代码和代码块。行内代码适合在段落里插入简短的技术术语，代码块则是展示完整代码片段的利器。

行内代码：最简单也最容易出错

行内代码用单个反引号包裹，这是Markdown里最基础的用法：

在Python里，`print()`函数可以输出内容到控制台。

渲染效果是这样的：在Python里，print()函数可以输出内容到控制台。

看起来简单对吧？但很多人会在这里栽跟头——如果你的代码本身包含反引号怎么办？比如你想展示一个包含反引号的示例：

在JS里，模板字符串用反引号包裹：`const str = `hello``

这样写会直接报错，因为反引号会提前闭合。解决办法是用两个或更多反引号：

在JS里，模板字符串用反引号包裹：``const str = `hello` ``

渲染效果：在JS里，模板字符串用反引号包裹：const str = `hello`

记住这个原则：代码里有多少个连续的反引号，外层就用比它多一个的反引号包裹。

代码块：三种写法你都知道吗？

代码块有三种写法，分别是缩进式、围栏式和围栏式带语言标识。

缩进式代码块：最不推荐的旧写法

缩进式代码块需要在代码前加四个空格或一个Tab：

    function hello() {
        console.log('Hello, World!');
    }

这种写法的问题很多：

  • 容易被误删，尤其是用空格缩进时，有时候只有三个空格
  • 复制粘贴时经常莫名其妙多出或减少缩进
  • 不支持语言语法高亮
  • 在编辑器里看着就乱，很难对齐

所以我基本不推荐用这种写法，除非你在写纯文本且不想用围栏标记。

围栏式代码块：最主流的做法

围栏式代码块用三个反引号包裹：

```
function hello() {
    console.log('Hello, World!');
}
```

渲染效果如下：

function hello() {
    console.log('Hello, World!');
}

这种写法比缩进式可靠多了，不会因为几个空格的问题导致渲染失败。

围栏式带语言标识：开发者必备

在围栏代码块的开头加上语言名称，可以启用语法高亮：

```javascript
const name = "Agnes";
console.log(`Hello, ${name}!`);
```

渲染效果：

const name = "Agnes";
console.log(`Hello, ${name}!`);

常见的语言标识符包括：python、javascript、java、c++、go、rust、html、css、json、bash、sql 等。

有些平台还支持缩写形式，比如 py、js、sh 等，但不是所有平台都兼容，建议用完整名称更保险。

缩进混乱？这些坑你一定踩过

坑一：围栏前后有空格

很多新手会这样写：

``` python
print("hello")
```

注意看，围栏后面多了一个空格！这会导致语言标识失效，代码块不会高亮，甚至有些地方会直接渲染成纯文本。

正确写法：三个反引号后面紧跟语言名称，中间不要有空格：

```python
print("hello")
```

坑二：代码行首有多余空格

```python
    print("hello")
    print("world")
```

这种情况下，代码会保持缩进，渲染结果：

    print("hello")
    print("world")

有时候这是你故意的（比如展示Python的缩进依赖），但更多时候这是误操作——比如从某个文档复制代码时，不小心带了前面的空格。

解决办法：确保代码第一行紧贴围栏，不要有多余空格。如果确实需要展示缩进，可以在代码前面手动加空格，但要清楚这是你有意为之。

坑三：围栏式代码块嵌套在列表里

这是最容易让人崩溃的场景：

1. 第一步：
```python
print("hello")
  1. 第二步

渲染结果可能会完全乱掉，因为列表的缩进会和代码块的缩进产生冲突。

**解决办法**：在代码块前后加空行，并尽量不用嵌套列表：

```markdown
1. 第一步：

```python
print("hello")
  1. 第二步

或者干脆把代码块移到列表外面单独展示。

### 坑四：代码块里包含反引号

前面说过行内代码的处理方式，但很多人不知道**围栏式代码块里的反引号**该怎么处理。

````markdown
```python
code = "`print('hello')`"
print(code)


这种写法会直接报错，因为代码里的反引号会被当成围栏的结束标记。

**解决办法**：在围栏处使用**四个或更多反引号**：

````markdown
````python
code = "`print('hello')`"
print(code)
```

渲染效果：

code = "`print('hello')`"
print(code)

同理，如果代码里有四个连续反引号，就用五个反引号包围，以此类推。

坑五：代码块后面没有空行

```python
print("hello")
```这段文字没有空行会出错

有些Markdown解析器会对这种写法处理不友好，可能导致后续内容被当成代码的一部分。

正确做法：在代码块前后都加上空行：

```python
print("hello")

这段文字有清晰的分隔。


## 代码块里的特殊字符处理

### 波浪号 ~ 的问题

有些平台支持用波浪号围栏代码块：

````markdown
~~~python
print("hello")
~~~
````

这种写法在某些老旧系统里兼容性更好，但在现代Markdown解析器中，反引号是主流。

### 大括号 {} 和井号 # 的问题

这些字符在代码块里完全没问题，不需要转义。代码块里的内容会被**原样保留**，不会当作Markdown语法处理。

这也是代码块的魅力所在——它是Markdown里的"免死金牌"，里面写什么都不会被渲染成其他格式。

## 进阶技巧：让代码块更专业

### 代码块里展示错误信息

很多时候你需要同时展示代码和运行结果，可以这样做：

````markdown
```python
print("hello")
print("world")

输出：

hello
world


渲染效果：

```python
print("hello")
print("world")
```

**输出：**

```
hello
world
```

### 展示多语言对比

````markdown
**Python:**

```python
print("Hello, World!")
```

**JavaScript:**

```javascript
console.log("Hello, World!");
```

**Go:**

```go
fmt.Println("Hello, World!")
```

这样用户可以直观地看到不同语言的写法差异。

代码块里展示配置文件

```json
{
    "name": "my-project",
    "version": "1.0.0",
    "dependencies": {
        "express": "^4.18.2"
    }
}
```

常见平台的问题与解法

GitHub/GitLab

这两个平台对Markdown代码块的支持都很好，推荐使用围栏式代码块加语言标识。缩进式代码块也能正常渲染，但不建议用。

注意：GitHub的GFM（GitHub Flavored Markdown）对围栏前后空行有要求，最好保持代码块前后各有一个空行。

知乎/掘金/CSDN

国内博客平台对Markdown的支持参差不齐。有些平台会错误地处理代码块里的缩进，导致渲染结果错位。

建议：

  • 尽量用围栏式代码块，少用缩进式
  • 代码块前后加空行
  • 如果平台不支持语言标识，就别加了，加了反而可能渲染异常
  • 长代码可以拆分展示，不要一次性放太多

微信公众号

微信公众号的Markdown支持是最差的之一，很多高级特性都不支持。

解法：

  • 用纯文本+颜色标注代替代码块
  • 或者把代码截图放进去
  • 如果一定要用Markdown，尽量用最简单的围栏式，不加语言标识

VS Code / Typora 等编辑器

本地编辑器的预览通常比较可靠，但还是要注意：

  • 不要用Tab缩进，统一用空格
  • 代码块前后加空行
  • 及时预览，确保渲染效果符合预期

调试代码块问题的实用技巧

当你发现代码块渲染不对时，按以下步骤排查：

第一步：检查围栏

确保围栏是三个半角反引号，不是全角的”`，也不是中文的「」。

第二步：检查语言标识

如果加了语言标识，确认标识名称正确，且围栏和标识之间没有空格。

第三步：检查缩进

代码块里的每一行都不要有多余的前导空格或Tab，除非你确实想要这个缩进。

第四步：检查嵌套

如果代码块在列表、引用或表格里面，尝试把代码块移到外面，或者在代码块前后加空行。

第五步：检查特殊字符

代码块里如果有反引号，用更多数量的围栏包裹。如果有波浪号围栏，确保代码里没有连续三个波浪号。

第六步：检查平台兼容性

有些平台对Markdown的实现不一致，尝试换一个平台粘贴测试，或者查看平台的文档说明。

总结几个核心原则

  1. 永远优先用围栏式代码块，缩进式是历史遗留问题
  2. 围栏和语言标识之间不要有空格
  3. 代码块前后加空行，避免解析器混淆
  4. 代码里有反引号时，增加围栏数量
  5. 不要用Tab缩进，统一用空格
  6. 长代码拆分成多个代码块展示，提升可读性
  7. 平台不兼容时，降级处理，别硬上花哨语法

最后说一句

Markdown代码块虽然看起来简单，但真正用起来的时候，各种坑都能让你怀疑人生。我见过最离谱的一次是一个博主的代码块渲染出来全是乱码，排查半天发现是因为他的编辑器把空格转成了全角空格——这种问题在中文输入法环境下特别容易出现。

记住，好的代码块展示不只是”能跑就行”，而是要让读者看得清楚、复制方便、排版美观。这几个原则做到了，你的文章就已经超越大部分人了。

希望这篇文章能帮你彻底搞定Markdown代码块的问题。如果还有具体场景搞不定，欢迎把代码贴出来，我们一起分析。

-- 展开阅读全文 --