Academic Pandoc

Last year, I decided that I was going to break out of the Academic LaTeX convention and write my Masters dissertation in Markdown. I've collected these resources to help others bootstrap a new academic project with Pandoc and Markdown.

For the unfamiliar, Pandoc is a document conversion tool that can turn a carefully thought out superset of Markdown into a PDF (via a compile to LaTeX). It's perfect for writing reports and short papers, but the documentation can be sparse and it can be especially difficult to find examples of LaTeX interop for more involved writing.

This repo comes with everything you need for:

• Multiple Chapters
• References & Citations
• Figures & Listings
• Appendix

Here's an example of the kind of PDF this will generate.

Getting Started

To get started you'll need to install Pandoc, Citeproc and LaTeX.

sudo apt-get install pandoc texlive

Then clone this repository.

git clone https://github.com/danprince/academic-pandoc.git 

To compile a PDF, run ./scripts/build then find the output at publish/publish.pdf.

References & Citations

You can collect your references in a BibTeX format in the references.bib file and many research tools will provide you with an option to export to BibTeX format. Alternatively, some services like Google Scholar will provide BibTeX ready references for citations.

For example, if we wanted to cite Chris Okasaki's Purely Functional Data Structures, then we can run a search on Google Scholar, click the cite link and choose the BibTeX option to end up with the following:

@book{okasaki1999purely,
  title={Purely functional data structures},
  author={Okasaki, Chris},
  year={1999},
  publisher={Cambridge University Press}
}

Copy that reference and add it to your references.bib file.

Pandoc's markdown format has been enhanced to allow pandoc-citeproc to recognize citations in the following format.

@okasaki1999purely

Or you can cite a specific page

[@okasaki1999 p. 104]

Or a range of pages

[@okasaki1999purely, pp 45-48]

Figures & Listings

Pandoc's markdown format makes it easy to insert images and code blocks, but without LaTeX you won't be able to caption, list or reference them. However, you can embed LaTeX commands into your Markdown to make this possible.

![Some Figure Caption\label{fig:unique-name}](figures/misc/some-figure.pdf)

Then you can reference the figure from elsewhere, using the \ref command.

See \ref{fig:unique-name}.

The end result should look something like this.

Creating a reference to a listing for a code block is similar.

```{caption="Listing Caption" label=lst:unique-name}
(defn menu [state]
  (render [this]
    (dom/ul nil
      (map (fn [item]
        (dom/li nil item))
        (:items state)))))
```

It can be referenced in the same way.

See Listing \ref{lst:unique-name}.

Which will generate the following.

It's not enforced, but it's good practice to prefix your labels with lst: and fig:. This will help prevent naming collisions.