Documenter et diffuser sans effort

Quarto - Gitlab Pages

Olivier Rué
olivier.rue@inrae.fr

5 février 2026

Introduction

  • Dans nos métiers il est indispensable de documenter/tracer/archiver nos réalisations
  • Pour rendre compte aux autres (biologistes, scientifiques…)
    • Présentations
    • Rapports
    • Site web

  • Pour organiser sa propre activité d’analyse ou de développement

    • Documents computationnels, prise de notes
    • Documents versionnés, facilement retrouvables
    • Travail collaboratif

Une solution assez simple et éprouvée

Quarto pour créer ses documents…

…stockés sur un dépôt Gitlab hébergé par la forge institutionnelle…

…et diffuse-les facilement sur le web !

Quarto

Système de publication scientifique et technique open-source

  • Un outil, plusieurs formats
    • À partir d’une seule source (Markdown) : HTML, PDF, Word, slides ou site web
  • Intégration naturelle avec Git
    • Fichiers texte versionnables, comparables et collaboratifs
  • Polyglotte et interopérable
    • Support natif de R, Python, Bash, Julia…
    • Plusieurs langages peuvent être utilisés dans le même document
  • Standard moderne et pérenne
    • Successeur de R Markdown, soutenu par une large communauté et conçu pour des projets scientifiques durables.

Pas (peu) de limites

  • Gère les citations (bibtex…), les références croisées, la numérotations des tableaux et figures
  • Gère la mise en page (layouts, TOC…)
  • Affichage équations, images, graphiques, émojis… ✔️ ☺️

Pas (peu) de limites

  • Réutilisation de sections via include
  • Création de diagrammes
```{mermaid}
flowchart LR
    A{node 1}-- is -->B(node 2)
    A-- has -->C[node 3]
```

flowchart LR
    A{node 1}-- is -->B(node 2)
    A-- has -->C[node 3]

Exemple 1 - Listing

---
title: "Listing Example"
listing:
  contents:
    - "presentations/*.qmd"
    - "lab-notes/*reports.qmd"

Exemple 1 - Listing

  • Des métadonnées peuvent être associées au listing
---
shorttitle: "Introduction to the R language"
lang: fr
image: "preview.png"
Module: 12
Registration: '<div class="progress"><div aria-valuemax="100" aria-valuemin="0" class="progress-bar" role="progressbar" style="width: 50%;">  50 %  </div></div>'
Duration: 2 days
Requirements: None
Date: March 10-11
---

Exemple 2 - Rapport d’analyse

---
title: "Metabarcoding analysis (16S rRNA marker) with FROGS 5.0.1 in command line"
author:
  - name: Olivier Rué
    email: olivier.rue@inrae.fr
    orcid: 0000-0001-7517-4724
    affiliations:
      - name: Migale bioinformatics facility
        address: Domaine de Vilvert
        city: Jouy-en-Josas
        state: France
date: "2025-05-02"
lang: en
image: preview.png
date-modified: today
categories: [metabarcoding, FROGS, command line]
number-sections: false
license: "CC BY-SA"
resources: 
  - media/affiExplorer.webm
  - media/easy16S.webm
format:
  html:
    dot-format: png
    page-layout: full
editor: 
  markdown: 
    wrap: sentence
execute:
   engine: knitr
---



The purpose of this post is to show you how to analyze 16S metabarcoding datasets (Illumina 16S V3-V4 region) from the command line with **FROGS**  @frogs, @frogsITS **version 5.0.1** on the migale `front` server and how to explore data in a `BIOM` file with **phyloseq**  @phyloseq.

# Introduction

**FROGS**  @frogs, @frogsITS is a tool dedicated to metabarcoding data analysis, available on a Galaxy server and from command line.
**Phyloseq**  @phyloseq is the reference R package for dealing with metabarcoding data.

::: callout-note
The analyses performed in this document have been performed on the Migale cluster `front.migale.inrae.fr` and `rstudio.migale.inrae.fr`.
You can easily reproduce the analyses if you have got an account on our infrastructure.
If you are not familiar with the Migale infrastructure, you can read the [dedicated post](https://tutorials.migale.inra.fr/posts/migale/).
:::

::: callout-warning
This post is intended neither to provide an in-depth analysis of the dataset nor to answer biological questions (refer to <a href="https://documents.migale.inrae.fr/posts/tutorials/chaillou-16s/">our other tutorial</a> instead).
It is rather an illustration of the technical possibilities and various tools offered by the Migale infrastructure for this kind of data.
Please be aware that the parameters of the tools used here are tailored to this particular dataset and should be adapted to your own needs
:::

Exemple 3 - Présentations avec template INRAE

---
title: "Documenter et diffuser sans trop d'efforts"
subtitle: "Quarto / Gitlab Pages"
author:
  - name: "Olivier Rué"
    email: olivier.rue@inrae.fr
    orcid: 0000-0001-7517-4724
    affiliations:
      - name: Migale bioinformatics facility
        address: Domaine de Vilvert
        city: Jouy-en-Josas
        state: France
draft: true
lang: fr
toc: false
date: "2026-02-05"
date-format: long
image: preview.jpg
from: markdown+emoji
format:
  inrae-revealjs:
    header-logo: "migale-logo.png"
    header-logo-link: "https://documents.migale.inrae.fr"
    preview-links: true
    slide-number: true
    self-contained: false
    chalkboard: true
categories: 
  - Quarto
footer: "Wébinaires CATI - Retours d'expériences"
filters: 
  - reveal-header
lightbox: auto
---

Exemple 4 - Dashboards

Documents quarto stockés sur un dépôt Git

  • Traçabilité complète
    • Chaque modification est historisée : qui a fait quoi, quand et pourquoi.
  • Travail collaboratif structuré
    • Plusieurs personnes peuvent travailler en parallèle sans écraser le travail des autres.
  • Retour arrière garanti
    • Une erreur ? On peut revenir instantanément à une version stable.
  • Branches pour expérimenter sans risque
    • Développement, tests et production sont clairement séparés.

Bonus des Gitlab Pages - déployer très facilement

Un fichier de config à écrire

pages:
  script:
    - mkdir .public
    - quarto render
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Fonctionnalités avancées (une autre fois)

  • URL institutionnel après demande DNS
  • Protection des rapports par mot de passe
  • Utilisation d’une image Docker pour ne pas devoir réinstaller tous les paquets nécessaires

Retour d’expérience

  • Les documents Migale sont
    • construits avec Quarto (rapports d’analyse, documentation, FAQ, publications, présentations, plaquettes de formation…)
    • et mis en ligne via les Gitlab Pages
    • tous les membres peuvent contribuer
  • à titre personnel
    • organisation de mes travaux en cours
    • production de métriques (rapports…)

Nous vous proposerons bientôt

  • un dépôt contenant un template pour créer un livre (quarto book) ✔️
    • https://inraebook-b071c8.pages-forge.inrae.fr/intro.html
  • un dépôt contenant un template pour créer une présentation (quarto revealjs) 🔜
  • un dépôt pour la gestion de rapports d’analyse (quarto website) 🔜

Gestion des analyses

  • Préparation de scripts de gestion des projets (création, ajout d’évènements, déploiement…)

N’hésitez pas à me contacter, ainsi que Cédric et Agnès si vous êtes intéressés ou voulez contribuer

  • Pôle développement informatique du CATI BOOM (partager les méthodes pour améliorer la gestion / déploiement / rédaction)

Merci de votre attention