Quarto + Revealjs 中文使用文档

Nite 收录于笔记

2026-05-22 约 1500 字预计阅读 7 分钟

适用范围：本文聚焦 Quarto 使用 revealjs 输出 HTML 幻灯片 的常见与进阶用法。

主要依据的官方资料：

https://quarto.org/docs/presentations/

https://quarto.org/docs/presentations/revealjs/

https://quarto.org/docs/presentations/revealjs/advanced.html

https://quarto.org/docs/presentations/revealjs/presenting.html

https://quarto.org/docs/reference/formats/presentations/revealjs.html

https://quarto.org/docs/cli/preview.html

https://quarto.org/docs/cli/render.html

1. 什么是 Quarto + Revealjs

Quarto 官方支持多种演示文稿格式：revealjs、pptx、beamer。官方文档明确指出，功能最强的是 revealjs，适合制作 HTML slides，也可以再打印成 PDF。

revealjs 的优点主要是：

直接用 Markdown / Quarto 写幻灯片
支持代码块、公式、图表、可执行代码
支持动画、分步显示、演讲者备注、菜单、画板
支持背景图/视频/iframe
适合技术汇报、课程展示、研究报告

2. 最小可用示例

新建一个 slides.qmd：

---
title: "我的演示"
author: "nite"
format:
  revealjs:
    theme: dark
    slide-number: true
    incremental: true
---

## 第一页

- 第一条
- 第二条
- 第三条

## 第二页

这是第二页正文。

预览：

quarto preview slides.qmd

渲染：

quarto render slides.qmd

Quarto 官方 preview 文档说明：quarto preview [file] 会渲染并启动本地预览，且在文档修改后自动刷新；render 用于正式输出文件。

3. 文档结构：YAML Front Matter + 正文

Quarto 文档通常由两部分组成：

YAML Front Matter：放在文件开头，用 --- 包住
正文内容：Markdown / Quarto 语法

最常见结构：

---
title: "标题"
subtitle: "副标题"
author: "作者"
date: "2026-05-22"
format:
  revealjs:
    theme: dark
---

## 第一页

内容

4. 幻灯片如何分页

根据 Quarto 官方文档，演示文稿的分页主要有三种方式。

4.1 用二级标题 `##` 作为普通页

## 第一页
内容 A

## 第二页
内容 B

4.2 用一级标题 `#` 作为分节页 / section 页

# 第一部分

## 背景

## 方法

# 第二部分

## 实验

4.3 用水平线 `---` 手动分页

适合“无标题页”：

这是第一页

---

这是第二页

4.4 用 `slide-level` 改变分页级别

官方参考文档说明：

slide-level 指定“哪个标题级别创建 slide”
0 表示只接受手动分页，也就是主要靠 ---

示例：

format:
  revealjs:
    slide-level: 2

5. 最常用的正文语法

下面这些，是写 Quarto Revealjs 幻灯片时最常用、最值得掌握的语法。

5.1 列表

普通列表：

- 项目一
- 项目二
- 项目三

有序列表：

第一步
第二步
第三步

5.2 分步显示列表（incremental）

全局开启

format:
  revealjs:
    incremental: true

局部开启

::: {.incremental}
- 第一条
- 第二条
- 第三条
:::

局部关闭

::: {.nonincremental}
- 同时出现 1
- 同时出现 2
:::

用 `. . .` 插入停顿

Quarto 官方文档给出的方式是单独一行写：

- 第一点

. . .

- 第二点

5.3 分栏布局

官方推荐语法：

:::: {.columns}

::: {.column width="40%"}
左栏内容
:::

::: {.column width="60%"}
右栏内容
:::

::::

适合：

左文右图
方法 / 结果对照
两个方案并排比较

5.4 演讲者备注（Speaker Notes）

## 这一页

观众能看到的内容

::: {.notes}
这里只给演讲者看。
:::

官方文档说明：按 S 可以打开 Speaker View。

注意：官方也提到，备注中的内容不能依赖外部前端依赖动态渲染；例如 Mermaid 这类通常依赖 JS 的内容，最好转成 SVG/PNG 再插入。

5.5 旁注（Aside）

## 示例页

主要内容

::: aside
这是次要说明，会以较小、较淡的样式显示在页底。
:::

适合补充说明、备注、口头解释提示。

5.6 脚注

这里有一句带脚注的话。^[这是脚注内容]

