Skip to main content

Some tips and tricks for Quarto when rendering as a reveal.js slideshow

Elevate your Quarto presentations! Discover essential tips and tricks for rendering stunning reveal.js slideshows, including custom title slides, logo placement, CSS/JS customization, and advanced slide layouts.

· 12 min read
View raw
Christophe
Markdown, WSL and Docker lover ~ Insatiable curious.
Cet article existe aussi en français — lire la version française.

This article is over a year old but was reviewed on July 30, 2026 — the content is still accurate.

Some tips and tricks for Quarto when rendering as a reveal.js slideshow

⚡
TL;DR

This article is a grab bag of Quarto reveal.js tips: title slides, custom logo positioning with CSS/JS, background images and their background-size behavior, slide-level control, emoji, r-fit-text and r-stretch classes, fragment-based reveals, multi-column and quadrant layouts, custom short codes, inline and external CSS, hiding image captions, styling callouts, vertical/grid navigation, custom slide slugs, slide numbers, and speaker notes.

The Quarto reveal.js documentation is the best place to find instructions for creating impeccable reveal.js presentations.

In this article, we'll take a quick look at a few tips and tricks to make your reveal.js presentations even better.

For the complete workflow — writing, previewing and exporting a reveal.js slideshow as HTML and PDF from a devcontainer — see Level Up Your Presentations with Quarto, reveal.js, Decktape, Docker and DevContainers.

Docker image with Quarto

If you don't have yet a Docker image with Quarto, read this article Running Quarto Markdown in Docker.

Working with slides​

Create a title slide​

The title slide is the first one of your presentation. You can add such slide with a few yaml lines:

---
title: "My Slide Show"
title-slide-attributes:
data-background-image: ./img/background.jpg
data-background-size: cover
data-background-opacity: "0.9"
---
# Slide 1
# Slide 2
# Slide 3

This is a configuration file for a slide presentation (likely Pandoc or Reveal.js based). The front matter (lines 1-7) sets up metadata for the presentation, including a title and styling for the title slide with a background image. The rest of the file defines three slide sections marked by heading tags.

The slideshow will have four slides, the first one will be the title-slide.

Title slide

Display a logo top left on the first slide, then bottom right​

The example below illustrates the need: on your first slide, you want to make your logo much more visible than on the other slides.

To achieve this, on the first slide displayed, your logo will be displayed at the top left with a certain size, whereas when you change slides, the logo will be positioned at the bottom right and will be much smaller.

Here is a visual example:

Logo top left

Logo bottom right

To do this, we'll need to add a custom JavaScript and custom CSS.

Create a new folder called assets and, in that folder, a file called style.css and a second called custom.js.

📦 Project setup: assets
Help

Need help here? Click the "Help" button above for setup instructions.

Now, use them in your slides.md like this:

---
title: "My Slide Show"
subtitle: "Playing with logo"
author: "Christophe Avonture"
date: last-modified
lang: "en"
format:
revealjs:
logo: images/my-logo.svg
css: assets/style.css
resources: images
header-includes: |
<script src="assets/custom.js" type="application/javascript"></script>
---

This is a YAML configuration file for a Reveal.js presentation that sets up metadata like the title and author, and configures how the presentation should be rendered with a custom logo, stylesheet, image resources, and a JavaScript file.

As you can see above, the JavaScript code is injected in your presentation using the header-includes directive. For the stylesheet, the css directive is used (there is no js: directive unfortunately).

To run this example, run quarto render slides.md --to revealjs.

Adding a background image to a slide​

A background, a title and some style:

# Merry Christmas {background-image="images/winter.jpg" style="text-align: center; background-color: #cfb0f399; color: #210753;"}

This is a markdown heading with embedded styling attributes for a Christmas-themed page section. It sets up a centered title with a winter background image, a semi-transparent purple background color, and dark purple text.

To run this example, run quarto render slides.md --to revealjs.

Adding a background image to a slide

Background-size contain or cover​

Sometimes the image display isn't what you'd like; this is the case when the image is too large and/or the slide too narrow.

