Asciidoctor Backends

This repository hosts an assortment of backends (i.e., templates) for Asciidoctor, a pure Ruby port of the AsciiDoc markup language.

In this repository, you’ll find replicas of both the html5 and docbook45 backends from AsciiDoc (and Asciidoctor) written in both Haml and Slim, as well as backends for generating HTML5 presentations from AsciiDoc.

General Usage Instructions

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

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

   Warning

   The Slim-based templates are not yet compatible with Slim 3.

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

   $ git clone git://github.com/asciidoctor/asciidoctor-backends.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 Asciidoctor templates:

   1. Command Line:

      $ asciidoctor -T TEMPLATE_DIRECTORY ${options} 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 PRESENTATION_LIBRARY

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.

Table 1. Existing Backends Templates

Backend	PRESENTATION_LIBRARY	TEMPLATE_DIRECTORY
deck.js	git://github.com/imakewebthings/deck.js.git	asciidoctor-backends/haml/deckjs
reveal.js	git://github.com/hakimel/reveal.js.git	replaced by: asciidoctor/asciidoctor-reveal.js
DZSlides	git://github.com/paulrouget/dzslides.git	asciidoctor-backends/slim/dzslides
Bespoke.js	git://github.com/markdalgleish/bespoke.js	asciidoctor-backends/slim/bespokejs

Note	Some backends may be broken out into new repositories in order to manage releases independently (and potentially publish separate gems). Aggregation of those releases back into this project may be delayed.

Examples

deck.js Backend

The deck.js backend is a collection of Haml templates which transform an AsciiDoc document to HTML5 slides animated by deck.js.

deck.js Notes

• Follow the "General Usage Instructions", replacing PRESENTATION_LIBRARY and TEMPLATE_DIRECTORY with the corresponding values from Table 1 above.

• If you are planning to split your slides you also need to copy to extensions directory the deck.split.js file which can be downloaded from GitHub

• Also if you want to use the fullscreen photo feature you must create an images directory.

deck.js Source Examples

Let’s see some examples of deckjs backend features:

= Title Slide
Presenter Name

== Slide One

Foo

Bar

World

[canvas-image="./images/cosplay.jpg"]
== Slide Two

[role="canvas-caption", position="center-up"]
Hello World - Good Bye Cruel World

In previous snippet we are creating a slide without a title (Slide One will not be shown), but a fullscreen image as background will be embedded, and centered at top of the slide and over the image the message “Hello World - Good Bye Cruel World”.

Some things to consider:

• canvas-image attribute receives as parameter the location of image we want to use and always must go before section.

• if you are planning to add a message over the image, you can do it as usually, but probably won’t be read good, using position attribute which positions text into the slide (bottom-left, top-left, bottom-right, top-right, center-up, center-down) and canvas-caption role will improve so much how text is rendered.

== Another Slide

[options="step"]
That's all.

[options="step"]
My Folks

In previous example we are creating one slide which instead of showing both paragraphs at the same time, will be presented each time you try to go to next slide.

And the same can be applied to lists, images, quotes, code:

== Yet Another Slide

[options="step"]
* A
* B
* C

In this case each bullet will appear to screen each time you try to go to next slide.

Warning

The original deckjs backend for AsciiDoc used the option name incremental instead of step. We’ve changed it here to save you some typing :)

deck.js Options

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

ATTRIBUTE	Value(s)	Description
:deckjs_theme:	none, web-2.0, swiss, neon	where you set the deck.js theme.
:deckjs_transition:	none, horizontal-slide, vertical-slide, fade	where you set the kind of transition.
:customjs:	<javascript folder>	where you set a custom javascript file. It can be used as a deck.js custom configuration.
:customcss:	<css folder>	where you set a custom css file.
:navigation:	N/A	the presence of this attribute makes deck.js to render a back/next icons.
:status:	N/A	the presence of this attribute makes deck.js to render current slide and total number of slides.
:split:	N/A	with this attribute we are registering the deck.split.js file.

Note	You can also specify a custom stylesheet using the stylesheet attribute, which can be used to customize AsciiDoc elements like section, paragraph, images, etc…​

Stay Connected

If you need any other feature supported by deckjs to be ported to this backend, any way to make it better or you find any bug do not hesitate to open an issue.