正文

Markdown代码块缩进错一位全文乱掉程序员亲测4种正确写法GitHub文档一键排版

/0 浏览量
0826

Markdown代码块缩进错一位全文乱掉程序员亲测4种正确写法GitHub文档一键排版

前两天加班改需求，顺手给团队写了一份接口文档。代码块写得正顺手，一预览——全乱了。标题缩进没了，列表变成了怪异的横线，连我精心排版的表格都跑到了标题上面。

朋友看到后调侃：”你这文档是写给外星人看的吧？”

说实话，当时我内心是崩溃的。作为写了五年代码的程序员，Markdown用得挺溜，但代码块缩进这件事，真的栽过不少跟头。今天就把我踩过的坑、总结出的4种正确写法，以及GitHub文档一键排版技巧，全部分享出来。如果你也写过Markdown文档，相信这篇文章能帮你省下不少调试时间。

为什么代码块缩进总出问题？

先搞清楚问题出在哪，再谈解决。

Markdown本身是基于纯文本的标记语言，它的解析逻辑是按行处理的。代码块的特殊之处在于——它需要”保留原文格式”，包括空格、缩进、换行。但问题来了：

Markdown解析器怎么知道你这段是代码，而不是普通文字？

答案是：通过缩进或围栏。但正是这两种方式，让很多人踩坑。

举个例子，你写了一段Python代码：

```python
def hello():
    print("你好")
    if __name__ == "__main__":
        hello()


看着没问题对吧？但如果你在实际编辑时，不小心在围栏前面加了几个空格，或者围栏内的代码没有按正确缩进对齐，解析器就会懵——它不知道该把这段当代码，还是当正文。

更坑的是，**不同平台的Markdown解析器，对缩进的处理规则还不完全一样**。你在本地编辑器里看着正常，推到GitHub上就变形了。这就是为什么很多人会吐槽："我的文档在本地没问题，怎么一上传就乱了？"

所以，代码块缩进问题，本质上是个**规则理解+环境一致性**的问题。下面我来讲4种我亲测有效的正确写法。

---

## 第一种写法：围栏代码块（Fenced Code Block）——最主流也最容易踩坑

围栏代码块，是目前使用最广泛的写法。用三个反引号（```）或三个波浪号（~~~）把代码包起来。

### 基本语法

```markdown
```语言名
代码内容


或者不用语言名也行：

```markdown

纯代码内容

实际例子

给你看一个我之前写过的接口文档片段：

## 用户登录接口

请求方法：POST
请求路径：/api/v1/login

### 请求参数

```json
{
  "username": "string",
  "password": "string",
  "remember": false
}

响应示例

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}


这个看起来挺正常，对吧？但问题出在哪？

**问题出在围栏前后的空白行和缩进。**

如果你把围栏前面加了空格，比如：

```markdown
  ```json
  {
    "username": "zhangsan"
  }


有些解析器会认为这是**代码块里的代码**，而不是一个围栏包裹的代码块。结果就是你看到的"全文乱掉"——文档结构被破坏，标题、列表全跟着跑偏。

### 正确姿势

围栏代码块的**三个反引号必须顶格写**，不能有任何缩进。代码内容内部的缩进，是你代码本身的缩进，跟Markdown解析器无关。

```markdown
```json
{
  "username": "zhangsan",
  "password": "123456"
}


注意看：围栏（```）是顶格的，但代码内部的 `{` 和 `}` 是对齐的，这个缩进是代码本身的，不是Markdown语法。

### 一个容易忽略的细节：语言名后面可以跟参数

比如你想让代码高亮显示行号，或者指定起始行号：

```markdown
```python:example.py
# 这是第1行
def main():
    print("Hello")

if __name__ == "__main__":
    main()


再比如GitHub Flavoured Markdown支持用 `~` 来代替 ```` ``` ````，效果一样：

