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


GitHub 提供專案授權簡介與概要

Do What The F*ck You Want To Public License,

大概上週看到有人在 Twitter 講到 GitHub 現在會在專案上顯示該專案所使用授權條款的摘要,長的像是上面那樣,官方也有發表公告,其實這個修改是結合之前的授權偵測Choose a License

Choose a License 也是一個 GitHub 的附加服務,用來協助使用者挑選適合的授權條款,現在在 GitHub 建立新的專案時,可以順便初始化專案,包括建立 README、產生.gitignore和挑選要使用的授權條款:

Initialize Project

授權條款旁邊的 i 點下去其實就會送到 Choose a License 網站去了(不過兩邊沒有連動接起來就是),Choose a License 網站則針對每種條款都一份重點摘要,分為 Permissions、Conditions 和 Limitations 三個區塊,分別條列出該條款可以做什麼(例如商業使用)、有什麼條件(例如需要也使用相同條款授權)和條款的限制(例如免責),而現在 GitHub 上顯示的條款摘要其實就是這邊的資訊搬過來的:

Choose a License

Choose a License 網站其實有很多授權條款的整理,而不是只有常見的幾種,可以看appendix頁面有完整清單,可惜裡面沒有Vim License,另外特別想說的是 GitHub 自己(應該沒錯)提供的Unlincense,相似於創作領域的CC0,就類似丟到 Public Domain 的意思,不過保留了免責條款,講到免責聲明,就還要順便提一下WTFPL,它其實也是超自由的 License,差別就是連免責聲明都沒,其實是更加接近丟到 Public Domain 吧?

最後想說的是 GitHub 用來判斷專案使用的授權,用的是licensee這個 Ruby Gem,看起來完全就是為了做這些事情寫的,我看好像也沒其他類似功能的專案,作者 Ben Balter 其實也是 GitHub 員工。


Gitdags, Git 示意圖工具

cherrypick-2

最近因緣際會,需要畫些圖來教 Git,不是要拿真的 repository 來畫,當然可以用繪圖軟體刻,不過時間不夠,而且覺得應該之前就有人有需求了,應該有現成的工具,所以我就找了一下看有沒有方便的工具可以畫,結果很幸運的,沒多久就找到了gitdags這個 Latex 的 package,專門就是用來畫教學用的 Git 圖,而且圖的樣版還蠻接近 Pro Git v1 書內的樣子(v2 的樣版改的更簡潔了),看起來還蠻 ok 的,它是基於TikZ這個 package,是 Latex 上的繪圖 library,可以產生出向量格式的圖,所以我可以用 pdf2latex 先轉成 pdf,pdf 檔案就可以給 Keynote 用了,不過要通用一點,還可以用 pdf2svg 生成 SVG 圖檔,SVG 內容看起來也還蠻乾淨的,tex 文件內容大概像這樣:

\documentclass[preview]{standalone}
\usepackage{gitdags}

\begin{document}
    \centering
    \begin{tikzpicture}
      % Commit DAG
      \gitDAG[grow right sep = 2em]{
        0 -- {
          1 -- 2 -- 3 -- 4,
          A
        }
      };
      \gitbranch
        {master}     % node name and text 
        {above=of 4} % node placement
        {4}          % target
      \gitbranch
        {for-rebase} % node name and text 
        {below=of A} % node placement
        {A}          % target
      \gitHEAD
        {below=of for-rebase} % node placement
        {for-rebase} 
      \end{tikzpicture}
\end{document}

產生的圖片就像是最上面的圖,gitdags 是用solarized來配色,我覺得顏色不是很精緻,不過還可以接受,另外我有自己調整一版黑底用的,把線條和邊框改淺,還有把 commit node 的形狀調整了一下,也放在GtiHub 上。使用 gitdags 的過程,比較大的問題就是文件和範例不足,所以我把自己畫的部分全部丟上 GitHub了,後來發現原作者也有一些 sample可以參考,作者自己兩年前是說有要寫文件和準備範例,不過後來就都沒動靜就是了。如果要在 Mac 上處理 Latex 文件,一般就是建議直接裝MacTeX就好,不過 gitdags 沒包在裡面,所以要自己安裝,或是把 sty 檔案和 Tex 文件放在同一個目錄也可以。

不過 SVG 就是用 pdf2svg 產生的 SVG 檔我用 AI 要編輯時會發現有些問題,我有另外試著用inkscape做轉換,出來的文字大小是正常的,不過看起來字形和間距不太正確就是,如果要轉 PNG 之類的非向量格式是可以直接用 Preview 或是 convert 轉換,不過解析度要設定一下,通常預設的 150,輸出的圖片大小是不太夠就是了。

最後,gitdags 這名字裡面的 dag 應該是有向無環圖(Directed Acyclic Graph)的意思,這種圖剛好可以用來描述 Git 裡面 commit、branch 等東西之間的關係。


Docker 雜談

最近使用的一些感想和疑問

  • --name自動會變 network 內的 hostname,蠻方便
  • Image build 失敗,還是會產生一個東西在那邊,要 rm 掉才能重新 build...
  • Service 還不支援 update 修改 network
  • DB container 的資料要開 volume 掛比較保險(免得不小心砍到 container)
  • 在多個 node 上開 replica,掛 volume 的話都是在該 node 上找,目前似乎沒有透過網路共享 volume container 這種事
  • 很多服務的官方 docker 都是用環境變數做設定,不知道是不是本來就有的慣例
  • 一直更新 registry 上的 image 好像會越來越多垃圾,不知道是不是有清理機制
  • 整體而言,我覺得 docker service 介面是個很容易讓 fat finger 造成服務爆炸設計,不過架構規劃的好的話,應該不會太難修復就是

Guetzli: A New Open Source JPEG Encoder

Guetzli

今天一早起來就看到 Google發表的新的 JPEG 壓縮程式,叫 Guetzli(一種瑞士餅乾),這是 Google 繼ZopfliBrotli之後,算是第三個比較容易被大家廣為使用的新的節省網路流量的工具,這次主要針對 JPEG 圖片格式,和之前 Mozilla 的mozjpeg的作法一樣,保持目前 JPEG decoder 的相容性,然後看能加強 JPEG 圖檔到什麼程度,我稍微測試了一下,結果還不錯,目前還沒有 homebrew formula,如果要自己 build 的可以參考這篇,基本上就是用 bazel 來編譯,然後可能會需要先裝 libpng 和 gflags,這兩個可以用 homebrew 安裝:

brew install libpng gflags

然後裝bazel

brew install bazel

然後到專案目錄下執行編譯指令:

bazel build -c opt //:guetzli

結果就會把執行檔放到bazel-bin/guetzli這位置,就可以拿來用了,不過其實官方 GitHub repo 上的release那邊就有編譯好的版本,抓下來用 Terminal 執行chmod +x也可以用(我是自己丟到/usr/local/bin/裡面),指令很簡單,可以加上--quality,預設是 95,不過最小只能 84,設更小的值會跟你說,真的想要的話自己去改原始碼...

速度就如大家所說的,和其它工具比起來真的慢很多,感覺是有一些 recursive 找最佳解的過程,輸出的結果我覺得最讓人印象深刻的是對於純色色塊的處理,也比 mozjpeg 好上不少,輸出檔案的大小不一定會是最小的,不過品質好很多,差異是達到我可以放棄這點容量差距,而寧願要這畫質改進,然後就是 Quality 100 可能會體積暴漲,我隨便測試了幾張圖片,看起來設到 90 品質就蠻不錯的,看來目前通行的圖片最佳化工具又要有一輪更新了。


➡ 看看其它文章