Quelques astuces pour Quarto lors du rendu en diaporama reveal.js

La documentation reveal.js de Quarto est le meilleur endroit pour trouver les instructions permettant de créer des présentations reveal.js impeccables.

Dans cet article, nous allons passer rapidement en revue quelques astuces pour rendre vos présentations reveal.js encore meilleures.

Pour le workflow complet — écrire, prévisualiser et exporter un diaporama reveal.js en HTML et en PDF depuis un devcontainer — voir Améliorez vos présentations avec Quarto, reveal.js, Decktape, Docker et les DevContainers.

Travailler avec les slides​

Créer une slide de titre​

La slide de titre est la première de votre présentation. Vous pouvez ajouter une telle slide avec quelques lignes de yaml :

---
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

Le diaporama comportera quatre slides, la première sera la title-slide.

Afficher un logo en haut à gauche sur la première slide, puis en bas à droite​

L'exemple ci-dessous illustre le besoin : sur votre première slide, vous voulez rendre votre logo bien plus visible que sur les autres slides.

Pour y arriver, sur la première slide affichée, votre logo sera affiché en haut à gauche avec une certaine taille, alors qu'au changement de slide, le logo sera positionné en bas à droite et sera bien plus petit.

Voici un exemple visuel :

Pour cela, nous allons devoir ajouter un JavaScript personnalisé et un CSS personnalisé.

Créez un nouveau dossier appelé assets et, dans ce dossier, un fichier appelé style.css et un second appelé custom.js.

Maintenant, utilisez-les dans votre slides.md comme ceci :

---
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>
---

Comme vous le voyez ci-dessus, le code JavaScript est injecté dans votre présentation via la directive header-includes. Pour la feuille de style, c'est la directive css qui est utilisée (il n'y a malheureusement pas de directive js:).

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Ajouter une image de fond à une slide​

Un fond, un titre et un peu de style :

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

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Background-size contain ou cover​

Parfois, l'affichage de l'image n'est pas celui que vous souhaitez ; c'est le cas quand l'image est trop grande et/ou la slide trop étroite.

L'illustration ci-dessous le montre : la photo du paresseux est beaucoup trop grande et vous ne pouvez pas la voir en entier.

Cela peut être corrigé en utilisant l'attribut background-size. Quand il n'est pas mentionné (comme pour la première slide ci-dessous), la valeur par défaut est cover (voir https://developer.mozilla.org/en-US/docs/Web/CSS/background-size pour plus d'informations).

Vous pouvez demander au navigateur de redimensionner l'image pour qu'elle soit affichée en entier. C'est le comportement quand background-size vaut contain.

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

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

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

La slide ci-dessous utilise cover et, non, ce n'est pas vraiment attrayant.

La seconde slide utilise contain et, au moins, on voit ce que le paresseux essayait de nous dire.

Slide-level​

Le niveau de slide est un élément de configuration important (documentation officielle).

Si nous regardons le Markdown ci-dessous, combien de slides aurons-nous ? Deux ou trois ? La première pour le titre, la seconde pour Technologies and tools, mais Apache sera-t-il une slide séparée ou non ?

---?
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.

En fait, cela dépend du réglage slide-level. Par défaut, slide-level vaut 2 et le résultat sera alors :

Nous avons deux slides. Sur la seconde, on voit notre titre de niveau 3 Apache comme du texte dans Technologies and tools.

Si vous voulez qu'une slide soit créée pour chaque titre de niveau 2 et de niveau 3 (ou plus), vous devez le définir avec 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.

Et le résultat donnera :

Utiliser des emoji​

C'est simple, ajoutez juste l'entrée suivante dans votre front matter YAML.

---
from: markdown+emoji
---

Vous pouvez ensuite ajouter des emoji en tapant simplement le code comme :wave: ou :raised_hands:.

Vous trouverez une liste complète sur https://gist.github.com/rxaviers/7360908.

Texte en grand​

La classe r-fit-text (doc officielle) donnera la taille maximale à votre contenu, c'est-à-dire :

#

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

Stretch​

La classe r-stretch (doc officielle) est ma préférée.

Prenez l'exemple ci-dessous :

# Slide 1

Here is an image:

![Quarto slide with stretched image](image.webp){.r-stretch}?

Some text after the image.

Cela génèrera cette slide :

Ajouter beaucoup plus de texte / de paragraphes donnera cette nouvelle slide :

La hauteur de l'image sera redimensionnée automatiquement pour que le texte et les images tiennent sur la même slide. Si vous avez moins de texte, la hauteur de l'image sera plus grande, plus petite sinon. Sans devoir redimensionner l'image manuellement sur le disque. Très utile.

Afficher une image à la pression d'une touche​

En utilisant ::: {.fragment .fade-up} pour définir une zone de contenu, vous demandez à reveal.js de n'afficher son contenu qu'à la séquence de touches suivante.

# 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)
:::

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Créer des colonnes​

Vous pouvez utiliser columns pour diviser votre 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)
:::
:::

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Quatre quadrants​

L'exemple ci-dessous vient de https://mine.quarto.pub/hello-quarto/#/quarto-highlights, un diaporama reveal.js réalisé avec Quarto.

L'idée est de découper les slides en quatre parties et d'afficher le contenu dans le sens horaire, en commençant par le cadran en haut à gauche.

