Markdown 速查：一份務實的快速教學

大多數文件最初都只是一個帶幾個星號和井號的純文字檔案。這個檔案通常就是 Markdown。它不是為 Web 寫作的唯一方式，卻是 README、問題追蹤器、聊天機器人和靜態網站的預設格式，因為它在渲染之前就能被直接閱讀。

這是一份務實的快速教學。假設你只有十分鐘和一個文字編輯器，不需要安裝任何東西。

Markdown 是什麼

Markdown 是一種輕量級標記語法。John Gruber 在 2004 年發布原始規範時只有一個目標：讓純文字看起來舒服，並且能乾淨地轉成 HTML。如今它已成為 GitHub、Obsidian、Notion、多數靜態網站產生器，以及大多數大型語言模型輸出的輸入格式。

核心思想很簡單：用標點符號而不是標籤來標記結構。

# 這是一個標題

這是一個段落。

- 這是清單項目
- 這是另一項

解析器會把這段內容轉成 HTML。不同解析器支援不同擴充功能，這正是標準變得重要的原因。

Markdown 標準很重要

Markdown 沒有唯一的官方標準。Gruber 的原始規範留有空隙，不同工具用互不相容的方式填補了它們。如果你在一個應用程式裡寫了一張表格，再貼到另一個應用程式，它可能會壞掉。所以要知道自己面向的是哪種方言。

• CommonMark。 2014 年啟動的嚴格、經過充分測試的規範，精確定義了核心語法。如果你想要可移植性，就寫 CommonMark。
• GitHub Flavored Markdown（GFM）。 增加了表格、任務清單、刪除線、圍欄程式碼區塊和自動連結。GitHub README 和 issue 留言用的就是它。
• Pandoc Markdown。 增加了引用、腳註、定義清單、上下標和數學公式。學術界很常見。
• Obsidian / Quarto / MDX。 增加了維基連結、標註、可執行程式碼單元或嵌入元件。功能強大，但可移植性差。

日常工作選 GFM 最安全。如果文件可能會在多個工具之間遷移，CommonMark 加一組有文件記錄的擴充功能是更好的選擇。

Markdown 基礎

標題

使用一到六個井號。一個井號最大。

# 一級標題

## 二級標題

### 三級標題

段落與換行

段落之間用空行分隔。行尾加兩個空格或反斜線可以強制換行。

這是第一個段落。

這是第二個段落。

強調

_斜體_ 或 _斜體_
**粗體** 或 **粗體**
**_粗體加斜體_**
~~刪除線~~（僅 GFM）

清單

無序清單用 -、* 或 +：

- 第一項
- 第二項
  - 巢狀項目

有序清單用數字：

1. 第一步
2. 第二步
3. 第三步

數字不一定要正確，渲染時 Markdown 會重新編號。不過為了讓原始碼可讀，還是建議按順序寫。

連結與圖片

[連結文字](https://example.com)
[帶標題的連結](https://example.com "標題")
![替代文字](https://example.com/image.png)

內部連結用相對路徑：

[Markdown 轉 PDF](/tools/markdown-to-pdf)

程式碼

行內程式碼用單個反引號：`console.log("hi")`。

程式碼區塊用三個反引號：

```python
def hello():
    return "hello"
```

在開頭三個反引號後面加上語言識別碼，方便語法高亮。

## 常用技巧與範例

### 引用

```markdown
> 這是一段引用。
> 它可以跨越多行。

也可以巢狀：

> 外層引用
>
> > 巢狀引用

分隔線

---

單獨一行使用三個或更多短橫線、星號或底線即可。

任務清單

GFM 支援核取方塊：

- [x] 寫完初稿
- [ ] 檢查表格
- [ ] 發布文章

它們在 HTML 裡渲染為禁用狀態的核取方塊，不能替代真正的表單輸入。

轉義字元

想讓 Markdown 符號原樣顯示，就在前面加反斜線：

\*不是斜體\*
\# 不是標題

進階技巧與範例

表格

表格是 GFM 擴充功能，不屬於原始 Markdown 規範。

| 特性     | CommonMark | GFM |
| -------- | ---------- | --- |
| 表格     | 否         | 是  |
| 任務清單 | 否         | 是  |

對齊方式是可選的：

| 靠左對齊 | 置中 | 靠右對齊 |
| :------- | :--: | -------: |
| A        |  B   |        C |

盡量保持表格簡單。巢狀表格、跨行、跨欄都不是標準特性，經常會失效。

腳註

Pandoc 和部分 GFM 解析器支援腳註：

這是一個陳述。[^1]

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

如果需要在渲染後的 PDF 裡顯示腳註，使用支援 Pandoc 風格語法的轉換器，或者手動嵌入。

數學公式

Pandoc 和許多現代編輯器支援 LaTeX 數學：

行內公式：$E = mc^2$

塊級公式：

$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$

數學渲染取決於解析器和輸出格式。HTML 通常需要 MathJax 或 KaTeX，PDF 轉換器通常需要 LaTeX 後端。

定義清單

這是 Pandoc 的另一項擴充功能：

術語
: 術語的定義。

另一個術語
: 另一個定義。

在 Markdown 中嵌入 HTML

當 Markdown 不夠用時，可以直接寫 HTML：

<p style="color: red;">這是紅色文字。</p>

這適合排版、嵌入影片或 Markdown 不支援的屬性。但它會犧牲可移植性，所以要少用。

什麼時候需要轉換 Markdown

Markdown 適合寫作和版本控制，但不適合需要在任何地方看起來都一模一樣的最終文件。因此轉換器應運而生。

如果你有一份 Markdown 草稿，想把它變成可分享的 PDF，可以使用 Markdown 轉 PDF 轉換器。它在瀏覽器中執行，檔案不會離開你的電腦。

如果你手裡是 PDF，需要可編輯的 Markdown，可以使用 PDF 轉 Markdown 轉換器。它能擷取標題、清單和段落，無需上傳到伺服器。

Markdown 速記表格

把這張表列印出來貼在螢幕旁邊，你基本不用再查 Markdown 語法。

結語

Markdown 的優點在於克制。90% 的內容用核心語法就夠了，表格、腳註和 HTML 只在文件真正需要時才拿出來。如果你堅持 CommonMark 或 GFM，文件就能在編輯器、平台和轉換器之間自由遷移，不會出意外。