Presentations on steroids

Learn how to combine reveal.js+pandoc+GitHub Pages to put together a great presentation.


Reveal.js is a great framework for producing awesome presentations. If you are reading this, then you are probably already familiar with it; if you don’t, and you give presentations using slides, then you should stop reading immediately and go read about Reveal here. This article explains how to host your presentations on GitHub pages. Check this page to see what the result looks like.


I find it very convenient to host my presentations on GitHub for three reasons. First, I deploy and then I don’t need my laptop with me anymore: usually at conferences or in class there is always one desktop computer connected to the projector: I can open the browser, visit the page hosted on GitHub and it always works. Second, if somebody wants to check the presentation later, he does not have to download anything or ask me to send the slides: write down the url and visit it whenever you want. Finally, If I have to make a small change, I can use the GitHub editor: the presentation is updated on the commit. Convinced? Keep reading to learn how to do it.

How to do it

Create an empty repository on GitHub

The first thing to do is creating a new repository: we will call it reveal_HelloWorld.


Set a branch for Pages

Now you have to specify which branch to publish: got to, and from the menu branch under GitHub Pages set master as the source branch, then click save. At this point you don’t need to do anything else on the GitHub website: close the browser and open the terminal.


Clone reveal.js

Download reveal.js on your local machine inside the folder reponame

git clone reponame

Set your GitHub repo as the default origin

This commands remove the remote origin of reveal.js and connects it to your newly created repo:

cd reponame/
git remote rm origin
$ git remote add origin

Where reponame is the name of the repo that you just created on GitHub.


We are almost done: let’s push! I use the -f option to overwrite the that is in the remote branch: I initialized the repo with the README so that I could go directly to the settings and set master as the source branch for Pages; if the branch is empty, you can’t do that.

$ git push -f --set-upstream origin master 

Now you have just pushed the demo presentation of reveal.js to your repository. You can see it here: If you can’t see it, then give it a minute.

Editing the presentation

To create your presentation and replace the demo, you have to modify the index.html file. A quick way to do it is to write it in markdown — one title per slide — and then export it to HTML using pandoc (follow the instructions to install it).

This is my sample presentation in markdown:

# ./revealHello/
author: Angelo Basile
title: Reveal.js+GitHubPages+Pandoc
date: June 21, 2017
# Reveal rocks

Some code

       print("hello world")

# Slide 2

* test
* test

Now, assuming that you have in the the presentation folder, you type the following to export the presentation from markdown to HTML.

$ pandoc -t revealjs -V revealjs-url=./ --slide-level=2 -s -o index.html

Note: you have to set the number of levels that you want, otherwise you will produce one big slide.

Now you are done: push again to save the changes and update your presentation online.

$ git add .
$ git commit -m 'edited presentation with pandoc'
$ git push

If you enjoyed the article, consider subscribing to the newsletter to receive free updates directly in your mailbox.


create a new repository from

got to

under GitHub Pages set the variable source to master branch and click Save


$ git clone reponame
$ cd reponame/
$ git remote rm origin
$ git remote add origin
$ git push --set-upstream origin master


Here is a screencast that shows that whole process: