Markdown代碼塊完整指南 - 語法、範例與最佳實踐

Markdown代碼塊是在文檔、README檔案和技術寫作中展示代碼片段的重要工具。本指南全面介紹了markdown代碼格式化的所有知識點。

什麼是Markdown代碼塊？

Markdown代碼塊允許你以適當的格式和語法高亮顯示代碼。它們保留空格、縮排和特殊字符，使代碼易於閱讀。

行內代碼

對於文字中的短代碼片段，使用單個反引號：


```
使用 `console.log()` 在JavaScript中列印輸出。
```

結果：

使用 `console.log()` 在JavaScript中列印輸出。

圍欄代碼塊

對於多行代碼，使用三個反引號（```）或三個波浪號（~~~）：

基本語法

```
function greet(name) {
    return "你好，" + name + "！";
}
```

指定程式語言

```javascript
function greet(name) {
    return "你好，" + name + "！";
}
```

常用語言標識符

語法高亮的常用語言標識符：

javascript 或 js - JavaScript
python 或 py - Python
java - Java
cpp 或 c++ - C++
html - HTML
css - CSS
json - JSON
xml - XML
bash 或 shell - Shell腳本
sql - SQL
php - PHP
ruby - Ruby
go - Go
rust - Rust
typescript 或 ts - TypeScript

進階範例

JavaScript範例

```javascript
// 計算階乘的函式
function factorial(n) {
    if (n <= 1) return 1;
    return n * factorial(n - 1);
}

console.log(factorial(5)); // 輸出：120
```

Python範例

```python
# 串列推導式範例
numbers = [1, 2, 3, 4, 5]
squares = [x**2 for x in numbers]
print(squares)  # 輸出：[1, 4, 9, 16, 25]
```

HTML範例

```html
<!DOCTYPE html>
<html>
<head>
    <title>範例頁面</title>
</head>
<body>
    <h1>歡迎來到我的網站</h1>
    <p>這是一個段落。</p>
</body>
</html>
```

最佳實踐

1. 始終指定程式語言

始終包含語言標識符以獲得更好的語法高亮：

推薦：

```javascript
const message = "你好世界";
```

避免：

```
const message = "你好世界";
```

2. 保持代碼可讀性

使用適當的縮排
必要時包含註解
適當換行長行代碼

3. 提供上下文

在代碼塊周圍提供上下文說明：


```javascript
// 此函式驗證電子郵件地址格式
function isValidEmail(email) {
    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return regex.test(email);
}
```

替代語法

縮排代碼塊

也可以透過縮排4個空格或1個製表符來建立代碼塊：

    function example() {
        return "這是縮排代碼";
    }

波浪號圍欄

使用波浪號代替反引號：

~~~javascript
const alternative = "使用波浪號";
~~~

轉義反引號

要在代碼塊中顯示反引號，可以使用更多的反引號作為圍欄：


````
```
這個代碼塊包含反引號
```
````

常見問題及解決方案

問題1：代碼沒有高亮

問題： 代碼顯示時沒有語法高亮解決方案： 檢查語言標識符的拼寫，確保它受支援

問題2：反引號不起作用

問題： 反引號顯示為文字而不是建立代碼塊解決方案： 確保使用三個反引號並且它們在單獨的行上

問題3：特殊字符顯示問題

問題： 特殊字符顯示不正確解決方案： 代碼塊會自動轉義特殊字符，但要確保編碼正確

平台特定說明

GitHub

支援廣泛的語言高亮
在README檔案中渲染代碼塊
支援使用 diff 語言進行差異高亮

GitLab

類似GitHub，但有額外功能
支援在代碼塊中使用mermaid圖表

Medium

支援有限的代碼高亮
建議使用線上代碼高亮工具

代碼塊看起來很簡單，但真的能讓文檔的可讀性提升一大截。語言標識符應該是最重要的部分了——它能把普通文字變成高亮顯示的專業代碼。

大部分時候用反引號圍欄就夠了，不過知道其他方法也挺有用的，萬一哪天用得上呢。