---
title: "文件：用註腳，俐落收納資料"
tags: zh, docs, writing
description: 說明 Markdown 註腳的語法和用法。
image: https://hackmd.io/_uploads/HJ2XgmUWY.png
author: elek
summary: "撰寫文件，難免要附上資料。註腳幫助你維持正文易讀、資料完備。與你分享在 HackMD 使用註腳的小訣竅。"
date: "2021-8-27"
---

# 文件：用註腳，俐落收納資料

註腳有種學究味。只有教科書、學術書籍才會在字裡行間穿插蠅頭小數字，一言不合就編到上百號，誰會看呢，我就聽過許多人抱怨書後的註腳內容、參考書目應該全部拿掉，賣便宜一點。

不過，實際撰寫文件，尤其需要做功課再下筆的文件，註腳其實挺好用的。譬如開發產品，常要設想使用情境，拍完腦門拍膝蓋，光憑自己設想還是有點乾，需要引用調查、論壇文章，甚至是論文。又好比一個功能可能有好幾種實現方式，各有優缺點，多半要參考許多討論才能定案，其間的折衷，有時也需要留下紀錄。

我們寫在文件裡的一句話，往往花了十倍時間和力氣調查、比較、分析。文件的讀者可能是主管、同事、外部合作單位或未來的新人，他們不見得下過相當的工夫了解文件的主題，因此，需要額外說明考慮的因素與經過。

傳達論點，同時也希望化解讀者可能有的疑問，所以需要附資料佐證。這時，註腳就是**簡明**和**翔實**的平衡點。

不過在 Markdown 文件裡，怎麼使用註腳呢？

>:point_left: 回到 [HackMD 中文官方部落格](https://blog.hackmd.io/zh) :point_right: [本文單篇連結](https://blog.hackmd.io/zh/blog/2021/10/12/footnote)

# 跟字面脱勾

本來 Markdown 沒有專屬於註腳的語法。HackMD 遵循的主要規範 [CommonMark](https://spec.commonmark.org/) 中，最接近的是「連結參照」。

「連結參照」包含連結標籤、網址、標題（可省）：

[連結標籤]: hackmd.io "HackMD"

[連結標籤]

上面這段 Markdown 會被解析為以下的 HTML：

<p><a href="hackmd.io" title="HackMD">連結標籤</a></p>

<!-- 看不懂沒有關係，文中序順不響影解理(?) -->

跟常用的超連結功能，也就是`[連結標籤](網址)`，效果是一樣的。

如果寫在 Markdown 文件中，算繪結果如下分隔線夾住的內容（請用 <i class="fa fa-columns"></i> [雙欄模式](https://hackmd.io/Ajzseh5wQbi1KwjqyIXewQ?both)參看 Markdown 的語法）：

---

這裡有一個[連結標籤]，不過連結的目的地其實寫在這個段落後面。

還隔了一個段落。請開 <i class="fa fa-columns"></i> [雙欄模式](https://hackmd.io/Ajzseh5wQbi1KwjqyIXewQ?both)看看呀 :point_up_2: 也可以按 `Ctrl` + `Alt` + `B`。按 `Ctrl` + `Alt` + `V` 可以切回檢視模式。

[連結標籤]: hackmd.io "HackMD"

---

可以發現，上面的寫法跟常用的超連結寫法 `[連結標籤](網址)` 會得到幾乎一致的結果，只是 `[連結標籤]` 可以放在文件的任何位置。

這個「連結參照」其實已經很接近我們從書本、論文接觸到的註腳。不過它有一個缺點：不管你把連結標籤取名為 `[大中天]` 還是 `[AZ]`，它一定會有「字面」，有字面就難以避免跟文件的正文混淆。

印刷文化裡的註腳之所以會演化成蠅頭小數字，固定長在字面的右上角（或用中括號括住），就是要讓註腳成為一種結構，好比樑、柱、牆之於建築，才不會跟正文混淆。

# Caret 不是胡蘿蔔

於是，在各式擴充的 Markdown 語法裡，出現了專屬註腳的語法。 :sparkles:

HackMD 透過 [markdown-it](https://github.com/markdown-it/markdown-it) 的 [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote) 支援註腳，而 markdown-it-footnote 則是根據 Pandoc 的[成例](https://pandoc.org/MANUAL.html#footnotes)。所以在 HackMD 當中，我們用以下的語法來寫註腳：

[^註腳標籤]

[^註腳標籤]: 註腳內容

    如果註腳超過一個段落，第二個段落開始請記得縮排 4 個空白字元。

「^」：這個符號叫**脱字符**，不過大家比較熟悉的可能是 Y-hat $\hat{Y}$ 的「^」，英文叫 `caret`[^懺悔]。

[^懺悔]: 我每次都以為是胡蘿蔔。

實際應用的情況：

> 我知道有一項研究的主題是，圖書館裡哪種書最常被偷。[^Schwitzgebel][^label_caution]

你發現了嗎？在 HackMD 裡，註腳有兩大特性：

### 首先，你**不需**幫註腳編號。 :exclamation:

在 Markdown 文件裡的註腳經過解析後，會自動依連結參照出現的順序編號，跟連結標籤的內容（`[也就是中括號裡的文字]`）無關。所以你可以隨時增刪註腳，不用擔心重新編號的問題。

### 其次，註腳的內容可以出現在文件的**任何**位置。 :exclamation:

一個值得推薦的作法是：把註腳內容寫在註腳出現段落的下一個段落。這樣一來，即使直接閱讀 Markdown 檔案，仍舊很容易讀懂。


>你發現「我每次都以為是胡蘿蔔。」只有出現在本文最下方的註腳處了嗎 :eyes:

# 善用註腳，精簡兼翔實，流通更容易

如果你曾經在 Word 或 Google Doc 裡用過註腳，就會知道**註腳**跟**正文**，屬於文檔的不同部分，而且樣式通常有別；意思是說，在不同軟體、甚至同一軟體的不同版本間，註腳的格式還有可能會跑掉，還要多換心思處理。 :sweat_drops:

在 Markdown 的情況，因為是純文字的格式，註腳的內容跟正文寫在一起，直接讀沒問題，不必多費心思再去手調格式，文件仍然保持著良好的可攜性。

雖然**註腳**不在 CommonMark 規格中，但已獲得廣大支援（阿就真的好用咩），不擔心淪為語法孤兒，可以放心使用，享受「註腳自己會編號」跟「註腳內容放在正文段落裡也不會被發現」的快感。

下次提案，就利用註腳讓你的文件更精簡、更有說服力！

[^Schwitzgebel]: Schwitzgebel 2009; Schwitzgebel and Rust 2014.

[^label_caution]: 請留意，註腳標籤中間不能有空白。建議使用 `-` 或 `_` 代替，英文也可以用 CamelCase，來兼顧可讀性。