📽️

reveal-hugo

A Hugo theme for creating Reveal.js presentations.

~ made by @dzello ~

What’s included?

All Reveal.js HTML, CSS and JS (v4.4.0)
All out-of-the-box Reveal.js themes
Two custom Reveal.js themes (including this one)

see the code on github

Features

Write slides in Markdown in one or more files
Shortcodes for fragments, sections, slides & more
All Reveal.js parameters can be customized
Any Hugo section can be output as a presentation
Supports math code blocks
Supports mermaid code blocks
Supports offline development or using a CDN

Usage

Prerequisite

First, add this to your config.toml:

[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true

Presentation at site root

Create content/_index.md:

+++
outputs = ["Reveal"]
+++

# Slide 1

Hello world!

Add slides

Separate them by --- surrounded by blank lines:

# Slide 1

Hello world!

---

# Slide 2

Hello program!

Cool equations

For equations, you can use a math code block:

```math
\tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0
```

renders to:

$$ \tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0 $$

Inline equations (e. g. $E=mc^2$) are wrapped in single $:

Albert Einstein's famous formula: $E=mc^2$

💡 Note: When using inline math only (no math code block present), you have to set math=true in the frontmatter of your slide page.

💡 Note: for code blocks support (```math ...```), hugo highlighting must be on (codeFences = true in config.toml). If you want to set codeFences = false, use the math shortcode.

Mermaid

Slides can contain mermaid diagrams:

```mermaid
graph LR
    A --> B
    B --> C
```

Or (see mermaid shortcode)

{{< mermaid >}}
graph LR
    A --> B
    B --> C
{{< /mermaid >}}

results in:

graph LR A --> B B --> C

💡 Note: for code blocks support (```mermaid ...```), hugo highlighting must be on (codeFences = true in config.toml)

Add slides with other files

Add slides to content/home/*.md

+++
weight = 10
+++

# Slide 3

---

# Slide 4

💡 Tip: Use weight to specify the order that files should be considered.

Presentation at ‘/{section}/’

Add slides to content/{section}/_index.md:

+++
outputs = ["Reveal"]
+++

# Slide 1

---

# Slide 2

Add slides from other files in content/{section}/*.md

+++
weight = 10
+++

# Slide 3

---

# Slide 4

💡 Tip: Use weight to specify the order that files should be considered.

Configuration

Place configuration values in config.toml or a presentation’s front matter (_index.md).

Reveal.js themes

Themes control the look and feel of your presentation. Set the theme param to any valid Reveal.js theme.

[params.reveal_hugo]
theme = "moon"

Use a custom theme

To use a custom Reveal.js theme, place the CSS file in the static directory and set the custom_theme param.

[params.reveal_hugo]
custom_theme = "reveal-hugo/themes/robot-lung.css"

Use a custom theme (advanced)

To use Hugo pipes to build a custom Reveal.js theme, place the source file (SCSS / PostCSS) in the assets directory and set the custom_theme_compile param.

[params.reveal_hugo]
custom_theme = "reveal-hugo/themes/custom-theme.scss"
custom_theme_compile = true

💡 See the custom theme example presentation for more details.

Bundled themes

reveal-hugo comes with 2 extra Reveal.js themes:

robot-lung (this one)
sunblind

They live in the static/reveal-hugo/themes folder and also on Github.

Reveal.js params

Set snakecase versions of Reveal.js params, which will be camelized and passed to Reveal.initialize.

[params.reveal_hugo]
history = true
slide_number = true
transition = 'zoom'
transition_speed = 'fast'

Full list of params

highlight.js themes

To change the syntax highlighting theme, set the highlight_theme to a valid highlight.js theme name.

[params.reveal_hugo]
highlight_theme = "zenburn"

Extending the layout

Use partials to add HTML to the page for one or all presentations at a time.

💡 This is the recommended way to add script and style tags to customize your presentations.

Here is where to put partials for different presentations and places in the DOM.

Presentation	Before </head>	Before </body>
All	reveal-hugo/head.html	reveal-hugo/body.html
Root	home/reveal-hugo/head.html	home/reveal-hugo/body.html
Section	{section}/reveal-hugo/head.html	{section}/reveal-hugo/body.html

💡 You can also create an end.html to put content before the end of the .reveal div tag.

Custom CSS Example

In home/reveal-hugo/head.html:

<style>
.reveal section h1 {
  color: blue;
}
</style>

Custom JS Example

In home/reveal-hugo/body.html:

<script type="text/javascript">
Reveal.on('slidechanged', function(event) {
  console.log("🎞️ Slide is now " + event.indexh);
});
</script>

Extending the layout

(alternative)

You can declare a custom CSS or javascript in your configuration.

[reveal_hugo]
custom_css = "css/custom.css"
custom_js = "js/custom.js"

These files can be located in static/css, static/js folder

💡 See the extending layout example for more details.

Shortcodes

Hugo’s shortcodes are similar to functions or templates that extend what you can do with Markdown.

Shortcode documentation

Fragment

The fragment shortcode makes content appear incrementally.

{{% fragment %}} One {{% /fragment %}}
{{% fragment %}} Two {{% /fragment %}}
{{% fragment %}} Three {{% /fragment %}}

One Two Three

Frag

The frag shortcode is more terse than fragment. It accepts a c attribute.

{{< frag c="One" >}}
{{< frag c="Two" >}}
{{< frag c="Three" >}}

One Two Three

Both fragment and frag accept two additional parameters:

class: sets the class of the wrapping span element
index: controls the order in which sections will appear

Mathematical equations

Use the math shortcode if you need to enable reveal-js highlighting module (codeFences = false).

{{< math >}}
\tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0
{{< /math >}}

displays as:

$$ \tag*{(1)} \lim\limits_{x \to \infty} \exp(-x) = 0 $$

For inline equations, use a self closed math shortcode:

Albert Einstein's famous formula: {{< math "E=mc^2" />}}

is rendered to:

Albert Einstein’s famous formula: $E=mc^2$

Mermaid diagrams

Use the mermaid shortcode if you need to enable reveal-js highlighting module (codeFences = false). Otherwise, when codeFences = true, ```mermaid ``` codeblocks are also supported. More info.

{{< mermaid >}}
graph LR
    A --> B
    B --> C
{{< /mermaid >}}

results in:

graph LR A --> B B --> C

Section

The section shortcode groups slides into a vertical display.

use the down arrow or swipe down to continue
🔽

Put the shortcode around the slides you want to group together.

{{% section %}}

## Section slide 1

---

## Section slide 2

{{% /section %}}

Keep going down.

That’s it!

Use the right arrow or swipe right to continue.

Slide

Use this shortcode when you need to customize slide attributes like id, class, background color and transition.

Slide

Add the shortcode above the slide’s content, below the ---.

---

{{< slide class="hello" >}}

## Hello, world!

---

Custom slide 1

Did you notice? This slide has a fast zoom transition.

---

{{< slide transition="zoom" transition-speed="fast" >}}

## Custom slide 1

---

Custom slide 2

This slide has a different background color.

---

{{< slide background-color="#FF4081" >}}

## Custom slide 2

---

Custom slide 3

This slide has a background image.

---

{{< slide background-image="/images/alex-litvin-790876-unsplash.jpg" >}}

---

(credit Alex Litvin)

💡 Tip: Setting a slide’s id attribute makes it easy to link to from other parts of the presentation.

---

{{< slide id="custom-slide" >}}

## Custom slide

---

[Try the link](#custom-slide)

Try the link

Slide attribute possibilities from the Reveal.js docs:

autoslide
state
background
background-color
background-image
background-size
background-position
background-repeat

background-video
background-video-loop
background-video-muted
background-interactive
background-iframe
background-transition
transition (can have different in and out transitions)
transition-speed
notes (can also use the note shortcode)
timing

Slide templates

Store sets of common slide attributes in front matter variables and apply them to slides with the template attribute.

navigate down to learn more
🔽

Create templates in config.toml, _index.md or the current page’s front matter. Put them under the templates key with a meaningful name:

[reveal_hugo.templates.hotpink]
class = "hotpink"
background = "#FF4081"

Apply the template using the template attribute of the slide shortcode:

{{< slide template="hotpink" >}}

# I'm a hot pink slide!

If a template exists in multiple configurations, it’s properties will be merged. If a property is declared multiple times, the order of precedence is:

page
section (_index.md)
site (config.toml)

Slide-specific CSS

Add more variety to your presentation by applying slide-specific CSS.

navigate down to learn more
🔽

First, use the slide shortcode to give the slide a class:

---

{{< slide class="side-by-side" >}}

# 📈

# 📊

---

Next, use a layout extension partial like reveal-hugo/head.html to add CSS selectors:

<style>
.reveal section.side-by-side h1 {
  position: absolute;
}
.reveal section.side-by-side h1:first-of-type {
  left: 25%;
}
.reveal section.side-by-side h1:nth-of-type(2) {
  right: 25%;
}
</style>

📈

📊

Notes

Add speaker notes (with markdown) to your presentation with the note shortcode. Type ’s’ to see this slide’s speaker notes.

---

{{% note %}}
- You found the **speaker notes**!
{{% /note %}}

---

Notes

You can also add notes with the slide shortcode and notes attribute:

---

{{% slide notes="You found the notes!" %}}

---

Write slides in HTML

Use a section tag with a data-noprocess attribute to avoid any processing by reveal-hugo.

<section data-noprocess>
  <h1>Hello world!</h1>
</section>

💡 This is useful if you can't get Markdown to output exactly what you want.

Resources

Code and docs

External resources

Designed to…

Deploy to Netlify
Edit with Forestry

🙏

Contribute by opening issues and pull requests.

Thanks!

↩️

Start over

If more markdown files are present in the bundle, their contents will be added to the presentation.

Specify weight in the frontmatter if it’s necessary to order them.

If you don’t want them to be included, specify layout = "list" in the front matter instead of layout = "bundle".

THE END

Page Bundles

Hugo page bundles are a useful way to organize content.

To create a reveal-hugo presentation from the index.md file of a leaf page bundle, you need to specify the layout manually.

layout = "bundle"

Why? By default, reveal-hugo doesn’t create pages for single template types (foo.md), only for list template types (_index.md).

This technique can also be used to output an HTML file for any section of a presentation, should you need to.