A Hugo theme for [Reveal.js](https://revealjs.com/) that makes authoring and customization a breeze. With it, you can turn any properly-formatted Hugo content into a HTML presentation.
Visit [reveal-hugo.dzello.com](https://reveal-hugo.dzello.com/) to see a presentation created with this theme and learn more about what you can do. Jump to the [exampleSite](exampleSite) folder in this repository to see the source code for that presentation.
If you're looking for a very simple reveal-hugo app you can use as a boilerplate, see the [programming-quotes](https://github.com/dzello/programming-quotes) repository.
For a full-length blog post about reveal-hugo, checkout [Harness the Power of Static Site Generators to Create Presentations](https://forestry.io/blog/harness-the-power-of-static-to-create-presentations/) on the [Forestry.io blog](https://forestry.io/blog).
You should be able to complete this section with no prior knowledge of Hugo or Reveal.js. At the end, you'll have a working presentation with instant reloading.
To add more slides, just add content to `_index.md` or create new markdown files in `content/home`. Remember that each slide must be separated by `---` with blank lines above and below.
The Usage guide is contained in the example presentation that lives in this repository in the [exampleSite](./exampleSite) directory. You can access a live version at [reveal-hugo.dzello.com](https://reveal-hugo.dzello.com/).
This will create two presentations, one at `/` and one at `/ted-talk/`. The order that slides are appended to each can be controlled by the `weight` parameter specified in each file's front matter. The slides in `_index.md` will always come first, though you don't have to put any slides in there if you want to.
### Shortcodes
reveal-hugo comes with a variety of shortcodes that help you take advantage of some very useful Reveal.js features.
#### fragment shortcode
Wrap any content in the fragment shortcode and it will appear incrementally. Great for bulleted lists where you want one bullet point at a a time to appear.
```markdown
- {{% fragment %}}One{{% /fragment %}}
- {{% fragment %}}Two{{% /fragment %}}
- {{% fragment %}}Three{{% /fragment %}}
```
#### frag shortcode
Like fragment but more terse - content is placed inline in a self-closing shortcode.
The slide shortcode lets you set custom Reveal.js attributes for each slide - things like id, transition, background and [much more](https://github.com/hakimel/reveal.js/#slide-attributes). The names are the same as Reveal.js but without the 'data-' prefix.
To create groups of slides that can be navigated vertically, surround your markdown with the section shortcode.
```markdown
{{% section %}}
# Vertical slide 1
---
# Vertical slide 2
{{% /section %}}
```
#### note shortcode
Add [speaker notes](https://github.com/hakimel/reveal.js/#speaker-notes) for each slide with the note shortcode.
```markdown
{{% note %}}
Don't forget to thank the audience.
{{% /note %}}
```
*💡 Tip: you can also add notes by adding a `note` attribute to the slide shortcode.*
#### markdown shortcode
Markdown surrounded by the markdown shortcode will not be rendered by Hugo but by Reveal.js itself. This is useful if you want to use some native Reveal.js markdown syntax that isn't supported by reveal-hugo.
```markdown
{{% markdown %}}
# I'm rendered...
...by Reveal.js
{{% /markdown %}}
```
### HTML slides
If you need to create fancier HTML for a slide than you can do with markdown, just add `data-noprocess` to the <section> element.
```html
<sectiondata-noprocess>
<h1>Hello, world!</h1>
</section>
```
### Reusable slides and sections
Sometimes you need to reuse a slide in the same presentation or across different presentations. reveal-hugo makes use of Hugo data templates to make both cases easy.
To create reusable slides, create a TOML (or JSON or YAML) file in your site's data directory. Give it a name that reflects its content or just `slides.toml`. In that file, add a key for each reusable slide. The name should reflect the slide's content and the value should be the slide's markdown.
```toml
thankyou = '''
# Thank you!
Any questions?
'''
```
*💡 Tip: TOML's multiline string syntax comes in handy here, note the '''.*
Each key can contain **one or more** slides separated by `---` and newlines. That way you can create reusable sections.
```toml
thankyou = '''
# Thank you!
---
Any questions?
'''
```
To render a slide from a data template, use the slide shortcode with a content attribute:
```markdown
{{% slide content="slides.thankyou" /%}}
```
The part before the "." is the name of the file in the data directory. The part after the dot is the key to look up in that file.
You can use all the additional slide shortcode attributes. They will be applied to every slide in the data template.
Include any other attributes in `params.reveal_hugo` that you'd like to be fed as arguments to `Reveal.initialize` in **snakecase**. So `slideNumber` becomes `slide_number`. The reason is that Hugo lowercases all params and Reveal.js is case-sensitive. Params are converted from snakecase to camelcase before passing to Reveal.js.
See the [extensive list of Reveal.js configuration options](https://github.com/hakimel/reveal.js/#configuration) here. The defaults used by this theme are located in `data/reveal_hugo.toml`.
If you need to add something to the HTML page, just override one or both of the empty partials that live at `layouts/partials/reveal-hugo/body.html` and `layouts/partials/reveal-hugo/head.html`. These partials are injected into the page just before the closing of the body and head tags respectively. Common uses would be to add custom CSS or JavaScript to your presentation.
If your Hugo site already has a theme but you'd like to create a presentation from some of its content, that's very easy. First, manually copy a few files out of this theme into a few of your site's directories:
Files and directories are named such that they shouldn't conflict with your existing content. Of course, you should double check before copying, especially the shortcodes which can't be put under a directory.
Now you can add `outputs = ["Reveal"]` to the front matter of any section's `_index.md` file and that section's content will be combined into a presentation and written to `index.html`. If you already have a `index.html` page for that section, just change the `baseName` above to `reveal` and the presentation will be placed in a `reveal.html` file instead.
Note: If you specify `outputs = ["Reveal"]` for a single content file, you can prevent anything being generated for that file. This is handy if you other default layouts that would have created a regular HTML file from it. Only the list file is required for the presentation.
