2018-03-13

Introduction

I really enjoy myself writing papers and reports with Markdown. The syntax is relatively easy. Here is a quick syntax cheet sheet. Furthermore, this post focuses on citations, footnotes and figure references in Markdown.

Pandoc

Pandoc is a very powerful tool converting files between many formats. Regarding writing papers in Markdown, the most two important transfers might be from .md to .pdf and .md to Word(really?).

To generate a PDF file from Markdown file, the command is as simple as

pandoc test1.md -s -o test1.pdf


Installation

1. A latex implementation is needed. I am using MiKTEX
3. Install a plug-in for figure and table references with pip install pandoc-fignos pandoc-tablenos pandoc-eqnos, you need python environment and pip for that.
4. You may found VS Code is a good editor for Markdown. There are many related plug-ins you can use like vs-pandoc.

Citations

A good practice is to get the BibTeX format of the article and put all such information in a file like ref.bib in the same folder of the Markdown file. For example, on this page of a famous paper Google Bigtable, we get the BibTeX format on the bottom of the right box as follow.

@article{Chang:2008:BDS:1365815.1365816,
author = {Chang, Fay and Dean, Jeffrey and Ghemawat, Sanjay and Hsieh, Wilson C. and Wallach, Deborah A. and Burrows, Mike and Chandra, Tushar and Fikes, Andrew and Gruber, Robert E.},
title = {Bigtable: A Distributed Storage System for Structured Data},
journal = {ACM Trans. Comput. Syst.},
issue_date = {June 2008},
volume = {26},
number = {2},
month = jun,
year = {2008},
issn = {0734-2071},
pages = {4:1--4:26},
articleno = {4},
numpages = {26},
url = {http://doi.acm.org/10.1145/1365815.1365816},
doi = {10.1145/1365815.1365816},
acmid = {1365816},
publisher = {ACM},
address = {New York, NY, USA},
keywords = {Large-Scale Distributed Storage},
}


Then, we put this piece of information in ref.bib file. To cite it in Markdown file, we use [@Chang:2008:BDS:1365815.1365816], the content after @ is basically the identity segment on the first line. Multiple citation can be separated by ; as [@article1;@article2]

In order to tell Pandoc to process those citation properly, use following Pandoc options. The --csl option specifies the format. You can download the right one from citationstyles.org. (Usually a journal would specify the preferred one)

pandoc --filter pandoc-citeproc --bibliography=ref.bib --csl=ieee.csl test1.md -o test1.pdf


Footnotes

Footnote is identified with [^1]. The content starts with [^1]:, followed by details. An example is as below.

On the first month, this application will attract 5% of the students in Texas A&M and UT Austin.[^1] There are 68,825 enrolled students in TAMU.

[^1]: author: nobody, ID: 12345.
*supported by xxx.

Other content...


Figure, table and equation references

Figures can be referenced as below. Basically, {#fig:figure-id-or-name} is for the source, while {@fig:figure-id-or-name} is for the reference. Figure x will substitute the reference.

The result is shown in {@fig:test-result}.

![Test result](pig/test.png){#fig:test-result}

Other content...


If you prefer other name rather than Figure, we can specify it with two lines in the header section of Markdown file as below.

---
fignos-cleveref: On
fignos-plus-name: Fig
---


Extra Pandoc options are needed for figures, tables and equations. They are shown as below combined with those for citations.

pandoc --filter pandoc-eqnos --filter pandoc-tablenos --filter pandoc-fignos --filter pandoc-citeproc --bibliography=ref.bib --csl=ieee.csl test1.md -o test1.pdf


Table references

For table reference use the pair of {#tbl:table-id} and {@tbl:table-id}. The table header should be placed at the end of table, shown as below.

|Time after launch |User population / million |
|:---:|:---:|
|9 months |0.01 |
|1 year |0.5 |
|2 years | 18.7 |
|3 years | 70 |
Table: User growth of the application {#tbl:user_growth}


Equation references

For equation reference, just use the pair of {#eq:eq-id} and {@eq:eq-id}.

The Mass energy equivalence is shown as Eq. {@eq:m-e}.

$$E = m c^2$$ {@eq:m-e}