默认脚注显示在当前 slide 底部。若希望脚注集中到文档末尾，可设置：

format:
  revealjs:
    reference-location: document

5.7 代码块

普通代码块：

```python
print("hello")
```

高亮指定代码行

官方支持 code-line-numbers：

```python {code-line-numbers="2-4"}
def add(a, b):
    x = a + b
    return x
```

也可以：

指定不连续行："2,4"
逐步高亮："|2|4"

调整代码块高度

format:
  revealjs:
    code-block-height: 650px

代码复制、折叠、换行

revealjs 继承了很多 Quarto HTML 代码块能力，参考文档中可配置：

code-fold
code-summary
code-overflow (scroll / wrap)
code-copy

5.8 可执行代码块

Quarto 在 slides 中也支持可执行代码（如 Python / R / Julia 等，具体取决于环境）。

官方文档特别提到：在 revealjs 中，代码默认 echo: false，也就是默认不显示代码，只显示结果；如果要显示代码，需要显式设置：

execute:
  echo: true

或者在具体代码块里设置。

输出放置位置 `output-location`

这是 revealjs 特有的实用选项。官方列出的值包括：

default
fragment：结果分步出现
slide：结果放到下一页
column：结果和代码并排
column-fragment：并排且分步显示

示例：

format:
  revealjs:
    output-location: column

5.9 Tabset 标签页

::: {.panel-tabset}
### 标签一
内容 A

### 标签二
内容 B
:::

适合放：

Python / R 两套代码
方法 A / 方法 B 对比
主结果 / 补充结果切换

注意：官方说明，打印成 PDF 时通常只会显示第一个标签页。

5.10 公式、引用、图片

这些基本沿用 Quarto / Pandoc Markdown 的通用写法。

行内公式

这是行内公式 $E = mc^2$。

块级公式

$$
\nabla f(x) = 0
$$

引用块

> 这是引用内容。

图片

![](figure.png)

如果某一页只有一张顶层图片，Revealjs 默认会尝试自动拉伸填充剩余空间（见下文 auto-stretch / .r-stretch）。

6. 页面级语法与类

6.1 `.smaller`：缩小当前页字号

## 信息很多的一页 {.smaller}

- 很多内容
- 很多内容

也可全局设置：

format:
  revealjs:
    smaller: true

6.2 `.scrollable`：当前页可滚动

## 超长内容页 {.scrollable}

这里有很多很多内容……

也可全局设置：

format:
  revealjs:
    scrollable: true

官方限制说明

官方文档明确提醒：scrollable 与图片自动拉伸 auto-stretch 可能冲突，导致图像显示异常。常见解决办法：

全局关闭自动拉伸：

format:
  revealjs:
    auto-stretch: false

然后只给需要的图手动加 .r-stretch。

给该页加 .nostretch。

6.3 `.center`：垂直居中一页

## 居中页 {.center}

一句核心结论

6.4 `.absolute`：绝对定位

适合精确摆放图片/文字。

![](img1.png){.absolute top=50 left=50 width="300"}
![](img2.png){.absolute bottom=20 right=40 width="200"}

官方说明：

top / left / bottom / right 控制位置
width / height 控制尺寸
数字默认按像素处理，也可以显式写 px、em 等 CSS 单位

6.5 `.r-stack`：元素堆叠

适合配合 fragment 做图层切换：

::: {.r-stack}
![](a.png){.fragment width="400"}
![](b.png){.fragment width="400"}
:::

6.6 `.r-fit-text`：自动放大文本到尽可能充满宽度

::: {.r-fit-text}
非常重要的一句话
:::

6.7 `.r-stretch`：拉伸元素填满剩余高度

![](figure.png){.r-stretch}

官方文档说明：

这通常用于图片
如果某页只有一张顶层图片，Revealjs 往往会自动应用类似效果
可通过 auto-stretch: false 关闭全局自动行为

6.8 `.nostretch`：禁用某页 / 某图的自动拉伸

## 这一页禁用自动拉伸 {.nostretch}

![](figure.png)

7. 页面标题上的属性写法

很多 revealjs 功能都通过在标题后面追加属性实现。

通用模式：

## 标题 {key="value" .class-name}

例如：

## 带背景图的一页 {background-image="bg.png"}

这是 Quarto Revealjs 非常核心的写法。

8. 过渡动画与可见性

8.1 全局过渡动画

