Markdown Slideshow Example: Pandoc

In my last two postings, I introduced a way to create slide presentations by writing them in a simple text file, with Markdown formatting, and add some of the “infinite canvas” features of Impress.js. The resulting presentation (simple example) can be viewed in modern browsers without any special software.

If you want a markdown text based slideshow without any need for the flexible pan/scale/rotate features of Impress.js there are a number of far better alternatives. In theory, one of several advantages to composing markdown text based slides is that, as new and better ways emerge to create browser based presentations, there is very little you should need to change to make it work. Unfortunately, the truth is that differing interpretations of markdown and the way they render markdown text means that the export/import inconsistencies you may be familiar with between PowerPoint/Keynote/PDF do not vanish in the world of plain text and markdown slides. They don’t leave us quite as helpless, however, since it can often take less to tweak a text file here and there, than a mangled deck of slides saved in a proprietary binary format.

One of the favorite tools for converting markdown files out there is Pandoc. Lincoln introduced us to the power of Pandoc last year, with an overview and later a posting on how to use it to create ebooks. It was Caleb McDaniel, however, who helped get me up to speed on using it for presentations and is to be thanked for most of what follows.

Pandoc has built-in support for the conversion of markdown (and a range of other simple text markup) into several browser friendly slideshow formats. These include DZSlides, S5, Slidy, and Slideous (if you know LaTeX, beamer too). Many of these offer a shortcut to display a table of contents and Slideous offers a shortcut to easily change the font size.

For example, let us take the original markdown text that I began with on Tuesday as a very simple example:


To transform this into a DZSlides presentation with Pandoc (see Lincoln’s overview for information on getting it setup), run the command:

pandoc -t dzslides -s -o index.html

This takes my text document and transforms it into a DZSlides web page called index.html when you can then take on the road. So how did this go? Here was the output: DZSlides Example.

DZSlides did not know what to do with the [text] alt label for my image and showed it over the image as text (removing the text within [] fixed this problem). Also, the default styling for the slides also blew my cover image up too much. This trouble with image size was not something I saw in other output methods listed below which made DZSlides less attractive “out of the box.” Finally, it inserted an extra blank slide in because I have a level one header in the following slide. This is not a DZSlides problem but is apparently connected to a convention that Pandoc follows in handling the structure of your slideshow. Although you can get around this problem without any changes to the original markdown file by adding a “–slide-level” option (h/t Caleb!) I went ahead and made minor modifications to the original markdown that I went on to use for all the examples below. The resulting partially fixed out put for DZSlides can be see here: DZSlides Fixed.


For S5 I created the slides with:

pandoc -t s5 --self-contained -o index.html

The “self-contained” parameter I used here allows the slideshow, which might otherwise need a number of supporting files, to be all contained in a single HTML file. This includes the image in my first slide, which is embedded directly into the html file as raw data. DZSlides and the other output options below also support this handy feature. This time my cover image came out a decent size and the alt label on the image appeared below the image instead of over it, so I changed it slightly to serve as a caption. The result is here: S5 Example.


I had some trouble getting Slideous to work but Slidy compiled fine:

pandoc -t slidy --self-contained -o index.html

See the Slidy output here: Slidy Example.


It is also possible to use Pandoc to convert into slideshows that use reveal.js which offers a range of extra features such as multi-directional navigation, the ability to easily zoom out and see an overview of the slides with the escape key, and many others. See an example by Caleb which was created in this way (and the raw markdown text it is based on). Using it with Pandoc does require a bit of a hack, however, in that you must use a template modified from the Reveal.js repository: Using Pandoc with Reveal.js. You also need to download the Reveal.js folder so it has all the necessary supporting files.

I followed this process with the same modified version of my simple presentation text in the previous examples and got the following: Reveal.js Example. Notice that the three hyphens used as a divider between slides in all the other formats simply creates a horizontal line (as markdown is supposed to) and that Reveal.js uses headers to separate slides. I could go back and again modify my markdown accordingly.

Of the various outputs, I found Slidy to be the nicest default, and I’ve noticed its code can be found incorporated into a number of other browser based solutions out there. Reveal.js is nice and offers more power, but until it is supported natively within Pandoc (and hopefully Impress.js output, along the lines we saw with the mdpress tool) it requires a bit more work to get it out the door.


Pandoc and Mdpress from the last two postings are both forms of compilers. In the world of programming, one common division exists between “compilers” and “interpreters” (though the division between the two is sometimes deceptive, it is useful here as a way to imagine a compound or indirect versus a direct process as we experience it).

In the process we have described here, both are involved in a way. Pandoc and Mdpress both take your markdown text file and transform it, or compile, into something else less conveniently accessible, usually a collection of HTML, CSS, and Javascript files (or all three in a “self-contained” HTML file). These, in turn, are formats that are easily interpreted by the browser. How it actually appears in the browser depends on that mix of html/css/js created by the developer of tools like Impress.js, Reveal.js, Slidy, S5, DZSlides, etc.

Our original text-based slides are also composed with a markup format Markdown, that is interpreted, just as HTML and CSS are interpreted by your browser. When you use a Markdown application on your computer (such as Marked, Byword, Mou, or FoldingText on OS X) and “preview” the results, your Markdown gets interpreted just like HTML does in the browser. The primary difference is in the experience of the writer. There is, I would argue, far greater simplicity and aesthetic comfort found in:

# My Presentation Title

Instead of:

<h1>My Presentation Title</h1>

Markdown (and other simple markup formats like Textile) allows us to write in pure simple text but add a very minimal layer of markup that neither distracts us or, hopefully, confuse us with the more complex syntax required by things like HTML or the powerful LaTeX.

As I showed above, we sometimes need to tweak our markdown according to the way it gets interpreted, but the heart of our presentation remains a simple portable text file. Where I think we have a fair bit to go, is in making the styling (fonts, sizes, coloring, positioning, etc.) process far more friendly for the simple tasks we often work with: a markdown equivalent for CSS, if you will.

Have you ever used Pandoc to create your slideshows? If so, what tips might you have to share?

Image by Konrad M. Lawson released to the public domain. Thanks to Caleb McDaniel and Lincoln Mullen for their feedback on a draft of this posting.

Return to Top