Marp 生态更新实战：Marp Core v3 数学排版与自动缩放重构、Marp CLI v2 幻灯片过渡动画-育师

Marp 生态更新实战：Marp Core v3 数学排版与自动缩放重构、Marp CLI v2 幻灯片过渡动画

【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp

本篇文章围绕 Marp 生态 2022 年 5 月的核心更新展开：Marp Core v3 将数学排版默认切换为 MathJax、把自动缩放组件重构为 Web Components，Marp CLI v2 则内置 v3 核心并带来基于 View Transitions API 的全新幻灯片过渡动画体系。读完本文，你将掌握math、transition等指令的正确用法，理解自定义过渡动画的@keyframes命名约定，并学会为存量幻灯片平滑迁移与规避已弃用的语法。

本文内容源自 202205-ecosystem-update.md 这篇官方生态更新公告，并结合当前仓库中的 math-typesetting.md、directives.md、how-to-make-custom-transition.md 等文档与 README.md 中的生态结构展开。

生态背景：本次更新涉及哪些组件

Marp 是一个用纯 Markdown 编写幻灯片的开源生态。按 README.md 的划分，生态由多个职责单一的仓库组成：

Marpit framework：从 Markdown 生成幻灯片骨架的轻量框架；
Marp Core：带实用特性与内置主题的转换器核心；
Marp CLI：Marp Core / Marpit 的命令行界面，可转换为 HTML、PDF、PPTX 与图片；
Marp for VS Code：在 VS Code 中预览 Marp Markdown 幻灯片的扩展。

本次公告的主角是其中的两块：Marp Core v3（引擎层）与Marp CLI v2（命令行层）。公告原文用两句话概括了核心变化：

Marp Core v3：默认使用 MathJax 渲染数学公式、更新default主题、提供全新的自动缩放组件；
Marp CLI v2：内置 Marp Core v3，并带来包含 33 种内置效果 + CSS 自定义过渡的全新幻灯片过渡实验（该特性在 v2.4.0 中转为稳定）。

Marp Core v3：引擎层的稳定演进

Marp Core v3.0.0 早在 2021 年 11 月就以 release candidate 的形式发布，之后半年以nexttag 作为 Marp CLI 的可选引擎接受社区反馈。本月（公告发布时点）v3.2.0 成为稳定版本，团队开始逐步让下游 Marp 工具默认使用 v3 核心。

公告强调，v3 的核心升级致力于减少 Marp 的 CSS 与通用 CSS 之间的摩擦，例如自动缩放元素的样式将比 v2 更容易理解。大多数幻灯片作者只要没有复杂的主题定制，几乎无需担心回归；但主题作者可能需要调整部分样式。

停止支持已停止维护的 Node.js

Marp Core v3 首先放弃了已到生命周期终点（EoL）的 Node.js 10。Node.js 12 虽然仍是 EoL 版本，但 v3 暂时保留支持——不过公告提示，能否持续支持取决于依赖模块的支持状态，并建议开发者跟进处于活跃 LTS 状态的 Node.js 版本。

数学排版默认切换到 MathJax

这是 v3 最值得关注的行为变更之一：默认数学渲染库从 KaTeX 切换为 MathJax。

公告解释了切换的动机：

Marp 长期使用 KaTeX 是出于性能考虑，但这一观点在 MathJax 3 出现后已过时；
KaTeX 与 Marp Core 自动缩放特性存在难以修复的不兼容问题（对应 marp-core 仓库的 issue #159 与 #236，其中 #159 正是"Safari 不会缩小 KaTeX 渲染的大数学块"的问题，详见仓库中的 math-typesetting.md 已知问题清单）；
MathJax 在 Marp Core 中的实现渲染更可靠、支持更多 TeX 函数，且展示数学公式无需联网；
当时已有大量 Markdown 产品采用 MathJax 排版数学，切换到 MathJax 有助于提升 Marp Markdown 在各种 Markdown 服务间的兼容性。

通过`math`全局指令继续使用 KaTeX

