How do I bodge a quick report using Markdown

For long enough I’ve been able to avoid using Microsoft Word as much as possible. Since I got the chance to get acquainted with John MacFarlane’s pandoc I don’t see any reason to come back. I’ll present you some tooling using vim, make, pandoc, and some extensions to pandoc to produce great report, article, issue from Markdown.

Let’s get started with a simple Markdown document with some metadata formatted in YAML.

---
title: My first report
author: Yoan Blanc <yoan@dosimple.ch>
---
Hello world

Okay, let’s turn this into a PDF file via latex.

$ pandoc -t latex -o hello.pdf hello.md

Et voilà!

As a lazy vim user, I like to compile from the editor using a Makefile. Let’s create one. Beware, that Makefiles use tabs, if you copy and paste from the following snippet, it may not work.

SOURCES=$(wildcard *.md)
PDFS=$(patsubst %.md,%.pdf,$(SOURCES))
.PHONY: all
all: $(PDFS)
%.pdf: %.md
       pandoc -o $@ \
              -t latex \
              $^

Okay, now I can simply run :make from vim and it produces the PDF which is automatically updated by the reader.

The table of Contents

In markdown, titles are defined using the pound# , ## , and so on. Pandoc knows how to turn that into a beautiful table of content. Enrich the Makefile with the --toc and --toc-depth N arguments.

Nice isn’t it?

Localisation

Sometimes I’m also writing in French, my mother tongue. By default, it displays Table of contents in english, which is a bummer. We can set the language into the metadata and change it to the proper Table des matières.

---
title: ...
lang: fr
---

Links

The de facto output for Markdown is HTML, hence I tend to put links all over the place. By default, you can click on them but they won’t appear formatted and the URL is not visible if you were to print the document. Once again, using the metatdata, we can instruct Pandoc to deal with the links.

---
title: ...
lang: ...
linkcolor: pink
urlcolor: blue
links-as-notes: true
---

At this point, you document is much better suited for being printed.

Figures

Our first plugin is pandoc-fignos. It enriches pandoc with figures references. When using a picture, you may reference it by specifing an identifier. That can be later referenced by @fig:... .

![alt text](myimage.png){#fig:id}
+@fig:id shows that...

Pandoc is not only aware about Markdown, but also abour Latex. It means we can also create a proper List of figures.

\listoffigures

The filter needs to be called using the pandoc command --filter pandoc-fignos . Add this to the Makefile.

Bibliography

And last but not least, pandoc-citeproc. I tend to manage by bibliographies using bibtex, but we can also do it manually in the metadata.

---
title: ...
references:
- id: ref
  title: ...
  author:
    family: ...
    given: ...
  URL: ...
  issued:
    year: ...
    month: ...
    day: ...
---
According to that famous study [@ref], ...
# Bibliography

And another pandoc filter --filter pandoc-citeproc to the Makefile brings you a wonderful bibliography. Other formattings may be used but this is left as an exercise to the reader.

Customization

And to conclude, let me share with you the styling I’m using it terms of fonts (Linux Libertine), class (Koma-Script) and options (recto-verso).

---
title: ...
mainfont: Linux Libertine O
sansfont: Linux Biolinum O
papersize: A4
documentclass: scrartcl
classoption: twoside
fontsize: 12pt
---

Vim and pandoc are the best authoring tools I’ve met so far. I have to keep everything stupid simple and let latex do the rendering. The fact that you cannot control most of the rendering (unless you fallback to writing latex manually) let me focus of the text and only the text.

By the way, Markdown and Latex are only a fraction of the wonderful options given by Pandoc.