發布於 2026-03-23

Markdown 語法完全指南：從入門到實戰應用

Markdown 寫作工具 前端開發 文件撰寫 效率工具

你是否曾在 GitHub 上看到格式整齊的 README 檔案，或是在 Notion 筆記裡用簡單符號排出漂亮標題，卻不知道背後那套語法叫什麼名字？那就是 Markdown——一種誕生於 2004 年、如今已滲透進幾乎所有數位寫作場景的輕量級標記語言。本文將帶你從歷史背景到語法細節，再到實際應用場景，完整認識 Markdown 的一切。

一、Markdown 是什麼？從一個故事說起

2004 年，美國作家兼程式設計師 John Gruber 和知名資安研究員 Aaron Swartz 共同設計了 Markdown。Gruber 當時的出發點很簡單：當他在寫文章時，需要一種語法讓純文字檔案「讀起來也很舒服」，同時又能一鍵轉換成乾淨的 HTML，省去手動套標籤的繁瑣。他把這套語法命名為 Markdown，語意上是 Markup（標記語言，例如 HTML）的「反義」——用最少的符號做到最多的格式表達。

Markdown 的核心設計哲學有三點：純文字優先（任何文字編輯器都能開啟與編輯，不綁定專屬軟體）、視覺直覺（語法符號的形狀本身就暗示了它的功能，例如 **粗體** 就像被強調了兩次）、可轉換性（Markdown 文件可輸出為 HTML、PDF、Word、LaTeX 等多種格式）。

二十多年後的今天，Markdown 已成為 GitHub、GitLab、Stack Overflow、Reddit、Discord、Notion、Obsidian、Confluence、Jira、VS Code 原生文件系統乃至各大部落格平台的標準寫作語言。學好 Markdown，等於學了一項橫跨開發、寫作、協作三個領域的通用技能。

二、為什麼選擇 Markdown 而非 Word 或直接寫 HTML？

這個問題值得認真回答，因為選擇工具應該基於情境，而非盲目跟風。以下是三種格式各自的定位：

格式 最適合情境 主要優點 主要限制
Word / Google Docs 商業文件、合約、正式報告 所見即所得、複雜版面、Track Changes 綁定軟體、格式易亂、Git 版本控管困難
HTML 需要精確控制樣式的網頁 完全控制、瀏覽器原生支援 語法冗長、閱讀原始碼不直覺
Markdown 技術文件、README、部落格、筆記 純文字、輕量、易讀、版本控管友好 複雜版面（多欄、精確定位）需借助 HTML

Markdown 的殺手級優勢在於它是純文字。純文字檔案可以：用 git diff 追蹤每一行的修改歷程；在任何裝置、任何作業系統用任何編輯器開啟；透過命令列工具（Pandoc、Hugo、Jekyll、MkDocs）批次轉換格式；輕鬆搜尋與替換。這些特性讓 Markdown 成為技術寫作、開源文件、個人知識管理的首選。

三、基本語法：標題、段落、文字樣式

所有 Markdown 語法都圍繞著「在純文字中插入特定符號」的核心原則。讓我們從最常用的三類開始。

標題（Headings）

Markdown 使用井字符號 # 來定義標題層級，數量對應 HTML 的 H1 到 H6：

# H1 一級標題（通常為頁面主標題，每頁建議只有一個）
## H2 二級標題（主要章節）
### H3 三級標題（子章節）
#### H4 四級標題
##### H5 五級標題
###### H6 六級標題

實踐建議：文章的 H1 通常讓平台自動從文章標題生成；正文章節從 H2 開始使用；不要跳階（例如從 H2 直接跳到 H4），否則會破壞無障礙閱讀工具的文件結構解析。

段落與換行

Markdown 中，一般段落就是連續的文字行，段落之間用空行分隔（不是單次 Enter，而是留一個完全空白的行）。若想在同一段落內強制換行，在當前行末尾加兩個空格再按 Enter，或直接使用 <br> HTML 標籤。