如果你的 Markdown 尚未准备好迁移到 MathJax，可以设置math全局指令为katex，继续使用 KaTeX 渲染：

--- math: katex --- Continue to use KaTeX: $ax^2+bc+c$

官方明确表示短期内不会移除 KaTeX 集成，因此使用 KaTeX 专属语法、或遇到 MathJax 渲染性能问题的用户仍可保留 KaTeX。若想显式声明使用 MathJax，将指令值设为mathjax即可：

--- math: mathjax --- Render inline math such as $ax^2+bc+c$.

关于数学排版的更多用法，仓库中的 math-typesetting.md 提供了完整参考：行内公式用单个美元符号 $...$ ，块级公式用$$...$$（块级公式超出幻灯片水平边界时会自动缩小，仅限支持的主题）；KaTeX 下可通过marp.config.js配置katexFontPath、katexOption.macros等选项，也可以加载 mhchem 化学方程式扩展。需要注意的是，KaTeX 渲染需要从 CDN 拉取 Web Fonts，离线或受限网络环境下可能无法正常显示数学公式。

迁移提示：为了让存量幻灯片平滑迁移到 v3，Marp for VS Code 已从一年前开始对未声明math全局指令的数学用法进行诊断标注，帮助作者发现需要显式声明的位置。

重构为 Web Components 的自动缩放组件

Marp Core 中有一个小型运行时脚本，用于激活以下元素的自动缩放：

代码块（code block）；
数学块（math block）；
Fitting header（#  header）。

v3 将自动缩放逻辑重构为基于 Web Components的实现，以提升输出清晰度，并改善与部分 CSS 选择器的兼容性。具体的实现细节可参考 marp-core 仓库的 pull request #263。

这次重构不改变实际的自动缩放行为，因此大多数幻灯片作者无需关心；但如果你有自定义主题对自动缩放元素写过样式，需要审查并同步修改 CSS 声明以匹配 v3。

关于 fitting header 本身，仓库中的 fitting-header.md 说明了其用法：在标题中加入注释（Marp 用 HTML 注释隐藏关键字，避免污染渲染结果），标题会被缩放到单行显示：

# <!-- fit --> Fitting header

它与 heading divider 指令结合，可以高效制作 Takahashi 风格的大字幻灯片（每行一个# 标题即一页）。

基于 github-markdown-css v5 的全新 default 主题

Marp Core 的default主题一直以 GitHub 的 Markdown 样式为基础，为默认状态提供熟悉的 Markdown 观感。本次更新包括：

基于最新 github-markdown-css v5 更新配色方案；
代码高亮配色与 GitHub 风格保持一致；
允许通过CSS 变量自定义颜色（参见 marp-core 仓库 themes 目录下的主题文档）。

以下示例同时演示了新的default主题与基于 GitHub 深色模式的invert配色：

<!-- paginate: true --> <style>:root { font-size: 40px; }</style> # This is a new `default` theme --- <!-- class: invert --> # Updated `invert` color scheme based on GitHub dark mode

（上例用开启页码，用<style>内联样式调大根字号，则切换为反向配色。）如果你需要调整幻灯片整体字号、页码、页眉页脚等元素，可以结合 directives.md 中的全局/局部指令体系一起使用。

URL 自动链接化收紧：必须携带 http(s) scheme

Marp Core v2 及更早版本会把形似 URL 的字符串自动转换为超链接，但这种识别过于模糊，常常把非预期的词链接化，例如 "Amazon.com" 或 "ML.NET"。

v3 中不再有这种模糊链接：自动链接现在要求 URL 字符串必须携带https://或http://scheme。如果你希望之前被自动链接的词保持超链接，需要显式写出 Markdown 链接：

