Using Reveal.JS on GitHub Pages

So after getting yelled at by @adr, I decided that I would finally move away from PowerPoint and use reveal.js for my presentations.

Unfortunately, while it seemed fairly simple, all the instructions I found involved the command line, which I didn’t want to use unless it was absolutely necessary. So here are the basic instructions without command line use.

Requirements

  1. Basic HTML knowledge (preferably CSS)
  2. Github account
  3. For testing, very basic command line knowledge.

If you ended up on this page, but don’t want to be writing HTML or learning how to load up reveal on Github, check out their browser based GUI-like editor over at slides.com (formerly rvl.io).

“Installing” reveal.js on GitHub Pages

These assume that you’re using a GUI client.

  1. Create a new repository (call it presentations or whatever you want)
  2. Download and add the latest revealjs (minus N/A things e.g. license, travis, test folder)
  3. Create new branch, ‘gh-pages’ with a copy of everything in your master, then sync.
  4. On the github website, find your repository, go to ‘Settings’
  5. In Settings, set ‘Default branch’ to ‘gh-pages’
  6. Back in your client, Unpublish (or delete) ‘master’ branch.
  7. Edit the index.html or add a new .html file and create away!

If it’s your first time creating a gh-pages branch, it will take a little while (it took ~30 minutes for me) for your site to work. To test, it should tell you the link, but it will always be: username.github.io/repository-name

Themes Dependencies Workaround

If you read the themes readme, it’ll instruct you on installing quite a few dependencies and that you then need to write the themes in SASS.

I for one am not going to do all of that just to change a couple of colours. So, while a very seemingly obvious thing,

Tip: Add your own custom css file and add the stylesheet after the theme stylesheet in the HTML head, overriding specific classes in an existing theme with your own tweaks.

Running Localhost for Testing

If you want to test speaker notes and anything else depending on node, you’ll need to run your presentation off of a localhost instead of just opening the html file in the browser.

Setup

  1. Install node.js
  2. Go to your command line (i.e. Cmd in Windows or Terminal on Mac), type “npm install -g http-server”
  3. Have a drink, let it run.

After setup, any time you need to start the server for testing:

  1. Go to your repo directory in your command line, enter for example: cd “C:\Users\user\My Documents\GitHub\presentations”
  2. Type “http-server” to start a localhost server.
  3. Open localhost:8080/index.html in your browser. By default it uses port 8080 (but it’ll also tell you in the command line window).

Just a note that you do not need to do anything extra in your repository. Github pages will load node on its own.

Some Notes and Tips

On Using Markdown

Reveal.js will convert markdown for you if you add the appropriate tag in each section. However, if for some reason you don’t want to do that, you can use an online markdown to HTML converter.

You can also combine HTML and markdown.

On Code Hightlight

The code highlight simply highlights code, but your page will still process HTML inside the code highlight as actual HTML, so remember to use HTML entities, such as & lt; and & gt; (without space) for < and >.

Printing to PDF

Of course, if you used a custom.css hack sheet instead of doing it the proper way, you may encounter some issues when printing to PDF.

For example, I had to remove top margin and add max-height: 650px; to all img, otherwise if I had anything below or above the image, it tended to overflow onto a second page. I had to play around with the value a bit by printing, checking, adjusting, and repeat.

Just be aware that you might need to spend a little time to get this right.

Complete!

That’s it. You can check out what I’ve done if you’re interested on my presentations repo.

References

Published by

Cynthia

A librarian learning the ways of technology, accessibility, metadata, and people

3 thoughts on “Using Reveal.JS on GitHub Pages”

    1. Glad you found it useful. GH pages is definitely a good way to test websites, especially if you know the environment is similar (namely that any dependencies are loaded on both your test and your production server).

      If a web builder provides GH integration that’s great! I’ve never used a web builder, so I would be cautious about whether you know exactly what the program is uploading and how it accesses GH. Do you know all the code that’s being uploaded? Can you be sure there’s nothing malicious in there? Is the program on your computer the only thing getting access to your GH account, or does the program send that information back to the company that built the program? If it’s a reputable, trusted company/program then you should be fine. (I’ve just personally never heard of mobirise, so I know nothing about it.) Hope that helps.

Leave a Comment

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s