文字樣式：粗體、斜體、刪除線

**粗體文字** 或 __粗體文字__
*斜體文字* 或 _斜體文字_
***粗斜體文字*** 或 ___粗斜體___
~~刪除線文字~~

注意：底線語法（__粗體__、_斜體_）在部分平台（例如 Slack）的行為與其他平台略有不同，若跨平台使用建議統一改用星號語法。

四、列表：有序、無序與巢狀

列表是 Markdown 最高頻使用的元素之一。Markdown 支援三種列表形式。

無序列表（Unordered List）

使用 -、* 或 + 開頭均可（同一份文件建議統一）：

- 第一項
- 第二項
- 第三項

有序列表（Ordered List）

使用數字加句點，數字的實際值在大多數渲染器中不影響最終輸出（都會從 1 開始重新計數），但建議維持正確順序以保持原始碼可讀性：

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

巢狀列表（Nested List）

在子項目前縮排 2 到 4 個空格即可建立巢狀結構，無序與有序可以混用：

- 前端技術
  - HTML
  - CSS
  - JavaScript
    1. 變數與型別
    2. 函式
- 後端技術
  - Node.js
  - PHP

五、連結與圖片

Markdown 的連結語法採用「文字 + URL」分離的設計，閱讀原始碼時不會被長網址干擾視線。

連結（Link）

