reveal-hugo

reveal-hugo is a Hugo theme that converts markdown content into HTML slide presentations built with Reveal.js, giving static-site users a Git-friendly way to author and publish decks. Developed by joshed-io, the theme registers a custom output format and lets you create multiple slides from a single markdown file by separating them with --- on blank lines.

What is reveal-hugo?

reveal-hugo is a Hugo theme for Reveal.js that takes Hugo content files (markdown with front matter) as input and produces a fully client-side HTML presentation as output. It requires Hugo v0.93.0 or newer for the current release, and supports installation either as a Hugo module or as a traditional git submodule. The theme is authored and maintained by joshed-io, and its live documentation and demo site is reveal-hugo.dzello.com.

What makes reveal-hugo stand out?

• Markdown-to-slides workflow — Write an entire presentation in one markdown file, with each slide separated by --- surrounded by blank lines; the first slide goes in _index.md and additional markdown files in the same section append slides in order.
• Slide shortcode with Reveal.js attributes — Set id, class, background, transition, transition-speed, and many other per-slide attributes by adding the slide shortcode above the slide content; a data- prefix is added automatically where needed.
• Reusable slides via data templates — Define slides in TOML, JSON, or YAML files under the data directory and render them anywhere with the slide shortcode's content attribute, e.g. {{% slide content="slides.thankyou" /%}}.
• MathJax equation rendering — Use a math code block, the math shortcode, or inline $...$ syntax; the MathJax scripts activate automatically when a math block or shortcode appears.
• Custom theme compilation with Hugo pipes — Turn on custom_theme_compile to build a SCSS/PostCSS Reveal.js theme from the assets folder, letting you override color variables like $backgroundColor directly.
• Additional Reveal.js plugin loading — Register plugins through [[params.reveal_hugo.plugins]] entries in hugo.toml or front matter, specifying name, source, and optional css files so the theme loads their JavaScript and stylesheets.
• Offline-friendly by default — Reveal.js and highlight.js are served from the site's static folder out of the box, while reveal_cdn and highlight_cdn let you switch to a CDN when preferred.

Who should use reveal-hugo?

• Technical presenters and conference speakers who want to maintain slide decks in markdown and track changes with Git.
• Hugo site owners who need to embed a presentation into an existing website without adopting a separate toolchain.
• Educators and technical trainers who benefit from speaker notes (press s), code syntax highlighting, and MathJax formulas in their teaching materials.
• Teams that reuse slide content across multiple decks, since data templates allow the same slide or section to be included in different presentations.

What can you do with reveal-hugo?

• Create a full presentation from a single file: Put slides in content/_index.md, add outputs = ["Reveal"], and run hugo server to get a live-reloading deck at localhost:1313.
• Build an internal training site: Use a section like content/ted-talk/ with its own _index.md to generate a standalone presentation accessible at a sub-path.
• Add math-heavy slides: Write equations with \tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k} inside a math code block for a compiled presentation.
• Reuse a slide element across decks: Store slides in data/slides.toml and render them on multiple pages with {{% slide content="slides.thankyou" /%}}.

How does reveal-hugo work?

After creating a Hugo site, install the theme either as a Hugo module (hugo mod get github.com/joshed-io/reveal-hugo) or a git submodule, then add the Reveal output format and set theme in hugo.toml. Create content/_index.md with outputs = ["Reveal"] and write slides separated by ---. Finally run hugo server; the presentation is generated as index.html in the root or section folder.

Pros and cons

• Pro — Markdown-based authoring: Presentations are written in markdown and built with Hugo, making them easy to review and version-control.
• Pro — Reusable slides: Data templates let you share slides across different presentations.
• Con — Version requirement: Current release needs Hugo v0.93.0 or newer; older Hugo users must use a previous release.
• Con — Legacy setup steps: For Hugo versions below v0.42, you have to copy layouts and static from the theme into your site.

FAQ

What Hugo version is required for reveal-hugo?

The latest version of the theme requires Hugo v0.93.0 or newer. If you're using an earlier Hugo version, you can use a previous release of the theme for compatibility.

How do I create a new slide in reveal-hugo?

Separate slides in your markdown by placing a line containing only --- with blank lines above and below it. Each segment becomes a slide in the presentation, and multiple markdown files in the same section append their slides to the section's deck.

Can I present with speaker notes using reveal-hugo?

Yes. Add a note shortcode with your note text, or use the notes attribute on the slide shortcode. During the presentation, press s to open a separate speaker window that shows the notes and a timer.

Does reveal-hugo work without an internet connection?

Yes, by default the theme loads Reveal.js and highlight.js from your site's static directory. To use a CDN instead, set reveal_hugo.reveal_cdn and reveal_hugo.highlight_cdn in your configuration.

Can I use MathJax equations in my slides?

Yes, you can write equations in a math code block, use the math shortcode, or wrap inline math in $...$. The theme activates the required MathJax scripts automatically when a math code block or shortcode is present.