Markdown語法範例大全：從基礎到進階的完整程式碼與效果對照

為什麼你需要一份 Markdown 範例參考

說實話，Markdown 語法本身不難，但有時候就是想不起來某個具體寫法——表格對齊怎麼搞來著？引用裡面能不能巢狀清單？任務清單的語法是什麼來著？

這篇文章把所有常用的 Markdown 語法範例整理在一起，每個都附帶原始碼和渲染效果。你可以把它當速查表用，也可以從頭到尾看一遍，基本就能覆蓋日常寫作的 90% 需求了。

順便說一句，下面所有範例我用的是標準 Markdown 和 GitHub Flavored Markdown（GFM）語法，這是目前最通用的標準，在 GitHub、VS Code、Obsidian、Notion 等主流平臺上都能正常渲染。

標題範例

Markdown 用 # 號來標記標題，幾個 # 就是幾級標題：

## 二級標題
### 三級標題
#### 四級標題
##### 五級標題
###### 六級標題

渲染效果就是你現在看到的這些大小不同的標題樣式。實際使用中，一級標題通常用作文章大標題，二級和三級標題用來組織章節結構。一篇文件裡只用一個一級標題是比較好的習慣。

對了，還有另一種標題寫法叫 Setext 風格，用 === 和 --- 分別表示一級和二級標題：

一級標題
========

二級標題
--------

這種寫法現在用得比較少了，但有些舊文件裡還能見到。

文字格式化範例

粗體和斜體

這是最基礎也是最常用的 markdown 格式範例：

**粗體文字**
*斜體文字*
***粗體斜體***
~~刪除線~~

效果：

粗體文字：用雙星號包裹
斜體文字：用單星號包裹
粗體斜體：用三星號包裹
~~刪除線~~：用雙波浪號包裹（GFM 擴充套件語法）

粗體也可以用雙底線 __粗體__，斜體也可以用單底線 _斜體_，不過我個人習慣一直用星號，保持一致性比糾結選哪個更重要。

段落和換行範例

這是第一段。

這是第二段。

段落之間用空行分隔。
同一段落內換行需要在行尾加兩個空格。

這點很容易被忽略——直接按 Enter 不會換行，需要行尾加兩個空格，或者用 <br> 標籤。我之前就踩過這個坑，寫了一大段文字想分行顯示，結果渲染出來全擠在一行裡。

清單範例

無序清單

- 蘋果
- 香蕉
  - 小米蕉
  - 大蕉
- 橘子

效果：

蘋果
香蕉
- 小米蕉
- 大蕉
橘子

無序清單可以用 -、*、+ 三種符號，效果一樣。子清單透過縮排實現，一般縮排 2 或 4 個空格。

有序清單

1. 安裝依賴
2. 配置環境
3. 啟動專案

效果：

安裝依賴
配置環境
啟動專案

任務清單

這是 GFM 擴充套件語法，在 GitHub 的 README 和 Issue 裡特別常用：

- [x] 已完成的任務
- [ ] 待完成的任務
- [ ] 另一個待辦

效果：

[x] 已完成的任務
[ ] 待完成的任務
[ ] 另一個待辦

連結範例

