4 Introduction au yaml

4.1 Principes généraux

Il s’agit du header du document qui comprend toutes les métadonnées du document: titre, date, options de mise en page, options d’exécution….
La syntaxe du yaml est très sensible à l’intendation¹. Les règles restent néanmoins assez simples.
Il s’agit du header du document qui comprend toutes les métadonnées du document: titre, date, options de mise en page, options d’exécution….il s’agit des différentes options entrant dans la partie <head> </head> du code source html.
La syntaxe du yaml est très sensible à l’intendation². Les règles restent néanmoins assez simples.
Lors de la compilation, le yaml est le premier élément qui est évalué. En cas d’erreur elle sera stoppée quasi instantanément.

4.2 Balisage et commentaires

Balisage du yaml

En tête du code source du fichier .qmd, la zône du yaml est balisée par 3 tirets:

Zône pour les options du yaml

---
options du yaml
---

Les commentaires

Tout simplement avec #

4.3 Les Règles de retrait: intendation

Options
- Si aucune autre option: On peut placer la première lettre ou l’on veut

---
titre: "Le yaml"
---

---
       titre: "Le yaml"
---

Si autres options: elle doivent toutes être alignées. Si la première option n’est pas sur le premier caractère de la ligne , la seconde commencer au même niveau.

Erreur

---
       titre: "Le yaml"
format: html
---

---
       titre: "Le yaml"
       format: html
---

Sous options
- Les sous options commencent au moins niveau du second caractère de l’option ou de la sous-option de niveau supérieur (option parente).
- Il est d’usage de placer les sous options au niveau du troisième caractère (deux espaces)

Si les espaces sont indiqués par un .

Règles de retrait

---
option: 
..sous-option1: argument
..sous-option2: argument
....sous-sous-option21: argument
....sous-sous-option22: argument
---

Exemple:

On veut ajouter un nom d’auteur/autrice: option author: "Bidibule

Ajout de deux options

---
title: "yaml d'un document"

author: "Bidibule"
---

Si on souhaite ajouter le lieu d’exercice, le nom devient une sous option de author et est renseigné avec la sous option name: "Bidibule". Sur le même principe le lieu d’exercice sera donné par l’option affiliation: "Bidibules inc".

Ajout de sous options

---
title: "yaml d'un document"

author:
  name: "Bidibule"
  affiliation: "Bidibules inc"  
---

Exemple 2: format hmtl et pdf

Le html est le format par défaut d’un notebook ou d’une présentation via le format reveal js. Si on veut indiquer explicitement le format html, c’est l’argument de l’option format. Si on veut ajouter des sous options au format html comme des thèmes (document, bloc de code) et/ou un autre format (pdf), sur le même principe que l’exemple précédent, html: devient une sous option de l’option format. Si on ne souhaite pas ajouter d’autres options pour la compilation en pdf, la sous option est renseignée par pdf:default. Elle se trouve sur le même niveau de retrait que html:.

Options pour deux formats

---
title: "yaml d'un document"

format: 
  html:
    theme: zephyr
    highlight-style: dracula
  pdf: default  
---

Ce qui nous donne au final le template suivant:

Un yaml avec options et sous options

---
title: "yaml d'un document"

author:
  name: "Bidibule"
  affiliation: "Université X" 

format: 
  html:
    theme: zephyr
    highlight-style: dracula 
  pdf: default
---    

<!-- corps du document qmd -->

4.4 A savoir

Dans Rstudio

Si RStudio repère une erreur dans le retrait, une croix rouge apparaitra à droite du numero de ligne. Pratique.

Extension externe qui ne s’active pas

Il arrive que certaines options installées sous forme d’extension ne s’active pas après la compilation. C’est désagréable. Je n’arrive pas à expliquer pourquoi, mais le changement de position dans le yaml ou en ajoutant/supprimant une ligne vide entre cette option et une autre peut résoudre le problème… où alors on attend que cela finisse par fonctionner après plusieurs compilations.

Par rapport au yaml d’un projet

Le yaml du document à la priorité sur le yaml du projet: pas pour tout, mais on peut donc contredire des éléments de configuration qui sont dans le fichier _quarto.yaml dans un fichier .qmd.
Exemple: on active une table des matière pour chaque .qmd du projet dans _quarto.yaml (toc: true). On peut la supprimer dans un ou plusieurs fichiers .qmd avec toc:false dans le yaml du fichier.

Dans cette section on a juste regardé les règles de retrait des options. Dans le fichier de configuration les sous options peuvent prendre la forme de liens vers des fichiers .qmd comme les différents chapitres d’un book. La même règle est appliquée. A ce stade, juste pour information:

Exemple d'un fichier _quarto.yml


book:
  title: "Formation Quarto"
  chapters:
    - chap1.qmd
    - chap2.qmd
    - chap3.qmd

qui se traduit ici par retrait↩︎
On gardera le mot anglais, qui peut se traduire ici par retrait↩︎

