Yesterday, I described why my current presentation stack needs an overhaul. Today I'm going to show you my new stack. This how-to will introduce a little helper project that will allow you to easily kickstart a new Reveal.js presentation, split it up into subfiles and host it on Github Pages.
When I played around with Reveal.js I
immediately fell in love with it. There is just one thing that bothers me: You
are supposed to put your whole presentation into one big
index.html file. I
don't want to do this because I'm going to collaborate on the slides with
others and I want to avoid merge conflicts. Therefore I would like to split
that one big file into many small ones (i.e. one file per slide).
So clearly, we need a templating engine which is able to include other sub templates in its main template file. Jinja can do that and if you are familiar with Django's templating engine you will feel at home with Jinja immediately.
Ultimately, this little "hack" is another great example why Python and its ecosystem are awesome and why everyone should know a little bit of Python. Remember: We are not trying to do any coding here. We just want to produce some beautiful (and powerful) presentation slides.
So let's start cooking:
For your convenience I have prepared a little template-project on Github to kickstart your Reveal.js presentation. All you need to do is clone the project and initiate a new repository:
git clone https://github.com/mbrochh/reveal-template your_presentation_name cd your_presentation_name rm -rf .git git init git add . git commit -am "Initial commit"
You should be able to execute
open presentation/index.html and see a basic
presentation with a few test slides.
In order to use Jinja and Fabric you need to install a few Python packages. As always, you should first create a virtual environment and then install the packages into that environment:
mkvirtualenv -p python2.7 your_presentation_name pip install -r requirements.txt
This will take a while. When it's done you should be able to run
You might also want to install observr in order to build your presentation whenever you save one of the template files.
As always, when you want to publish stuff on Github pages, you need to have one source folder with your raw content, which will be part of your Git repository and one destination folder with your compiled content which will usually not be part of the Git repository.
In our case the source folder is called
source and the destination folder
presentation. I cheated a little bit. Not everything in the
destination folder is under
.gitignore. I put the Reveal.js sources in there.
A cleaner solution would have been to add those sources as a git submodule
and copy them into the presentation folder every time you run
Maybe I will do that later. However, the index.html file in the
presentation folder is in .gitignore and will be compiled every time you run
Now have a look at the
source folder. You will find six files:
- source/ - base.html - index.html - title.html - test_markdown.html - test_code.html - test_backgrounds.html
base.html contains all the HTML boilerplate stuff that is needed to display a
proper Reveal.js presentation. Once you have set this up (i.e. included all CSS
styles and plugins, changed the title etc.) this will rarely ever change again.
index.html is our Jinja template. It extends
base.html and includes
all the remaining files, which are our individual slides.
In order to create the final
presentation/index.html we need to tell Jinja to
source/index.html template and render it into the destination
folder. I have created a tiny Fabric task for this, so all you need to do is
Now when you are working on your slides you probably want to review them in
the browser all the time, so you would have to run
fab build all the time,
which sucks. A proper solution would be to setup a tiny webserver which listens
to requests and returns the rendered template (might do that later) but for
once I suggest that you simply install observr and keep it running in a
separate terminal widow. In order to watch for changes, I have created a small
shell script which you can execute via
Hint: Don't forget to stop observr when you don't need it any more. It eats 20% CPU all the time, which will eat your battery in no time when you are on the go ;)
requirements.txt file I have added the awesome ghp-import
tool which really opened up the glorious world of Github Pages for me. Again I
provided a small Fabric task, so in order to publish your presentation simply
It will create the
gh-pages branch and push it. A few seconds later you
should be able to see your presentation at
I haven't had the time to try this myself, yet, but the instructions for multiplexing in the Reveal.js README seem to be straightforward. The idea is that you start a local webserver and your audience will browse to your IP. Now your audience will be connected to you in real-time, so when you change a slide, it will change on all screens.
That's it! I hope my little reveal-template will be useful to someone and allow you to publish awesome presentations in no time - have fun!