format:
  revealjs:
    transition: slide
    background-transition: fade
    transition-speed: fast

官方支持的 transition 值：

none
fade
slide
convex
concave
zoom

transition-speed 可选：

default
fast
slow

8.2 单页过渡动画

## 本页淡入 {transition="fade" transition-speed="fast"}

官方还支持分别指定进场/退场，例如：

## 页面 {transition="fade-in slide-out"}

8.3 页面可见性

隐藏页

## 不显示的页 {visibility="hidden"}

不计入页码/进度条的页

## 附录页 {visibility="uncounted"}

这类页仍可存在，但不会进入正常页码统计。适合备用页、答疑页。

9. 自动动画与 Fragment

9.1 `auto-animate`

给相邻两页都加 auto-animate=true，Revealjs 会自动对相同元素做平滑动画。

## {auto-animate=true}
::: {style="margin-top: 100px;"}
Animating content
:::

## {auto-animate=true}
::: {style="margin-top: 200px; font-size: 3em; color: red;"}
Animating content
:::

全局可配置：

format:
  revealjs:
    auto-animate: true
    auto-animate-duration: 0.8
    auto-animate-easing: ease-in-out
    auto-animate-unmatched: false

9.2 Fragment

fragment 用来控制元素逐步出现、淡出、放大、缩小、高亮等。

常见写法：

- 第一项
- 第二项 {.fragment}
- 第三项 {.fragment}

官方文档中列出的常见 fragment 类包括：

.fragment
.fade-out
.fade-up
.fade-down
.fade-left
.fade-right
.fade-in-then-out
.fade-in-then-semi-out
.grow
.semi-fade-out
.shrink
.strike
.highlight-red
.highlight-green
.highlight-blue
.highlight-current-red
.highlight-current-green
.highlight-current-blue

如果只想要“列表逐项出现”，优先用 incremental；如果想要更复杂的强调效果，再用 fragment 类。

10. 背景相关语法

官方支持给单页设置多种背景。

10.1 背景色

## 纯色背景页 {background-color="aquamarine"}

支持常见 CSS 颜色写法，如：

颜色名
#RRGGBB
rgba(...)
hsl(...)

10.2 渐变背景

## 渐变背景页 {background-gradient="linear-gradient(to bottom, #283b95, #17b2c3)"}

也可使用 radial-gradient(...)、conic-gradient(...)。

10.3 背景图

## 背景图页 {background-image="bg.jpg" background-size="cover" background-position="center"}

常用附加属性：

background-size
background-position
background-repeat
background-opacity

10.4 背景视频

## 视频背景页 {background-video="demo.mp4" background-video-loop="true" background-video-muted="true"}

10.5 背景 iframe

## iframe 背景页 {background-iframe="https://example.com"}

如需可交互，可加：

## iframe 背景页 {background-iframe="https://example.com" background-interactive="true"}

但官方提醒：iframe 交互开启后，会影响普通 slide 交互体验。

10.6 标题页背景

标题页不能直接像普通 slide 那样写标题属性，应使用：

title-slide-attributes:
  data-background-image: cover.png
  data-background-size: cover
  data-background-opacity: "0.5"

注意：标题页这里要求使用带 data- 前缀的键名，这是官方文档明确说明的。

11. Logo、Footer、标题页

11.1 全局 Logo

format:
  revealjs:
    logo: logo.png

format:
  revealjs:
    footer: "课程名 / 作者 / 日期"

## 本页无页脚 {footer=false}

## 某页

正文内容

::: {.footer}
这是本页专属页脚
:::

11.5 标题页样式

默认标题页由 title、subtitle、author、date、institute 等元数据生成
可设置：

format:
  revealjs:
    title-slide-style: pandoc

可关闭标题页垂直居中：

format:
  revealjs:
    center-title-slide: false

12. 纵向 slides、导航模式、滚动视图

12.1 纵向 / 网格导航

官方高级文档提到：如果使用 vertical 或 grid 导航，建议用一级标题作为横向轴、二级标题作为纵向轴。

可理解成：

# 第一大组

## 子页 1

## 子页 2

# 第二大组

## 子页 1

可选值：

linear
vertical
grid

示例：

format:
  revealjs:
    navigation-mode: vertical

12.3 Scroll View

Reveal 5 提供了“滚动视图”，官方文档说明它在小屏幕上尤其有用。

开启：

