An Asciidoctor extension that adds a carousel block to AsciiDoc. It turns a sequence of images into a responsive, accessible image carousel (or slideshow).
|
ℹ️
|
This extension is intended for HTML backends (e.g., html5).
For all other backends, the custom block enclosure is discarded and its visual content is converted normally.
|
Each carousel is constructed from visual blocks enclosed in an example block annotated with the carousel style.
Every child block that resolves to a single image becomes one slide.
The following child blocks are supported:
-
block image macro (
image::) -
Asciidoctor Diagram block (e.g.,
[plantuml]) -
Asciidoctor Diagram block macro (e.g.,
plantuml::file.puml[]) -
Asciidoctor Diagram inline macro on its own paragraph (e.g.,
plantuml:file.puml[]) -
any other paragraph that contains a single inline image (e.g.,
image:logo.svg[])
The extension does not redefine image or diagram processing. It delegates each slide to the normal AsciiDoc converters, so existing image and diagram attributes continue to work.
The simplest carousel contains two or more block image macros.
[carousel]
====
.Sunset over the bay
image::images/sunset.jpg[Sunset,800,600]
.Beach at noon
image::images/beach.jpg[Beach,800,600]
.City at dusk
image::images/city.jpg[City,800,600]
====The optional block title above each image becomes that slide’s caption. Within a carousel, those titles are not numbered as figures.
You can use an include directive to load a sequence of slides.
[carousel]
====
include::gallery/slides.adoc[]
====The included file contains the image macros:
.Sunset over the bay
image::sunset.jpg[Sunset,800,600]
.Beach at noon
image::beach.jpg[Beach,800,600]Load Asciidoctor Diagram alongside this extension and use any of its block forms as a slide.
[carousel]
====
.Flow diagram
[plantuml,target=flow,format=svg]
....
@startuml
Alice -> Bob: hello
@enduml
....
.Sequence diagram
plantuml::diagrams/sequence.puml[format=svg]
.Overview diagram
plantuml:diagrams/overview.puml[format=svg]
====Diagram attributes such as target, format, server-url, and svg-type are passed through to Asciidoctor Diagram unchanged.
If a diagram outputs a text format (e.g., txt), the carousel falls back to a normal example block.
|
ℹ️
|
Asciidoctor Kroki reads a diagram file target relative to the working directory and ignores imagesdir, so a file-based macro needs an absolute path when you load that extension, for example plantuml::/diagrams/sequence.puml[format=svg,target=sequence].
Asciidoctor Diagram resolves the same target relative to the document, so plantuml::diagrams/sequence.puml[format=svg] is enough there.
|
Options and named attributes are assigned on the carousel block using standard AsciiDoc block attribute syntax.
[carousel#tour.hero%autoplay%loop,interval=3000,active-slide=2,height=400px]
====
image::images/a.jpg[First]
image::images/b.jpg[Second]
image::images/c.jpg[Third]
====| Attribute | Description |
|---|---|
|
Autoplay interval in milliseconds. Defaults to |
|
Initial slide number, starting at |
|
Optional stage height as a CSS length (e.g., |
|
Optional stage width as a CSS length. |
|
Optional stage aspect-ratio hint (e.g., |
|
Stage alignment within its container: |
|
Transition effect used to move between slides. Defaults to |
| Option | Description |
|---|---|
|
Advance slides automatically using |
|
Wrap from the last slide to the first. Enabled by default. |
|
Disable looping. |
|
Pause autoplay while the pointer is over the carousel. |
|
Enable left and right arrow keys. Enabled by default. |
|
Disable keyboard navigation. |
|
Enable swipe navigation on touch devices. Enabled by default. |
|
Disable touch navigation. |
|
Show previous and next controls. Enabled by default. |
|
Hide the previous and next controls. |
|
Show slide indicators. Enabled by default. |
|
Hide the slide indicators. |
The fade attribute names the effect used to move between slides.
[carousel,fade=cube]
====
image::images/a.jpg[First]
image::images/b.jpg[Second]
image::images/c.jpg[Third]
====| Effect | Description |
|---|---|
|
Slide horizontally from one slide to the next. This is the default. |
|
Cross-fade the slides in place. |
|
Cross-fade while the incoming slide settles back to its natural size and the outgoing slide grows towards the reader. |
|
Turn each slide around its vertical centre line, so a slide arrives from the side it belongs to. |
|
Roll the slides as the faces of a cube; each slide hinges on the edge it shares with the next one. |
|
Keep the neighbouring slides visible behind the active one, like the rest of a deck. |
|
Set the active slide back from the edges and turn the neighbouring slides beside it, so the slide on screen stands in the middle and nothing covers it. |
|
Cross-fade while the slide on screen grows from just under its full size into place, then holds at that size. |
An effect the extension does not recognize falls back to slide.
Every effect except slide stacks the slides, so the stage takes its height from the slide that is showing.
When the slides do not share an aspect ratio, set height or aspect-ratio to hold the stage steady and to keep the neighbouring slides of cards and coverflow from being clipped.
The kenburns growth takes 800 ms and then holds, so the slide has settled well before it changes at the default interval; an interval shorter than that cuts the growth short.
When the pointer hovers over a slide indicator, a popup shows a preview of the slide associated with that indicator. The preview is centered above the indicator and disappears when the pointer leaves the indicator.
The preview size is derived from the carousel stage:
-
The preview width is one quarter of the current carousel stage width.
-
The preview height is one quarter of the current carousel stage height.
-
If
widthorheightis configured, those settings affect the stage size, and the preview scales accordingly.
The image is scaled with object-fit: contain, so it keeps its aspect ratio and is never distorted.
This feature is always available when indicators are shown.
$ asciidoctor -r asciidoctor-carousels basic.adoc
To use diagrams in a carousel, load Asciidoctor Diagram as well:
$ asciidoctor -r asciidoctor-carousels -r asciidoctor-diagram diagrams.adoc
You can specify an alternate stylesheet using the carousel-stylesheet document attribute.
$ asciidoctor -r asciidoctor-carousels -a carousel-stylesheet=my-carousel.css basic.adoc
The value of carousel-stylesheet is handled in the same way as the built-in stylesheet document attribute.
Require the extension with either of these two forms:
require 'asciidoctor'
require 'asciidoctor-carousels'require 'asciidoctor'
require 'asciidoctor/carousels'You can also register the extension with a scoped registry:
require 'asciidoctor'
require 'asciidoctor/carousels/extensions'
registry = Asciidoctor::Extensions.create
Asciidoctor::Carousels::Extensions.register registry
Asciidoctor.convert_file 'basic.adoc', extension_registry: registry, safe: :safeThe extension transforms the visual blocks inside the example block into a single carousel block that is a specialization of an open block. The example block enclosure is discarded.
The carousel interface consists of:
-
a stage element that clips the visible slide,
-
a track element that contains the slides,
-
one slide element per visual block,
-
optional previous and next controls,
-
optional slide indicators.
The supporting stylesheet and script are added only when producing a standalone HTML document.
The stylesheet is added to the end of the <head> element and the script is added to the end of the <body> element.
By default, both assets are embedded into the HTML.
If the linkcss attribute is set, the HTML links to these assets instead.
The extension writes the linked assets into the output directory automatically.
The stylesheet is written under stylesdir and the script is written under scriptsdir.
If scriptsdir is not set, it is derived from stylesdir by replacing the final path segment with scripts.
The first slide is selected by default, or the slide specified by active-slide.
The carousel is activated at runtime by a stylesheet and a script. Both assets are embedded by default, so there is normally nothing else to do.
If linkcss is set, the linked assets are written automatically when the document is converted to a file:
-
asciidoctor-carousels.css is written under
stylesdir. -
asciidoctor-carousels.js is written under
scriptsdir. -
If
scriptsdiris not set, it is derived fromstylesdirby replacing the final path segment withscripts.
For example, with :stylesdir: assets/styles, the assets are written as:
-
assets/styles/asciidoctor-carousels.css
-
assets/scripts/asciidoctor-carousels.js
Copyright © 2026-present Asciidoctor Carousels contributors. Use of this software is granted under the terms of the MIT License. See the LICENSE file for the full license text.