文件:用註腳,俐落收納資料 | HackMD Blog
August 27, 2021

文件:用註腳,俐落收納資料

elek
elek
雜而不精的家政媽媽桑

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

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

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

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

不過在 Markdown 文件裡,怎麼使用註腳呢?

:point_left: 回到 HackMD 中文官方部落格 :point_right: 本文單篇連結

跟字面脱勾

本來 Markdown 沒有專屬於註腳的語法。HackMD 遵循的主要規範 CommonMark 中,最接近的是「連結參照」。

「連結參照」包含連結標籤、網址、標題(可省):

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

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

<p><a href="hackmd.io" title="HackMD">連結標籤</a></p>
<!-- 看不懂沒有關係,文中序順不響影解理(?) -->

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

如果寫在 Markdown 文件中,算繪結果如下分隔線夾住的內容(請用 雙欄模式參看 Markdown 的語法):


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

還隔了一個段落。請開 雙欄模式看看呀 :point_up_2: 也可以按 Ctrl + Alt + B。按 Ctrl + Alt + V 可以切回檢視模式。


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

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

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

Caret 不是胡蘿蔔

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

HackMD 透過 markdown-itmarkdown-it-footnote 支援註腳,而 markdown-it-footnote 則是根據 Pandoc 的成例。所以在 HackMD 當中,我們用以下的語法來寫註腳:

[^註腳標籤]
[^註腳標籤]: 註腳內容
如果註腳超過一個段落,第二個段落開始請記得縮排 4 個空白字元。

「^」:這個符號叫脱字符,不過大家比較熟悉的可能是 Y-hat \(\hat{Y}\) 的「^」,英文叫 caret[1]

實際應用的情況:

我知道有一項研究的主題是,圖書館裡哪種書最常被偷。[2][3]

你發現了嗎?在 HackMD 裡,註腳有兩大特性:

首先,你不需幫註腳編號。 :exclamation:

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

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

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

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

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

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

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

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

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


  1. 我每次都以為是胡蘿蔔。 ↩︎

  2. Schwitzgebel 2009; Schwitzgebel and Rust 2014. ↩︎

  3. 請留意,註腳標籤中間不能有空白。建議使用 -_ 代替,英文也可以用 CamelCase,來兼顧可讀性。 ↩︎


本篇文章驕傲的使用 HackMD 發佈