```markdown
~~~python
def hello():
    print("Hello, World!")
~~~

这个细节很多教程不讲，但我发现用波浪号有时候比反引号更顺手，尤其是当你的代码里包含反引号的时候——比如写Markdown语法的示例代码，这时候用波浪号围栏就不会冲突。

第二种写法：缩进代码块（Indented Code Block）——老派但偶尔有用

这是Markdown最原始的代码块写法：在代码前面加四个空格或一个制表符。

基本语法

    这是一段代码
    它有四空格的缩进
    解析器会把它当作代码块

实际例子

假设你在写一个Shell脚本的教程：

## 快速部署脚本

下面这段脚本可以将应用部署到服务器上：

    #!/bin/bash
    set -e
    
    echo "开始部署..."
    docker-compose up -d
    echo "部署完成，请访问 http://your-domain.com"

这样写，渲染出来的效果就是一个灰色的代码块，不会有语言高亮（因为不知道是什么语言），但代码格式会被保留。

为什么现在不太推荐这种写法？

说实话，缩进代码块有个致命缺陷：它跟列表会冲突。

比如你想写一个带编号的步骤，里面还插了一段代码：

1. 第一步：安装依赖
2. 第二步：运行代码
    npm start
3. 第三步：测试

问题来了——那个四空格的代码行，会被解析器认为是属于第二点的子列表，而不是独立的代码块。结果就是你看到的那种”乱掉”的效果：代码缩进去了，列表编号断了，格式全乱。

我在GitHub上看过不少老文档，里面混杂了大量缩进代码块，阅读体验很差。所以我个人不推荐在新文档中使用这种写法，除非你在写那种纯文本风格的Markdown，不需要语法高亮。

一个例外场景

如果你在写内联代码的对比，比如想展示一段代码在不同语言里的写法，缩进代码块有时候会派上用场。比如：

### Hello World 的多语言写法

    // JavaScript
    console.log("Hello World");
    
    # Python
    print("Hello World")
    
    # Go
    fmt.Println("Hello World")

这种场景下，因为不需要列表结构，缩进代码块倒是挺清爽的。不过说实话，这种需求用围栏代码块配合语言名更好看，所以我个人还是偏向围栏。

第三种写法：HTML标签代码块——最稳定但也最麻烦

在Markdown里直接嵌HTML，代码块可以用 <pre><code> 标签。

基本语法

<pre><code class="language-python">
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
</code></pre>

实际例子

## 递归算法示例

<pre><code class="language-java">
public class Fibonacci {
    public static long fib(int n) {
        if (n <= 1) return n;
        return fib(n - 1) + fib(n - 2);
    }
    
    public static void main(String[] args) {
        System.out.println(fib(10));
    }
}
</code></pre>

优缺点分析

说实话，这个方法我不太推荐日常使用，原因有几个：

优点：

  • 绕过Markdown解析器的缩进问题，直接用HTML标签，格式绝对稳定
  • 可以精确控制样式，比如加背景色、边框、字体大小

缺点：

  • 写起来麻烦，每次都要打一堆标签
  • 可读性差，写文档的时候满屏都是HTML标签，干扰思路
  • 不是所有Markdown渲染器都完美支持HTML，有些会过滤掉标签

我有一次给一个技术博客写教程，用了大量HTML代码块，结果导出PDF的时候，那些标签全变成了文本显示出来，尴尬极了。

不过，如果你在用某些特殊的Markdown工具（比如一些老旧的静态博客生成器），它们对围栏代码块支持不好，这时候HTML标签代码块就是个可靠的保底方案。

第四种写法：混合格式——围栏+转义——解决代码中包含围栏的终极方案

这个写法是我最想推荐的，也是解决”代码块里还有代码块”这种套娃场景的终极方案。

核心问题：代码里有反引号怎么办？

假设你要写一段JavaScript代码，里面用到了模板字符串，模板字符串里有反引号：

const template = `Hello, ${name}`;

如果你用围栏代码块来包裹这段代码，问题来了——代码里的反引号会被解析器误认为是代码块的结束标记。

```javascript
const template = `Hello, ${name}`;  // 这里面的反引号会打断围栏！


