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 ComponentsMarp 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 CLIMarp 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.jsMarp 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^2bcc$官方明确表示短期内不会移除 KaTeX 集成因此使用 KaTeX 专属语法、或遇到 MathJax 渲染性能问题的用户仍可保留 KaTeX。若想显式声明使用 MathJax将指令值设为mathjax即可--- math: mathjax --- Render inline math such as $ax^2bcc$.关于数学排版的更多用法仓库中的 math-typesetting.md 提供了完整参考行内公式用单个美元符号$...$块级公式用$$...$$块级公式超出幻灯片水平边界时会自动缩小仅限支持的主题KaTeX 下可通过marp.config.js配置katexFontPath、katexOption.macros等选项也可以加载 mhchem 化学方程式扩展。需要注意的是KaTeX 渲染需要从 CDN 拉取 Web Fonts离线或受限网络环境下可能无法正常显示数学公式。迁移提示为了让存量幻灯片平滑迁移到 v3Marp for VS Code 已从一年前开始对未声明math全局指令的数学用法进行诊断标注帮助作者发现需要显式声明的位置。重构为 Web Components 的自动缩放组件Marp Core 中有一个小型运行时脚本用于激活以下元素的自动缩放代码块code block数学块math blockFitting header# !--fit-- header。v3 将自动缩放逻辑重构为基于 Web Components的实现以提升输出清晰度并改善与部分 CSS 选择器的兼容性。具体的实现细节可参考 marp-core 仓库的 pull request #263。这次重构不改变实际的自动缩放行为因此大多数幻灯片作者无需关心但如果你有自定义主题对自动缩放元素写过样式需要审查并同步修改 CSS 声明以匹配 v3。关于 fitting header 本身仓库中的 fitting-header.md 说明了其用法在标题中加入!-- fit --注释Marp 用 HTML 注释隐藏关键字避免污染渲染结果标题会被缩放到单行显示# !-- fit -- Fitting header它与 heading divider 指令结合可以高效制作 Takahashi 风格的大字幻灯片每行一个# !--fit--标题即一页。基于 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上例用!-- paginate: true --开启页码用style内联样式调大根字号!-- class: invert --则切换为反向配色。如果你需要调整幻灯片整体字号、页码、页眉页脚等元素可以结合 directives.md 中的全局/局部指令体系一起使用。URL 自动链接化收紧必须携带 http(s) schemeMarp 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.02021 年 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: fade 1s --_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 关键帧未声明则回退到普通关键帧。若要禁用回退可以声明空的keyframeskeyframes 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局部指令随时覆盖如!-- transition: fade 2s --固定属性若某些属性在过渡期间需要保持固定值把相同声明同时写进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[alt1] { view-transition-name: one; contain: layout; } /* Generic image styling for number icons */ img:is([alt1], [alt2], [alt3]) { height: 64px; position: relative; top: -0.1em; vertical-align: middle; width: 64px; } --- # Todays topics -  Introduction -  Features -  Conclusion --- !-- _class: lead --  # Introduction --- #  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 框架此前允许用、bg这类写法为当前幻灯片页设置对应的color: red、background-color: yellow样式。但这类语法在实际中很少使用且从 MarkdownCommonMark兼容性角度看是有害的。Marpit 框架已经提供了color/backgroundColor局部指令配合作用域局部指令下划线前缀即可获得相同效果。如果你正在使用这些颜色简写请替换为下面的写法旧简写应替换为!-- _color: red --bg!-- _backgroundColor: red --说明_color/_backgroundColor属于作用域局部指令只作用于当前页不会被子页面继承详见 directives.md 中Scoped local directives一节。官方计划为 VS Code 扩展提供可自动修复的诊断能力帮助用户便捷地更新这些已弃用语法。社区与后续Marp 团队欢迎大家加入社区反馈意见GitHub Discussions 是聚集 Marp 全部讨论的社区论坛可借此与 Marp 团队及其他用户交流项目还提供了一份支持指南供参考。对于本公告介绍的过渡动画官方尤其期待社区创作出更具创意的自定义过渡效果。延伸阅读仓库内文档README.mdMarp 生态全貌Marpit / Marp Core / Marp CLI / Marp for VS Codehow-to-make-custom-transition.md自定义过渡动画的深度教程过渡原理、关键帧命名、反向导航、调优技巧math-typesetting.mdMathJax 与 KaTeX 数学排版的完整参考含已知问题清单directives.md全局/局部指令与作用域局部指令的语法与继承规则fitting-header.md# !-- fit --自动缩放标题的用法与 Takahashi 风格示例how-to-write-slides.mdMarp Markdown 基础语法与分页规则marpit-v2-marp-core-v2-and-marp-cli-v1.md上一代大版本更新记录可对照了解演进脉络【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考