Composer le site avec Quarto dans RStudio

Créer le site dans RStudio et le lier à Git

Pour créer un projet qui va générer un site dans RStudio et qui comprend un lien à Git, cliquer sur File -> New Project… et sélectionner Version control.

puis Git :

Ensuite il faut lier le projet créé dans GitLab avec le projet RStudio en collant l’URL SSH du projet GitLab dans l’espace Repository URL.

Et ne pas oublier de cliquer sur Create Project.

Votre projet Quarto est maintenant lié entre votre instance RStudio et Git. Vous retrouvez alors votre interface RStudio habituelle, avec un petit onglet Git en plus. Dans cet onglet, vous retrouverez les fonctionnalités permettant de :

• “puller” (charger en local) les fichiers déposés sur votre forge
• d’inscrire des commentaires pour documenter vos modifications via l’instruction “commit”, ce qui est obligatoire avant de déposer des fichiers locaux vers une forge
• “pusher” (déposer sur une forge) des fichiers créés ou modifiés en local

Les éléments du site

Le projet est créé et il contient différents fichiers à adapter selon vos besoins :

• _quarto.yml,
  
• index.qmd ,
  
• styles.css pour changer les couleurs du site par exemple.
  Et aussi
• le dossier _site où seront placés les pages (.html) générées par Quarto au fur et à mesure de leurs créations.

_quarto_yml

Ce fichier de type yaml comprend les métadonnées du site et de ses pages comme le titre, et des options comme la mise en page.

Exemple de quarto_yml

Le type du projet ici est site web. On définit ici l’apparence et l’emplacement des pages du site dans la barre de navigation.

La syntaxe est assez simple mais le yaml très sensible à l’intendation.
Il est donc important de respecter les espaces et les retours à la ligne (\). Lors de la compilation, le yaml est le premier élément qui est évalué ; elle sera stoppée quasi instantanément en cas d’erreur.

Si on insère des images dans les documents, il est recommandé d’ajouter dans ce fichier l’option self-contained: true pour que celles-ci soient contenues dans les pages .html.

Structure d’un projet Quarto

• Les projets Quarto sont généralement composés de fichiers .qmd puis de leurs fichiers en sortie aux extensions .html, pdf, etc.
  
• Les images présentes dans les différents documents sont dans un dossier images situé à la racine du projet
  
• Les données permettant la réalisation des traitements et des analyses de données dans un dossier donnees ou data
  
• Les fichiers quarto nécessaires à la mise en forme des fichiers de sortie sont dans des dossiers de type index_files ou connexion_forge_files.

D’autres fichiers :

• .css (mise en forme des documents) ;
• .bib (base bibliographique) ;
• README.md (créé automatiquement sur la forge, à modifier pour présenter le contenu du dépôt) ;
• .gitinore (recense les fichiers à ne pas déposer sur la forge grâce à leurs extensions, comme par exemple les fichiers .Rhistory)
• .gitlab-ci.yml (permet de configurer un pipeline pour gérer différentes étapes telles que l’affichage en ligne d’un fichier ou d’un site, cela se fait via une fonction intégrée CI/CD - pour Continuous Integration and Continuous Delivery/Deployment permettant le déploiement en continu)

sont situés à la racine du projet

index.qmd

C’est ici qu’on paramètre la page d’accueil du site. Les premières lignes du fichier, encadrées par 2 séries de tirets --- correspondent au yml . On peut y ajouter des éléments et options qui seront spécifiques à cette page.

L’autre partie s’écrit avec le markdown, langage pour formater le texte des titres, des listes, insérer des liens, des images…

Exemple de Index

Alimenter les pages

Vous pouvez y créer toutes sortes de documents (rapports, présentations, notes, etc.) sous différents formats (PDF, HTML, docx, etc.).

Il existe de plus en plus de ressources pour réaliser des documents avec Quarto. Pour une introduction vous pouvez lire ce document introductif, ainsi que celui intégrant du code R, tous deux créés par Elodie Baril & Bénédicte Garnier. Pour une introduction à la génération de sites Internet avec Quarto vous pouvez regarder ce document créé par Bénédicte Garnier & Solenne Roux à l’occasion de ce tuto@Mate.

Sinon vous retrouverez tout ce qui concerne l’édition et le formatage d’un document quarto sur le support de Marc Thévenin et sur le guide officiel de Quarto.

Créer un document

Dans le projet via le menu File -> New File -> Quarto Document

Nouveau document

Les premières lignes du fichier, encadrées par 2 séries de tirets ---, correspondent au yml . Par défaut, elles contiennent uniquement le titre du document et son format de sortie (ici .html). Dans notre exemple, nous avons ajouté nos noms et l’affichage de la table des matières (“toc”).

Une recette

Les autres parties du fichier sont écrites avec le markdown , souvent utilisé pour rédiger des documents, des articles ou des pages web.
Il permet de créer des titres, des listes, des liens, des images et d’autres éléments de mise en forme[^1] sans avoir à utiliser de balises HTML complexes.
[^1]: On peut aussi facilement faire des notes de bas de page.

Exemple de mise en forme de titre avec la langage markdown

Le document doit être sauvegardé en lui donnant un nom via File Save As et le fichier portera l’extension .qmd.

Pour générer le document, cliquer sur le bouton Render et la page .html correspondante sera crée dans le dossier public.

Pour publier ce document sur le site, il faut ajouter les noms des 2 fichiers (.qmd et .html) dans le fichier index.qmd dans le paramétrage de la barre de navigation.

Puis utiliser le bouton Render Website de l’Onglet Build de RStudio pour actualiser le site.

Les pages nouvelles ou modifiées sont alors visibles dans l’onglet Git, il faut alors les sélectionner et utiliser les boutons Pull puis Commit et Push pour les déployer sur le site GitLab distant.

Onglet Git

Attention à écrire un message dans la partie Commit message pour documenter les modifications.

Puis on génère le site via la commande quarto render de la console de RStudio ou via le bouton Render Website de l’Onglet Build de RStudio.

Render Website

Petit retour sur la forge

Dans la zone Deploy, Pages, à droite de la page GitLab du projet, on trouve l’adresse du site et en cliquant sur le lien on vérifie que le site a bien été déployé.

Les fichiers sont à la fois dans RStudio et dans le projet GitLab et les pages du site sont générées.

Pour terminer, indiquer l’adresse du site dans le fichier Readme.md du projet.

Créer un diaporama

Via le menu File -> New File -> Quarto Presentation

Nouveau diaporama

Un diaporama

On note ici que le format est différent de celui d’un document (ici revealjs). On a ajouté d’autres élements dans le .yaml : soustitre, affiliations et indiqué un fichier css personnalisé.

Les titres des diapositives sont également précédés de # et on sépare le contenu de chaque diapositive par ---.

Créer le site dans RStudio sans l’héberger sur une forge

Dans RStudio, vous pouvez créer un projet qui va générer un site “local” sur votre machine et que vous pouvez transmettre.

Dans RStudio, via le menu File -> New Project -> New Directory -> Quarto Website

Donner un nom au dossier Directory name qui sera un sous dossier du répertoire contenant le projet R. Puis cliquer sur Create Project.

Exemple de génération de site

Les fichiers constituants le projet sont similaires à l’étape précedente, c’est le dossier _site qui contient les pages .html qu’il faudra transmettre. Pour accéder au site il suffit d’ouvrir le fichier index.html.

Ce dossier qui peut être transmis sous forme de fichier .zip (par exemple) ou déposé plus tard sur une instance GitHub ou GitLab.