渲染结果就是：代码块只到第一个反引号就结束了，后面的内容变成了普通文本，格式全乱。

### 解决方案：用四个或更多反引号

Markdown规范（CommonMark）规定：**如果你的代码内容里包含N个反引号，你就用N+1个或更多反引号作为围栏**。

```markdown
````javascript
const template = `Hello, ${name}`;
const another = `Welcome, ${user}`;
````

用四个反引号围栏，就能完美包裹含有一到三个反引号的代码内容。同理，如果代码里用了三个反引号，你就用四个或五个。

实际例子：文档里套文档

我最近在给一个开源项目写README，里面有一段是教别人怎么用Markdown写文档，这就出现了”文档里套文档”的场景：

## 如何写代码块

在你的Markdown文件中，用三个反引号包裹代码：

````markdown
```python
def greet(name):
    return f"Hello, {name}"

””

如上所示，外层用四个反引号，内层用三个，就能正确渲染。


这个技巧非常实用，我几乎每周都会在写技术文档时用到。而且这个规则不仅适用于Markdown，在**GitHub的Markdown渲染器、VS Code的预览、Hexo、Hugo**等主流工具中都能正确工作。

### 进阶技巧：转义反引号

除了增加围栏反引号数量，还有一个办法：**在代码里的反引号前加反斜杠转义**。

```markdown
```javascript
const msg = \`Hello, \${name}\`;


这样写也能解决问题，但我个人更喜欢用"多反引号围栏"的方式，因为：
1. 代码更原生，不需要转义字符
2. 阅读时更直观，知道这段代码原本就是这样的
3. 复制粘贴到其他环境时不会因为转义符而出问题

---

## GitHub文档一键排版——实战技巧与工具推荐

讲完了四种代码块写法，下面来点实用的：**怎么在GitHub上让文档排版更漂亮、更专业？**

### 技巧一：善用任务列表（Task List）

GitHub支持在Markdown里写任务列表，渲染出来是一个可勾选的方框。非常适合写TODO、步骤、 checklist之类的场景。

```markdown
## 部署检查清单

- [x] 确认服务器状态正常
- [x] 备份数据库
- [ ] 更新应用版本
- [ ] 重启服务
- [ ] 验证接口响应

渲染效果就是带复选框的列表，一目了然。我在好几个开源项目的README里看到这种用法，显得特别专业。

技巧二：表格的规范写法

表格在Markdown里是个容易出格式问题的地方。很多人写表格时，对齐符号|和-没对齐，结果渲染出来表格错位。

正确的写法是：列分隔符要对齐，表头下面的对齐行要用---或:-:或-:来指定对齐方式。

| 参数名 | 类型 | 必填 | 说明 |
|:------:|:----:|:----:|:----:|
| username | string | 是 | 用户名，3-20个字符 |
| password | string | 是 | 密码，至少8位 |
| email | string | 否 | 邮箱地址，用于找回密码 |

注意看中间那行：|:------:|:----:|:----:|:------:|，每个单元格的-数量跟上面的列宽对齐，两边的:表示居中。这样写出来的表格，在GitHub上渲染得非常整齐。

技巧三：引用块的嵌套使用

GitHub的Markdown支持引用块（blockquote），可以用来做提示、警告、注意等场景。

> **注意**：生产环境部署前请确认数据库备份已完成。
>
> 如果部署失败，可以使用回滚脚本：
>
> ```bash
> ./rollback.sh --version=2.1.0
> ```
>
> 如需帮助，请联系运维团队。

这样写出来，引用块里可以嵌套代码块、加粗文字、列表等，排版层次分明。我经常在技术文档的”注意事项”部分用这种方式。

技巧四：使用GitHub Flavored Markdown的表格对齐功能

