marp官方文档翻译
翻译：巽星石 发布时间：2022年11月4日15:55:25
目录
概述
因为对MarkDown制作PPT的兴趣高涨，我(bilibili@巽星石)于是将marp官方的英文文档做了一个简单的翻译。
marp是一个用MarkDown制作幻灯片的工具集，包括VSCode的插件Marp for VS Code以及Marp-CLI。我使用的前者。
官方将marp所采用的语法称为Marpit Markdown，表示是对Markdown原生语法的扩展。
Marpit Markdown 语法
Marpit Markdown语法侧重于与常见的Markdown文档的兼容性。这意味着即使你在一个常规的 Markdown编辑器中打开Marpit Markdown，渲染的结果仍然看起来很好。
如何编写幻灯片？
Marpit 用水平尺划分幻灯片页面(例如 —) ，非常简单。
# Slide 1
foo
---
# Slide 2
bar
根据通用标记的规范，破折号标尺前可能需要一个空行。如果不想添加空行，可以使用:
- 下划线标尺
___ - 星号标尺
*** - 包含空格的标尺
- - -
扩展功能
指令
Marpit Markdown扩展了名为“指令”的语法，以支持编写出色的幻灯片。它可以控制幻灯片主题、页码、页眉、页脚、样式等。
图像语法
Marpit扩展了Markdown图像语法 ，有助于创建漂亮的幻灯片。
片段列表
从0.9.0版开始，Marpit将使用特定的标记解析列表，作为逐个显示内容的片段列表。
Marpit Markdown使用称为“指令”的扩展语法来支持编写令人惊叹的幻灯片。它可以控制幻灯片主题、页码、页眉、页脚、样式等。
1.指令
用法
书面指令将解析为YAML。
当该值包含YAML特殊字符时，应使用引号换行以正确识别。您可以通过以下方式启用松散解析松散构造函数选项如果你愿意。
HTML注释
<!-- theme: default paginate: true -->
HTML注释也用于演示者注释。当它被解析为一个指令时，它不会被收集到Marpit.render()的注释结果中。
前言
Marpit还支持YAML前言，这是一种常用于保存Markdown元数据的语法。它必须是Markdown的第一件事，并在破折号f分割线之间。
---
theme: default
paginate: true
---
请不要和分页幻灯片的水平分割线混淆。实际的幻灯片内容将在YAML前言的—之后开始。
指令类型
全局指令
全局指令是整个幻灯片的设置值，比如主题theme。如果多次编写相同的全局指令，Marpit只识别最后一次设置的值。
在 v1.4.0中，全局指令的$前缀已被删除。如果需要，开发人员可以将美元前缀的自定义指令重新定义为内置指令的别名。
局部指令
本地指令是 每个幻灯片页面的设置值。 相应设置将适用于 定义了指令的页面和后续页面。
<!-- backgroundColor: aqua -->
这个页面有水绿色的背景。
---
第二页也是同样的颜色。
应用于单个页面 (带下划线前缀的指令)
如果只想将局部指令应用于当前页面，则必须给指令名称添加前缀_。
<!-- _backgroundColor: aqua -->
向局部指令的名称中添加下划线前缀`_`。
---
第二页将不应用指令的设置。
示例：
全局指令
| 名称 | 描述 |
|---|---|
| theme | 指定幻灯片的主题。 |
| style | 为调整主题指定CSS。 |
| headingDivider | 指定标题分隔符选项。 |
主题
用theme全局指令选择一个主题。
<!-- theme: registered-theme-name -->
它识别添加到MarPitInstance的ThemeSet中的主题的名称。
调整主题风格
通常，您可以通过<style>元素调整主题，但在另一个Markdown编辑器中打开时，它可能会破坏文档样式。因此，您可以使用style全局指令，而不是<style>。
---
theme: base-theme
style: |
section {
background-color: #ccc;
}
---
标题分隔符
您可以使用headingDivider全局指令指示在标题之前自动划分幻灯片页面。这一功能类似于Pandoc的--slide-leveloption和Deckset 2的“Slide Dividers”选项。
它必须指定标题级别从1到6，或它们的数组。如果在数字中，则在级别大于或等于指定值的标题上启用此功能，如果在数组中，则仅在指定的级别上启用此功能。
例如，以下两个标记具有相同的输出。
常规语法
# 1st page
The content of 1st page
---
## 2nd page
### The content of 2nd page
Hello, world!
---
# 3rd page
😃
标题分隔符
<!-- headingDivider: 2 -->
# 1st page
The content of 1st page
## 2nd page
### The content of 2nd page
Hello, world!
# 3rd page
😃
当您要从普通的Markdown创建幻灯片卡片组时，它非常有用。即使你在普通的编辑器中打开了使用headingDivider的Markdown，它也会保持一个漂亮的渲染效果，没有难看的水平分割线。
Marpit 构造函数可以设置标题分隔符的默认级别。
局部指令
| 名称 | 描述 |
|---|---|
| paginate | 如果设置为True，则在幻灯片上显示页码。 |
| header | 指定幻灯片标题的内容。 |
| footer | 指定幻灯片页脚的内容。 |
| class | 指定幻灯片的<section>元素的HTML类。 |
| backgroundColor | 设置幻灯片的background-color样式。 |
| backgroundImage | 设置幻灯片的background-image样式。 |
| backgroundPosition | 设置幻灯片的background-position样式。 |
| backgroundRepeat | 设置幻灯片的background-repeat样式。 |
| backgroundSize | 设置幻灯片的background-size样式。 |
| color | 设置幻灯片的color样式。 |
页码
我们支持通过paginate局部指令显示或隐藏页码。
<!-- paginate: true -->
此时你可以在右下角看到幻灯片的页码。
跳过标题幻灯片设置页码
您只需将分页指令的定义移到第二个页面就可以了。
# Title slide
此页面将由于缺乏`paginate`局部指令而不显示页码。
---
<!-- paginate: true -->
将从该页面作为幻灯片页码的起始。
或者也可以使用下划线前缀的指令。
---
paginate: true
_paginate: false
---
页眉和页脚
当您必须在多个幻灯片上显示相同的内容(如幻灯片的标题)时，您可以使用header或footer指令。
---
header: 'Header content'
footer: 'Footer content'
---
# Page 1
---
## Page 2
它将渲染为如下所示的HTML:
<section>
<header>Header content</header>
<h1>Page 1</h1>
<footer>Footer content</footer>
</section>
<section>
<header>Header content</header>
<h2>Page 2</h2>
<footer>Footer content</footer>
</section>
内容将被一个相应的元素包裹起来，并插入到每个幻灯片的正确位置。这些可以看作是幻灯片内容的一部分。
如果希望将这些内容像PowerPoint一样放在幻灯片的边缘，则必须使用受支持的主题。
格式化
此外，您还可以通过Markdown语法格式化页眉/页脚的内容，并插入行内图像。
---
header: '**bold** _italic_'
footer: ''
---
注意：用双引号包裹起来，以避免被解析为无效的YAML。
由于Markdown的解析顺序，您不能在页眉和页脚指令中使用![bg]()语法。
设置幻灯片样式
Class
在某些页面上，您可能认为需要更改布局、主题颜色等等。Class指令可以更改幻灯片页面的<section>元素的class属性。
假设您使用的主题包含如下规则：
section.lead h1 {
text-align: center;
}
您可以通过设带下划线前缀的class指令来使用居中的lead标题。
<!-- _class: lead -->
# THE LEADING HEADER
背景
如果要使用任何颜色或渐变作为背景，可以通过backoundColor或backoundImage局部指令设置样式。
<!-- backgroundImage: "linear-gradient(to bottom, #67b8e3, #0288d1)" -->
渐变背景
---
<!--
_backgroundColor: black
_color: white
-->
黑色背景 + 白色文字
此外，我们还支持对以下声明进行自定义：
backgroundColorbackgroundImagebackgroundPosition(默认为center)backgroundRepeat(默认为no-repeat)backgroundSize(默认为cover)color
如果您想将图像或颜色作为背景设置为单页，它还可以使用扩展的图像语法。
高级
自定义指令
开发人员可以扩展可识别的指令。例如，Marp Core扩展了size全局指令来更改Markdown中的幻灯片大小。Marp CLI将添加设置转换后的HTML元属性的指令。Marpit实例具有customDirectives.globalandcustomDirectives.localobject，可以根据需要添加指令。
自定义全局指令
下面的示例定义了内置的global指令的$前缀别名。
marpit.customDirectives.global.$theme = (value, marpit) => {
return { theme: value }
}
请定义一个函数来处理从Markdown传递的值。第一个参数是传递的值，第二个参数是当前的Marpit实例。它应该返回一个对象，该对象包含用于传递给同类指令的键值对。
自定义局部指令
自定义指令还可以提供一种一次分配多个同类指令的方法。让我们定义ColorPreset局部指令来分配幻灯片颜色的预设置。
marpit.customDirectives.local.colorPreset = (value, marpit) => {
switch (value) {
case 'sunset':
return { backgroundColor: '#e62e00', color: '#fffff2' }
case 'dark':
return { backgroundColor: '#303033', color: '#f8f8ff' }
default:
// 如果不必分配新值，则返回空对象
return {}
}
}
现在，您可以使用定义的ColorPreset局部指令和相同的内置局部指令。用于将预设置应用于单张幻灯片的下划线前缀(_colorPreset)也可以很好地工作。
<!-- colorPreset: sunset -->
# 日落颜色预设
---
<!-- _colorPreset: dark -->
# 暗色预设
---
# 日落颜色预设
返回的Key-Value将按指令类型分配给预定markdown-it标记的metaObject中的marbitDirections属性。它对于在markdown-it插件中使用赋值非常有用。
2.图像语法
Marpit扩展了Markdown图像语法，以帮助创建精美的幻灯片。
| 功能 | 内联图像 | 幻灯片BG | 高级BG |
|---|---|---|---|
| 按关键字调整大小 | 仅支持 auto | √ | √ |
| 按百分比调整大小 | √ | √ | √ |
| 按长度调整大小 | √ | √ | √ |
| 图像滤镜 | √ | x | √ |
| 多个背景 | - | x | √ |
| 分割背景 | - | x | √ |
基本上，可以通过将对应的关键字包括到图像的替代文本来启用扩展功能。
调整图像大小
可以通过使用 width 和 height 关键字参数来调整图像的大小。
 <!-- 设置宽度为200px -->
 <!-- 设置高度为300px -->
 <!-- 同时设置宽度和高度 -->
