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.
This article is over a year old but was reviewed on July 30, 2026 — the content is still accurate.
This article is part of the Discovering Quarto series:
- Running Quarto Markdown in Docker
- Quarto conditional display
- Use Quarto and create a PowerPoint slideshow
- Using variables from external file in your Quarto project
- Some tips and tricks for Quarto when rendering as a reveal.js slideshow
- Quarto Callout Blocks
- Quarto includes short code
- Quarto Inline style
- My favorite Quarto extensions
- Using Mustache templating with Quarto
- Make your Quarto project Devcontainer-Ready — No More Setup Headaches
- Quarto - How I Built a Self-Documenting Ecosystem for 50+ Projects

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 3This 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.

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:

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.
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-modifiedlang: "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.

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.

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

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:
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-lineformat: # 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:
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.
Stretch
The r-stretch class (official doc) is my preferred one.
Consider the example below:
# Slide 1
Here is an image:
{.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:

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

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}:::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.

Creating columns
You can use columns to divide your slide:
##
::: columns
::: {.column width="70%"}

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


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

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}
{width="450px"}
:::
:::
:::
::: {.column width="5%"}
:::
::: {.column width="40%"}
::: bulletbox
::: {.fragment .fade-in-then-semi-out}
{width="450px"}
:::
:::
:::
::: {.column width="5%"}
:::
:::
::: columns
::: {.column width="5%"}
:::
::: {.column width="40%"}
::: bulletbox
::: {.fragment .fade-in-then-semi-out}
{width="450px"}
:::
:::
:::
::: {.column width="5%"}
:::
::: {.column width="40%"}
::: bulletbox
::: {.fragment .fade-in-then-semi-out}
{width="450px"}
:::
:::
:::
::: {.column width="5%"}
:::
:::
To run this example, run quarto render slides.md --to revealjs.

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:

Use a custom css
Use the YAML header block for this.
---pagetitle: "Using my custom css"format: revealjs: theme: custom.css---##
{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.

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}## NoticeSkip 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:

.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.
Navigation
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.3This 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.
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.

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

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/tThis 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.

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%"}:::
::: {.column width="30%"}
::::::
::: notesOn the left side, you have ... and, on the right side, the first image is ....
The second image has been ...:::
##
```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.

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.
This article is part of the Discovering Quarto series:
- Running Quarto Markdown in Docker
- Quarto conditional display
- Use Quarto and create a PowerPoint slideshow
- Using variables from external file in your Quarto project
- Some tips and tricks for Quarto when rendering as a reveal.js slideshow
- Quarto Callout Blocks
- Quarto includes short code
- Quarto Inline style
- My favorite Quarto extensions
- Using Mustache templating with Quarto
- Make your Quarto project Devcontainer-Ready — No More Setup Headaches
- Quarto - How I Built a Self-Documenting Ecosystem for 50+ Projects





