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
- A latex implementation is needed. I am using MiKTEX
- Download and install Pandoc
- Install a plug-in for figure and table references with
pip install pandoc-fignos pandoc-tablenos pandoc-eqnos, you need python environment andpipfor that. - 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}.
{#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}