[顯示文字](https://example.com)
[顯示文字](https://example.com "滑鼠 hover 時的 title 提示")


[顯示文字][ref-id]

[ref-id]: https://example.com "參考連結說明"

圖片（Image）

圖片語法與連結幾乎相同，只是在最前面加上驚嘆號 !：

![替代文字](https://example.com/image.png)
![替代文字](./local-image.png "圖片標題")

無障礙重點：一定要填寫有意義的替代文字（Alt Text），這是螢幕閱讀器使用者感知圖片的唯一途徑。不要寫「image.png」這樣無意義的描述，而是寫「網站架構示意圖」這樣具說明性的文字。

六、程式碼：行內程式碼與圍欄程式碼區塊

程式碼是技術文件的靈魂，Markdown 對程式碼的支援相當完善。

行內程式碼（Inline Code）

用反引號 `` ` `` 包住短程式碼或指令名稱：

請執行 `npm install` 後再啟動 `npm run dev`。

若行內程式碼本身包含反引號，改用兩個反引號包住：``這裡可以放 ` 反引號``。

圍欄程式碼區塊（Fenced Code Block）

用三個反引號 ``` 開頭與結尾，並在開頭行指定語言名稱以啟用語法高亮：

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

console.log(greet('Markdown'));
```

常用語言識別碼：javascript（或 js）、typescript（或 ts）、python、php、bash（或 sh）、css、html、json、yaml、sql、markdown。不指定語言時仍會套用等寬字型，只是沒有顏色高亮。

七、引用區塊（Blockquote）

引用區塊用於標示引述他人的話、警告提示、重要說明等場景，語法是在每行開頭加上 >：

> 「寫作對我來說是探索自己思想的方式。」
> ——E. M. Forster

> **注意**：這個 API 在 v3.0 後已廢棄，
> 請改用 `newFeatureApi()`。

> 引用區塊也可以巢狀：
> > 這是二層引用。
> > > 這是三層引用。

許多平台（如 GitHub）會對以 [!NOTE]、[!WARNING]、[!TIP] 開頭的引用區塊套用特殊視覺樣式（稱為 Alerts），是技術文件常見的提示框寫法。

八、表格（Tables）—— GFM 延伸語法

標準 Markdown 規範（CommonMark）不包含表格語法，但 GitHub Flavored Markdown（GFM）對此做了擴充，已被廣泛平台採用：

| 語言       | 類型       | 初學難度 |
| ---------- | ---------- | -------- |
| Python     | 直譯       | 低       |
| JavaScript | 直譯       | 中       |
| Rust       | 編譯       | 高       |
| Go         | 編譯       | 中低     |

冒號（:）可控制對齊方式：

  • :--- 靠左對齊（預設）
  • ---: 靠右對齊
  • :---: 置中對齊

實用建議：手動對齊表格管線（|）會讓原始碼更易讀，但非必要——Markdown 渲染器不在乎管線是否對齊。若頻繁需要撰寫複雜表格，推薦使用有表格 GUI 的 Markdown 編輯器（例如 Typora、本站的線上 Markdown 編輯器）。

九、進階語法

任務清單（Task List）—— GFM 語法

在無序列表項目前加上 [ ]（未完成）或 [x]（已完成）：

- [x] 閱讀 Markdown 指南
- [x] 安裝 VS Code
- [ ] 設定 Prettier 格式化
- [ ] 提交第一個 Pull Request

GitHub、GitLab、Notion、Obsidian 等平台會將任務清單渲染為可點擊的核取方塊，是追蹤待辦事項的輕量方式。

水平分隔線（Horizontal Rule）

用三個以上的連字符、星號或底線獨立成行，即可建立水平分隔線：

---
***
___

三者效果相同，建議在文章中統一使用一種以維持一致性。

混用 HTML

Markdown 允許在文件中直接插入 HTML 標籤，Markdown 渲染器通常會原樣輸出：

這是普通段落。

<details>
<summary>點我展開詳細說明</summary>
這是折疊的內容，只有點擊後才會顯示。
</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd> 複製

注意：基於安全考量，部分平台（例如 GitHub Comments）會過濾掉 <script>、<style> 等潛在危險標籤，HTML 混用的效果因平台而異。

跳脫字元（Escaping）

若需要在文件中顯示 Markdown 的特殊符號而不觸發語法，在符號前加上反斜線 \：

\*這段文字不會變成斜體\*
\# 這不會成為標題
\[這不是連結語法\]

十、Markdown 方言與規範演進

Markdown 的原始規範（由 Gruber 定義）存在部分模糊之處，導致不同渲染器的行為差異頗大。多年來社群陸續推出了更嚴格的規範版本：

  • CommonMark：由 Jeff Atwood（Stack Overflow 創辦人）等人推動的標準化規範，定義明確、測試完整，是最多工具採用的基礎規範。
  • GFM（GitHub Flavored Markdown）：GitHub 在 CommonMark 基礎上新增表格、任務清單、Alerts 等擴充語法，已成事實上的業界標準。
  • MDX：結合 Markdown 與 JSX（React 元件語法），允許在 Markdown 文件中直接嵌入互動元件，廣泛用於 Next.js、Astro 等現代前端框架的文件系統。
  • R Markdown / Quarto：學術界與資料科學領域常用，支援在文件中嵌入可執行的 R、Python 程式碼及圖表輸出。

選擇使用哪種方言取決於你的目標平台。對大多數人來說，學好 CommonMark + GFM 足以應付 90% 的使用場景。

十一、Markdown 的主要應用場景

1. GitHub / GitLab 專案文件

這是 Markdown 最主流的應用場景。README.md 是開源專案的「門面」，優質的 README 應包含：專案簡介（What）、安裝說明（How to install）、使用範例（How to use）、授權資訊（License）、貢獻指引（Contributing）。許多專案還會用 Markdown 撰寫 CHANGELOG.md（版本更新紀錄）、CONTRIBUTING.md（貢獻者指引）和 CODE_OF_CONDUCT.md（行為守則）。

2. 個人知識管理（PKM）

Obsidian、Logseq、Joplin、Foam（VS Code 外掛）等工具都以 Markdown 為核心儲存格式。純文字的好處是：即使你未來換了工具，筆記檔案仍然可以直接閱讀，不存在供應商鎖定（Vendor Lock-in）問題。許多人用 Markdown 建立個人維基、日誌系統（Journaling）、閱讀筆記、研究資料庫。

3. 技術部落格與靜態網站

Hugo、Jekyll、Hexo、Eleventy、Astro、Next.js 等靜態網站生成器都以 Markdown 作為文章格式，前面可以加上 YAML Front Matter（以 --- 包圍的元資料區塊）指定標題、日期、標籤、封面圖等資訊：

---
title: "Markdown 語法指南"
date: 2026-03-23
tags: ["Markdown", "寫作"]
draft: false
---

正文從這裡開始...

4. 協作工具與即時通訊

Notion、Confluence、Jira 支援 Markdown 輸入；Slack、Discord、Microsoft Teams 也支援 Markdown 的子集（粗體、斜體、程式碼、引用等），讓你在聊天訊息中快速套用格式。

5. API 文件與技術規格

Swagger / OpenAPI 規範、GitHub API 回傳的 Markdown 欄位、npm 套件的 package README，乃至各大雲端服務（AWS、GCP、Azure）的官方文件，都廣泛使用 Markdown。熟悉 Markdown 能讓你更快速閱讀、撰寫與維護技術規格。

十二、常見陷阱與最佳實踐

以下是初學者最常踩到的坑，以及對應的解決方式：

陷阱 1：段落沒有空行隔開

直接在兩段文字之間按一次 Enter，大多數渲染器不會換段，而是當作同一段落的連續文字。必須留一個完全空白的行才能分段：


第一段文字
第二段文字


第一段文字

第二段文字

陷阱 2：標題 # 後面忘記加空格

#標題 在嚴格的渲染器中不會被識別為標題，必須寫成 # 標題（井字號後加一個空格）。

陷阱 3：過度嵌套列表

巢狀列表超過三層時，可讀性會急速下降。若結構真的複雜，考慮改用標題 + 表格的組合來呈現層次關係。

陷阱 4：混用不同風格的列表符號

在同一份文件中混用 -、*、+ 作為無序列表符號，視覺上沒有差異，但會降低原始碼可讀性。選定一種後保持一致。

陷阱 5：不注意平台差異

同樣的 Markdown 在不同平台的渲染結果可能不同。例如：GitHub 支援 ~~刪除線~~，但部分平台不支援；Notion 支援雙方括號的內部連結語法，但這是 Notion 專屬，放到 GitHub 就失效。養成「在目標平台預覽後再發布」的習慣。

最佳實踐小結

  • 使用具有即時預覽功能的編輯器（如本站線上 Markdown 編輯器、VS Code + Markdown Preview Enhanced）撰寫，可立即確認渲染效果。
  • 長文建議按章節拆分，再用工具（如 Pandoc）合併輸出，避免單一 Markdown 檔案過長難以維護。
  • 圖片建議使用穩定的 CDN URL 而非相對路徑，以確保在不同環境下仍可正確顯示。
  • 為 Markdown 設定 Linting（如 markdownlint），統一規範整個團隊的風格，避免貢獻者之間因格式差異產生不必要的 diff。
  • 版本控管 Markdown 文件時，以一句話為一行（Semantic Line Break）可讓 git diff 的輸出更精準，便於 Code Review。
立即動手試試看
開啟本站的線上 Markdown 編輯器，把本文的任何程式碼範例貼進去，左側輸入、右側即時預覽——這是學習 Markdown 最快的方式，比反覆閱讀有效十倍。

結語

Markdown 的魅力在於它的「低起點、高天花板」：五分鐘內就能掌握基本語法應付日常需求，但隨著深入使用，你會發現它與 Git、靜態網站生成器、知識管理系統、CI/CD 文件流程的結合可以構建出非常強大的工作流。

更重要的是，Markdown 讓你的專注力回歸到內容本身——不需要費心調整字型、點選工具列、擔心跨平台格式跑版，只需要打字，其餘的交給工具處理。這才是一個好的寫作工具應該做到的事：它的存在感越低，你的思路就能流動得越順暢。

現在，拿起你慣用的編輯器，建立一個 .md 檔案，寫下你的第一篇 Markdown 文章吧。

相關工具

線上 Markdown 編輯器 文字差異比對
← 回到知識庫