Harness the Power of Static Site Generators to Create Presentations

As a developer evangelist, I make a lot of presentations. Over the years, I’ve used a variety of different drag-and-drop tools to make slides including Powerpoint, Keynote and Google Docs. I’ve also used more developer-friendly frameworks like Reveal.js.

For me, Reveal.js takes the cake. Reveal.js presentations are written in HTML, CSS and JavaScript. I can store the files in git and edit, version, and deploy them with a familiar, git-based workflow. Because these presentations are HTML I can also use a static site generator (SSG) to build them and take advantage of nice SSG features like Markdown support, reusable layouts, and intuitive content organization. Just as SSGs can help you organize a web site, they can also help you organize a presentation.

Let’s take an example. One thing that I find clumsy about using Powerpoint is reordering groups of slides. I always seem to drag-and-drop to the wrong place, and hitting undo only works if I haven’t any changes after reordering. It’s not conducive to developing a new presentation where I want to try a lot of different orders and combinations to see what looks best.

With an SSG however, I can do this easily, because SSGs all have a way to order content. As I’ll show you, ordering groups of slides in a presentation is as easy as ordering blog posts by date, which in SSG-land is a trivial task—often just setting a parameter in what’s called the “front matter” of a content file. Don’t worry if you’re not sure what “front matter” is, you’ll see an example later.

There are many other advantages that the combination of Reveal.js and an SSG offer over the traditional Powerpoint method, and my goal today is to show you how to take advantage of them. I’ll walk you through how to use a theme I’ve created for Hugo called reveal-hugo which contains all of the Reveal.js boilerplate so you can start creating slides instantly.

By the end of the tutorial you’ll have created your first presentation and learned a new workflow that’ll make you the fastest slide maker in the office.

Step 1: Create a New Hugo Site

No prior knowledge of Hugo or Reveal.js is required but a basic understanding of how static site
generators work will be helpful. I recommend trying this tutorial if you haven’t created a static site before.

For fun, we will make a demo presentation that contains some famous programming quotes.

First, let’s create a new Hugo site called “quotes”. Open a terminal and type this in.

hugo new site quotes

You should see a message that says ‘Congratulations!’. Next, let’s change into the directory of the new site that was created.

cd quotes

Let’s confirm that you can build and run this new, empty site.

hugo server

If you open localhost:1313 in your browser, you should see a blank page. That’s ok. It’s because we haven’t added any content or layout files yet.

Step 2: Add the reveal-hugo Theme

With Hugo, layout files typically live in the layouts folder, but they can also come from themes. To create our demo presentation, we’ll use a theme I wrote called reveal-hugo. This theme comes with layout HTML files, JavaScript, and CSS built-in, so all you have to add is Markdown-based content.

We’re going to add the theme as a git submodule, because we want to use git to deploy code later. To do that, we first need to initialize git inside of our project directory.

Output formats are a very useful Hugo feature that allow you to build multiple representations of your content. Output formats are how, for example, you can easily build a JSON API for your static site. The “Reveal” output format builds source content into a Reveal.js presentation instead of a traditional web page.

Step 3: Create Your First Presentation

Before we will see any output, we still need to create a content file. In your terminal or your editor, create a file in the content directory called _index.md. Note the presence of the underscore. This is a special Hugo convention that allows you to add front matter to list templates. List templates are used to serve content at the top level of a section directory, including the root of the site.

In the file content/_index.md, add the following front matter and content.

Save and your HTML page should reload immediately. This is one of the benefits of Hugo, lightning-fast builds and built-in browser refreshing with Hugo server.

Look for a blue arrow in the bottom-right hand corner of the first slide. Click it, or use your right arrow key to navigate to the next slide.

This is one of the most well-known computer science quotes of all time, attributed to Phil Karlton by Tim Bray.

Two Ways to Add Slides

The --- Separator

The reason the quote above is on a different slide is the use of the --- separator in the Markdown file. Use --- surrounded by blank lines to indicate that the following content should be on a different slide. This allows you to keep presentation content from spreading over too many files, which tends to slow down the editing process.

Additional Markdown Files

Storing every slide in one file, however, would be too unwieldy for large presentations. reveal-hugo gives you another way to add slides by creating new content files in the same Hugo section, or a special section called home for the root presentation.

How would the previous example have looked if we wanted to store every quote in its own markdown file?

First, we would have created a directory called home in the content folder. Then, we would have created a file with a name that reflects the quote, maybe two-hard-things.md. In that file, we would have a TOML front-matter section delimited by the +++ lines and followed by a Markdown section.

