Asciidoctor reveal.js is a converter for Asciidoctor and Asciidoctor.js that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the reveal.js presentation framework.
|
💡
|
Want to see some example presentations, see Showcase Presentations |
There are four main technology stacks that can convert AsciiDoc into HTML5 / reveal.js:
-
Asciidoctor / Ruby / Bundler (See Ruby Setup)
-
Asciidoctor.js / JavaScript (Node.js) / npm (See Node / JavaScript Setup)
-
Standalone Executable (See Standalone Executable)
-
AsciidoctorJ / JVM / Maven (See this project)
|
📎
|
You’re viewing the documentation for an upcoming release.
If you’re looking for the documentation for the current release or an older one, please click on the appropriate link below: 4.0.1 (latest from 4.x series) ⁃ 3.1.0 (latest from 3.x series) ⁃ Unversioned pre-release (compatible with reveal.js 2.x) |
- Ruby Setup
- Node / JavaScript Setup
- Standalone Executable
- Syntax Examples
- Basic presentation with speaker notes
- Slides without titles
- Background Colors
- Background images
- Background videos
- Background iframes
- Slide Transitions
- Fragments
- Stretch class attribute
- Videos
- Syntax highlighting
- Vertical slides
- Columns layout
- Asciidoctor reveal.js specific roles
- Asciidoctor reveal.js specific attributes
- Title slide customization
- Content meant for multiple converters
- CSS override
- Slide state
- Admonitions
- Supplemental Content with Docinfo
- Reveal.js Options
- Minimum Requirements
- reveal.js Compatibility Matrix
- Asciidoctor.js Compatibility Matrix
- Showcase Presentations
- Contributing
- Copyright and Licensing
|
📎
|
To ensure repeatability, we recommend that you manage your presentation projects using bundler. |
-
Install 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
|
📎
|
These instructions should be repeated for every presentation project. |
-
Create project directory
$ mkdir my-awesome-presentation $ cd my-awesome-presentation
-
Create a file named
Gemfilewith the following content:source 'https://rubygems.org' gem 'asciidoctor-revealjs' # latest released version
📎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.9.2 --depth 1 https://github.com/hakimel/reveal.js.git
-
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 \ -a revealjsdir=https://cdn.jsdelivr.net/npm/reveal.js@3.9.2 CONTENT_FILE.adoc
-
If you did the optional step of having a local reveal.js clone you can convert AsciiDoc source with
$ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc
|
💡
|
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.
|
Starting with 4.0.0 you can specify a set of custom templates to use instead of the ones provided by this project. This can help you achieve even more concise AsciiDoc syntax and integration with reveal.js at the cost of more maintenance.
To use it, add the following dependencies to your Gemfile:
gem 'tilt', '~>2.0' gem 'slim', '~>4.0'
Then install the dependencies with:
$ bundle install
The feature is activated with the --template-dir or -T option:
$ bundle exec asciidoctor-revealjs -T templates/ CONTENT_FILE.adoc
Any individual template file not provided in the directory specified on the command-line will fall back to the template provided by your version of Asciidoctor reveal.js. Refer to our templates for inspiration.
This feature hasn’t been ported to the JavaScript CLI (and API) or the standalone executables.
First you must install and configure Node on your machine.
We recommend to install the dependencies in a project directory, such as the directory where your AsciiDoc presentations are stored.
If you don’t have a package.json file in your project directory, you can create one to eliminate warnings during the installation using:
$ npm init -y
You can now install the dependencies:
$ npm i --save asciidoctor@^2.0 @asciidoctor/reveal.js
Once the dependencies are installed, verify that the asciidoctor-revealjs command is available.
On Linux and macOS, open a terminal and type:
$ npx asciidoctor-revealjs --version
On Windows, open PowerShell and type:
$ .\node_modules\.bin\asciidoctor-revealjs.cmd --version
The command should report the Asciidoctor CLI version in the terminal:
Asciidoctor.js 2.0.3 (Asciidoctor 2.0.9) [https://asciidoctor.org]
Runtime Environment (node v10.15.1 on linux)
CLI version 2.0.1If you don’t have an existing presentation, you can create a sample presentation named presentation.adoc:
= Title Slide
== Slide One
* Foo
* Bar
* WorldTo convert the sample presentation into slides, open a terminal and type:
$ npx asciidoctor-revealjs presentation.adoc
On windows, open PowerShell and type:
$ .\node_modules\.bin\asciidoctor-revealjs.cmd presentation.adoc
The above command will generate a file named presentation.html. You can open this file in a browser.
Alternatively, you can use the JavaScript API to register the converter and convert a document:
// Load Asciidoctor.js and the reveal.js converter
var asciidoctor = require('@asciidoctor/core')()
var asciidoctorRevealjs = require('@asciidoctor/reveal.js')
asciidoctorRevealjs.register()
// Convert the document 'presentation.adoc' using the reveal.js converter
var options = { safe: 'safe', backend: 'revealjs' }
asciidoctor.convertFile('presentation.adoc', options) // (1)-
Creates a file named
presentation.html(in the directory where command is run)
To execute the script, open a terminal and type:
$ node convert-slides.js
You can open the presentation.html file in your browser and enjoy!
Pre-built binary packages can be downloaded from our GitHub release page. We provide them for Windows 64-bit, Linux 64-bit and macOS 64-bit. Open an issue if your platform isn’t supported. The executables are built using the Node / JavaScript toolchain.
-
Download the executable for your platform and make it executable with
chmodor using the files properties' user interface. -
Copy or clone the reveal.js presentation framework in the directory where you will build your slidedeck. Here we do a shallow clone of the repo:
$ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git
Open a terminal where the executable is and type:
$ ./asciidoctor-revealjs --version
The command should report the Asciidoctor reveal.js and Asciidoctor CLI version in the terminal:
Asciidoctor reveal.js 3.0.1 using Asciidoctor.js 2.0.3 (Asciidoctor 2.0.9) [https://asciidoctor.org]
Runtime Environment (node v12.13.1 on linux)
CLI version 3.1.0If you don’t have an existing presentation, you can create a sample presentation named presentation.adoc:
= Title Slide
:revealjsdir: reveal.js
== Slide One
* Foo
* Bar
* WorldTo convert the sample presentation into slides, open a terminal and type:
$ ./asciidoctor-revealjs presentation.adoc
The above command will generate a file named presentation.html. You can open this file in a browser.
Let’s see some examples of revealjs backend features.
Additional examples can be found in the AsciiDoc files (.adoc) in examples/.
= Title Slide
== Slide One
* Foo
* Bar
* World
== Slide Two
A Great Story
[.notes]
--
* tell anecdote
* make a point
--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.
Other syntax exists to create speaker notes, see examples/speaker-notes.adoc.
Starting with Reveal.js 3.5 speaker notes supports configurable layouts:
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 use your browser to navigate to the URL http://localhost:5000.
There are a few ways to have no titles on slides.
-
Setting your title to
! -
Adding the
notitleoption to your slide -
Adding the
concealoption to your slide
|
📎
|
conceal and notitle have the advantage that the slide still has an id so it can be linked to.
|
|
❗
|
Like the first page of an AsciiDoc document, the first slide is handled differently.
To hide the whole slide use the :notitle: document attribute.
To achieve the effect of hiding only the first slide’s title, combine the :notitle: attribute on the first slide and use [%notitle] on the second slide which will, in effect, be your first slide now.
|
Background colors for slides can be specified by two means: a classic one and one using AsciiDoc roles. See background-color.adoc for more examples.
Using roles respects the AsciiDoc philosophy of separation of content and presentation.
Colors are to be defined by CSS and the :customcss: attribute need to be used to specify the CSS file to load.
To avoid clashing with existing reveal.js themes or CSS, a specific CSS class called background is expected to be present.
Here is an example:
= Title
:customcss: my-css.css
[.red.background]
== Slide One
Is very redsection.red.background {
background-color: red;
}|
📎
|
The canvas keyword can be used instead of background for the same effect.
|
[background-color="yellow"]
== Slide Three
Is very yellowSlide Three applies the attribute data-background-color to the reveal.js <section> tag.
Anything accepted by CSS color formats works.
[%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 relevant reveal.js documentation for details.
|
📎
|
Background images file names are now relative to the :imagesdir: attribute if set.
|
|
📎
|
The canvas keyword can be used instead of background for the same effect.
|
[%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.
A background video for a slide can be specified using the background-video element attribute.
[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:
[background-video="https://my.video/file.mp4",options="loop,muted"]
== Nice background!See the relevant reveal.js documentation for details.
Note that the data- prefix is not required in asciidoc files.
The background can be replaced with anything a browser can render in an iframe using the background-iframe reveal.js feature.
[%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 videoSee the relevant reveal.js documentation for details.
[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 the relevant reveal.js documentation for details.
== Slide Four
[%step]
* this
* is
* revealed
* graduallySlide 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 the relevant reveal.js
documentation on the topic.
Note that only fade-in is supported for lists at the moment.
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]
In addition to background videos, videos can be inserted directly into slides. The syntax is the standard asciidoc video block macro syntax.
== 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.
reveal.js is well integrated with 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:
= Presentation Title
// [...] other document attributes
:source-highlighter: highlightjsBy default, we are using a prebuilt version of Highlight.js with 34 commonly used languages hosted on https://cdnjs.com/[cdnjs]. You can load additionnal languages using the `:highlightjs-languages:` attribute: ``` // load yaml and scilab languages :highlightjs-languages: yaml, scilab ``` You can also load Highlight.js from a custom base directory (or remote URL) using the `:highlightjsdir:` attribute: ``` // load from a local path :highlightjsdir: highlight // load from jsdelivr CDN //:highlightjsdir: https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.18.0/build
Once enabled, you can write code blocks as usual:
== 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:
== Slide Five
[source,perl]
----
print "$0: hello world\n"
----|
📎
|
Alternatively, you can use Rouge, Coderay or 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.
|
== Slide Six
Top slide
=== Slide Six.One
This is a vertical subslideSlide Six uses the vertical slide feature of reveal.js.
Slide Six.One will be rendered vertically below Slide Six.
Here is the relevant reveal.js
documentation on that topic.
Inspired by Bulma, Asciidoctor reveal.js supports columns layout out-of-the-box:
[.columns]
== 2 columns
[.column]
--
* **Edgar Allen Poe**
* Sheri S. Tepper
* Bill Bryson
--
[.column]
--
Edgar Allan Poe (/poʊ/; born Edgar Poe; January 19, 1809 – October 7, 1849) was an American writer, editor, and literary critic.
--If you do not specify a size, each column will have an equal width, no matter the number of columns.
[.columns]
== 3 columns
[.column]
* Java
* **Kotlin**
[.column]
* Node
* **Deno**
[.column]
* Ruby
* **Crystal**If you want to change the size of a single column, you can use one of the following classes:
-
is-three-quarters -
is-two-thirds -
is-half -
is-one-third -
is-one-quarter -
is-full
The other columns will fill up the remaining space automatically.
You can use the following multiples of 20% as well:
-
is-four-fifths -
is-three-fifths -
is-two-fifths -
is-one-fifth
[.columns]
== Columns with size
[.column.is-one-third]
--
* **Kotlin**
* Java
* Scala
--
[.column]
--
Programming language for Android, mobile cross-platform
and web development, server-side, native,
and data science. Open source forever Github.
--The vertical alignment of columns defaults to top aligned.
Content can be centered by adding the is-vcentered class to the slide.
[.columns.is-vcentered]
== Columns Vertically Centered
[.column]
--
* Few
* Bullets
* Here
--
[.column]
image::large-image.png[]Text alignment of columns is also supported.
Text content on individual columns can be aligned with has-text-left, has-text-right and has-text-justified CSS classes.
[.columns]
== Column Text Alignment
[.column.has-text-left]
--
Something Short
Something So Long That We Need It Aligned
--
[.column.has-text-justified]
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
[.column.has-text-right]
--
Something Short
Something So Long That We Need It Aligned
--Roles are usually applied with the following syntax where the important-text CSS class would be applied to the slide title in the generated HTML:
[.important-text]
== Slide Title
* Some
* InformationOr
[role="important-text"]
== Slide Title
* Some
* InformationSee Asciidoctor’s documentation for more details.
In addition to the existing attributes to position images, roles can be used as well. However, the shorthand syntax (.) doesn’t work in the image macro arguments but must be used above with the angle bracket syntax. See images.adoc for examples.
Here is a list of supported roles:
- right
-
Will apply a
float: rightstyle to the affected block
The reveal.js feature activated by a global previewLinks: true configuration or by adding the data-preview-link HTML attribute to <a> tags can be activated by using special AsciiDoc attributes.
On links use the preview=true attribute, on images use the link_preview=true attribute and globally you can set :revealjs_previewlinks: attribute.
See links.adoc and links-preview.adoc for examples.
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 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-.
The title slide is also added a title CSS class to help with template customization.
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:
== Main section
=== Sub Section
Small +
Multiline +
intro
. very
. long
. list
. of
. items
ifdef::backend-revealjs[=== !]
Some overview diagram
ifdef::backend-revealjs[=== !]
Detailed view diagramIf 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:
.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.
Reveal.js supports a 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:
[state=topic]
== Epic TopicThat 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:
@import 'https://fonts.googleapis.com/css?family=Baloo+Bhai';
section[data-state="topic"] h2 {
font-family: 'Baloo Bhai', cursive;
font-size: 4em;
}Asciidoctor font-based admonitions are supported. Make sure to add the following attribute to your document:
:icons: fontHere is an example slide:
== But first
WARNING: This presentation is dangerous!Here are details about Asciidoctor’s Admonition icons support.
It’s possible to inject supplemental content into the output document using docinfo files. This core feature of AsciiDoc has been adapted to work with the reveal.js converter.
Currently, there are three insertion locations for docinfo content in a reveal.js document:
- head
-
content is inserted after the last child of the
<head>element - header
-
content is inserted before the first child of the
<div class="slides">element (before the slides) - footer
-
content is inserted after the last child of the
<div class="slides">element (after the slides)
The content you want to insert goes into a sibling file of the slide deck document with the following filename patterns:
- head
-
docinfo-revealjs.html - header
-
docinfo-header-revealjs.html - footer
-
docinfo-footer-revealjs.html
For example, let’s say you want to embed a tweet into your slide deck. You might inject the shared embedding JavaScript using a footer docinfo file:
<script src="https://platform.twitter.com/widgets.js"></script>You then need to set the following document attribute in the AsciiDoc header:
:docinfo: shared
When this attribute is defined, the converter will automatically read the docinfo file(s) and insert the contents into the specified location in the output document.
Some attributes can be set at the top of the document that are specific to the reveal.js converter.
They use the same name as in the reveal.js project except that they are prepended by revealjs_ and case doesn’t matter.
They are applied in the document template.
|
📎
|
Default settings are based on reveal.js default settings.
|
| Attribute | Value(s) | Description |
|---|---|---|
|
beige, black, league, night, serif, simple, sky, solarized, white |
Chooses one of reveal.js’ built-in themes. |
|
<file|URL> |
Overrides CSS with given file or URL. Default is disabled. |
|
<file|URL> |
Overrides highlight.js CSS style with given file or URL. Default is built-in lib/css/zenburn.css. |
|
<file|URL> |
Overrides reveal.js directory.
Example: ../reveal.js or
https://cdn.jsdelivr.net/npm/reveal.js@3.9.2.
Default is |
|
true, false |
Display presentation control arrows |
|
true, false |
Help the user learn the controls by providing hints, for example by bouncing the down arrow when they first encounter a vertical slide |
|
edges, bottom-right |
Determines where controls appear, "edges" or "bottom-right" |
|
faded, hidden, visible |
Visibility rule for backwards navigation arrows; "faded", "hidden" or "visible" |
|
true, false |
Display a presentation progress bar. |
|
true, false, h.v, h/v, c, c/t |
Display the page number of the current slide. true will display the slide number with default formatting. Additional formatting is available:
|
|
all, speaker, print |
Control which views the slide number displays on using the "showSlideNumber" value:
|
|
true, false |
Add the current slide number to the URL hash so that reloading the page/copying the URL will return you to the same slide |
|
true, false |
Push each slide change to the browser history. Implies |
|
true, false |
Enable keyboard shortcuts for navigation. |
|
true, false |
Enable the slide overview mode. |
|
true, false |
Enables touch navigation on devices with touch input. |
|
true, false |
Vertical centering of slides. |
|
true, false |
Loop the presentation. |
|
true, false |
Change the presentation direction to be RTL. |
|
default, linear, grid |
See https://github.com/hakimel/reveal.js/#navigation-mode for details |
|
true, false |
Randomizes the order of slides each time the presentation loads |
|
true, false |
Turns fragments on and off globally. |
|
true, false |
Flags whether to include the current fragment in the URL, so that reloading brings you to the same fragment position |
|
true, false |
Flags if the presentation is running in an embedded mode (i.e., contained within a limited portion of the screen). |
|
true, false |
Flags if we should show a help overlay when the questionmark key is pressed |
|
true, false |
Flags if speaker notes should be visible to all viewers |
|
null, true, false |
Global override for autolaying embedded media (video/audio/iframe)
|
|
null, true, false |
Global override for preloading lazy-loaded iframes
|
|
<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 |
|
true, false |
Stop auto-sliding after user input. |
|
Reveal.navigateNext |
Use this method for navigation when auto-sliding |
|
<integer> |
Specify the average time in seconds that you think you will spend presenting each slide. This is used to show a pacing timer in the speaker view. Defaults to 120 |
|
<integer> |
Specify the total time in seconds that is available to present. If this is set to a nonzero value, the pacing timer will work out the time available for each slide, instead of using the defaultTiming value. Defaults to 0 |
|
<integer> |
Specify the minimum amount of time you want to allot to each slide, if using the totalTime calculation method. If the automated time allocation causes slide pacing to fall below this threshold, then you will see an alert in the speaker notes window. Defaults to 0. |
|
true, false |
Enable slide navigation via mouse wheel. |
|
true, false |
Hide cursor if inactive |
|
<integer> |
Time before the cursor is hidden (in ms). Defaults to 5000. |
|
true, false |
Hides the address bar on mobile devices. |
|
true, false |
Opens links in an iframe preview overlay.
Add the |
|
none, fade, slide, convex, concave, zoom |
Transition style. |
|
default, fast, slow |
Transition speed. |
|
none, fade, slide, convex, concave, zoom |
Transition style for full page slide backgrounds. |
|
<integer> |
Number of slides away from the current that are visible. Default: 3. |
|
<integer> |
Number of slides away from the current that are visible on mobile devices. It is advisable to set this to a lower number than viewDistance in order to save resources. Default 3. |
|
<file|URL> |
Parallax background image. Defaults to none |
|
<CSS size syntax> |
Parallax background size (accepts any CSS syntax). Defaults to none |
|
<Number of pixels> |
Number of pixels to move the parallax background per slide
|
|
<Number of pixels> |
Number of pixels to move the parallax background per slide
|
|
<a valid CSS display mode> |
The display mode that will be used to show slides. Defaults to block |
|
<pixels|percentage unit> |
Independent from the values, the aspect ratio will be preserved when scaled to fit different resolutions. Defaults to 960 |
|
<pixels|percentage unit> |
See |
|
<percentage value> |
Factor of the display size that should remain empty around the content. Defaults to 0.1 |
|
true, false |
In PDF export, put each fragment on a separate page. Defaults to true |
|
<integer> |
In PDF export, when a slide does not fit on a single page, maximum number of pages. Defaults to 1 |
If you want to build a custom theme or customize an existing one you should
look at the
reveal.js
theme documentation and use the revealjs_customtheme AsciiDoc attribute to
activate it.
Follow reveal.js' documentation for PDF export. We would add that we have successfully used PDF export without the requirement of a Web server.
By default, generated presentations will have the following reveal.js plugins enabled:
-
plugin/zoom-js/zoom.js
-
plugin/notes/notes.js
All these plugins are part of the reveal.js distribution.
To enable or disable a built-in plugin, it is possible to set the revealjs_plugin_[plugin name] attribute to enable or disable.
For example, to disable all the default plugins set the following document attributes:
:revealjs_plugin_zoom: disabled :revealjs_plugin_notes: disabled
Additional reveal.js plugins can be installed and activated using AsciiDoc attributes and external javascript files.
-
Extract the plugin files in a directory
-
Create a JavaScript file that will contain the JavaScript statements to load the plugin (only one required even if you are using several plugins)
-
Add a
:revealjs_plugins:attribute to point to that JavaScript file -
(Optional) Add a
:revealjs_plugins_configuration:attribute to point to a JavaScript file that configures the plugins you use
Looking at the example provided in the repository will provide guidance: AsciiDoc source, Plugin Loader, Plugin Configuration.
Read the relevant reveal.js documentation to understand more about reveal.js plugins. A list of existing reveal.js plugins is also maintained upstream.
Our requirements are expressed in our packages and by our dependencies. Basically, all you need is the package manager of the flavor of Asciidoctor reveal.js you are interested to run:
-
With Ruby / Bundler: A recent Ruby and Bundler
-
With JavaScript (Node.js) / npm: a recent Node.js environment
If you need more details about our dependencies check out Asciidoctor dependencies:
-
With Ruby / Bundler: Asciidoctor 2.0.10
-
With JavaScript (Node.js) / NPM: Asciidoctor.js 2.0.3
We try as much as possible to be compatible with a broad range of reveal.js versions. However, changes made by that project sometimes forces us to drop compatibility with older reveal.js releases. This table tracks this compatibility.
| Asciidoctor reveal.js version | reveal.js version |
|---|---|
4.x |
3.9 - 3.8 |
3.x, 2.x, 1.x |
3.7 - 3.0 |
Unversioned releases |
2.x |
|
📎
|
This section is intended only for more advanced users who combine extensions or maintain slide decks over many releases and need to update their dependencies. |
Due to our Ruby to JavaScript conversion process, published npm packages have strict requirements with which version of Asciidoctor.js they are compatible with. This table tracks this compatibility.
| Asciidoctor-reveal.js version | Asciidoctor.js version |
|---|---|
3.x |
2.x |
2.x |
1.5.9 |
1.1.x |
1.5.6-preview.4 |
Be aware that it is always possible to recompile the converter into JavaScript from source so compatibility can be created by anyone if needed. More details on that topic can be found in the development guide.
A smooth presentation, featuring video backgrounds, slide transitions, code and callout examples and the use of notes.
Presentation and source
Interested in contributing? We are interested! Developer-focused documentation is over here.
Copyright © 2012-2020 Olivier Bilodeau, Guillaume Grossetie, Dan Allen, Rahman Usta, Charles Moulliard and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.
See the LICENSE file for details.