GitHub Flavored Markdown 標準規範

Github Markdown Cheat Sheet

前陣子看到 DK 提到 GitHub 的 Markdown:GitHub Flavored Markdown 發表正式的 spec 了,當時有大概看了一下內容,不過昨天才有空寫出來(然後今天也看到碼天狗有提到這件事),基本上這份 spec 是基於 CommonMark 的,只是多了一些語法,包括:

  • 刪除線
  • 表格
  • 待辦清單
  • 自動連結(包括網址和 email)
  • Raw HTML 黑名單:
    • <title>
    • <textarea>
    • <style>
    • <xmp>
    • <iframe>
    • <noembed>
    • <noframes>
    • <script>
    • <plaintext>

新增的部分都有很顯眼的標註,其中 Raw HTML 黑名單的 HTML 標籤的<都會被轉成 entity,基本上看起來是安全性考量,不過不太確定為何有些很老的標籤出現,感覺上和安全性比較沒關係。另外我還注意到 emojireference link沒包含在這份 spec 內,emoji 或許是因為實做上的問題,轉成 unicode 字元相容性不好,要用 img 會有不少相依性問題,而 reference link 大概是因這是比較針對 GitHub 網站的特性。

GitHub 轉換 Markdown 引擎的過程也有在文中說明,這次 Markdown 引擎是從 Sundown(更早是 Ruby 實做的 redcarpet 的樣子)改成 cmark,當然為了這些新語法,他們 fork 了自己的版本出來,然後在真的套上 GitHub 本站前,有先做過測試,結果發現有 1% 的文件(所有的 Markdown 文件,包括 user comment、issue...etc)會受到影響,而且判斷方法不是單純 diff 輸出結果,而是 diff 正規化過的 HTML 文件樹,不過即使只有 1% 的文件,那也是很大量,後來他們又更仔細分析,發現會受影響的幾乎都是 issue、user comment 之類的內容,是存放在 GitHub 資料庫內的,而不是 repository 內的文件,所以他們可以直接修改,如果是 repository 內的文件,因為要看 sha1 hash,所以是改不了的,後來他們魔改 Sundown,讓它吃舊文件然後吐出符合新 spec 的 Markdown 文件,接著跑了幾天把全部需要修改的舊文件(1%)都轉完,所以現在除了少數文件外,剩下的文件都是符合 GFM spec 的文件了。