Ruby Setup

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

Prerequisites

If you manage Ruby using RVM (as recommended), make sure you switch to the default Ruby version and gemset:

$ rvm use default

If you’ve installed Ruby using RVM, you should already have Bundler installed. You can verify this using the following command:

$ bundle -v

If Bundler is not installed, you can install it using the following command:

$ gem install bundler

You’re now ready to install Asciidoctor reveal.js.

Install

These instructions should be repeated for every presentation project.

Create a project directory

$ mkdir my-awesome-presentation
$ cd my-awesome-presentation

In that directory, create a file named Gemfile with the following contents:
```
source 'https://rubygems.org'

gem 'asciidoctor-revealjs' (1)
```
1 Installs the latest released version of the asciidoctor-revealjs gem

Install the gems into the project using Bundler

$ bundle config --local path .bundle/gems
$ bundle

(Optional) Copy or clone reveal.js presentation framework
```
$ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git
```
This step allows you to modify themes or view slides offline.

Rendering the AsciiDoc into slides

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

Generate HTML presentation from the AsciiDoc source

$ bundle exec asciidoctor-revealjs \
  -a revealjsdir=https://cdn.jsdelivr.net/npm/reveal.js@3.9.2 \
  presentation.adoc

If you did the optional step of having a local clone of reveal.js, you can convert the AsciiDoc source using:
```
$ bundle exec asciidoctor-revealjs presentation.adoc
```

If you’re using GitHub Pages, plan ahead by keeping your source files on the default 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 presentation.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.