Intro à Quarto et au déploiement d’un blog

Hackathon inter-CATI, Aussois
GitLab
R
Quarto
CI/CD
Author

Cédric Midoux

Published

December 8, 2022

Quarto

Quatro est une amélioration de rmarkdown. On peut facilement porter les rmd mais également des documents python. Voici comment mettre en place un website Quarto, déployé sur GitLab, avec freeze des calculs ou non.

  1. Créer un blog quarto avec git, knitr et renv : New project > Quarto Blog (ou website, blog, …).

  2. L’architecture est la suivante :

    File Description
    _quarto.yml Quarto project file.
    index.qmd Blog home page.
    about.qmd Blog about page.
    posts/ Directory containing posts
    posts/_metadata.yml Shared options for posts
    renv/ renv directory
    renv.lock renv lockfile
    styles.css Custom CSS for website

  3. Le dépôt utilise renv pour installer et versionner les versions des packages.

    1. Call renv::init() to initialize a new project-local environment with a private R library,
    2. Work in the project as normal, installing and removing new R packages as they are needed in the project,
    3. Call renv::snapshot() to save the state of the project library to the lockfile (called renv.lock),
    4. Continue working on your project, installing and updating R packages as needed.
    5. Call renv::snapshot() again to save the state of your project library if your attempts to update R packages were successful, or call renv::restore() to revert to the previous state as encoded in the lockfile if your attempts to update packages introduced some new problems.

    • Pas de soucis pour installer un package BioConductor. Pour un package GitHub utiliser :

      renv::install('mahendra-mariadassou/phyloseq-extended@dev')

  4. Ajouter le dépôt distant

    usethis::use_git()
usethis::use_git_remote(name = "origin", url = "git@forgemia.inra.fr:cedric.midoux/quartoblog.git")
    git push --set-upstream origin main

  5. Définir l’output-dir dans _quarto.yml:

    project:
  type: website
  output-dir: public

  6. Exclure les fichiers temporaire et les pages html du dépôts

    usethis::use_git_ignore(c("/.quarto/", "public/"))

  7. Générer le site avec l’onglet Build.

    quarto::quarto_render()

  8. Les résultats des calculs sont stockés dans le dossier _freeze/. Ce dossier peut être versionné ou non suivant les besoins (voir Doc).

  9. Les posts sont rédiger dans le dossier le dossier posts/ avec un sous-dossier par post et un fichier index.qmd dont l’entête est décrite dans la doc :

    ---
title: "Post With Code"
description: "Post description"
author: "Fizz McPhee"
date: "5/22/2021"
categories:
  - news
  - code
  - analysis
draft: false
---

  10. Les paramètres par défaut pour l’ensemble des posts sont spécifiés dans posts/_metadata.yml.

    # options specified here will apply to all posts in this folder

# freeze computational output
# (see https://quarto.org/docs/projects/code-execution.html#freeze)
freeze: auto

# Enable banner style title blocks
title-block-banner: true

    Je recommande freeze: auto.

  11. Configurer un pipeline CI/CD .gitlab-ci.yml.

    # The Docker image that will be used to build your app
image: rocker/verse:4.2

# Functions that should be executed before the build script is run
before_script:
  - R -e "renv::restore()"

pages:
  script:
    - quarto render
  artifacts:
    paths:
      # The folder that contains the files to be exposed at the Page URL
      - public
  rules:
    # This ensures that only pushes to the default branch will trigger
    # a pages deploy
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

    Si il n’y a aucun code a exécuter, inutile d’utiliser renv.

  12. On peut suivre l’avancé des taches dans l’onglet jobs et le site est disponible https://<user>.pages.mia.inra.fr/<repo>/.

  13. Le site est généré et déployé à chaque commit sur la branche main. Si il y a des résultats disponibles dans le dossier freeze ils sont utilisés.

  14. Pour rendre un post privé, il suffi d’ajouter draft: true dans le header.

    ---
title: "Penguins"
description: "Penguins description"
author: "Midoux"
date: "2022-12-09"
categories: [penguins, code, analysis]
image: "https://allisonhorst.github.io/palmerpenguins/logo.png"
draft: true
---

    On peut également utiliser des listes.

  15. Il existe de multiples paramètres pour les blocs de codes et autres. Parmi les intéressants identifié, le repliement du code. Pour le reste voir la doc complète.

    ```{r}
#| label: penguins
#| code-fold: true
```

  16. A tester :