Skip to contents

Source: vignettes/quarto.qmd

Premiers pas avec Quarto

Quelques conseils d’écriture et de format

au commencement

Tout commence par un .qmd. Il doit être placé dans un sous dossier du projet général, pour être rangé de façon compréhensible par tout le monde. Demandez à votre administratrice de projet les règles qu’elle souhaite voir appliquées.

Un exemple de projet est ci-dessous. Il ne respecte pas toutes les règles recommandées, mais c’est souvent comme ça. Notez les fichiers importants :

  • _quarto.yml : dans lequel sont spécifiés les options principales et communes ainsi que les menus et la structure du site

  • index.qmd qui est la page de démarrage du site et qui doit toujours être à la racine du projet et s’appeler index.qmd

  • rinit.r qui contient des options par défaut pour les chunks R (c’est important pour le rendu des graphiques)

  • README.md qui apparaît sur la première page du projet sur github.com

  • _extensions qui contient tous les templates quarto, il faut absolument que ce dossier soit présent (et il ne faut pas y toucher).

legislatives2024
    _quarto.yml
    index.qmd
    about.qmd
    rinit.r
    README.md
    .gitignore
        _extensions/
            ofce/
            ...
    programmes/
        rn.qmd
        nfp.qmd
        Comparatif programmes législatives 2024.xlsx
        ...
    analyses/
        transition.qmd
        tissu_productif.qmd
        ...
        Tables/
            Tableau_retraite.xlsx
            Spreads.xlsx
            spread.rds
            ...

Donnez un nom simple (court, explicite, pas de majuscules, pas de caractères spéciaux), pour que le contenu soit clair, mais aussi qu’il soit facile à retaper quelque part si nécessaire. Les noms à rallonge sont donc à proscrire. Tâchez aussi d’éviter la multiplication des versions dans le dossier (dont une seule est ok), si vous avez des déchets, mettez dans un sous dossier spécifique (moi je l’appelle rkiv) de façon à garder les vieux morceaux d’essais.

Le .qmd est très simple, l’entête yaml n’a besoin que d’un champ : le titre. L’auteur est aussi utile, mais pas obligatoire. Pas besoin d’ajouter un format (ils sont communs au site et défini dans _quarto.yml), ni d’options spécifiques (définies aussi ailleurs). Eventuellement, on peut ajouter des éléments spécifiques au texte comme le champ date ou keyword ou bibliography.

Notez qu’il n’y pas de section de niveau header 1. Ce n’est pas possible parce qu’il y a un titre et que le titre est considéré comme la section header 1 : une alternative au titre dans le yml est une section de niveau header 1 ou simple #. S’il n’y a pas d’auteur ou d’autre champ, l’ensemble yml peut être omis avec simplement le header 1.

Dernier petit détail, il faut sourcer le fichier rinit.r. Ce fichier définit les options par défaut des chunks et permet d’avoir les bonnes polices de caractère dans la bonne taille pour tous les graphiques. La fonction ofce::init_qmd() simplifie le process et trouve le fichier rinit.r même s’il est bien caché. Il faut le mettre au début et à part pour que ces options s’appliquent aux chunks suivants. Il est toujours possible de modifier le rinit.r de votre projet pour des variables globales, comme la taille de la police de tous les graphiques, et des fonctions disponibles dans chaque .qmd.

Si vos graphiques sont moches, si les polices de caractère sont toutes petites ou trop grandes, avant d’appeler à l’aide, vérifiez 1. que ofce::init_qmd() est bien appelé ; 2. que vous n’avez pas un fig-width ou un fig-heigth quelque part dans le chunk ou dans le yml de votre .qmd.

---
title: Mon texte en qmd
author: Georgette
---
```{r, include=FALSE}
ofce::init_qmd()
```
## section 1
blabla
## section 2
blabla

Gardez vos yml les plus simples possibles, c’est le moyen d’assurer l’homogénéité des documents sur le site.

Quarto.org est une excellente source d’informations et d’aide sur l’écriture en markdown et la variante particulière que nous utilisons ici. La section “Authoring” est à avoir lu au moins une fois.

les règles typographiques

Grace à quarto et un filtre développé par Romain Lesur de l’INSEE, les règles typographiques standards au français sont appliquées automatiquement. Par exemple les guillemets sont mis conformément à la pratique en France «…» à partir du caractère tapé directement (“). Les espaces avant les signes de ponctuation ( : ;) sont remplacés par des demi cadratins et les espaces séparateurs des milliers sont remplacés par des espaces insécables. Pas besoin donc de s’embêter avec ça. Juste, pensez à mettre les espaces avant”:“.

