asciidoctor-revealjs 3.0.0 → 4.1.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2339f9a2b0d41e0d60f1b93c165ac143f93a093687d0006986039b7d75a4b864
-  data.tar.gz: 52ba202bef3578b773faaea1b0a5ccca9491b2350237916c41cd32bff1a0e0ff
+  metadata.gz: 51f0597f97711399e5fbd268198a6b2482e813cc9015d8f2b405549931a499b9
+  data.tar.gz: 144f1493734fcccf711f0e2ca635af999979feee73976b9ebe753800b3ff7c5f
 SHA512:
-  metadata.gz: 40df2ec1142b6fd602e8cadbaefd17452d455226a75dc41fab9040c97870111155a06dbc788aa219d9034b6ac8e64f856697f35cf8dd6bc7c13cea66fd66de46
-  data.tar.gz: 06a6e6d0f534404c15d30898f0740afc033a274b625786e8c01155919f584c6ae55482af04765b48d303c9f3d03681cce1cd2d7ac59655a93921f1dd3b3ddd44
+  metadata.gz: 00d7608d340549717eb2d73d9b03405e13bbe7151002a94dbf0725ca487a970c6332109f974ffb36a62b1f48cb32e67dc00d19dbda73729be726771e4f1eccaf
+  data.tar.gz: b32a2253ee741a20fb42ed1ceec11e0a82384b3282707d7c1fcae1677e4ff8a571c70eba377bcab97e6647f2ca2b81b5c371ab5f5e06d83f3af3933b48ed3962

data/LICENSE.adoc

@@ -1,6 +1,6 @@
 .The MIT License
 ....
-Copyright (C) 2012-2019 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project
+Copyright (C) 2012-2020 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.adoc

@@ -18,10 +18,11 @@ endif::[]
 :uri-project-repo: https://github.com/asciidoctor/asciidoctor-reveal.js
 :uri-asciidoctor: https://github.com/asciidoctor/asciidoctor
 :uri-asciidoctorjs: https://github.com/asciidoctor/asciidoctor.js
-:uri-revealjs-home: http://lab.hakim.se/reveal-js/
-:uri-revealjs-gh: https://github.com/hakimel/reveal.js
+:uri-revealjs-home: https://revealjs.com
+:uri-revealjs-gh: https://github.com/hakimel/reveal.js/blob/v3.9
+:uri-revealjs-doc: {uri-revealjs-gh}/README.md
 :uri-nodejs-download: https://nodejs.org/en/download/
-:showcasedir: showcase 
+:showcasedir: showcase
 
 ifdef::env-github[]
 image:https://travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=https://travis-ci.org/asciidoctor/asciidoctor-reveal.js]
@@ -34,35 +35,27 @@ endif::[]
 
 TIP: Want to see some example presentations, see <<Showcase Presentations>>
 
