#eSolia's Presentation Site

eSolia is publishing presentation slides at show.esolia.pro, the repo for which is this site. The site is assembled with the very fast static site generator Hugo, and works to turn Markdown files into HTML presentations because of the Reveal.js javascript library.

Many thanks and kudos go to:

• Josh Dzielak for the "reveal hugo" theme, which lets us smoothly integrate Hugo and Reveal.js. In fact you can see their extensive demo here.
• Drew Devault for the "sr.ht" service, which this repo is hosted in, and which gives us the capability to continually build and deploy to our web server, for each commit.

#Basic Example

Using reveal-hugo, presentations with multiple slides can be created with just one markdown file, by putting a --- between slides, like so:

+++
title = "How to say hello"
+++

# English
Hello.

---

# 日本語
こんにちは。

#Setup

The "reveal hugo" theme is meant to be plugged in to a Hugo site in the usual way for installing themes. In this case, I incorporated it by copying its files directly into the usual places Hugo expects - layouts, data, static.

• Added Tachyons.io css library into layouts/_default/baseof.reveal.html.
• To add a presentation, it's probably easiest to duplicate content/12-factor-app-and-engineer to another folder and edit its files.
  • _index.md - the main file that gets loaded and makes settings.
  • whatever1.md and whatever2.md - get loaded after what's in _index.md by their "weight".
• Access each presentation by simply plugging in its folder, i.e. https://show.esolia.pro/12-factor-app-and-engineer.
• If HTML customizations need to be done per presentation, they can be done by copying layouts/partials/reveal-hugo into a folder with the same name as that of the presentation under content. If the presentation is in esolia_intro_2018, then copy into layouts/partials/esolia_intro_2018/reveal-hugo.
• Reusable slides can be placed in data and accessed as a slide via a shortcode. Given data/slides.toml, you would access a key called "arigato" in your slide, via the "slide" shortcode, as {{% slide content="slides.arigato" %}}. That creates a slide where you specify, by copying the info in the data file.

#Hugo Shortcodes

The reveal-hugo theme comes with a variety of Hugo shortcodes that you use in your presentation's markdown files to take advantage of Reveal.js features. The following info is from the theme's readme:

#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.

- {{% 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.

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

#slide shortcode

The slide shortcode lets you set custom HTML and Reveal.js attributes for each slide - things like id, class, transition, background just to name a few. The names are the same as Reveal.js but without the 'data-' prefix.

Add the shortcode above the slide content, below the --- separator. Do not place content inside of the shortcode.

---

{{< slide id="hello" background="#FFF" transition="zoom" transition-speed="fast" >}}

# Hello, world!

---

Here's a list of documented slide attributes 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

You can also pass through your own, a data- prefix will be added automatically to each one (except for id and class).

#section shortcode

To create groups of slides that can be navigated vertically, surround your markdown with the section shortcode.

{{% section %}}

# Vertical slide 1

---

# Vertical slide 2

{{% /section %}}

#note shortcode

Add speaker notes for each slide with the note shortcode.

{{% 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 %}}
# 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.

<section data-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.

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.

thankyou = '''

# Thank you!

---

Any questions?

'''

To render a slide from a data template, use the slide shortcode with a content attribute:

{{% 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.

#Configuration

Customize the Reveal.js presentation by setting these values in config.toml or the front matter of any presentation's _index.md file.

• reveal_hugo.theme: The Reveal.js theme used; defaults to "black"
• reveal_hugo.custom_theme: The path to a locally hosted Reveal.js theme in the static folder
• reveal_hugo.highlight_theme: The highlight.js theme used; defaults to "default"
• reveal_hugo.reveal_cdn: The location to load Reveal.js files from; defaults to the reveal-js folder in the static directory to support offline development. To load from a CDN instead, set this value to https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 or whatever CDN you prefer.
• reveal_hugo.highlight_cdn: The location to load highlight.js files from; defaults to https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0. For local development, change this to point to a file in the static directory.

This is how parameters will look in your config.toml:

[params.reveal_hugo]
theme = "moon"

Or in the front matter of an _index.md file:

[reveal_hugo]
theme = "moon"

Include any other attributes in those sections that you'd like to be fed as arguments to Reveal.initialize in snakecase, so slide_number instead of slideNumber. Params are converted from snakecase to camelcase before passing to Reveal.js. This is necessary to maintain the proper case of the parameters.

Here's an example of configuring Reveal.js parameters alongside a theme and highlight.js theme:

[reveal_hugo]
theme = "moon"
highlight_theme = "solarized-dark"
slide_number = true
transition = "zoom"

See the extensive list of Reveal.js configuration options here.

#Custom Reveal.js Themes

If you have a custom reveal theme to use (in .css form), place it somewhere in your static folder. For example, if you have:

- static
  - assets
    - custom-theme.css

Then you will need to have this line in config.toml

[params.reveal_hugo]
reveal_hugo.custom_theme = "assets/custom-theme.css"

#Adding HTML to the layout

If you need to add something to the HTML layout, you can create partials that live at specific locations, depending on which presentation you want to customize and where you want the HTML inserted into the page.

This is the recommended way to add custom CSS and JavaScript to each presentation.

💡 Tip: In Hugo, partials live in the layouts folder:

For example, if you have HTML that is to be placed before every presentation, this would be the structure:

- layouts
  - partials
    - reveal-hugo
      - head.html
      - body.html
      - end.html

#Reveal.js tips

These are some useful Reveal.js features and shortcuts.

• 's' - type 's' to enter speaker mode, which opens a separate window with a time and speaker notes
• 'o' - type 'o' to enter overview mode and scroll through slide thumbnails
• 'f' - type 'f' to go into full-screen mode

Here are a few useful Reveal.js-related tools:

• decktape for exporting a presentation as a PDF
• More revealjs themes including robot-lung and sunblind

Find many more on the Reveal.js wiki: Plugins, tools and hardware.