Markdown 到底是怎麼運作的？

重點摘要
  • Markdown 就是少數幾個標點符號，由轉換程式把它們變成真正的 HTML。
  • 這一頁涵蓋全部核心元素：標題、強調、清單、程式碼、連結、圖片、分隔線、跳脫字元與行內 HTML。
  • 每一節都會告訴你要打哪些符號、會得到什麼結果，以及最容易出錯的地方。
  • 建議先從頭讀一遍，之後當成查詢手冊用。邊讀邊把範例貼進線上編輯器最有效。

與其說 Markdown 是一種程式或檔案格式，不如說它是一套約定：用少數幾個標點符號，在純文字裡標示文件的結構。

標題前面加 #、想強調的字用星號包起來、每行開頭加連字號變成清單。接著由轉換程式把這些符號變成真正的 HTML。這個轉換程式稱為解析器或渲染器，它輸出的就是 <h1>、<strong>、<ul> 這些標籤。

這個設計最聰明的地方在於：原始檔本身依然好讀。用任何文字編輯器打開一份 Markdown 檔案，它看起來仍然是一份排版合理的文件。

這正是它成為 README、維基、筆記軟體、靜態網站部落格與聊天平台標準格式的原因，今天寫下的檔案，三十年後照樣打得開。想了解它的來龍去脈，請讀什麼是 Markdown？；還在猶豫該直接寫 HTML 還是用 Markdown，Markdown 與 HTML 的比較會給你答案。

開始之前先說一個前提：Markdown 有「方言」。2004 年的原始規格留了不少空白，在 CommonMark 規格於 2014 年把核心語法釘死之前，各家生態系早就各自補齊了。

其中最重要的方言是 GitHub 風格 Markdown（GFM），它加入了表格、待辦清單與刪除線。本指南的所有內容在 GFM 與幾乎所有現代渲染器中都適用，包括我們的線上編輯器。每個元素也都有更完整的專頁，全部收在 Markdown 語法總覽裡。

插圖：帶有 Markdown 符號的純文字經過轉換器，變成排版精美的網頁

標題

六個標題層級

在一行開頭放 1 到 6 個井字號（#），就是第一到第六級標題。井字號和文字之間務必空一格，少了這個空格，有些渲染器會拒絕把它當標題。

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

這六行會轉換成 HTML 的 <h1> 到 <h6>。各層級的用途如下：

  • # 對應 <h1>，也就是文件標題，整份文件只用一次。
  • ## 對應 <h2>，用來切分主要章節。
  • ### 對應 <h3>，用來切分章節底下的子題。
  • #### 對應 <h4>，長篇技術文件才用得到。
  • ##### 與 ###### 對應 <h5>、<h6>，實務上幾乎用不到。

多數解析器也接受在同一行結尾再補上一串井字號，例如 ## 第二級標題 ##。結尾那串純粹是裝飾，不會出現在輸出裡。

Setext 底線式寫法

前兩級標題另有一種較舊的替代寫法，稱為 Setext：在文字下方畫一整行等號或連字號。

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

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

底線符號的數量完全不影響結果，一個 = 和二十個一模一樣。

注意：連字號版本會和分隔線撞在一起。段落下方不小心多出一行連字號，那個段落就會悄悄變成第二級標題，而不是畫出一條分隔線。

標題的最佳實務

四個習慣，可以讓標題層級乾淨又通用：

  • 一份文件只用一個第一級標題。那是文件標題，本來就只會有一個。
  • 不要跳級。h2 底下直接出現 h4，讀者和螢幕閱讀器都會混亂。
  • 標題前後各留一行空行。有些渲染器會把緊貼上下文的標題解析錯。
  • 優先用 # 寫法而不是底線寫法。它支援全部六級，而且一眼就看得出目前是第幾級。

還有一個把層級整理乾淨的理由：多數渲染器會依標題文字自動產生錨點 id，例如 ## 段落與換行 會變成可以直接連過去的錨點。標題寫得清楚又不重複，等於免費得到一整套指向文件內部的深層連結。標題語法專頁還談到錨點、大小寫與整份文件的大綱結構。

