Utiliser des variables depuis un fichier externe dans votre projet Quarto

Mon cas d'usage est le suivant : je dois rédiger une longue documentation technique où je dois fournir des informations comme les adresses IP des serveurs utilisés, des chemins vers l'application, des dossiers de configuration, ...

La manière normale de faire consiste à mettre ces informations directement dans la documentation et à veiller à mettre à jour chaque occurrence en cas de changement durant le cycle de vie de l'application.

La meilleure approche est probablement d'utiliser un fichier externe où l'information est stockée sous forme clé-valeur et, pendant le processus de rendu de Quarto, de remplacer les short codes par les valeurs.

Ce que les variables Quarto vous apportent​

Vous écrivez ceci dans votre source Markdown :

Version {{< var version >}} is a minor upgrade.

Please contact us at {{< var email.info >}}.

Et voici ce que Quarto affiche :

Le numéro de version et l'adresse email vivent désormais dans un seul fichier. Changez-les là, relancez le rendu, et chaque page de la documentation est à jour — y compris les vingt endroits que vous auriez oubliés.

Il suffit de : un _variables.yml contenant vos clés-valeurs, un _quarto.yml (qui peut être vide), et les short codes {{< var >}} / {{< meta >}} dans votre texte.

Mise en place​

Vous trouverez la documentation officielle sur https://quarto.org/docs/authoring/variables.html.

Voici comment procéder :

Donc, _quarto.yml peut rester vide. Sa présence sert juste à dire à Quarto que le fichier Markdown fait partie d'un projet.

Voici un exemple de ce que peut contenir un _variables.yml :

version: 1.2

email:?
  info: info@example.com
  support: support@example.com

engine:?
  jupyter: "[Jupyter](https://jupyter.org)"
  knitr: "[Knitr](<https://yihui.name/knitr>)"

Et voici un exemple de Markdown (fichier documentation.md) :

---
title: Testing of variables short code.
---

{{< meta title >}}

Version {{< var version >}} is a minor upgrade.

Please contact us at {{< var email.info >}}.

Quarto includes {{< var engine.jupyter >}} and
{{< var engine.knitr >}} computation engines.

Comme vous pouvez le voir, le short code ressemble à {{< meta xxx >}} ou {{< var xxx >}}.

meta sert aux métadonnées du document, comme son titre, et var à récupérer des informations depuis _variables.yml.

Lancez le rendu avec quarto preview documentation.md --to html et vous obtenez la page montrée au début de cet article.

Variables d'environnement​

Vous pouvez aussi récupérer des variables d'environnement avec {{< env xxx >}} mais, là, vous devez d'abord charger ces variables si nécessaire.

Par exemple, vous pouvez avoir un fichier .env comme celui-ci :

APPLICATION_NAME=My application name
VERSION_NUMBER=1.2

Ensuite, avant d'appeler le processus de rendu de Quarto, vous devez charger le fichier. Comme j'utilise Docker, je fais ceci :

$ docker run --rm -it -v .:/input -w /input --env-file .env cavo789/quarto quarto preview documentation.md --to html▋

Voici le contenu de documentation.md :

---
title: Testing of variables and env short codes.
---

:::{.callout-tip}
## Environment variables

{{< env APPLICATION_NAME >}} v.{{< env VERSION_NUMBER >}}
:::

{{< meta title >}}

Version {{< var version >}} is a minor upgrade.

Please contact us at {{< var email.info >}}.

Quarto includes {{< var engine.jupyter >}} and
{{< var engine.knitr >}} computation engines.

J'utilise donc --env-file .env dans l'instruction docker run pour que Docker charge mes variables et les rende disponibles dans le container. Quarto peut alors y accéder.

Cette solution est encore meilleure si vous avez une application comme Laravel, et donc déjà un fichier .env de ce type. Résultat : vous réutilisez les mêmes valeurs pour l'application et pour la documentation.

Conclusion​

Les variables sont le bon outil quand ce qui se répète est une valeur : un numéro de version, une IP, une adresse de support, un chemin. Elles coûtent deux fichiers et sont rentabilisées dès le premier serveur renommé.

Quand ce qui se répète est une structure de page entière plutôt qu'une valeur, les variables ne suffisent plus — et c'est là que Utiliser le templating Mustache avec Quarto prend le relais.