another reveal.js plugin for Jekyll

I use Jekyll to create my course websites and reveal.js to create my lecture slides. Both of them are awesome, and allow me to focus on writing (hopefully) great content, and the formatting/presentation stuff stays out of the way until I git push the updates to the server.

There are a few ways of making these two tools (Jekyll and reveal.js) play nicely together: see here and here for example. However, most of these require you to put each slide in a new .md file, which is a pain.

What I want to do is to write one .md file per presentation, and have the sections (separated by ## headings) to determine the slide splits (this is how pandoc does it).

I wrote a simple Jekyll to make this happen—which has just a couple of moving parts

1. the revealify filter

First, put this code into a revealify.rb file in your Jekyll _plugins directory:

# (c) Ben Swift 2018, MIT Licence
# [email protected]

# a liquid filter for turning regular md output into the <section>-enclosed
# chunks required by reveal.js

require 'jekyll'
require 'nokogiri'

module Jekyll

  module Revealify

    def revealify(html)

      # parse content
      content = Nokogiri::HTML.fragment(html)

      # create an empty node
      reveal_div = Nokogiri::HTML.fragment('<div class="reveal"><div class="slides"></div></div>', 'UTF-8')
      slides_div ='.slides').first

      content.xpath("*").each do |element|

        # <section> elements should be passed through as-is
        if element.matches? "section"

          # on "split" elements (<h1>, <h2>, <hr>)
          if element.matches? "h1,h2,hr"
            current_section = slides_div.add_child("<section>").first
            # hoist all the header's attributes up to the wrapper element
            # not sure if this will always work, but here goes...
            element.keys.each do |attribute|
              # relies on the fact that the "current" wrapper node is the last child in ret
              current_section[attribute] = element[attribute]
              # element.delete attribute

          # add the element to the current <section> (i.e. the current slide)
          # unless it's just an <hr> (which are used for splitting only)
          current_section = slides_div.last_element_child
          current_section.add_child(element.dup) unless element.matches? "hr"






2. add a reveal layout

You’ll need a new layout as well: create a reveal.html file in your Jekyll _layouts directory and make sure that the body tag has this in it (you’ll need to make sure it’s got the right paths & other stuff for your setup). The key part is that first {{ content | revealify }} line—that takes the content of your page (the jekyll .md file with layout: reveal in the frontmatter) and passes it through the filter defined in the revealify filter.

The configuration stuff here is just the example config from reveal.js, so feel free to tweak to suit your own presentation.

<!-- this is where the reveailfy filter gets applied -->
{{ content | revealify }}

<!-- load the reveal.js source -->
<script src="/reveal.js-3.6.0/js/reveal.js" type="text/javascript"></script>

<!-- configure the presentation -->

   // Display presentation control arrows
   controls: true,

   // Help the user learn the controls by providing hints, for example by
   // bouncing the down arrow when they first encounter a vertical slide
   controlsTutorial: true,

   // Determines where controls appear, "edges" or "bottom-right"
   controlsLayout: 'bottom-right',

   // Visibility rule for backwards navigation arrows; "faded", "hidden"
   // or "visible"
   controlsBackArrows: 'faded',

   // Display a presentation progress bar
   progress: true,

   // Display the page number of the current slide
   slideNumber: false,

   // Push each slide change to the browser history
   history: false,

   // Enable keyboard shortcuts for navigation
   keyboard: true,

   // Enable the slide overview mode
   overview: true,


Note: I’m ommitting some details here about how to set up everything (e.g. putting the reveal.js source folder in the right place).

3. write your slides as markdown content

Finally, write your content as a regular jekyll post which uses the reveal layout, e.g.

title: "Week 1: intro"
layout: reveal

## Intro

- welcome to the course
- we're gonna learn all the things

## Timeline

- first, we'll sit in boring lectures...
- ... then, there will be a huge exam!

fun times.

Then, you get all the niceties of the jekyll watch cycle; livereload, auto-compilation of scss assets, etc.

And if you need to do something interesting with the formatting or layout of your content, then you can just drop straight into writing HTML (as you can always do in a markdown file).

4. write amazing content

This is the hard part. But at least if you’ve got a nice workflow for actually turning your content into nice looking slides then you’ve got a head start :)

