Coders, here's a JavaScript presentation tool you'll love

One of my tasks at my job is to develop and maintain technical presentations. In the past I’ve stored these presentations on Google Drive in Apple’s Keynote format. Keynote, like many office suite applications, stores its files as big, fat binary blobs. When multiple people modify a presentation and attempt to update it, you get problems. People silently clobber each other’s changes.

This annoyance isn’t unique to Keynote. PowerPoint and other formats suffer the same problem. While PowerPoint theoretically has an XML-based file, it’s wrapped in a Zip, so there’s no practical way to merge changes at the file level.

Another problem with Keynote is that while there are slide masters, the stuff that gets pasted into a slide has to be carefully formatted. WYSIWIG is great and awful at the same time. Stuff that gets pasted into a slide has to be formatted with love. This usually means that while the master is consistent, the contents often diverge in format: spacing is a little off, font choices go off-brand, and colors go wild.

In an ideal world, you’d store presentations on GitHub exactly like code and write presentations in a simplified format like Markdown without having to know the style. The UI/brand guy or gal could do all the “pretty stuff” up front in CSS while you wax philosophic in your bulleted prose.

That’s exactly what the open source, in-browser slideshow tool Remark.js lets you do. 

Remark-able technical presentations

With Remark.js, you have one HTML file and however many CSS files, but your presentation is separate in a flavor of Markdown. You can store everything on GitHub. There’s even a presenter mode to allow you to see your notes while your audience looks on at your brilliant visuals.

As the name might suggest, Remark.js is a JavaScript library. Like any JavaScript library there are like 50 alternative implementations. The most impressive to me visually is Reveal.js.

While Remark.js lets you write entirely in Markdown with sprinkles of HTML or extensions, Reveal.js makes you actually learn HTML. I’ve been saying that I know HTML on my resume since the ‘90s, but it’s exactly like I know how to use a paintbrush: I make ugly things with both. That’s why I prefer using Remark.js.

Here’s the Markdown and slide text for an actual slide from one of my presentations:

—-
class: left, top

# Fusion Concepts: Collection

* Contains documents
* Associated with actual indexed data and schema
* Associated with a named configuration in Zookeeper
* Logical index that can be spread across multiple servers
* Routing strategy that defines how documents get assigned to shards replica placement strategy that defines how many copies to keep of each document in the collections
* A collection as it exists on an instance of Solr is called a “Core”

???
Script: In short a collection is a logical index that is tied to a whole lot of configuration and process management in the cluster, including how it is configured, replicated, and routed.
—-

Here is what that looks like on my phone (which I can Chromecast by the way):

Andrew C. Oliver

Here is presenter mode! I can set my slides up, so I can read my screen like a teleprompter (I don’t actually because it would bore me to do so):

Andrew C. Oliver

When you clone a presentation, the browser windows are synced even if you enter presenter mode on one. Your audience sees the view in the first screenshot. You see the view in the second.

The bad stuff

Remark.js is far from perfect. It’s great for technical people doing technical presentations, but I wouldn’t subject the sales team to it. If you have a GitHub account, you’re probably more comfortable with Markdown than PowerPoint or Keynote’s fickle WYSIWYG editor. If you read your email willingly in Outlook, you probably won’t like it.

To use this, you need a local web server like Python SimpleHTTPServer. I also recommend going with Chrome. Firefox got out of sync if I clicked around. The Presenter view is helpful, but there’s no thumbnail view for people who go back and forth between slides a lot.

If you organize your presentations as separate files, you have to reclone and re-enter presentation mode for each one. Images and title slides may require CSS tweaking to get right. Any code you don’t escape with ``` backtics will get mangled (especially regex). You also have to tweak the CSS to make print to PDF line up right.

Once you have the hang of it and get your CSS done, the comparative effort to create “one more” presentation in Remark.J’s/Markdown is lower than that of PowerPoint or Keynote. Managing versions in GitHub is monumentally better, and knowing I can present from my phone or tablet makes me happy. The next time you put on a conference and realize your materials all reverted to previous versions, maybe think of Remark.js.