Asciidoctor Reveal.js

> Asciidoctor > Asciidoctor Documentation >

The reveal.js backend is a collection of templates for Asciidoctor (or Asciidoctor.js) that transform an AsciiDoc document into HTML5 slides animated by reveal.js.

There are two main technology stacks that can transform AsciiDoc into HTML5 / Reveal.js:

Right now the Ruby / Slim templates are more featureful but that is changing quickly.

Ruby Setup

asciidoctor-reveal.js is now a Ruby Gem. To ensure repeatability, we recommend that you manage your presentation projects using bundler.

For a quick start clone our starter repository and follow instructions there.

For more complete instructions, read on.

If you want to use reveal.js 2, please clone the asciidoctor-reveal.js repo and switch to the reveal.js-2.x branch.

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
#gem 'asciidoctor-revealjs', github: 'asciidoctor/asciidoctor-reveal.js' # github master branch
    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 --path=.bundle/gems --binstubs=.bundle/.bin

  4. Optional: Copy or clone reveal.js presentation framework. Allows you to modify themes or view slides offline.

    $ git clone -b 3.3.0 --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 in Syntax Examples section to get started or look at files in test/.

  2. Generate HTML presentation from the AsciiDoc source

    $ 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.

Node / JavaScript Setup

Prerequisites

First you must install and configure Node.js on your machine.

Install

Using npm:

$ npm i --save asciidoctor.js@1.5.5-2
$ npm i --save asciidoctor-template.js@1.5.5-2
$ npm i --save asciidoctor-reveal.js@1.5.5-2

Rendering the AsciiDoc into slides

Once the package is installed, you can convert AsciiDoc files using Reveal.js backend. Here we are converting a file named presentation.adoc into a Reveal.js presentation using Node.js:

asciidoctor-revealjs.js
// Load asciidoctor.js + asciidoctor-template.js
var asciidoctor = require('asciidoctor.js')();
var Asciidoctor = asciidoctor.Asciidoctor();
var Opal = asciidoctor.Opal;
Opal.load('nodejs');
Opal.load('pathname');
require('asciidoctor-template.js');

// Convert the document 'presentation.adoc' using Reveal.js backend
var attributes = 'revealjsdir=node_modules/reveal.js@';
var options = Opal.hash({safe: 'safe',
                         backend: 'revealjs',
                         attributes: attributes});
Asciidoctor.$convert_file('presentation.adoc', options); (1)
1 Creates a file named presentation.html (in the directory where command is run)
presentation.adoc
= Title Slide
// depending on your npm version, you might need to override the default
// 'revealjsdir' value by removing the comments from the line below:
//:revealjsdir: node_modules/asciidoctor-reveal.js/node_modules/reveal.js

== Slide One

* Foo
* Bar
* World

To render the slides, run:

node asciidoctor-reveal.js

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

Syntax Examples

Let’s see some examples of revealjs backend features.

Basic presentation with speaker notes

= Title Slide

== Slide One

* Foo
* Bar
* World

== Slide Two

Hello World - Good Bye Cruel World

[NOTE.speaker]
--
Actually things aren't that bad
--

