嘿，朋友！你是不是也遇到过这种情况：想给朋友或者同事发一段代码，结果粘贴到微信或者邮件里，缩进全乱了，变量名挤在一起，看起来像一团乱麻？或者你在写技术文档，想展示一段脚本，但普通文字没法区分“这是说明”和“这是代码”？
别急，今天我要带你认识的这位“魔法刷子”——Markdown 代码块，就是专门解决这个问题的。而且我保证，学会了它，你写文档的速度能翻倍，看起来还特别专业。哪怕你完全没写过代码，也没关系，因为这就像是在文档里画个框，把重要的东西圈出来一样简单。
为什么我们需要“代码块”这个框框？
想象一下，你在写一封信告诉朋友：“把那个红色的盒子交给小明。”如果你只是普通地写着，朋友可能会困惑：“哪个盒子？红色的在哪里？”
但在 Markdown 里，如果我们用代码块把代码包起来，就像给这段文字穿了一件特别明显的“荧光黄背心”。
print("Hello, World!")
你看，这段 print("Hello, World!") 是不是瞬间就从周围的文字里跳出来了？它的字体变了，背景可能还有点颜色，甚至如果你知道的小技巧，它还能告诉你这是什么语言（比如上面的 python）。
对于程序员来说，这是保命技能；对于非程序员来说，这是让你写的文档看起来“很厉害”、“很清晰”的捷径。
第一关：最简单的“三步走”——行内代码
在深入复杂的代码块之前，我们先聊聊它的“小弟弟”——行内代码。
当你只是想在一段话里提一下某个命令、某个文件名，或者某个代码变量时，不需要搞一个大的代码块，用两个反引号（`）把它包起来就行。
那个反引号长什么样？就在键盘数字 1 的左边，ESC 键的下面。
比如：
你想告诉朋友：“别直接运行 pip install，要先看看版本。”
在 Markdown 编辑器里，你这样写：
别直接运行 `pip install`，要先看看版本。
渲染出来后，效果大概是这样的：
别直接运行
pip install，要先看看版本。
是不是很像程序员平时说话的样子？简洁，重点突出。记住，一对反引号，就是行内代码。这是最基础的，我们继续升级。
第二关：正式登场——多行代码块
这是今天的主角。当你有一整段代码、一段配置、或者一个脚本需要展示时，就需要用到代码块。
1. 裸奔的代码块（最基础）
怎么画这个框？很简单，在你想开始写代码的那一行，单独放三个反引号（”`），然后在结尾再放三个反引号。
这是一个普通的代码块 里面可以写很多行 每一行都会保留空格和缩进
渲染出来的效果：
这是一个普通的代码块
里面可以写很多行
每一行都会保留空格和缩进
你看，无论你在里面写多少空格，Markdown 都会原封不动地保留下来。这就是代码块最强大的地方：它保护了你的排版。
2. 给代码穿上“颜色外衣”——语法高亮
如果你只是普通的写代码，那上面的方法就够了。但是，如果你知道这是什么语言，加个名字会更好。
在开头的三个反引号后面，直接写上语言的名字（英文缩写）。比如 Python 是 python，JavaScript 是 javascript 或 js，HTML 是 html，JSON 是 json。
举个例子，我想展示一段 Python 代码：
```python
def greet(name):
print(f"Hello, {name}!")
greet("小明")
```
渲染出来可能是这样的（取决于你的编辑器主题，会有不同的颜色）：
def greet(name):
print(f"Hello, {name}!")
greet("小明")
看到没有？函数名、字符串、注释可能都有了不同的颜色。这让阅读体验提升了不止一个档次。如果你不知道代码是什么语言，不写也没关系，它还是会保留缩进，只是没有颜色。
第三关：实战演练——几种常见的应用场景
光说不练假把式。我们来模拟几个你马上就能用到的场景。
场景一：给小白教程里插入配置
假设你在写一个博客，教别人怎么安装软件。你不能只说“复制这段配置”，你得让读者能轻松复制。
你的草稿：
在 `config.json` 文件中，加入以下内容：
```json
{
"debug": true,
"timeout": 3000,
"user": "admin"
}
```
这样，读者一眼就能看出这是 JSON 格式，而且因为加了 json，很多编辑器会自动帮你校验括号有没有闭合。万一写错了，高亮可能还会变红，这就帮你提前排雷了。
场景二：在社交媒体或论坛解释问题
有时候你在 Stack Overflow 或者技术论坛上问问题，如果你把代码直接贴进正文，格式全乱，别人根本看不懂。
错误示范： “我运行了 python main.py 结果报错了，错误是 TypeError: unsupported operand type(s) for +: ‘int’ and ‘str’”
正确示范：
“我运行了 python main.py，结果报错了：
age = 25
message = "Age is " + age
print(message)
报错信息是：TypeError: unsupported operand type(s) for +: 'int' and 'str'”
看到区别了吗？用代码块包住出错的代码片段，再在行内代码里包住报错信息，别人三秒钟就能定位问题。这就是专业度。
场景三：展示命令行的操作记录
对于 IT 相关的工作，命令行是家常便饭。展示命令时，我们通常习惯在命令前加一个 $ 符号，表示这是终端输入。
你的草稿：
你可以这样检查你的 Git 状态：
```bash
$ git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
```
这里我们用了 bash 来标识。虽然 Bash 的代码高亮可能不如 Python 那么五彩斑斓，但加上 $ 符号会让读者明确知道：“哦，这是我要在终端里敲的命令”，而不是程序里的代码。这是一个小小的习惯，但非常贴心。
第四关：避坑指南——那些让你崩溃的细节
虽然 Markdown 很简单，但有几个小坑，新手（甚至老手）经常掉进去。我来帮你填平。
1. 反引号的数量要对
开头三个，结尾也要三个。不能头大脚小。
❌ ``` 你好
❌ ``` 你好
✅ ```` ``` ```` 你好 ```` ``` ````
### 2. 语言标识符拼写要对
虽然有些编辑器很聪明，能猜出 `py` 是 Python，`js` 是 JavaScript，但为了保险起见，还是用全称比较好，或者用通用的缩写。
常见的包括：
- `python` 或 `py`
- `javascript` 或 `js`
- `html`
- `css`
- `sql`
- `bash` 或 `shell`
- `json`
- `markdown` 或 `md`
如果你写了一个奇怪的语言名，比如 ```` ```superlang````，大部分编辑器会把它当作纯文本处理，虽然没有语法高亮，但至少不会报错，依然会保留格式。
### 3. 嵌套问题：如果在代码块里想显示反引号怎么办？
这是一个高级技巧。假设你的代码块里，本身就需要展示一个行内代码（比如你是在教别人写 Markdown）？
这时候，你只需要在代码块的开头和结尾多用几个反引号。
**示例：我想展示一个包含行内代码的代码块**
~~~
这是文档说明：请使用 code 命令。
~~~
注意看，我用了**四个**反引号来包裹。这样，里面的**三个**反引号就被视为普通文本，不会提前关闭代码块。
渲染效果：
这是文档说明：请使用 code 命令。
“”
这就是 Markdown 的“套娃”规则：外层用几个反引号，内层就能用少一个的反引号。
4. 缩进陷阱
在有些 Markdown 解析器中，如果你在代码块内部使用了 Tab 键缩进，有时候会出问题，或者在不同的平台上显示不一致。
建议： 尽量使用空格来进行缩进，而不是 Tab 键。虽然这有点强迫症，但能保证你的文档在任何地方看起来都一样整齐。
第五关：不同工具的小差异
虽然 Markdown 是标准，但你用的工具不同，细节上可能有一点点差别。
- GitHub / GitLab / Gitee： 对语法高亮的支持最好，语言列表最全。只要是你写的语言名，它基本都能高亮。
- Typora / Obsidian / Notion： 这些是离线编辑器，它们会实时渲染。你敲完 `
python回车，下面就会自动变颜色。这很有成就感，建议初学者用这类工具体验一下。 - 微信 / QQ 内置编辑器： 很遗憾，这些聊天软件的内置 Markdown 支持非常弱，甚至不支持代码块。所以，如果你要在微信里发代码，建议先写成图片或用截图，或者使用支持 Markdown 的第三方插件。
- 飞书 / 钉钉文档： 它们对 Markdown 的支持很好，代码块功能完善，甚至可以一键复制。
结语：让表达更清晰，从这一个框开始
写文档，说到底，是为了让别人更容易看懂。
Markdown 的代码块，就是一个小小的“聚焦框”。它告诉读者：“嘿，这一段很重要，是代码，别把它和普通文字混为一谈。”
你不需要成为程序员才能用它。哪怕你只是写周报、写博客、写学习笔记，只要涉及到任何“需要原样保留格式”的内容，代码块就是你的好朋友。
下次，当你准备粘贴一段乱糟糟的文字时，记得找找那个在数字键 1 左边的反引号。按下它，你的文档就开始变得整洁、专业、易读了。
祝你在文档写作的道路上，越写越顺，越写越清晰！如果有其他 Markdown 的小技巧想问，随时来找我聊聊。