-There are two main technology stacks that can transform AsciiDoc into HTML5 / reveal.js:
+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>>)
-
-Right now the Asciidoctor / Ruby stack is the better tested one but with the changes in v1.1.0 they have feature parity.
+* Standalone Executable (See <<Standalone Executable>>)
+* AsciidoctorJ / JVM / Maven (See https://github.com/asciidoctor/asciidoctorj-reveal.js[this project])
 
 ifeval::['{branch}' == 'master']
 NOTE: 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: +
-{uri-project-repo}/tree/v2.0.1#readme[2.0.1] (latest release)
-&hybull;
-{uri-project-repo}/tree/v1.1.3#readme[1.1.3] (latest from 1.1 series)
+{uri-project-repo}/tree/v4.0.0#readme[4.0.1] (latest from 4.x series)
 &hybull;
-{uri-project-repo}/tree/maint-1.0.x#readme[1.0.x]
+{uri-project-repo}/tree/v3.1.0#readme[3.1.0] (latest from 3.x series)
 &hybull;
-{uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with RevealJS 2.x)
+{uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with reveal.js 2.x)
 endif::[]
 
 
 == Ruby Setup
 
-NOTE: asciidoctor-reveal.js is now a Ruby Gem.
-To ensure repeatability, we recommend that you manage your presentation projects using bundler.
-
-For a quick start clone our https://github.com/obilodeau/presentation-revealjs-starter[starter repository] and follow instructions there.
-
-For more complete instructions, read on.
-
+NOTE: To ensure repeatability, we recommend that you manage your presentation projects using http://bundler.io/[bundler].
 
 === Prerequisites
 
@@ -107,7 +100,7 @@ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to
 . Optional: Copy or clone reveal.js presentation framework.
   Allows you to modify themes or view slides offline.
 
-  $ git clone -b 3.7.0 --depth 1 https://github.com/hakimel/reveal.js.git
+  $ git clone -b 3.9.2 --depth 1 https://github.com/hakimel/reveal.js.git
 
 
 === Rendering the AsciiDoc into slides
@@ -118,7 +111,7 @@ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to
 . Generate HTML presentation from the AsciiDoc source
 
   $ bundle exec asciidoctor-revealjs \
-    -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 CONTENT_FILE.adoc
+    -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
@@ -127,6 +120,29 @@ NOTE: For some reason, when you use the system Ruby on Fedora, you also have to
 
 TIP: If you are using https://pages.github.com/[GitHub Pages], plan ahead by keeping your source files on `master` branch and all output files on the `gh-pages` branch.
 
+=== Features Unique to the Ruby CLI
+
+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 https://github.com/asciidoctor/asciidoctor-reveal.js/tree/master/templates[templates] for inspiration.
+
+This feature hasn't been ported to the JavaScript CLI (and API) or the standalone executables.
+
 
 == Node / JavaScript Setup
 
@@ -148,14 +164,14 @@ You can now install the dependencies:
 
 === Convert AsciiDoc into slides
 
-Once the dependencies are installed, verify that the `asciidoctor` command is available.
+Once the dependencies are installed, verify that the `asciidoctor-revealjs` command is available.
 On Linux and macOS, open a terminal and type:
 
- $ $(npm bin)/asciidoctor --version
+ $ npx asciidoctor-revealjs --version
 
 On Windows, open PowerShell and type:
 
- $ .\node_modules\.bin\asciidoctor.cmd --version
+ $ .\node_modules\.bin\asciidoctor-revealjs.cmd --version
 
 The command should report the Asciidoctor CLI version in the terminal:
 
@@ -183,12 +199,12 @@ If you don't have an existing presentation, you can create a sample presentation
 
 To convert the sample presentation into slides, open a terminal and type:
 
- $ $(npm bin)/asciidoctor -r @asciidoctor/reveal.js -b revealjs presentation.adoc
+ $ npx asciidoctor-revealjs presentation.adoc
 
 On windows, open PowerShell and type:
 
- $ .\node_modules\.bin\asciidoctor.cmd -r @asciidoctor/reveal.js -b revealjs presentation.adoc
- 
+ $ .\node_modules\.bin\asciidoctor-revealjs.cmd presentation.adoc
+
 The above command will generate a file named [.path]_presentation.html_.
 You can open this file in a browser.
 
@@ -216,6 +232,61 @@ To execute the script, open a terminal and type:
 
 You can open the `presentation.html` file in your browser and enjoy!
 
+
+== Standalone Executable
+
+Pre-built binary packages can be downloaded from our {uri-project-repo}/releases[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 Setup,Node / JavaScript>> toolchain.
+
+=== Install
+
+* {uri-project-repo}/releases[Download the executable] for your platform and make it executable with `chmod` or 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
+
+=== Convert AsciiDoc into slides
+
+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:
+
+[source,console]
+----
+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.0
+----
+
+If you don't have an existing presentation, you can create a sample presentation named [.path]_presentation.adoc_:
+
+.presentation.adoc
+[source,asciidoc]
+----
+= Title Slide
+:revealjsdir: reveal.js
+
+== Slide One
+
+* Foo
+* Bar
+* World
+
+----
+
+To convert the sample presentation into slides, open a terminal and type:
+
+ $ ./asciidoctor-revealjs presentation.adoc
+
+The above command will generate a file named [.path]_presentation.html_.
+You can open this file in a browser.
+
+
 == Syntax Examples
 
 Let's see some examples of `revealjs` backend features.
@@ -244,7 +315,7 @@ A Great Story
 --
 ----
 
-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 {uri-revealjs-gh}#speaker-notes[speaker notes].
+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 {uri-revealjs-doc}#speaker-notes[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:
@@ -331,7 +402,7 @@ NOTE: The `canvas` keyword can be used instead of `background` for the same effe
 Is very yellow
 ----
 
-Slide Three applies the attribute {uri-revealjs-gh}#slide-backgrounds[data-background-color] to the `reveal.js` <section> tag.
+Slide Three applies the attribute {uri-revealjs-doc}#slide-backgrounds[data-background-color] to the `reveal.js` <section> tag.
 Anything accepted by CSS color formats works.
 
 
@@ -348,7 +419,7 @@ 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 {uri-revealjs-gh}#image-backgrounds[relevant reveal.js documentation] for details.
+See the {uri-revealjs-doc}#image-backgrounds[relevant reveal.js documentation] for details.
 
 NOTE: Background images file names are now relative to the `:imagesdir:` attribute if set.
 
@@ -386,7 +457,7 @@ For example:
 == Nice background!
 ----
 
-See {uri-revealjs-gh}#video-backgrounds[the relevant reveal.js documentation] for details.
+See {uri-revealjs-doc}#video-backgrounds[the relevant reveal.js documentation] for details.
 Note that the `data-` prefix is not required in asciidoc files.
 
 
@@ -400,7 +471,7 @@ The background can be replaced with anything a browser can render in an iframe u
 == a youtube video
 ----
 
-See {uri-revealjs-gh}#iframe-backgrounds[the relevant reveal.js documentation] for details.
+See {uri-revealjs-doc}#iframe-backgrounds[the relevant reveal.js documentation] for details.
 
 
 === Slide Transitions
@@ -418,7 +489,7 @@ This slide will override the presentation transition and zoom!
 Choose from three transition speeds: default, fast or slow!
 ----
 
-See {uri-revealjs-gh}#slide-transitions[the relevant reveal.js documentation] for details.
+See {uri-revealjs-doc}#slide-transitions[the relevant reveal.js documentation] for details.
 
 
 === Fragments
@@ -435,9 +506,9 @@ See {uri-revealjs-gh}#slide-transitions[the relevant reveal.js documentation] fo
 ----
 
 Slide Four has bullets that are revealed one after the other.
-This is what `reveal.js` calls http://lab.hakim.se/reveal-js/#/fragments[fragments].
+This is what `reveal.js` calls {uri-revealjs-home}/fragments[fragments].
 Applying the step option or role on a list (`[%step]` or `[.step]`) will do the trick.
-Here is {uri-revealjs-gh}#fragments[the relevant reveal.js
+Here is {uri-revealjs-doc}#fragments[the relevant reveal.js
 documentation] on the topic.
 Note that only `fade-in` is supported for lists at the moment.
 
@@ -453,7 +524,7 @@ To apply that class to block simply use asciidoctor's class assignment:
 
     [.stretch]
 
-See {uri-revealjs-gh}#stretching-elements[reveal.js documentation on stretching elements].
+See {uri-revealjs-doc}#stretching-elements[reveal.js documentation on stretching elements].
 
 
 === Videos
@@ -474,9 +545,9 @@ To override that behavior use the `width` and `height` named attributes.
 
 === Syntax highlighting
 
-Reveal.js is well integrated with https://highlightjs.org/[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:
+reveal.js is well integrated with https://highlightjs.org/[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:
 
 [source, asciidoc]
 ----
@@ -485,7 +556,26 @@ You can activate highlight.js syntax highlighting (disabled by default) by setti
 :source-highlighter: highlightjs
 ----
 
-Once enabled you can write code blocks as usual:
+[NOTE]
+====
+By 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:
 
 [source, asciidoc]
 ....
@@ -515,7 +605,8 @@ print "$0: hello world\n"
 ....
 
 [NOTE]
-Alternatively, you can use http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as syntax highlighters if you are using the Asciidoctor/Ruby/Bundler toolchain (not Asciidoctor.js/JavaScript/npm).
+Alternatively, you can use http://rouge.jneen.net/[Rouge], http://coderay.rubychan.de[Coderay] or http://pygments.org[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.
 
@@ -535,11 +626,135 @@ 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 {uri-revealjs-gh}#markup[the relevant reveal.js
+Here is {uri-revealjs-doc}#markup[the relevant reveal.js
 documentation] on that topic.
 
