= Reveal.js converter for Asciidoctor
Olivier Bilodeau <https://github.com/obilodeau[@obilodeau]>; Guillaume Grossetie <https://github.com/mogztter[@mogztter]>; Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Rahman Usta <https://github.com/rahmanusta[@rahmanusta]>; Charles Moulliard <https://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: https://github.com/asciidoctor/asciidoctor-reveal.js
:uri-asciidoctor: https://github.com/asciidoctor/asciidoctor
:uri-asciidoctorjs: https://github.com/asciidoctor/asciidoctor.js
:uri-revealjs-home: http://lab.hakim.se/reveal-js/
:uri-revealjs-gh: https://github.com/hakimel/reveal.js
:uri-nodejs-download: https://nodejs.org/en/download/

ifdef::env-github[]
image:https://travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=https://travis-ci.org/asciidoctor/asciidoctor-reveal.js]
image:http://img.shields.io/gem/v/asciidoctor-revealjs.svg[gem, link=https://rubygems.org/gems/asciidoctor-revealjs]
image:http://img.shields.io/npm/v/asciidoctor-reveal.js.svg[npm, link=https://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}[Asciidoctor] and {uri-asciidoctorjs}[Asciidoctor.js] that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the {uri-revealjs-home}[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.

ifeval::['{branch}' == 'master']
NOTE: You're viewing the documentation for the upcoming release.
If you're looking for the documentation for an older release, please refer to one of the following branches: +
{uri-project-repo}/tree/maint-1.0.x#readme[1.0.x]
&hybull;
{uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with RevealJS 2.x)
endif::[]


== 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 https://github.com/obilodeau/presentation-revealjs-starter[starter repository] and follow instructions there.

For more complete instructions, read on.


=== Prerequisites

. Install http://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 '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.
+
. 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.6.0 --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 CONTENT_FILE.adoc

TIP: If you are using https://pages.github.com/[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 {uri-nodejs-download}[Node.js] on your machine.

=== Install

Using npm:

 $ 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
[source, javascript]
----
// Load asciidoctor.js and asciidoctor-reveal.js
var asciidoctor = require('asciidoctor.js')();
require('asciidoctor-reveal.js');

// Convert the document 'presentation.adoc' using the reveal.js converter
var attributes = {'revealjsdir': 'node_modules/reveal.js@'};
var options = {safe: 'safe', backend: 'revealjs', attributes: attributes};
asciidoctor.convertFile('presentation.adoc', options); // <1>
----
<1> Creates a file named `presentation.html` (in the directory where command is run)

.presentation.adoc
[source, asciidoc]
----
= 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-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

[source, asciidoc]
----
= 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 {uri-revealjs-gh}#speaker-notes[speaker notes].

Starting with Reveal.js 3.5 speaker notes supports configurable layouts:
image:https://cloud.githubusercontent.com/assets/629429/21808439/b941eb52-d743-11e6-9936-44ef80c60580.gif[]

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 open your browser at: 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

ifeval::[{safe-mode-level} >= 20]
See <<examples/concealed-slide-titles.adoc#,concealed-slide-titles.adoc>>.
endif::[]
ifeval::[{safe-mode-level} < 20]
Here is an example of the three techniques in action:

.concealed-slide-titles.adoc
[source,asciidoc]
....
include::examples/concealed-slide-titles.adoc[lines=5..-1]
....
endif::[]

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


=== Background colors

[source, asciidoc]
----
[background-color="yellow"]
== Slide Three

Is very yellow
----

Slide Three applies the attribute {uri-revealjs-gh}#slide-backgrounds[data-background-color] to the `reveal.js` <section> tag.
Anything accepted by CSS color formats works.


=== Background images

[source, asciidoc]
----
[%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 {uri-revealjs-gh}#image-backgrounds[relevant reveal.js documentation] for details.

NOTE: Background images file names are now relative to the `:imagedir:` attribute if set.

NOTE: The `canvas` keyword can be used instead of `background` for the same effect.

[source, asciidoc]
----
[%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]
=== Background videos

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

[source, asciidoc]
----
[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:

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

See {uri-revealjs-gh}#video-backgrounds[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.

[source, asciidoc]
----
[%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 {uri-revealjs-gh}#iframe-backgrounds[the relevant reveal.js documentation] for details.


=== Slide Transitions

[source, asciidoc]
----
[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 {uri-revealjs-gh}#slide-transitions[the relevant reveal.js documentation] for details.


=== Fragments

[source, asciidoc]
----
== Slide Four

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

Slide Four has bullets that are revealed one after the other.
This is what `reveal.js` calls http://lab.hakim.se/reveal-js/#/fragments[fragments].
Applying the step option or role on a list (`[%step]` or `[.step]`) will do the trick.
Here is {uri-revealjs-gh}#fragments[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 {uri-revealjs-gh}#stretching-elements[reveal.js documentation on stretching elements].


=== Videos

In addition to <<Background videos,background videos>>, videos can be inserted directly into slides.
The syntax is the standard http://asciidoctor.org/docs/user-manual/#video[asciidoc video block macro] syntax.

[source, asciidoc]
----
== 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 https://highlightjs.org/[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:

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

Once enabled you can write code blocks as usual:

[source, asciidoc]
....
== 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:

[source, asciidoc]
....
== Slide Five

[source,perl]
----
print "$0: hello world\n"
----
....

[NOTE]
Alternatively, you can use http://coderay.rubychan.de[Coderay] or http://pygments.org[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

[source, asciidoc]
....
== 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 {uri-revealjs-gh}#markup[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 converter supports changing the color, image, video, iframe and
transitions of the title slide.

Read {uri-revealjs-gh}#slide-backgrounds[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-`.

ifeval::[{safe-mode-level} >= 20]
See <<examples/title-slide-image.adoc#,title-slide-image.adoc>>.
endif::[]
ifeval::[{safe-mode-level} < 20]
Here is an example:

.title-slide-image.adoc
[source,asciidoc]
....
include::examples/title-slide-image.adoc[lines=5..-1]
....
endif::[]

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:

[source, asciidoc]
----
== 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:

[source, css]
----
.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 {uri-revealjs-gh}#slide-states[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:

[source, asciidoc]
----
[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:

[source, 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 http://asciidoctor.org/docs/user-manual/#admonition[admonitions] are supported.
Make sure to add the following attribute to your document:

[source, asciidoc]
----
:icons: font
----

Here is an example slide:

[source, asciidoc]
----
== But first

WARNING: This presentation is dangerous!
----

Here are details about Asciidoctor's http://asciidoctor.org/docs/user-manual/#admonition-icons[Admonition icons] support.


== Reveal.js Options

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

NOTE: Default settings are based on `reveal.js` default settings.

[cols="1m,1,2"]
|===
|Attribute |Value(s) |Description

|:revealjs_theme:
|beige, *black*, league, night, serif, simple, sky, solarized, white
|Chooses one of reveal.js`' {uri-revealjs-gh}#theming[built-in themes].

|:revealjs_customtheme:
|<file\|URL>
|Overrides CSS with given file or URL.
Default is disabled.

|:highlightjs-theme:
|<file\|URL>
|Overrides https://highlightjs.org[highlight.js] CSS style with given file or URL.
Default is built-in [path]_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
{uri-revealjs-gh}/blob/master/css/theme/README.md[reveal.js
theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to
activate it.

== Minimum Requirements

* asciidoctor 1.5.6

== Copyright and Licensing

Copyright (C) 2012-2018 {authors} and the Asciidoctor Project.
Free use of this software is granted under the terms of the MIT License.

ifdef::env-github,env-browser[See the <<LICENSE#,LICENSE>> file for details.]