Skip to content

Latest commit

 

History

History
395 lines (283 loc) · 15 KB

README.md

File metadata and controls

395 lines (283 loc) · 15 KB
Raw

reveal-jekyll

Transforms Markdown files into presentation slides using reveal.js and Jekyll. The theme is based on Solarized Colors (by Ethan Schoonover) containing a light and a dark theme.
reveal-jekyll is ready for GitLab Pages as well as GitHub Pages.

Build Status

Try the DEMO presentation (how to use Jekyll written in German).

Get reveal-jekyll running

Hosted on GitLab Pages

To see how it works follow the Tutorial: Create a GitLab Pages website from scratch.

As a User or Organization Site on GitLab

To set up a user or organization site https://${yourname}.gitlab.io/, fork reveal-jekyll and name your fork with your user or organization name like https://gitlab.com/${yourname}/${yourname}.github.io. Your site will build off the main branch.

As a Project Site on GitLab

To set up a project site https://${yourname}.gitlab.io/${projectname}:

  • Fork as above, but name your fork with whatever ${projectname} you want.
  • In _config.yml change baseurl: "" to baseurl: /${projectname}. This is needed to construct asset include and internal link URLs correctly when you are serving your site from a non-root path.

For an Existing Repository on GitLab

  • Clone your repository.
  • Go into it.
  • Add reveal-jekyll as an upstream remote.
  • Create an empty branch named like pages.
  • Delete all cached files of your new pages branch from git.
  • Clean the directory from uncached files.
  • Merge reveal-jekyll/main with your ${repository}/pages branch.
git clone [email protected]/${yourname}/${repository}.git
cd ${repository}
git remote add upstream https://gitlab.com/tasmo/reveal-jekyll.git
git checkout --orphan pages
git rm --cached -r .
git clean -fdx
git merge upstream/main

Hosted on GitHub Pages

Follow the instructions on get started with GitHub Pages.

As a User or Organization Site on GitHub

To set up a user or organization site https://${yourname}.github.io/, fork reveal-jekyll and name your fork with your user or organization name like ${yourname}.github.io. Your site will build off the main branch.

As a Project Site on GitHub

To set up a project site https://${yourname}.github.io/${projectname}:

  • Fork as above, but name your fork with whatever ${projectname} you want.
  • Your site will build from the gh-pages branch, so you should set that as the default branch.
  • In _config.yml in your gh-pages branch change baseurl: "" to baseurl: /${projectname}. This is needed to construct asset include and internal link URLs correctly when you are serving your site from a non-root path.

For an Existing Repository on Github

  • Clone your repository.
  • Go into it.
  • Add reveal-jekyll as an upstream remote.
  • Create an empty branch named gh-pages.
  • Delete all cached files of your new gh-pages branch from git.
  • Clean the directory from uncached files.
  • Merge reveal-jekyll/master with your ${repository}/gh-pages.
git clone [email protected]/${yourname}/${repository}.git
cd ${repository}
git remote add upstream https://github.com/tasmo/reveal-jekyll.git
git checkout --orphan gh-pages
git rm --cached -r .
git clean -fdx
git merge upstream/main

Local Jekyll

Install RubyGems for your system.

Clone reveal-jekyll with submodule reveal.js (recommended):

git clone --recursive --depth 1 https://github.com/tasmo/reveal-jekyll.git

…or just download the zip file.

Make sure you have a Gemfile in the root of your project containing at least:

source "https://rubygems.org"

gem 'github-pages'

Install Bundler and the dependencies:

gem install bundler \
bundle install

Write Your Slides

Put your Markdown slides in the _posts folder like in any Jekyll instance.
Name the files in numbered order or dated following a pattern like YEAR-MONTH-DAY-TITLE.md:

2014-1-1-start.md
2014-1-1-intro.md
…
2014-3-2-third-topic-second-slide.md
…
2014-9-8-end.md
2014-9-9-very-last-slide.md

Write the slide's header in Front-matter and put the Markdown formatted content below. In the header you need at least the layout: slide attribute:

---
layout: slide
title:
---

MARKDOWN_FOMATTED_SLIDE_CONTENT

Personalize

In the _config.yml give your slide show an name, author's name and a description:

title:       reveal-jekyll
author:      Thomas Friese
description: Reveal.js for Jekyll with Solarized Color theme

Start Your Slide Show

On GitLab/GitHub Pages you are done. Just open your pages URL in your browser.

An your local machine run:

bundle exec jekyll serve

…and go to https://127.0.0.1:4000/.

reveal.js

A framework for easily creating beautiful presentations using HTML.

reveal.js comes with a broad range of features including nested slides, markdown contents, PDF export, speaker notes and a JavaScript API. It's best viewed in a browser with support for CSS 3D transforms but fallbacks are available to make sure your presentation can still be viewed elsewhere.

Links for reveal.js

Jekyll

