Switching To Reveal.js for Presentations

UPDATE: I presented at one event using reveal.js and have since rebuilt all my presentations in my original toolchain (rst2pdf). One presentation completely resized itself (I used rem units but that didn’t help) so code samples were unreadable/missing. Also each presentation has all the dependencies INSIDE the presentation folder, so any backing up or syncing to dropbox becomes impossible (I ended up tethered to my phone with 250k files to sync …). I like backups AND I like my Dropbox to work. So, no more reveal.js, it’s just not fit for (my) purpose.

Original post retained here for posterity

I give a lot of conference talks, and my new job as a Developer Advocate means that isn’t going to change any time soon! Some of my colleagues have been using reveal.js so I thought I’d give it a try. Well, there were quite a few things that I had to research to get a slide deck that I was happy with, so I am capturing them all here so I can look them up later and in case anyone else needs them.

The Background

I started making slides in Libreoffice Impress as plenty of people do, and I kept using that tool for a few years but as my RSI got worse and I started giving more talks, I quickly realised that I needed to find a tool that didn’t need me to use a GUI to create slide decks – I was paying people to turn scribbled notes and diagrams into slides, and then not being able to edit them myself if I wanted to make changes in my final talk rehearsals.

So I used LaTeX, with a bit of setup help from my friend to get working templates and syntax highlights. Which was … fine, actually. LaTeX really isn’t hard compared to, say, rocket science. Also I like hard things, like calculus and vim.

Eventually the restrictions of a toolchain that I didn’t really understand started to bite and so I spent the last probably 4 years using rst2pdf which is python-flavoured and presenting using pdfpc and its predecessors. Using rst2pdf opened the door to many great things for me, but my new team writes markdown rather than restructured text so I thought it might be time for a change.

Get Set Up

I found the project layout in reveal.js really strange – I haven’t been using tools that have the content integrated in the same project space as the tool and it feels really jumbled. However that is what is expected here – the basic setup is to fork the reveal.js github repo locally (and then I usually push to my own repo), and then edit index.html to include all your content as well as the boilerplate setup and presentation configuration.

All you need to do is:

npm install
npm start – this might open in a new tab of an existing browser somewhere

Once this is running, it will live-update all your changes, so if you change the content, the config, add any assets, edit a theme (including the .scss files), anything: the presentation will reload on the current slide and reflect your changes. This is great for speedy development :)

Use Markdown Rather Than HTML

I don’t really write HTML which has always been interesting for a web developer. I’m definitely not going anywhere near it for content that I want to maintain but happily reveal.js supports writing content in Markdown – and you can just fall back to HTML for anything else. The examples in the docs show boilerplate HTML chunks around every markdown slide but it’s also possible to have a single, separate markdown file and just source it in index.html:

    <body>
        <div class="reveal">
            <div class="slides">
                <section data-markdown="beyond-mysql.md">
                </section>
            </div>
        </div>

Then in the Markdown file, you need to indicate new slides by adding three dashes --- as a section separator (this would normally be a horizontal rule in markdown). Here’s a snippet of that markdown file:

## Beyond MySQL

MySQL is great!

If you're ready for something more advanced, how about:

 * PostgreSQL
 * Redis
 * CouchDB

---

## About PostgreSQL

Homepage: https://www.postgresql.org/

* Open source project
* Powerful, relational database

Setting up the content in the external file means I can work with it without caring about presentation or styling issues.

Working with Themes

There are some instructions for creating your own theme but I still found it a bit confusing so here’s my process.

Pick a theme you like (themes are in css/themes, you can edit index.html to include the one you want). If you like it exactly as it is, great. You can stop here :)

If your theme could do with some alterations/additions, then you should clone and change it. To do this, copy the .scss file that’s one directory level further down in css/themes/source – put the new copy in the same directory with a new name ending in .scss also. The watches scripts that are running while you have that npm start command going will pick up that there’s a new source and generate the CSS for you to include in index.html. Changes should be make to the .scss file, not directly to CSS.

Configuration Options

