Creating Reveal.JS

This tutorial walks through how to create a Reveal.JS slide presentation using RMarkdown. If you are not familiar with the syntax for RMarkdown, please start with the RMarkdown tutorial and then continue with this tutorial.

Introduction

Reveal.JS is a framework for creating HTML slides developed by Hakim El Hattab. You can find an overview by him here. The framework is not already embedded in RStudio but we can gain access by installing the revealjs library.

In my opinion, these slides look more professional than the ioslides or Slidy packages that are built into RStudio and is a little more interesting to look at than Beamer. And once you’re using RMarkdown its actually pretty easy to apply this formatting. After you set up the basics you can just apply your customizations into all of your presentations.

Here’s an example of a presentation that I created using Reveal.JS. The slides are fully interactive within this webpage. You can see the slides in full-size here.


Let’s get started!

Basic Setup

First install the revealjs package from the R terminal.

install.packages("revealjs")

Then create a new RMarkdown document which will have the following default settings.

---
title: "Untitled"
author: "Vincent Bauer"
date: "August 13, 2016"
output: html_document
---

Change the output from html_document to revealjs::revealjs_presentation.

---
title: "Untitled"
author: "Vincent Bauer"
date: "August 13, 2016"
output: revealjs::revealjs_presentation
---

Customization

That is enough to create the presentation, which already looks a lot better than ioslides or Slidy, but the defaults are a little garish and we can do even better without a lot of effort (or taking advantage of the effort that I already put into the css).

Themes and highlighting

First lets specify some more options that will improve the appearance. The indenting here matters.

---
title: "Introduction to Web Scraping in R"
author: "Vincent Bauer"
output: 
  revealjs::revealjs_presentation: 
    theme: simple
    highlight: haddock
    center: true
    transition: slide
---
  • theme: simple specifies that we want the black and white presentation with a simple font

  • highlight: haddockis a particularly nice color scheme that’s fairly bright, which is good for presentations. This page is using pygments which is similar but a little toned down. I use textmate on most pages because it has the least highlighting.

  • center:true controls the verticle centering of slide content instead of top aligned

  • transition: slide means that slides slide from left to right and up to down instead of box animation

You can find other theme and highlighting options here from the RMarkdown website.

Custom CSS

These changes are easy and help a little but now come the actually important steps.

Add a reference to my custom style sheet that mimics the presentation of Reveal.JS slides in IPython. A CSS files controls the styling of elements in an HTML document using their classes and ids. Notice the references to reveal.css below. I have also ensured that the html document continues to rely on external files rather than embedded in the css information which makes it easier to tweak.

---
title: "Introduction to Web Scraping in R"
author: "Vincent Bauer"
output: 
  revealjs::revealjs_presentation: 
    theme: simple
    highlight: haddock
    center: true
    transition: slide
    css: reveal.css
    self_contained: false
---

You can download my CSS file here. Place the .css file in the same directory as the .html file produced by RMarkdown, which is the same directory that the .Rmd file.

Usage

Organization

Reveal.JS slides are organized by section from left to right and then sub-sections or sub-slides are organized top to bottom. You can always move onto the next section by pressing the left/right arrows, even if you have not completed an entire section yet, which makes it easy to add additional backup slides to particular sections because you can skip them without the audience ever noticing.

The organization looks like the following:

TITLE         SECTION           SECTION          SECTION
               slide             slide            slide
               slide             slide            slide
               slide             slide            slide

You can move up or down within a column or left and right between the tops of columns.

Syntax

The framework mostly uses the normal RMarkdown syntax but makes a few changes.

For instances the # command which normally indicates a Level 1 Header in RMarkdown is redefined as a new Section (i.e. a column of slides), while ##, which is normally a Level 2 heading, now donates a new slide and any text following the ## becomes the slide title which takes the Level 1 Header formatting. To create new slides that do not have titles, just place a ## with no additional text on the same line.

  • # begins a new section (column)

  • ## begins a new slide (row in a column)

  • ### begins a new header within a slide

Advanced

While technically a feature, this way of organizing sections introduces something of a bug because you cannot start a new section with slides that contain normal text. Any text placed after a section begins (#) but before a slide starts (##) is lost.

To get around this, you can change the HTML directly into RMarkdown and it will render it however you want, although this is probably not worth your time for most presentation. Don’t become discouraged, these steps really are not necessary, and I did not follow them to make the example presentation at the beginning.

Setup

Let’s start with the RMarkdown code code for a simple two slide presentation.

This is what the code would look like

#Section Header
If I type things here they will not show up

##Slide 1
text

#Slide 2
text

And this is the HTML that is generated by the revealjs package:

<section>
    <section id="section-header" class="titleslide slide level1">
        <h1>Section Header</h1>
    </section>
    <section id="slide-1" class="slide level2">
        <h1>Slide 1</h1>
            <p>text</p>
    </section>
    <section id="slide-2" class="slide level2">
        <h1>Slide 2</h1>
            <p>text</p>
    </section>
</section>

Notice the text “If I type things here they will not show up” has not been rendered.

But we learn that columns are wrapped in <section class="titleslide slide level1"> while individual slides are wrapped in <section class="slide level2">. Ids are determined based off of the text that is given to the headers.

Editing

If I really want some text on the slide that begins a new column/section I can just add it, like such:

<section>
    <section id="section-header" class="titleslide slide level1">
        <h1>Section Header</h1>
            <p>If I type things here they will show up now</p>
    </section>

But I don’t want to write out the entire slides in HTML, so you can mix and match in RMarkdown to get the result you need.

You can write out the column heading in HTML – making sure not to leave any spaces because RMarkdown will then interpret it as text rather than HTML – but then continue the rest of the slides in RMarkdown syntax just as normal, making sure to close the column that you added manually again at the end.

This works pretty well, but unfortunately it seems like the revealjs package will automatically start with a level2 slide section after the title, which means that the first slide that you insert cannot have children slides. But you can probably do something useful with that space anyways.

Final

Here’s what this HTML/RMarkdown frankenstein would look like:

---
title: "Introduction to Web Scraping in R"
author: "Vincent Bauer"
output: 
  revealjs::revealjs_presentation: 
    theme: simple
---
    
<h1>Unfortunately</h1>
<p>There has to be a slide with no children here</p>
</section>
<section>
<section id="section-header" class="titleslide slide level1">
<h1>Section Header</h1>
<p>If I type things here they will show up now</p>

##Slide 1
back to normal

##Slide 2
text

</section>

#Now a normal column of slides

##Slide 1
text

Its not pretty but it gets the job done and in the end is pretty simple to copy and paste in case you ever actually do want a section to start with normal sized text.