markdown for academia

最近在準備 lse 的考試，整體來說是一場災難，經濟真的是一個很煩人的學科。。。

所以這篇文章的時間比較緊，我就隨便寫寫了。

有幾點注意的：

（1） markdown for academia 仍然是一個 very early alpha。

我剛剛把轉 pdf 部分寫完，很多的 error message 都沒有寫，test 也僅僅只覆蓋了 80% 的 code。

之後的語法都有可能有變動。

（2） 這並不是一個嚴格的文檔，只是一個簡單的介紹，文檔會等到我考完試就寫。

1. Incentive

之前我用過很久的 latex。後來也用過一段時間的 org-mode。

但是後來我漸漸的發現，至少在我的認知裡面，latex 大量的功能都是不被用到的，我所需要的東西其實 org mode 裡面都能實現。

但是 emacs 對於我這樣的懶人來說還是太複雜了，我有時候用的時候經常覺得我這是在配置一個編輯器還是在寫一個編輯器。。。

更不用說 emacs 卡的問題，當你的富文本太多的時候 emacs 會在用翻頁的時候閃瞎你的狗眼。（當然也可能只在 windows 上這樣）

之後我就找到了 org-mode 的兄弟，markdown。 markdown 現在也支持越來越多 latex 中的功能了，但是還是有少量的不行的，好在 pandoc 是支持 raw latex expression 的。但是 pandoc markdown 的語法並沒有很可讀（我個人對於可讀的定義是一個有基本編程經驗的人使能夠猜出來程序是幹嘛的），而且語法很不統一，比如 table 的 caption 的寫法就和 image 的 caption 是不一樣的。

我也在晚上找了很多相關的 markdown 的衍生品，最令我滿意的一個是 bookdown: Easy Book Publishing with R Markdown，可惜 bookdown 是基於 r 的，而我本人對於 r 並沒有那麼熟悉。其他的 ScholarlyMarkdown 和 smathot/academicmarkdown 都已經有些年頭沒有動了，而且很多東西都不支持。

於是我乾脆就用了大概兩周時間擼了一個 markdown for academia，簡稱 mdac

2. 安裝

因為目前在國內，就沒有使用 GitHub release 的功能。

windows 用戶可以用 appveyor 的 artifact：win64-python3.6

其他用戶可以從 source build，需要 python 3.5 或以上：

cd path/to/markdown_for_academianpython3 freezer.py buildn

完成之後可以通過如下把一個 mdac file 轉製成 pdf：

mdac ./test.mdacn

因為 mdac 在 yaml header 中加入了 output 這一選項，所以可以在文件裡面直接寫入你想要的設置。

目前還沒有寫 pip install 用的東西。

3. 語法

3.1 mdac block

mdac （markdown for academia）的語法考慮到了研究時的筆記和真正發表的研究論文。

mdac 主要時在 markdown 的基礎上加入了 mdac block：

==== block_typenblock_contentnn---nblock_metan====n

以下是幾點語法的設計：

1. mdac block 由 3 - 15 個 『=』 開始，由同樣數量的 『=』 結束。
2. 每一個 block 分成三個部分分別時 block content（optional）， block meta（optional）， 和 block type。
3. meta block 和 content block 用 3 個 『-』 來分割。
4. meta block 用的是 yaml 語法

這是一個 sample block：

==== codenfor i in "test":n print inn---ncaption: this is a test codenlabel: test_coden====n

當然在我們平常記筆記的時候肯定不會寫 caption 和 label，我們可以就不用寫 meta：

==== codenfor i in "test":n print in====n

在一些特殊情況下，我們可能想要從其他地方 import content，而不是寫 content：

===== tablen---nfile: ./test.csvncaption: experiment resultn=====n

因為大量的研究結果都是用 csv 儲存的，這裡就這樣直接導入 table 了。

在個別的情況下，我們也希望能直接 embed 兩個 block，比如有時候 theorem 裡面會需要 table （其實 equation 更需要，但是我還沒 implement equation block）

=== theoremnI have got the following table:nn======= tabnHead row1 Head row2n---------------- ----------------nContent row1 Content row2nn---ncaption: theorem tablenlabel:the_tabn=======nn---nlabel: table theoremn===n

我們只要用不同的等號的長度來寫就行了，等號的長度是 3 - 15 個，所以，應該夠用。。。

你可能也發現了，我在寫的 table block 的時候用的是 tab 而不是 table，在沒有歧義的情況下，mdac 會接受用單詞的前幾個字母來標誌你的 block type。

比如 code block 可以寫成 co， theorem block 可以寫成 the。這在平時記筆記的時候會很有用。

3.2 reference

mdac 不僅僅統一了 figure， table， code， include， theorem 等等的語法，而且還統一了 bibtex 引用和文章內引用的語法。全部都是用如下引用：

[@label]n

比如我要引用上面的一個 theorem：

theroem [@table theorem] is such a great theorem, because it got a table in it.n

就可以了。

4. 更多

MarkdownForAcademia/markdown_for_academia 這是一個 test case，其中包含了很多的不同的使用情況，可以看一看。

除此之外，就等著我寫 document 的時候再說把。。。

明天還要複習計量。。。要早些睡了。

推薦閱讀：