GitHub 可以在 Markdown 文件裡寫 TeX 語法了

Hacker News 首頁上看到 GitHub 上的「Render mathematical expressions in Markdown」這個公告:

You can now use LaTeX style syntax to render math expressions within Markdown inline (using $ delimiters) or in blocks (using $$ delimiters).

其中 TeX rendering 這塊是透過 MathJax 產生的:

GitHub's math rendering capability uses MathJax; an open source, JavaScript-based display engine.

我記得 MathJax 的效能好像不怎麼樣... 反正是跑在使用者端的 javascript?XD

GitHub 的 Markdown 透過 Mermaid 支援各種流程圖

前幾天 GitHub 宣佈他們站上的 Markdown 透過 Mermaid 支援流程圖:「Include diagrams in your Markdown files with Mermaid」。

翻了一下 GitLab 也有 Mermaid 支援:「GitLab Flavored Markdown」,所以這個部份兩邊的系統可以通了...

寫 API 文件時也蠻常用到的東西,之前是在 GitLab 上面弄了 PlantUML 的支援,找時間來分析...

Vim 的 Performance Profiling

在「Profiling Vim」這邊看到 Vim 上常見的效能問題,很多時候會覺得「慢」但不知道慢在哪邊的問題...

文章作者已經知道是開 Markdown 檔案時的問題,所以可以在開啟 Vim 後用下指令啟動 profiling,但如果是想要追蹤一開起來很慢的問題,可以看「對 Vim 啟動過程做效能分析」這篇的方式,直接在啟動時加上 --startuptime vim.log 這樣的語法,把 log 寫到 vim.log 裡面。

PyPI 支援 Markdown

在「Markdown Descriptions on PyPI」這邊看到 PyPI 的網站要支援 Markdown 語法了,目前有 markdown-description-example 這個專案可以看效果。

同一個 package,舊的在「markdown-description-example 0.0.1 : Python Package Index」這邊可以看到,新的則可以在「markdown-description-example · Warehouse Preview (PyPI)」這邊看到。

code block 的地方看起來還不太好看,也許之後還會調整?

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 語法說明」。