行內連結：九成場合都用它

最基本的寫法是：方括號包住要顯示的文字，緊接著用小括號包住目的地網址：

建議先讀 [Markdown 指南](https://mdeditor.tw/zh/markdown-guide)。
重點摘要
  • 方括號放文字、小括號放網址，兩者之間不能有空格。
  • 參考式連結能把又長又重複的網址集中到檔案底部。
  • 錨點 ID 是把標題轉小寫、移除標點、再把空格換成連字號得到的。
  • 中文輸入法打出的全形括號看起來沒問題，實際上完全不會渲染。

為什麼一個空格就會壞掉

] 和 ( 之間不能有空格。那一個空格是 Markdown 連結最常見的失敗原因，而且它不會報錯，只會在正文中間留下裸露的括號。

加上 title 屬性

網址後面加一段用引號包住的文字，會變成 HTML 的 title 屬性，滑鼠停留時顯示成提示泡泡：

[Markdown 指南](https://mdeditor.tw/zh/markdown-guide "每個元素都有說明")

單引號和小括號也能當分隔符號，但雙引號是慣例。title 請節制使用：觸控裝置上看不到提示泡泡，螢幕閱讀器也不保證會朗讀，所以它不能承載連結文字沒交代的資訊。

連結文字裡的格式

連結文字接受行內 Markdown，可以只強調其中一部分，規則就是粗體與斜體參考裡那一套：

請參考[**必填**的 `--force` 參數](https://example.com/docs/flags)。

但連結不能巢狀包在另一個連結裡。解析器會在第一個能配對的 ] 收尾，畫面上留下一個斷掉的半截連結。

插圖：裝著連結文字的方括號，用鎖鏈連向裝著網址的小括號

參考式連結，以及它什麼時候真的有用

參考式連結把標籤和目的地分開。你在正文寫 [文字][識別碼]，再在文件其他地方定義 [識別碼]: 網址：

[樣式指南][style]與[API 參考][api]都由同一份原始碼產生，
而[樣式指南][style]每一季都會重新審視。

[style]: https://example.com/handbook/style-guide
[api]: https://example.com/developers/reference/v3/endpoints

定義本身不會出現在輸出結果裡，位置也很自由，慣例是放在檔案最後，而且識別碼不分大小寫。

兩種簡寫，其中一種有風險

  • 收合式寫法 [Markdown 指南][]，直接拿連結文字當識別碼。
  • 捷徑式寫法 [Markdown 指南]，連第二組方括號都省略，只要有同名定義就能生效。

捷徑式很優雅，但風險也在這裡：一旦有人加了同名定義，任何被方括號包住的詞都會突然變成連結。

什麼時候值得用

參考式連結在三種情況下最划算：

  • 同一個網址重複出現，你希望只在一個地方更新。
  • 網址長到會毀掉整行版面，原始碼變得難讀。
  • 文件會以 diff 形式審閱，改網址只動到檔案底部一行，而不是動到正文。

至於一次性的連結，行內寫法更簡單。Markdown 完整指南裡的範例也是這個原則：網址不重複就用行內。

相對路徑與絕對網址

絕對網址包含協定與網域，從任何地方指過去意義都相同，例如 https://example.com/docs/setup。相對網址則相對於「目前這份文件所在的位置」解析，這既是它的優點也是它的問題。

[貢獻指南](CONTRIBUTING.md)
[安裝說明](docs/setup.md)
[回到根目錄的 readme](../README.md)

儲存庫畫面與發佈後的網站

在 GitHub 儲存庫裡，上面的寫法完全正確，因為 GitHub 以該檔案所在目錄為基準解析路徑。

麻煩出現在同一批檔案被靜態網站產生器發佈之後。多數產生器會把 docs/setup.md 改寫成 /docs/setup/ 這種乾淨網址，於是你手寫的 setup.md 連結在正式站上可能變成 404。MkDocs 與 Docusaurus 會替你自動改寫 .md 目標，所以它們的文件才叫你保留副檔名；其他組合就不一定了。

三條值得背下來的路徑規則

  • 儲存庫內不要加開頭斜線。在瀏覽器裡 /docs/setup 指的是網域根目錄，在儲存庫畫面裡卻可能被解析成儲存庫根目錄。
  • 會出現在兩個地方的內容就用絕對網址，例如同時顯示在 npmjs.com 上的 README。
  • 大小寫要完全一致。託管靜態網站的伺服器多半區分大小寫，即使你的筆電不是；Setup.md 與 setup.md 在本機是同一個檔案，在正式環境卻是兩個網址。
插圖：左邊是資料夾樹狀結構，右邊是已發佈的網站，兩者之間由兩條不同顏色的連結路徑串起

跳到標題的錨點連結

錨點連結是跳到頁面內的某個標題，而不是載入新頁面。目的地是一個 # 加上該標題自動產生的 ID：

可直接跳到[安裝](#installation)或[疑難排解](#troubleshooting)。

這些 ID 不需要你自己建立：GitHub 與多數渲染器會替每個標題產生一個，規則簡單到你可以手動推導。同一套規則從標題那一側的說明，請見標題參考。

標題 ID 是怎麼產生的：實例推導

以這個標題為例：

## Setting Up Your API Key (v2)

渲染器依序做四件事：

  1. 去掉標題符號，剩下 Setting Up Your API Key (v2)
  2. 全部轉成小寫：setting up your api key (v2)
  3. 移除標點，只留字母、數字、空格、連字號與底線：setting up your api key v2
  4. 把空格換成連字號：setting-up-your-api-key-v2

所以連結要這樣寫：

[設定你的金鑰](#setting-up-your-api-key-v2)

重複標題、中文標題與其他渲染器

  • 文字相同的第二個標題會加上 -1，第三個加 -2。
  • 中日韓文字在 GitHub 上會被保留，所以 ## 安裝步驟 的 ID 就是 #安裝步驟。
  • 表情符號與大多數符號會被整個移除。
  • 各渲染器的 slug 規則略有差異，用猜的並不可靠。

小提醒：跳轉連結沒反應時，別再猜 slug 了。打開渲染後的頁面，把滑鼠移到標題上，直接從旁邊的連結圖示複製錨點。五秒鐘的事，而且不會錯。

連到另一份文件裡的標題

把路徑和片段組合起來即可。前一節的路徑規則依然適用，片段則由那份文件的標題產生：

[安裝 CLI](docs/setup.md#installing-dependencies)
[流量限制](https://example.com/api/reference#rate-limits)

這是多檔案文件導覽的骨幹。連到章節比連到整份檔案更有用，因為讀者會被直接送到正確的段落。

刁鑽網址、跳脫，以及在新分頁開啟

網址裡有空格

空格會終止目的地，所以 [報告](my report.pdf) 會壞掉。解法有兩個：把空格做百分比編碼（可攜性最好），或用角括號把目的地包起來（CommonMark 與 GitHub 都支援）：

[第三季報告](my%20report.pdf)
[第三季報告](<my report.pdf>)

網址裡有小括號

右小括號可能讓連結提前結束。CommonMark 允許成對的括號，所以結尾是 _(disambiguation) 的維基百科網址在 GitHub 上通常沒事；不成對的括號一定會壞，較舊的渲染器則兩種都會壞。用反斜線跳脫，或編碼成 %28 與 %29：

[Markdown](https://en.wikipedia.org/wiki/Markdown_%28disambiguation%29)
[更新日誌](https://example.com/notes\(final\))

同樣的跳脫也適用於連結文字裡真正要顯示的方括號：寫 \[ 就能印出一個不會啟動連結的方括號。

在新分頁開啟連結

Markdown 刻意沒有這個語法，因為這個格式描述的是結構而不是行為。如果真的需要，就退回原生 HTML：

<a href="https://example.com" target="_blank" rel="noopener noreferrer">開啟儀表板</a>

使用 target="_blank" 時務必一起加上 rel="noopener noreferrer"，否則目的地頁面會拿到一個可以用腳本操作你頁面的把柄。另外，許多平台會直接過濾掉 Markdown 裡的原生 HTML，多數網站產生器則提供設定或外掛，自動替外部連結加上該屬性。兩種格式的分界線在哪，Markdown 與 HTML 比較有深入討論。

常見錯誤與修正寫法

幾乎所有渲染不出來的連結，都逃不出這五個錯誤：

  1. 括號放反了，文字被放進小括號。
  2. ] 與 ( 之間多了空格，括號直接印在畫面上。
  3. 中文或日文輸入法打出的全形括號。
  4. 錨點直接照抄標題文字，大寫和標點都留著。
  5. 網址裡有沒編碼的空格，目的地被截斷。

括號順序與多餘的空格

文字放方括號，網址放小括號。錯誤寫法與正確寫法：

(Markdown 指南)[https://mdeditor.tw/zh/markdown-guide]
[Markdown 指南](https://mdeditor.tw/zh/markdown-guide)

多餘空格則是刪掉一個字元就好。錯誤寫法與正確寫法：

[Markdown 指南] (https://mdeditor.tw/zh/markdown-guide)
[Markdown 指南](https://mdeditor.tw/zh/markdown-guide)

中文輸入法打出的全形括號

這是中日韓寫作者最浪費時間的失敗原因。輸入法設定成全形標點時，打括號會得到 ［］ 或 （），而不是半形的 [] 與 ()。兩者在畫面上幾乎一模一樣，但解析器只看到普通文字，什麼都不會渲染。錯誤寫法，以及改用半形標點的正確寫法：

［Markdown 指南］（https://mdeditor.tw/zh/markdown-guide）
[Markdown 指南](https://mdeditor.tw/zh/markdown-guide)

小提醒：這個問題要從源頭解決。寫 Markdown 前先把輸入法切到半形標點，macOS 與 Windows 的中文、日文輸入法都有這個切換。同樣的陷阱也會出現在標題的全形 ＃ 與行內程式碼的全形 ｀，一次設定好，等於省下三次除錯。

錨點與沒編碼的空格

大寫與標點在產生 slug 時不會保留。錯誤寫法與正確寫法：

[Setup](#Setup Guide!)
[Setup](#setup-guide)

最後一個是沒編碼的空格：空格之後的內容會被當成 title 或直接丟掉，連結因此指向一個被截斷的網址，請照前面說的做百分比編碼。

連結出狀況時怎麼除錯

把那一行貼進編輯器看預覽，原因幾乎都是上述五種之一。

Markdown 完整指南會把連結放進所有元素之中一起說明，語法速查表讓語法一眼可查，姊妹頁面清單、表格與程式碼區塊則涵蓋連結最常被放進去的元素。

相容性資料驗證日期

常見問題

怎麼讓 Markdown 連結在新分頁開啟？

Markdown 沒有這個語法，只能改寫原生 HTML：<a href="https://example.com" target="_blank" rel="noopener noreferrer">文字</a>。會過濾 HTML 的平台會把整個標籤丟掉；多數靜態網站產生器則有設定或外掛，能自動替外部連結加上該屬性。

為什麼我的錨點連結跳不到標題？

片段與自動產生的 ID 不一致。ID 會全部轉小寫、移除標點、把空格換成連字號，所以 ## API Key (v2) 的 ID 是 #api-key-v2，重複的標題還會加上 -1 後綴。最可靠的做法是打開渲染後的頁面，從標題旁的連結圖示直接複製錨點。

什麼時候該用參考式連結？

網址重複出現時、網址長到讓原始碼那一行難以閱讀時，或文件會以 diff 形式審閱、你希望網址變動集中在檔案底部時。若只是留言或短筆記裡的單一連結，行內連結更簡單好讀。

裸網址會自動變成可點擊的連結嗎？

只有在 GitHub 風格 Markdown 與類似方言裡才會。純 CommonMark 與較舊的渲染器會留成純文字。可攜的做法是用角括號 <https://example.com>，或寫成有描述性文字的完整行內連結。

為什麼用中文輸入時連結都壞掉？

因為輸入法插入的是全形括號 ［］（），而不是半形的 []()。兩者外觀非常接近，但解析器認不得。寫 Markdown 語法前先把輸入法切到半形或英文標點，標題與行內程式碼的同類問題也會一併解決。

延伸閱讀

Markdown 清單

項目符號、編號、巢狀縮排、勾選框與行距規則。

Markdown 圖片

嵌入圖片、替代文字、尺寸控制，以及圖片為何只是多一個驚嘆號的連結。

Markdown 完整指南

依序解釋每一個元素，範例都可以直接貼上測試。

立即使用編輯器

立即使用編輯器