段落與換行

如何開始新段落

段落完全不需要語法：連續的文字行就是一個段落，空一行就開始新的段落。

這是第一段。

這是第二段。中間那行空行就是段落的分界。

只含空格或 Tab 的行也算空行。連續空好幾行也沒有額外效果，不論中間空幾行，結果都只是兩個段落。想要更明顯的垂直留白，該用的是分隔線或標題，而不是多按幾次 Enter。

如何強制換行

初學者最常被嚇到的是單次換行：按一下 Enter，輸出裡並不會換行。Markdown 會把只隔一個換行的多行文字接成同一個段落。

想在段落內強制換行，例如地址或詩句，請在行尾加上兩個以上的空格：

床前明月光
疑是地上霜

小提醒：那兩個空格就藏在第一行的行尾，畫面上完全看不出來。如果換行怎麼樣都不生效，把游標移到該行最後面，再按幾次右方向鍵；游標要多按兩下才跳到下一行，就表示空格確實存在。

行尾空格與 br 標籤的取捨

行尾空格看不見，而且很多編輯器、程式碼檢查工具和 commit hook 會自動把它清掉。更穩妥的做法是在行尾寫 HTML 標籤 <br>，所有 Markdown 渲染器都接受。

也有一些方言把每一次換行都當成真正的換行，大多數聊天軟體用的就是這種。自己用很方便，但只要文字可能在不同平台之間流通，就不要依賴這個行為。把兩種寫法都貼進線上編輯器，差別會立刻顯現。

注意：不要用空格或 Tab 替段落開頭縮排。行首四個空格在 Markdown 裡代表「程式碼區塊」，這是文字莫名變成等寬字型的經典原因。

強調：粗體、斜體與刪除線

粗體

用兩個星號或兩個底線包住文字就是粗體，會變成 HTML 的 <strong> 元素。

**粗體**    或  __粗體__

兩種符號可以互換，但養成用星號的習慣比較保險。底線在單字中間會失效，snake_case_names 在多數渲染器裡刻意維持原樣；星號則不受影響，fan**tas**tic 會渲染成 fantastic。

斜體

符號從兩個減成一個，就是斜體，對應 HTML 的 <em> 元素。

*斜體*      或  _斜體_

同樣的「單字邊界」規則也適用，所以星號依然是相容性最好的選擇。另外值得一提：中文字型多半沒有真正的斜體字面，瀏覽器只能用機械式傾斜模擬，所以中文內容用粗體強調通常比斜體好讀。選定一種符號，就從頭用到尾，細節可以看粗體與斜體專頁。

粗斜體

三個符號就是兩種效果疊加：***粗斜體*** 會渲染成粗斜體，也就是 <em> 包在 <strong> 裡面。

***粗斜體***
**_也是粗斜體_**

像第二行那樣刻意混用兩種符號，在強調範圍緊鄰標點時更可靠，因為解析器比較容易分辨哪一對符號要配哪一對。

刪除線

刪除線不是原始 Markdown，而是 GFM 的擴充功能，用兩個波浪號包住文字：

~~刪掉的文字~~

渲染結果是刪掉的文字。它在 GitHub、GitLab、Discord、Reddit 和我們的編輯器裡都有效，但在嚴格遵循舊規格的解析器裡不行。

以上這些符號都有兩個共通的常見錯誤：

  • 符號內側多了空格。** 粗體 ** 完全不會渲染。
  • 忘了寫收尾符號。星號會原樣留在畫面上。

哪個符號做什麼一時想不起來？一頁式語法參考有完整的對照表。

引用區塊

基本引用

在行首加一個大於符號，就是引用：

> 預測未來最好的方法，就是把它創造出來。

渲染結果是：

預測未來最好的方法，就是把它創造出來。

引用多個段落時，段落之間的空行也要加上 >。多數解析器也接受偷懶的寫法，只在每段第一行加符號，但完整標記的版本才是所有渲染器都認同的形式。

小提醒：每個引用區塊前後都要留一行空行。少了空行，有些渲染器會把相鄰的段落一併吞進引用裡，而且不會給你任何提示。