Jekyll is a simple, blog-aware, static site generator perfect for personal, project, or organization sites. Think of it like a file-based CMS, without all the complexity. Jekyll takes your content, renders Markdown and Liquid templates, and spits out a complete, static website ready to be served by Apache, Nginx or another web server. Jekyll is the engine behind GitHub Pages, which you can use to host sites right from your GitHub repositories.

Links for Jekyll

Differences and Limitations

Slide Attributes

Attributes to the slide <section> elements are written in the Front-matter:

---
layout: slide
title: Background Transitions
data:
  transition: linear
  background: 'red'
  background-transition: slide
---

Fragments

Markdown fragments must be covered in a HTML block element using the attribute markdown="1":

<div markdown="1" class="fragment">
# Markdown Heading
 
Fragment 1 text
</div>
<div markdown="1" class="fragment">
Fragment 2 text
</div>

Fragments can be nested.

Vertical Slides

For vertical scrolling you need to leave the title: blank. All content on vertical slides must be wrapped in HTML <section> blocks:

---
layout: slide
title:
---

<section markdown="1">
# Top Slide
</section>
<section markdown="1">
# Bottom Slide
</section>

Configuration

All options for the reveal.js presentation are available in the _config.yml as sub keys of reveal:.

The configuration will be built in the <script /> block at the bottom of the index.html presentation file.

Code Syntax Highlighting

To insert a highlighted code block the code can be surrounded with the Liquid tag highlight:

{% highlight coffee %}
# Objects:
math =
  root:   Math.sqrt
  square: square
  cube:   (x) -> x * square x
{% endhighlight %}

Insted of Rouge for highlighting the code, reveal-jekyll uses the Reveal.js's preferred method via highlight.js. To use all options it is possible to surround the code with HTML nodes pre and code using the class language-* adding optional data tags:

<pre><code class="language-coffee" data-trim data-noescape data-line-numbers="1|3-5">
# Objects:
math =
  root:   Math.sqrt
  square: square
  cube:   (x) -> x * square x
</code></pre>

Slide Numbers

You can show slide numbers by selecting a format in the _config.yml file:

slideNumber:
  # Slide number formatting can be configured using these variables:
  #  "h.v":  horizontal . vertical slide number (default)
  #  "h/v":  horizontal / vertical slide number
  #    "c":  flattened slide number
  #  "c/t":  flattened slide number / total slides
  # "none":  don't show slide numbers
  format:    "c/t"

Speaker Notes

reveal.js comes with a speaker notes plug-in which can be used to present per-slide notes in a separate browser window. The notes window also gives you a preview of the next upcoming slide so it may be helpful even if you haven't written any notes. Press the 's' key on your keyboard to open the notes window.

Notes are defined by appending an <aside> element to a slide as seen below. You can add the markdown="1" attribute to the aside element if you prefer writing notes using Markdown:

---
layout: slide
---

Slide text...

<aside class="notes" markdown="1">
Oh hey, these are some notes. They'll be hidden in your presentation, but you can see them if you open the speaker notes window (hit 's' on your keyboard).
</aside>

When used locally, this feature requires that reveal.js runs from a local web server.

Runtime Dependencies for Development

Running Jekyll on Your Server

  • Commander: Command-line interface constructor (Ruby)
  • Colorator: Colorizes command line output (Ruby)
  • Classifier: Generating related posts (Ruby)
  • Directory Watcher: Auto-regeneration of sites (Ruby)
  • Kramdown: Default Markdown engine (Ruby)
  • Liquid: Templating system (Ruby)
  • Pygments.rb: Syntax highlighting (Ruby/Python)
  • Safe YAML: YAML Parser built for security (Ruby)
  • Sass: CSS extension language (Ruby)
  • CoffeeScript: compiling to JavaScript (Ruby)

Running reveal.js

Reveal.js doesn't rely on any third party scripts to work but a few optional libraries are included by default. These libraries are loaded as dependencies in the order they appear, for example:

Reveal.initialize({
  dependencies: [
    // Cross-browser shim that fully implements classList - //github.com/eligrey/classList.js/
    { src: 'lib/js/classList.js', condition: function() { return !document.body.classList; } },

    // Zoom in and out with Alt+click
    { src: 'plugin/zoom-js/zoom.js', async: true },

    // Speaker notes
    { src: 'plugin/notes/notes.js', async: true },

    // Remote control your reveal.js presentation using a touch device
    { src: 'plugin/remotes/remotes.js', async: true },

    // MathJax
    { src: 'plugin/math/math.js', async: true }
  ]
});

You can add your own extensions using the same syntax. The following properties are available for each dependency object:

  • src: Path to the script to load
  • async: [optional] Flags if the script should load after reveal.js has started, defaults to false
  • callback: [optional] Function to execute when the script has loaded
  • condition: [optional] Function which must return true for the script to be loaded

Licenses

Jekyll: MIT licensed

reveal.js: MIT licensed
Copyright (C) 2020 Hakim El Hattab, https://hakim.se

reveal-jekyll contains the third party fonts:

reveal-jekyll: MIT licensed