Hosting a self-built jekyll site on GH pages

This blog is built from md files using Jekyll hosted on GitHub pages, which saves a lot of hassle involved with DIY hosting1. There are a bunch of useful tutorials on how to set all this up.

However, I like to have control over which plugins are used, etc. which GitHub pages doesn’t let you do. What it pages does let you do, though, is dump a bunch of files (html, js, css) in a repo and bypass the “Jekyll” step by adding a .nojekyll file. This is separate from the blog content, and so you’ll probably want a separate repo for your content (e.g. your markdown files) and the built site. Handling this stuff can be a hassle, so here’s the Makefile I use to make it easy.

The basic process is:

  1. create a git repo where you keep your jekyll site (or not, but it’s so nice to have your blog content under version control)

  2. create a separate project on GitLab called $(GH_USERNAME)/$(GH_USERNAME), but don’t create anything in there yet

  3. make init will turn the local jekyll build directory into a git repo

  4. make push target will build your site (locally) and push it up to GitHub, where it’ll be served by GitHub pages

After that, you can work on, commit & push your blog wherever you like (I actually keep the content on GitLab) but you can push the built site to GitHub so they can serve it for you.

GH_USERNAME=benswift # change this to your GH username

all: push

	mkdir -p $(BASE_HTML_DIR) && cd $(BASE_HTML_DIR) && git init . && git remote add origin [email protected]:$(GH_USERNAME)/$(GH_USERNAME)

	bundle exec jekyll build

commit-all: generate-blog
	cd $(BASE_HTML_DIR) && git add . && git commit -m "update blog"

push: commit-all
	cd $(BASE_HTML_DIR) && git push origin master
  1. I know that it’s not actually that much hassle, especially if you’ve already got a webserver set up for other reasons, but zero hassle still beats minimal hassle every time when there’s other work to be done. 

CHI hangs

Here’s a photo of Kieran and I hanging out at CHI. I’ll write a more detailed trip report some other time, but from the general chats I had with people (and random unsolicited blog posts) it seems like the ritual started some conversations.

Ben and Kieran at CHI

ANU Laptop Orchestra

One of the coolest parts of my job is doing livecoding gigs—here’s a recent set I did at Smiths as part of Soundscapes #21. A big shout-out to Ushini Attanayake (not in the video, sadly) who did a fantastic job of her first livecoding set.

Somehow I’ve managed to make that stuff part of my day job as a (cough) respectable computer science lecturer, because Laptop Orchestras (or LOrks) are a thing. Seriously, look it up on the internet. But ANU doesn’t have one—sadface. And it’s time to fix that.

  • if you’re a current ANU undergrad or coursework-postgrad student (any ANU student, not just in computer science) and you’re into

    1. music: hi-tech DJing (including livecoding, live patching e.g. Max/MSP, PD, live loop manipulation e.g. Ableton), and other instrumentalists who want to perform live with the laptop orchestra are invited too

    2. visuals: VJing, projection mapping, 2D/3D graphics e.g. shaders, Unity, etc., and other drawers/dancers/painters/glassblowers who want to perform live with the laptop orchestra are invited too

    3. organising, managing and promoting these sorts of gigs and bands so that people actually show up and have an awesome time (because even laptop orchestras need agents

  • and you want to get together with like (and unlike!)-minded folks and play some gigs for university credit, and you have 6–12 credit points (1–2 courses) of room in your ANU degree in S2 2018 and S1 2019

  • then you need to get in touch with me ([email protected]), perhaps with a link to some of your creative work, and we can try and make this happen.

I’m putting together a Laptop Orchestra (or, alternately an Algorave group) as a TechLauncher project. Don’t wait till the start of semester 2; the groups might be full up by then and you’ll miss out!

Even if you’re not sure if you’re the right person (e.g. you’re not sure how to fit it into your degree program) if you’ve always liked technology, creativity and live performance but never found the right outlet for those passions, then get in touch, there might be ways to make it happen.

Centre for the Public Awareness of Code

*What’s your favourite movie? Most folks already have an answer to this questions (because they’ve been asked before). Mine’s The Castle.

Cast of 'The Castle'

What’s your favourite band/album? Again, a pretty standard “dinner party” line of questioning. As a muso (at least in the loose sense of the word) I find this a much tougher one to answer, partially because I have so many favourites, and partially because I’m trying t

What’s your favourite scientist or scientific theory/fact? This one is harder, but thanks to great work by many gifted science communicators people increasingly have an answer to those questions.

What’s your favourite bit of (software) code? What’s your favourite algorithm? I reckon that most people will struggle to have an answer for this one. In fact, most folks probably won’t understand the question. Yet code (and the algorithms they manifest) does impact the world today. Mark Zuckerberg is still travelling around with a suit and a haircut apologising for the way his code changed the course of history. It also true that a naive “code doesn’t kill people; people kill people” techno-dualism doesn’t really stack up in practice. The modern world is a complex, socio-technical assemblage (a glorious hot mess!) and everything affects everything else.

This isn’t about setting up a dichotomy between those who “get” code and those who don’t, and it certainly isn’t about adding a moral dimension to code literacy (so that if you don’t code, you’re a bad person). There are some amazing code communicators out there—check out Dan Shiffman on the Coding Train. And there’s stuff like Critical Code Studies (CCS), although that’s more about understanding code-as-text deeply rather than raising awareness of what code is currently doing in the world.

What we need is a Centre for the Public Awareness of Code, with a bunch of folks doing for code/software/algorithms what Carl Sagan did for space science with Cosmos. I’ve got some ideas about how we could do it (musical livecoding is one of them) but I’m sure there are other ways as well.

I know that there are a lot of people (and organisations) who are working hard at this problem right now, all over the world. Which angles are they attacking the problem from? Who’s doing it best? What can we all learn from each other? Let’s discuss on twitter :)

