reveal.js Backend for Asciidoctor

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

Usage Instructions

1. Ensure Asciidoctor, Slim and their dependencies are installed:

   $ gem install asciidoctor tilt thread_safe
     gem install slim --version 2.1.0

   Warning

   We recommend using Slim 2.1.0 until issue #8 is resolved.

2. Clone asciidoctor/asciidoctor-reveal.js to get templates for rendering presentation HTML:

   $ git clone git://github.com/asciidoctor/asciidoctor-reveal.js.git

3. Edit CONTENT_FILE ( *.adoc or *.ad or …​):

   • Slides & content per slide

   • (Optional) Set presentation options at top of CONTENT_FILE. The options available & their values will depend on presentation library (some examples below).

     :${Attribute}: ${Value}

4. Generate HTML from the Asciidoctor templates

   1. Command Line:

      $ asciidoctor -T templates/slim CONTENT_FILE

   2. Build Script: use Ruby, JavaScript, Gradle or your favorite build tool/script with presentation options

5. Copy or clone presentation library (to output destination/branch)

   $ git clone -b 3.0.0 git://github.com/hakimel/reveal.js.git

Note	If you want to use reveal.js 2, please switch to the reveal.js-2.x branch.

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.

Source Examples

Let’s see some examples of revealjs backend features:

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

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

Is very yellow

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

== 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 upstream documentation on the topic. Note that only fade-in is supported for lists at the moment.

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

Note	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

== 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 upstream documentation on that topic.

Note	The reveal.js backend only supports level 1 (==) and level 2 (===) sections. Level 3 sections are not supported and will not render correctly.

reveal.js Options

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

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
: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 documentation and use the revealjs_customtheme AsciiDoc attribute to activate it.