上面已经讲过了，但值得再强调一下：对齐的指定方式。

| 左对齐 | 居中 | 右对齐 |
|:-------|:----:|-------:|
| 内容   | 内容 | 内容   |
  • :------- → 左对齐
  • :----: → 居中
  • -------: → 右对齐

这个功能在写API文档、参数说明表的时候特别有用，能让文档看起来更整洁专业。

工具推荐：帮你自动排版的神器

手动调格式太麻烦了？推荐几个我常用的工具：

1. Markdownlint（代码检查工具）

# 安装
npm install -g markdownlint-cli

# 检查文档
markdownlint README.md

# 自动修复大部分问题
markdownlint README.md --fix

这个工具能帮你检查Markdown语法问题，包括代码块缩进、标题层级、列表格式等，还能自动修复一部分。我每次写完文档都会跑一遍，能发现不少肉眼看不出来的问题。

2. VS Code的Markdown预览插件

VS Code自带的Markdown预览已经很好用了，但如果你想要实时预览+源码分屏，可以装一个”Markdown All in One”插件，里面有很多快捷键和格式化工具。

3. GitHub本身的预览功能

写GitHub上的README或文档时，编辑界面右上角有个”Preview”按钮，点一下就能实时看到渲染效果。这个功能被很多人忽略了，但其实非常有用。

踩坑总结：代码块缩进的五大常见错误

最后，我把这些年踩过的坑汇总一下，帮你避坑：

错误一：围栏代码块前后加了空格

  ```python  ← 错了！前面有空格
  def hello():
      print("hello")


**后果**：解析器可能把它当成缩进代码块，而不是围栏代码块，导致整个文档结构错乱。

**正确**：围栏必须顶格。

### 错误二：代码内容顶格写，没有考虑语言特性

```markdown
```python
def hello():
print("hello")  # 错了！Python靠缩进区分代码块，这里缩进没了


**后果**：代码本身语法错误，虽然Markdown能渲染出来，但代码没法运行。

**正确**：代码内部的缩进要保持原样，这是代码语言的要求，不是Markdown的要求。

### 错误三：在列表里写缩进代码块，导致冲突

```markdown
1. 第一步
    code here  ← 被当成列表的子项，而不是代码块
2. 第二步

后果：代码缩进了，列表结构也乱了。

正确：在列表里插入代码块时，用围栏代码块，不要用缩进代码块。或者在代码块前后加空行。

错误四：代码里有反引号，没用多围栏或转义

```javascript
const str = `hello`;  ← 这里面的反引号会结束代码块

”`

后果：代码块提前结束，后面的内容变成普通文本，文档格式全乱。

正确：用四个或更多反引号围栏，或者转义代码里的反引号。

错误五：混用不同风格的围栏

”`markdown ~~~python ← 波浪号围栏 def hello():

print("hello")

”` ← 反引号围栏结束

后果：有些解析器能识别，有些不能，兼容性差。

正确：围栏的开始和结束要一致，用反引号就用反引号，用波浪号就用波浪号。

最后说几句

写技术文档这件事，看似简单，其实有很多细节值得琢磨。代码块缩进问题，表面上是个语法问题，实际上考验的是对Markdown解析规则的理解，以及在不同场景下选择合适的写法。

我这五年写文档踩过的那些坑，总结下来就一句话：围栏代码块顶格写，代码里有反引号就用更多围栏，列表里插代码块就别用缩进风格。

如果你还在用本地编辑器写Markdown，建议装个Markdownlint跑一跑，能帮你发现不少隐藏问题。推到GitHub之前，也别忘了点一下预览按钮，确认一下渲染效果。

文档写得好，不仅能帮别人理解你的项目，也能体现你自己的专业度。希望这篇文章能帮你在写文档的路上少踩点坑，多省点时间。

如果这篇文章对你有帮助，欢迎收藏转发给你身边还在被Markdown格式折磨的朋友。咱们下次见！

-- 展开阅读全文 --