Reveal.js converter for Asciidoctor

Olivier Bilodeau <github.com/obilodeau[@obilodeau]>; Guillaume Grossetie <github.com/mogztter[@mogztter]>; Dan Allen <github.com/mojavelinux[@mojavelinux]>; Rahman Usta <github.com/rahmanusta[@rahmanusta]>; Charles Moulliard <github.com/cmoulliard[@cmoulliard]> ifdef::env-github,env-browser[] :toc: preamble :toclevels: 2 endif::[] ifdef::env-github[] :branch: master :status: :outfilesuffix: .adoc :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] :uri-project-repo: github.com/asciidoctor/asciidoctor-reveal.js :uri-asciidoctor: github.com/asciidoctor/asciidoctor :uri-asciidoctorjs: github.com/asciidoctor/asciidoctor.js :uri-revealjs-home: revealjs.com :uri-revealjs-gh: github.com/hakimel/reveal.js/blob/v3.9 :uri-revealjs-doc: {uri-revealjs-gh}/README.md :uri-nodejs-download: nodejs.org/en/download/ :showcasedir: showcase

ifdef::env-github[] image:travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=travis-ci.org/asciidoctor/asciidoctor-reveal.js] image:img.shields.io/gem/v/asciidoctor-revealjs.svg[gem, link=rubygems.org/gems/asciidoctor-revealjs] image:img.shields.io/npm/v/@asciidoctor/reveal.js.svg[npm, link=www.npmjs.org/package/@asciidoctor/reveal.js] endif::[]

// IMPORTANT: Changes made to this description should be sync'ed with the readme field in package.json. uri-project-repo}[Asciidoctor reveal.js] is a converter for {uri-asciidoctor and uri-asciidoctorjs that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the uri-revealjs-home presentation framework.

TIP: Want to see some example presentations, see <<Showcase Presentations>>

There are four main technology stacks that can convert AsciiDoc into HTML5 / reveal.js:

ifeval::['{branch}' == 'master'] NOTE: You're viewing the documentation for an upcoming release. If you're looking for the documentation for the current release or an older one, please click on the appropriate link below: + {uri-project-repo}/tree/v4.0.0#readme (latest from 4.x series) &hybull; {uri-project-repo}/tree/v3.1.0#readme (latest from 3.x series) &hybull; {uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with reveal.js 2.x) endif::[]

Ruby Setup

NOTE: To ensure repeatability, we recommend that you manage your presentation projects using bundler.io/[bundler].

Prerequisites

. Install bundler.io/[bundler] (if not already installed) using your system's package manager or with:

$ gem install bundler

. If you're using RVM, make sure you switch away from any gemset:

$ rvm use default

+ or +

$ rvm use system

Install

NOTE: These instructions should be repeated for every presentation project.

. Create project directory

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

. Create a file named `Gemfile` with the following content: +

source,ruby

source 'rubygems.org'

gem 'asciidoctor-revealjs' # latest released version


+ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to add the json gem to the Gemfile. + . Install the gems into the project

$ bundle config --local github.https true
$ bundle --path=.bundle/gems --binstubs=.bundle/.bin

. 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

. Create content in a file (*.adoc, *.ad, etc.).

See examples in <<Syntax Examples>> section 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 CONTENT_FILE.adoc

. 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

TIP: If you are using pages.github.com/[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 github.com/asciidoctor/asciidoctor-reveal.js/tree/master/templates[templates] for inspiration.

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

Node / JavaScript Setup

Prerequisites

First you must install and configure uri-nodejs-download on your machine.

[node-install]

Install

We recommend to install the dependencies in a project directory, such as the directory where your AsciiDoc presentations are stored. If you don't have a `package.json` file in your project directory, you can create one to eliminate warnings during the installation using:

$ npm init -y

You can now install the dependencies:

$ npm i --save asciidoctor@^2.0 @asciidoctor/reveal.js

Convert AsciiDoc into slides

Once the dependencies are installed, verify that the `asciidoctor-revealjs` command is available. On Linux and macOS, open a terminal and type:

$ npx asciidoctor-revealjs --version

On Windows, open PowerShell and type:

$ .\node_modules\.bin\asciidoctor-revealjs.cmd --version

The command should report the Asciidoctor CLI version in the terminal:

source,console

Asciidoctor.js 2.0.3 (Asciidoctor 2.0.9) [asciidoctor.org] Runtime Environment (node v10.15.1 on linux) CLI version 2.0.1


If you don't have an existing presentation, you can create a sample presentation named [.path]presentation.adoc:

.presentation.adoc

source,asciidoc

Title Slide

Slide One

  • Foo

  • Bar

  • World


To convert the sample presentation into slides, open a terminal and type:

$ npx asciidoctor-revealjs presentation.adoc

On windows, open PowerShell and type:

$ .\node_modules\.bin\asciidoctor-revealjs.cmd presentation.adoc

The above command will generate a file named [.path]presentation.html. You can open this file in a browser.

Using the JavaScript API

Alternatively, you can use the JavaScript API to register the converter and convert a document:

.convert-slides.js

source,javascript

// Load Asciidoctor.js and the reveal.js converter var asciidoctor = require('@asciidoctor/core')() var asciidoctorRevealjs = require('@asciidoctor/reveal.js') asciidoctorRevealjs.register()

// Convert the document 'presentation.adoc' using the reveal.js converter var options = { safe: 'safe', backend: 'revealjs' } asciidoctor.convertFile('presentation.adoc', options) // <1>


<1> Creates a file named `presentation.html` (in the directory where command is run)

To execute the script, open a terminal and type:

$ node convert-slides.js

You can open the `presentation.html` file in your browser and enjoy!

Standalone Executable

Pre-built binary packages can be downloaded from our {uri-project-repo}/releases[GitHub release page]. We provide them for Windows 64-bit, Linux 64-bit and macOS 64-bit. Open an issue if your platform isn't supported. The executables are built using the <<Node / JavaScript Setup,Node / JavaScript>> toolchain.

Install

  • {uri-project-repo}/releases[Download the executable] for your platform and make it executable with `chmod` or using the files properties' user interface.

  • Copy or clone the reveal.js presentation framework in the directory where you will build your slidedeck. Here we do a shallow clone of the repo:

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

Convert AsciiDoc into slides

Open a terminal where the executable is and type:

$ ./asciidoctor-revealjs --version

The command should report the Asciidoctor reveal.js and Asciidoctor CLI version in the terminal:

source,console

Asciidoctor reveal.js 3.0.1 using Asciidoctor.js 2.0.3 (Asciidoctor 2.0.9) [asciidoctor.org] Runtime Environment (node v12.13.1 on linux) CLI version 3.1.0


If you don't have an existing presentation, you can create a sample presentation named [.path]presentation.adoc:

.presentation.adoc

source,asciidoc

Title Slide

:revealjsdir: reveal.js

Slide One

  • Foo

  • Bar

  • World


To convert the sample presentation into slides, open a terminal and type:

$ ./asciidoctor-revealjs presentation.adoc

The above command will generate a file named [.path]presentation.html. You can open this file in a browser.

Syntax Examples

Let's see some examples of `revealjs` backend features. Additional examples can be found in the AsciiDoc files (.adoc) in `examples/`.

Basic presentation with speaker notes

source, asciidoc

Title Slide

Slide One

  • Foo

  • Bar

  • World

Slide Two

A Great Story

.notes