Asciidoctor reveal.js is a converter for Asciidoctor and Asciidoctor.js that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the reveal.js presentation framework.

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

• Asciidoctor / Ruby / Bundler (See Ruby Setup)

• Asciidoctor.js / JavaScript (Node.js) / NPM (See Node / JavaScript Setup)

Right now the Asciidoctor / Ruby stack is the better tested one but with the changes in v1.1.0 they have feature parity.

Ruby Setup

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

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

Note	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

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

2. Generate HTML presentation from the AsciiDoc source

   $ bundle exec asciidoctor-revealjs \
     -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 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

Tip	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:

Create a directory to place slides. Initialize the directory to store npm packages within that directory.

$ echo {} > package.json               # eliminates warnings, use `npm init` if you prefer
$ npm i --save asciidoctor-reveal.js

Rendering the AsciiDoc into slides

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

asciidoctor-revealjs.js

// Load asciidoctor.js and asciidoctor-reveal.js
var asciidoctor = require('asciidoctor.js')();
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); // <b class="conum">(1)</b>

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

presentation.adoc

= Title Slide

== Slide One

* Foo
* Bar
* World

To render the slides, run:

node asciidoctor-revealjs.js

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

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

= Title Slide

== Slide One

* Foo
* Bar
* World

== Slide Two

A Great Story

[.notes]
--
* tell anecdote
* make a point
--

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. Other syntax exists to create speaker notes, see examples/speaker-notes.adoc.

Starting with Reveal.js 3.5 speaker notes supports configurable layouts:

Speaker notes are opened by pressing s. With Reveal.js 3.5 they require a webserver to work. This limitation is not present in 3.6. You can get a Web server running quickly with:

ruby -run -e httpd . -p 5000 -b 127.0.0.1

Then use your browser to navigate to the URL http://localhost:5000.

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

See concealed-slide-titles.adoc.

Note	conceal and notitle have the advantage that the slide still has an id so it can be linked to.

Important

Like the first page of an AsciiDoc document, the first slide is handled differently. To hide the whole slide use the :notitle: document attribute. To achieve the effect of hiding only the first slide’s title, combine the :notitle: attribute on the first slide and use [%notitle] on the second slide which will, in effect, be your first slide now.

Background Colors

Background colors for slides can be specified by two means: a classic one and one using AsciiDoc roles. See background-color.adoc for more examples.

Using AsciiDoc Roles

Using roles respects the AsciiDoc philosophy of separation of content and presentation. Colors are to be defined by CSS and the :customcss: attribute need to be used to specify the CSS file to load. To avoid clashing with existing reveal.js themes or CSS, a specific CSS class called background is expected to be present. Here is an example:

= Title
:customcss: my-css.css

[.red.background]
== Slide One

Is very red

my-css.css

section.red.background {
  background-color: red;
}

Note	The canvas keyword can be used instead of background for the same effect.

Classic

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

Note	Background images file names are now relative to the :imagesdir: attribute if set.

Note	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

Reveal.js is well integrated with highlight.js for syntax highlighting. Asciidoctor-reveal.js supports that. You can activate highlight.js syntax highlighting (disabled by default) by setting the source-highlighter document attribute as follows:

= Presentation Title
// [...] other document attributes
:source-highlighter: highlightjs

Once enabled you can write code blocks as usual:

== Slide Five

Uses highlighted code

[source, python]
----
print "Hello World"
----

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"
----

Note

Alternatively, you can use Coderay or Pygments as syntax highlighters if you are using the Asciidoctor/Ruby/Bundler toolchain (not Asciidoctor.js/Javascript/NPM). Check the examples/ directory for examples and notes about what needs to be done for them to work. They are considered unsupported by the asciidoctor-reveal.js project.

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.

Asciidoctor-reveal.js specific roles

Roles are usually applied with the following syntax where the important-text CSS class would be applied to the slide title in the generated HTML:

[.important-text]
== Slide Title

* Some
* Information

Or

[role="important-text"]
== Slide Title

* Some
* Information

See Asciidoctor’s documentation for more details.

Image specific note

In addition to the existing attributes to position images, roles can be used as well. However, the shorthand syntax (.) doesn’t work in the image macro arguments but must be used above with the angle bracket syntax. See images.adoc for examples.

Here is a list of supported roles:

right

Will apply a float: right style to the affected block

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

See title-slide-image.adoc.

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

Content meant for multiple converters

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

To mark slides split points you can use preprocessor conditionals combined with a backend 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 backend 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;
}

Admonitions

Asciidoctor font-based admonitions are supported. Make sure to add the following attribute to your document:

:icons: font

Here is an example slide:

== But first

WARNING: This presentation is dangerous!

Here are details about Asciidoctor’s Admonition icons support.

Reveal.js Options

Some attributes can be set at the top of the document that are specific to the reveal.js converter. They use the same name as in the reveal.js project except that they are prepended by revealjs_ and case doesn’t matter. They are applied in the document template.

