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.

Table of Contents

• Prerequisites
• Rendering the AsciiDoc into slides
• Some Examples
  • Basic presentation with speaker notes
  • Background colors
  • Fragments
  • Syntax highlighting
  • Vertical slides
  • Slides without titles
• About Jade Templates
• reveal.js Options
• Minimum Requirements
• Copyright and Licensing

Prerequisites

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

   $ gem install asciidoctor tilt thread_safe slim

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

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

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

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

Rendering the AsciiDoc into slides

1. Create content in a file (*.adoc, *.ad, etc.). See examples in Some Examples section to get started or files in test/.

2. Generate HTML presentation from the Asciidoctor templates

   $ asciidoctor -T templates/slim CONTENT_FILE

Note	If you want to use reveal.js 2, please switch your asciidoctor-reveal.js repo 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.

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

Background colors

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.

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

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

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

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

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:

link:test/concealed-slide-titles.adoc[role=include]

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

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.

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.

Minimum Requirements

• asciidoctor 1.5.0

Copyright and Licensing

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.