巢狀引用

引用可以巢狀：再加一個 > 就是引用中的引用，加三個就再深一層。郵件往返和討論串裡一層層的回覆，在純文字裡向來就是靠這個表現出來的。

> 原始訊息。
>
> > 針對它的回覆。

引用裡放其他元素

引用區塊裡面可以放任何其他 Markdown 元素：標題、強調、清單，甚至程式碼。記得每一行都要有 >，包括用來分隔區塊的空行。

> #### 引用裡的標題
>
> 引用的第一段，其中包含**粗體**文字。
>
> > 引用裡的巢狀引用。
>
> - 引用裡的清單項目
> - 另一個項目

引用區塊最適合用來引述郵件、標註出處，以及在技術文件裡做重點提示。GitHub 在此之上還加了警示語法：引用的第一行寫 > [!NOTE] 或 > [!WARNING]，在 GitHub 上會變成彩色提示框，在其他地方則退回成普通的引用。引用區塊專頁整理了全部的警示類型與各平台的退化行為。

清單：有序、無序、巢狀與待辦清單

無序清單

無序清單的每一行都以一個符號開頭，可以用的有三種：

  • - 連字號。這是通行的慣例，多數檢查工具預期的也是它。
  • * 星號。喜歡和強調符號一致的人常用。
  • + 加號。合法，但少見到會被誤認成打錯字。
- 第一項
- 第二項
- 第三項

小提醒：建議固定用 -。中途換符號並不會接續同一個清單，多數解析器會把前一個清單結束掉、另起一個新的，這是版面莫名多出間距、編號重新從頭算起的常見原因。

注意：清單上方一定要留一行空行。把項目符號直接接在段落下面，很多渲染器會把它併進那個段落。標題、引用和程式碼圍欄也適用同一條規則。

有序清單

有序清單以數字加句點開頭：

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

有個實用的小知識：數字本身其實不重要，只有第一個數字決定起始值。1.／1.／1. 照樣渲染成 1、2、3。

因此很多人乾脆每項都寫 1.，之後調整順序就不必重新編號。若從 5. 開始，符合規範的渲染器會輸出 <ol start="5">，這正是讓被段落打斷的清單接續編號的方法。

巢狀清單

要在清單裡再放一層清單，就把子項目縮排。四個空格（或一個 Tab）在所有渲染器都有效；兩個空格在很多渲染器可以，但不是全部。有序和無序層級可以自由混用：

1. 準備發佈
    - 更新版本號
    - 更新變更記錄
2. 正式發佈
    - 建立版本標籤
    - 推送到套件庫

想在清單項目裡面放一個段落或程式碼區塊，把它縮排到與項目文字（而不是與符號）對齊，上方再留一行空行。縮排量抓錯，這個區塊就會整個跳出清單之外。清單語法專頁把多層巢狀與混合清單講得更完整。

待辦清單

GFM 還加入了待辦清單，在 GitHub 上會顯示成可勾選的核取方塊：

- [x] 寫完指南
- [ ] 校對
- [ ] 發佈

這裡有兩條規則：方括號必須緊接在一般的清單符號後面，未勾選的方括號裡那個空格也不能省。

在 GitHub 和 GitLab 的 issue 與 pull request 裡，這些方塊可以直接點選，勾一下就會改寫底層的 Markdown，所有人都看得到。在其他平台則會退化成帶著方括號文字的普通清單。

程式碼：行內、圍欄區塊與語法上色

行內程式碼

程式碼是 Markdown 對技術寫作者最有價值的地方，規則也很單純：被標記為程式碼的內容會一字不改地以等寬字型呈現，內部的 Markdown 語法全部失效。

句子中的片段用一對反引號包住即可，例如 `npm install`。變數名稱、指令、檔名都適合用這種寫法。

如果片段本身就含有反引號，改用兩個反引號來包，並在符號內側各留一個空格，兩串反引號才不會黏在一起。想在內文中原樣展示 Markdown 符號時，行內程式碼也是最省事的辦法，不必逐一跳脫。

圍欄程式碼區塊

整段程式碼則用圍欄：在程式碼前後各放一行三個反引號。