Pour un document en anglais, il suffit de rajouter dans le yml la langue anglaise pour que la typographie correspondante soit appliquée. Les principaux champs (date, auteur, tableau, figure, graphique) sont aussi traduits.

---
title: English Version of the Document
author: William 
lang: en
---

les références croisées

Les références croisées demandent un peu de soin, mais permettent de produire des documents plus riches dans lesquels :

  • La numérotation des tableaux et figures, mais aussi tout autre type de documents (un encadré par ex.) est faite automatiquement. La mise en page est automatisée (avec quelques gains en html), les mots récurrents sont traduits automatiquement.

  • On peut appeler la référence croisée dans le texte. En html, cela créé un lien qui permet de naviguer directement vers la référence croisée.

  • On peut générer des tables des tableaux et des figures.

Le secret d’une référence croisée c’est l’instruction (le tag) #| label: xxx que l’on met en tête d’un chunk. “xxx” est l’id du document. Il définit le type (fig pour un graphique ; tbl pour un tableau ; tip pour un encadré ; eq pour une équation) et après le tiret le nom (sans espace ni tiret) qui sera appelé dans le texte par la séquence @fig-id ou @tbl-id (voir quarto cross references pour plus de détails).

On définit également le titre du graphique qui est donc identifié pour être mis en page, utilisé par ailleurs (par exemple la table des figures) et agrémenté des mots récurrents (par exemple tableau pour un tableau, donc on ne met pas dans le titre tableau ou son numéro). Le titre est déini par le tag #| fig-caption: xxx

le cas des graphiques

Pour un graphique (on ne met pas le numéro du graphique dans le titre, c’est fait automatiquement) :

``` {{r}}
#| label: fig-id
#| fig-cap: Le titre du graphique
#| fig-asp: 0.8
```

Si c’est un graphique produit autrement que par R, la syntaxe standard de markdown fonctionne aussi de cette façon (en changeant image en fonction du contexte !):

![Le titre de l'image](limage.png){#fig-image}

This is illustrated well by @fig-image.

le cas des tableaux

Pour un tableau (on ne met pas le numéro du tableau dans le titre, c’est fait automatiquement) :

``` {{r}}
#| label: tbl-id
#| tbl-cap: Le titre du tableau
```

les encadrés

Pour un encadré, c’est un peu plus compliqué (pour le moment). tip est le hack pour la catégorie, .callout-tip pour le style. Le champ collapse permet de replier l’encadré par défaut et l’option "false" (notez les guillemets et les minuscules) permet de le déplier par défaut. L’encadré sera numéroté et on peut le cross référencer par @tip_id.

::: {#tip-id .callout-tip collapse="true"}
## titre  l'encadré
texte de l'encadré
:::

un cas plus général

On peut être dans le cas où le contenu n’est pas une image ou un tableau (par exemple une composition d’images, un tableau sous forme d’un png). Dans ce cas quarto protestera. C’est dans la documentation de Quarto et cela prend la forme suivante (l’utilisation du tag fig implique une figure, la première ligne est le contenu, la dernière est le titre, les autres lignes sont affichées comme CONTENT) :

::: {#fig-example}

CONTENT

Caption

:::

Par ailleurs, on peut définir d’autres catégories de références croisées si nécessaire, par exemple en distinguant les cartes des figures.

Les tabsets

Les tabsets sont un moyen commode de proposer des options pour un tableau, un graphique sans entrer dans des complications trop grandes d’interactivité.

::: {.panel-tabset}
## tab 1

du code R, du texte ou des images

## tab2

du code R, du texte ou des images
:::

une bibliographie

Il est facile d’insérer une bibliographie. La première chose est d’indiquer un (ou plusieurs) fichier .bib à quarto :

---
title: Mon titre
bibliography: references.bib
---

Le fichier references.bib doit être à la racine du projet et contient dans la syntaxe bibtex les références. Pour entrer une référence, avec RStudio, il y a plusieurs façon de faire.

  1. Dans RStudio, en mode visuel, on fait insérer une citation. Plusieurs sources sont possibles : Zotero, un DOI, une recherche sur Crossref, etc…

  2. Directement en copiant dans le .bib les références (on peut ainsi utiliser la biblio d’un autre document).

Les appels de références sont alors simplement fait en utilisant @angel2021 où angel2021 est l’id de la référence. L’appel de référence, la biblio sera insérée et formattée automatiquement. Les appels de référence peuvent se mettre également en note de bas de page ou dans un tableau en syntaxe markdown.