Marp 生态大版本升级解读：Marpit v2、Marp Core v2 与 Marp CLI v1 的变更与迁移实践

Marp 生态大版本升级解读Marpit v2、Marp Core v2 与 Marp CLI v1 的变更与迁移实践【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp2021 年 5 月Marp 团队一次性发布了 Marp 生态的三个关键大版本——Marpit 框架 v2、Marp Core v2 以及 Marp CLI v1本文基于 marp 仓库的官方发布公告 marpit-v2-marp-core-v2-and-marp-cli-v1.md系统梳理这三个版本各自包含的破坏性变更、新增能力与底层依赖调整并结合仓库文档给出升级与迁移的具体操作建议。读完本文你将清楚知道这次大版本升级改了什么、为什么改、影响谁、如何平滑迁移以及后续 Marpit v3 的演进方向。一、为什么这次会同时发布三个大版本要理解这次升级先要明确 Marp 生态三个组件的分层关系。根据 README.md 与 whats-marp.md 的说明Marpit最底层的瘦框架负责把 Markdown 转成幻灯片 HTML/CSS 的核心机制Marp Core在 Marpit 之上提供实用语法、内置主题Default、Gaia、Uncover 等与开箱即用能力的完整版转换器Marp CLI把 Marp Core / Marpit 封装成命令行接口用于转换为 HTML、PDF、PPTX 和图片是服务端转换与批处理场景的主力工具。官方公告明确指出这次升级之所以全部提升大版本号核心原因只有一个——Node.js 10 已经到达生命周期终点End-of-Life。Marpit 与 Marp Core 在 Node 10 上依然可以运行团队只是给出一个过渡窗口但由于安全考量官方不建议继续使用已过期的 Node.js 版本。这也是理解本次所有破坏性变更的主线。二、Marpit v2.0.0框架层的现代化改造Marpit v2.0.0 是本次升级中位于最底层的改动其变更直接影响所有基于 Marpit 构建的上层工具包括 Marp Core 与 Marp CLI。破坏性变更安装要求 Node.js 10BreakingMarpit 从 v2.0.0 起要求 Node.js 10 才能安装。这是对 Node 10 寿命到期的直接响应属于最低限度的版本约束调整。内部依赖升级PostCSS 8ChangedMarpit 将 CSS 处理核心从旧版 PostCSS 升级到PostCSS 8。这是一次底层构建链的现代化影响面主要在主题 CSS 的解析与转换环节。对于大多数只写 Markdown、不深入框架内部的用户而言该变化是透明的。Changed同步升级 Node 版本要求与全部依赖包至最新版本。移除已废弃接口markdownItPluginsRemoved移除了markdownItPlugins——它是面向 markdown-it 插件体系的旧版 getter 接口。影响面如果你是基于 Marpit 的插件开发者需要检查自己的插件是否依赖该 getter并迁移到 Marpit 推荐的插件注册方式。普通幻灯片作者不受影响。缺陷修复高级背景中的 CSS columnsFixed修复了高级背景advanced background场景下 CSScolumns属性未重置的问题避免背景元素在特定渲染环境下出现意外的多栏布局。三、Marp Core v2.0.0主题定制能力的增强Marp Core v2.0.0 的重点是主题层的定制能力升级同时对底层框架进行了同步更新。新增Gaia 与 Uncover 主题支持 CSS 变量自定义颜色本次版本最值得关注的新特性是Gaia与Uncover内置主题开放了通过 CSS 变量Custom Properties自定义颜色的能力Added允许在 Gaia 和 Uncover 主题中通过 CSS 变量定制配色。这意味着主题作者或幻灯片作者不再需要复制整套主题 CSS 来改颜色而可以在 Marp 文档的style中声明:root级别的 CSS 变量对主题颜色进行局部覆盖。典型的使用方式如下变量名以你所使用的主题实际定义为准style :root { /* 用 CSS 变量覆盖 Gaia / Uncover 主题中的颜色定义 */ --color-foreground: #0f4c81; --color-background: #f7f7f7; } /style结合 whats-marp.md 中内容与样式分离Separation of content and presentation的设计理念可以看出CSS 变量方案正是这一理念的延伸颜色这种高频定制点被提升为可配置的变量用户无需改动主题源码即可换肤。注意官方同时提示如果你的现有幻灯片带有自定义样式覆盖变量后可能改变已有演示文稿的外观。这是本次升级中唯一明确提示外观可能变化的变更点主题定制较深的用户升级后应回归检查。依赖同步升级到 Marpit v2.0.0ChangedMarp Core v2 将底层框架升级到 Marpit v2.0.0从而继承上节所述的全部框架层改进PostCSS 8、Node 要求等。ChangedNode LTS 与全部依赖包同步升级至最新版本。四、Marp CLI v1.0.0迈向稳定的命令行工具Marp CLI v1.0.0 是本次公告中最具里程碑意义的一个版本——官方明确表示Marp CLI 正在走向稳定。它不再只是实验性转换工具而是覆盖 Docker、多平台 CI 场景的成熟 CLI。破坏性变更正式放弃 Node 10BreakingMarp CLI v1 彻底移除了对 Node.js 10 的支持。配合 install.md 的说明当前推荐使用 Node.js 12 的环境如通过npx即装即用更稳妥的做法是使用长期支持LTS版本的 Node.js。新增ARM64 Docker 容器镜像Added构建并发布ARM64 架构的 Docker 容器镜像。此前 Docker 镜像主要面向 x86_64ARM64 镜像的加入使 Marp CLI 可以原生运行在 Apple Silicon Mac、ARM 云服务器与树莓派等设备上不再依赖模拟层。新增MARP_USER环境变量AddedDocker 镜像支持通过MARP_USER环境变量显式设置容器内运行进程的 UID/GID。这解决了容器内文件权限与宿主机不一致的常见痛点便于在 CI 或挂载卷场景下正确读写文件。典型用法是在docker run时传入该变量# 将容器内进程的 UID/GID 显式指定为宿主机当前用户 docker run --rm -e MARP_USER$(id -u):$(id -g) \ -v $PWD:/home/marp/app \ marpteam/marp-cli deck.md --pdf容器镜像名为marpteam/marp-cli此信息来自 install.md 中关于官方容器的说明。新增Windows 上的 Node 16 测试Added在 Windows 平台上针对 Node.js 16 增加自动化测试弥补此前平台/版本组合的覆盖缺口提升跨平台可靠性。依赖同步内置 Marpit v2 与 Marp Core v2ChangedMarp CLI v1 内置了 Marpit v2.0.0 与 Marp Core v2.0.0因此上面两节提到的所有框架层与核心层变更都会随 Marp CLI 一起生效。ChangedNode 与全部依赖包升级至最新版本。安装与使用方式Marp CLI 提供了多种安装途径完整说明见 install.md# 方式一npx 即用即走需要 Node.js 12无需本地安装 npx marp-team/marp-clilatest markdown.md # 方式二作为 Node 项目开发依赖安装 npm install --save-dev marp-team/marp-cli npx marp markdown.md也可以使用yarn add --dev marp-team/marp-cli或通过 HomebrewmacOS 的brew install marp-cli、ScoopWindows 的scoop install marp以及独立二进制、Docker 镜像等方式安装。需要注意官方不推荐全局安装marp命令。如上图所示Marp CLI 的核心工作流即一条命令完成转换marp deck.md生成 HTMLmarp deck.md --pdf生成 PDF终端内会输出转换进度与产物路径。这也解释了为什么 Marp CLI 特别适合批处理、CI、服务端转换以及与其他工具通过管道组合的场景详见 install.md 中 Marp CLI 适用场景清单。五、升级影响评估谁需要关注这些变化综合三个版本本次升级的影响可以按下表快速定位用户类型需要关注的变化应对建议普通幻灯片作者无直接破坏性变更升级 Node.js 至 LTS 版本即可幻灯片语法不受影响主题定制者Marp Core v2 的 CSS 变量覆盖可能改变外观升级后回归检查自定义样式善用 CSS 变量插件 / 框架开发者Marpit v2 移除markdownItPlugins接口改用新插件注册方式检查对 Node 10 的假设Docker / CI 用户ARM64 镜像与MARP_USER新变量按需改用 ARM64 镜像通过MARP_USER解决权限问题值得一提的是官方公告反复强调尽管是大版本升级但团队没有引入任何剧烈drastic变化核心诉求是在不破坏现有幻灯片的前提下推进现代化。这与 the-story-of-marp-next.md 中保持与普通 Markdown 文档的兼容性的长期设计原则一脉相承。六、未来路线Marpit v3 的规划公告在 Whats Next 部分披露了 Marpit v3 的早期规划官方同时坦承由于维护精力有限re-creation-of-marp-website.md 中预告的部分计划有所延期TypeScript 全量重写Marpit v3 将使用 TypeScript 完整重写提升类型安全与可维护性插件体系内部化计划在内部把 Marp 幻灯片专属插件与框架核心分离以便更好地与其他幻灯片渲染器协作异步转换支持render()方法将支持返回 Promise从而支持异步转换流程保留 Markdown 解析器团队曾认真考虑更换 Markdown 解析器但最终决定不换——因为大量 Marp 用户依赖第三方插件markdown-it 生态更换解析器会造成大面积破坏。这一规划同样体现了 Marp 生态最小化 兼容性优先的长期路线。从后续发布的 202205-ecosystem-update.md 也可以看到Marp 生态此后继续演进到 Marp Core v3 与 Marp CLI v2本文所述的 v2/v1 版本为后续发展奠定了稳定的框架与工具链基础。七、总结Marpit v2、Marp Core v2 与 Marp CLI v1 的同期发布标志着 Marp 生态在 2021 年完成了一次低调但关键的现代化以 Node.js 10 终止支持为契机完成了 PostCSS 8 升级、依赖整体更新、废弃接口清理Marpit开放了 Gaia / Uncover 主题的 CSS 变量配色能力Marp Core并让 Marp CLI 走向稳定——补齐 ARM64 镜像、MARP_USER权限控制与 Windows Node 16 测试矩阵。对于绝大多数用户升级只需两步把 Node.js 升级到受支持的版本然后更新依赖到最新版只有主题定制较深或基于框架开发插件的用户才需要针对性地回归验证。如果你想在升级后动手验证可以在当前仓库的 install.md 中查阅完整安装方式用一份现有幻灯片快速做一次升级前后渲染对比。【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址: https://gitcode.com/gh_mirrors/mar/marp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考