如何正确使用Markdown代码块语法？

Question

**问题：如何在Markdown中正确使用代码块语法，以实现代码高亮和格式保留？** 在使用Markdown编写技术文档或博客时，正确使用代码块语法对于展示代码至关重要。然而，许多用户在实际操作中常遇到代码块无法高亮、语言标识错误或格式错乱的问题。例如，未指定语言导致代码未正确着色，或者忘记使用缩进/围栏符号造成渲染失败。掌握Markdown中围栏代码块（Fenced Code Blocks）的正确写法，包括使用三个反引号（```）包裹代码，并在起始符号后标明编程语言，是确保代码可读性的关键。此外，还需注意空行和缩进的使用，避免解析错误。

Answer 1

一、Markdown代码块语法基础
在Markdown中，代码块的展示主要依赖于两种方式：缩进代码块和围栏代码块（Fenced Code Blocks）。其中，围栏代码块由于其语法清晰、支持语言高亮，成为技术文档中的首选。

缩进代码块：使用四个空格或一个Tab缩进，适用于简单的代码展示，但不支持语言指定和高亮。
围栏代码块：使用三个反引号（```）包裹代码内容，推荐使用方式。语法示例如下：


```python
def hello():
    print("Hello, Markdown!")
```


注意：反引号必须成对出现，且起始行需指定语言名称，如python、javascript、java等，以便渲染器正确高亮。

二、语言标识与高亮机制
Markdown本身并不提供语法高亮功能，而是依赖于解析器（如Pandoc、CommonMark、GitHub Flavored Markdown等）或前端渲染库（如Prism.js、Highlight.js）。

语言标识
示例代码片段
推荐解析器
javascript
console.log("Hello")
Prism.js
sql
SELECT * FROM users;
Highlight.js
bash
sudo apt update
GitHub GFM

语言标识错误会导致高亮失败，例如将js写成javascripts，或遗漏语言标识。

三、格式保留与常见错误分析
为确保代码格式正确保留，需注意以下几点：

避免在代码块内使用中文标点或特殊字符，可能导致渲染异常。
代码块前后应保留空行，避免与普通文本混淆。
不要混合使用Tab和空格缩进，建议统一使用空格。


  

```json
{
  "name": "John",
  "age": 30
}
```

  
图1：JSON代码块示例


错误示例：未闭合的代码块会导致后续内容被误认为代码。

四、高级用法与扩展支持
某些Markdown解析器（如Docusaurus、VuePress、MkDocs）支持自定义代码块扩展，例如添加标题、行号、高亮特定行等。


```python {2,4} title="示例脚本"
def hello():
    print("Hello")  # 这行将被高亮
    return 0
```



graph TD
    A[开始] --> B[编写Markdown代码]
    B --> C{是否使用代码块?}
    C -->|是| D[指定语言标识]
    C -->|否| E[使用缩进代码块]
    D --> F[检查语法是否正确]
    F --> G[结束]


通过流程图可见，从代码编写到渲染，每一步都需要关注语法细节。