How do I create slides with the Deck.js backend?

Deck.js Backend for Asciidoctor

The Deck.js backend for Asciidoctor is a collection of Haml templates that transform an AsciiDoc document to HTML 5-based slides animated by Deck.js.

Ruby Gem Requirements

The Asciidoctor Deck.js backend requires the following Ruby gems:

asciidoctor
tilt
haml

To determine what gems are installed on your system, open a terminal window and type:

$ gem list --local

A list of installed gems will be returned.

If you’re missing the asciidoctor, tilt, or haml gems, install them from the command-line with gem install.

$ gem install asciidoctor tilt haml

To learn more about installing the Asciidoctor toolchain, read the Installing the Toolchain or Installing Asciidoctor on OS X guides.

Backend and Deck.js Installation

Download or git clone the asciidoctor-deck.js repository.

$ git clone https://github.com/asciidoctor/asciidoctor-deck.js

Create a directory named deck.js inside your working directory (i.e. where your AsciiDoc document resides).
Download and extract the Deck.js archive or git clone the Deck.js repository into the deck.js directory you created in step 2.
```
$ git clone git://github.com/imakewebthings/deck.js.git
```
If you plan to split your slides, download the deck.split.js extension and extract it into the deck.js/extensions/split directory.
If you want to add the blank screen control, download the deck.js-blank extension and extract it into the deck.js/extensions/blank directory.
If you want to use the fullscreen photo feature, create an images directory in your working directory.

Document Attributes

There are a number of document attributes specific to the deckjs backend.

Table 1. `deckjs` backend document attributes
Attribute	Description	Example
:backend: deckjs	Activates the Deck.js backend to render the document as a Deck.js presentation	`:backend: deckjs`
:deckjs_theme: <theme>	Sets the Deck.js theme to neon, swiss or web-2.0	`:deckjs_theme: web-2.0`
:deckjs_transition: <type>	Sets the transition style to horizontal-slide, vertical-slide or fade	`:deckjs_transition: fade`
:customjs: <javascript location>	Sets a custom javascript file; can be used as a Deck.js custom configuration	`:customjs: <javascript location>`
:customcss: <css location>	Sets a custom css file	`:customcss: <css location>`
:blank:	Registers the third-party blank module for toggling the visibility of the slide using the `b` key	`:blank:`
:goto:	Opens a floating control when the `g` key is pressed to advance to a specific slide	`:goto:`
:menu:	Toggle to and from a grid layout overview of all the slides by pressing the `m` key	`:menu:`
:navigation:	Renders clickable previous and next navigation icons on the slides	`:navigation:`
:status:	Renders the current slide number and total number of slides at the bottom of each slide	`:status:`
:split:	Registers the third-party split module for use in the presentation	`:split:`
:toc:	Includes a table of contents that can be toggled by pressing the `t` key	`:toc:`

You can also specify a custom stylesheet using the stylesheet attribute, which customizes AsciiDoc elements like section, paragraph, images, etc. Learn more about the stylesheet attribute in the guide How do I use the Asciidoctor stylesheet factory to produce custom themes?

The attributes described in the table above are set in the header of your document.

Header with deckjs backend attributes

= Presentation Title
Presenter Name
:backend: deckjs
:deckjs_theme: web-2.0
:deckjs_transition: horizontal-slide
:navigation:

Slide Syntax Examples

Structuring a slideshow and writing the slide content uses the same syntax as a typical AsciiDoc document, with a few added features.

Let’s see some examples of the deckjs backend features:

Slide titles and background images

= Title of Presentation (1)
Presenter Name
:backend: deckjs
:deckjs_transition: fade
:navigation:

== Title of Slide One (2)

This is the first slide after the title slide.

[canvas-image=images/example.jpg] (3)
== Slide Two's Title will not be displayed (4)

[.canvas-caption, position=center-up] (5)
This text is displayed on top of the example.jpg image.

1	The presentation title and author’s name will be displayed on the title slide.
2	Each new slide is designated by a level 1 section title (`==`).
3	The `canvas-image` attribute embeds a fullscreen image as a slide background. Position the attribute above the title of the slide you want the image applied to.
4	When the `canvas-image` attribute is applied to a slide, that slide’s title will not be displayed.
5	`canvas-caption` applies a colored box around the caption text. `position` specifies the location of the caption block (bottom-left, top-left, bottom-right, top-right, center-up, center-down)

Stepped paragraphs, lists, and blocks

== Stepped paragraphs

[%step]
This paragraph is displayed first.

[%step]
Then this paragraph is displayed when the _Next_ arrow is clicked.

== Stepped list items

[%step]
* A bullet is displayed each time the _Next_ arrow is clicked.
* B
* C

== Stepped blocks

[%step]
--
Block one
--

[%step]
--
Block two
--

The step option reveals each paragraph, bullet, etc. separately each time you click the Next arrow.

The original AsciiDoc deckjs backend for the AsciiDoc processor used the option incremental instead of step. We’ve changed it to step in order to save you some typing.

Split

= Presentation Title
Presenter Name
:backend: deckjs
:split: (1)

== This Slide is Split

This Slide will act like

<<< (2)

three individual slides with the same title

<<<

once the document is rendered.

1	To create multiple, consecutive slides with the same title, set the `split` attribute in the document header.
2	Then, within a slide, insert `<<<` to specify the slide breaks.

Rendering

To render your presentation as HTML5, execute the command:

$ asciidoctor -T ../asciidoctor-deck.js/templates/haml presentation.adoc

The command -T (--template-dir) tells the Asciidoctor processor to override the built-in converter.
Directly after -T is the path to where you saved or cloned the asciidoctor-deck.js repository containing the templates for the deckjs backend (step 1 under the installation section).

Further information about rendering documents with Asciidoctor is available in the guide How do I render a document?

Stay Connected

If you encounter a bug or need additional Deck.js features ported to Asciidoctor’s deckjs backend, visit the asciidoctor-deck.js issue tracker and file an issue.

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