Affichage conditionnel avec Quarto

Comme moi, vous avez sûrement abandonné Microsoft Word, PowerPoint et compagnie pour tout faire en Markdown. Comme moi, vous utilisez le même fichier Markdown pour générer votre documentation en html, pdf, docx, pptx, revealjs, ... selon les besoins, au cas par cas.

Mon cas d'usage personnel est le suivant. J'ai un seul fichier readme.md, parfois volumineux, pour la documentation d'un outil que j'ai créé. Dans ce document, je peux afficher par exemple des tableaux comportant plusieurs colonnes, parfois très larges. Aucun problème si j'affiche la documentation en HTML : le navigateur propose une barre de défilement horizontale. Mais quand je génère un PDF, le tableau explose la largeur de ma page et le résultat est affreux.

Même idée : si ma sortie est une page HTML, je peux facilement afficher un listing de quelques dizaines de lignes de mon code source, par exemple pour illustrer une fonctionnalité. En revanche, dans un diaporama, ce serait contre-productif : la slide serait énorme et peu efficace.

Et si mon objectif est de générer un diaporama, la dernière partie de ma documentation sera un chapitre Merci de votre attention ! Avez-vous des questions ?. Celui-là ne doit certainement pas apparaître dans la sortie docx / pdf / html. Juste pour l'affichage revealjs (ou PowerPoint, si votre public y tient).

content-visible when​

La syntaxe est très simple : il suffit d'utiliser le tag spécial ::: pour délimiter une zone dans le fichier, puis d'utiliser un filtre spécial appelé content-visible. Pour la syntaxe en détail, voyez la documentation officielle

Voyons ça en action. Créez un simple fichier Markdown (conditional-display.md) sur votre disque et appelez quarto avec quarto render conditional-display.md --to xxx en remplaçant xxx par, par exemple, docx, pdf, html, revealjs, ...

# Conditional display

::: {.content-visible when-format="html"}
This paragraph will only appear in HTML.
:::

::: {.content-visible when-format="docx"}
And this one only when the output format is Word
:::

::: {.content-visible when-format="revealjs"}
I'm part of the slideshow
:::

En rendant l'exemple Markdown ci-dessus vers Word, nous obtenons le titre et le paragraphe when-format="docx" :

Pour when-format="html" aussi, seulement le titre et un paragraphe :

Pour when-format="revealjs", c'est un peu plus malin puisque revealjs est un document HTML :

Et comme nous n'avons aucun paragraphe non conditionnel, la conversion en PDF ne donne que le titre.

Le when-format="xxx" fonctionne donc exactement comme prévu.