使用pandoc markdown寫作後記

用了兩年多markdown寫我的博士論文，到現在基本上用得比較順手，所以把自己的一些心得記錄在此。
markdown是很好用的輕量化標記語言，自從兩年多前拋棄pages/google docs，我就改用markdown來寫論文，基本沒碰到什麼大問題。markdown雖好，但對於學術寫作來說，功能偏弱。學術寫作最大的區別在於需要大量的引用，而markdown本身並不支持這一功能，所以需要退而求其次，可供選擇的有multi-markdown和pandoc。因為M.Tong的慫恿，我就誤打誤撞地用上了pandoc，當然了，這玩意比mmd好用多了，而且也強大多了。
只用pandoc markdown最大的好處是，你既可以體驗markdown的輕巧，又可以享受latex的強大，而且可以避免latex\那\些\痛\苦\的\杠\號 (\號瞅着就難受吧）？
之前寫過幾篇和這個主題的文章，主要講的都是markdown的問題，這篇主要記錄pandoc的應用。
為什麼文科生也該用markdown寫作?
學術寫作tips
我的寫作workflow
1. pandoc md語法
pandoc有自己的markdown語法，是在md的基礎上發展的，作者John Macfarlane （會寫haskell的哲學家真恐怖）提供了詳盡的文檔 ，嚴格按照這個文檔寫的話，不會出問題。
2. 求助
如果出了問題，請google，或者去stackoverflow找答案，實在找不到，請到pandoc的google group發帖求助，一般一小時內就會有大神回覆你。
3. md編輯
請務必找一個好用的文本編輯器，裝上相應的插件，個人使用了vim和sublime。使用sublime的話，無比裝M.Tong開發的smart markdown插件，沒這玩意的話，我都不知道怎麼死的。
4. 表格
pandoc提供了多种表格的寫法，參加文檔種的table部份，應該說，這些表格的寫法完全滿足了需求。
在這裡，請特別注意caption的寫法。我一開始使用縮進的寫法，即在開頭加一個>符號，這樣pandoc會自動縮進caption。但pandoc不會識別這樣的寫法為表格的caption，所以當你想要建一個索引的時候，pandoc就沒辦法了。正確的寫法是，在caption的開頭加table:，或者直接一個冒號。
                
                
                
                
5. 圖片
圖片的插入也非常方便，只要在相應位置插入圖片的硬盤位置即可。
                
                
                
                
需要注意的是，第一，最好使用圖片的絕對位置，而不是相應位置，也就是你最好把完整的目錄貼上去；第二，在圖片文件名種只能出現一個.號，也就是說比如這個8.1.1圖，你不能命名為8.1.1.pdf，必須避免多個.號的存在，我使用了下劃綫，就是8_1_1.pdf。
圖片唯一的問題是，pandoc有時會將表格放在錯誤的位置。因為某些圖片過高，所以pandoc會把他們插入到一個新的空白頁，然後將後面的內容直接查到表格前面，這樣很容易產生錯位。有兩個解決辦法，一是，轉換到latex後，手動修改圖片位置，當然這個比較痛苦；二是在圖片後面加入一個latex的分頁比較\pagebreak，讓後面的內容自動寫到新的一頁上，儘管這樣比較廢紙。
6. 標題
標題的寫法和markdown類似，pandoc在compile的時候，會自己動生成一個索引，非常方便。需要注意的是，在每一級標題前必須留空，否則pandoc無法識別。比如你有多個子文檔，整合到一起的時候，很有可能在文檔之間忘記留空，這樣會發生錯誤。正確的做法是在文檔末尾留一個空行，即使多個空行，pandoc會自動合併為一個空行。
7. 文獻引用
嗯，這個是我們最關心的問題了。pandoc提供了強大的引用支持，特別是最近又改進了許多。去年年底的時候，這功能還比較雞肋，比如如果你引用一個網頁的話，pandoc使用的pandoc-citeproc插件是無法識別這類引用的，好在現在都解決了。
基本的文中引用格式是 [@citekey]，這裡的citekey可以用Paper，zotero之類的文獻管理軟件自動生成，基本的格式是
作者的姓:年份+兩個或以上的隨機字母組合
比如像 Smith:1990xh
我使用APA6的格式，所以要求文中的格式是作者的姓+年份：(Smith, 1990)。我只要在文中寫成
[@Smith:1990xh]
pandoc會自動render，然後在文末插入這條reference（等會解釋怎麼配置）。
如果我們需要寫成Smith (1990) pointed out之類的寫法，也很簡單，具體是這樣:
 pointed out
也就是去掉方括號即可
再比如，如果是直接引用，Smith (1990) pointed out "blabla" (p. 140)，可以寫成：
@Smith:1990xh pointed out "blabla" (p. 140)
如果有多個引用需要放在一起的話，需要用分號鏈接：
[@Smith:1990xh; @Smith:1990ts]
如果是同一個作者的話，放心，pandoc會自動將他們render成 (Smith, 1990a; 1990b)
8. 文獻引用的配置
pandoc的強大之處在於，你可以隨心所欲的配置。它默認的引用格式好像是MLA，而我需要的是APA，所以這裡需要在compile的時候，添加APA 的CSL模版。所謂CSL是zotero開發的一套引用格式，和xml的格式很像，不過這是為文獻引用專門開發的。具體的格式可以在上面的zotero網站上找到。
剩下的，你需要將所有的文獻生成一個bibtex文檔，這個Papers或者zotero之類的文獻管理軟件都支持導出。當然pandoc也識別其他格式，具體可以在pandoc的文檔種找到。
9. 數學公式
pandoc使用了tex的數學公式寫法，如果你熟悉latex的話，可以忽略這些。如果你不熟悉的話，可以參見pandoc的文檔。
10. 模版
pandoc提供了幾個默認的模版，包裹latex模版，word模版等等，基本夠用。但各個學校有自己的規矩，所以你很有可能需要改造自己的模版。
我的做法是，直接在默認的模版上改。默認的模版可以在github上找到: https://github.com/jgm/pandoc-templates。因為我需要導出為pdf，所以選了那個latex模版改。下面是部份改動的地方：
在\begin{document}前面加上如下語句
\usepackage{anysize}
\marginsize{3cm}{2cm}{3cm}{3cm} %change the margin
\usepackage{setspace}
\doublespacing %change the spacing
\let\stdsection\section
\renewcommand\section{\newpage\stdsection} %set new page for each chapter
\usepackage{chngcntr} %change the overall font
\counterwithin{figure}{subsection} %change the figure numbering
\usepackage{placeins}
\FloatBarrier %put the figure within the boarder
\usepackage{apacite}
\usepackage{floatrow}
\DeclareFloatFont{footnotesize}{\footnotesize}% "scriptsize" is defined by floatrow, "small" not
\floatsetup[table]{font=footnotesize}% change the table font to small
\usepackage[labelformat=empty]{caption} %remove captions of figures
\usepackage{flafter} %make sure that the floats never go before the refer
\usepackage{booktabs}
\usepackage[listformat=empty]{caption}
在\begin{document}下增加
\hypersetup{linkcolor=black}
\setcounter{tocdepth}{$toc-depth$}
\tableofcontents
\cleardoublepage
\phantomsection
\listoffigures %add list of figures
\listoftables %add list of tables
每條後面的註釋解釋了具體用法，\usepackage是指你需要使用這些latex包，具體話，你需要從tex utility里安裝。
11. compile
最後一步，也就是使用pandoc來complie文檔，我需要將markdown文本compile成pdf，具體的語法如下：
pandoc -s -S --filter pandoc-citeproc --biblio all.bib --csl apa6.csl --latex-engine=xelatex --template=template.latex --variable mainfont="Georgia" --variable fontsize=12pt --toc all.md -o all.pdf
-s: standalone, 這個貌似是pdf的默認選項，可以不管它。
-S: smart，幾乎也是默認選項，大致是可以減少出錯的機率。
--biblio all.bib，告訴pandoc文獻的bibtex位置，我將文獻導出到all.bib的文檔裡，並且存放在同一目錄下。
--csl apa6.csl 告訴pandoc使用APA6的引用格式，這個csl文檔直接在zotero csl上找的。
--latex-engine=xelatex 我沒有使用默認的latex引擎，而是使用xelatex這個引擎，好處是可以改字體。
--template=template.latex 告訴pandoc使用模版，這個template.latex就是我在默認模版基礎上修改的。
--variable mainfont="Georgia" --variable fontsize=12pt 嗯，個人偏愛Georgia這個字體，大小合適，也很正式。至於12號字體是論文的基本要求吧?
--toc 告訴pandoc添加目錄，即table of contents的縮寫，pandoc會自動生成目錄，太方便了！
all.md -o all.pdf 告訴pandoc輸入文檔，-o告訴它輸出文檔。
嗯，以上就是這兩年多使用pandoc markdown的心得，難點基本都覆蓋到了，希望對大家有用～