Markdown 代码块与语法高亮

2 min中级2026/9/12

行内代码、围栏代码块、语言标注与高亮配置。

认知导入（Layer 1 进阶层） 前置知识：Layer 0 五篇。边界说明：代码块是技术文档的核心能力；三个反引号开闭必须成对，语言名写在开头的反引号后。强制练习：用三个反引号包一段代码，并在开头写 javascript 观察语法高亮；删掉一个反引号观察代码块“吞掉”后续内容。

1. 行内代码 (Inline Code)

语法：使用反引号 ` 包围代码示例：

在 Markdown 中，行内代码使用 `` ` `` 包围，例如 `console.log('Hello, World!');`

渲染效果：在 Markdown 中，行内代码使用 ` 包围，例如 console.log('Hello, World!');

2. 代码块 (Code Blocks)

2.1 基本代码块

语法：使用三个反引号 ``` 包围代码块示例：

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

渲染效果：

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

2.2 语法高亮

语法：在三个反引号后指定语言名称示例：

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

```python
def hello():
print('Hello, World!')
hello()
```

```java
public class Hello {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```

```c
#include <stdio.h>
int main() {
printf("Hello, World!\n");
return 0;
}
```

```css
body {
  font-family: Arial, sans-serif;
  background-color: #f0f0f0;
}
h1 {
  color: #333;
}
```

```html
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>Hello</title>
  </head>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
```

```sql
SELECT * FROM users WHERE age > 18;
```

```json
{
  "name": "John",
  "age": 30,
  "city": "New York"
}
```

```yaml
server:
port: 8080
spring:
datasource:
url: jdbc:mysql://localhost:3306/db
```

渲染效果：

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

 def hello():
  print('Hello, World!')
 hello()

 public class Hello {
  public static void main(String[] args) {
  System.out.println("Hello, World!");
  }
 }

 #include <stdio.h>
 int main() {
  printf("Hello, World!\n");
  return 0;
 }

body {
  font-family: Arial, sans-serif;
  background-color: #f0f0f0;
}
h1 {
  color: #333;
}

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>Hello</title>
  </head>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>

 SELECT * FROM users WHERE age > 18;

{
  "name": "John",
  "age": 30,
  "city": "New York"
}

server:
  port: 8080
spring:
  datasource:
  url: jdbc:mysql://localhost:3306/db

2.3 代码块中的换行和缩进

示例：

```javascript
// 代码块中的换行和缩进会被保留
function formatText(text) {
  return text
    .split(' ')
    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');
}
```

渲染效果：

// 代码块中的换行和缩进会被保留
function formatText(text) {
  return text
    .split(' ')
    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');
}

3. 代码块的高级功能（平台相关）

行号、指定行高亮等不是 CommonMark/GFM 规范能力，而是各静态站点生成器高亮引擎的扩展。GitHub 网页端不支持以下任何一种写法，用到时必须标注适用平台。

3.1 行号

Hugo（Chroma 高亮引擎）在语言名后附加选项：

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

Python-Markdown 系（MkDocs 等）通过 Highlight 扩展配置行号。GitHub 上如需展示行号，只能把行号写进代码文本或贴片段链接（GitHub 支持 #L行号 形式的文件片段锚点）。

3.2 高亮指定行

同样是高亮引擎扩展：Hugo/Chroma 用 {hl_lines=[2,4]}，Pygments 风格写作 hl_lines="2 4"：

```javascript {hl_lines=[2,4]}
function hello() {
  console.log('Hello, World!');
}
hello();
```

各平台语法不兼容，迁移时需按目标站点的高亮引擎改写。

3.3 代码块标题

CommonMark/GFM 没有代码块标题语法，通用做法是在代码块前放一行加粗文本或小标题：

**示例代码：hello.js**

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

部分工具有私有实现（如 Obsidian callout 包裹、部分主题解析 info string 附加文字），跨平台文档不要依赖。

4. 支持的编程语言

常见的支持语法高亮的编程语言包括：