::: 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%"}
:::
:::

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Créer notre propre short code, facilement​

J'aime pouvoir écrire ==Important text== et, pour une présentation revealjs, transformer automatiquement ce texte en <mark>Important text</mark> afin de pouvoir facilement lui appliquer un CSS personnalisé.

D'abord, créez un assets/custom.js s'il n'existe pas encore et copiez/collez le code suivant :

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>");?
    } );
});

Dans votre front matter YAML, ajoutez ceci :

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

Et maintenant, quand le diaporama sera joué, un code JavaScript personnalisé remplacera à la volée chaque fragment ==xxxx== par <mark>xxx</mark>.

CSS​

Utiliser du css inline​

Vous pouvez appliquer des styles à du texte inline en créant des spans : [] pour entourer le texte à styler et {} pour définir le style à appliquer.

# 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;"}.?

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Le rendu est correct en HTML :

Utiliser un css personnalisé​

Utilisez le bloc d'en-tête YAML pour cela.

---
pagetitle: "Using my custom css"
format:?
  revealjs:?
    theme: custom.css?
---
##?

![Mimikyu example image](./images/mimikyu.webp){style="width:400px;"}?

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Maintenant, créez le fichier custom.css dans le même dossier que votre fichier Markdown et, par exemple, mettez le fond de la slide en jaune :

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

Masquer la légende de l'image​

Par défaut, revealjs affiche la légende de l'image en dessous de celle-ci. Vous pouvez la masquer avec cette feuille de style :

.reveal p.caption {
  display: none;
}

Les callouts peuvent être stylés​

Un callout est une div spéciale comme ci-dessous :

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

Dans revealjs, personnellement, je trouve que le rendu prend trop de place par rapport au contenu de ma slide. J'utilise donc du css pour masquer le titre :

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

Navigation​

Slides verticales​

Il existe trois types de navigation : linear (celle par défaut), vertical ou grid (doc officielle).

Si vous utilisez la navigation vertical ou grid, vous devriez structurer vos slides avec des titres de niveau 1 pour l'axe horizontal et des titres de niveau 2 pour l'axe vertical.

Dans une navigation linear normale, revealjs affichera chaque slide, quelle que soit la touche pressée par l'utilisateur. Dans une navigation linear, en tant qu'auteur, vous êtes sûr que votre visiteur verra chacune d'elles.

Dans une navigation vertical ou grid, c'est comme si vous montriez le titre du chapitre : si l'utilisateur presse la touche down ou space, il entrera dans le chapitre (et ce verticalement). Mais s'il presse la touche right, il le sautera et passera au chapitre suivant.

Le navigation-mode dans l'en-tête yaml vous permet d'activer le mode vertical, voici un exemple :

---
title: "Presentation"
format:?
  revealjs:?
    navigation-mode: vertical?
---

# Slide 1

## Slide 1.1

# Slide 2

## Slide 2.1

## Slide 2.2

## Slide 2.3

Définir un nom pour votre slide​

Par défaut, reveal.js génèrera un slug depuis le titre pour que vous puissiez référencer la slide dans une URL.

Prenez l'exemple suivant :

## 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.

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

L'URL générée pour la première slide sera http://[...]index.html#/elit-ad-fugiat-proident-culpa-sint et, pour la seconde slide, http://[...]index.html#/cillum-do-et-commodo-minim-ullamco-elit-culpa.

Pour définir le nom vous-même, ajoutez juste {#} suivi du slug que vous souhaitez.

<!-- 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.

Mais attention au menu des slides (en bas à gauche) : il est peut-être bon d'y définir aussi un nom adapté.

Pour cela, définissez l'attribut data-menu-title ; p.ex. :

<!-- 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"}?

Afficher le numéro de slide​

Pour n'afficher que le numéro de la slide courante, vous pouvez utiliser slide-number: true mais, si vous voulez aussi le nombre total de slides, vous devriez utiliser slide-number: c/t :

format:
  revealjs:
    slide-number: c/t?

Vous trouverez plus d'informations dans la documentation Quarto sur les numéros de slides.

Divers​

Utiliser les notes du présentateur​

Vous pouvez écrire dans votre présentation des messages qui ne seront pas affichés lors de la lecture du diaporama, mais seulement sur un second écran quand le présentateur le souhaite.

L'exemple ci-dessous l'illustre. La façon d'insérer de telles notes de présentateur est d'utiliser le bloc ::: notes.

##

::: 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)
```

Pour exécuter cet exemple, lancez quarto render slides.md --to revealjs.

Donc, dans l'exemple ci-dessus, nous aurons deux slides. En pressant la touche s du clavier (s pour speakers), une nouvelle fenêtre s'affichera.

Quand vous avez deux écrans, sur le premier vous affichez votre présentation sans les notes (écran de gauche ci-dessous) et sur le second vous affichez les notes (écran de droite ci-dessous).

Si vous partagez votre écran via un outil comme Teams ou Zoom, même chose : vous partagez l'écran où la présentation est affichée (le premier) et gardez les notes pour vous seul.

Comme vous le voyez sur l'image ci-dessus, les notes du présentateur affichent des informations utiles comme le temps écoulé depuis le début de la présentation, l'heure actuelle et la slide suivante pour faciliter votre transition.