In previous snippet we are creating a slide titled Slide One with bullets and another one titled Slide Two with centered text (reveal.js' default behavior) with speaker notes.

Slides without titles

There are a few ways to have no titles on slides.

  • Setting your title to !

  • Adding the notitle option to your slide

  • Adding the conceal option to your slide

Here is an example of the three techniques in action:

Unresolved directive in https://cdn.rawgit.com/asciidoctor/asciidoctor-reveal.js/v1.0.1/README.adoc - include::test/concealed-slide-titles.adoc[]
conceal and notitle have the advantage that the slide still has an id so it can be linked to.

Background colors

[background-color="yellow"]
== Slide Three

Is very yellow

Slide Three applies the attribute data-background-color to the reveal.js <section> tag. Anything accepted by CSS color formats works.

Background images

[%notitle]
== Grand Announcement

image::cover.jpg[background, size=cover]

This will put cover.jpg as the slide’s background image. It sets reveal.js' data-background-image attribute. The size attribute is also supported. See the relevant reveal.js documentation for details.

Background images file names are now relative to the :imagedir: attribute if set.
The canvas keyword can be used instead of background for the same effect. 
[%notitle]
== The Great Goat

image::https://upload.wikimedia.org/wikipedia/commons/b/b2/Hausziege_04.jpg[canvas,size=contain]

As you can see, you can use a URL to specify your image resource too.

Background videos

A background video for a slide can be specified using the background-video element attribute.

[background-video="https://my.video/file.mp4",background-video-loop=true,background-video-muted=true]
== Nice background!

For convenience background-video-loop and background-video-muted attributes are mapped to loop and muted options which can be specified with options="loop,muted".

For example:

[background-video="https://my.video/file.mp4",options="loop,muted"]
== Nice background!

See the relevant reveal.js documentation for details. Note that the data- prefix is not required in asciidoc files.

Background iframes

The background can be replaced with anything a browser can render in an iframe using the background-iframe reveal.js feature.

[%notitle,background-iframe="https://www.youtube.com/embed/LaApqL4QjH8?rel=0&start=3&enablejsapi=1&autoplay=1&loop=1&controls=0&modestbranding=1"]
== a youtube video

See the relevant reveal.js documentation for details.

Slide Transitions

[transition=zoom, %notitle]
== Zoom zoom

This slide will override the presentation transition and zoom!

[transition-speed=fast, %notitle]
== Speed

Choose from three transition speeds: default, fast or slow!

See the relevant reveal.js documentation for details.

Fragments

== Slide Four

[%step]
* this
* is
* revealed
* gradually

Slide Four has bullets that are revealed one after the other. This is what reveal.js calls fragments. Applying the step option or role on a list ([%step] or [.step]) will do the trick. Here is the relevant reveal.js documentation on the topic. Note that only fade-in is supported for lists at the moment.

Stretch class attribute

Reveal.js supports a special class that will give all available screen space to an HTML node. This class element is named stretch.

Sometimes it’s desirable to have an element, like an image or video, stretch to consume as much space as possible within a given slide.

To apply that class to block simply use asciidoctor’s class assignment:

[.stretch]

See reveal.js documentation on stretching elements.

Videos

In addition to background videos, videos can be inserted directly into slides. The syntax is the standard asciidoc video block macro syntax.

== Trains, we love trains!

video::kZH9JtPBq7k[youtube, start=34, options=autoplay]

By default videos are given as much space as possible. To override that behavior use the width and height named attributes.

Syntax highlighting

== Slide Five

Uses highlighted code

----
print "Hello World"
----

revealjs uses highlight.js to do its syntax highlighting by default. By default [source] blocks and blocks delimited by ---- will be highlighted. An explicit [listing] block will not be highlighted. highlight.js does language auto-detection but using the language="..." attribute will hint the highlighter. For example this will highlight this source code as Perl:

== Slide Five

[source,perl]
----
print "$0: hello world\n"
----
Currently revealjs uses a rather old version of highlight.js that does not handle callouts correctly. To fix this download a current version of highlight.js and copy it to reveal.js/plugin/highlight/highlight.js.

Alternatively, you can use Coderay or Pygments as the highlighter. These handle callouts correctly.

To use Coderay:

= Title slide
:source-highlighter: coderay

To use Pygments:

= Title slide
:source-highlighter: pygments

Vertical slides

== Slide Six

Top slide

=== Slide Six.One

This is a vertical subslide

Slide Six uses the vertical slide feature of reveal.js. Slide Six.One will be rendered vertically below Slide Six. Here is the relevant reveal.js documentation on that topic.

Title slide customization

The title slide is customized via Asciidoc attributes. These are the global variable assigned at the top of a document under the lead title that look like this: :name: value.

This back-end supports changing the color, image, video, iframe and transitions of the title slide.

Read the relevant reveal.js documentation to understand what attributes need to be set. Keep in mind that for title slides you must replace data- with title-slide-.

Here is an example:

Unresolved directive in https://cdn.rawgit.com/asciidoctor/asciidoctor-reveal.js/v1.0.1/README.adoc - include::test/title-slide-image.adoc[]

The title slide is also added a title CSS class to help with template customization.

Content meant for multiple back-ends

Some content can be created with both slides and book in mind.

To mark slides split points you can use preprocessor conditionals combined with back-end declaration. Breaking points are set using slides with no title === ! wrapped in a conditional: ifdef::backend-revealjs[=== !]. In the end, the whole document has to be compiled with the back-end option: -b revealjs

For example:

== Main section

=== Sub Section

Small +
Multiline +
intro

. very
. long
. list
. of
. items

ifdef::backend-revealjs[=== !]

Some overview diagram

ifdef::backend-revealjs[=== !]

Detailed view diagram

CSS override

If you use the :customcss: document attribute, a CSS file of the name given in the attribute is added to the list of CSS resources loaded by the rendered HTML. Doing so, you can then easily override specific elements of your theme per presentation.

For example, to do proper position-independent text placement of a title slide with a specific background you can use:

.reveal section.title h1 {
    margin-top: 2.3em;
}

.reveal section.title small {
    margin-top: 15.3em;
    font-weight: bold;
    color: white;
}

If the :customcss: attribute value is empty then asciidoctor-revealjs.css is the CSS resource that the presentation is linked to.

Slide state

Reveal.js supports a data-state tag that can be added on slides which gets rendered into <section> tags. In AsciiDoc the data-state can be applied to a slide by adding a state attribute to a section like this:

[state=topic]
== Epic Topic

That state can be queried from Javascript or used in CSS to apply further customization to your slide deck. For example, by combining this feature with the CSS override one, you can alter fonts for specific pages with this CSS:

@import 'https://fonts.googleapis.com/css?family=Baloo+Bhai';

section[data-state="topic"] h2 {
    font-family: 'Baloo Bhai', cursive;
    font-size: 4em;
}

About Jade Templates

/templates/jade directory contains jade template files they are ported from /templates/slim templates. These templates were written to support reveal.js backend for Asciidoctor.js environment that is currently using in AsciidocFX editor. You can look at the demo.

reveal.js Options

There are some attributes that can be set at the top of the document which they are specific of revealjs backend.

Default settings are based on reveal.js default settings.
Attribute Value(s) Description

:revealjs_theme:

beige, black, league, night, serif, simple, sky, solarized, white

Chooses one of reveal.js' built-in themes.

:revealjs_customtheme:

<file|URL>

Overrides CSS with given file or URL. Default is disabled.

:highlightjs-theme:

<file|URL>

Overrides highlight.js CSS style with given file or URL. Default is built-in lib/css/zenburn.css.

:revealjsdir:

<file|URL>

Overrides reveal.js directory. Example: ../reveal.js or https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.3.0

:revealjs_controls:

true, false

Display controls in the bottom right corner.

:revealjs_progress:

true, false

Display a presentation progress bar.

:revealjs_slideNumber:

true, false

Display the page number of the current slide.

:revealjs_history:

true, false

Push each slide change to the browser history.

:revealjs_keyboard:

true, false

Enable keyboard shortcuts for navigation.

:revealjs_overview:

true, false

Enable the slide overview mode.

:revealjs_touch:

true, false

Enables touch navigation on devices with touch input.

:revealjs_center:

true, false

Vertical centering of slides.

:revealjs_loop:

true, false

Loop the presentation.

:revealjs_rtl:

true, false

Change the presentation direction to be RTL.

:revealjs_fragments:

true, false

Turns fragments on and off globally.

:revealjs_embedded:

true, false

Flags if the presentation is running in an embedded mode (i.e., contained within a limited portion of the screen).

:revealjs_autoSlide:

<integer>

Delay in milliseconds between automatically proceeding to the next slide. Disabled when set to 0 (the default). This value can be overwritten by using a data-autoslide attribute on your slides.

:revealjs_autoSlideStoppable:

true, false

Stop auto-sliding after user input.

:revealjs_mouseWheel:

true, false

Enable slide navigation via mouse wheel.

:revealjs_hideAddressBar:

true, false

Hides the address bar on mobile devices.

:revealjs_previewLinks:

true, false

Opens links in an iframe preview overlay.

:revealjs_transition:

none, fade, slide, convex, concave, zoom

Transition style.

:revealjs_transitionSpeed:

default, fast, slow

Transition speed.

:revealjs_backgroundTransition:

none, fade, slide, convex, concave, zoom

Transition style for full page slide backgrounds.

:revealjs_viewDistance:

<integer>

Number of slides away from the current that are visible. Default: 3

:revealjs_parallaxBackgroundImage:

<file|URL>

Parallax background image. Defaults to none

:revealjs_parallaxBackgroundSize:

<CSS size syntax>

Parallax background size (accepts any CSS syntax). Defaults to none

If you want to build a custom theme or customize an existing one you should look at the reveal.js theme documentation and use the revealjs_customtheme AsciiDoc attribute to activate it.

Minimum Requirements

  • asciidoctor 1.5.4

Copyright © 2012-2016 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

See the LICENSE file for details.

Stay Connected

If you encounter a bug or need additional reveal.js features ported to this converter, visit the issue tracker and file an issue.

If you have questions or would like to help develop this project, please join the Asciidoctor discussion list.