命令行

slides [deck.md] [flags]
slides [command] [flags] deck.md

命令

slides <command> --help 会列出某个命令的参数。参数可以写在演示文稿之前或之后： slides deck.md -o out.html 与 slides -o out.html deck.md 等价。长参数使用两个短横线（--html）；-o 是唯一的短参数。 除非 -o 另行指定，build 会在 deck.md 旁边写出 deck.html。

参数

多个演示文稿与目录

从 v0.6.0 起，build 可以接受多个演示文稿、一个目录（递归查找其中的演示文稿） 或一个通配模式，并同时构建最多 --parallel 个。- 表示标准输入；与 marp-cli 不同，除非用 - 明确指定，否则不会读取管道。

通配模式的解释方式与 marp-cli 的 glob 相同（** 和 {a,b} 自 v0.7.0 起支持； 请加引号，让 shell 把它原样交给 slides）：名称中可使用 *、?、[a-z] 和 {md,txt}，** 匹配任意层目录，因此 'docs/**/*.md' 会选取整棵目录树中的演示文稿。 通配符不会匹配以点开头的名称，不会在 node_modules 中查找，区分大小写 （*.md 找不到 UPPER.MD），并且模式匹配到的任何文件都会被转换，无论其扩展名是什么。 没有匹配到任何文件的模式会报错。

• -I dir 与 marp-cli 一样，查找 dir 下的 Markdown 文件（.md、.mdown、.markdown、 .markdn，小写）：不会进入 node_modules 和以点开头的目录。配合 -o out 时， 每个演示文稿按其在 dir 下的路径，镜像写到 out 下：dir/sub/b.md 生成 out/sub/b.html（或 b.pdf、b.001.png、b.txt、…，取决于参数）。 不带 -o 时，输出文件写在各自的演示文稿旁边。同时指定演示文稿和 -I 会报错，对多个演示文稿使用 -o file 也会报错（允许 -o -）。
• -P n 同时构建 n 个演示文稿。单个演示文稿的渲染本身已经会利用多核， 所以 n 的上限是 CPU 核数；使用 -o - 时逐个构建。同一个演示文稿的消息会集中在一起输出， 一个演示文稿失败不会中断其他演示文稿：退出状态为 1，消息中会列出失败项。

过渡效果与演示页面

从 v0.6.0 起，marp-cli 的 transition 指令可用：<!-- transition: fade 1s -->（名称加可选的时长）作用于当前幻灯片及其后的幻灯片， <!-- _transition: cover --> 则只作用于一张。内置名称与 marp-cli 相同： clockwise、counterclockwise、cover、coverflow、cube、cylinder、 diamond、drop、explode、fade、fade-out、fall、flip、glow、 implode、in-out、iris-in、iris-out、melt、overlap、pivot、pull、 push、reveal、rotate、slide、star、swap、swipe、swoosh、wipe、 wiper 和 zoom；none 表示关闭。当观众向前离开带有过渡效果的幻灯片， 以及返回该幻灯片时，页面会使用浏览器的 View Transition API 播放过渡； 不支持该 API 的浏览器照旧切换幻灯片，而要求减弱动态效果的观众会看到简单的淡入淡出。 主题可以自带关键帧，命名为 marp-transition-NAME（或 marp-outgoing- 和 marp-incoming-，以及 -backward），它们优先于内置关键帧。

页面带有屏幕控制器（上一张、页码、下一张、全屏），在指针移动或按键时显示， 片刻后隐藏（--bespoke.osc=false 可将其移除）；使用 --bespoke.progress 时还会显示进度条。 进度条现在默认关闭，与 marp-cli 相同；以前总是绘制。

演讲者视图

从 v0.7.0 起，页面提供 marp-cli 的演讲者视图。按 p 或控制器的最后一个按钮， 会打开一个窗口，显示当前幻灯片、下一步、你的演讲者备注、页码、时间和计时器 （点击计时器可重置；+ 和 - 调整备注字号；幻灯片与备注之间的分隔条可以拖动）。 两个窗口双向同步：在任一窗口中按方向键、点击下一步或点击 Previous/Next， 另一个窗口都会跟着移动，每次一个片段。