语言	标识符	示例
JavaScript	javascript, js	```javascript
Python	python, py	```python
Java	java	```java
C	c	```c
C++	cpp, c++	```cpp
C#	csharp, cs	```csharp
HTML	html	```html
CSS	css	```css
SQL	sql	```sql
JSON	json	```json
YAML	yaml, yml	```yaml
Markdown	markdown, md	```markdown
Shell	shell, bash	```shell
PowerShell	powershell	```powershell
PHP	php	```php
Ruby	ruby, rb	```ruby
Go	go	```go
Rust	rust	```rust
Swift	swift	```swift
Kotlin	kotlin	```kotlin

5. 最佳实践

5.1 代码块最佳实践

使用语法高亮：为代码块指定正确的语言，提高代码可读性
保持代码整洁：确保代码格式正确，缩进一致
添加必要的注释：解释复杂代码的逻辑
控制代码长度：过长的代码块可能影响文档可读性，考虑只展示关键部分
提供上下文：在代码块前添加简短的说明，解释代码的用途

5.2 代码示例最佳实践

可运行的示例：确保代码示例可以正常运行
完整的示例：提供完整的代码示例，包括必要的导入和初始化
有意义的变量名：使用描述性的变量名，提高代码可读性
处理边界情况：在示例中展示如何处理边界情况
添加输出示例：对于有输出的代码，展示预期的输出结果

6. 常见问题与解决方案

6.1 语法高亮不工作

问题：代码块没有显示语法高亮 解决方案：

确保正确指定了语言标识符
检查 Markdown 渲染器是否支持语法高亮
尝试使用更常见的语言标识符（如 js 代替 javascript）

6.2 代码块中的反引号

问题：代码块中包含反引号，导致代码块提前结束 解决方案：

使用更多的反引号来包围代码块，例如使用四个反引号包围包含三个反引号的代码
或者使用 HTML 的 <pre> 和 <code> 标签

6.3 代码缩进问题

问题：代码块中的缩进显示不正确 解决方案：

确保代码块中的缩进使用空格或制表符一致
避免混合使用空格和制表符
检查 Markdown 编辑器的缩进设置

7. 扩展语法

7.1 GitHub Flavored Markdown (GFM)

示例：

```javascript
// GitHub Flavored Markdown 支持语法高亮
function githubExample() {
  console.log('Hello, GitHub!');
}
```

渲染效果：

// GitHub Flavored Markdown 支持语法高亮
function githubExample() {
  console.log('Hello, GitHub!');
}

7.2 代码块中的数学公式

示例：

```math
E = mc^2
```

渲染效果：

E = mc^2

8. 总结

Markdown 代码块和语法高亮功能使文档中的代码更加清晰易读，有助于更好地展示和解释代码。通过掌握这些功能，你可以创建包含各种编程语言代码的专业文档。在使用代码块时，遵循最佳实践可以确保代码的可读性和可维护性。同时，了解常见问题的解决方案可以帮助你快速解决在使用过程中遇到的问题。

Markdown 代码块与语法高亮

1. 行内代码 (Inline Code)#

2. 代码块 (Code Blocks)#

2.1 基本代码块#

2.2 语法高亮#

2.3 代码块中的换行和缩进#

3. 代码块的高级功能（平台相关）#

3.1 行号#

3.2 高亮指定行#

3.3 代码块标题#

4. 支持的编程语言#

5. 最佳实践#

5.1 代码块最佳实践#

5.2 代码示例最佳实践#

6. 常见问题与解决方案#

6.1 语法高亮不工作#

6.2 代码块中的反引号#

6.3 代码缩进问题#

7. 扩展语法#

7.1 GitHub Flavored Markdown (GFM)#

7.2 代码块中的数学公式#

8. 总结#

1. 行内代码 (Inline Code)

2. 代码块 (Code Blocks)

2.1 基本代码块

2.2 语法高亮

2.3 代码块中的换行和缩进

3. 代码块的高级功能（平台相关）

3.1 行号

3.2 高亮指定行

3.3 代码块标题

4. 支持的编程语言

5. 最佳实践

5.1 代码块最佳实践

5.2 代码示例最佳实践

6. 常见问题与解决方案

6.1 语法高亮不工作

6.2 代码块中的反引号

6.3 代码缩进问题

7. 扩展语法

7.1 GitHub Flavored Markdown (GFM)

7.2 代码块中的数学公式

8. 总结