+=== Columns layout
+
+Inspired by https://bulma.io/[Bulma], Asciidoctor reveal.js supports columns layout out-of-the-box:
+
+[source, asciidoc]
+....
+[.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.
+
+[source, asciidoc]
+....
+[.columns]
+== 3 columns
+
+[.column]
+* Java
+* **Kotlin**
+
+[.column]
+* Node
+* **Deno**
+
+[.column]
+* Ruby
+* **Crystal**
+....
 
-=== Asciidoctor-reveal.js specific roles
+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`
+
+[source, asciidoc]
+....
+[.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.
+
+[source, asciidoc]
+....
+[.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.
+
+[source, asciidoc]
+....
+[.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
+--
+....
+
+
+=== Asciidoctor reveal.js specific roles
 
 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:
 
@@ -574,6 +789,17 @@ Here is a list of supported roles:
 right:: Will apply a `float: right` style to the affected block
 
 
+=== Asciidoctor reveal.js specific attributes
+
+==== iFrame Preview Overlay
+
+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 <<examples/links.adoc#,links.adoc>> and <<examples/links-preview.adoc#,links-preview.adoc>> for examples.
+
+
 === Title slide customization
 
 The title slide is customized via Asciidoc attributes.
@@ -583,7 +809,7 @@ title that look like this: `:name: value`.
 This converter supports changing the color, image, video, iframe and
 transitions of the title slide.
 
-Read {uri-revealjs-gh}#slide-backgrounds[the relevant reveal.js documentation] to understand what attributes need to be set.
+Read {uri-revealjs-doc}#slide-backgrounds[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-`.
 
 ifeval::[{safe-mode-level} >= 20]
@@ -666,7 +892,7 @@ If the `:customcss:` attribute value is empty then `asciidoctor-revealjs.css` is
 
 === Slide state
 
-Reveal.js supports a {uri-revealjs-gh}#slide-states[data-state] tag that can be added on slides which gets rendered into `<section>` tags.
+Reveal.js supports a {uri-revealjs-doc}#slide-states[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:
 
 [source, asciidoc]
@@ -709,6 +935,41 @@ WARNING: This presentation is dangerous!
 
 Here are details about Asciidoctor's http://asciidoctor.org/docs/user-manual/#admonition-icons[Admonition icons] support.
 
+=== Supplemental Content with Docinfo
+// Originally from https://github.com/asciidoctor/asciidoctor-bespoke#supplemental-content
+
+It's possible to inject supplemental content into the output document using http://asciidoctor.org/docs/user-manual/#docinfo-file[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:
+
+.src/docinfo-footer-revealjs.html
+[source,html]
+----
+<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.
+
 
 == Reveal.js Options
 
@@ -724,7 +985,7 @@ NOTE: Default settings are based on `reveal.js` default settings.
 
 |:revealjs_theme:
 |beige, *black*, league, night, serif, simple, sky, solarized, white
-|Chooses one of reveal.js`' {uri-revealjs-gh}#theming[built-in themes].
+|Chooses one of reveal.js`' {uri-revealjs-doc}#theming[built-in themes].
 
 |:revealjs_customtheme:
 |<file\|URL>
@@ -740,7 +1001,7 @@ Default is built-in [path]_lib/css/zenburn.css_.
 |<file\|URL>
 |Overrides reveal.js directory.
 Example: ../reveal.js or
-https://cdnjs.com/libraries/reveal.js/3.7.0[https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0].
+https://cdn.jsdelivr.net/npm/reveal.js@3.9.2.
 Default is `reveal.js/` unless in a Node.js environment where it is `node_modules/reveal.js/`.
 
 |:revealjs_controls:
@@ -782,9 +1043,13 @@ all:: show on all views (default)
 speaker:: only show slide numbers on speaker notes view
 print:: only show slide numbers when printing to PDF
 
+|:revealjs_hash:
+|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
+
 |:revealjs_history:
 |true, *false*
-|Push each slide change to the browser history.
+|Push each slide change to the browser history. Implies `hash: true`
 
 |:revealjs_keyboard:
 |*true*, false
@@ -810,6 +1075,14 @@ print:: only show slide numbers when printing to PDF
 |true, *false*
 |Change the presentation direction to be RTL.
 
+|:revealjs_navigationMode:
+|*default*, linear, grid
+|See {uri-revealjs-doc}#navigation-mode for details
+
+|:revealjs_shuffle:
+|true, *false*
+|Randomizes the order of slides each time the presentation loads
+
 |:revealjs_fragments:
 |*true*, false
 |Turns fragments on and off globally.
@@ -838,6 +1111,14 @@ null:: Media will only autoplay if data-autoplay is present
 true:: All media will autoplay, regardless of individual setting
 false:: No media will autoplay, regardless of individual setting
 
+|:revealjs_preloadIframes:
+|*null*, true, false
+a|Global override for preloading lazy-loaded iframes
+
+null:: Iframes with `data-src` AND `data-preload` will be loaded when within the `viewDistance`, iframes with only `data-src` will be loaded when visible
+true:: All iframes with `data-src` will be loaded when within the `viewDistance`
+false:: All iframes with `data-src` will be loaded only when visible
+
 |:revealjs_autoSlide:
 |<integer>
 |Delay in milliseconds between automatically proceeding to the next slide.
@@ -858,10 +1139,31 @@ This value can be overwritten by using a `data-autoslide` attribute on your slid
 This is used to show a pacing timer in the speaker view.
 Defaults to *120*
 
+|:revealjs_totalTime:
+|<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*
+
+|:revealjs_minimumTimePerSlide:
+|<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*.
+
 |:revealjs_mouseWheel:
 |true, *false*
 |Enable slide navigation via mouse wheel.
 
+|:revealjs_hideInactiveCursor:
+|*true*, false
+|Hide cursor if inactive
+
+|:revealjs_hideCursorTime:
+|<integer>
+|Time before the cursor is hidden (in ms).
+Defaults to *5000*.
+
 |:revealjs_hideAddressBar:
 |*true*, false
 |Hides the address bar on mobile devices.
@@ -869,7 +1171,7 @@ Defaults to *120*
 |:revealjs_previewLinks:
 |true, *false*
 |Opens links in an iframe preview overlay.
-Add `data-preview-link` and `data-preview-link="false"` to customise each link individually
+Add the `preview=true` attribute on links or `link_preview=true` attribute on images to customize each link individually.
 
 |:revealjs_transition:
 |none, fade, *slide*, convex, concave, zoom
@@ -885,7 +1187,14 @@ Add `data-preview-link` and `data-preview-link="false"` to customise each link i
 
 |:revealjs_viewDistance:
 |<integer>
-|Number of slides away from the current that are visible. Default: 3
+|Number of slides away from the current that are visible.
+Default: *3*.
+
+|:revealjs_mobileViewDistance:
+|<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*.
 
 |:revealjs_parallaxBackgroundImage:
 |<file\|URL>
@@ -943,10 +1252,17 @@ Defaults to *1*
 
 If you want to build a custom theme or customize an existing one you should
 look at the
-{uri-revealjs-gh}/blob/master/css/theme/README.md[reveal.js
+{uri-revealjs-gh}/css/theme/README.md[reveal.js
 theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to
 activate it.
 
+
+=== PDF Export
+
+Follow {uri-revealjs-doc}#pdf-export[reveal.js' documentation] for PDF export.
+We would add that we have successfully used PDF export without the requirement of a Web server.
+
+
 === Default plugins
 
 By default, generated presentations will have the following reveal.js plugins enabled:
@@ -965,17 +1281,6 @@ For example, to disable all the default plugins set the following document attri
 :revealjs_plugin_notes: disabled
 ----
 
-reveal.js ships with a plugin that allows to create a PDF from a slide deck.
-To enable this plugin, set the `revealjs_plugin_pdf` attribute.
-
-----
-:revealjs_plugin_pdf: enabled
-----
-
-When the plugin is enabled and you run your presentation in a browser with `?print-pdf` at the end of the URL, you can then use the default print function to print the slide deck into a PDF document.
-
-TIP: To work properly, this plugin requires a Chrome-based browser.
-
 
 === Additional plugins
 
@@ -988,7 +1293,7 @@ Additional reveal.js plugins can be installed and activated using AsciiDoc attri
 
 Looking at the example provided in the repository will provide guidance: link:examples/revealjs-plugins.adoc[AsciiDoc source], link:examples/revealjs-plugins.js[Plugin Loader], link:examples/revealjs-plugins-conf.js[Plugin Configuration].
 
-Read {uri-revealjs-gh}#dependencies[the relevant reveal.js documentation] to understand more about reveal.js plugins.
+Read {uri-revealjs-doc}#dependencies[the relevant reveal.js documentation] to understand more about reveal.js plugins.
 A {uri-revealjs-gh}/wiki/Plugins,-Tools-and-Hardware[list of existing reveal.js plugins] is also maintained upstream.
 
 
@@ -1005,6 +1310,28 @@ If you need more details about our dependencies check out Asciidoctor dependenci
 * With Ruby / Bundler: https://github.com/asciidoctor/asciidoctor/tree/v2.0.10#requirements[Asciidoctor] 2.0.10
 * With JavaScript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v2.0.3/packages/core/package.json[Asciidoctor.js] 2.0.3
 
+
+[[revealjs-compatibility-matrix]]
+== reveal.js Compatibility Matrix
+
+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
+|===
+
+
 [[asciidoctorjs-compatibility-matrix]]
 == Asciidoctor.js Compatibility Matrix
 
@@ -1055,7 +1382,7 @@ Developer-focused documentation is link:HACKING.adoc[over here].
 
 == Copyright and Licensing
 
-Copyright (C) 2012-2019 {authors} and the Asciidoctor Project.
+Copyright (C) 2012-2020 {authors} and the Asciidoctor Project.
 Free use of this software is granted under the terms of the MIT License.
 
 ifdef::env-github,env-browser[See the <<LICENSE#,LICENSE>> file for details.]