Using Github Pages for Presentations

Categories: presentations howto

This post is a description of how to use GitHub Pages as a way to generate slide presentations as simply as you can use it to generate a blog. In order to provide some context, I’ve included a little bit about my motivations when choosing the various tools, that are used in the process, in the hope you get a better understanding of whether this might be useful for you.

For the TL;DR version, skip ahead to the section To make a presentation

Introduction

For a while now, when I’m working on presentations, I’ve been trying to focus on the content rather than styling. It seems like a sensible approach, however I’m easily distracted by all the shiny formatting and transition options available. So, in order to help me in my aim of focussing on content, I wanted to just use plain text files to create the content. That would have the additional benefit that I could use a source code control system to keep track of any changes, which helps when collaborating on presentations, by allowing people to see what has changed in each edit.

reveal.js

I decided to use reveal.js, since it generates a presentation from text content and then presents it, including things like slide transitions and speaker notes, if you want them. It works with HTML files, but also supports using MarkDown for creating the slide content. It worked resonably well for the presentations, but it required that reveal.js was included in the source of the presentations, so that a starter template for a presentation already had a lot of files included in it. It seemed very cluttered to me that there were so many files but the important content was only in one, even though it was only in the source files the content was being hidden.

reveal-md

So I looked into reveal-md. It’s intended to use MarkDown files for a presentation and converts them into a reveal.js presentation as a build step. The config for reveal-md, which passes through to reveal.js, is stored as frontmatter in the MarkDown source file:

---
title: Slides Template
separator: <!--s-->
verticalSeparator: <!--v-->
theme: solarized
revealOptions:
    transition: 'fade'
---

This allows me to keep the source of my presentation clean, with just the relevent content, and it pulls in reveal.js for the actual presentation. I’ve set it up so that the presentation is generated into the docs folder.

GitHub Pages

So at this point, I can write a presentation in MarkDown, in an uncluttered source repoository and push it to GitHub for collaboration. GitHub has a nice feature where you can serve project or user content as web pages. So I could use GitHub Pages to serve the content from the gh-pages branch, I just had to upload the presentation generated in the docs folder to the gh-pages branch . While GitHub Pages does support generating a blog from text files using the Jekyll system, it doesn’t support running reveal-md.

Travis CI

Travis CI is a contiunuous integration build system that is able to run a build after code is checked into a source code control system. Since that is what I was doing, I configured Travis CI to run my reveal-md process when the source code of my presentation was updated, and using the Travis CI pages provider to push the generated website back to the GitHub Pages branch of my presentation repository. The .travis.yml file is straightforward, just configure the GITHUB_TOKEN environment variable in the Travis CI settings, whose value should be a personal access token generated in the GitHub Developer Settings. The build script that is being run it the generate script defined in the package.json file of the presentation repository

language: node_js
node_js: "6"

install: npm install

script: npm run generate

deploy:
  provider: pages
  skip_cleanup: true
  local_dir: docs
  github_token: $GITHUB_TOKEN
  on:
    branch: master

Presentation: Slides Template

I’ve setup a Template Presentation. The slides are written in MarkDown, in the slides.md file

---
title: Slides Template
separator: <!--s-->
verticalSeparator: <!--v-->
theme: solarized
revealOptions:
    transition: 'fade'
---
# Local

This will serve the presentation

and open a browser to view it

* clone the repo
* edit the `slides.md` file
* then:

npm install
npm run presentation


Note: This is a speaker note, you need node 6.x installed

<!--s-->

# GitHub Pages

* fork the repo
* setup a build in travis for the fork - don't forget the env var with your personal access token
* edit the `slides.md` file
* push to github
* view presentation on GitHub - in the project pages for your repo

<!--v-->

# References

* [reveal-md](https://github.com/webpro/reveal-md)
* [reveal.js](http://lab.hakim.se/reveal-js)
* [GitHub Pages](https://pages.github.com)
* [Travis CI](https://travis-ci.org)
* [This template](https://github.com/martinmurphy/slidestemplate)

To make a presentation:

  • Fork the repository
  • Enable GitHub Pages from the gh-pages branch, in the repository settings
  • Setup a build in Travis CI for the fork (with the environment variable GITHUB_TOKEN set to your personal access token from GitHub)
  • Replace the slide content and title in the slides.md file with your slides content
  • Push to GitHub
  • View presentation on GitHub in the project pages for your repo (or serve it locally)

You can view the above template slides at the generated Template Presentation site

References