The Other Side: Algorithm as Ritual in Artificial Intelligence

Tomorrow morning (Wed April 25, 9am Montréal time) Kieran Browne and I are performing an Artificial Intelligence divination ritual as part of the alt.chi session Scary, Sporty, Ginger and Posh.

This is not a talk about the ritual; we will be performing the ritual live at CHI, using an analog computing apparatus to communicate with an artificial intelligence to divine the answers to our questions.

The ritual will start on time at 9am in room 514B—it’s a small room, so please come a touch early to make sure you don’t miss out on a seat.

See Kieran’s blog for more details about tomorrow’s ritual, and read the paper for the full story.

Telopea Hour of Code

Welcome, Telopea Hour of Code students. Here are a couple of links you’ll need today: the p5 web editor and the slides for the presentation.

Have fun!

Science Week gig

I’m playing a livecoding set at the ACT Science Week launch party tonight. Sorry about the late notice to anyone who uses this blog to come to my gigs—I really should set up a newsletter or something. I think there are still a few tickets left ($5, available from the website linked above).

COMP1720 teaser

If you’re an ANU student and you want to learn how to make art with code, then sign up for COMP1720/6720 in semester 2, 2017. Taught by me and a bunch of internationally recognised artists (there’s a weekly computational artist guest lecture) it’s the best way to scratch the art+code itch at the ANU.

No previous programming or artistic experience is required: we’ll teach you both things from the ground up, then we’ll teach you to put them together.

Here are 5 reasons you should take COMP1720 this year (number 4 will shock you!):

  1. the course has been tweaked from last year’s version: this year we’ll make art in the browser (with javascript and the p5 library)

  2. the major project theme this year will be ANU Grand Challenges—here’s your chance to say something about the big problems facing the world

  3. if you’re doing a CS degree but find some of the programming stuff a bit difficult, here’s a secret: making art with code is how I learned to program. This course is the perfect chance to make sure those fundamentals are solid, and will teach you skills you can use in all of your CS courses (even the non-arty ones)

  4. this year we’ll be doing more sound/music stuff than ever before (because, as you’ll know if you’ve seen me perform or clicked around this site a bit, I love me some code + music)

  5. if you’re not a computer science student, but you’ve heard that computers are going to eat all of the jobs in the future and you want to get on board, then this is a perfect “intro to programming” course, and you’ll learn about how to communicate through interactive digital media

So head on down to student services and sign up. update (July 2017 edition)

Well, has been given another coat of paint. The content’s still a bit sparse, but hopefully this time it’ll be the place to go to keep up with my adventures in livecoding, research and just generally making thing with computers—and teaching others to do the same.