Reference

Every option the animate extension accepts.

The complete animate configuration: shortcode arguments, timing attributes, project defaults, validation rules, and the Animate.css behaviour behind them.

Shortcode

{{< animate <effect> "<text>" >}}
{{< animate <effect> "<text>" duration=... delay=... repeat=... stagger=... direction=... >}}
Arguments of the animate shortcode.
Argument Type Required Description
effect string Yes The Animate.css effect to play. See Examples for the full list rendered.
text string Yes The text to animate. Quoted, and plain text only.

Both arguments are positional and both are required. Calling the shortcode without either writes an error and renders nothing.

Note

The text is plain text. It is HTML-escaped before it is written out, so &, <, and quotes survive, but markdown inside it is not parsed: a link written in the second argument comes out as literal characters. Animating a link needs the Animate.css classes written directly on a span or a div.

Options

The same five names work as shortcode attributes and as document or project configuration.

extensions:
  animate:
    duration: 1s
    delay: 1s
    repeat: 1
    stagger: 0s
    direction: normal
Animation options, as shortcode attributes or metadata.
Option Type Default Description
duration CSS time 3s How long one run of the animation takes. Written as an inline style, so any value works exactly.
delay CSS time 2s How long to wait before the animation starts. See the caution below: only whole seconds from 1s to 5s have any effect.
repeat integer or infinite 1 How many times the animation runs. Only 1, 2, 3, and infinite have any effect.
stagger CSS time 0s An increment added to the delay of each successive shortcode in the document, so a run of them animates in sequence.
direction string normal The CSS animation-direction. One of normal, reverse, alternate, alternate-reverse.

An attribute on the shortcode wins over the metadata, and the metadata wins over the defaults above.

A CSS time needs its unit: 2s or 500ms, never a bare number.

What the timing values actually do

duration and direction are written into the span’s style attribute, so they apply exactly as given.

delay and repeat are applied as Animate.css class names instead, and that library only ships a fixed set of them.

Which values reach the output.
Option Classes that exist Everything else
delay 1s, 2s, 3s, 4s, 5s No class matches, so the animation starts immediately.
repeat 1, 2, 3, and infinite No class matches, so the animation runs once.
Caution

A delay of 500ms or 2500ms passes validation, because it is a well-formed CSS time, and then does nothing at all. The same is true of repeat: 7. Neither is reported as a problem: the class is written out and never matched.

There is a second surprise in how Animate.css defines those classes. Each one multiplies a CSS variable rather than setting an absolute value:

.animate__delay-2s { animation-delay: calc(var(--animate-delay) * 2); }
.animate__repeat-2 { animation-iteration-count: calc(var(--animate-repeat) * 2); }

The extension writes --animate-delay and --animate-repeat into a :root block from the first animate shortcode in the document, and every class from then on multiplies them. With delay: 2s the span gets animate__delay-2s on top of a variable of 2s, which resolves to four seconds. With repeat: 2 the same thing happens to the iteration count, which resolves to four runs.

Keeping the first shortcode in the document at delay: 1s and repeat: 1 makes the variables neutral, and every later value then means what it says.

Note

That :root block, carrying --animate-duration, --animate-delay, and --animate-repeat, is written once per document. Later shortcodes still get their own inline duration, but they do not rewrite the variables.

Sequencing with stagger

stagger adds a fixed increment to the delay of each successive shortcode in a document. The first call uses the base delay, the second adds one increment, the third adds two, and so on.

The counter is per document and resets between documents in a project render.

Because the result is expressed as a delay, it inherits the limitation above: an increment that lands anywhere other than a whole second between one and five has no visible effect.

Validation

Every invalid value is reported with a warning and replaced by the default rather than passed through.

Validation rules and what happens when a value fails them.
Rule What is accepted On failure
duration, delay, stagger A CSS time: digits, an optional decimal part, then s or ms. Warns, and the default is used.
repeat A positive integer, or infinite. Warns, and 1 is used.
direction normal, reverse, alternate, alternate-reverse. Warns, and normal is used.
effect One of the Animate.css effect names. Warns, and the shortcode renders nothing, text included.
Warning

Configuring duration, delay, or repeat at the top level of the front matter, rather than under extensions.animate, warns and is then ignored. The extension reads its options from extensions.animate only, so a top-level block silently leaves the defaults in place.

Output

<span class="animate__animated animate__<effect> animate__delay-<delay> animate__repeat-<n>"
      style="display: inline-block;animation-duration:<duration>">text</span>

animate__repeat-<n> becomes animate__infinite when repeat is infinite, and animation-direction joins the style only when direction is not normal.

The extension loads animate.min.css on any HTML format, and additionally animate.js under revealjs, where the animations are triggered as each slide comes into view.

Limitations

  • HTML formats carrying JavaScript only. Everywhere else the shortcode and its text are dropped entirely.
  • Plain text only, as described under Shortcode.
  • delay and repeat are limited to the values Animate.css ships classes for.
Back to top