The illustration below shows this: the photo of the sloth is far too large and you can't see the whole thing.

This can be corrected by using the attribute background-size. When not mentioned (as for the first slide below), the default value is cover (see https://developer.mozilla.org/en-US/docs/Web/CSS/background-size to get more information).

You can ask the browser to resize the image so it's fully displayed. This is the behavior when background-size is set to contain.

## {background-image="images/2024.jpg"}
## {background-image="images/2024.jpg" background-size="contain"}

These are two slide header declarations that set background images for presentation slides. The first one uses a default background size, while the second explicitly specifies that the image should fit entirely within the slide without being cropped.

To run this example, run quarto render slides.md --to revealjs.

The slide below is using cover and, no, not really attractive.

Background-size is set to cover

The second slide is using contain and, at least, we can see what the sloth was trying to tell us.

Background-size is set to contain

Slide-level​

The slide level is an important configuration item (official documentation).

If we look at the Markdown below, how many slides will we have? Two or three? The first is for the title, the second for Technologies and tools, but will Apache be a separate slide or not?

---
title: "Playing with slide-level"
---
## Technologies and tools
### Apache
Our web applications are running under [Apache](https://httpd.apache.org/).
We don't need to have Apache locally since we're using it as a Docker image.

This is a markdown document header that introduces a page about technologies and tools, specifically starting with information about Apache web server and its use in Docker containers.

In fact, it depends on the slide-level setting. By default, slide-level is equal to 2 and then, the result will be:

Slide level 2

We've two slides. On the second slide, we can see our Apache heading 3 as a text on Technologies and tools.

If you want a slide to be created for each level 2 and level 3 (or higher) title, you need to set this with slide-level.

---
title: "Playing with slide-level"
# highlight-next-line
format:
# highlight-next-line
revealjs:
# highlight-next-line
slide-level: 3
---
## Technologies and tools
### Apache
Our web applications are running under [Apache](https://httpd.apache.org/).
We don't need to have Apache locally since we're using it as a Docker image.

This is a YAML configuration file for a Reveal.js presentation (a tool for making slideshows). It's setting up the presentation so that headings with three hash marks (###) become the top-level slides, rather than the usual two hash marks (##). This lets you organize your content with more granular control over what appears on each slide.

And the result will give:

Slide level 3

Using emoji​

It's simple, just add the following entry to your YAML front matter.

---
from: markdown+emoji
---

Then you can add emoji by just typing the code like :wave: or :raised_hands:.

You can find a full list on https://gist.github.com/rxaviers/7360908.

Big text​

The r-fit-text class (official doc) will give the maximum size to your content i.e.

#
::: {.r-fit-text}
Big Text
:::

This is a Pandoc markdown syntax block that declares 'Big Text' as content that should be automatically sized to fit its container. It's typically used in presentations or documents where you want text to scale responsively based on available space.

Big text

Stretch​

The r-stretch class (official doc) is my preferred one.

Consider the example below:

# Slide 1
Here is an image:
![Quarto slide with stretched image](image.webp){.r-stretch}
Some text after the image.

This is a Quarto slide that displays an image with the filename 'image.webp' using a special stretching effect, followed by some text. The `.r-stretch` class makes the image expand to fill available space on the slide.

This will generate this slide:

Stretch 1

Adding a lot of more text / paragraphs will give this new slide:

Stretch 2

The image height will be resized automatically so both text and images can be displayed on the same slide. If you have less text, the height of the image will be bigger, smaller otherwise. Without to have to manually resize the image on the disk. Very useful.

Show an image on key press​

Using ::: {.fragment .fade-up} to define a content area, you are asking reveal.js to show its content only the next key sequence.

# It's a candy dog
::: {style="font-size: 2em; color: #75AADB;"}
Would you like to see a candy dog?
:::
::: {.fragment .fade-up}
![Candy dog reveal.js example](./images/dog.webp)
:::

This is a Reveal.js presentation slide that displays a question asking if the viewer wants to see a candy dog, followed by an image of a candy dog that animates in with a fade-up effect when the slide is revealed.

To run this example, run quarto render slides.md --to revealjs.

It&#39;s a candy dog

Creating columns​

You can use columns to divide your slide:

##

::: columns
::: {.column width="70%"}
![Left column: slide example image](./images/image_1.webp)
:::

::: {.column width="30%"}
![Right column: top image](./images/image_2.webp)

![Right column: bottom image](./images/image_3.webp)
:::
:::

To run this example, run quarto render slides.md --to revealjs.

Columns

Four quadrants​

The example below comes from https://mine.quarto.pub/hello-quarto/#/quarto-highlights, a reveal.js slideshow made using Quarto.

The idea is to split the slides in four parts and display content clockwise, starting with the top-left dial.

::: columns
::: {.column width="5%"}
:::

::: {.column width="40%"}
::: bulletbox
::: {.fragment .fade-in-then-semi-out}
![Top-left quadrant example](./images/top-left.webp){width="450px"}
:::
:::
:::

::: {.column width="5%"}
:::

::: {.column width="40%"}
::: bulletbox
::: {.fragment .fade-in-then-semi-out}
![Top-right quadrant example](./images/top-right.webp){width="450px"}
:::
:::
:::

::: {.column width="5%"}
:::
:::

::: columns
::: {.column width="5%"}
:::

::: {.column width="40%"}
::: bulletbox
::: {.fragment .fade-in-then-semi-out}
![Bottom-left quadrant example](./images/bottom-left.webp){width="450px"}
:::
:::
:::

::: {.column width="5%"}
:::

::: {.column width="40%"}
::: bulletbox
::: {.fragment .fade-in-then-semi-out}
![Bottom-right quadrant example](./images/bottom-right.webp){width="450px"}
:::
:::
:::

::: {.column width="5%"}
:::
:::

To run this example, run quarto render slides.md --to revealjs.

Four quadrants

Creating our own short code, easily​

I like to be able to write ==Important text== and, for a revealjs presentation, transform this text automatically to <mark>Important text</mark> so I can easily add a custom CSS to it.

First, create a assets/custom.js if not yet present and copy/paste the following code:

window.addEventListener("load", (event) => {
// This function will search for short code like "==IpsoLorem=="
// i.e. a portion of text between two equal sign and will replace it
// to "<mark>IpsoLorem</mark>" so we can then use CSS to highlight
// that portion.
Reveal.on("slidechanged", function (event) {
var re = /==([^=]*)==/;
event.currentSlide.innerHTML = event.currentSlide.innerHTML.replace(new RegExp(re, "g"), "<mark>$1</mark>");
} );
});

When the page loads, we set up a listener that watches for slide changes in a presentation. Whenever a slide changes, we search through that slide's HTML content for text wrapped in double equal signs (like ==highlighted text==) and replace it with the same text wrapped in HTML mark tags so CSS can style it visually.

In your YAML front matter, add this:

---
format:
revealjs:
header-includes: |
<script src="assets/custom.js" type="application/javascript"></script>
---

This is a YAML configuration block for a Reveal.js presentation (a tool for making slideshows). It's telling the presentation engine to load a custom JavaScript file from the assets folder so you can add extra functionality or styling to your slides.

And now, when the slideshow will be played, a custom JavaScript code will replace on-the-fly each fragment with ==xxxx== and replace with <mark>xxx</mark>.

CSS​

Using inline css​

You can apply styles to inline text by creating spans using [] to surround the text you want to style and {} to define the style you want to apply.

# Inline style
To draw attention to a specific part of the text, you might want to make it [red]{style="color: red;"} with a [yellow background]{style="background-color: yellow;"}; [like this]{style="color: red; background-color: yellow;"}.

This snippet demonstrates how to apply inline CSS styles directly to text in a document by using the style attribute. It shows three examples of styling text with different colors and backgrounds to highlight specific parts of a sentence.

To run this example, run quarto render slides.md --to revealjs.

This is correctly rendered in HTML:

html

Use a custom css​

Use the YAML header block for this.

---
pagetitle: "Using my custom css"
format:
revealjs:
theme: custom.css
---
##
![Mimikyu example image](./images/mimikyu.webp){style="width:400px;"}

This is a Quarto document configuration that sets up a reveal.js slideshow with a custom CSS theme. It defines the page title and then includes a slide with an image that's sized to 400 pixels wide.

To run this example, run quarto render slides.md --to revealjs.

Now, create the custom.css file in the same folder as your Markdown one and, for instance, set the slide background to yellow:

/*-- scss:defaults --*/
.reveal {
background-color: rgb(224, 226, 98);
}

This CSS snippet sets the background color of any element with the class 'reveal' to a yellowish-green color. It's the kind of basic styling you'd use to make certain parts of a presentation or webpage stand out visually.

Custom css

Hide image caption​

By default, revealjs will display the caption of the image below it. You can hide it by using this stylesheet:

.reveal p.caption {
display: none;
}

This CSS rule hides any paragraph elements with the 'caption' class inside elements with the 'reveal' class. It's a way to keep caption text invisible by default, likely until some JavaScript or user interaction makes it visible later.

Callout can be stylized​

A callout is a special div like below:

## Customize your terminal
:::{.callout-note}
## Notice
Skip this part if you do not want to customize your terminal right now
:::
As you can see on the image below, we can customize the terminal:

This is a markdown section introducing terminal customization as an optional topic. It uses a callout box to let readers know they can skip this section if they're not interested in customizing their terminal right now.

In revealjs, personally, I find that the rendering takes up too much space compared to the content of my slide. So I use css to hide the title:

Callout title

.reveal .callout-title {
display: none;
}

This CSS rule hides the callout title elements within reveal containers by setting their display property to none, which removes them from the page layout entirely as if they don't exist.

Vertical slides​

There are three types of navigation: linear (default one), vertical or grid (official doc).

If you use vertical or grid navigation, you should structure your slides using level 1 headings for the horizontal axis and level 2 headings for the vertical axis.

In a normal, linear navigation, revealjs will show each slide, whatever the key the user is pressing on his keyboard. In a linear navigation, as author, you are sure that your visitor will see each of them.

In a vertical or grid navigation, it's just like you're showing the chapter's title and if the user press the down or space key, he will jump in the chapter (and this vertically). But if he is pressing the right key he'll skip it and go to the next chapter.

The navigation-mode in the yaml header allows you to enable vertical mode, below an example:

---
title: "Presentation"
format:
revealjs:
navigation-mode: vertical
---
# Slide 1
## Slide 1.1
# Slide 2
## Slide 2.1
## Slide 2.2
## Slide 2.3

This is a Quarto presentation file that uses reveal.js to create an interactive slideshow. The YAML header at the top configures the presentation settings, specifically telling it to use vertical navigation mode so viewers can scroll up and down through slides. The rest of the file outlines the slide structure with a main title and several nested subsections.

Vertical navigation

Press <kbd>esc</kbd> key

The esc key allow you to see the structure of your revealjs slideshow.

Define a name for your slide​

By default, reveal.js will generate a slug from the title so you can reference the slide in a URL.

Consider the following example:

## Elit ad fugiat proident culpa sint

Elit ad fugiat proident culpa sint qui id pariatur nostrud ullamco velit irure tempor culpa. Laborum occaecat ea tempor voluptate duis pariatur proident ea. Aute adipisicing ut ullamco exercitation nisi nulla sint. Reprehenderit tempor quis non cupidatat.

## Cillum do et commodo minim ullamco elit culpa

Occaecat minim eu veniam laborumanim. Nostrud duis eiusmod ut amet velit commodo. Aliqua laborum cillum officia culpa quis duis enim cillum esse duis excepteur cillum do qui. Veniam dolore enim qui labore proident. Minim ipsum nisi Lorem cillum proident labore cupidatat aliqua pariatur. Nisi id magna incididunt et culpa.

This appears to be a placeholder or Lorem Ipsum-style document with two section headers in Markdown format, followed by filler text. There is no actual code present to explain.

To run this example, run quarto render slides.md --to revealjs.

The generated URL for the first slide will be http://[...]index.html#/elit-ad-fugiat-proident-culpa-sint and, for the second slide, http://[...]index.html#/cillum-do-et-commodo-minim-ullamco-elit-culpa.

To define the name yourself, just add {#} followed by the slug you desire.

<!-- highlight-next-line -->
## Elit ad fugiat proident culpa sint {#intro}
Elit ad fugiat proident culpa sint qui id pariatur nostrud ullamco velit irure tempor culpa. Laborum occaecat ea tempor voluptate duis pariatur proident ea. Aute adipisicing ut ullamco exercitation nisi nulla sint. Reprehenderit tempor quis non cupidatat.
<!-- highlight-next-line -->
## Cillum do et commodo minim ullamco elit culpa {#chapter1}
Occaecat minim eu veniam laborumanim. Nostrud duis eiusmod ut amet velit commodo. Aliqua laborum cillum officia culpa quis duis enim cillum esse duis excepteur cillum do qui. Veniam dolore enim qui labore proident. Minim ipsum nisi Lorem cillum proident labore cupidatat aliqua pariatur. Nisi id magna incididunt et culpa.

This is a markdown document with two sections, each marked with a heading (## syntax) and an anchor ID in curly braces. Each section heading is preceded by an HTML comment telling a renderer to highlight that specific line. The content between headings is Lorem Ipsum placeholder text.

Define a name for your slide

But, pay attention to the slide's menu (bottom left): perhaps it's also good to define a suitable name there.

Also define the name in the menu

To do this, set the data-menu-title attribute; f.i.:

<!-- highlight-next-line -->
## Elit ad fugiat proident culpa sint {#intro data-menu-title="Introduction"}
<!-- highlight-next-line -->
## Cillum do et commodo minim ullamco elit culpa {#chapter1 data-menu-title="Chapter 1"}

This is a Markdown document with two section headers that have custom attributes. Each header has an anchor ID (like #intro and #chapter1) and a data attribute that sets a custom menu title different from the displayed heading text.

Show slide number​

To only show the current slide number, you can use slide-number: true but, if you also want the total number of slides, you should use slide-number: c/t :

format:
revealjs:
slide-number: c/t

This is a YAML configuration file that sets up reveal.js, which is a presentation framework. It's telling the presentation to display slide numbers in the format 'current/total' (like '3/10') at the bottom of each slide.

Slide / Total of slides

You can retrieve more information in the Quarto slide numbers documentation.

Misc​

Using speaker notes​

You can write messages in your presentation that will not be displayed when the slideshow is played, but only as a second screen when the presenter wishes.

The example below illustrates this. The way to insert such presenter's notes is by using the ::: notes block.

##
::: columns
::: {.column width="70%"}
![Left column: speaker notes example image](./images/image_1.webp)
:::
::: {.column width="30%"}
![Right column: speaker notes top image](./images/image_2.webp)
![Right column: speaker notes bottom image](./images/image_3.webp)
:::
:::
::: notes
On the left side, you have ... and, on the right side, the first image is ....
The second image has been ...
:::
##
![Example slide image 4](./images/image_4.webp)
```

This is a presentation slide layout using Pandoc markdown syntax. It creates a two-column layout on the first slide with images on the left (70% width) and two images stacked on the right (30% width), then adds speaker notes explaining what's shown. A second slide follows with a single image.

To run this example, run quarto render slides.md --to revealjs.

So, in the example above, we'll have two slides. By pressing the s key on the keyboard (s for speakers) a new window will be displayed.

When you have two screens, on the first you'll display your presentation without the notes (left screen below) and on the second you'll display the notes (right screen below).

If you share your screen through a tool like Teams or Zoom, same thing; you share the screen where the presentation is displayed (the first one) and keep the notes only for you.

Speaker notes

As you can see on the image above, the speaker notes are displaying valuable information as the elapsed time since the start of the presentation, the current time and the next slide to make your transition easier.


Was this article helpful?
Did you try the steps in this article?