Ronan Soares

Ronan Soares

Professor of the Department of Statistics and Applied Mathematics at Federal University of Ceará.

Jekyll with(out) reveal.js

2 minute read

There is an elegant way to add a reveal.js presentation inside a Jekyll site. In a way that the presentation is a page of the site. However, this approach has some drawbacks. The main one is that in order to update the reveal.js dependency with a breaking change you might need to update all the presentation broken by this change.

Other approach would be to use reveal.js as a standalone presentation.

Prerequisite

Depends if you are hosting locally or with GitHub Pages:

  • Locally: Install Jekyll.
  • GitHub Pages: “Nothing”.

However you should still install Jekyll locally in order to be able to see changes in your site without having to push to GitHub.

Setup Jekyll

First you need to create a new Jekyll site from the command line.

The following command will make a new folder named jekyll-reveal-tutorial inside the current folder and populate it with a default Jekyll theme.

jekyll new jekyll-reveal-tutorial

Now you can enter the folder with:

cd jekyll-reveal-tutorial

To start the Jekyll server you can use the following command inside the folder:

bundle exec jekyll serve --livereload

The --livereload option allow for the automatic reloading of web pages from the browser upon changes in the files.

Now you can access the site from the browser at localhost:4000.

Setup reveal.js the submodule way

If you are not using git you should.

If you are using git you can add reveal.js as a submodule to your site.

Add reveal.js as a submodule with the following command:

git submodule add https://github.com/hakimel/reveal.js.git reveal.js

This will create a folder named reveal.js inside your site.

Copy the file demo.html from reveal.js folder to another folder the root directory of your site. Let’s put it inside a new directory called slides.

From the root folder of your site adapt the command below and use it:

mkdir slides
cp reveal.js/demo.html slides/demo.html

Now edit the demo.html created by changing the lines:

<link rel="stylesheet" href="dist/reset.css">
<link rel="stylesheet" href="dist/reveal.css">
<link rel="stylesheet" href="dist/theme/black.css" id="theme">
<link rel="stylesheet" href="plugin/highlight/monokai.css">

<script src="dist/reveal.js"></script>
<script src="plugin/zoom/zoom.js"></script>
<script src="plugin/notes/notes.js"></script>
<script src="plugin/search/search.js"></script>
<script src="plugin/markdown/markdown.js"></script>
<script src="plugin/highlight/highlight.js"></script>

to:

<link rel="stylesheet" href="../reveal.js/dist/reset.css">
<link rel="stylesheet" href="../reveal.js/dist/reveal.css">
<link rel="stylesheet" href="../reveal.js/dist/theme/black.css" id="theme">
<link rel="stylesheet" href="../reveal.js/plugin/highlight/monokai.css">

<script src="../reveal.js/dist/reveal.js"></script>
<script src="../reveal.js/plugin/zoom/zoom.js"></script>
<script src="../reveal.js/plugin/notes/notes.js"></script>
<script src="../reveal.js/plugin/search/search.js"></script>
<script src="../reveal.js/plugin/markdown/markdown.js"></script>
<script src="../reveal.js/plugin/highlight/highlight.js"></script>

Then you should be able to see the demo presentation accessing http://localhost:4000/slides/demo.html from the browser.

Do not forget the ending .html. Otherwise, the stylesheets will not work.

Changing: title, author and description, metadata

You must have realized that the title, author and description in the , we can remedy this by changing the lines in slide.html:

<title>reveal.js – The HTML Presentation Framework</title>
<meta name="description" content="A framework for easily creating beautiful presentations using HTML">
<meta name="author" content="Hakim El Hattab">

to

<title>TITLE YOU WANT</title>
<meta name="description" content="A DESCRIPTION FOR THE PRESENTATION">
<meta name="author" content="YOU ALIAS">

Adding new presentations

You can add new presentations simply by copying the demo.html file and changing its name.

Why do it this way?

The objective of this approach is to make presentations that could stand the test of time.

There are some obvious conventions that we are explicitly avoiding with this approach.

First one is violating Do not Repeat Yourself (DRY), there are several components that stays the same between two different presentations. However, each presentation should be considered unique since they seldom have the same topics, styles or needs.

Second one is violating Separation of Concerns (SoC), the presentation is not separated from the site. However, the presentation is a page of the site. And I wanted to have an unique repository for all the presentations and website for a given course.