[Experimental] Transitions for bespoke template

[yhatt]

Warning This is about the first iteration of transition experiement. It is not working in Google Chrome / Chromium 101 and later due to the updated spec of Shared Element Transition API.

Please refer to #447 for the latest spec of transition experiment. (Marp CLI v2.0.0 and later)

See outdated details...

Expreimental transitions are available in Marp CLI v1.4.0 and later + Google Chrome / Chromium 92-100.

This issue is for tracking an experimental transitions support for bespoke template, and the content may change actively. Welcome your feedback about this experiment!

See "Guide" section of this issue for how to use transitions experiment. ⬇️

Quick look

transitions.mov

See a Markdown document of this demo in Gist: https://git.io/JE2GO

Try this command to preview transitions on Marp CLI:

curl -L https://git.io/JE2GO | marp --bespoke.transition -p --no-output

Background

A slide transition is a very common feature in several full-featured presentation tools. However, handling transition tends to become complex due to rendering 2 pages while performing transitions.

Even in a simple case, where content fades from one screen to another, it means rendering your page with both states at once, performing a cross-fade, then removing the old state.

This is harder than it sounds. You need to make sure that the outgoing page can't receive additional interactions, and that the outgoing state doesn't jank the transition by updating its own state. You also need to ensure the presence of both states doesn't create a confusing experience for those using accessibility technology.

― Smooth and simple page transitions with the shared element transition API - Chrome Developers

We believe that holding a complex logic makes hard to maintain the ecosystem, and will bring burnout eventually as like as a classic app. So we had ever not worked on transitions for Marp.

But it becomes a different story if provided a simple solution by the browser. Shared Element Transition API proposal provides a simple and high-level API for transition animations.

By using this proposal, transitions for Marp CLI bespoke template can get both of effective transitions for Marp slides and the ecosystem sustainability.

Guide

Prerequisite

The experimental transition feature is relied on Shared Element Transition API proposal. It is still early phase of proposal and not generally available in the most of browsers at this time.

This API requires Chromium 92 and later, with enabled documentTransition API experiment (chrome://flags/#document-transition or Origin Trials).

You can try experimental transitions easily by using Marp CLI preview window (--preview). The preview window will turn on a depending experiment automatically.

Enable experimental transitions

Add --bespoke.transition option.

marp --bespoke.transition --preview slide.md

The transition feature is bespoke template specific so it would not work in non-HTML format and other templates like bare template.

If you are using a custom engine which have supported transition custom directive like reveal.js based Marpit engine, the output HTML may break due to an overridden directive definition by a CLI option.

transition local directive

To use transition animations, you have to choose a transition effect for slide(s) by defining transition local directive in your Markdown.

---
transition: fade
---

# Slide

As same as other local directives like header and class, you can change the kind of transition in the middle of slides by defining the transition directive through HTML comment, or apply a specific transition into a single slide by using a scoped local directive (_transition: as known as spot directive).

---
transition: fade
---

# Fade transition

---

<!-- transition: cover -->

Changed the kind of transition to `cover`.

---

<!-- _transition: false -->

Disabled transition for this slide.

---

Got back cover transition.

Available effects

• fade
• reveal
• cover
• implode
• explode

Check the video at the top section of this issue.

You also can turn off the transition effect by setting an undefined effect name such as false and none.

Compatibility with Shared Element Transition API

This effect set is based on Shared Element Transition API proposal, and transition directive actually can specify supported effects in API directly.

For example, cover and reveal can specify the direction of transition effect by adding suffix (cover-left, reveal-right).

However, we don't recommend to use an effect with direction because directional keywords may change to logical keywords soon. Marp CLI will transform our unique effect keywords, which have no suffixes, into a compatible effect with API.

Configurable transitions (#425)

Marp CLI v1.6.0 and later versions also allows transition directive configurable by YAML object. It is useful to specify custom duration and delay.

<!--
transition:
  type: fade
  duration: 0.75s
  delay: 250ms
-->

• type (required): The transition type.
• duration (optional): Set the duration of the transition in milliseconds between 0 to 5000.
• delay (optional): Set the delay to start the transition in milliseconds between 0 to 5000.

For better user experience, Marp CLI supports both of ms and s unit in duration and delay.

Helpful resources to know API

• Smooth and simple page transitions with the shared element transition API - Chrome Developers
• WICG/shared-element-transitions
• Shared Element Transitions - Chrome Platform Status
• Shared Element Transitions | CSS-Tricks

Status in Marp CLI

--bespoke.transition is going to keep experimental and optional until Shared Element Transition API proposal makes stable and generally available in at least one of major browsers.

[yhatt]

The spec of transition is going to update drastically in the second iteration of experiment. So I've migrated the issue for details and feedbacks into #447.