I’m opinionated about presentations since I see such a lot of them! I was delighted to turn off two-dimensional centering of content (ideal for “lessig” style slides but I’m normally giving quite technical presentations) and also to rid myself of transitions. Reveal.js is configured in javascript syntax at the bottom of index.html so it’s a very accessible way of finding and changing settings – and the README for the project has a good list of settings and defaults. I tweaked a few things, and here is my configuration:

	// More info https://github.com/hakimel/reveal.js#configuration
	Reveal.initialize({
            history: true,
            progress: false,
            controls: false,
            center: false,
            slideNumber: true,
            transition: 'none',
            transitionSpeed: 'fast',
            width: 960,
            height: 540,

I found this StackOverflow question and added a footer using the linked example.

Giving Presentations With Reveal.js

Actually presenting has been a bit of a challenge so far, especially as different size screens seem to cause the HTML generated by reveal.js to resize so you can practice on three different projectors/screens and still have it spill out at some critical moment! If you have to, you can zoom out a bit just to fit something more on but after years of PDF I am not enjoying mid-presentation surprises of this nature.

I use Chrome on OS X so you may need to adapt some of these shortcuts for your platforms. My presenter remote works perfectly well with reveal.js which is a good start! Some other keys I use:

s to show the speaker notes in a new window, these show the current and next slides, the current time and the elapsed time – if you set up before you actually start talking, you can click on the time block to reset the timer. This also shows speaker notes but I don’t use those.
arrow keys to move between slides
f to full-screen Chrome
b to black the screen

I’m also a Vimium user, which is a plugin that lets you use your web browser from the keyboard. I would like to find out how to detect reveal.js and disable vimium but for now I am just excluding the “f” and “b” keys in Vimium for the http://localhost:8000 that reveal.js usually runs on.

Reveal.js As A Presentation Tool

Using the browser feels less safe than having a PDF that you’ve printed and tested, but now I’ve overcome the major hurdles (more blog posts to come, on generating PDFs and handling syntax highlight) at least I can choose to present with this tool if I want to. As I said at the start, since I had to do so much research and ask questions, I thought I’d collect it all into one place in case anyone else needs it.

5 thoughts on “Switching To Reveal.js for Presentations”

Paul on September 21, 2016 at 10:08 said:

If you like writing Markdown, Pandoc is another option for creating slides. I don’t think it supports all the transition effects but it does produce a PDF which should work on any machine – particularly handy for conferences where all slides run off the same machine instead of speakers using their own (e.g. UKNOF).

Reply ↓
- lornajane on September 21, 2016 at 21:50 said:
  
  I love pandoc but have had no joy getting it to create any kind of presentable output at all. If you have some examples of that, I’d be interested to give it a try. Reveal.js is a bit of a pain to work with – the tool is tangled in the content so the number of files needed to back up your talk is astonishing. Not sure I will be sticking with this one for long.
  
  Reply ↓
  - Paul on September 27, 2016 at 14:19 said:
    
    I guess it depends what you mean by presentable – I run ‘pandoc -t beamer -i slides.md -o slides.pdf’ and that gives me a PDF which reveals one bullet point per slide and highlights the syntax on any code blocks. It’s rather basic but I prefer to keep slides simple in case they need to run on a machine without the same fonts etc. (and I’m definitely more dev/sysadmin than design/UI).
    
    Reply ↓
  - Gour on October 14, 2016 at 00:20 said:
    
    > Reveal.js is a bit of a pain to work with – the tool is tangled in the content so the number of files needed to back up your talk is astonishing. Not sure I will be sticking with this one for long.
    
    Thank you for this comment…I’m looking for some tool before starting work on series of presentations for the regular lectures I’m conducting…Wanted something different than Beamer (was using LyX/LaTeX) and was considering AsciiDoc(tor)+Reveal.js, but also have feeling that JS-stuff is, in general, not my cup of tea. :-)
    
    I also tend to have more simple slides for which PDF can be enough.
    
    Of course, ConTeXt macro package is serious contender considering I can use Emacs to prepare content and the learning curve might be worthwhile…I’m going to investigate using e.g. AsciIDoc markup + Pandoc which can convert e.g. ConTeXt…
    
    Reply ↓
Kristofer on May 22, 2017 at 20:35 said:

So, what did you switch to instead of Reveal.js? Did you find anything better? (I’m referring to the disclaimer comment in the top of the article.)

Reply ↓

LornaJane Blog