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 的文件了。

comments powered by Disqus