jekyll-reveal.js

A Jekyll-based framework for creating presentations based on Reveal.js and Markdown.

• Introduction
• Howto
• Slide filenames
• Configuring the presentation
  • Specifying reveal options and dependencies
• Custom reveal.js themes
• Markdown extensions and simplification
  • Multiple slides
  • Vertical slides
  • Fragments
  • Slide backgrounds
  • Speaker notes
  • SVG Diagrams

Introduction

If you like Reveal.js for creating your online presentations, like the site management Jekyll gives you and like Markdown because of its easy and clean look, here's an easy way to create a presentation using Jekyll, Markdown and Reveal.js.

See the example presentation created using the contents in this repository and jekyll build or docker-compose up.

Howto

First, install Jekyll. After that, clone this repository and create a branch for your new presentation:

git clone --recursive https://github.com/dploeger/jekyll-revealjs.git
git checkout -b presentation1

Clean the Example presentation:

git rm _posts/*
mkdir _posts

Alternatively, you can create a new Jekyll site from scratch and refer to this repository as a remote theme using the Jekyll Remote Theme plugin (supported on GitHub Pages).

After that, add your slides into the _posts subdirectory in clean Markdown syntax and you're ready to build your presentation with Jekyll:

jekyll build

If you don’t have Jekyll installed (but you do have Docker) then you can just run the following to build and serve your changes using a container. Hit ctrl-c to stop the process.

 docker-compose up

You can even manage multiple presentations using the power of Git. Simply branch from the master branch to create a new presentation:

git checkout master
git branch presentation2
git checkout presentation2

Slide filenames

Because we're using Jekyll posts to easily gather the slides for the presentation, we use their filename conventions with the following syntax:

<year>-<month>-<day>-<title>.md

We recommend naming the files like

0000-01-01-welcome.md
0000-01-02-topics.md

and so forth.

Jekyll will assume that each post has been made on the first of January, 2001 (which is of no interest for a presentation). The additional number is for sorting purposes. After that comes a title to identify the specific slide (which is actually only for the presentation author, Jekyll doesn't care about it).

Configuring the presentation

You can configure almost any reveal.js setting using the _config.yml settings file in the root directory.

• title: The title of your presentation (displayed in the browser's title bar, optional and defaults to your repository’s name thanks to the jekyll-github-metadata plugin)

• description: A description for your presentation (displayed in the HTML head, optional and defaults to your repository’s description thanks to the jekyll-github-metadata plugin)

• author: Your name (displayed in the HTML head)

• reveal_theme: The reveal.js-theme to use [default.css]

• reveal_transition: The reveal.js-transition to use [default]

• reveal_theme_path: The path to the reveal.js-theme (can be changed for custom themes) [reveal.js/css/theme/]

• reveal_notes_server: Whether to support the speaker notes server [false (only local speaker notes)]

• reveal_options: Additional reveal.js options

• reveal_dependencies: Additional reveal.js dependencies

• reveal_path: Path to the reveal.js-installation reveal.js

You can also further customize the presentation:

• extra_css: Additional CSS files added after the reveal theme
• highlight_style_sheet: CSS theme for highlight.js reveal.js/lib/css/zenburn.css
• mermaid_diagrams: Feature toggle (defaults to false) for mermaid.js diagrams

Specifying reveal options and dependencies

reveal_options can be either a list of strings specifying the JavaScript options, e.g.:

reveal_options:
  - 'width: "960px"'
  - 'height: "720px"'

or, as a convenience, it can be a mapping of options to their values:

reveal_options:
  width: 960px
  height: 720px

Note that if a mapping is passed, the values will be inserted into the final JavaScript as quoted strings. If this is unacceptable (for example, if you want to pass a Boolean parameter that takes true or false), specify a list of strings.

reveal_dependencies takes a list of strings representing the JavaScript to specify a dependency as you would in reveal.js, for example:

reveal_dependencies:
  # Speaker notes
  - "{ src: 'path/to/plugin.js', async: true },"

Custom reveal.js themes

If you want to use your custom reveal.js theme, we recommend adding a directory theme, putting the file(s) there and referencing that directory in the configuration reveal_theme_path.

Don't mess with the reveal.js subdirectory as it is a submodule and doesn't adhere to your repository's branches.

Markdown extensions and simplification

Reveal.js already includes a Markdown interpreter, which we use for jekyll-reveal.js. We have already configured it and included some simplification just for you!

Multiple slides

To use multiple slides in one slide file, use a newline, three dashes and another newline like this:

# Slide 1

This is the content of Slide 1

---

# Slide 2

This is the content of Slide 2

Vertical slides

To use vertical slides, do the same, but use two dashes:

# Slide 1

This is the content of Slide 1

--

And this is a vertical slide below Slide 1

Fragments

Fragments allow slide elements to come one by one. This is often used in lists to subsequently show fragments of a list during a presentation.

jekyll-reveal.js simplifies the reveal.js syntax. To specify the current element as a fragment, use <fragment/> like this:

# Slide

- This <fragment/>
- will <fragment/>
- come one by one <fragment/>

Or, if you find it cleaner, like this:

# Slide

+ This
+ will
+ come one by one

Slide backgrounds

To modify the background of the current slide, jekyll-reveal.js simplifies the syntax to <background>color</background>:

# Slide

<background>white</background>

This slide has a white background

Image backgrounds

You can also set image backgrounds:

# Slide

<backgroundimage>{{ site.github.url }}/images/image.jpg</backgroundimage>
<backgroundimageopacity>0.25</backgroundimageopacity>

This slide has an image background

Note: {{ site.github.url }} expands to the URL of your hosted site, but you could also use remote URLs.

Speaker notes

To include speaker notes, add Note: on a separate line and write your notes below:

# Slide

Some slide content

Note:

This is only displayed in the speaker notes.

SVG Diagrams

You can use mermaid-js to create SVG diagrams.

Once you’ve enabled the feature by setting mermaid_diagrams to true in _config.yml, code like this:

<mermaid>
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
    D-->E
</mermaid>

should render like this:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
    D-->E

Loading

You can tweak the height of the diagram by following the closing tag with an element attribute: <!-- .element: style="height: 400px;" -->.