From markdown to reveal.js slides with pandoc

Pandoc is a universal converter for markup languages (markdown, HTML, LaTeX, etc). It’s one of those tools that change your life when you discover them. I use it regularly to create various documents from LaTex/docx reports to beamer/reveal.js slides, usually from markdown. Pandoc is also one of the biggest open-source Haskell projects, what’s not to love about that?

This post describes my workflow for generating reveal.js slides from markdown, because writing HTML by hand in 2018 is boring.

Starting with vanilla slides

Producing slides from markdown is straightforward with pandoc. You don’t have to take my word for it, just search for “pandoc markdown slides” or read the pandoc manual.

We start with a slides.md file containing a header of the form

---
author: John Smith
title: Some slides
date: 01.01.1970
---

that defines some metadata used to generate the first slide. Then we can add more slides using --- or by simply starting a new section with a title #. Filling in our slides with some dummy content, we end up with this markdown

---
author: John Smith
title: Some slides
date: 01.01.1970
---

# Let's start a section

## Then put subsections

with some text

# Start a new section

## Make a list

- of items
- that have no meaning
- or coherence
- with **bold text**
- or _emphasized text_

## Show pictures

![Wikipedia FTW](https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia-logo-v2.png)

from local path or from the internet

# {data-background-image="https://upload.wikimedia.org/wikipedia/commons/e/ea/Thats_all_folks.svg"}

We can already generate slides

pandoc -t revealjs \
    --standalone \
    --variable revealjs-url="https://revealjs.com" \
    slides.md -o slides.html

We get a very simple that can be viewed here.

Customizing slides with templates

This is all nice, but how can I change that title font size? or change the theme of my slides? Customization is well documented in pandoc’s user manual. These go through variables

You can also define a template to be applied to your slides and apply it using the --template when running pandoc. My current template is on github if you want to reuse it.

Now running pandoc again with my customized workflow becomes

pandoc -t html5 \
    --standalone \
    --section-divs \
    --template=template-revealjs.html \
    --variable theme="black" \
    --variable transition="linear" \
    --variable revealjs-url="https://revealjs.com" \
    --from markdown-markdown_in_html_blocks+raw_html \
    slides.md -o slides.html

Which yields these slides.

Let’s break it down

The full example is also documented in my personal grimoire on github.

That’s all folks! For real this time. As you can see my workflow is pretty simple, thanks to pandoc. As the metaphor of the dwarfs standing on the shoulder of giants goes nanos gigantum humeris insidentes. We get the best of both worlds: simple yet beautiful slides with minimal effort and a fully reproducible process.