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.
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
If you don’t have Hugo installed yet, install it using the instructions on gohugo.io.
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.
Let’s confirm that you can build and run this new, empty site.
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
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.
Now, let’s add the submodule.
git submodule add firstname.lastname@example.org:dzello/reveal-hugo.git themes/reveal-hugo
Next, we need to tell Hugo that we want to use this theme, as well as register
Reveal as an output format. Open the
config.toml file in your editor and add the following lines.
theme = "reveal-hugo" [outputFormats.Reveal] baseName = "index" mediaType = "text/html" isHTML = true
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.
+++ title = "Famous Programming Quotes" outputs = ["Reveal"] +++ # Famous Programming Quotes
If you aren’t already running it, run
hugo server and open a web browser to
http://localhost:1313. You should be greeted with a one-slide presentation displayed with the black Reveal.js default theme:
The content is coming from the Markdown in the
_index.md file. We have just one slide, but it’s very easy to add another. Let’s do that next.
Add the following lines to the
_index.md file, so that the total markdown section looks as follows.
# Famous Programming Quotes --- > "There are only two hard things in Computer Science: cache invalidation and naming things." -- Phil Karlton
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.
Two Ways to Add Slides
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.
+++ weight = 10 +++ > "There are only two hard things in Computer Science: cache invalidation and naming things." -- Phil Karlton
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.
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.
Importing to Forestry
Create a new Github repository called
Head back to your terminal and commit the changes we’ve made so far.
git add . git commit -m ‘Initial commit’
Next, register the new remote (substitute “dzello” for your Github username in the example below) and push up to Github.
git remote add origin email@example.com:dzello/programming-quotes.git git push -u origin master
Now, Forestry will be able to find and import your site. If you don’t already have a Forestry account, sign up for a free one.
Go to your Forestry Dashboard located at https://app.forestry.io/dashboard/. Click the “Add Site” button and a modal dialog will appear.
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.
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.
- Use reveal-hugo shortcodes like
sectionto enrich your presentations. Read the full reveal-hugo documentation to learn now.
- Create a custom Reveal.js theme that matches your company branding. To learn how and see a beautiful example, check out this tutorial and this live presentation.
Thanks for reading!
If you have any questions about or suggestions for how to improve reveal-hugo, don’t hesitate to reach out, I’m @dzello on Twitter.
Join us every Friday 📅
Frontend Friday is a weekly series where we write in-depth posts about modern web development.
Next week: We'll look at one way to use Hugo's new Theme Components feature.
Last week: We showed you the Hugo version of uBuild and discussed some strategies for using Blocks.
Have something to add?
Caught a mistake or want to contribute to the blog? Edit this page on Github!