GAMSD

computing scientist and software programmer

Beautiful collaborative presentations with reveal.js and Docker

Recently in a chat with my friend and manager at VivaReal Luis Guerrero, we caught ourselves discussing the best way to build presentations in a collaborative way. I rather build my presentations from code, using reveal.js, that's how I am most productive. While I was building one of such presentations, though, Luis rightly pointed out that we didn't have a good setup to work on it as a team.

Being a programmer, I knew I could make it better with not a lot of effort. I've been playing with Docker lately, so decided to give it a try. The results are quite interesting, see for yourself!

From this point, I assume you are slightly familiar with Docker or working on a tech-savvy team. If you are not, I suggest you check out slides.com for teams, it is reveal.js as a service with tools to lower the barrier to entry for less tech-inclined people.

Simple markdown-based presentations in two steps

I'm a big fan of Markdown. I use it a lot to structure thought, to write these blog posts and also to build presentations. Building presentations is the easiest. In two steps:

  • Write a slides.md file, using --- to separate the content for each slide (see example)
  • Let Docker set everything up for you in a single command from within the same directory: docker run -v `pwd`:/revealjs/md -p 8000:8000 -d gamsd/revealjs-md

Move your browser to http://192.168.99.100:8000 and see what you've just done. You can edit your file locally and refresh the browser to see the changes you make. If you need to use any images, put them under a images/ folder and they'll be available to your presentation under md/images/. You can also use -- as separator for data verticals and Note: to add speaker notes to any slide. Take a look at reveal.js's site to see what verticals and speaker notes mean.

If you're running Linux, you should probably point your browser to http://localhost:8000. If you're running docker-machine on a Mac, check out my last post on docker-machine networking, IPs and port forwarding.

The slides.md file is easy to write, can be versioned as source code and can be run as a presentation anywhere where Docker is set up.

Rich presentations with HTML, JS and D3JS

Sometimes a simple static presentation will do. Other times we need more flexibility. In these ocasions I want to be able to use all the power I can get from HTML and JS, thus I built a more general docker image. The idea for this image is to push all of your presentations directory tree into a reveal.js ready container.

So if I wanted to locally deploy and work on all my presentations, I could just clone my repo, move into my talks directory (see https://github.com/gamsd/gamsdcom/tree/master/revealjs/talks) and run:

docker run -d -p 8000:8000 -v `pwd`:/revealjs/talks gamsd/revealjs  

My talks would then be available under http://192.168.99.100:8000/talks. Each folder is an independent reveal.js presentation and each of them can reference anything inside its own directory. This way you can use as much technology as you want. For example, you can have your presentation change itself based on real-time data or use in your slides the same data visualization components that you use in your reporting applications.

You should only pay atention that your talks will be deployed under /talks/{your-presentation-name}, so your index.html files would need to reference reveal.js components two levels above itself. Instead of <script src="js/reveal.js"></script>, you would have <script src="../../js/reveal.js"></script>.

You can find a complete example of a D3.js-ready reveal.js talk in https://github.com/gamsd/dockerfiles/tree/master/revealjs/examples. Follow the README and get started in no time!

Collaborate!

So, this is it. No matter how complex your presentation is, if you're working on a highly-technical team you can build it from code using reveal.js. You can keep it versioned and collaborate on it as code using Github and can remove the burden of setting things up using readilly available Docker images.

Granted, if your team is not that comfortable with HTML and JS, there are better alternatives like the already mentioned slides.com or the ubiquitous Google Docs. Choose accordingly!

Enjoy!

Kudos to Peter Parente! The work depicted in this post is heavily based on his work, adapted to my own needs. Check out his blog and see how his solution works for you.

Finally, what about your team? What do you use to build your presentations and collaborate on them? If you tried any of the examples in this post, what are your impressions and how do you think they could be made easier? Share your thoughts in the comments!