它的工作方式与 marp-cli 相同（依据其 4.5.1 源码）：该窗口是同一文件的 ?view=presenter&sync=KEY，下一步是在框架中以 ?view=next 打开的同一页面， 窗口之间通过 localStorage（bespoke-marp-sync-KEY）共享位置，因此不需要服务器， 也不需要网络；在没有 localStorage 的浏览器中无法使用（按钮会给出提示）。 备注是纯文本：&、< 和 > 会被转义，所以备注永远不会成为标记。 备注隐藏在页面中，供演讲者视图读取，这样屏幕阅读器就不会把它们读给观众听。 --bare 页面不包含这些功能。该视图会使页面增加约 10 KB。

概览视图

从 v0.8.0 起，按 o（或 Escape：marp-cli 两者都可切换）、控制器的网格按钮， 或演讲者视图的页码计数器，所有幻灯片会以网格形式完整显示在页面上方。 方向键选择幻灯片（上下键按行移动），Home 和 End 跳到首尾，其他窗口随之同步； Enter、Space 或点击会选中幻灯片，在主页面上还会关闭概览。 在演讲者视图上选择后概览保持打开（演讲者挑选要展示的幻灯片，并继续浏览）。 “Close overview” 按钮、o 和 Escape 可关闭概览。它与 marp-cli 的实现相同： 同一页面再次在框架中以 ?view=overview&sync=KEY 打开，通过 localStorage 共享位置，无需网络。网格中的幻灯片可获得焦点，标签为 “Slide N”； 概览关闭时处于 inert 状态，因此键盘用户和屏幕阅读器用户不会误入其中。 两个视图合计使页面增加约 15 KB。

配置文件

marp-cli 从工作目录中的文件读取选项，slides 也一样，前提是该文件是数据文件： .marprc（YAML；JSON 也是 YAML）、.marprc.json、.marprc.yaml、.marprc.yml、 .config/marprc*，或 package.json 中的 marp 键；--config-file（-c） 可指定任意 JSON 或 YAML 文件，例如 marp.config.json。与 marp-cli 的查找方式一样， 只查找工作目录，不查找其上级目录。JavaScript 或 TypeScript 文件 （marp.config.js …）是程序，slides 不会运行它：会给出提示并继续。 支持的选项是 marp-cli 文档中在这里有意义的那些：title、description、author、 keywords、url、ogImage、lang、theme、themeSet、html、allowLocalFiles、 template、bespoke、inputDir、output、parallel、pdf、pptx、notes、 pdfNotes、pdfOutlines、images、image、imageScale、jpegQuality、watch、 server、preview；路径相对于该文件。命令行优先。 engine、options 和 browser* 需要 Marp 的引擎和浏览器，会被忽略并给出警告， --browser* 参数也是如此：为 marp-cli 编写的脚本可以继续使用。 （slides.yaml 和 slides.hcl，连同 kind 和模板数据，是独立的，读取方式不变。）

监视、托管与预览

自 v0.6.0 起，采用 marp-cli 的路由和实时刷新协议（依据其 4.5.1 源码， 并与运行中的 marp -s 对照过）。

slides --server dir（-s）在 http://127.0.0.1:8080/ 上托管该目录 （环境变量 PORT 可修改端口；端口已被占用时会报错并说明原因）：

页面会打开一个连接到 /.__marp-cli-watch-notifier__/<id> 的 WebSocket，其中 id 是 演示文稿路径的 SHA-256；服务器先发送 ready，在演示文稿或目录下任何内容变化时发送 reload。 请求目录时如果缺少结尾的斜杠，会重定向到带斜杠的地址（marp-cli 会在不带斜杠的地址上返回索引， 这会破坏页面的相对链接）。

