A Hugo theme for creating Reveal.js presentations.
~ made by @dzello ~
First, add this to your config.toml
:
[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true
Create content/_index.md
:
+++
outputs = ["Reveal"]
+++
# Slide 1
Hello world!
Separate them by ---
surrounded by blank lines:
# Slide 1
Hello world!
---
# Slide 2
Hello program!
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.
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:
đĄ Note: for code blocks support (```mermaid ...```
), hugo highlighting must be on (codeFences = true in config.toml)
Add slides to content/home/*.md
+++
weight = 10
+++
# Slide 3
---
# Slide 4
đĄ Tip: Use weight
to specify the order that files should be considered.
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.
Place configuration values in config.toml
or a presentation’s front matter (_index.md
).
Themes control the look and feel of your presentation. Set the theme
param to any valid Reveal.js theme.
[params.reveal_hugo]
theme = "moon"
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"
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.
reveal-hugo comes with 2 extra Reveal.js themes:
They live in the static/reveal-hugo/themes
folder and also on Github.
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'
To change the syntax highlighting theme, set the highlight_theme
to a valid highlight.js theme name.
[params.reveal_hugo]
highlight_theme = "zenburn"
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.
In home/reveal-hugo/head.html
:
<style>
.reveal section h1 {
color: blue;
}
</style>
In home/reveal-hugo/body.html
:
<script type="text/javascript">
Reveal.on('slidechanged', function(event) {
console.log("đī¸ Slide is now " + event.indexh);
});
</script>
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.
Hugo’s shortcodes are similar to functions or templates that extend what you can do with Markdown.
The fragment
shortcode makes content appear incrementally.
{{% fragment %}} One {{% /fragment %}}
{{% fragment %}} Two {{% /fragment %}}
{{% fragment %}} Three {{% /fragment %}}
One Two Three
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
elementindex
: controls the order in which sections will appearUse 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$
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:
The section
shortcode groups slides into a vertical display.
Put the shortcode around the slides you want to group together.
{{% section %}}
## Section slide 1
---
## Section slide 2
{{% /section %}}
Keep going down.
Use the right arrow or swipe right to continue.
Use this shortcode when you need to customize slide attributes like id, class, background color and transition.
Add the shortcode above the slide’s content, below the ---
.
---
{{< slide class="hello" >}}
## Hello, world!
---
Did you notice? This slide has a fast zoom transition.
---
{{< slide transition="zoom" transition-speed="fast" >}}
## Custom slide 1
---
This slide has a different background color.
---
{{< slide background-color="#FF4081" >}}
## Custom slide 2
---
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)
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
Store sets of common slide attributes in front matter variables and apply them to slides with the template attribute.
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:
Store markdown in a data template and reuse it in multiple sections or presentations.
Add a example
key to data/home.toml:
example = "I'm a slide"
Set the content
attribute to “home.example”:
{{< slide content="home.example" >}}
đĄ Each data template entry can contain one or more slides, separated by ---
with newlines.
đĄ All other slide shortcode attributes (background, transition, etc.) can be used and will be applied to each slide in the data template entry.
đĄ Adding a new file in data
folder requires to restart hugo
đĄ Symbolic links are not allowed in data
folder
You can organize reusables into folder.
An an example
key in data/common/nested.toml
example = "I'm a slide"
Set the content
attribute to “common.nested.example”:
{{< slide content="common.nested.example" >}}
Add more variety to your presentation by applying slide-specific CSS.
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>
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 %}}
---
You can also add notes with the slide
shortcode and notes
attribute:
---
{{% slide notes="You found the notes!" %}}
---
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.
Contribute by opening issues and pull requests.