我们还支持简单的w和h参数。通常情况下，使用这些参数很有用。
 <!--设置尺寸为32x32px -->
内联图像只允许auto关键字和CSS中定义的长度单位。
与视口大小相关的几个单位(例如vw、vh、vmin、vmax)不能用于确保不变的渲染结果。
图像滤镜
您可以通过MarkDown图像语法将CSS滤镜应用于图像。包括<filter-name>(:<param>(,<param>...))到图像的替代文本。
滤镜可以在内联图像和高级背景中使用。
| 滤镜 | 不带参数写法 | 带参数写法 |
|---|---|---|
| 高斯模糊 | ![blur]() | ![blur:10px]() |
| 亮度 | ![brightness]() | ![brightness:1.5]() |
| 对比度 | ![contrast]() | ![contrast:200%]() |
| 阴影 | ![drop-shadow]() | ![drop-shadow:0,5px,10px,rgba(0,0,0,.4)]() |
| 灰度 | ![grayscale]() | ![grayscale:1]() |
| 色相旋转 | ![hue-rotate]() | ![hue-rotate:180deg]() |
| 反相 | ![invert]() | ![invert:100%]() |
| 透明度 | ![opacity]() | ![opacity:.5]() |
| 饱和度 | ![saturate]() | ![saturate:2.0]() |
| 褐色化？ | ![sepia]() | ![sepia:1.0]() |
更多的关于CSS滤镜的内容可以参考：
当您省略参数时，Marpit将使用上面显示的默认参数。
当然，多个滤镜可以应用于一个图像。
幻灯片背景
我们提供了一种背景图像语法来通过Markdown指定幻灯片的背景。它只需在替换文本中包含bg关键字。
当您在幻灯片中定义了两个或更多的背景图像时，Marpit将只显示最后定义的图像。如果要显示多个图像，可以通过启用内联 SVG 幻灯片来尝试高级背景。
背景尺寸
您可以根据关键字调整背景图像的大小。关键字值基本上遵循background-size样式。
| 关键字 | 描述 | 示例 |
|---|---|---|
| cover | 缩放图像以填充幻灯片 (默认) |  |
| contain | 缩放图像以适合幻灯片 |  |
| fit | contain的别名，与 Deckset 兼容 |  |
| auto | 不缩放图像，而使用原始尺寸 |  |
| x% | 按百分比值指定缩放因子 |  |
您还可以继续使用 width (w)和 height (h)选项关键字来按长度指定大小。
高级背景
📐 它将只在实验性的内联式SVG幻灯片中工作。
高级背景支持多背景、分割背景和针对背景的图像滤镜。
多个背景
这些图像将排列成水平行。
方向关键字
您可以通过使用vertical方向关键字将对齐方向从水平更改为垂直。
背景的左右切分布局
Left或Right关键字与BG关键字一起为指定侧的背景留出空间。它有一半的幻灯片大小，幻灯片内容的空间也会缩小。
# 左右切分布局
幻灯片内容的空间将缩小到右侧。
多个背景将在指定的背景端很好地工作。
# 左右切分布局 + 多个背景
幻灯片内容的空间将缩小到左侧。
这一功能类似于Deckset的拆分幻灯片。
当left关键字和right关键字通过使用多个背景混合在同一张幻灯片中时，Marpt将在幻灯片中使用最后定义的关键字。
控制切分的尺寸
Marpit可以按百分比指定背景的左右分割布局的尺寸，如left:33%。
# 按指定的百分比分割背景
3.片段列表
从v0.9.0开始，Marpit会将带有特定标记的列表解析为片段列表，以便逐个显示内容。
对于项目符号列表
CommonMark允许-、+和作为项目符号标记的字符。如果您使用作为标记，Marpit将解析为片段列表。
# Ordered list
1. One
2. Two
3. Three
---
# Fragmented list
1) One
2) Two
3) Three
对于有序列表
CommonMark的有序列表标记在数字之后必须具有.或)。如果您使用)作为跟随字符，Marpit将解析为片段列表。
# Ordered list
1. One
2. Two
3. Three
---
# Fragmented list
1) One
2) Two
3) Three
渲染
从片段列表中呈现的HTML结构与常规列表相同。它只是将数据属性添加到列表项中并按识别项目的顺序从1开始编号。
此外，有碎片列表的幻灯片的 <section>元素将添加data-marpit-fragments数据属性。它显示了其幻灯片中的片段化列表项的数量。
下面的HTML是项目符号列表示例的渲染结果。
<section id="1">
<h1>Bullet list</h1>
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
</section>
<section id="2" data-marpit-fragments="3">
<h1>Fragmented list</h1>
<ul>
<li data-marpit-fragment="1">One</li>
<li data-marpit-fragment="2">Two</li>
<li data-marpit-fragment="3">Three</li>
</ul>
</section>
片段化的列表不会更改DOM结构和外观。它取决于集成的应用程序的行为是否真的将呈现的列表视为片段。
4.主题的CSS样式
HTML结构
marp的HTML结构的基本思路是 <section>元素对应于每个幻灯片页面。这和reveal.js是一样。
<section><h1>First page</h1></section>
<section><h1>Second page</h1></section>
在转换时，Marpit会将通过使用容器元素的选择器自动包装它们来确定CSS选择器的范围。然而，主题作者不必知道这个过程。
创建主题CSS
如前所述，要创建主题，您只需知道<section>元素就像每个幻灯片页面的视口一样使用。
/* @theme marpit-theme */
section {
width: 1280px;
height: 960px;
font-size: 40px;
padding: 40px;
}
h1 {
font-size: 60px;
color: #09c;
}
h2 {
font-size: 50px;
}
我们没有任何额外的类或混合语句，并且几乎不需要需要知道创建主题的额外规则。这是Marpit不同于其他幻灯片框架的一个关键因素。
:root 伪类选择器
在 Marpit 的上下文中，:root伪类表示幻灯片页面的每个<section>元素，而不是 <html> 。
下面的主题定义与前面的示例类似，但它使用的是:root选择器。
/* @theme marpit-theme */
:root {
width: 1280px;
height: 960px;
font-size: 40px;
padding: 1rem;
}
h1 {
font-size: 1.5rem;
color: #09c;
}
h2 {
font-size: 1.25rem;
}
Marpit 主题中的rem单位会自动转换为来自父<section>元素的计算相对值，所以任何人都不必担心放置 Marpit 幻灯片的根<html>中的字体大小的影响。一切都会按照主题作者的预期进行。
:root选择器可以像 section 选择器一样使用，但是有一个区别:root比 section 具有更高的 CSS 专用性。如果两个选择器在一个 CSS 主题中混合使用，则:root选择器中的声明将优先于节选择器。
元数据
@Theme元数据始终是MarPit所必需的。您必须通过CSS注释定义元数据。
/* @theme name */
如果您使用的是 Sass 的压缩输出，那么应该使用/* ! comments */语法来防止删除注释。
样式
幻灯片尺寸
根部分选择器中的width 和height声明，或者:root伪类选择器表示每个主题预定义的幻灯片大小。指定的大小不仅用作区段元素的大小，而且用作打印PDF的大小。
默认大小为1280 x 720像素。而如果你想要一张经典的4：3的幻灯片，可以试试这样：
/* 切换为经典的4:3幻灯片 */
section {
width: 960px;
height: 720px;
}
请注意，它必须以绝对单位定义静态长度。我们支持cm，in，mm，pc，pt和 px作为单位。
在 Marpit，每个主题都有一个尺寸。幻灯片大小不能通过使用内联样式、自定义类和 CSS 自定义属性更改。但是如果用户使用分割背景，内容的宽度可能会缩小。
页码
paginate指令可以控制是否显示幻灯片的页码。主题创建者可以通过section::after(:root::after)伪元素对其进行样式化。
/* 页码的样式 */
section::after {
font-weight: bold;
text-shadow: 1px 1px 0 #fff;
}
也请参考脚手架主题中的section::after的默认样式。
自定义内容
Marpit has a default content: attr(data-marpit-pagination), indicates the current page number. Theme CSS can add other strings and attributes to the shown page number.
Marpit 有一个默认内容:attr (data-Marpit-pagination)，表示当前页码。主题 CSS 可以向显示的页码添加其他字符串和属性。
/* 添加“Page”前缀和总页数 */
section::after {
content: 'Page ' attr(data-marpit-pagination) ' / ' attr(data-marpit-pagination-total);
}
Attr(data-marpot-pagination-Total)指的是所渲染的幻灯片的总页数。因此，上面的示例会显示为Page 1 / 3。
主题 CSS 必须在内容声明中包含attr (data-marpit-pagination) ，因为用户希望通过paginate: true指令显示页码。如果不包含对该属性的引用，则 Marpit 将忽略整个内容声明。
页眉和页脚
Header和footer元素可以通过 header或footer指令呈现。Marpit 没有这些元素的默认样式。
如果你想放置到幻灯片的边缘，使用position: absolute将是一个很好的解决方案。
section {
padding: 50px;
}
header,
footer {
position: absolute;
left: 50px;
right: 50px;
height: 20px;
}
header {
top: 30px;
}
footer {
bottom: 30px;
}
自定义主题
我们允许基于另一个主题创建自定义主题。
@import 规则
我们支持使用CSS@import规则导入另一个主题。例如，你可以把一个无聊的单色主题染成一个明亮的橙色，如下所示：
/* @theme base */
section {
background-color: #fff;
color: #333;
}
/* @theme customized */
@import 'base';
section {
background-color: #f80;
color: #fff;
}
导入主题必须提前使用Marpit.themeSet.add(css)添加到主题集中。
@import-theme 规则
当您使用像Sass这样的CSS预处理器时，@import可能会解析编译中的路径并丢失其定义。因此，您也可以交替地使用@import-theme规则。
$bg-color: #f80;
$text-color: #fff;
@import-theme 'base';
section {
background: $bg-color;
color: $text-color;
}
@import和@import-theme对于主题可以放置在CSS的根目录上的任何地方。导入的内容将按照规则的顺序插入到CSS的开头。(@import在@import-theme之前处理）
通过Markdown调整样式
有时您可能会认为想要调整当前主题而不是完全自定义主题。
Marpit对写在Markdown中的<style> HTML元素给予了特殊处理。指定的内联样式将在与主题相同的上下文中进行解析，并与其一起绑定到转换后的CSS。
---
theme: base
---
<style>
section {
background: yellow;
}
</style>
# Tweak style through Markdown
你会看到一张黄色的幻灯片。
<style>元素将不会在渲染后的HTML中，并将合并到发出的CSS中。
style全局指令也可以用作相同的目的。
带作用域的样式
我们还通过<style scoped>支持作用域内联样式。当style元素具有scoped属性时，其样式将仅适用于当前幻灯片页。
<!-- Global style全局样式 -->
<style>
h1 {
color: red;
}
</style>
# 红色文字
---
<!-- 带作用域的样式 -->
<style scoped>
h1 {
color: blue;
}
</style>
# 蓝色文字 (仅在当前幻灯片)
---
# 红色文字
当您想调整每个幻灯片页面的样式时，它很有用。
5.内联SVG幻灯片（试验阶段）
省略。
扫一扫
3575
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
