b9d502335b | ||
---|---|---|
data | ||
exampleSite | ||
images | ||
layouts | ||
static/reveal-hugo | ||
.gitignore | ||
LICENSE | ||
README.md | ||
netlify.toml | ||
package-lock.json | ||
package.json | ||
theme.toml |
README.md
reveal-hugo
A Hugo theme for Reveal.js that makes authoring and customization a breeze. With it, you can turn any properly-formatted Hugo content into a HTML presentation.
Example
Using reveal-hugo, presentations with multiple slides can be created with just one markdown file, like so:
+++
title = "How to say hello"
+++
# English
Hello.
---
# Français
Salut.
---
# Español
Holá.
Just use ---
to split content into different slides.
Demo
Visit reveal-hugo.dzello.com to see a presentation created with this theme and learn more about what you can do. Jump to the 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 repository.
For a full-length blog post about reveal-hugo, checkout Harness the Power of Static Site Generators to Create Presentations on the Forestry.io blog.
Tutorial
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.
Create your first presentation
To start, install Hugo and create a new Hugo site:
$ hugo new site my-presentation
Change into the directory of the new site:
$ cd my-presentation
Add the reveal-hugo theme as a submodule in the themes directory:
$ git submodule add git@github.com:dzello/reveal-hugo.git themes/reveal-hugo
Open config.toml
and add the following contents:
theme = "reveal-hugo"
[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true
This tells Hugo to use the reveal-hugo theme and it registers a new output format called "Reveal".
Next, create a file in content/_index.md
and add the following:
+++
title = "My presentation"
outputs = ["Reveal"]
+++
# Hello world!
This is my first slide.
Back on the command line, run:
$ hugo server
Navigate to http://localhost:1313/ and you should see your presentation.
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.
# Hello world!
This is my first slide.
---
# Hello Mars!
This is my second slide.
Usage
The Usage guide is contained in the example presentation that lives in this repository in the exampleSite directory. You can access a live version at reveal-hugo.dzello.com.
Root vs. section presentations
Here's what the folder structure would look like with one root presentation and one section presentation. I use "chunk" in the following example to avoid a collision with Hugo's "section".
- content
- home # special hugo section for adding to the root presentation
- body.md # a chunk of the root presentation
- conclusion.md # another chunk of the root presentation
- _index.md # beginning of the root presentation
- ted-talk
- _index.md # beginning of the ted talk presentation
- body.md # a chunk of the ted talk presentation
- conclusion.md # another chunk of the ted talk presentation
This will create two presentations, one at /
and one at /ted-talk/
. The order of the chunks can be controlled by the weight
parameter specified in the front matter. The _index.md
chunk will always come first, though you don't have to put any slides in it if you want to. The Reveal outputFormat need only be added to the _index.md
file.
Configuration
Customize the Reveal.js presentation by setting these values in config.toml
or the front matter of any presentation's index.md
file.
params.reveal_hugo.theme
: The Reveal.js theme used, defaults to "black"params.reveal_hugo.custom_theme
: The path to a locally hosted Reveal.js themeparams.reveal_hugo.highlight_theme
: The highlight.js theme used, defaults to "default"
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 here. The defaults used by this theme are located in data/reveal_hugo.toml
.
If you're new to TOML, this is how it should look in your config.toml
:
[params.reveal_hugo]
theme = "moon"
Or in the front matter of an _index.md
file:
[reveal_hugo]
theme = "moon"
Adding HTML to the page
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.
Add a Reveal.js presentation to an existing Hugo site
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:
cd my-hugo-site
git clone git@github.com:dzello/reveal-hugo.git themes/reveal-hugo
cd themes/reveal-hugo
cp -r data layouts static ../../
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.
Next, add the Reveal output format to your site's config.toml
file
[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true
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.
Reveal.js favorites
Not directly related to reveal-hugo, but these are some of my favorite 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 of my favorite Reveal.js-related tools:
- decktape for exporting a presentation as a PDF
Find many more on the Reveal.js wiki: Plugins, tools and hardware.
Contributing
Contributions are very welcome. To run the example site in this repository locally, clone this repository and run:
hugo server -s exampleSite
or simply...
npm start