GitHub 版本的 Markdown 的正式規格

GitHub 自家版本的 Markdown 給出了正式的規格,GitHub Flavored Markdown Spec:「A formal spec for GitHub Flavored Markdown」。

規格裡面把標出 GFM 版本所特有的特性:

When reviewing the GFM spec, you can clearly tell which parts are GFM-specific additions because they’re highlighted as such. You can also tell that no parts of the original spec have been modified and therefore should remain fully compliant with all other implementations.

有種內部在實做時順便整理出來的感覺...

RFC 7763:text/markdown

Markdown 的 RFC:「The text/markdown Media Type」。

This document registers the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML.

雖然是 Category: Informational,但有個標準後是不是有機會在瀏覽器裡面原生支援?

用 Markdown 寫測試的 Silk

堆了很久的文章...

Markdown 同時寫 API 測試文件,並且可以實際測試的工具:「Introducing Silk: Markdown driven API tests」,專案在「Markdown based document-driven RESTful API testing.」這邊可以抓到,用 Go 寫的。

Silk 規範了在 Markdown 裡要測試的文字,然後用這樣測:

silk -silkurl=http://127.0.0.1:3000 example-test.md.silk

其中 -silkurl= 帶的參數最後面不能有斜線 (slash)。

這個工具比較像是確保 API 文件與目前的 API 相同,而不是要取代現有的測試架構。畢竟用程式語言的彈性還是高很多,Silk 只是初步的確認。

GitHub 對 Open Source Community 請願的回應

大約一個多月前 (2016 年一月 15 日),一群用 GitHub 發展 Open Source 軟體的人對 GitHub 提出請願,要求重視 Open Source Community 在 GitHub 平台上遇到的問題:「An open letter to GitHub from the maintainers of open source projects」。

這個請願在卡了將近一個月後,陸陸續續有相當多要搬出 GitHub 的討論,像是 eslint 就直接在 GitHub 開了 issue,討論搬出 GitHub 會遇到的問題以及可能的解決方法:「Investigate switching away from GitHub」。

在二月 13 日的時候,GitHub 透過 pull request 發出回應說「我們在處理了」,但也沒講正在處理什麼,看起來就是個很 PR 的回應:「Dear Open Source Maintainers」。

直到昨天,三個主要的請願中關於 issue 範本的問題 (也就是下面這段) 總算有進展了:

Issues are often filed missing crucial information like reproduction steps or version tested. We’d like issues to gain custom fields, along with a mechanism (such as a mandatory issue template, perhaps powered by a newissue.md in root as a likely-simple solution) for ensuring they are filled out in every issue.

為了解決使用者在開 issue 時有時會忘記給出完整的環境資訊 (以及其他有用的資料),GitHub 推出了新的功能,在開 issue 或 pull request 時利用 template 讓使用者有個範本可以照著填寫,同時 template 也支援 Markdown,讓填寫的方式會更豐富一些:「Issue and Pull Request templates」。

這總算開始有進展了。但也開始感覺到 GitHub 的動作已經開始慢下來了...

在 Ubuntu 下即時編輯 Markdown 語法:ReText

找了找資料,發現用 apt-get install retext 直接裝 ReText 就可以了,開起來以後選 Live preview 的功能就可以即時看結果了:

官方的 screenshot:

除了支援 Markdown 以外,還支援 reStructuredText

PS:Markdown 語法可以參考中文版文件:「Markdown 語法說明」。