```
沒有上色的純程式碼
```

要引用的內容本身就含有一行三個反引號怎麼辦？請改用四個以上的反引號來開頭和結尾，因為圍欄只會被「長度不小於開頭」的那一串結束掉。波浪號（~~~）同樣可以當圍欄符號，想把一個圍欄區塊包在另一個裡面時特別好用。

小提醒：開了的圍欄一定要關。沒關閉的圍欄會把整份文件剩下的內容全部吞成一個灰色區塊，而且渲染器不會提出任何警告。看到頁面從某一行以下全部變成等寬字，往上找最後一個圍欄就對了。

用語言標籤做語法上色

在開頭圍欄後面直接寫語言名稱，例如 ```python、```js 或 ```bash，支援語法上色的渲染器就會替程式碼上色，包括 GitHub、GitLab、多數靜態網站產生器和我們的編輯器。

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

最常用到的標籤大致是這幾類：

  • python、js、ts、go、rust 等語言名稱，拼法要照上色工具認得的寫。
  • bash 或 sh，用於指令與終端機畫面。
  • json、yaml、html、css、sql，用於資料與標記語言。
  • diff，會把新增與刪除的行分別標成綠色和紅色。
  • text，用在根本不是程式碼的內容，例如日誌輸出。

小提醒：養成每次都加語言標籤的習慣。不支援的環境會直接忽略它，完全沒有壞處；寫了不認識的標籤也只是被忽略，不會弄壞區塊。

不少生態系還會沿用這個位置放額外資訊，例如在語言名稱後面接上檔名或要標示的行號範圍。程式碼區塊專頁整理了各大平台認得的語言識別字。

四空格縮排的舊寫法

最初的替代寫法至今仍有效：把整段程式碼每行縮排四個空格，不需要圍欄。

但實務上圍欄已經完全勝出：貼上程式碼不必重新縮排、可以標語言、也不會誤觸。

四空格規則現在反而主要以陷阱的形式存在：把普通段落縮排，就會冒出一個意料之外的程式碼區塊。若你常寫程式碼密集的文件，可列印的語法表把三種寫法都整理在一眼可及的位置。

插圖：帶有彩色語法上色的程式碼區塊，被反引號組成的圍欄框住

圖片

圖片語法

圖片就是前面多一個驚嘆號的連結。方括號放替代文字（alt text），圓括號放圖片網址，後面可以再加引號包住的標題：

![分割畫面的 Markdown 編輯器](/img/md-editor-screenshot.png "MD Editor 實際畫面")

圖片同樣支援參考式定義，可以把冗長的檔案路徑挪出內文。也要記得相對路徑是相對於「渲染後的網頁」而不是原始檔，所以在自己電腦上看起來正常的 README 圖片，發佈到網路上之後仍可能斷掉。圖片語法專頁把代管、路徑與尺寸問題講得更細。

替代文字為什麼重要

替代文字千萬不要留空。它是螢幕閱讀器朗讀的內容、搜尋引擎索引的依據，也是圖片載入失敗時顯示的文字。

請用一句話描述圖片內容，就像在電話裡講給別人聽。![截圖] 太敷衍；![左側是 Markdown 原始碼、右側是渲染預覽的並排編輯器] 才到位。

唯一合理的例外是純裝飾用的圖片：這時刻意留空的替代文字等於告訴螢幕閱讀器「跳過它」，而不是讓它把檔名唸出來。

可點擊的圖片

想讓圖片可以點擊，把圖片語法整個放進連結的方括號裡：

[![MD Editor 預覽](/img/thumb.png)](https://mdeditor.tw/)

README 最上方那一排徽章就是這樣做出來的：每個徽章都是一張小圖片，外面再包一層連到對應服務的連結。這種寫法的替代文字一樣重要，因為那正是螢幕閱讀器唸出來代表這個連結的文字。

控制圖片尺寸

Markdown 本身無法調整圖片大小或對齊，因為根本沒有寬度語法。需要 width="400" 或置中時，就得改用 HTML 的 <img> 標籤，詳見下方的行內 HTML 章節，更完整的討論在Markdown 與 HTML 的比較。

少數生態系發明了自己的縮寫語法，GitHub 也接受純 HTML 以及加在圖片網址後面的查詢參數，但這些都不通用。請把 HTML 標籤當成唯一能跨平台使用的做法。

分隔線

單獨一行、連續三個以上的連字號、星號或底線，就是一條水平分隔線（HTML 的 <hr>）：

---

***

___

三種寫法的渲染結果完全相同，選一種用到底即可。

注意：--- 如果緊貼在一行文字下方，就變成了標題章節提過的第二級標題替代寫法：上面那行文字會變成標題，而不是出現分隔線。只要分隔線前後都留空行，這個歧義就不存在。

分隔線請節制使用，主要主題之間放一條就夠了。多數情況下用標題來分段更好，因為標題還能替該段落命名。

用反斜線跳脫特殊字元

反斜線跳脫

有時你就是想顯示一個星號、井字號或方括號本身，不希望 Markdown 解讀它。在字元前面加一個反斜線，就能跳脫它：

\*不是斜體\* - 星號會原樣顯示

\# 不是標題

1\. 不是清單項目，只是以「1.」開頭的句子。

在沒有特殊意義的字元前面加反斜線，多數解析器會原樣保留，所以正規表示式裡的 \d 通常不會被吃掉。不過這只是慣例而非保證，這也是「符號密集的內容請用程式碼標記包起來」的另一個理由。

哪些字元可以跳脫

可以用反斜線跳脫的字元共有十六個：

  • \ 反斜線與 ` 反引號
  • * 星號與 _ 底線
  • { } 大括號
  • [ ] 方括號
  • ( ) 圓括號
  • # 井字號、+ 加號與 - 連字號
  • . 句點、! 驚嘆號與 | 直線

