How to host Reveal.js slides on GitHub pages and have a tidy repository

Let’s say you want to create slides with reveal.js and host them on GitHub pages for free to show everyone that you don’t use PowerPoint. But let’s add that you want a clean and manageable way to do that, without copy-pasting library files or create jumbo commits on your GitHub repository with code that you didn’t write either. And what if you also want to upgrade reveal.js version without having to repeat this lengthy procedure?

Messy repositories

The most common way to deploy reveal.js slides on GitHub pages is to download the latest release of the library and then add to your repository all the files, as explained in this other medium story. Congratulations, you have your slides working! But what if you take a look at your repository? Let’s take a look at one random example:

Example of files used for a presentation

Do we really need to version on our own all the css and js folders and files? Can’t we just commit the files that we customised or created on our own? (usually only the index.htmlfile)

reveal.js is a library, not our code. And in a repository, the provenance of the files should be clear (e.g. to do a git blame or to overwrite the library files with a new version without erasing our own modifications).

There are different variations, and each one of them does not feel “ok”:

• versioning on our own the entire reveal.js repository content
• using the gh-pages branch to commit the library files and keep our files on the master branch. In this way, every time that you want to create a commit, you have to: 1) switch to the master branch (because you are on the gh-pages if you're going to run your slides locally) 2) commit the file here 3) switch back to the gh-pages branch and merge the master 4) push both the branches to have the “nice and clean” master and the “messy and complete” gh-pages
• use reveal.js as a dependency on a npm project: this is a bit of overhead if we want just to create slides. And in this way, you also need to define a task that builds your frontend and puts it in the gh-pages branch of your repo (you may need considering Webpack)

Solution: submodules to make it easy and clean

Luckily there is an easy solution that uses the submodule functionality. And GitHub pages will take care of initialising the submodules.

Just the essential files are versioned, submodules make the repository clean

With this solution, we have:

• one git submodule that points toreveal.js, with a specified and recognisable version
• one index.html file that contains my slides
• just one branch without the related mess of having to switch or commit on the wrong one

Give me the instructions!

The instructions to obtain this configuration are the following:

instructions for setting up the submodule

The differences needed compared to the traditional usage of reveal.js

Example index.html:

example presentation

You can now test on your local environment that everything works, using one of the many servers (e.g. live-server).

To publish on GitHub pages, you just need to push and configure GitHub Pages to take from the master branch.

What if I want to change reveal.js version?

Leaving the code on another repository makes this pretty easy:

• cd reveal.js to go in the submodule
• git checkout tags/3.9.3 to select the version
• cd .. go back to your repository and test if everything is working (maybe there are breaking changes on its API)
• git add reveal.js && git commit -m “changed reveal.js version” && git pushto deploy the new version

One-click template

And what if you could just create your Reveal.js slides using this strategy with just one click, without requiring to copy and paste code from here? Well, thanks to Marcus Baw, we have available a repository template that we can use without even needing to open the command line: https://github.com/pacharanero/2021-revealjs-template

Click on the “use this template” button, pick a repository name and your slides are ready.

Recap

• avoid committing reveal.js files: it does not look good
• easily change the reveal.js version without creating huge commits and risk to overwrite your customised files (keep them in your repository)
• clearly see the few files that you created for the slides. Like any other languages, you don’t version the node_modules or venv folders because that’s not your code