Loading...

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

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

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

傳達論點,同時也希望化解讀者可能有的疑問,所以需要附資料佐證。這時,註腳就是簡明翔實的平衡點。不過在 Markdown 文件裡,怎麼使用註腳呢?

跟字面脱勾

本來 Markdown 沒有專屬於註腳的語法。HackMD 遵循的主要規範 CommonMark 中,最接近的是「連結參照」。
「連結參照」包含連結標籤、網址、標題(可省):

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

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

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

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



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

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

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

Caret 不是胡蘿蔔

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

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

實際應用的情況:

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

首先,你不需幫註腳編號

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

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

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

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

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

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

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

雖然註腳不在 CommonMark 規格中,但已獲得廣大支援(阿就真的好用咩),不擔心淪為語法孤兒,可以放心使用,享受「註腳自己會編號」跟「註腳內容放在正文段落裡也不會被發現」的快感。
下次提案,就利用註腳讓你的文件更精簡、更有說服力!

HackMD 中文電子報訂閱連結

原刊載於 HackMD 中文部落格:https://hackmd.io/@hackmd/footnote