實務上最常用到的情境有四種：內文中的星號、行首的井字號、會意外變成有序清單的「數字加句點」，以及表格儲存格裡的直線符號。

還有兩個相關提醒。在行內程式碼和程式碼區塊裡，任何字元都不需要跳脫，這正是它們的用途；遇到符號很多的內容，用程式碼標記通常是更乾淨的解法。至於反斜線本身，用另一個反斜線跳脫它：\\。

若遇到不在上述清單裡的字元，例如想顯示角括號而不是被當成標籤，就改用 HTML 實體 &lt;。

行內 HTML：預留的逃生門

什麼時候該用 HTML

Markdown 的作者刻意留了一道逃生門：在 Markdown 文件裡輸入的任何 HTML，都會原封不動地進入輸出。每當 Markdown 沒有對應語法時，這就是解答：

  • <u> 底線文字，Markdown 沒有對應符號。
  • <kbd> 鍵盤按鍵，寫快捷鍵清單時很好用。
  • <sup> 與 <sub> 上標與下標。
  • <img width="400"> 指定尺寸的圖片。
  • <details> 與 <summary> 摺疊區塊，GitHub README 上隨處可見。

把 HTML 當調味料，不要當主菜。每多一個標籤，原始檔就少一分可讀性，而可讀性正是 Markdown 存在的理由。

如果你發現自己寫的標籤比內文還多，也許你真正需要的是一份 HTML 文件；Markdown 與 HTML 的比較詳細分析了這條界線在哪裡。對多數人來說，一份文件裡誠實的用量大概是兩三個 <br> 和 <details>，其餘全部交給 Markdown。

怎麼寫才安全

混用的主要規則和空行有關：區塊層級的 HTML（<div>、<table>、<details>）前後要用空行和周圍的 Markdown 隔開。

也不要期待這些區塊內部的 Markdown 語法還有效，傳統解析器在區塊層級標籤裡會關閉 Markdown 解析。至於 <kbd>、<sup> 這類行內標籤，直接寫在句子中間即可，沒有任何額外規矩。

開了的標籤一律要關，連 HTML 本身容許省略的也別省；屬性值也一律加上引號。一個沒關的 <div> 可能把整頁剩下的內容全部吞進去，而且渲染器把這個區塊視為不透明，永遠不會給你任何警告。

渲染器會濾掉什麼