--watch（-w）先构建演示文稿，之后重新构建发生变化的那一个；当 --theme-set 文件、kind 或数据文件、配置发生变化时，则全部重新构建。它写出的页面会在回环地址上打开一个套接字 （端口 37717，或下一个空闲端口），并在对应演示文稿重新构建时刷新。构建失败的演示文稿会报告错误， 但仍继续监视。--preview（-p）在默认浏览器中打开服务器，或刚刚构建的 HTML 页面； 它没有自己的窗口，因为 slides 没有可以驱动的浏览器。

服务器是进入本机的一个入口，所以它比 marp-cli 的更严格（marp-cli 的服务器监听所有网络接口， 且不做任何检查）：

• 它监听 127.0.0.1；--host 可以更改，但会给出警告，而且通配地址将无法再检查 Host 请求头；
• Host 请求头必须是回环名称（localhost、127.0.0.1、 [::1]、*.localhost）或其监听的主机名，以防范 DNS 重绑定；
• WebSocket 的 Origin 必须是服务器自身；监视模式的套接字还接受从文件打开的页面的 null 来源；来自其他站点、且不是页面导航的请求（脚本、图片、fetch）会被拒绝；
• 路径会被规范化，符号链接会被解析，结果必须位于该目录内：.. 和指向目录外的链接会被拒绝， 对目录外演示文稿的 ?pdf 请求也是如此；以点开头的名称（.git、.env）不会被提供；
• 只接受 GET 和 HEAD；同时进行的转换数量有限；最多监视 4096 个目录， 且不监视 node_modules 中或以点开头的目录。

页面元数据

与 marp-cli 一样，命令行优先于演示文稿；在 marp-cli 中，这些参数会作为最后一条指令注释追加到演示文稿末尾。 以下规则依据 marp-cli 4.5.1 整理，并由针对其输出的测试固定下来（v0.6.0 起）：

• 未设置 title 的演示文稿，取其最低层级的第一个标题的原文 （# **Bold** title 得到 **Bold** title）。没有标题时就没有 <title>。
• keywords 按逗号拆分、去除首尾空白并去重；front matter 中的列表按原样使用。 与 marp-cli 一样，只有从第二个关键词起，页面才会带 keywords 标签，只有一个关键词时不带。
• 无效的 url（非绝对地址）会被忽略并给出警告，保留之前的值； 有效值还会写出 <link rel="canonical"> 和 og:url。
• author 和 description 会附带对应的 Open Graph 标签；og:image:alt 和 Twitter 大图卡片需要同时有标题和图片。

图片、PDF、PPTX 和 ODP

与 marp-cli 一样，-o 配合 .pdf、.pptx、.odp、.png 或 .jpg 扩展名即可选择格式。 输出目录会自动创建。PDF 每张幻灯片一页，页面尺寸与幻灯片相同，并带有由幻灯片及其标题组成的书签大纲。

PDF 备注与书签大纲

从 v0.6.0 起，PDF 支持 marp-cli 的两个选项，并与 marp-cli 4.5.1 为同一演示文稿写出的 PDF 做过对比：

• --pdf-notes 将每张幻灯片的演讲者备注作为注释批注放在对应页面上： 左下角一个黄色的 Note 图标，内容为备注（多条注释之间以空行连接），标题为演示文稿的 author。与 marp-cli 一样，单独使用 --pdf-notes 时会写出 PDF。
• 书签大纲为每张幻灯片包含一个粗体书签 “Page N”，其下按层级嵌套该幻灯片的标题 （--pdf-outlines.pages 和 --pdf-outlines.headings 分别控制这两部分）。 书签大纲在这里默认开启，在 marp-cli 中默认关闭。 slides 一直都会写出书签大纲； 它只占几百字节，却能让长篇演示文稿便于导航，所以保留这一默认值。 --pdf-outlines=false 或 marp-cli 的 --no-pdf-outlines 可将其关闭， 在 .pages 或 .headings 上使用 =false 则去掉对应部分。标题书签跳转到其所在的幻灯片； marp-cli 还会滚动到该标题。

渲染由 go-webengine 完成， PDF 由 go-pdfkit 写出； 内置主题所需的字体（Lato、Roboto Mono）来自 go-opentype/fonts 并被内嵌， 因此任何渲染都不会访问网络。这里没有 Chrome。

