reveal-hugo, a Hugo theme that turns content files into Reveal.js decks

What the theme does and the Hugo requirement

reveal-hugo is a Hugo theme for Reveal.js, described as making authoring and customization a breeze, with the effect that any properly formatted Hugo content becomes an HTML presentation. The theme is MIT licensed, the site is at reveal-hugo.dzello.com, and the last push was on 2026-05-19.

The requirement is stated as a warning rather than a note. The latest version of the theme requires Hugo version 0.93.0 or newer, and if you need compatibility with an earlier version you should try a previous release. That is the kind of warning that tells you the theme uses the modern Hugo template and asset system rather than the older one.

The core idea is small and specific. A presentation with multiple slides is one Markdown file, where slides are split with --- surrounded by blank lines:

+++
title = "How to say hello"
+++

# English
Hello.

---

# Français
Salut.

---

# Español
Hola.

The front matter block at the top carries the title, and the horizontal rule between the blank lines is the slide separator. That is the whole authoring model, and it is the reason the theme is worth using: a deck is content, not an artefact, so it lives in the same repository, gets the same review, and is built by the same pipeline as everything else on the site.

The other thing to note is what the theme is not. It is a theme, not a slide editor. There is no interface for arranging slides, and no tool for previewing them other than running Hugo. If you want to drag boxes around, this is not that.

The README also links a full-length blog post about harnessing static site generators to create presentations, on the Forestry.io blog, which is the background argument for why a presentation should be a build artefact at all.

Setting up a site and the two installation methods

The tutorial starts by assuming no prior knowledge of Hugo or Reveal.js, and the aim is a working presentation with instant reloading at the end.

Creating a skeleton site is the usual Hugo step:

hugo new site my-presentation

then moving into it and starting version control:

cd my-presentation
git init

The theme can be added two ways, and the README marks the first as recommended. The first turns your skeleton into a Hugo module and declares the theme as a dependency, which is the modern approach and gives you reproducible versions:

hugo mod init github.com/me/my-presentation

hugo mod get github.com/joshed-io/reveal-hugo

and then you add the theme to hugo.toml:

theme = 

The second method is a git submodule, which is the older approach and works when you want a specific commit of the theme without the module machinery.

The starter repository is the fastest way to see something working. The README points at a programming-quotes repository to clone and hack on, and separately at a blank Reveal-Hugo template maintained by someone else, a templated skeleton site to get started quickly.

The presentation site itself, reveal-hugo.dzello.com, doubles as the documentation. The README says to visit it to see a presentation created with the theme and to learn about all of the available functionality, which is a sensible arrangement: the docs are a real deck rather than a page describing a deck.

The examples and the features they cover

The exampleSite folder in the repository holds the source for the demos, and the list of demos is effectively the feature list, because each one isolates a capability.

The logo-example shows how to add a logo to a presentation. The custom-theme-example uses Hugo pipes to compile and use a custom Reveal.js SCSS theme, and the README marks this as recommended, which tells you the theme is designed to be restyled rather than used as shipped.

The section-example is the basic case of creating a presentation for a Hugo section, which is how you would keep conference talks or slide decks in their own part of a site.

The plugin-example shows adding additional Reveal.js plugins, with an image gallery given as the example. That matters because Reveal.js has a plugin ecosystem and the theme does not lock you out of it.

The template-example demonstrates the slide shortcode with what the README calls powerful templates, which is the mechanism for a repeatable slide layout rather than writing the same markup each time.

The bundle-example creates a presentation from one or more Markdown files in a leaf bundle, which is how you split a long deck into several files without it becoming one unwieldy document.

Then there are three about code. The hugo-hl-example uses Hugo's compile-time syntax highlighter, so the highlighting happens when the site is built rather than in the browser. The highlightjs-linenumbers-example uses the multiline and multi-step capabilities of highlight.js, which is the way to show a snippet appearing line by line across successive slides. And the docs mention the documentation site and the release history.

Taken together, the examples show a theme that expects to be extended: custom themes through the asset pipeline, Reveal.js plugins, a shortcode for slide templates, and two different syntax highlighting strategies, one at build time and one in the browser. The choice between them is the interesting one, because build-time highlighting means the code is styled in the HTML and needs no JavaScript, while highlight.js means the styles are applied at runtime.

The CI story is CircleCI for the tests and Netlify for the deploys, with a live site status badge, so the example site is rebuilt on every push and the demos are always current.

How this compares with the alternatives

The alternatives split into two categories, and the difference is about where the slides live.

The first category is a dedicated slides tool: Marp, Slidev, reveal.js on its own, or a hosted service such as Google Slides or Canva. These give you a live preview, an editor, and sometimes collaboration. What they do not give you is a deck that is versioned with the rest of your documentation and built by your site pipeline, which is the thing a Hugo user usually wants.

The second category is building the deck by hand with reveal.js and writing the HTML or Markdown yourself. That gives full control and no theme to fight with, at the cost of reimplementing the slide splitting, the fragment support, the speaker view and the print-to-PDF handling that reveal.js already does well.

reveal-hugo sits between them. It takes the content authoring model of Hugo, which many people already know, and outputs a reveal.js presentation, which handles the presentation mechanics.

The specific advantages are worth naming. A deck that is a content file can be written by someone who does not know HTML, since the slide separator is a horizontal rule. A deck in the site repository gets the site's styling, so a change to the design system reaches the slides. And the deck is a build artefact, so it is searchable, diffable and reviewable, which a binary export from a slides tool is not.

The costs are the mirror image. There is no live editor, so iterating on a deck means editing a file and reloading the browser, and the theme has opinions about structure that you will occasionally fight. The theme's own flexibility is a mitigation, since the custom theme example shows how to restyle it through Hugo pipes, but that is work.

The version requirement is the practical thing to check first. A theme that needs Hugo 0.93 or newer means your site has to be on a reasonably current Hugo, and the README is explicit that older versions need an older release of the theme, which is a maintenance fork you probably do not want.

Editorial conclusion

Adopt reveal-hugo if you already publish with Hugo and want a presentation that is versioned alongside the site rather than a separate file in a slides tool. Skip it if your slides live in a dedicated tool with its own collaboration features, since this is a build-time theme rather than an editor. Verify first by running the logo example locally, then by attempting a custom theme through Hugo pipes, because that path is the one the README recommends and the one most likely to need work.

Frequently asked questions

Official sources

1. Issues
2. joshed-io/reveal-hugo on GitHub
3. License: MIT
4. Project website
5. README