Migrating from v5 to v6

v6 carries a few breaking changes. Most of them affect how you set up and run the converter (the reveal.js version, the JavaScript API, the standalone executables) rather than your slides. As far as slide content goes, you may have to rename a docinfo file or two at most.

reveal.js 6 is required

The generated HTML now targets the reveal.js 6 distribution layout (for instance, the built-in plugins are loaded from dist/plugin/zoom.js instead of plugin/zoom/zoom.js), so it no longer works with reveal.js 4 or 5. See the Compatibility Matrix for details.

If revealjsdir points at a local copy or a CDN URL of reveal.js 4 or 5, upgrade it to reveal.js 6, for instance:

:revealjsdir: https://cdn.jsdelivr.net/npm/reveal.js@6.0.2

Or, for a local copy:

$ git clone -b 6.0.2 --depth 1 https://github.com/hakimel/reveal.js.git

The npm package already depends on reveal.js 6, so if you use the default revealjsdir with Node.js (node_modules/reveal.js), reinstalling your dependencies is enough.

If you use third-party reveal.js plugins, make sure the version you load supports reveal.js 6.

Docinfo `header`/`footer` now match the html5 converter

In every other Asciidoctor converter (html5, docbook5, …), a docinfo header is inserted right after <body> and a docinfo footer right before </body>. Before v6, this converter’s header/footer meant something else entirely: the first/last child of <div class="slides">, one level deeper and inside the slides container specifically.

v6 redefines header/footer to match every other converter, and gives the position they used to mean a new, more specific name: slides-header/slides-footer.

If you have this file… …it now behaves like this

If you have this file…	…it now behaves like this
`docinfo-header-revealjs.html` (or `<docname>-docinfo-header-revealjs.html`)	Content moves from just inside `.slides` to just inside `<body>`, before `.reveal` even starts. Rename it to `docinfo-slides-header-revealjs.html` to keep the exact same behavior.
`docinfo-footer-revealjs.html` (or `<docname>-docinfo-footer-revealjs.html`)	Content moves from just inside `.slides` (after the last slide) to just inside `</body>`, after reveal.js has initialized. Rename it to `docinfo-slides-footer-revealjs.html` to keep the exact same behavior.

docinfo-header-revealjs.html
(or <docname>-docinfo-header-revealjs.html)

Content moves from just inside .slides to just inside <body>, before .reveal even starts. Rename it to docinfo-slides-header-revealjs.html to keep the exact same behavior.

docinfo-footer-revealjs.html
(or <docname>-docinfo-footer-revealjs.html)

Content moves from just inside .slides (after the last slide) to just inside </body>, after reveal.js has initialized. Rename it to docinfo-slides-footer-revealjs.html to keep the exact same behavior.

If you never had a docinfo-header-revealjs.html/docinfo-footer-revealjs.html file, this change doesn’t affect you.

A second, related fix: a footer docinfo file with no backend suffix (plain docinfo-footer.html, or <docname>-docinfo-footer.html) used to be picked up by the revealjs backend too, at the new footer position — even though that file is meant for the html5 backend (the unsuffixed convention exists for backwards compatibility with single-slot converters). That cross-backend leak is fixed in v6: only docinfo-footer-revealjs.html (suffixed) is read at the footer position now. If you were relying on an unsuffixed docinfo-footer.html to inject something into your reveal.js presentation (for example, to configure and initialize a reveal.js plugin after Reveal.initialize() runs — see reveal.js Plugins), rename it to docinfo-footer-revealjs.html.

Supplemental Content with Docinfo documents the full set of insertion locations, including two entirely new ones — slide-header/slide-footer, injected into every slide — that didn’t exist before v6.

Embedded conversion wraps the title in a proper title slide

Converting with standalone: false (or --embedded/--no-header-footer) and showtitle used to render the document title as a bare <h1>My Title</h1>, outside of any <section>. It’s now wrapped the same way the standalone converter already wraps it:

<section class="title" data-state="title"><h1>My Title</h1></section>

If you embed this fragment as-is on a page (e.g. via a static site generator) and styled that bare <h1> directly, update your selector to target section.title h1 (or [data-state="title"] h1) instead.

`:notitle:` now suppresses the title slide

:notitle: was silently ignored by the title slide — every other place that checks it (a [%notitle] option on a section, the embedded converter’s own heading) already did, only the standalone title slide dispatch didn’t. It now behaves consistently: setting :notitle: on a document with a title removes its title slide, the same way it already removed <h2> headings on sections marked [%notitle].

If you had :notitle: set on a presentation and still expected to see the title slide, remove the attribute.

JavaScript converter: Node.js 20+, Asciidoctor.js 4.0 and an ESM, asynchronous API

The JavaScript converter is now a native port targeting the Asciidoctor.js 4.0 API (async convert handlers), instead of running through the Slim-templates compiler on top of Asciidoctor.js 2.x/3.x. This raises two minimum versions:

Node.js 20 or later
asciidoctor (the npm package) >=4.2.1 <5.0.0

Asciidoctor.js 4.0 is published as the asciidoctor package instead of @asciidoctor/core. It’s a peer dependency of @asciidoctor/reveal.js, so install it alongside the converter:

$ npm i --save asciidoctor @asciidoctor/reveal.js

Both packages are now ES modules only, and the conversion functions (convert, convertFile) are asynchronous, so a script that uses the JavaScript API must be updated:

Before (v5)

var asciidoctor = require('@asciidoctor/core')()
var asciidoctorRevealjs = require('@asciidoctor/reveal.js')
asciidoctorRevealjs.register()

var options = { safe: 'safe', backend: 'revealjs' }
asciidoctor.convertFile('presentation.adoc', options)

After (v6)

import { convertFile } from 'asciidoctor'
import { register } from '@asciidoctor/reveal.js'

register()

const options = { safe: 'safe', backend: 'revealjs' }
await convertFile('presentation.adoc', options)

Use the .mjs file extension (or set "type": "module" in your package.json) so Node.js loads the script as an ES module. See Node / JavaScript Setup for a complete example.

The Ruby gem’s asciidoctor dependency is unaffected (>= 2.0.0, < 3.0.0).

Standalone executables: new platforms and file names

The standalone executables are now built for the following platforms:

Linux: amd64 (x86-64) and arm64
macOS: arm64 (Apple Silicon)
Windows: amd64 (x86-64)

v5 provided a single x86-64 executable per operating system, including macOS. There’s no macOS Intel (x86-64) executable anymore: on an Intel Mac, use the npm package or the Ruby gem instead.

The release assets are now named after the platform and the architecture: asciidoctor-revealjs-linux-amd64, asciidoctor-revealjs-linux-arm64, asciidoctor-revealjs-macos-arm64 and asciidoctor-revealjs-win-amd64.exe (instead of asciidoctor-revealjs-linux, asciidoctor-revealjs-macos and asciidoctor-revealjs-win.exe). If a script downloads them, update the file names.

The highlight.js adapter only applies to the `revealjs` backend

To support the reveal.js highlight plugin, this converter registers its own highlightjs (and highlight.js) syntax highlighter. Before v6, loading the converter replaced the built-in highlight.js syntax highlighter for every backend: for instance, an html5 conversion with :source-highlighter: highlightjs running in the same process got the reveal.js-specific data-noescape/data-line-numbers attributes and the highlight plugin scripts.

In v6, the adapter delegates to the built-in highlight.js syntax highlighter whenever the backend isn’t revealjs (or reveal.js), so loading this converter no longer changes the output of the other backends. Presentations converted with the revealjs backend are not affected.