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.
- Basic HTML knowledge (preferably CSS)
- Github account
- 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.
- Create a new repository (call it presentations or whatever you want)
- Download and add the latest revealjs (minus N/A things e.g. license, travis, test folder)
- Create new branch, ‘gh-pages’ with a copy of everything in your master, then sync.
- On the github website, find your repository, go to ‘Settings’
- In Settings, set ‘Default branch’ to ‘gh-pages’
- Back in your client, Unpublish (or delete) ‘master’ branch.
- 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.
- Install node.js
- Go to your command line (i.e. Cmd in Windows or Terminal on Mac), type “npm install -g http-server”
- Have a drink, let it run.
After setup, any time you need to start the server for testing:
- Go to your repo directory in your command line, enter for example: cd “C:\Users\user\My Documents\GitHub\presentations”
- Type “http-server” to start a localhost server.
- 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.
That’s it. You can check out what I’ve done if you’re interested on my presentations repo.
- GitHub Pages Intro Page with instructions for clients and terminal
- revealjs on github pages command line instructions