有些環境基於安全考量會把 HTML 全部濾掉，Reddit、許多聊天軟體和部分靜態網站設定都是如此。周圍的 Markdown 要寫成「標籤消失後照樣讀得通」的樣子。

有些則是選擇性過濾：GitHub 保留 <details>、<kbd> 和指定尺寸的圖片，但會移除 <script>、<style>、表單元件和大多數行內 style 屬性。

比較安全的假設是：只要超出單純的呈現用標記，總會在某個平台被丟掉。重要的頁面請直接在最終發佈的那個渲染器上測試，單一預覽畫面不算數。兩套工具吵起來時，Babelmark 可以把同一段輸入丟給數十種解析器一次比對，最快分出勝負；整份檔案則可以上傳到Markdown 檔案檢視器，提交前快速確認。

插圖：一個 HTML 標籤像拼圖一樣，嵌進純文字的 Markdown 文件中

最佳實務與常見錯誤

最佳實務

以下是讓文件在各種渲染器之間都穩定可攜的好習慣，每一項在 Markdown 語法總覽裡都有更完整的專頁：

  • 每個區塊前後都留空行 - 標題、清單、引用、程式碼圍欄、表格。零成本，卻能消除絕大多數解析器之間的歧異。
  • 保持一致：一種清單符號（-）、一種強調符號（*）、# 式標題、帶語言標籤的圍欄程式碼。
  • 只用一個 h1、不跳級 - 對讀者、螢幕閱讀器和 SEO 都好。
  • 每張圖片都寫出有意義的替代文字，不要只放檔名。
  • 發佈前先預覽。把草稿貼進線上編輯器，預覽會隨每次按鍵即時更新。

常見錯誤

世界上絕大多數的 Markdown 問題，都出自下面這張短清單。出錯時先對照這裡：

#標題              ← # 後面少了空格 - 不會渲染
** 粗體 **         ← 符號內側有空格 - 不會渲染
1) 項目            ← 請用「1.」而不是「1)」，相容性較好
  - 子項目         ← 兩空格縮排在部分渲染器會失效；請用四個
文字
- 清單項目         ← 清單前少了空行 - 可能不會渲染

文件渲染結果不對時，照這個順序檢查：

  1. 確認 # 或清單符號後面有沒有漏掉空格。
  2. 確認清單、引用、程式碼圍欄的上方有沒有留空行。
  3. 確認每個程式碼圍欄和每一組強調符號都有收尾。
  4. 確認巢狀清單縮排的是四個空格，而不是兩個。
  5. 把出問題的段落貼進即時預覽，每次刪掉一半，很快就能定位。

這些錯誤有個共通點：它們都不會跳出任何錯誤訊息，只是安靜地渲染成你沒預期的樣子。所以發佈前掃一眼預覽，永遠比事後回頭查原因划算得多。

接下來，把快速參考表加入書籤方便隨時查閱，再學會 GitHub 上一定會遇到的 GFM 擴充語法；需要以列與欄呈現資料時，表格指南涵蓋了對齊、跳脫直線符號等表格的一切。

常見問題

我該學哪一種 Markdown 方言？

先學本指南的核心語法 - 它在任何地方都通用 - 再補上 GitHub 風格 Markdown（GFM），它增加了表格、待辦清單、刪除線與自動連結。GitHub、GitLab 和多數現代軟體渲染的都是 GFM，實質上就是業界標準。

為什麼按一次 Enter 換行會不見？

這是刻意的設計：單次換行不會換行，Markdown 會把相鄰的行接成同一個段落。想開新段落就空一行；想在段落內強制換行，就在行尾加兩個空格，或寫一個 <br> 標籤。

為什麼我的巢狀清單縮排無效？

幾乎都是縮排量的問題：兩個空格不是每個渲染器都認得。把子項目縮排四個空格（或一個 Tab）就能在所有環境正常巢狀。也請確認清單和上方段落之間有留一行空行。

Markdown 要怎麼做表格？

表格是 GFM 的擴充功能：用直線符號（|）分隔欄位、用連字號畫出表頭列、用冒號控制對齊。內容多到值得獨立成一頁 - 請看完整的 Markdown 表格指南，附可直接複製的範本。

