Mes extensions Quarto préférées

J'utilise Quarto depuis 18 mois pour générer ma documentation : j'écris des fichiers Markdown (.md) et je les convertis en document Word, en PDF, en site HTML statique ou en diaporama revealjs. Si Quarto est nouveau pour vous, Exécuter Quarto Markdown dans Docker vous donne une installation fonctionnelle en quelques minutes.

Quarto prend en charge des extensions externes (aussi appelées plugins ailleurs).

Voici une liste de quelques-unes que j'utilise.

gadenbuie/quarto-partials : du contenu partiel réutilisable​

Voir https://github.com/gadenbuie/quarto-partials/tree/main

Quand j'en suis arrivé à cette extension, mon besoin était le suivant : j'avais codé plus de 60 fonctionnalités et je devais les documenter. Chacune aura le même look&feel, avec un chapitre Description, un Comment l'exécuter ?, Comment la configurer ?, Remarques et ainsi de suite.

Parfois le texte sera exactement le même (comme un texte générique) et, dans certains cas, presque le même : le chapitre Comment la configurer ? aura les mêmes phrases, sauf que je dois remplacer quelques placeholders (comme le nom de la fonctionnalité, le nom du fichier de configuration, ...)

Autrement dit : je dois pouvoir écrire une sorte de template de page et y injecter du contenu spécifique. Je veux que mes 60 pages de fonctionnalités se ressemblent et, si je dois changer un texte global, le faire à un seul endroit central.

Partial content est parfait ici. D'après leur documentation, c'est similaire à Mustache.

Exemple​

Créons un fichier appelé _hello.md avec ce contenu :

Hello, {{ name }}!

Ensuite, dans n'importe quel fichier, nous pouvons faire :

{{< partial _hello.md name="John" >}}

Pensez à ajouter les lignes ci-dessous dans votre front matter YAML :

filters:
   - quarto-partials

Nous pouvons passer des variables comme ci-dessus mais, bien plus puissant, nous pouvons déclarer une clé partial-data dans notre frontmatter YAML.

Si vous voulez aller beaucoup plus loin avec cette extension (blocs conditionnels, contenu brut, un cas d'usage réel de documentation), j'ai écrit un article dédié : Utiliser le templating Mustache avec Quarto.

quarto-ext/fontawesome : des icônes Font Awesome​

Voir https://github.com/quarto-ext/fontawesome

Utilisez les icônes Font Awesome dans vos documents HTML et PDF.

Par exemple, si vous voulez une icône GitHub, il suffit de mettre le code {{< fa brands github size=5x >}} dans votre fichier. Plutôt facile.

Pensez à ajouter les lignes ci-dessous dans votre front matter YAML :

filters:
   - fontawesome

quarto-ext/include-code-files : inclure des fichiers externes​

```{.yaml include="files/.gitlab-ci.yml"}
```

```yaml
{{< include files/.gitlab-ci.yml >}}
```

Voir https://github.com/quarto-ext/include-code-files

L'objectif est de pouvoir inclure un fichier externe en utilisant la syntaxe ci-dessous :

```{.bash include="documentation/chapter_1/install.sh"}
```

Pensez à ajouter les lignes ci-dessous dans votre front matter YAML :

filters:
   - include-code-files

quarto-ext/search-replace : des macros de remplacement​

Voir https://github.com/ute/search-replace

Une extension de filtre Quarto pour de simples macros de recherche-remplacement.

Cette extension vous permet de rechercher et remplacer lors du rendu des documents. Par exemple, en mettant le code +quarto dans le frontmatter de l'article ou, mieux, dans le fichier global _quarto.yaml, nous pouvons simplement écrire +quarto (une constante) dans notre document et laisser le remplacement se faire pendant le rendu de la documentation.

search-replace:
  +quarto: "[Quarto](https://quarto.org)"?

Pensez à ajouter les lignes ci-dessous dans votre front matter YAML :

filters:
   - search-replace

Exemple​

Voici comment l'utiliser. C'est simple ; écrivez juste le nom de votre constante et, pendant le rendu de votre document, la constante sera remplacée par la valeur prédéfinie. Facile !

I'm using +quarto and I love it

shafayetShafee/code-fullscreen : du code en plein écran​

Voir https://github.com/shafayetShafee/code-fullscreen

Cette extension concerne les diaporamas revealjs.

Si vous avez un très long bloc de code, revealjs n'affichera pas toutes les lignes et le code sera donc tronqué (seules les 25 premières lignes seront affichées, par exemple).

En ajoutant le filtre ci-dessous à votre frontmatter YAML, un petit bouton Full screen sera affiché en haut à droite du bloc de code.

filters:
   - code-fullscreen