Marp 入门指南：用 Markdown 打造 Markdown Presentation Ecosystem 幻灯片

前端文档【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址https://gitcode.com/gh_mirrors/mar/marp点击查看免费下载MarpMarkdownPresentation Ecosystem是一套以纯 Markdown 编写演示文稿的开源生态。本文以仓库中的官方介绍文档 website/docs/introduction/whats-marp.md 为主体结合本仓库README.md、package.json、website/docs/manifest.yaml的源码与文档结构系统讲解 Marp 的设计理念、核心概念、可插拔架构以及 CLI 与 VS Code 两种工具的安装与选用方式。读完本文你将掌握 Marp 幻灯片的基本写法、主题与指令的运作机制并能够在自己的机器上完成从安装到导出 PDF/PPTX/HTML 的完整流程。Marp 是什么Marp 是 Markdown Presentation EcosystemMarkdown 演示文稿生态的缩写它的目标非常明确为“用 Markdown 写演示文稿”这件事提供一流的体验。在传统工作流中做 PPT 往往意味着在 PowerPoint 或 Keynote 里手工排版、拖拽元素注意力被分散到“如何生成这张幻灯片”的代码与操作上。Marp 则把重心拉回到内容本身作者只需专注于演示文稿的逻辑结构用最朴素的 Markdown 把要点写出来剩下的事情交给生态内的工具链。需要特别强调的是本仓库是一个生态入口仓库entrance repository。正如 package.json 中描述的那样它的定位是 The entrance repository of Markdown presentation ecosystem仓库主体内容位于website目录Next.js 站点而真正的引擎、核心与工具由若干子项目构成。理解这一点有助于你在阅读后续“可插拔架构”与“生态全家桶”两节时建立全局视角。一段真实的 Marp 幻灯片先看效果官方介绍文档给出的第一个示例就是一段完整的、可直接运行的 Marp 幻灯片源码。它展示了 Marp 的三个基础要素YAML front matter启用 Marp 并指定主题、Markdown 内容、以及用---分割的多页结构--- marp: true theme: uncover --- [](https://link.gitcode.com/i/3cf3c0ee1c2067efdad7d18ba4379d8f) # **Marp** Markdown Presentation Ecosystem --- !-- paginate: true -- ## Whats Marp? Marp provides a great experience for _writing_ presentations with Markdown. :pencil: markdown # Slide 1 foo --- # Slide 2 bar 这段代码展示了几个关键点marp: true在 front matter 中显式启用 Marp 功能VS Code 扩展也靠这个开关识别 Marp 文档theme: uncover选用内置的uncover主题Marp 内置了多套可直接使用的主题详见theme指令!-- paginate: true --以 HTML 注释形式定义局部指令为后续幻灯片开启页码---水平分隔线Marp 依据水平分隔线把一份 Markdown 文档切分成多张幻灯片。文档中这类带有marp标记的代码块是可以直接渲染成真实幻灯片的你可以把它粘贴到 VS Code 的 Markdown 预览中立即看到效果。四大核心设计理念基于 CommonMark兼容一切 Markdown 生态Marp 的 Markdown 语法建立在CommonMark规范之上。CommonMark 是 Markdown 的统一规范社区中大多数编辑器、渲染器都遵循它。Marp 选择 CommonMark 的原因有两个最大兼容性你的 Marp 文档在任何支持 CommonMark 的编辑器或渲染器中都不会“走样”超集而非另起炉灶Marp 只在 CommonMark 之上增加少量扩展语法这意味着你已有的 Markdown 写作习惯可以无缝迁移。用文档中的话说Marp only adds a few additional features on top of CommonMark, so your Marp document will look good regardless of what software you used to edit or render Markdown——即便你换了编辑/渲染工具文档效果依然一致。在 website/docs/guide/how-to-write-slides.md 中可以看到这些“额外特性”的具体清单段落内换行自动转为br /、支持 GFM 的自动链接/Emoji/删除线/代码高亮/表格、以及style与br /两个默认放行的 HTML 标签等。出于安全考虑其他 HTML 标签默认禁用需要按所用工具显式开启。主题 CSS内容与样式彻底分离会一点 HTML 和 CSS就能轻松定制 Marp 幻灯片的观感。Marp 的主题系统允许你用纯 CSS定义幻灯片样式其背后是经典的Separation of content and style内容与样式分离设计原则作者专注内容Markdown社区贡献的主题纯 CSS负责样式两者通过theme指令解耦同一份内容可以随时套用不同主题。这种设计让“使用社区做好的设计”变得极其简单——不需要改任何内容只需切换theme名称即可。你可以通过style指令为整套幻灯片补充 CSS 微调也可以借助_class等指令做局部覆盖。导出 PDF / PPTX / HTML跨格式渲染一致是硬目标Marp 对格式转换提供一等公民first-class支持并且把“跨格式渲染一致”当作首要目标同一份幻灯片导出的 PDF、PPTX、HTML 三个版本应当看起来完全一样用户不需要担心换一种格式就会破坏排版。文档同时给出了一条重要的定位说明Marp 并不是一款独立的演示软件。推荐的演示方式是格式适用场景PDF最推荐。任何支持 PDF 的环境都能放映尤其适合离线无网络演示HTML适合发布到互联网、展示交互内容、使用碎片化列表fragmented lists等高级特性PPTX当你需要在 PowerPoint 中手动补充内容时使用上手简单CLI 与 GUI 双通道生态同时提供命令行Marp CLI与图形界面VS Code 扩展两条创作通道。创建一套幻灯片的最小成本是安装 Marp然后写一个 Marp 格式的 Markdown 文件。唯一的前提是如需导出 PDF/PPTX本地需装有 Chrome、Edge 或其他 Chromium 内核浏览器转换引擎依赖 Chromium 渲染。Marp CLI一条命令把 Markdown 转为 HTML/PDF/PPTXVS Code 扩展实时预览幻灯片、提供 Marp 语法特性补全、诊断、悬停提示与导出命令。可插拔架构基于 Marpit 框架Marp 的底层是Marpit framework——“一个用 Markdown 生成幻灯片套件的精简框架”the skinny framework for creating a slide deck from Markdown。Marpit 采用可插拔架构开发者可以通过插件为其增加能力。这一架构最终通过 Marp CLI 向终端用户开放了定制入口官方文档列出的可扩展点包括新增 Markdown 语法兼容 markdown-it 插件体系自定义指令directives扩展 Marp 的 YAML 指令系统提供自定义主题集交付自己的主题 CSS 集合。“Push the limits of Marp as you like!”——这句话正是 Marp 生态开放性的注脚从“改一行 CSS”到“写一个 markdown-it 插件”定制的深度由你自己决定。从仓库结构看生态全家桶本仓库 README.md 用 “Marp family” 一节清晰地罗列了生态中的各个角色这也是理解“可插拔架构”的完整上下文Marpit从 Markdown 生成幻灯片套件的底层框架可插拔架构的根基Marp CoreMarp 转换器的核心提供实用特性与内置主题built-in themesMarp CLI基于 Marp Core/Marpit 的命令行界面可转换为 HTML、PDF、PPTX 及图片Marp for VS Code在 VS Code 中预览 Marp Markdown 幻灯片稿的扩展。从 website/docs/manifest.yaml 的文档结构可以看出本站点将文档划分为 Introductionwhats-marp / install、Guidehow-to-write-slides / directives / theme / heading-divider / image-syntax / fragmented-list / fitting-header / math-typesetting与 Toolsmarp-cli / marp-for-vs-code三大板块其中 Tools 板块在本仓库内目前保留为入口页stubMarp CLI 与 Marp for VS Code 的完整能力说明分别在其各自的独立子项目中维护。这套“入口仓库 多子仓库”的组织方式正是生态可插拔、可独立演进的工程基础。开始使用选 CLI 还是 VS Code要开始创作你必须安装Marp CLI或VS Code 扩展二者之一。website/docs/introduction/install.md 给出了两者的基础对比Marp for VS CodeMarp CLI编辑器VS Code任意编辑器实时预览有有导出方式点击导出命令行支持 Marp 插件否是Marp for VS Code不熟悉命令行的用户可以直接选择它所有基础 Marp 功能都已涵盖即便是 CLI 老手也可能因为 VS Code 的语法补全与实时预览而偏爱用它创作。Marp CLI更适合以下场景用自己偏好的编辑器如 vim编写 Markdown 与主题 CSS批量处理batch processing通过管道piping与重定向与其他工具组合持续集成CI服务端转换设置 Marp 的高级配置在 Node.js 项目中使用 Marp使用 Marp / Marpit / markdown-it 插件使用其他 Marpit 风格flavored的引擎。安装 Marp for VS Code安装 Visual Studio Code安装 Marp for VS Code 扩展新建并打开一个扩展名为.md的 Markdown 文件在编辑器工具栏的 Marp 图标中选择Toggle Marp feature for current Markdown命令它会自动在文件 front matter 中加入--- marp: true ---打开 VS Code Markdown 预览开始写作。安装 Marp CLIHomebrewmacOSbrew install marp-cliScoopWindowsscoop install marpNode.jsnpx 一次性转换如果已安装 Node.js文档要求 Node.js 12可以不经安装、直接用npx即npm exec做一次性转换npx marp-team/marp-clilatest markdown.md安装到 Node 项目npm install --save-dev marp-team/marp-cli npx marp markdown.mdyarn add --dev marp-team/marp-cli yarn exec markdown.md也可以将marp命令全局安装但官方文档明确提示这样做并不推荐。此外还提供独立二进制从发布页下载与官方 Docker 容器两种方式。作为参考本仓库采用 Yarn workspaces 管理见 package.json 的workspaces: [website]与 Marp 生态各 npm 包的使用习惯一致。快速掌握 Marp 语法要点这里补充 website/docs/guide/how-to-write-slides.md 中与“上手”直接相关的语法要点方便你读完本文就能写出第一套幻灯片。幻灯片分割用水平分隔线如---切分幻灯片。需要注意根据 CommonMark 规范---前后可能需要空行如果不想加空行可以用下划线___、星号***或带空格的分隔线- - -代替。扩展语法段落内换行自动转为br /也可显式书写br /标签某些不常见的列表标记*、1)具有特殊含义用于碎片化列表详见 website/docs/guide/fragmented-list.md启用部分 GFM 特性URL 自动链接、Emoji 短代码、删除线~~strike~~、代码块语法高亮、表格HTML 标签默认大多禁用仅放行style用于微调主题与br /如需开启全部 HTML 标签必须在所用的 Marp 工具中显式 opt-in。指令DirectivesMarp 用一套 YAML 语法扩展——“指令”来控制主题、页码、页眉页脚等元素。指令可以写在 HTML 注释中也可以写在文档开头的 YAML front matter 里。指令分为两类全局指令作用于整套幻灯片如theme、size、headingDivider、math、title、author、description、keywords、url、image、style、marp和局部指令作用于单页如paginate、header、footer、class、backgroundColor、backgroundImage、color等。局部指令会向后续页面继承加下划线前缀如_color可让指令只作用于当前页。详见 website/docs/guide/directives.md。作者与许可证Marp 由 Marp team 维护目前实际由维护者 Yuki Hattoriyhatt。小结从官方介绍文档出发可以看到Marp 的定位清晰而克制以 CommonMark 为语法基石以 CSS 实现内容与样式分离以“跨格式渲染一致”为转换目标以 Marpit 的可插拔架构支撑生态扩展再以 CLI VS Code 双通道降低上手门槛。它不试图成为独立的演示软件而是把“写幻灯片”这件事彻底简化为“写 Markdown”。接下来你可以前往 website/docs/guide/how-to-write-slides.md 系统学习幻灯片语法或参考 website/docs/introduction/install.md 安装工具后立即动手创作第一套幻灯片。赞分享前端文档【免费下载链接】marpThe entrance repository of Markdown presentation ecosystem项目地址https://gitcode.com/gh_mirrors/mar/marp点击查看免费下载相关推荐Marp极速入门指南3分钟打造专业Markdown幻灯片Marp极速入门指南3分钟打造专业Markdown幻灯片 为什么选择Marp 你是否还在为制作演示文稿浪费数小时尝试过复杂的PPT排版却得不到满意效果M前端文档Marp Next终极指南用Markdown打造专业级动态幻灯片Marp Next终极指南用Markdown打造专业级动态幻灯片 Marp Next是一款基于Markdown的专业幻灯片制作工具让你轻松创建视觉震撼的演示Marp终极指南用Markdown打造专业幻灯片的完整教程Marp终极指南用Markdown打造专业幻灯片的完整教程 Marp是一款基于Markdown的幻灯片制作工具让你无需复杂操作就能快速创建专业级演示文稿。本创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考