[前往 GitHub](https://github.com)
[帶標題的連結](https://github.com "GitHub 首頁")

效果：點擊前往 GitHub 就能跳轉。

還有一種引用式連結寫法，適合文章中多次引用同一個 URL 的場景：

[Markdown Guide][1] 是一個很好的學習資源，裡面有很多實用的 [markdown 範例][2]。

[1]: https://www.markdownguide.org "Markdown Guide"
[2]: https://www.markdownguide.org/basic-syntax "Basic Syntax"

引用式連結把 URL 集中放在文章末尾，正文部分更乾淨。寫長文章的時候我會用這種方式。

圖片範例

![替代文字](https://picsum.photos/200/100)
![帶標題的圖片](https://picsum.photos/200/100 "範例圖片")

語法跟連結很像，就是前面多了一個 !。方括號裡寫替代文字，當圖片載入不出來的時候會顯示這段文字，對 SEO 和無障礙存取也有幫助。

如果你想給圖片加上連結，可以這樣巢狀：

[![點擊圖片](https://picsum.photos/200/100)](https://github.com)

標準 Markdown 不支援直接調整圖片大小，但在 GitHub 和不少編輯器裡可以用 HTML 的 <img> 標籤來控制尺寸。

程式碼範例

行內程式碼

使用 `console.log()` 輸出除錯資訊。

效果：使用 console.log() 輸出除錯資訊。

程式碼區塊

用三個反引號包裹，可以在後面指定語言實現語法高亮：

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

渲染效果：

function greet(name) {
  return `Hello, ${name}!`;
}

支援的語言高亮非常多，常用的有 python、java、go、rust、bash、css、html、json、yaml 等。

引用範例

> 這是一段引用文字。
>
> 引用可以包含多個段落。
>
> > 引用也可以巢狀。
>
> - 甚至可以包含清單
> - 以及 **格式化文字**

效果：

這是一段引用文字。
引用可以包含多個段落。
引用也可以巢狀。
甚至可以包含清單
以及 格式化文字

引用區塊很適合用來標註注意事項、引述他人觀點或者突出某些資訊。

表格範例

這是日常使用頻率很高的一個 markdown 語法範例：

| 語法 | 說明 | 支援情況 |
|------|------|---------|
| `**粗體**` | 粗體文字 | 通用 |
| `*斜體*` | 斜體文字 | 通用 |
| `~~刪除線~~` | 刪除線 | GFM |
| `[]()` | 連結 | 通用 |

效果：

語法	說明	支援情況
`粗體`	粗體文字	通用
`斜體`	斜體文字	通用
`~~刪除線~~`	刪除線	GFM
`[]()`	連結	通用

表格對齊

| 置左 | 置中 | 置右 |
|:-----|:----:|-----:|
| 內容 | 內容 | 內容 |

效果：

置左	置中	置右
左邊	中間	右邊

表格用冒號位置控制對齊：左邊有冒號是置左對齊，兩邊都有是置中，右邊有冒號是置右對齊。

說實話表格是 Markdown 裡寫起來最累的部分，超過 5 欄維護起來就比較痛苦了。複雜表格我一般先用線上表格產生器做好再貼上過來。

分隔線範例

---

***

___

三種寫法效果一樣，都渲染為一條水平分隔線。習慣上用 --- 的最多。注意分隔線前後留空行，避免被識別為 Setext 標題。

註腳範例

這是一段帶有註腳的文字[^1]，註腳會在文章末尾顯示。

[^1]: 這是註腳的內容。

效果：點擊上標編號就能跳轉到對應註釋。註腳是擴充套件語法，在 Obsidian、Typora、Pandoc 等編輯器中支援，但 GitHub 原生不支援。

跳脫字元範例

當你想顯示 Markdown 的特殊符號本身時，用反斜線跳脫：

\*這不是斜體\*
\# 這不是標題
\[這不是連結\]

效果：*這不是斜體*，# 這不是標題。

以下字元可以跳脫：\、`、*、_、{}、[]、()、#、+、-、.、!、|。

一個完整的 Markdown 文件範例

把上面的語法串起來，這裡是一個完整的專案 README 風格的 markdown 文件範例：

# 我的開源專案

一個簡潔高效的 **Web 元件庫**，幫助開發者快速構建現代化介面。

## 功能特性

- 豐富的主題客製化
- 支援 tree-shaking
- 完整的 TypeScript 型別定義
- 測試覆蓋率 > 95%

## 快速開始

```bash
npm install my-components
```

```javascript
import { Button } from 'my-components';

const app = () => {
  return <Button type="primary">點擊我</Button>;
};
```

## API 參考

| 屬性 | 型別 | 預設值 | 說明 |
|:-----|:-----|:------:|:-----|
| type | string | 'default' | 按鈕型別 |
| size | string | 'medium' | 按鈕尺寸 |
| disabled | boolean | false | 是否停用 |

> **注意：** 本元件庫需要 React >= 18.0。

## 開發計畫

- [x] 基礎元件開發
- [x] 文件站點搭建
- [ ] 國際化支援
- [ ] 暗色主題

## 貢獻

歡迎提交 PR！請先閱讀 [貢獻指南](https://github.com/example/contributing)。

---

© 2024 我的開源專案

這個範例可以直接複製使用，改改內容就是一份不錯的 README。

不同平臺的相容性說明

同樣是 Markdown，不同平臺支援的程度不一樣。這裡簡單列一下常見的差異：

語法	GitHub	VS Code	Obsidian	Notion
基礎語法	完全支援	完全支援	完全支援	完全支援
表格	支援	支援	支援	支援
任務清單	支援	支援	支援	支援
註腳	不支援	視外掛而定	支援	不支援
數學公式	支援 LaTeX	視外掛而定	支援	支援
Mermaid 圖表	支援	視外掛而定	支援	不支援

實測發現 GitHub 上巢狀清單的縮排要求比較嚴格，必須跟上一級的清單標記對齊。而 Obsidian 在這方面寬容一些。如果你的文件需要跨平臺使用，建議優先用標準 Markdown 語法，避免依賴特定平臺的擴充套件功能。

參考來源

CommonMark Spec — Markdown 標準規範
GitHub Flavored Markdown Spec — GitHub 擴充套件語法規範
Daring Fireball: Markdown Syntax — Markdown 創始人的原始規範
Markdown Guide — 綜合學習資源