Support construction de sites évènements MATE-SHS

Author

Bénédicte Garnier & Solenne Roux

Ce document rassemble des éléments très pratico-pratiques d’aide à la réalisation de sites de présentation d’évènements MATE-SHS réalisés sous Quarto et déployés sur gitlab.

Quarto ?? What is it ?

Quarto est un language informatique permettant l’édition de documents computationnels et de sites web notamment. Ca tombe bien c’est ce qui nous intéresse ici. Il est possible d’utiliser Quarto via différents outils tels que VScode, Jupyter, Rstudio, Neovim et votre éditeur de commande, tel que c’est détaillé ici ou encore là.

Les auteurs de ces lignes étant toutes les 2 familières d’Rstudio, ce sera cet outil qui sera présenté dans ce document.

Merci pour l’info mais mainenant je fais quoi ?

Maintenant vous devez donc installer la dernière version de R sur votre ordinateur. Attention n’installez pas de prerelease versions pour ne pas être embêtés avec ces versions pas totalement finalisées.

Puis une fois R installé, vous devez installer Rstudio.

Et… c’est tout !! Oui Quarto est intégré à Rstudio depuis juillet 2022. Donc vous n’avez rien de plus à faire, si ce n’est ouvrir Rstudio.

Générer un site web dans Quarto

Afin de générer un site web dans Quarto et faire une jolie vitrine aux évènements MATE-SHS, il faudra suivre ce chemin : File -> New Project -> New Directory -> Quarto Website.

Oh magie, la structure de votre site est déjà là. Alors ce n’est qu’un début, mais vous avez déjà la page d’accueil dans le fichier ‘index.qmd’ et une page additionnelle dans le fichier ‘about.qmd’.

Chaque page de votre site sera donc un document .qmd qu’il faudra nommer selon les pages que vous souhaitez créer sur votre site. Pour les sites évènementiels MATE-SHS de type ANF vous aurez généralement besoin des pages suivantes :

  • Accueil (ça vous vous en doutez)
  • Comité d’organisation / intervenants
  • Programme
  • Descriptif des sessions
  • Modalités d’inscription
  • Candidater
  • Informations pratiques
  • Matériel / Installation logiciels

La page ‘about.qmd’ pourra être supprimée ou renommée, car elle ne sera pas utile en l’état.

D’autres fichiers ont également été générés lors de la création de votre projet. On va maintenant s’intéresser au fichier ‘_quarto.yml’. C’est dans ce fichier que nous allons indiquer les principales configurations du site web : le type de projet (website), le répertoire (soit en local au début, soit public pour un déploiement gitlab) et les pages du site avec leurs intitulés complets et les documents .qmd, créés précédemment, correspondants. Ce fichier contient également des informations relatives au format du site : style (css), présence d’une table des matières ou pas, etc.

Voici un exemple de fichier ‘_quarto.yml’

 project:
  type: website
  output-dir: public

website:
  title: "website"
  navbar:
    left:
      - text: " "
        href: index.qmd
      - text: "Comité d'organisation / intervenants"
        href: comite.qmd
      - text: "Programme"
        href: programme.qmd
      - text: "Descriptif des sessions"
        href: sessions.qmd
      - text: "Modalités d'inscription"
        href: info_inscriptions.qmd 
      - text: "Candidater"
        href: candidatures.qmd 
      - text: "Informations pratiques"
        href: infos.qmd
      - text: "Matériel / Installation logiciels"
        href: materiel.qmd 

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

Il y a différentes configurations possibles. On peut par exemple choisir d’afficher le menu à gauche ou à droite, avec ou sans sous-rubriques, avec différents styles, etc.

Pour approfondir le sujet :

Ok maintenant j’ai mon site, mais comment je l’alimente ?

Le site est constitué de plusieurs documents quarto .qmd et s’alimente comme un document quarto classique.

On peut rédiger directement en reprenant les spécificités d’écriture en Quarto (niveau de titre, mise en forme, etc.). On peut également y ajouter du code (R, Python, Observable entre autres) en ajoutant des chunks qui supporteront ces langages. Ceci pourra être très utile pour mettre à disposition les supports de formation à l’issue d’ANF ou d’ET par exemple.

J’ai mon site en local, mais comment je le déploie ?

Création d’un projet sur GitLab

Il faut se connecter sur le gitlab d’Huma-Num et dans notre cas avec le compte Mate-shs.

Une fois connecté, nous allons pouvoir créer un nouveau projet. Pour créer un nouveau projet sans en importer un existant, donc à partir de rien (from scratch) vous devrez sélectionner Blank Project. Il faudra renseigner le nom de votre projet (pas trop complexe, notamment car il sera intégré à l’URL de votre site lorsque celui-ci sera déployé). Puis, il faudra indiquer une visibilité publique pour pouvoir le déployer par la suite. N’oubliez pas d’enregistrer vos modifications.

Vous venez de créer votre projet sur gitlab, maintenant il va falloir relier votre projet local à ce projet en ligne…

Deux solutions s’offrent à vous : le token (jeton d’identification) ou la clef de cryptage SSH (moi j’utilise ça).

Création de jetons d’identifications :

Afin de faire le lien entre votre projet Git vide et votre projet Rstudio vous allez devoir créer des jetons (tokens) d’identification via votre compte Gitlab.

Sur votre compte gitlab il suffit de suivre ce chemin :

Edit profile => Acces Token => add new token.

Ajout du jeton dans Rstudio

Installation du jeton dans Rstudio grâce au package gitcreds

install.packages("gitcreds")
library(gitcreds)

library(gitcreds)
gitcreds_set(url = "https://gitlab.huma-num.fr/mate-shs")

Création d’une clef cryptée SSH

Pour générer une clef dans Rstudio :

Tools -> Global Options -> Git/SVN dans la barre de menu verticale -> Create SSH key: On génère la clé sous la zône d’enregistrement -> View public key: On visualise et récupère la clé SSH en la copiant

Puis maintenant copier la clef dans gitlab :

Cliquer sur votre avatar -> Aller sur preference -> Cliquer sur SSH Keys -> Cliquer sur Add new key -> Coller votre clé générée dans RStudio

  • Ajouter un titre si vous comptez avoir plusieurs clés
  • Modifier la date d’expiration (X si aucune expiration)

-> Cliquer sur Add key

Envoyer le projet Rstudio sur git (et vice/versa)

Onglet Git

Penser à :

  • Pull
  • Commit
  • Push

Ressources

Plein de détails et de subtilités sur la rédaction de documents Quarto :

Des détails sur la liaison du projet Rstudio à Git :