format:
  revealjs:
    scroll-view: true

更完整配置：

format:
  revealjs:
    scroll-view:
      layout: compact
      snap: proximity
      progress: true
      activation-width: 0

scroll-view 常见键：

progress: auto / true / false
snap: mandatory / proximity / false
layout: full / compact
activation-width
activate

13. 演示过程相关功能

13.1 菜单

format:
  revealjs:
    menu: true

或者自定义：

format:
  revealjs:
    menu:
      side: left
      width: normal
      numbers: true

官方文档说明：即使 menu: false 隐藏了按钮，通常仍可通过键盘 M 打开菜单。

13.2 Overview 总览模式

format:
  revealjs:
    overview: true

演示时可按 O 查看所有页缩略图。

13.3 Chalkboard 画板

format:
  revealjs:
    chalkboard: true

官方文档中提到常见快捷键：

C：切换 notes canvas
B：切换黑板
DEL：清理当前页绘图
BACKSPACE：重置全部绘图
X / Y：切换颜色
D：下载绘图 JSON

注意：与 `embed-resources` 不兼容

官方文档明确说明：

format:
  revealjs:
    embed-resources: true

与 chalkboard 不兼容，同时启用会出错。

13.4 自动播放

format:
  revealjs:
    auto-slide: 5000
    loop: true

表示每 5 秒自动翻页。

还可设置：

auto-slide-stoppable: false
单页覆盖：{autoslide=2000}

13.5 预览链接

format:
  revealjs:
    preview-links: auto

也可以对具体链接单独指定：

