Overview

If you’re a web developer and have been asked to give a presentation and need accompanying slides, then check out reveal.js.

If you go this route, you will probably start by cloning the reveal.js repository, finding the index.html file, and then you’ll begin replacing the default content with your own.

If you’d like to have some help with fitting your content into reveal.js, then you should take a look at reveal-ck. reveal-ck is short for “reveal.js construction kit.”

It requires basic comfort with ruby and haml, and allows you to focus on putting your slide content into a single file which will become an input to a command line tool.

The reveal-ck gem comes with a command line tool of the same name (reveal-ck) that transforms your content into a reveal.js slide deck.

A Quick Example

Open up a terminal, and make sure you have Ruby 1.9.3+ with ruby -v.

Then, install reveal-ck with gem install reveal-ck --no-rdoc --no-ri.

Verify that reveal-ck is present with reveal-ck --help.

As a first step toward creating a set of slides, put the following into a file named slides.haml:

%section
  3

%section
  2

%section
  1

%section
  Contact!

Each %section above represents a new slide. There are four slides: 3, 2, 1, and Contact!

Once you’ve got that saved in a file name slides.haml, run reveal-ck generate, and you’re done!

Your slides will be available at slides/index.html. If you are using MacOS, you can preview them with open slides/index.html.

I’ve generated these slides and put the result online.

The Basics

The example above is as simple as it gets. Here are a few more thoughts on getting the most out of reveal-ck and reveal.js.

haml

The content that goes in slides.haml is haml.

The reason reveal-ck does not author slides only in Markdown is because most of the really neat and more advanced stuff that you can do with reveal.js requires the ability to get at the underlying HTML classes and attributes.

Haml has a slight learning curve, but it is pretty slick once you get going. If you’re new to haml, check out the haml reference or the haml tutorial.

slim

You can also use slim with reveal-ck. The general idea is the same, but create a file named slides.slim instead.

If you’re new to slim, check out the slim reference or the main slim site.

markdown

If you don’t need the more advanced features of reveal.js, or if you just like markdown, reveal-ck bundles redcarpet for markdown processing. This means that you can embed markdown in both slim and haml. For example, in haml:

%section
  :markdown
    # Hello
    ## ..there!

ruby

You can also author slides in Ruby. The benefit of doing this is that you can build out a presentation programmatically. Here are some instructions if you’d like to learn more.

Alternate Slides File

By default, reveal-ck expects to find your slides in a file named slides.haml, slides.slim, or slides.rb. However, you can pick a different name that ends with haml, slim or rb and invoke reveal-ck like so:

reveal-ck generate --file water-slides.haml

reveal.js effects and styling

To get the most of out reveal.js you need to understand the classes, markup, and data attributes that it expects. For example, if you want something to be initially hidden and then fade in when you advance slides, you need to add the fragment class. Here’s an example where everything with fragment is hidden initially and then appears in stages as you advance:

%section
  %p
    RSpec is
    %a{ href: "https://github.com/rspec/rspec" } Behaviour Driven Development for Ruby
    %span.fragment And this is great.
    %span.fragment And RSpec is great.
    %span.fragment But..

And here is an example where vertical slides are used:

%section
  %section
    Vertical Slide 1
  %section
    Vertical Slide 2

The way to make progress here is to look at reveal.js proper and read through its documentation (and examine the markup for the default slides). reveal-ck has an embedded version of reveal.js. If things aren’t working as expected, drop me a line— reveal.js will get out of date over time. It only takes a moment to update, but the gem has to be republished: just let me know.

Supplying a Config

reveal-ck pays attention to a central configuration file. You can create a file named config.yml in the same directory with your slides files and put the following into it:

author:     "Your Name"
title:      "The Title of your Presentation"
theme:      "night"
transition: "default"

This will change the <title> of the slides as you might expect, and theme can be set to any of the available themes in reveal.js. Same goes for transition. By adding this file and regenerating, you can end up with this result.

Bundling Up Images

As with any HTML document, if you’ve got an <img/> you can make the src absolute. However, if you don’t have (or don’t want) images hosted anywhere, you can also bundle them up with reveal-ck.

If you’ve got a slides.haml, create an images/ directory as its peer and put your images in there. When reveal-ck generate runs, anything in images/ will be bundled up into the slides/ directory.

In short, this means that you can reference those images with the following:

%section
  %img{ alt: "My Image", src: "images/my-image.png" }

Displaying and Hosting

If you are connecting your computer up to a projector and displaying slides to an audience, you can simple open them in a browser.

If you want to make them accessible online, you get the benefits of presenter mode (hit “s” while presenting) as well as being able to view them from anywhere.

Because reveal.js slides are static content, you can generate the slides/ directory and place the contents anywhere using whatever tools you prefer.

If you’re already using Github, you should consider using Github Pages. In short:

Start tracking your project with git. You’ll have a single master branch initially.
When you generate your slides, add and commit everything in slides/
Create a new repository on Github. Push your master up to Github’s master.
Finally, also push your master up to Github’s gh-pages branch.

Because of how Github Pages works, if your username is jedcn and your repository is my-talk, then the contents of your gh-pages branch will be available at http://jedcn.github.io/my-talk/. Slides are generated in the slides/ directory, so you will find your content here: http://jedcn.github.io/my-talk/slides.

More Help?

Here’s a quick overview to reveal-ck.

And here’s a Getting Started page.

If these aren’t enough, let me know what’s missing.

In Closing

reveal.js is awesome.

Before I knew about it, I’d be coding along in Emacs (or whatever) and if I knew slides were in my future I’d boot up Keynote (or whatever).

Now, with reveal.js, you can author slides without ever leaving your favorite editor. They are plain text, so they can be easily managed in source control. On top of that, they look great, are mobile aware, and if you host them on the web, you can easily bring them anywhere.

Taking it one step further, I like using reveal-ck when dealing with reveal.js because:

reveal-ck allows me to isolate my content (the slides) from the 70+ files that come with reveal.js
reveal-ck allows me to focus right on my content (the slides.haml).

In short, reveal-ck takes less work to make a better presentation.

At any rate, I hope this helps. Let me know what you think.

jedcn.com

Notes in Passing

Reveal-ck