Création d’un site Web Quarto sur Github

1. Introduction

Ce document est basée sur cette série de vidéos Youtube en anglais produite par Joshua French

Les pages Github (https://pages.github.com/) sont une fonctionnalité offerte par Github qui permet d’héberger votre site Web personnel ainsi que vos projets.

L’hébergement s’effectue dans votre dépôt (ou repository), ce qui vous permet de :

  • conserver un dépôt git pour votre site Web
  • pousser (push) des changements dans votre site Web vers Github
  • visualiser presque instantanément les changements de votre site dans Github

Si votre nom d’utilisateur Github est username et que votre site Web est contenu dans le dépôt demositealors le rendu de votre site Web sera disponible à l’adresse https://username.github.io/demosite/.

Si vous créer un site Web personnel, il est préférable de l’héberger à l’adresse https://username.github.io.

2. Création d’un site Web Quarto

  • Dans R Studio,

  1. Depuis le menu File, click -> New Project

  2. Sélectionner New Directory -> Quarto website

  3. Choisir un nom de répertoire

  • s’il s’agit du site web personnel hébergé sur Github il faudra choisir comme nom de répertoire username.github.io, username représentant votre nom d’utilisateur Github. Le résultat sera visible à l’adresse https://username.github.io

  • s’il s’agit d’un site relatif à un projet hébergé sur Github, il faudra choisir comme nom de répertoire name qui représentera le nom de votre projet. Le résultat sera visible à l’adresse https://username.github.io/name/.

Un exemple est donné ici Figure 1

Figure 1: Configuration du projet de site Web Quarto
Note

Ne pas oublier de cocher l’option Create a git repository pour la gestion des versions de votre site. Git aura été préalablement installé depuis https://git-scm.com/downloads

6 fichiers vont être automatiquement créés :

  • _quarto.yaml, qui permet le paramétrage global du site Web
  • .gitignore identifie les fichiers et répertoire à ignorer par git
  • index.qmd est le fichier associé à la page défaut du site Web
  • about.qmd est une page démo associée à la page principale
  • <nom du projet>.Rproj est le fichier projet R associé au site Web
  • styles.css est le nom de la feuille de styles par défaut

Sur le site de Quarto une section est dédiée au paramétrage des Options de site Web

3. Modification du répertoire ‘output’ du site Web

Le répertoire output est le lieu où sont stockés les fichiers de rendu du site. Pour héberger votre site Web Quarto en utilisant la fonctionnalité “Github pages” il est préférable de modifier le répertoire output en “docs” (par défaut le répertoire output a pour valeur “_site”.)

Pour ce faire, il faut :

  • sélectionner le fichier _quarto.yml
  • ajouter la ligne output-dir: docs sous type: website
Figure 2: Modification du répertoire output

4. Création du dépôt Github

  • se loguer dans Github
  • Depuis la page principale, créer un dépôt Github.

    • Pour votre site web personnel, le dépôt devra s’appeler username.github.io. Il faudra bien sûr remplacer usernamepar votre nom d’utilisateur Github et sélectionner l’option Public pour que le site soit visible par tous (cf. Figure 3)

      Pour héberger un projet, le dépôt, si vous décider de l’appeler projet, apparaîtra à l’adresse https://username.github.io/projet (cf. Figure 4).

Figure 3: Configuration pour site web personnel
Figure 4: Configuration pour un site projet

5. Déploiement du site web sur Github

  • sélectionner l’onglet settings relatif au projet et cliquer sur Pages

  • Dans la section Build and deployment sélectionner la branche main et le répertoire /docs dans lequel figurent l’ensemble des fichiers constituant le site web (cf Figure 5)

Figure 5: Configuration de déploiement du site

La ligne “Your site live at https://a-lambda.github.io” permet de vérifier que le rendu du site s’est correctement effectué. Un clic sur le bouton Visit site permet d’apprécier le résultat.