[预览这个网页](https://example.com){preview-link="true"}

官方提示：若目标站点设置了 X-Frame-Options 或 Content-Security-Policy: frame-ancestors，iframe 预览可能失败。

13.6 Slide Tone

format:
  revealjs:
    slide-tone: true

官方说明这会在换页时播放音高变化的提示音。

14. 导出与发布

14.1 预览

quarto preview slides.qmd

官方 preview 文档中常见参数：

--port
--host
--render
--no-browser
--no-watch-inputs
--timeout
--quiet
--profile

14.2 正式渲染

quarto render slides.qmd

14.3 打印为 PDF

官方 presenting 文档推荐流程：

在演示页面按 E 进入 Print View
浏览器打印 / 保存 PDF
选择横向、无边距、开启背景图形

14.4 单文件 HTML

format:
  revealjs:
    embed-resources: true

这会把资源尽量嵌入 HTML，便于单文件分发。

再次提醒：不要和 chalkboard 同时开。

15. 内置主题与样式定制

官方列出的内置主题包括：

default
dark
dracula
beige
blood
league
moon
night
serif
simple
sky
solarized

切换方式：

format:
  revealjs:
    theme: dark

也可以结合：

css: 追加自定义 CSS
theme: 使用 SCSS / 自定义主题文件

例如：

format:
  revealjs:
    theme: dark
    css: styles.css

16. 常用 Front Matter 模板

16.1 极简深色技术汇报模板

---
title: "报告题目"
author: "你的名字"
format:
  revealjs:
    theme: dark
    slide-number: true
    incremental: true
    transition: fade
    menu: true
    scrollable: true
---

16.2 课程展示模板

---
title: "COMP 课程汇报"
subtitle: "Week 8 Presentation"
author: "Your Name"
date: today
format:
  revealjs:
    theme: simple
    slide-number: true
    footer: "COMP / Week 8"
    logo: logo.png
    incremental: true
    chalkboard: true
---

16.3 图文对照 + 打印友好模板

---
title: "Research Update"
author: "Your Name"
format:
  revealjs:
    theme: serif
    slide-number: true
    code-block-height: 650px
    output-location: column
    show-notes: separate-page
    pdf-separate-fragments: false
---

17. 常用 Front Matter 配置项总表（按类别整理）

下面这部分按官方 Revealjs Options 参考页整理，优先列出 revealjs 常用/相关项。

17.1 文档元信息

title
subtitle
date
date-format
author
institute
keywords
description-meta
author-meta
date-meta
pagetitle
title-prefix
order

17.2 通用格式与样式

format: revealjs
brand
theme
css
email-obfuscation
html-q-tags
quarto-required

17.3 目录与编号

toc
toc-depth
toc-title
number-sections
number-depth
number-offset
shift-heading-level-by

17.4 Slide 结构

incremental
slide-level
slide-number
show-slide-number
title-slide-attributes
title-slide-style
center-title-slide
show-notes
rtl

17.5 Slide 内容

logo
footer
scrollable
smaller
output-location

17.6 工具与插件

overview
menu
chalkboard
multiplex
scroll-view

17.7 动画与过渡

transition
transition-speed
background-transition
fragments
auto-animate
auto-animate-easing
auto-animate-duration
auto-animate-unmatched
auto-animate-styles

17.8 导航与交互

progress
history
touch
keyboard
mouse-wheel
loop
shuffle
controls
controls-layout
controls-tutorial
controls-back-arrows
navigation-mode
hash
hash-type
hash-one-based-index
jump-to-slide
pause
help
slide-tone

17.9 自动播放与计时

auto-slide
auto-slide-stoppable
auto-slide-method
default-timing

17.10 打印 PDF

pdf-max-pages-per-slide
pdf-separate-fragments
pdf-page-height-offset

17.11 媒体与背景

preview-links
auto-play-media
preload-iframes
view-distance
mobile-view-distance
parallax-background-image
parallax-background-size
parallax-background-horizontal
parallax-background-vertical

17.12 页面尺寸与布局

auto-stretch
width
height
min-scale
max-scale
center
disable-layout
code-block-height
margin
max-width
margin-left
margin-right
margin-top
margin-bottom
cap-location
fig-cap-location
tbl-cap-location
classoption

17.13 代码相关

code-fold
code-summary
code-overflow
code-line-numbers
code-copy

说明：上表是按官方参考页中与 revealjs 强相关的项目整理的“工作清单”。真正写幻灯片时，最常用的仍然是前几节演示过的那批配置。

18. 推荐实践

如果你是第一次用 Quarto + Revealjs，建议优先掌握下面这组能力：

## / # / --- 分页
theme、slide-number、incremental
.columns 分栏
.notes 演讲者备注
background-image / background-color
transition / auto-animate
.scrollable / .smaller
quarto preview 实时预览

如果是学术/技术汇报，再额外掌握：

code-line-numbers
output-location
panel-tabset
show-notes: separate-page
footer / logo

19. 常见坑

19.1 `scrollable` 和自动拉伸图片冲突

症状：某些页图片不显示或布局奇怪。
解决：auto-stretch: false，或给该页加 .nostretch。

19.2 `chalkboard` 和 `embed-resources` 不能同时开

官方文档明确说明二者不兼容。

19.3 Tabset 打印 PDF 只显示第一个标签

如果你打算导出 PDF，不要把关键信息只放在第二、第三个 tab 里。

19.4 备注/预览 iframe 依赖外部资源时可能失败

Speaker Notes 中依赖前端 JS 的内容可能不能正常显示
preview-links 也可能因为目标站点的 iframe 安全策略被拦截

20. 一个比较完整的示例

---
title: "Quarto + Revealjs Demo"
subtitle: "A Practical Example"
author: "nite"
format:
  revealjs:
    theme: dark
    slide-number: true
    incremental: true
    transition: fade
    menu: true
    footer: "Demo / 2026"
    code-block-height: 650px
    scrollable: false
---

# 第一部分

## 研究问题

- 背景
- 动机
- 挑战

## 方法总览

:::: {.columns}

::: {.column width="50%"}
- 模块 A
- 模块 B
- 模块 C
:::

::: {.column width="50%"}
![](pipeline.png){.r-stretch}
:::

::::

## 代码示例

```python {code-line-numbers="|2|3"}
def add(a, b):
    x = a + b
    return x
```

## 背景图页 {background-image="bg.jpg" background-size="cover" background-opacity="0.35"}

一句核心结论

## 长内容页 {.scrollable .smaller}

这里放很多补充材料……

## 备注页

正文内容

::: {.notes}
这里写你真正演讲时要说的话。
:::

21. 总结

可以把 Quarto + Revealjs 理解成：

Quarto 负责写作、渲染和统一配置
Revealjs 负责网页幻灯片的交互、动画与演示体验

最核心的学习顺序是：

先学会基本分页和 YAML
再学 incremental、columns、notes
再学背景、过渡、动画
最后补齐 PDF、菜单、画板、自动播放等高级能力

如果你后面愿意，我还可以继续给你补两份东西：

“适合中文学术汇报的 Quarto Revealjs 模板”
“适合课程作业展示的简约深色主题模板”