Ruby Setup

To ensure repeatability, we recommend that you manage your presentation projects using bundler.

Prerequisites

  1. Install bundler (if not already installed) using your system’s package manager or with:

    $ gem install bundler
  2. If you’re using RVM, make sure you switch away from any gemset:

    $ rvm use default

    or

    $ rvm use system

Install

These instructions should be repeated for every presentation project.
  1. Create project directory

    $ mkdir my-awesome-presentation
    $ cd my-awesome-presentation
  2. Create a file named Gemfile with the following content:

    source 'https://rubygems.org'
    
    gem 'asciidoctor-revealjs' # latest released version
    For some reason, when you use the system Ruby on Fedora, you also have to add the json gem to the Gemfile.
  3. Install the gems into the project

    $ bundle config --local github.https true
    $ bundle config set --local path '.bundle/gems'
    $ bundle binstubs --all
  4. Optional: Copy or clone reveal.js presentation framework. Allows you to modify themes or view slides offline.

    $ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git

Rendering the AsciiDoc into slides

  1. Create content in a file (*.adoc, *.ad, etc.). See examples on the Features page to get started.

  2. Generate HTML presentation from the AsciiDoc source

    $ bundle exec asciidoctor-revealjs \
      -a revealjsdir=https://cdn.jsdelivr.net/npm/reveal.js@3.9.2 CONTENT_FILE.adoc
  3. If you did the optional step of having a local reveal.js clone you can convert AsciiDoc source with

    $ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc
If you are using GitHub Pages, plan ahead by keeping your source files on master branch and all output files on the gh-pages branch.

Features unique to the Ruby CLI

Starting with 4.0.0 you can specify a set of custom templates to use instead of the ones provided by this project. This can help you achieve even more concise AsciiDoc syntax and integration with reveal.js at the cost of more maintenance.

To use it, add the following dependencies to your Gemfile:

gem 'tilt', '~>2.0'
gem 'slim', '~>4.0'

Then install the dependencies with:

$ bundle install

The feature is activated with the --template-dir or -T option:

$ bundle exec asciidoctor-revealjs -T templates/ CONTENT_FILE.adoc

Any individual template file not provided in the directory specified on the command-line will fall back to the template provided by your version of Asciidoctor reveal.js. Refer to our templates for inspiration.

This feature hasn’t been ported to the JavaScript CLI (and API) or the standalone executables.