Note	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.7.0. Default is reveal.js/ unless in a Node.js environment where it is node_modules/reveal.js/.
:revealjs_controls:	true, false	Display presentation control arrows
:revealjs_controlsTutorial:	true, false	Help the user learn the controls by providing hints, for example by bouncing the down arrow when they first encounter a vertical slide
:revealjs_controlsLayout:	edges, bottom-right	Determines where controls appear, "edges" or "bottom-right"
:revealjs_controlsBackArrows:	faded, hidden, visible	Visibility rule for backwards navigation arrows; "faded", "hidden" or "visible"
:revealjs_progress:	true, false	Display a presentation progress bar.
:revealjs_slideNumber:	true, false, h.v, h/v, c, c/t	Display the page number of the current slide. true will display the slide number with default formatting. Additional formatting is available: h.v horizontal . vertical slide number (default) h/v horizontal / vertical slide number c flattened slide number c/t flattened slide number / total slides
:revealjs_showSlideNumber:	all, speaker, print	Control which views the slide number displays on using the "showSlideNumber" value: all show on all views (default) speaker only show slide numbers on speaker notes view print only show slide numbers when printing to PDF
: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_fragmentInURL:	true, false	Flags whether to include the current fragment in the URL, so that reloading brings you to the same fragment position
: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_help:	true, false	Flags if we should show a help overlay when the questionmark key is pressed
:revealjs_showNotes:	true, false	Flags if speaker notes should be visible to all viewers
:revealjs_autoPlayMedia:	null, true, false	Global override for autolaying embedded media (video/audio/iframe) null Media will only autoplay if data-autoplay is present true All media will autoplay, regardless of individual setting false No media will autoplay, regardless of individual setting
: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_autoSlideMethod:	Reveal.navigateNext	Use this method for navigation when auto-sliding
:revealjs_defaultTiming:	<integer>	Specify the average time in seconds that you think you will spend presenting each slide. This is used to show a pacing timer in the speaker view. Defaults to 120
: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. Add data-preview-link and data-preview-link="false" to customise each link individually
: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
:revealjs_parallaxBackgroundHorizontal:	<Number of pixels>	Number of pixels to move the parallax background per slide Calculated automatically unless specified Set to 0 to disable movement along an axis
:revealjs_parallaxBackgroundVertical:	<Number of pixels>	Number of pixels to move the parallax background per slide Calculated automatically unless specified Set to 0 to disable movement along an axis
:revealjs_display:	<a valid CSS display mode>	The display mode that will be used to show slides. Defaults to block
:revealjs_width:	<pixels|percentage unit>	Independent from the values, the aspect ratio will be preserved when scaled to fit different resolutions. Defaults to 960
:revealjs_height:	<pixels|percentage unit>	See :revealjs_width:. Defaults to 700
:revealjs_margin:	<percentage value>	Factor of the display size that should remain empty around the content. Defaults to 0.1

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.

Default plugins

By default, generated presentations will have the following reveal.js plugins enabled:

• plugin/zoom-js/zoom.js

• plugin/notes/notes.js

All these plugins are part of the reveal.js distribution.

To enable or disable a built-in plugin, it is possible to set the revealjs_plugin_[plugin name] attribute to enable or disable.

For example, to disable all the default plugins set the following document attributes:

:revealjs_plugin_zoom: disabled
:revealjs_plugin_notes: disabled

reveal.js ships with a plugin that allows to create a PDF from a slide deck. To enable this plugin, set the revealjs_plugin_pdf attribute.

:revealjs_plugin_pdf: enabled

When the plugin is enabled and you run your presentation in a browser with ?print-pdf at the end of the URL, you can then use the default print function to print the slide deck into a PDF document.

Tip	To work properly, this plugin requires a Chrome-based browser.

Additional plugins

Additional reveal.js plugins can be installed and activated using AsciiDoc attributes and external javascript files.

1. Extract the plugin files in a directory

2. Create a Javascript file that will contain the Javascript statements to load the plugin (only one required even if you are using several plugins)

3. Add a :revealjs_plugins: attribute to point to that Javascript file

4. (Optional) Add a :revealjs_plugins_configuration: attribute to point to a Javascript file that configures the plugins you use

Looking at the example provided in the repository will provide guidance: AsciiDoc source, Plugin Loader, Plugin Configuration.

Read the relevant reveal.js documentation to understand more about reveal.js plugins. A list of existing reveal.js plugins is also maintained upstream.

Minimum Requirements

Our requirements are expressed in our packages and by our dependencies. Basically, all you need is the package manager of the flavor of Asciidoctor-Reveal.js you are interested to run:

• With Ruby / Bundler: A recent Ruby and Bundler

• With Javascript (Node.js) / NPM: a recent Node.js environment

If you need more details about our dependencies check out Asciidoctor dependencies:

• With Ruby / Bundler: Asciidoctor 1.5.6

• With Javascript (Node.js) / NPM: Asciidoctor.js 1.5.6

Contributing

Interested in contributing? We are interested! Developer-focused documentation is over here.

Copyright and Licensing

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