[Amazon.com](https://amazon.com/)

补充背景：Marp 的 Markdown 基于 CommonMark，并启用部分 GFM 扩展（自动链接、删除线、表格等），详见 how-to-write-slides.md。v3 对自动链接规则的收紧正是为了减少 GFM 扩展带来的歧义。

Marp CLI v2：跟随核心的 CLI 大版本更新

在 Marp Core v3 转正的同时，Marp CLI 也发布了 v2.0.0 以内置新核心。公告强调：CLI 的常规用法几乎没有变化，大多数既有 CLI 工作流不会被破坏；而真正的"大版本"亮点藏在文末的过渡动画特性中。

环境要求：Node.js v14 及以上

Marp CLI v2 要求Node.js v14 及以上，原因是依赖模块（如用于生成 PDF/PPTX 的 Puppeteer）已放弃对 EoL 版本 Node.js v12 及更早版本的支持。

内置 Marp Core v3 引擎

Marp CLI v2 内置 Marp Core v3.2.0 作为核心引擎，可通过版本命令确认：

$ marp --version @marp-team/marp-cli v2.0.0 (w/ @marp-team/marp-core v3.2.0)

如何继续使用 v2 核心（迁移过渡方案）

官方建议尽早准备迁移到 v3 核心，但如果你希望暂时停留在 v2 核心，可以通过在项目中单独安装@marp-team/marp-core@^2实现：

npm i --save-dev @marp-team/marp-cli @marp-team/marp-core@^2 npx marp ./your-markdown.md

这对于"Markdown 幻灯片尚未适配 v3"的情况很有用。但请注意：官方几乎不会再为 v2 核心提供更新，长期使用可能带来未修复安全漏洞的风险。

幻灯片过渡动画：本次更新的隐藏宝石

公告作者直言，本次 CLI 更新中最令人兴奋的部分，是bespokeHTML 模板中的全新幻灯片过渡动画（对应 marp-cli 仓库的 issue #447）。

该功能自 Marp CLI v1.4.0（2021 年 8 月）起以实验形式提供--bespoke.transition选项，但效果相比常见演示工具还不够实用。Marp CLI v2 跟进了 W3C 的View Transitions API规范（CSS View Transitions Module Level 1），带来了 CSS 自定义过渡效果与形变（morphing）动画等能力。该特性在v2.4.0 中转为稳定，Marp for VS Code v2.5.0+ 同样支持。

过渡动画的三类核心能力：

33 种内置过渡：开箱即用，覆盖绝大多数使用场景；
通过 CSS 定义自定义过渡：Markdown 作者和主题设计师可以用@keyframes声明注册命名过渡；
形变动画：利用 View Transitions API 提供的view-transition-nameCSS 属性，在过渡过程中实现元素形变，类似 PowerPoint Morph 与 Keynote Magic Move。

快速体验：开启过渡与预览

HTML 输出中的幻灯片过渡通过--bespoke.transitionCLI 选项开启。它只会在支持 View Transitions API 的浏览器中工作，例如 Chrome / Chromium 110 及以上版本。

--preview选项可以让你确定地看到过渡效果：在 Marp CLI v2.4.0+ 中打开过渡展示的预览窗口：

marp --preview ./showcase.md

其中./showcase.md是官方提供的过渡展示样例 Markdown（可从公告原文中给出的 gist 地址下载得到）。你也可以直接对任意本地幻灯片文件运行marp --preview ./your-deck.md来观察过渡效果。公告中还提供了在线演示入口：内置过渡展示、自定义过渡示例、形变动画示例三个页面（在线 Demo 运行于 Glitch，需使用支持 View Transitions API 的浏览器访问）。

使用`transition`局部指令切换过渡

transition是一个局部指令，可以随时设置和更改过渡类型：

--- transition: fade --- Fade transition with 0.5s duration --- <!-- transition: cover 1s --> Changed the kind of transition to `cover` with 1s duration --- <!-- _transition: none --> Disabled transition for this slide --- Got back to cover transition

要点：

每个过渡默认持续0.5s；
可以用空格分隔的值指定自定义时长，例如；
_transition: none使用作用域局部指令（下划线前缀）在单页上禁用过渡，后续页面不受影响。关于作用域局部指令的继承规则，可参考 directives.md 中的说明。

用 CSS 自定义过渡动画

如果内置的 33 种效果仍不满足需求，可以完全用 CSS 打造自己的过渡动画。Marp 会把你声明在 CSS 中的动画集注册为具名过渡，并在 Markdown 幻灯片中使用。

过渡动画的构成原理

要编写自定义过渡，先要理解页面切换时的机制：切换发生时，视口中会同时呈现两层幻灯片——过渡前显示的一页称为Outgoing slide（出站幻灯片），过渡后出现的一页称为Incoming slide（入站幻灯片）。Marp CLI 的bespoke模板在导航时会创建两个幻灯片图层，并施加合适的动画关键帧。

据此可以推导出两条设计原则：

出站幻灯片应有"隐藏"的动画；
入站幻灯片应有"显示"的动画。

若其中任一条未被满足，过渡就会显得怪异。基于此原理，自定义过渡的@keyframes命名遵循以下约定（详见仓库中的 how-to-make-custom-transition.md）：

关键帧命名	作用
`marp-transition-xxx`	简单声明：只定义出站动画，入站动画自动反向播放
`marp-outgoing-transition-xxx`	为出站幻灯片单独定义动画
`marp-incoming-transition-xxx`	为入站幻灯片单独定义动画
`marp-transition-backward-xxx`（及 outgoing/incoming 变体）	反向导航时优先使用的动画，未声明时回退到普通关键帧

过渡可以声明在 Markdown 内联<style>元素、style全局指令或自定义主题 CSS 中。

简单声明：dissolve（溶解/交叉淡入淡出）

/* Simple definition: "dissolve" custom transition */ @keyframes marp-transition-dissolve { from { opacity: 1; } to { opacity: 0; } }

简单声明只需写出站动画，入站动画会被 Marp 自动反向。将其注册后，在 Markdown 中通过transition: dissolve局部指令即可使用：

--- transition: dissolve style: | @keyframes marp-transition-dissolve { from { opacity: 1; } to { opacity: 0; } } --- # Slide 1 --- <!-- _class: invert --> # Slide 2

声明from { opacity: 1; }只是为了清晰，实际上可省略（opacity: 1是默认样式）。

拆分声明：slide-up

并非所有过渡的入站/出站动画都是恰好相反的，多数情况下需要为两层分别定义动画。例如 slide-up 效果：出站幻灯片从视口移出到上方，入站幻灯片从下方移入视口。

@keyframes marp-outgoing-transition-slide-up { from { transform: translateY(0%); } to { transform: translateY(-100%); } } @keyframes marp-incoming-transition-slide-up { from { transform: translateY(100%); } to { transform: translateY(0%); } }

与简单声明不同，拆分声明不会自动反向，每个动画都要按正确方向定义。

反向导航的处理

如果只定义上述动画，你会发现向后翻页时页面仍然向上移动，交互不直觉。公告原文的示例中提供了两种解法：

解法一：利用--marp-transition-directionCSS 变量。过渡播放期间，关键帧中可以读取该变量：向前导航为1，向后导航为-1。结合calc()计算位置：

@keyframes marp-outgoing-transition-slide-up { from { transform: translateY(0%); } to { transform: translateY(calc(var(--marp-transition-direction, 1) * -100%)); } } @keyframes marp-incoming-transition-slide-up { from { transform: translateY(calc(var(--marp-transition-direction, 1) * 100%)); } to { transform: translateY(0%); } }

注意：关键帧上下文中，除--marp-transition-direction外，其他在动画关键帧环境之外定义的 CSS 变量无法在关键帧内使用。

解法二：声明反向导航专用关键帧。给自定义过渡名加上backward-前缀（简单声明与拆分声明均可用）：

@keyframes marp-incoming-transition-triangle { /* Wipe effect from left top */ from { clip-path: polygon(0% 0%, 0% 0%, 0% 0%); } to { clip-path: polygon(0% 0%, 200% 0%, 0% 200%); } } @keyframes marp-incoming-transition-backward-triangle { /* Wipe effect from right bottom */ from { clip-path: polygon(100% 100%, 100% 100%, 100% 100%); } to { clip-path: polygon(-100% 100%, 100% -100%, 100% 100%); } }

反向导航时，每个图层会优先使用 backward 关键帧，未声明则回退到普通关键帧。若要禁用回退，可以声明空的@keyframes：

@keyframes marp-outgoing-transition-zoom-out { from { transform: scale(1); } to { transform: scale(0); } } @keyframes marp-incoming-transition-zoom-out { /* Send the incoming slide layer to back */ from { z-index: -1; } to { z-index: -1; } } /* Declare empty keyframes to disable fallback */ @keyframes marp-outgoing-transition-backward-zoom-out {} @keyframes marp-incoming-transition-backward-zoom-out { from { transform: scale(0); } to { transform: scale(1); } }

自定义过渡的实用技巧

从仓库中的 how-to-make-custom-transition.md 可以进一步提炼这些调优要点：

缓动函数：每个过渡默认是线性缓动，可以在单个关键帧内指定animation-timing-function（例如step-end可实现暂停效果）；
默认时长：所有过渡默认固定为 0.5s。若想为自定义过渡设置不同的默认时长，在第一个关键帧（from/0%）中设置--marp-transition-duration属性（例如--marp-transition-duration: 1s）；幻灯片作者仍可通过transition局部指令随时覆盖（如）；
固定属性：若某些属性在过渡期间需要保持固定值，把相同声明同时写进from与to（例如固定transform-origin: top left）；
图层顺序：入站图层默认叠放在出站图层之上，可用固定的z-index: -1把入站图层送到底层（不推荐对出站层使用正数z-index，在 Chrome 中可能引发动画抖动）；
中途换层：动画化z-index可在过渡中途交换图层顺序，注意z-index插值不产生小数；
常用动画属性：内置过渡中高频使用的属性包括opacity、transform、filter、clip-path、mask-image（-webkit-mask-image）、box-shadow、z-index。

基于 View Transitions API 的形变动画

借助浏览器的 View Transitions API，可以在过渡期间施加形变动画——这与 PowerPoint Morph 和 Keynote Magic Move 类似。做法很简单：为元素撒上几个 CSS 属性即可。

--- 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.

核心思路：通过view-transition-name为跨页出现的同一元素（此处是数字 "1" 的图标）命名，浏览器即可在过渡时对该元素进行形变。transition: fade提供基础过渡，view-transition-name: one则让同名元素在页面切换时平滑"变形"到新位置。

关于自定义过渡的完整原理、命名约定与调优细节，请进一步阅读仓库中的 how-to-make-custom-transition.md；过渡动画的官方完整文档位于 marp-cli 仓库的 bespoke-transitions 文档目录（含内置过渡清单、自定义过渡、形变动画三部分）。

弃用公告：图片语法中的颜色简写

本次更新还带来了一项语法弃用：通过 Markdown 图片语法设置颜色的简写。

Marpit 框架此前允许用![](red)、bg这类写法，为当前幻灯片页设置对应的color: red、background-color: yellow样式。但这类语法在实际中很少使用，且从 Markdown（CommonMark）兼容性角度看是有害的。

Marpit 框架已经提供了color/backgroundColor局部指令，配合作用域局部指令（下划线前缀）即可获得相同效果。如果你正在使用这些颜色简写，请替换为下面的写法：

旧简写	应替换为
`![](red)`	`<!-- _color: red -->`
`bg`	`<!-- _backgroundColor: red -->`

说明：_color/_backgroundColor属于作用域局部指令，只作用于当前页，不会被子页面继承，详见 directives.md 中"Scoped local directives"一节。官方计划为 VS Code 扩展提供可自动修复的诊断能力，帮助用户便捷地更新这些已弃用语法。

社区与后续

Marp 团队欢迎大家加入社区反馈意见：GitHub Discussions 是聚集 Marp 全部讨论的社区论坛，可借此与 Marp 团队及其他用户交流；项目还提供了一份支持指南供参考。对于本公告介绍的过渡动画，官方尤其期待社区创作出更具创意的自定义过渡效果。

Marp 生态更新实战：Marp Core v3 数学排版与自动缩放重构、Marp CLI v2 幻灯片过渡动画