--image-scale 2 以每个 CSS 像素两个设备像素进行渲染。除非指定 --allow-local-files， 否则会拒绝本地图片；即使指定了，也只读取演示文稿所在目录之下的文件： 来自别处的演示文稿无法访问 ~/.ssh。多重背景和分栏背景（![bg left:40%]） 的渲染方式与 Marp 的图层相同。

--pptx 使用 go-ooxml 的 WritePresentation 写出演示文稿，包含演讲者备注和演示文稿的元数据。自 v0.5.0 起幻灯片可编辑（见下文）；--pptx-raster 则与 marp-cli 一样，每张幻灯片写出一整张图片， 缩放比例默认为 2，可由 --image-scale 覆盖。生成的文件可以用 LibreOffice 打开。 只在 LibreOffice 中测试过，未在 PowerPoint 和 Keynote 中测试。

--odp 通过 go-odf 的 WritePresentation 写出 OpenDocument 演示文稿， 包含演讲者备注；--odp-raster 每张幻灯片写出一张图片。

可编辑的 PPTX 和 ODP

自 v0.5.0 起，PPTX 或 ODP 中的幻灯片是可编辑的：marp-cli 的 PPTX 每张幻灯片是一张图片， 其实验性的 --pptx-editable 则是借助 LibreOffice 转换 PDF。这里每张幻灯片都依据其布局绘制， 与 PNG 和 PDF 导出所用的布局相同：

• 每行文本都是一个位于其布局位置的文本框，使用幻灯片排版时所用的字体， 且字体内嵌在文件中，因此在没有 Lato 或 Inter 的机器上看起来也一样 （已用 LibreOffice 25.8 验证），并保留粗体、斜体、颜色、字间距和可点击的链接；
• 背景、边框和圆角框是形状；渐变在 PPTX 中是渐变填充，在 ODP 中是图片 （ODF 的渐变只有两种颜色）；
• 图片只存储一次，无论有多少张幻灯片显示它；
• 幻灯片无法表达的内容（受 opacity 影响的元素、filter、 模糊阴影、公式）会成为该元素的一张图片，其上保留文本。

经 LibreOffice 重新渲染后，幻灯片与 PNG 导出结果的像素差异在 0.04–2 % 之间。 --pptx-raster 和 --odp-raster 仍然每张幻灯片一张图片。

矢量 PDF

自 v0.4.0 起，PDF 以矢量方式绘制：go-webengine 将排好版的幻灯片绘制到 PDF 中，而不是绘制成像素。 文本就是文本，使用幻灯片排版时所用的字体，以子集方式内嵌并带有 /ToUnicode 映射， 因此可以选中、搜索和复制。背景、边框和渐变是路径和着色，在多张幻灯片上出现的图片只内嵌一次， 链接可以点击。100 张幻灯片的基准演示文稿大小为 758 KiB，marp-cli 为 837 KiB， v0.3.0 的图片 PDF 为 10 MiB，写出耗时 0.3 s。

这里没有矢量形式的元素（opacity < 1、带有 filter 或旋转、模糊的 box-shadow、 透明度渐变的渐变色）只会将该元素绘制为位图，其上覆盖不可见的文本，以保持可选中。 公式目前仍是位图。--pdf-raster 与 v0.3.0 一样，每页写出一张图片。

slides.yaml

演示文稿旁边的配置文件会作用于该演示文稿，因此一个文件夹中的演示文稿可以共享同一个配置文件：

kinds: kinds.yaml        # a mapping of kinds, or file(s) holding one
themes:                  # theme CSS files or directories
  - themes/
data:                    # template data
  company: Example Inc.
html: false              # allow all raw HTML
lang: en

kind：演示文稿自身的 kinds: 优先于配置文件和命令行中的定义。 数据：配置文件和命令行中的 data 优先于演示文稿的 front matter， 因此同一个演示文稿可以用不同的数据构建。

计划中

尚未实现：PDF 中的公式矢量化。实现后，会在这里以命令或参数的形式提供。