Markdown is the most common format for writing on GitHub, and is what I use for all of my own documentation. It also exports to HTML and other convenient formats for reading on mobile devices. However, sometimes you want to export it as a PDF so that you can author scientific papers and export the formats that pre-print servers like arxiv.org will accept.
The above example is from the Dat Paper.
Pandoc is a great tool for converting between different print formats. In this case pandoc will handle these conversions for us, all in one command:
Markdown -> Latex -> Latex Citeproc Bibliography Filter -> PDF
To install it on Mac OS using homebrew:
brew install pandoc pandoc-citeproc
See paper.md for an example. You can use YAML frontmatter to specify variables that Pandoc will use as the variables in it's Latex template. To see the Latex template you can run pandoc -D latex.
The pandoc-citeproc filter will automatically generate a references section for you at the end of your document, and also replace all Markdown references an academic citation style.
First you can grab some Bibtex references from Google Scholar and throw them in a paper.bib file:
Then when you render the paper references will get converted automatically if you cite them using the identifier from the bibtex in Markdown like this:
The seminal work [@pizza2000identification]
Once you have .md and .bib files you can generate a PDF like this:
pandoc --filter pandoc-citeproc --bibliography=paper.bib --variable classoption=twocolumn --variable papersize=a4paper -s paper.md -o paper.pdf
Or generate the intermediate Latex source like this:
pandoc --filter pandoc-citeproc --bibliography=paper.bib --variable classoption=twocolumn --variable papersize=a4paper -s paper.md -t latex -o paper.txt
Now you're ready to post the .txt, .bib, .pdf and .md files on a pre-print server, ideally with a CC0 public domain dedication license for maximum openness, and upload it to GitHub so others can access and re-use your research!
