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

A Note on Theme-ing

If you want to build your own theme, then follow the instructions, or just create a copy of an existing .scss file and edit it to your heart’s content.

If you’re just changing a couple of little things, you can of course 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.

Updating reveal.js

In the future, to update reveal, it will be a fairly manual process, but not difficult either. One thing you can do is check the version number and compare it to the current version to see what’s change and only replace those files.

Or, if you are very behind, rename or copy your existing css folder (and any other folders where you may have done customization) as a backup, then replace all existing folders along with the couple of files (.json, .js) files in the main directory. Finally, check the index.html file for any changes to how reveal is loaded at the top and bottom of the file. If there are any major changes, you will need to update those areas of your existing presentations.

Running Localhost for Testing

If you want to test speaker notes and anything else dependant 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. If you’re building your own theme using a scss file or you recently updated your reveal library, then use npm start instead.
3. Open localhost:8080/index.html in your browser. By default it uses port 8000 or 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. So, another option would be to upload the files, wait a minute or two, then test it off of your GH pages.

Some Notes and Tips

Storing Assets

If you’re uploading images and other assets for your presentation, I strongly recommend creating a folder specifically to store them. Feel free to organize the folder with subfolders, but it will keep your repository much more organized and will make it easier to update the reveal files.

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 a 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

• GitHub Pages Intro Page with instructions for clients and terminal
• revealjs on github pages command line instructions