mirror of
https://github.com/marp-team/marp.git
synced 2024-09-11 10:35:38 +03:00
Merge pull request #313 from marp-team/fix-grammar
Fix grammar in new blog articles
This commit is contained in:
Yuki Hattori
GitHub
commit
6e20e2f6f9
@ -1,44 +1,44 @@
|
||||
---
|
||||
title: 'Ecosystem update: Marp Core v3 & Slide transitions in CLI v2'
|
||||
date: 2022-05-26
|
||||
description: Introduce a stable release of Marp Core v3, and updated CLI v2 with entirely new slide transition experiment.
|
||||
description: Introduce a stable release of Marp Core v3, and updated CLI v2 with an entirely new slide transition experiment.
|
||||
author: Yuki Hattori
|
||||
github: yhatt
|
||||
image: /og-images/202205-ecosystem-update.jpg
|
||||
---
|
||||
|
||||
We are so excited to introduce a stable release of **[Marp Core](https://github.com/marp-team/marp-core) v3**, and **[Marp CLI](https://github.com/marp-team/marp-cli) v2** update with [entirely new slide transition experiment](#slide-transition-experiment).
|
||||
We are so excited to introduce a stable release of **[Marp Core](https://github.com/marp-team/marp-core) v3**, and **[Marp CLI](https://github.com/marp-team/marp-cli) v2** update with [an entirely new slide transition experiment](#slide-transition-experiment).
|
||||
|
||||
- **[Marp Core v3](#marp-core-v3)**: MathJax rendering as default, updated `default` theme, and new components for auto-scaling.
|
||||
- **[Marp CLI v2](#marp-cli-v2)**: Bundled core v3, and [brand-new slide transition experiment](#slide-transition-experiment) with 33 built-in effects + CSS custom transitions.
|
||||
|
||||
<!-- more -->
|
||||
|
||||
> I would like to mention beforehand; **Following updates are not coming to [Marp for VS Code](https://github.com/marp-team/marp-vscode) extension** at the time of publication of this article. We have recognized Marp users using with GUI are including a lot of beginners and non-developers, so we think should provide an enough window time to them to review breaking changes.
|
||||
> I would like to mention beforehand; **Following updates are not coming to [Marp for VS Code](https://github.com/marp-team/marp-vscode) extension** at the time of publication of this article. We have recognized Marp users using GUI are including a lot of beginners and non-developers, so we think should provide enough window time for them to review breaking changes.
|
||||
>
|
||||
> Currently we are planning that v3 core would be available as [pre-release extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions), and you would become able to toggle opt in and out v3 features. ([marp-team/marp-vscode#318](https://github.com/marp-team/marp-vscode/issues/318))
|
||||
> Currently, we are planning that v3 core would be available as [pre-release extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions), and you would become able to toggle opt in and out v3 features. ([marp-team/marp-vscode#318](https://github.com/marp-team/marp-vscode/issues/318))
|
||||
|
||||
# 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 `next` tag as opt-in engine of Marp CLI, and had accepted feedbacks from community.
|
||||
[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.
|
||||
|
||||
This month [v3.2.0](https://github.com/marp-team/marp-core/releases/tag/v3.2.0) has become a stable release, and **we are starting a work to make v3 core the default in downstream Marp tools gradually.**
|
||||
This month [v3.2.0](https://github.com/marp-team/marp-core/releases/tag/v3.2.0) has become a stable release, and **we are starting work to make v3 core the default in downstream Marp tools gradually.**
|
||||
|
||||
An updated Marp Core v3 has some major changes, but we also have worked to keep backward compatibility in many exist slides. The most of slide authors should not concern about regressions as long as your tweaks to the slide theme are not complicated.
|
||||
An updated Marp Core v3 has some major changes, but we also have worked to keep backward compatibility in many existing slides. Most slide authors should not be concerned about regressions as long as your tweaks to the slide theme are not complicated.
|
||||
|
||||
If you are theme author, you may have to modify some of styles. This update includes brand-new auto scaling component, the change of `default` theme caused by update of [`github-markdown-css`](https://github.com/sindresorhus/github-markdown-css), and so on.
|
||||
If you are a theme author, you may have to modify some of the styles. This update includes a brand-new auto scaling component, the change of `default` theme caused by the update of [`github-markdown-css`](https://github.com/sindresorhus/github-markdown-css), and so on.
|
||||
|
||||
Even so, you should not too worry: We worked to v3 core to reduce friction between Marp's CSS and common CSS, so I think the complex part of our theming system (e.g. styling auto-scaled element) must be easier to understand than v2.
|
||||
|
||||
## Notable changes
|
||||
|
||||
### Drop support for End-of-Lifed Node.js
|
||||
### Drop support for End-of-Life Node.js
|
||||
|
||||
First, Marp Core v3 has dropped support for end-of-lifed Node.js 10.
|
||||
First, Marp Core v3 has dropped support for end-of-life Node.js 10.
|
||||
|
||||
We have supported EoL Node.js v12 yet, but continuous support may not guarantee depending on support status of dependency modules. We recommend to follow up [the active LTS Node.js](https://nodejs.org/).
|
||||
We have supported EoL Node.js v12 yet, but continuous support may not guarantee depending on the support status of dependency modules. We recommend following up on [the active LTS Node.js](https://nodejs.org/).
|
||||
|
||||
> Check out https://endoflife.date/nodejs to know which version of Node.js are EoL
|
||||
> Check out https://endoflife.date/nodejs to know which version of Node.js is EoL.
|
||||
|
||||
### MathJax is a default typesetting library for math
|
||||
|
||||
@ -47,17 +47,17 @@ We have supported EoL Node.js v12 yet, but continuous support may not guarantee
|
||||
|
||||
Marp Core v3 has changed the default library for rendering math, from [KaTeX] to [MathJax].
|
||||
|
||||
Marp had used [KaTeX] as a default library for a long years by taking performance. But currently this opinion has become a thinking of past by the advent of MathJax 3. [See this interesting insights.](https://groups.google.com/g/mathjax-users/c/aboJLMb50uQ/m/Y77FexF_AwAJ)
|
||||
Marp had used [KaTeX] as a default library for long years for taking better performance. But currently, this opinion has become the past thinking with the advent of MathJax 3. [See this interesting insight.](https://groups.google.com/g/mathjax-users/c/aboJLMb50uQ/m/Y77FexF_AwAJ)
|
||||
|
||||
And some incompatibillities of KaTeX with Marp Core's auto scaling feature that are hard to fix had given our headache. ([marp-team/marp-core#159](https://github.com/marp-team/marp-core/issues/159), [marp-team/marp-core#236](https://github.com/marp-team/marp-core/issues/236))
|
||||
And some incompatibilities of KaTeX with Marp Core's auto scaling feature that are hard to fix had given us a headache. ([marp-team/marp-core#159](https://github.com/marp-team/marp-core/issues/159), [marp-team/marp-core#236](https://github.com/marp-team/marp-core/issues/236))
|
||||
|
||||
MathJax implementation in Marp Core has more reliable rendering than KaTeX. In addition, it also has more TeX function supports, and no network required to show.
|
||||
MathJax implementation in Marp Core has more reliable rendering than KaTeX. In addition, it also has more TeX function supports, and no network is required to show.
|
||||
|
||||
Currently a lot of Markdown flavors have adopted MathJax for math typesetting (e.g. [GitHub](https://github.blog/2022-05-19-math-support-in-markdown/)), and we expect Marp Markdown would get higher compatibility in several Markdown services.
|
||||
Now a lot of Markdown flavors have adopted MathJax for math typesetting (e.g. [GitHub](https://github.blog/2022-05-19-math-support-in-markdown/)), and we expect Marp Markdown would get higher compatibility in several Markdown services.
|
||||
|
||||
#### `math` global directive
|
||||
|
||||
If your Markdown is not yet ready to migrate math typesettings into MathJax, you can continue to use KaTeX as math typesetting library by setting [`math` global directive](https://github.com/marp-team/marp-core#math-global-directive) as `katex`.
|
||||
If your Markdown is not yet ready to migrate math typesettings into MathJax, you can continue to use KaTeX as a math typesetting library by setting [`math` global directive](https://github.com/marp-team/marp-core#math-global-directive) as `katex`.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@ -67,23 +67,23 @@ math: katex
|
||||
Continue to use KaTeX: $ax^2+bc+c$
|
||||
```
|
||||
|
||||
We have no plans to remove KaTeX integration for a while. So you can keep to render math with KaTeX if you're using KaTeX specific syntaxes or met rendering performance issue in MathJax.
|
||||
We have no plans to remove KaTeX integration for a while. So you can keep rendering math with KaTeX if you're using KaTeX specific syntaxes or met rendering performance issues in MathJax.
|
||||
|
||||
> For smooth migration of exist slides to v3, Marp for VS Code is [annotating to math use without `math` global directive](https://github.com/marp-team/marp-vscode#diagnostics) since a year ago.
|
||||
|
||||
### Renewed auto-scaling component
|
||||
|
||||
Marp Core has a tiny runtime script to activate element auto-scaling for code block, math block, and [fitting header `# <!--fit--> header`](https://github.com/marp-team/marp-core#fitting-header). v3 has updated auto scaling logic into [Web Components](https://developer.mozilla.org/docs/Web/Web_Components) based, to improve output lucidity and compatibility with CSS selector.
|
||||
Marp Core has a tiny runtime script to activate element auto-scaling for a code block, math block, and [fitting header `# <!--fit--> header`](https://github.com/marp-team/marp-core#fitting-header). v3 has updated auto scaling logic into [Web Components](https://developer.mozilla.org/docs/Web/Web_Components) based, to improve output lucidity and compatibility with some CSS selectors.
|
||||
|
||||
This update does not change the actual auto-scaling behavior from v2, so most of Markdown slide authors should not need to take care that. But if you have the custom theme that was styled to auto-scaling elements, you should review and modify CSS declarations in your theme to suit to v3.
|
||||
This update does not change the actual auto-scaling behavior from v2, so most Markdown slide authors should not need to take care of that. But if you have a custom theme that was styled to auto-scaling elements, you should review and modify CSS declarations in your theme to match with v3.
|
||||
|
||||
Please refer to the pull request **[marp-team/marp-core#263](https://github.com/marp-team/marp-core/pull/263)** for details of auto-scaling components.
|
||||
|
||||
### Updated `default` theme
|
||||
|
||||
To provide familiar Markdown style to users as default, Marp Core `default` theme is based on [GitHub's Markdown CSS](https://github.com/sindresorhus/github-markdown-css).
|
||||
To provide a familiar Markdown style to users as default, Marp Core `default` theme is based on [GitHub's Markdown CSS](https://github.com/sindresorhus/github-markdown-css).
|
||||
|
||||
The latest Marp Core has included following updates about `default` theme:
|
||||
The latest Marp Core has included the following updates about `default` theme:
|
||||
|
||||
- Updated color schemes based on the latest [github-markdown-css v5](https://github.com/sindresorhus/github-markdown-css)
|
||||
- Match colors for code highlight with GitHub style
|
||||
@ -117,9 +117,9 @@ based on GitHub dark mode
|
||||
|
||||
### URL without HTTP(S) scheme does no longer auto-linkify
|
||||
|
||||
Marp Core up to v2 had detected URL-like string and, convert to hyperlink automatically. However, that was too fuzzy and often brought linkify in not intended words, such as "[Amazon.com](https://amazon.com/)" and "[ML.NET](https://dotnet.microsoft.com/apps/machinelearning-ai/ml-dotnet)".
|
||||
Marp Core up to v2 had detected URL-like strings and converted them to hyperlinks automatically. However, that was too fuzzy and often brought linkify in not intended words, such as "[Amazon.com](https://amazon.com/)" and "[ML.NET](https://dotnet.microsoft.com/apps/machinelearning-ai/ml-dotnet)".
|
||||
|
||||
But there are no any more fuzzy links in v3! Now auto link feature requires the URL string with `https://` or `http://` scheme.
|
||||
But there are no more fuzzy links in v3! Now auto link feature requires the URL string with `https://` or `http://` scheme.
|
||||
|
||||
Please make a Markdown link `[Amazon.com](https://amazon.com/)` explicitly if you want the hyperlink in previously auto-linked words.
|
||||
|
||||
@ -127,7 +127,7 @@ Please make a Markdown link `[Amazon.com](https://amazon.com/)` explicitly if yo
|
||||
|
||||
According to the time to become core v3 stable, we also worked on **[a major update of Marp CLI](https://github.com/marp-team/marp-cli/releases/tag/v2.0.0)** to bundle a new core.
|
||||
|
||||
There are no major changes in general usage of Marp CLI, and I believe your CLI workflow would never break by this updation in most cases.
|
||||
There are no major changes in the general use of Marp CLI, and I believe your CLI workflow would never break by this updation in most cases.
|
||||
|
||||
So what feature is a "major" update of CLI? [_Perhaps you may have interested in a hidden gem..._ 💎](#slide-transition-experiment)
|
||||
|
||||
@ -148,24 +148,24 @@ $ marp --version
|
||||
|
||||
###### Continue to use v2 core in Marp CLI
|
||||
|
||||
We recommend to get ready for using updated v3 core, but Marp CLI also can stick to v2 core by installing `@marp-team/marp-core@^2` to your project individually.
|
||||
We recommend getting ready for using the updated v3 core, but Marp CLI also can stick to the v2 core by installing `@marp-team/marp-core@^2` to your project individually.
|
||||
|
||||
```bash
|
||||
npm i --save-dev @marp-team/marp-cli @marp-team/marp-core@^2
|
||||
npx marp ./your-markdown.md
|
||||
```
|
||||
|
||||
It's useful when your Markdown slide files are not ready to 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.**
|
||||
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
|
||||
|
||||
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)**
|
||||
|
||||
We had been 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 by compared to the common presentation tools.
|
||||
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 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 is in no any other Markdown slide tools, such as CSS custom transition effects!
|
||||
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!
|
||||
|
||||
**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 by the upstream API change, or can change the spec without notice.
|
||||
**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.
|
||||
|
||||
You can track the state of progress at **[marp-team/marp-cli#447](https://github.com/marp-team/marp-cli/issues/447)**.
|
||||
|
||||
@ -177,9 +177,9 @@ You can track the state of progress at **[marp-team/marp-cli#447](https://github
|
||||
- **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.
|
||||
|
||||
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 enabled "documentTransition API" flag._
|
||||
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._
|
||||
|
||||
**Both of `--bespoke.transition` and `--preview` are required as a CLI option to see transition effects surely.** Try this commands to open a preview window for the transition showcase:
|
||||
**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:
|
||||
|
||||
```bash
|
||||
curl -o ./showcase.md https://gist.githubusercontent.com/yhatt/d9e86ee53eb8816aaf9c996e773b6f82/raw/transition-showcase.md
|
||||
@ -216,7 +216,7 @@ Disabled transition for this slide
|
||||
Got back to cover transition
|
||||
```
|
||||
|
||||
Each transitions have a default 0.5s duration, but you can also set custom duration by space-separated value such as `<!-- transition: fade 1s -->`.
|
||||
Each transition has a default 0.5s duration, but you can also set custom duration by space-separated value such as `<!-- transition: fade 1s -->`.
|
||||
|
||||
## Custom transition
|
||||
|
||||
@ -257,7 +257,7 @@ The custom transition can define through just a few conventional [`@keyframes` a
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
It only has a relatively simple definition(s) but great flexibillity, and brings out boundless creativity of CSS animation! 🤩
|
||||
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)**
|
||||
|
||||
@ -265,19 +265,19 @@ We are really looking forward to what creative transition effects our community
|
||||
|
||||
# Deprecations
|
||||
|
||||
Finally, we have to mention that the latest update has a deprecated Markdown syntax in Marp ecosystem. It is still can use for now with deprecation warnings, and will be obsolete in future Marp tools.
|
||||
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.
|
||||
|
||||
> We have planned to work on [an auto-fixable diagnostic for VS Code extension](https://github.com/marp-team/marp-vscode#diagnostics), to make easier update use of deprecated syntaxes.
|
||||
> We have planned to work on [an auto-fixable diagnostic for VS Code extension](https://github.com/marp-team/marp-vscode#diagnostics), to make it easier to update the use of deprecated syntaxes.
|
||||
|
||||
### Shorthand for setting colors (Marpit framework)
|
||||
|
||||
[Marpit framework](https://marpit.marp.app/) had been provided the color setting shorthand through Markdown image syntax, such as `` and ``. This syntax had been allowed to set a corresponding color style like `color: red` and `background-color: yellow` to only a current slide page.
|
||||
|
||||
These are rarely used in reality, and now we have considered as harmful in the point of view from Markdown (CommonMark) compatibility.
|
||||
These are rarely used in reality, and now we have considered as harmful from the point of view of Markdown (CommonMark) compatibility.
|
||||
|
||||
Marpit framework has already provided [`color` / `backgroundColor` local directives](https://marpit.marp.app/directives?id=backgrounds), and setting [scoped local directives](https://marpit.marp.app/directives?id=apply-to-a-single-page-spot-directives) to the slide will bring exactly same result.
|
||||
Marpit framework has already provided [`color` / `backgroundColor` local directives](https://marpit.marp.app/directives?id=backgrounds), and setting [scoped local directives](https://marpit.marp.app/directives?id=apply-to-a-single-page-spot-directives) to the slide will bring the same result.
|
||||
|
||||
If you are using these shorthands for setting colors, please replace into the alternative scoped local directive.
|
||||
If you are using these shorthands for setting colors, please replace them with the alternative scoped local directive.
|
||||
|
||||
| Shorthands | Should replace to |
|
||||
| :----------: | :------------------------------: |
|
||||
@ -288,7 +288,7 @@ If you are using these shorthands for setting colors, please replace into the al
|
||||
|
||||
# Community
|
||||
|
||||
Join the Marp community! Our [GitHub Discussions](https://github.com/orgs/marp-team/discussions) is a community forum gathered discussions all about Marp, and allows you to connect with Marp team and other Marp users. Of course, we are welcome your feedback for this ecosystem update too. 😀
|
||||
Join the Marp community! Our [GitHub Discussions](https://github.com/orgs/marp-team/discussions) is a community forum that gathered discussions all about Marp, and allows you to connect with Marp team and other Marp users. Of course, we welcome your feedback for this ecosystem update too. 😀
|
||||
|
||||
- [**Go to GitHub Discussions**](https://github.com/orgs/marp-team/discussions)
|
||||
- [The support guideline of Marp project](https://github.com/marp-team/.github/blob/master/SUPPORT.md)
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
title: 'Marp CLI Experimental: How to make custom transition'
|
||||
date: 2022-05-28
|
||||
description: Marp CLI v2 has an experimental support for page transitions with many useful built-in effects. But if you had not satisfied to any effects? Make your own effects with CSS!
|
||||
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!
|
||||
author: Yuki Hattori
|
||||
github: yhatt
|
||||
image: /og-images/how-to-make-custom-transition.jpg
|
||||
@ -10,41 +10,41 @@ 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
|
||||
|
||||
**[Marp CLI v2](/blog/202205-ecosystem-update#marp-cli-v2)** has supported [brand-new page transitions for `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 a `bespoke` HTML template as experimental](/blog/202205-ecosystem-update#slide-transition-experiment).
|
||||
|
||||
Effective transitions will be helpful making 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 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).
|
||||
|
||||
Built-in transitions should be useful for 90% of Marp users. But what you can do if there are no effects you are satisfied? Make your own effects in CSS! Marp can register your custom animation set declared in CSS as a named transition, and use it in the Markdown slide.
|
||||
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.
|
||||
|
||||
<!-- more -->
|
||||
|
||||
### Index
|
||||
|
||||
This article will describe following things:
|
||||
This article will describe the following things:
|
||||
|
||||
1. **[The anatomy of a transition](#the-anatomy-of-a-transition)**: How the transition effect will work in Marp
|
||||
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 enjoy our transitions in your Markdown slide! :)
|
||||
_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! :)
|
||||
|
||||
> A word of "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).
|
||||
> 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).
|
||||
|
||||
### Warning: Transition is experimental
|
||||
|
||||
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!_
|
||||
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!_
|
||||
|
||||
# The anatomy of a transition
|
||||
|
||||
The first what the custom transition author has to know is "How the page transition effect is realized in a presentation slide".
|
||||
|
||||
Let's consider about what happening when the slide page was navigated from page 1 to 2. If no transitions were set to the slide, the first page will just disappear, and appear the second page immediately. If it has a transition effect, a certain time for playing animations will insert between switching pages.
|
||||
Let's consider what is happening when the slide page was navigated from 1 to 2. If no transitions were set to the slide, the first page will just disappear, and appear on the second page immediately. If it has a transition effect, a certain time for playing animations will insert between switching pages.
|
||||
|
||||
|
||||
|
||||
An important thing during transition is that 2 slides are presenting in the view at the same time like layers. All kind of effects produce smooth transition by applying specific animations to one or both slides.
|
||||
An important thing during transition is that 2 slides are presented in the view at the same time like layers. All kinds of effects produce smooth transitions by applying specific animations to one or both slides.
|
||||
|
||||
In Marp, the slide page that was shown before transition calls as **"Outgoing slide"**, and the next page to appear after transition calls as **"Incoming slide"**. Slide pages may have in a inverse relation when brought the backward navigation, but meaning of incoming slide and outgoing slide are always consistent.
|
||||
In Marp, the slide page that was shown before transition calls as **"Outgoing slide"**, and the next page to appear after transition calls as **"Incoming slide"**. Slide pages may have an inverse relationship when brought the backward navigation, but the meaning of "incoming" and "outgoing" is always consistent.
|
||||
|
||||
If you could figure them out, you probably also grasp that you have to respect the following 2 principles:
|
||||
|
||||
@ -59,14 +59,14 @@ If either or both was not respected in a transition effect, it would become a we
|
||||
|
||||
## Simple keyframe declaration
|
||||
|
||||
Let's get started from a simple keyframe declaration for [the dissolve effect (also known as cross-fade effect)](<https://en.wikipedia.org/wiki/Dissolve_(filmmaking)>), to learn how to set custom transition animation. Marp uses [a standard syntax for CSS animation `@keyframes`](https://developer.mozilla.org/docs/Web/CSS/@keyframes) to declare transitions.
|
||||
Let's get started with a simple keyframe declaration for [the dissolve effect (also known as the cross-fade effect)](<https://en.wikipedia.org/wiki/Dissolve_(filmmaking)>), to learn how to set custom transition animation. Marp uses [standard syntax for CSS animation `@keyframes`](https://developer.mozilla.org/docs/Web/CSS/@keyframes) to declare transitions.
|
||||
|
||||
When applied the dissolve effect to transition principles, you can derive that the effect needs these animations:
|
||||
When applying the dissolve effect to transition principles, you can derive that the effect needs these animations:
|
||||
|
||||
- The outgoing slide has an animation to **decrease opacity from 100% to 0%**.
|
||||
- The incoming slide has an animation to **increase opacity from 0% to 100%**.
|
||||
|
||||
There are opposite changes with each other. In this case, you can define animations for both slide layers by a one `@keyframes` declaration.
|
||||
There are opposite changes with each other. In this case, you can define animations for both slide layers by one `@keyframes` declaration.
|
||||
|
||||
First, declare `@keyframes` at-rule with the conventional name specified by Marp in your Markdown.
|
||||
|
||||
@ -88,11 +88,11 @@ style: |
|
||||
# Slide 2
|
||||
```
|
||||
|
||||
**`marp-transition-xxxxxxxx`** is the rule of animation name to register the transition with simple declaration. For using declared transition in Marp slide, assign `transition`local directive with the name declared in `xxxxxxxx`.
|
||||
**`marp-transition-xxxxxxxx`** is the rule of animation name to register the transition with a simple declaration. For using declared transition in Marp slide, assign `transition` local directive with the name declared in `xxxxxxxx`.
|
||||
|
||||
> This example is using [`style` global directive](https://marpit.marp.app/directives?id=tweak-theme-style) to declare keyframes. Of course, you also can use [inline `<style>` element](https://marpit.marp.app/theme-css?id=tweak-style-through-markdown) or [custom theme CSS](https://marpit.marp.app/theme-css) to declare.
|
||||
> This example is using [`style` global directive](https://marpit.marp.app/directives?id=tweak-theme-style) to declare keyframes. Of course, you also can use [the inline `<style>` element](https://marpit.marp.app/theme-css?id=tweak-style-through-markdown) or [custom theme CSS](https://marpit.marp.app/theme-css) to declare.
|
||||
|
||||
Well, declare animation details at keyframes. In a simple declaration, you only have to set animation for the outgoing slide. For the incoming slide, Marp will set an animation with reverse direction automatically.
|
||||
Well, declare animation details at keyframes. In a simple declaration, you only have to set animation for the outgoing slide. For the incoming slide, Marp will set the animation in the reverse direction automatically.
|
||||
|
||||
```css
|
||||
@keyframes marp-transition-dissolve {
|
||||
@ -105,9 +105,9 @@ Well, declare animation details at keyframes. In a simple declaration, you only
|
||||
}
|
||||
```
|
||||
|
||||
> This example has declared `from` keyframe for clarity, but you can omit `from` declaration because `opacity: 1` is a default style.
|
||||
> This example has been declared `from` keyframe for clarity, but you can omit it because `opacity: 1` is a default style.
|
||||
|
||||
You wanted 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 [a preview window](https://github.com/marp-team/marp-cli#preview-window---preview---p).
|
||||
|
||||
```bash
|
||||
npx @marp-team/marp-cli@^2 --bespoke.transition --preview ./transition.md
|
||||
@ -117,19 +117,18 @@ You have made the first custom transition!
|
||||
|
||||
|
||||
|
||||
In this article, the example is simplified for teaching how to make a custom transition, and there is a bit diffirence from built-in transition `fade` for getting the same effect. `dissolve` effect is looking good, but actually there is [a general pitfall about cross fading](https://jakearchibald.com/2021/dom-cross-fade/).
|
||||
In this article, the example is simplified for teaching how to make a custom transition, and there is a bit of difference from the built-in transition `fade` for getting the same effect. `dissolve` effect is looking good, but there is [a general pitfall about cross fading](https://jakearchibald.com/2021/dom-cross-fade/).
|
||||
|
||||
## Split animations into outgoing and incoming
|
||||
|
||||
A simple declaration should work in some of transition types well, but it's not that all of transitions have exactly contrary animations with each other. In reality different animations to the outgoing slide and incoming slide are required in most cases.
|
||||
A simple declaration should work in some transition types well, but it's not that all transitions have exactly contrary animations to each other. In reality, different animations for the outgoing slide and incoming slide are required in most cases.
|
||||
|
||||
For example, the slide up effect must have these animations:
|
||||
|
||||
- The outgoing slide should **move from the viewport to the upper outer**.
|
||||
- The incoming slide should **move from the lower outer to the viewport**.
|
||||
|
||||
So you can declare splitted animations for each layers rather than declaring a single keyframes.
|
||||
Set `@keyframes` with the prefix of the target transition: **`marp-outgoing-transition-xxxxxxxx`** and **`marp-incoming-transition-xxxxxxxx`**.
|
||||
So you can declare split animations for each layer rather than declaring a single animation. Set `@keyframes` with the prefix of the target transition: **`marp-outgoing-transition-xxxxxxxx`** and **`marp-incoming-transition-xxxxxxxx`**.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@ -154,17 +153,17 @@ style: |
|
||||
# Slide 2
|
||||
```
|
||||
|
||||
Unlike the simple transition, there is no auto-reversed animation in the incoming slide. Each keyframes should define animation with the right direction.
|
||||
Unlike the simple transition, there is no auto-reversed animation in the incoming slide. Each animation should define in the right direction.
|
||||
|
||||
|
||||
|
||||
## Transition for backward navigation
|
||||
|
||||
If you have been tested the above slide-up transition example, you may have noticed that is having a move to up also when slide navigation going to back has occured.
|
||||
If you have tested the above slide-up transition example, you may have noticed that is having a move to up also when slide navigation going to back has occurred.
|
||||
|
||||
|
||||
|
||||
It brings a wrong user interaction and not intuitive. You should want to provide the animation for correct direction when occurred backward navigation.
|
||||
It brings a wrong user interaction and is not intuitive. You should want to provide the animation for the correct direction when occurred backward navigation.
|
||||
|
||||
We are providing several solutions to deal with this.
|
||||
|
||||
@ -172,7 +171,7 @@ We are providing several solutions to deal with this.
|
||||
|
||||
While playing transition, `--marp-transition-direction` [CSS custom property (as known as CSS variables)](https://developer.mozilla.org/docs/Web/CSS/Using_CSS_custom_properties) will be available in `@keyframes`.
|
||||
|
||||
It provides `1` in forward navigation, or `-1` in backward navigation. Using [`var(--marp-transition-direction)`](https://developer.mozilla.org/docs/Web/CSS/var) together with [`calc()`](https://developer.mozilla.org/docs/Web/CSS/calc) function would be useful to calculate the position in response to the direction of slide navigation.
|
||||
It provides `1` in forwarding navigation, or `-1` in backward navigation. Using [`var(--marp-transition-direction)`](https://developer.mozilla.org/docs/Web/CSS/var) together with [`calc()`](https://developer.mozilla.org/docs/Web/CSS/calc) function would be useful to calculate the position in response to the direction of slide navigation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -189,17 +188,17 @@ It provides `1` in forward navigation, or `-1` in backward navigation. Using [`v
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
And now, slide-up custom transition is working completely in both directional navigation!
|
||||
And now, the slide-up custom transition is working completely in both directional navigation!
|
||||
|
||||
|
||||
|
||||
> NOTE: Other any CSS variables defined in the context of Marp cannot use in keyframes.
|
||||
> NOTE: Any other CSS variables defined in the context of Marp cannot use in keyframes.
|
||||
|
||||
### Set custom animations for backward transition
|
||||
|
||||
Alternatively you also can set more animation keyframes that are specific for backward navigation.
|
||||
Alternatively, you also can set more animation keyframes that are specific for backward navigation.
|
||||
|
||||
Declare `@keyframes` with **`backward-` prefix to the custom transition name**, just like as **`marp-transition-backward-xxxxxxxx`**. It is available in both of simple keyframes declartion and splitted keyframes declartion.
|
||||
Declare `@keyframes` with the **`backward-` prefix to the custom transition name**, just like as **`marp-transition-backward-xxxxxxxx`**. It is available in both simple keyframes declaration and split keyframes declaration.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -219,7 +218,7 @@ Declare `@keyframes` with **`backward-` prefix to the custom transition name**,
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
In backward navigation, each layers will try to use the backward keyframes first, and fallback to the the normal keyframes if not declared. To disable unintended fallback in backward animations, set an empty declaration of `@keyframes`.
|
||||
In backward navigation, each layer will try to use the backward keyframes first, and fallback to the normal keyframes if not declared. To disable unintended fallback in backward animations, set an empty declaration of `@keyframes`.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -250,17 +249,17 @@ OK, I've described all about declarations for the custom transition!
|
||||
|
||||
## Easing function
|
||||
|
||||
Each transitions have a linear easing by default. You can specify [`animation-timing-function` property within individual keyframes](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timing-function#:~:text=A%20keyframe%27s%20timing%20function%20is%20applied%20on%20a%20property%2Dby%2Dproperty%20basis%20from%20the%20keyframe%20on%20which%20it%20is%20specified%20until%20the%20next%20keyframe%20specifying%20that%20property%2C%20or%20until%20the%20end%20of%20the%20animation%20if%20there%20is%20no%20subsequent%20keyframe%20specifying%20that%20property) if you want.
|
||||
Each transition has a linear easing by default. You can specify [`animation-timing-function` property within individual keyframes](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timing-function#:~:text=A%20keyframe%27s%20timing%20function%20is%20applied%20on%20a%20property%2Dby%2Dproperty%20basis%20from%20the%20keyframe%20on%20which%20it%20is%20specified%20until%20the%20next%20keyframe%20specifying%20that%20property%2C%20or%20until%20the%20end%20of%20the%20animation%20if%20there%20is%20no%20subsequent%20keyframe%20specifying%20that%20property) if you want.
|
||||
|
||||
> Setting [`animation-timing-function: step-end;`](https://developer.mozilla.org/docs/Web/CSS/animation-timing-function#step-end) to a keyframe can make paused animation until next keyframe.
|
||||
> Setting [`animation-timing-function: step-end;`](https://developer.mozilla.org/docs/Web/CSS/animation-timing-function#step-end) to a keyframe can make paused animation until the next keyframe.
|
||||
|
||||
## Duration
|
||||
|
||||
We have a fixed duration `0.5s` as a default value. Custom duration can set through `transition` local directive in Markdown (`<!-- transition: fade 2s -->`), but unfortunately _there is no way to declare the default duration at the specific transition for now._
|
||||
We have a fixed duration `0.5s` as a default value. Custom duration can be set through `transition` local directive in Markdown (`<!-- transition: fade 2s -->`). But unfortunately, _there is no way to declare the default duration at the specific transition for now._
|
||||
|
||||
## Fixed property
|
||||
|
||||
If some of properties required a fixed value while playing transition, try to set the same declaration into `from` (0%) and `to` (100%).
|
||||
If some of the properties required a fixed value while playing transition, try to set the same declaration into `from` (0%) and `to` (100%).
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
@ -288,13 +287,13 @@ If some of properties required a fixed value while playing transition, try to se
|
||||
|
||||
## Layer order
|
||||
|
||||
[As presented as a diagram earlier](#the-anatomy-of-a-transition), the incoming slide layer always will be stacked on the top of the outgoing slide layer. According to the kind of transition, this order may be not suitable.
|
||||
[As presented in a diagram earlier](#the-anatomy-of-a-transition), the incoming slide layer always will be stacked on the top of the outgoing slide layer. According to the kind of transition, this order may be not suitable.
|
||||
|
||||
A fixed property [`z-index: -1`](https://developer.mozilla.org/docs/Web/CSS/z-index) is helpful to send the incoming slide layer to back.
|
||||
|
||||
> A fixed `z-index: 1` to the outgoing slide (send to front) is also getting same result, but currently setting positive number to `z-index` may bring the performance issue in Chrome.
|
||||
> A fixed `z-index: 1` to the outgoing slide (send to front) is also getting the same result, but currently setting a positive number to `z-index` may bring the performance issue in Chrome.
|
||||
|
||||
## Change layer order during transition
|
||||
## Change layer order during a transition
|
||||
|
||||
If you want to swap the order of layers during animation, try to animate `z-index` property.
|
||||
|
||||
@ -321,11 +320,11 @@ If you want to swap the order of layers during animation, try to animate `z-inde
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
`z-index` is always taking an integer value, and interpolated `z-index` value by animation does not take any decimal points too. So animating from `z-index: -1` to `z-index: 0` is exactly meaning to set `-1` at the first half of duration and `0` at the last half, except if used non-linear easing function.
|
||||
`z-index` is always taking an integer value, and interpolated `z-index` value by animation does not take any decimal points too. So animating from `z-index: -1` to `z-index: 0` is exactly meaning to set `-1` at the first half of duration and `0` at the last half, except if using a non-linear easing function.
|
||||
|
||||
## Frequently used properties in transition
|
||||
|
||||
[There are a lot of animatable CSS properties](https://developer.mozilla.org/docs/Web/CSS/CSS_animated_properties), and following properties are frequently animated in built-in transitions.
|
||||
[There are a lot of animatable CSS properties](https://developer.mozilla.org/docs/Web/CSS/CSS_animated_properties), and the following properties are frequently animated in built-in transitions.
|
||||
|
||||
- [`opacity`](https://developer.mozilla.org/docs/Web/CSS/opacity)
|
||||
- [`transform`](https://developer.mozilla.org/docs/Web/CSS/transform)
|
||||
@ -343,4 +342,4 @@ We are really looking forward to what creative transition effects our community
|
||||
|
||||
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, **transition is still experimental**. Before starting to use transitions, _you **must** read [a GitHub issue about this feature](https://github.com/marp-team/marp-cli/issues/447) through._ Any feedbacks are welcome!
|
||||
> 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!
|
||||
|
||||
Loading…
Reference in New Issue
Block a user