--- filters: - nutshell --- # Introduction au yaml ## Principes généraux [[:GIT YAML](https://fr.wikipedia.org/wiki/YAML)]{.nut} * Il s'agit du header du document qui comprend toutes les métadonnées du document: titre, date, options de mise en page, options d'exécution.... * La syntaxe du yaml est très sensible à l'*intendation*^[qui se traduit ici par *retrait*]. Les règles restent néanmoins assez simples. * Il s'agit du header du document qui comprend toutes les métadonnées du document: titre, date, options de mise en page, options d'exécution....il s'agit des différentes options entrant dans la partie **`<head> </head>`** du code source html. * La syntaxe du yaml est très sensible à l'*intendation*^[On gardera le mot anglais, qui peut se traduire ici par *retrait*]. Les règles restent néanmoins assez simples. * Lors de la compilation, le yaml est le premier élément qui est évalué. En cas d'erreur elle sera stoppée quasi instantanément. ## Balisage et commentaires **Balisage du yaml** En tête du code source du fichier .qmd, la zône du yaml est balisée par **3 tirets**: ```{.yaml filename="Zône pour les options du yaml"} --- options du yaml --- ``` **Les commentaires** Tout simplement avec **`#`** ## Les Règles de retrait: intendation * Options * Si aucune autre option: On peut placer la première lettre ou l'on veut :::: {.columns} ::: {.column width="47.5%"} :::callout-tip ### OK ```{.yaml} --- titre: "Le yaml" --- ``` ::: ::: ::: {.column width="5%"} ::: ::: {.column width="47.5%"} :::callout-tip ### OK ```{.yaml} --- titre: "Le yaml" --- ``` ::: ::: :::: * Si autres options: elle doivent toutes être alignées. Si la première option n'est pas sur le premier caractère de la ligne , la seconde commencer au même niveau. :::: {.columns} ::: {.column width="47.5%"} :::callout-warning ### Erreur ```{.yaml} --- titre: "Le yaml" format: html --- ``` ::: ::: ::: {.column width="5%"} ::: ::: {.column width="47.5%"} :::callout-tip ### OK ```{.yaml} --- titre: "Le yaml" format: html --- ``` ::: ::: :::: * Sous options * Les sous options commencent au moins niveau du second caractère de l'option ou de la sous-option de niveau supérieur (option parente). * Il est d'usage de placer les sous options au niveau du troisième caractère (deux espaces) Si les espaces sont indiqués par un `.` ```{.yaml filename="Règles de retrait"} --- option: ..sous-option1: argument ..sous-option2: argument ....sous-sous-option21: argument ....sous-sous-option22: argument --- ``` Exemple: - On veut ajouter un nom d'auteur/autrice: option `author: "Bidibule` ```{.yaml filename="Ajout de deux options"} --- title: "yaml d'un document" author: "Bidibule" --- ``` - Si on souhaite ajouter le lieu d'exercice, le nom devient une sous option de `author` et est renseigné avec la sous option `name: "Bidibule"`. Sur le même principe le lieu d'exercice sera donné par l'option `affiliation: "Bidibules inc"`. ```{.yaml filename="Ajout de sous options"} --- title: "yaml d'un document" author: name: "Bidibule" affiliation: "Bidibules inc" --- ``` Exemple 2: format hmtl et pdf Le html est le format par défaut d'un notebook ou d'une présentation via le format **reveal js**. Si on veut indiquer explicitement le format html, c'est l'argument de l'option `format`. Si on veut ajouter des sous options au format html comme des thèmes (document, bloc de code) et/ou un autre format (pdf), sur le même principe que l'exemple précédent, `html:` devient une sous option de l'option format. Si on ne souhaite pas ajouter d'autres options pour la compilation en pdf, la sous option est renseignée par `pdf:default`. Elle se trouve sur le même niveau de retrait que `html:`. ```{.yaml filename="Options pour deux formats"} --- title: "yaml d'un document" format: html: theme: zephyr highlight-style: dracula pdf: default --- ``` Ce qui nous donne au final le template suivant: ```{.yaml filename="Un yaml avec options et sous options"} --- title: "yaml d'un document" author: name: "Bidibule" affiliation: "Université X" format: html: theme: zephyr highlight-style: dracula pdf: default ---  ``` ## A savoir **Dans Rstudio** Si RStudio repère une erreur dans le retrait, une croix rouge apparaitra à droite du numero de ligne. Pratique. **Extension externe qui ne s'active pas** Il arrive que certaines options installées sous forme d'extension ne s'active pas après la compilation. C'est désagréable. Je n'arrive pas à expliquer pourquoi, mais le changement de position dans le yaml ou en ajoutant/supprimant une ligne vide entre cette option et une autre peut résoudre le problème... où alors on attend que cela finisse par fonctionner après plusieurs compilations. **Par rapport au yaml d'un projet** Le yaml du document à la priorité sur le yaml du projet: pas pour tout, mais on peut donc contredire des éléments de configuration qui sont dans le fichier `_quarto.yaml` dans un fichier .qmd. Exemple: on active une table des matière pour chaque .qmd du projet dans _quarto.yaml (`toc: true`). On peut la supprimer dans un ou plusieurs fichiers .qmd avec `toc:false` dans le yaml du fichier. Dans cette section on a juste regardé les règles de retrait des options. Dans le fichier de configuration les sous options peuvent prendre la forme de liens vers des fichiers .qmd comme les différents chapitres d'un book. La même règle est appliquée. A ce stade, juste pour information: ```{.yaml filename="Exemple d'un fichier _quarto.yml"} book: title: "Formation Quarto" chapters: - chap1.qmd - chap2.qmd - chap3.qmd ```