Just like with the content in _index.md we can add as many slides as we want in this file delimited by ---.

Note the presence of the weight parameter in the front matter. weight is a Hugo concept that is used to order content in the same section, specified as an integer and sorted ascendingly. Assume that we had added several more quotes or groups of quotes in their own files - how we would determine their order in the presentation? This is what weight is for. We would give each content file its own weight parameter - 10, 20, 30, and so on.

Customizing the Reveal.js Presentation

Additional parameters like the Reveal.js theme, code highlighting theme, transition effect and speed, and plugins like speaker notes can all be configured in the front matter of your Markdown files. See Configuration in the README for the full list of what’s available.

Step 4: Add Slides With Forestry

We’ve seen how to add slides from the command line, now let’s see how we can add them visually in a browser using Forestry. This is especially useful if you have non-developer colleagues who you’d like to share this technique with.

If you don’t want to use Forestry, you can skip directly to Step 5.

Before we import our site to Forestry, we need to commit it push it up to Github, Gitlab or Bitbucket. For the purpose of this example, we’ll use Github.

Choose Hugo and then click Next. Select your git provider on the next screen and click Next. Now it’s time to choose the git repository. Type “programming-quotes” into the dropdown box and you should see the repository you just created.

Click it and another dropdown will appear for you to choose the branch. Choose master and then click Next. Invite any guests you like using the next dialog, and then click Import Site. After a few seconds, you’ll be taken to the Forestry editor for your new site.

Using the Forestry Editor

Let’s add another quote to our presentation. Click Famous Programming Quotes, which represents a page of our Hugo static site that we can edit with Forestry.

You should now see the dual-pane Forestry editor. On the left side is the data from our file’s front matter. On the right side is a stylish Markdown editor that does live formatting as you type. Click into the bottom of the right side pane, and hit Enter twice to create a newline. Then add --- and hit Enter.

You will see that Forestry has added a horizontal line automatically, which is a handy visual separator for your slides. Below the line, add the following markdown.

> “To me programming is more than an important practical art. It is also a gigantic undertaking in the foundations of knowledge.” -- Grace Hopper

In the top-right hand corner of the screen to the left of the green Save button is an eye icon. This icon lets you preview your changes by building a full copy of your site at a unique URL. It’s very handy to double-check that things look right before you cause any commits back to your git repo.

Click the eye icon to open a preview of your presentation in a new browser window. Use the blue arrow or arrow keys to navigate to and inspect your new slide. If you’ve done everything right, it should look like this.

The last thing we need to do with Forestry is commit our new slide back to our git repository. That’s easy, we can just click the Save button back in our editor. You can verify that Forestry has made the commit by looking at your git history.

Live Preview With Forestry

Here’s what the last few steps look like in one animated GIF. You can see that editing, live previewing and saving to takes just a few seconds - this GIF is not sped up :p

Step 5: Deploy Your Presentation

You can host your Hugo + Reveal.js presentation anywhere that serves up static sites. In this tutorial, we’ll use Netlify, chosen for its seamless git integration and generous free tier.

If you don’t have a Netlify account, head over and create one. From your Netlify dashboard, click the ‘New Site from git’ button. You should see this 3-step modal window appear:

Choose the git provider you used in previous steps and then choose the programming-quotes repository from the dropdown that follows. Set the build command to hugo and the publish directory to public (these are the defaults). Then click Deploy Site.

In yellow at the top of your Netlify dashboard for this new application, you’ll see a message that says ‘Site deploy in progress’. That’s a good sign. In just a few seconds that message should turn green and show you a URL you can use to access your deployed site. Click it and verify you can see your presentation.

Really, that’s all there is to it. From there you can give your Netlify a friendlier name or CNAME it from a custom domain you own. Because everything is connected via git, the next time that you publish changes to your presentation—via the command line or via Forestry—Netlify will pull your changes, rebuild your Hugo site, and deploy your new content.

Step 6: Extra Credit

If you’ve followed the full tutorial, you now have a home on the Internet for your presentations, plus a technique for authoring them quickly with hassle-free maintenance.

Here are a few more things you can do in the future:

Create more presentations in the same repository. To do that, just create new sections of your Hugo site and set their output format to [“Reveal”]. You can customize each one with different Reveal.js parameters.

Add Reveal.js presentations to an existing Hugo site. Because “Reveal” simply is an output format with reveal-hugo, it can be used to output specific sections of a Hugo site without trying to turn the rest of the site into a presentation. You might use this, for example, to host slides next to the blog post for a talk you recently gave.