reveal-hugo

reveal-hugo is a Hugo theme that converts markdown files into HTML slide decks rendered by Reveal.js, giving you a text-based workflow for building presentations.

What is reveal-hugo?

reveal-hugo is a Hugo theme for Reveal.js that takes standard markdown content and produces a complete HTML presentation. You write slides in any Hugo content file, separating them with --- surrounded by blank lines, and the theme outputs a self-contained web page that runs the Reveal.js framework. The theme is maintained by the joshed-io GitHub organization and the latest release requires Hugo v0.93.0 or newer; earlier Hugo versions must use a previous release.

The theme supports both root presentations and section presentations, so you can organize slides across multiple files under a section's _index.md or in the special home section that appends to the root deck. It also registers a custom Reveal output format that writes to index.html.

Key Features

• Single-file slide decks — Combine all slides in one markdown file, separating them with --- lines; each block becomes a slide.
• Slide shortcode — Set per-slide Reveal.js attributes like id, class, background, transition, and notes with the {{< slide >}} shortcode, without a closing tag.
• Fragment and frag shortcodes — Reveal content incrementally using {{% fragment %}} for block-level content or {{< frag c="text" >}} for inline text.
• Vertical sections — Wrap slides in {{% section %}} to create groups that navigate vertically in Reveal.js.
• MathJax integration — Author LaTeX equations in math code blocks or with the math shortcode; the theme automatically activates MathJax when these are used.
• Custom theme compilation — Point custom_theme at a CSS file or set custom_theme_compile to compile SCSS from the assets folder via Hugo pipes, with options like targetPath and enableSourceMap.
• Plugin loading — Load additional Reveal.js plugins by declaring name, source, optional css, verbatim, and order in [params.reveal_hugo.plugins]; files are resolved from static, content, or the configured CDN.
• Reusable slides — Define slides in TOML, JSON, or YAML data files and render them with the slide shortcode's content attribute, applying extra attributes to each included slide.
• Offline development — Reveal.js and highlight.js assets default to the static directory for offline work; set reveal_cdn and highlight_cdn to load from a CDN instead.

Who is it for?

• Developers and technical writers who want version-controlled, plain-text slide decks that diff cleanly and render as HTML.
• Educators and trainers preparing course materials who need math equations, speaker notes, and syntax-highlighted code.
• Hugo site owners who want to add a presentation to an existing site by adding this theme and a new output format.
• Reveal.js users who prefer writing slides in markdown rather than hand-crafting HTML sections.

What can you do with reveal-hugo?

• Build a presentation from a single file: Create content/_index.md with outputs = ["Reveal"], write slides separated by ---, and run hugo server to get a live-reloading deck.
• Create multi-section presentations: Use a section's _index.md plus additional files in that section, controlling slide order with the weight front matter parameter.
• Add speaker notes and math: Use the note shortcode or notes attribute on slides, and write LaTeX equations in math code blocks or inline.
• Reuse slides across decks: Store slides in data/ files and reference them with {{% slide content="myslides.thankyou" /%}}, with attribute overrides applied to every slide.

How does reveal-hugo work?

reveal-hugo is a standard Hugo theme added via hugo mod get or a git submodule. You register a Reveal output format in hugo.toml with baseName = "index", mediaType = "text/html", and isHTML = true. When a page sets outputs = ["Reveal"], the theme renders the markdown content into a single HTML page using Reveal.js, reading settings from [params.reveal_hugo] and converting snake_case keys like slide_number to camelCase for Reveal.initialize.

Pros and cons

• Pros: Markdown-first authoring; no frontend build step beyond Hugo; supports custom themes, plugins, and offline use; includes a starter repository and documented examples.
• Cons: The latest version requires Hugo v0.93.0 or newer; older Hugo setups need a previous release. Some advanced layouts require raw HTML sections with data-noprocess.

Pricing

reveal-hugo is free and open-source; the repository displays a license badge indicating permissive open-source licensing.

FAQ

How do I split content into slides?

Use --- with a blank line above and below it to separate blocks of markdown into slides. Each block becomes a separate slide in the presentation.

Can I add a logo to my presentation?

Yes. The logo-example demonstrates adding a logo; you can insert HTML into the head or body via partials such as layouts/partials/reveal-hugo/head.html.

How do I use Reveal.js plugins?

Define plugin entries in [params.reveal_hugo.plugins] with name and source fields. The theme loads the plugin's JavaScript and optional CSS from the static directory, content dir, or a CDN depending on configuration.

Does reveal-hugo support syntax highlighting?

It offers two modes: Hugo's compile-time highlighting via the highlight shortcode, or Reveal.js's built-in highlight.js by setting codeFences = false in hugo.toml.

Is reveal-hugo free?

Yes, it is open-source software available on GitHub under the joshed-io organization, released under a permissive open-source license.