可以在 Markdown 文件裡混用 HTML 嗎？

可以 - HTML 會原封不動地進入輸出。用它來補足 Markdown 缺少的功能（底線、<kbd>、圖片尺寸、可摺疊的 <details>）。區塊層級的標籤前後要留空行，也要注意部分平台基於安全會把 HTML 濾掉。

哪裡可以練習這些語法？

在我們免費的線上 Markdown 編輯器 - 把指南裡的任何範例貼進去，就能即時看到渲染結果。你輸入的內容不會離開瀏覽器，草稿也會自動存在本機。

Markdown 要怎麼把文字註解掉？

Markdown 沒有官方的註解語法，所有做法都是變通。最常見的是 HTML 註解 <!-- 像這樣 -->，渲染器不會把它顯示在頁面上。另一招是寫一個沒人用到的連結參考定義，例如 [note]: # (提醒自己)，因為沒有任何連結指向它，所以不會印出任何東西。兩種都不是真的隱藏，打開原始檔的人照樣看得到，所以註解請當成寫給自己的備忘，不要放祕密。

Markdown 要怎麼換行？

在行尾打兩個空格再按 Enter，下一行就會落在同一個段落裡換行。但空格是看不見的，很多編輯器還會自動清掉，所以行尾直接寫 <br> 更可靠。如果你要的是全新的段落，就空一行，這在多數情況下才是正確答案。三種寫法在語法速查表裡並排列出。

Markdown 要怎麼跳脫特殊字元？

在字元前面加一個反斜線，例如 \*不是斜體\* 會原樣印出星號，而不是把文字變斜體。凡是 Markdown 當成語法的字元都適用：\ ` * _ { } [ ] ( ) # + - . !，以及表格裡的直線符號。反斜線放在普通字元前面通常會被原樣保留，但那只是慣例，不是保證。像正規表達式這種符號密集的文字，直接用反引號包起來比一個個數反斜線安全。

Markdown 的 front matter 是什麼？

front matter 是寫在 Markdown 檔案最前面的一段設定，上下各用一行三個連字號框起來，內容通常是 title、date、tags 這類 YAML 欄位。它並不屬於 Markdown 語法本身，而是 Jekyll、Hugo、Astro 這些靜態網站產生器共用的慣例，由它們讀走，不會印在頁面上。碰到沒聽過這個慣例的渲染器，整段設定就會被當成一般文字印出來，有時甚至會被畫成一張表格。那三個連字號和文章中段用來畫 setext 標題的符號一模一樣，這個衝突在標題語法指南裡講得很清楚。

Markdown 的段落要怎麼縮排？

沒辦法，Markdown 根本沒有段落縮排的語法。最多人踩到的坑是開頭空四格：那不會縮排，而是把整行變成程式碼區塊，用等寬字體框起來。真正可行的只有三招：寫原生 HTML（例如 <p style="text-indent:2em">）、用引用區塊做出一點內縮效果，或是在你能控制樣式的頁面上直接寫 CSS。

Markdown 有分大小寫嗎？

語法本身不分：# 標題 不管大小寫怎麼打，結果都一樣，程式碼圍欄後面的語言名稱（Python 和 python）一般也是忽略大小寫比對的。不過語法周邊有兩件事會分大小寫。標題自動產生的錨點一律轉成小寫，所以連到 #Setup 會找不到實際位在 #setup 的標題。真正會咬人的是連結和圖片裡的檔案路徑：Linux 伺服器把大小寫當一回事，macOS 和 Windows 通常放你一馬，所以 Logo.png 在你電腦上好好的，一上線就變破圖。

延伸閱讀

Markdown 語法速查表

所有語法濃縮成一頁 - 寫作時放在手邊隨查隨用的快速參考。

GitHub 風格 Markdown

表格、待辦清單、刪除線與自動連結 - GitHub 增加的擴充語法與用法。

Markdown 表格指南

建立、對齊表格與跳脫直線符號，附常見版面的可複製範本。

立即使用編輯器

立即使用編輯器