Markdown 代码块指南：内联代码、隔离块和语法突出显示 |WordToMD

代码格式化是 Markdown 最强大的功能之一。无论您是记录函数、显示终端命令还是编写教程，Markdown 代码语法都可以使代码在视觉上清晰、格式正确，并且（在大多数平台上）语法突出显示。本指南涵盖了有关的所有内容 Markdown 代码块.

内联代码

将短片段或单个表达式括在单个反引号中：

Use `console.log()` to print output.
Set the variable with `const x = 42;`.
The file is saved as `README.md`.

内联代码以等宽字体呈现，在视觉上与周围的文本不同。将其用于：

函数和方法名称： addEventListener()
变量名称： isLoading
文件名： package.json
命令参数： --verbose
短代码表达式

如果您的内联代码包含反引号，请使用双反引号将其包装：

`` `backtick inside` ``

防护代码块

对于多行代码，使用三个反引号 (`) 打开和关闭块：

```
This is a code block.
It preserves all whitespace and line breaks.
No formatting is applied inside.
```

缩进、间距和换行符都被准确保留。

语法突出显示

在左三个反引号后添加语言标识符以启用语法突出显示：

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))
```

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

```bash
#!/bin/bash
echo "Hello, World!"
ls -la ~/Documents
```

通用语言标识符

语言	标识符
Python	`python`
JavaScript	`javascript` or `js`
TypeScript	`typescript` or `ts`
HTML	`html`
CSS	`css`
JSON	`json`
YAML	`yaml` or `yml`
Bash / Shell	`bash` or `sh`
SQL	`sql`
Markdown	`markdown` or `md`
Java	`java`
C	`c`
C++	`cpp`
C#	`csharp`
去	`go`
生锈	`rust`
红宝石	`ruby`
PHP	`php`
斯威夫特	`swift`
科特林	`kotlin`
R	`r`
PowerShell	`powershell`
Dockerfile	`dockerfile`
XML	`xml`
TOML	`toml`
HTTP	`http`
差异	`diff`

缩进代码块

较旧的 Markdown 语法对代码块使用 4 空格缩进：

    function oldStyle() {
        return "This is a code block";
    }

这是 CommonMark 兼容的，但可读性较差，并且不支持语言标识符。请改用围栏块（三个反引号）。

从 Word 文档转换代码

Word 中的等宽文本（Courier New、Consolas 等）在您使用时会转换为内联代码 WordToMD. Multi-line code in Word converts depending on how it was formatted:

等宽字体段落 → 可能成为多个内联代码片段
Word“代码”样式 → 转换为代码块
文字文本块 → 可能需要手动围栏

转换后，检查代码部分并根据需要添加适当的防护：

查找应该是块的代码
用三个反引号括起来
添加适当的语言标识符

特定于语言的示例

HTTP 请求

```http
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "name": "Alice",
  "email": "alice@example.com"
}
```

终端命令

```bash
npm install
npm run build
npm run dev
```

差分输出

```diff
- const oldValue = "hello";
+ const newValue = "world";
  console.log(newValue);
```

YAML 配置

```yaml
server:
  host: localhost
  port: 8080
  debug: true
database:
  url: postgresql://localhost:5432/mydb
```

嵌套代码块（用于文档）

在记录 Markdown 本身时，使用 4 个反引号来包装包含 3 个反引号的块：

````markdown
```python
# This is a code block inside documentation
```
````

平台支持

平台	内联代码	围栏块	语法突出显示
GitHub	✅	✅	✅
GitLab	✅	✅	✅
Obsidian	✅	✅	✅
GitBook	✅	✅	✅
Notion	✅	✅	✅
Confluence（Markdown）	✅	✅	✅
VS 代码	✅	✅	✅

行号

标准 Markdown 不支持代码块中的行号。一些平台和静态站点生成器通过插件添加此功能：

Prism.js （被许多 SSG 使用）— 添加 {numberLines: true} 在代码围栏中
GitHub — 渲染的 Markdown 中没有本机行号（使用 GitHub Blame 视图代替）
GitBook — 通过代码块设置的行号

从块复制代码

GitHub 和许多平台自动向代码块添加“复制”按钮。这是一个渲染增强功能——它不需要 Markdown 中的任何特殊内容。

FAQ

为什么我的代码块语法没有突出显示？ 语言标识符丢失或拼写错误，或者平台不支持特定语言。检查上面的标识符列表。

如何在代码块内显示反引号？ 在受防护的代码块内，反引号被视为文字字符。只有三反引号栅栏需要特殊处理。

我的 Word 文档有彩色语法突出显示的代码。WordToMD 会保留颜色吗？ 否 - Markdown 代码块不保留颜色格式。WordToMD 将文本转换为代码块；然后 Markdown 渲染器根据语言标识符应用语法突出显示。

我可以突出显示代码块中的特定行吗？ 标准 Markdown 不支持此功能。一些平台（例如 Astro 与 Shiki 或 Hugo）支持通过注释突出显示行： {1,3-5} 。

Markdown 语法速查表 — 完整参考
Word 到 API 文档 — 代码较多的文档
Word 到 GitHub Markdown — GitHub 特定的代码格式

结论

Markdown 代码块很简单：内联代码的反引号，带有语言标识符的块的三个反引号。使用转换 Word 文档后 WordToMD，检查等宽文本是否已正确包装在代码语法中，并添加语言标识符以在目标平台上正确突出显示语法。