Merge pull request marp-team#420 from marp-team/stable-transitions

Update exist blog articles to cover the stable support of transitions
robin536180 · Feb 22, 2023 · 272358a · 272358a
2 parents cc01c60 + 7c5f6f3
commit 272358a
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 47 deletions.
diff --git a/website/blog/202205-ecosystem-update.md b/website/blog/202205-ecosystem-update.md
@@ -14,18 +14,6 @@ We are so excited to introduce a stable release of **[Marp Core](https://github.
 
 <!-- more -->
 
-### Opt in the new core in a VS Code extension
-
-_(Updated in 2022-06-03)_
-
-In [Marp for VS Code](https://github.com/marp-team/marp-vscode) extension, this update is not yet coming to the current extension release, but you can try the new core in [a pre-released major update](https://github.com/marp-team/marp-vscode/releases/v2.0.0). Opt in the pre-released version from a **"Switch to Pre-release Version"** button in the extension detail.
-
-![Marp for VS Code v2 is available as a pre-released version](https://user-images.githubusercontent.com/3993388/171881511-f0e925a5-5b61-417f-b662-60437d1f0233.png ' ')
-
-We have recognized that Marp users who use GUI are including a lot of beginners and non-developers, so we think we should provide enough window time for them to review breaking changes.
-
-Try the pre-release extension, and prepare for the following ecosystem updates! You can easily roll back to the stable version that uses v2 core while the new extension is shipping as pre-release.
-
 # Marp Core v3
 
 [We had released Marp Core v3.0.0 as a release candidate in November 2021.](https://github.com/marp-team/marp-core/releases/tag/v3.0.0) For a half year, it had been available in the `next` tag as an opt-in engine of Marp CLI, and had accepted feedback from the community.
@@ -165,36 +153,46 @@ npx marp ./your-markdown.md
 
 It's useful when your Markdown slide files are not ready for v3 core. But please keep in mind we would hardly provide more updates to v2 core, and **continuous use may bring a risk of unpatched security issues.**
 
-# Slide transition experiment
+# Slide transitions
 
-A really loving part of this CLI update for me is **[a brand-new experimental slide transition in `bespoke` HTML template.](https://github.com/marp-team/marp-cli/issues/447)**
+A really loving part of this CLI update for me is **[a brand-new slide transition in `bespoke` HTML template.](https://github.com/marp-team/marp-cli/issues/447)**
 
 We had started testing experimental slide transition effects since [Marp CLI v1.4.0](https://github.com/marp-team/marp-cli/releases/tag/v1.4.0) (Aug 2021). `--bespoke.transition` CLI option had been working well, but not so practical compared to the common presentation tools.
 
-As a result of catching up on the new spec of [Shared Elemental Transitions proposal](https://github.com/WICG/shared-element-transitions) in Marp CLI v2, I'm so excited to provide powerful transition features that are in no other Markdown slide tools, such as CSS custom transition effects!
+As a result of catching up on the new spec of [View Transitions API proposal][view transitions api] in Marp CLI v2, I'm so excited to provide powerful transition features that are in no other Markdown slide tools, such as CSS custom transition effects and morphing animations!
 
-**Please remember this is a cutting-edge and not stable feature.** There are the demanding browser requirements to work transitions. In addition, the slide transition experiment probably may stop working suddenly due to the upstream API change, or can change the spec without notice.
+[view transitions api]: https://www.w3.org/TR/css-view-transitions-1/
 
-You can track the state of progress at **[marp-team/marp-cli#447](https://github.com/marp-team/marp-cli/issues/447)**.
+> The slide transitions feature has made stable in v2.4.0. You can dive into all about of transitions at [the documentation of Marp CLI transitions][transition-docs].
+
+[transition-docs]: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md
 
 ## Quick look
 
-![Marp CLI experimental transition showcase poster=/assets/202205-ecosystem-update/transition-showcase-poster.jpg controls](https://user-images.githubusercontent.com/3993388/169697466-283dd2f2-b6e5-4b33-86d4-b10cc0a6c3e9.mp4)
+![Marp CLI transition showcase poster=/assets/202205-ecosystem-update/transition-showcase-poster.jpg controls](https://user-images.githubusercontent.com/3993388/169697466-283dd2f2-b6e5-4b33-86d4-b10cc0a6c3e9.mp4)
+
+- **[33 built-in transitions](https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#built-in-transitions)**: Marp CLI provides a lot of transition effects out of the box.
+- **[Define custom transitions via CSS](https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#custom-transitions)**: Markdown author and theme designer can define the custom transition through `@keyframes` declaration in CSS.
+- **[Morphing animations](https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#morphing-animations)**: [`view-transition-name` CSS property](https://www.w3.org/TR/css-view-transitions-1/#view-transition-name-prop) supplied by View Transition API helps to make morphing animation while transition.
 
-- **33 built-in transitions**: Marp CLI has provided a lot of transition effects out of the box.
-- **Define custom transition via CSS**: Markdown author and theme designer can define the custom transition through `@keyframes` declaration in CSS.
-- **Opt-out transitions**: Prefers [`@media (prefers-reduced-motion)` media query](https://developer.mozilla.org/docs/Web/CSS/@media/prefers-reduced-motion) to be able to opt out transition animations.
+## Usage
 
-The experimental slide transitions in HTML output can opt in through `--bespoke.transition` CLI option, and _it is only working in Chrome/Chromium 101 and later with the enabled "documentTransition API" flag._
+The slide transitions in HTML output can opt in and out through `--bespoke.transition` CLI option. _It is only working in the browser that supports [View Transitions API], such as Chrome/Chromium 110 and later._
 
-**Both `--bespoke.transition` and `--preview` are required as a CLI option to see transition effects surely.** Try this to open a preview window for the transition showcase:
+The `--preview` CLI option is helpful see transition effects surely. Try this in Marp CLI v2.4.0+ to open a preview window for the transition showcase:
 
 ```bash
 curl -o ./showcase.md https://gist.githubusercontent.com/yhatt/d9e86ee53eb8816aaf9c996e773b6f82/raw/transition-showcase.md
-marp --bespoke.transition --preview ./showcase.md
+marp --preview ./showcase.md
 ```
 
-> The source Markdown of the showcase is available at Gist: https://gist.github.com/yhatt/d9e86ee53eb8816aaf9c996e773b6f82
+## Showcase
+
+You can see online demo slides about Marp CLI brand new transitions! See them in the browser that supports [View Transitions API].
+
+- **[Marp CLI page transition showcase](https://marp-cli-page-transitions.glitch.me/)**: The showcase of built-in transitions
+- **[Custom transitions example](https://marp-cli-page-transitions.glitch.me/custom.html)**: Some examples and ideas about custom transitions
+- **[Transition with morphing animation](https://marp-cli-page-transitions.glitch.me/morph.html)**: An example of morphing animation powered by [View Transitions API].
 
 ## `transition` local directive
 
@@ -267,10 +265,62 @@ The custom transition can define through just a few conventional [`@keyframes` a
 
 It only has a relatively simple definition(s) but great flexibility, and brings out boundless creativity of CSS animation! 🤩
 
-**[👉 Marp CLI Experimental: How to make custom transition](/blog/how-to-make-custom-transition)**
+**[👉 Marp CLI: How to make custom transition](/blog/how-to-make-custom-transition)**
 
 We are really looking forward to what creative transition effects our community will create!
 
+## Morphing animations
+
+Thanks to the browser's [View Transitions API], we can apply morphing animations during a transition effect. This is similar to PowerPoint Morph and Keynote Magic Move.
+
+Just sprinkle a few CSS properties!
+
+![Morphing animations](https://raw.githubusercontent.com/marp-team/marp-cli/main/docs/bespoke-transitions/images/morphing-animation.gif ' ')
+
+```markdown
+---
+theme: gaia
+transition: fade
+style: |
+  /* ⬇️ Mark the image of "1" in every pages as morphable image named as "one" ⬇️ */
+  img[alt="1"] {
+    view-transition-name: one;
+    contain: layout;
+  }
+
+  /* Generic image styling for number icons */
+  img:is([alt="1"], [alt="2"], [alt="3"]) {
+    height: 64px;
+    position: relative;
+    top: -0.1em;
+    vertical-align: middle;
+    width: 64px;
+  }
+---
+
+# Today's topics
+
+- ![1](https://icongr.am/material/numeric-1-circle.svg?color=666666) Introduction
+- ![2](https://icongr.am/material/numeric-2-circle.svg?color=666666) Features
+- ![3](https://icongr.am/material/numeric-3-circle.svg?color=666666) Conclusion
+
+---
+
+<!-- _class: lead -->
+
+![1 w:256 h:256](https://icongr.am/material/numeric-1-circle.svg?color=ff9900)
+
+# Introduction
+
+---
+
+# ![1](https://icongr.am/material/numeric-1-circle.svg?color=666666) Introduction
+
+Marp is an open-sourced Markdown presentation ecosystem.
+```
+
+**[👉 See details at the documentation about transitions on Marp CLI repository...](https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#morphing-animations)**
+
 # Deprecations
 
 Finally, we have to mention that the latest update has a deprecated Markdown syntax in the Marp ecosystem. It is still can use for now with deprecation warnings and will be obsolete in future Marp tools.

diff --git a/website/blog/how-to-make-custom-transition.md b/website/blog/how-to-make-custom-transition.md
@@ -1,18 +1,19 @@
 ---
-title: 'Marp CLI Experimental: How to make custom transition'
+title: 'Marp CLI: How to make custom transition'
 date: 2022-05-28
-description: Marp CLI v2 has experimental support for page transitions with many useful built-in effects. But if you had not satisfied with any effects? Make your effects with CSS!
+description: Marp CLI v2.4.0+ and Marp for VS Code v2.5.0+ have a stable support for page transitions with many useful built-in effects. But if you had not satisfied with any effects? Make your effects with CSS!
 author: Yuki Hattori
 github: yhatt
 image: /og-images/how-to-make-custom-transition.jpg
 ---
 
-[built-in]: https://github.com/marp-team/marp-cli/issues/447#built-in
-[transition-proposal]: https://github.com/WICG/shared-element-transitions
+[readme]: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md
+[built-in]: https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#built-in-transitions
+[view transitions api]: https://www.w3.org/TR/css-view-transitions-1/
 
-**[Marp CLI v2](/blog/202205-ecosystem-update#marp-cli-v2)** has supported [brand-new page transitions for a `bespoke` HTML template as experimental](/blog/202205-ecosystem-update#slide-transition-experiment).
+**[Marp CLI v2](/blog/202205-ecosystem-update#marp-cli-v2)** has supported [brand-new page transitions for the `bespoke` HTML template](/blog/202205-ecosystem-update#slide-transition-experiment). You can use this stable transition support in either Marp CLI v2.4.0+ or Marp for VS Code v2.5.0+.
 
-Effective transitions will help make a dramatic presentation. Adding a touch of effects to slides is often common in great talks. By using Marp CLI with `--bespoke.transition` (and `--preview`) option, you can start to use [varied 33 transition effects][built-in] out of the box, by [just a simple definition `transition` directive](/blog/202205-ecosystem-update#transition-local-directive).
+Effective transitions will help make a dramatic presentation. Adding a touch of effects to slides is often common in great talks. By viewing HTML slide in the browser that supports [View Transitions API] (Chrome 111+), or Marp CLI with `--preview` option, you can start to use [varied 33 transition effects][built-in] out of the box, by [just a simple definition `transition` directive](https://github.com/marp-team/marp-cli/blob/main/docs/bespoke-transitions/README.md#transition-local-directive).
 
 Built-in transitions should be useful for 90% of Marp users. But what you can do if there are no effects you are satisfied with? Make your effects in CSS! Marp can register your custom animation set declared in CSS as a named transition, and use it in the Markdown slide.
 
@@ -26,13 +27,11 @@ This article will describe the following things:
 1. **[Declare custom transitions](#declare-custom-transitions)**: How to register custom transitions by CSS
 1. **[Helpful tips for making your transition](#tips)**
 
-_If using [built-in transitions made by us][built-in] was enough, you don't need to read this article._ Please save your time, with keeping enjoying our transitions in your Markdown slide! :)
-
-> The word "transition" in this article is meaning the slide transition effect in Marp, not meaning [`transition` property in CSS](https://developer.mozilla.org/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions).
+[See also the official documentation about transitions in Marp CLI.][readme]
 
-### Warning: Transition is experimental
+_If using [built-in transitions made by us][built-in] was enough, you don't need to read this article._ Please save your time, with keeping enjoying our transitions in your Markdown slide! :)
 
-An _experimental_ transition is a cutting-edge feature that is depending on [Shared Element Transitions proposal for Web][transition-proposal] and may change the spec in the future. Before trying to use transitions, _you **must** read [a GitHub issue about this feature](https://github.com/marp-team/marp-cli/issues/447) through!_
+> In this article, the word "transition" is meaning the slide transition effect in Marp. Please note that it is not meaning [`transition` property in CSS](https://developer.mozilla.org/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions).
 
 # The anatomy of a transition
 
@@ -107,10 +106,10 @@ Well, declare animation details at keyframes. In a simple declaration, you only
 
 > This example has been declared `from` keyframe for clarity, but you can omit it because `opacity: 1` is a default style.
 
-Did you want more? That's it! Try to test this transition in [a preview window](https://github.com/marp-team/marp-cli#preview-window---preview---p).
+Did you want more? That's it! Try to test this transition in the HTML slide with the browser that supports [View Transitions API], or [a preview window in Marp CLI](https://github.com/marp-team/marp-cli#preview-window---preview---p).
 
 ```bash
-npx @marp-team/marp-cli@^2 --bespoke.transition --preview ./transition.md
+npx @marp-team/marp-cli@^2.4.0 --preview ./transition.md
 ```
 
 You have made the first custom transition!
@@ -192,7 +191,7 @@ And now, the slide-up custom transition is working completely in both directiona
 
 ![Slide up transition with correct directions](/assets/how-to-make-custom-transition/slide-up-correct-direction.gif ' ')
 
-> NOTE: Any other CSS variables defined in the context of Marp cannot use in keyframes.
+> NOTE: Any other CSS variables defined in the context of animation keyframes cannot use in keyframes.
 
 ### Set custom animations for backward transition
 
@@ -255,8 +254,6 @@ Each transition has a linear easing by default. You can specify [`animation-timi
 
 ## Duration
 
-_(2022-06-08 Update)_
-
 We have a fixed duration time of `0.5s` as default for every transition. If you want to set a different default duration for your custom transition, please set `--marp-transition-duration` property in the first keyframe (`from` or `0%`).
 
 <!-- prettier-ignore-start -->
@@ -291,8 +288,6 @@ We have a fixed duration time of `0.5s` as default for every transition. If you
 
 The slide author can override the default duration at any time, through the `transition` local directive in Markdown (`<!-- transition: fade 2s -->`).
 
-> Setting custom default duration is available in [Marp CLI v2.0.4](https://github.com/marp-team/marp-cli/releases/tag/v2.0.4) and later.
-
 ## Fixed property
 
 If some of the properties required a fixed value while playing transition, try to set the same declaration into `from` (0%) and `to` (100%).
@@ -372,10 +367,8 @@ If you want to swap the order of layers during animation, try to animate `z-inde
 
 # Try it!
 
-Marp CLI transition experiment, backed by [Shared Element Transition API proposal for Web][transition-proposal], provides flexibility to design your talk as you like. Custom transition brings out your boundless creativity, without complex codings, just declarative definitions in CSS.
+Transitions for Marp CLI's bespoke template backed by [View Transitions API] in the browser, provides flexibility to design your talk as you like. Custom transition brings out your boundless creativity, without complex JS codings, just declarative definitions in CSS.
 
 We are really looking forward to what creative transition effects our community will create!
 
 Share the custom transition you've made with [Marp community](https://github.com/orgs/marp-team/discussions). You can provide custom theme CSS including a bunch of custom transitions too.
-
-> Again, **the transition feature is still experimental**. Before starting to use transitions, _you **must** read [a GitHub issue](https://github.com/marp-team/marp-cli/issues/447) through._ Any feedbacks are welcome!
diff --git a/website/public/og-images/how-to-make-custom-transition.jpg b/website/public/og-images/how-to-make-custom-transition.jpg