Comment contribuer à Chroma ?

Ce guide a pour vocation de vous accompagner pas à pas dans le processus de contribution à Chroma. Que ce soit en proposant des idées, en identifiant des problèmes ou en rédigeant vos propres pages, il y a toujours un moyen de donner un coup de main !

Donner un retour : questions, suggestions#

La première manière de contribuer à l’amélioration du site est de partager vos retours et vos propositions d’améliorations. Pour ce faire, deux voies s’offrent à vous :

• Sur Discord : Le canal 🔍 Review and Feedback vous permet de poser vos questions, discuter avec les autres collaborateurs et proposer vos idées pour améliorer le site.
• Sur GitHub : Si vous constatez un bug, n’hésitez pas à créer une issue sur le repository de Chroma.

Contribuer au développement de Chroma#

Si votre objectif de contribution est de rédiger un nouveau tutoriel, réécrire une partie d’un tutoriel déjà existant, ou encore plonger dans le code source du site pour aider à son amélioration, il est possible de configurer un environnement de développement sur son ordinateur en local.

Prérequis#

• Node.js — version 20.11 ou supérieure (LTS).
• Hugo — version 0.143.1.
• Hugo extended — version 0.143.1.
• Un IDE comme Visual Studio Code.
• Savoir utiliser GitHub (forks, issues, pull requests) — un tutoriel est disponible sur le site.

Mise en place de l’environnement de développement#

Tout d’abord, créez une fork du repository de Chroma. Clonez ensuite votre fork sur votre machine avec git clone. Dans un terminal au sein du répertoire du projet, exécutez la commande suivante pour installer les dépendances nécessaires :

npm install

Vous aurez ainsi accès à un serveur de développement qui vous permettra de prévisualiser le site. Toujours au sein du répertoire du projet, exécutez la commande ci-dessous pour démarrer le serveur de développement en local :

npm run dev

Si tout s’est bien passé, cela va afficher un message dans votre terminal avec le lien cliquable vers votre site local (à une adresse localhost) :

Watching for changes in /.../chroma/{assets,content,i18n,layouts,node_modules,package.json,static}
Watching for config changes in /.../chroma/config/_default, /home/mowibox/Documents/WorkspaceU/Git_folders/chroma/config/_default/menus
Start building sites … 
hugo v0.143.1-0270364a347b2ece97e0321782b21904db515ecc+extended linux/amd64 BuildDate=2025-02-04T08:57:38Z VendorInfo=gohugoio


                   | EN  | FR
-------------------+-----+------
  Pages            |  69 |  68
  Paginator pages  |   0 |   0
  Non-page files   |   2 |   2
  Static files     | 253 | 253
  Processed images |   4 |   0
  Aliases          |  13 |  12
  Cleaned          |   0 |   0

Built in 1638 ms
Environment: "development"
Serving pages from disk
Web Server is available at http://localhost:1313/chroma/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Cliquez sur ce lien pour parcourir le site sur votre navigateur. Tant que le serveur sera actif, chaque modification sauvegardée sera mise à jour automatiquement sur la prévisualisation du site.

npx shx rm -rf public resources hugo_stats.json .hugo_build.lock

Structure du site#

Les différents dossiers et fichiers de Chroma sont organisés de la manière suivante :

.
├── assets/
├── config/
│   └──_default/
│      ├── hugo.toml
│      ├── menus.toml
│      ├── module.toml
│      └── params.toml
├── content/
│   ├── en/
│   └── fr/
|       ├── blog/
|       ├── computer_vision/
|       └── tutorials/
├── i18n/
├── layouts/
└── static/
    ├── gifs/
    ├── icons/
    └── images/

• assets/ regroupe les ressources sources (SCSS, JavaScript, style, etc.) utilisées pour le site.
• config/ regroupe les fichiers de configuration et paramètres généraux du site.
• content/ contient l’ensemble des pages du site, organisées par langue (fr/ et en/).
• i18n/ contient les fichiers de traduction.
• static/ contient les fichiers statiques du site (images, gifs, icônes, etc.).

De manière générale, c’est le dossier tutorials/ qui vous intéressera, lui-même contenant quatre dossiers en fonction du thème du tutoriel : Informatique (computer_science/), Électronique (electronics/), Conception & développement 3D (design_3d_development/), et Autres (miscellaneous/). Mais il n’est pas exclu que votre contribution puisse concerner d’autres parties du site, par exemple s’il y a des issues connues.

Écrire un tutoriel#

La section suivante détaille les différentes étapes pour créer et mettre en forme un nouveau tutoriel :

Extensions Visual Studio Code utiles pour le développement du site#

Si vous utilisez VSCode, voici une liste non-exhaustive d’extensions qui peuvent vous aider à bien mettre en forme vos fichiers :

• HTML CSS Support
• Hugo Language and Syntax Support
• Markdown All in One
• markdownlint

Ajout du tutoriel dans les dossiers#

Pour créer un tutoriel, vous devez créer un dossier contenant un fichier index.md. Identifiez d’abord le thème de votre tutoriel afin de le mettre dans le bon dossier (Informatique, Électronique, etc.). Pour faciliter la visibilité et la structure du site, deux points sont à respecter lors du nommage :

• Le nom du dossier doit être en anglais. Cela facilite la gestion de l’internationalisation fr/en.
• Le nom du dossier ne doit pas être trop long.

La commande hugo new content content/<chemin_du_dossier>/index.md vous permet de créer directement la page en spécifiant son chemin d’accès.

Exemple : Le tutoriel “Initiation à la programmation embarquée” est un tutoriel en français d’électronique. Le dossier introduction_to_embedded_prog/ et son fichier index.md ont été créés dans le dossier content/fr/tutorials/electronics/ avec la commande :

hugo new content content/fr/tutorials/electronics/introduction_to_embedded_prog/index.md

Le lien internet sera alors de la forme suivante : https://mowibox.github.io/chroma/fr/tutorials/electronics/initiation-à-la-programmation-embarquée/

.
└── fr/
    ├── blog/
    ├── computer_vision/
    └── tutorials/
        ├── computer_science/
        ├── design_3d_development/
        └── electronics/
            └── introduction_to_embedded_prog/
                └── index.md

Avant-propos#

Chaque page de tutoriel commence par un avant-propos (aussi appelé front-matter), encadré par des tirets ---. Les différents champs sont détaillés ci-dessous :

---
title: ""
description: ""
summary: ""
date:
lastmod:
draft: false
weight:
toc: true
icon: ""

seo:
   title: ""
   description: ""
   canonical: ""
   noindex: false
   robots: "index, follow"

---

• title : C’est le titre de votre tutoriel. Je pense que c’est assez explicite, non ?

• description : Décrit votre contenu en une courte phrase. Utilisée notamment pour l’aperçu dans la liste des tutoriels.

• summary : Décrit votre tutoriel avec un peu plus de détail, en 2-3 phrases.

• date : La date à laquelle vous avez commencé à écrire votre tutoriel, au format YYYY-MM-JJ.

• lastmod : La date de dernière modification du tutoriel, au format YYYY-MM-JJ.

• draft : Rend le tutoriel visible ou non lors de la prévisualisation. Par défaut, il est visible (false).

• weight : Définit l’ordre d’affichage de votre contenu dans la liste des tutoriels. La manière de le remplir est détaillée dans la section suivante.

• toc : Affiche la table des matières de la page. Par défaut, elle est affichée (true).

• icon : Vous pouvez rajouter une nouvelle icône en allant dans Tabler Icons. Il s’agira de l’icône qui illustrera votre page dans la liste des tutoriels

  Attention

  Attention, il faut que la couleur de l’icône soit #a514e9 et doit être ajoutée dans le dossier static/icons.

• seo.title : Titre optimisé pour les moteurs de recherche. Il peut être différent de title.

• seo.description : Description affichée dans les résultats de moteur de recherche.

• seo.canonical : URL canonique de la page

• seo.noindex : Gère l’indexation de la page par les moteurs de recherche. Activé par défaut (false).

• seo.robots : Indique aux moteurs de recherche comment indexer la page.

Exemple d'aperçu de tutoriel dans la liste. Les champs title, description et icon, sont sollicités.

Convention des poids de page#

L’ordre des tutoriels est défini dans l’avant-propos grâce au champ weight. Pour le moment, cette valeur est gérée manuellement (par moi-même). Vous pouvez soit laisser le champ vide, soit lancer le site en local, repérer les tutoriels situés à l’endroit où vous souhaitez ajouter le vôtre, puis adapter les poids des pages environnantes.

Mise en forme du contenu#

La rédaction de contenu se fait principalement avec le langage Markdown, qui a l’avantage d’être assez facile à prendre en main, c’est d’ailleurs le langage utilisé pour les fichiers README sur GitHub.

Pour aller plus loin et exploiter toutes les fonctionnalités du site, la documentation de Doks (en anglais) propose des guides détaillés sur la création de contenu :

• La section Authoring content vous permet d’apprendre les bases : structurer votre texte, gérer les titres, paragraphes, listes etc.
• Pour insérer du contenu dynamique comme des notes, astuces, boutons ou autres spécificités, utilisez les shortcodes.
• Pour écrire du code, vous pouvez vous référer à la section Code blocks.
• Si votre tutoriel a besoin de rédaction mathématique, un support LaTeX est disponible dans la section Math.
• Vous pouvez créer des diagrammes et des schémas avec la section Diagrams.

N’hésitez pas à combiner les fonctionnalités de Markdown et des shortcodes Doks pour créer un tutoriel à votre image. Et en parlant d’image, voilà la section qui en parle !

Ajout d’images#

L’ensemble des images du site dédiées aux pages sont stockées dans le dossier static/images/. Pour intégrer une image du dossier dans votre page, adaptez le bloc HTML suivant à votre besoin :

<p align="center">
    <img src="/chroma/images/image1.jpg" alt="Image 1 short description" class="w-full h-auto" />
</p>

Où image1.jpg est le nom de l’image. Si vous voulez rajouter une nouvelle image, il suffit donc de rajouter l’image en question dans le dossier static/images/ pour qu’elle soit utilisable. Comme pour le reste du site, certains points sont à respecter lors de l’ajout d’images :

• L’image ne doit pas dépasser 2 MB.
• L’image utilisée doit être libre de droit.
• Il est préférable de nommer l’image en lien avec le tutoriel que vous écrivez. Par exemple, les images de ce tutoriel sont nommées contribute1.jpg, contribute2.png, etc. Cela permet de retrouver plus facilement dans quel tutoriel l’image est utilisée.
• Si certaines images peuvent être utilisées dans plusieurs tutoriels, vous pouvez leur donner un nom plus générique, tout en ajoutant un tiret du bas (_) au début pour les distinguer (ex : _buzzer.jpg).
• Le champ alt doit contenir une très courte description du contenu de l’image en anglais.

Il est aussi possible d’ajouter une légende à votre image en utilisant le bloc HTML ci-dessous :

<p align="center">
    <img src="/chroma/images/image2.jpg" alt="Image with caption" class="w-full h-auto" />
    </br>
    <em style="font-size: 0.95em;">Une image avec une légende.</em>
</p>

Une image avec une légende.

Crédits de fin de page#

À la fin de chaque page du site (comme celle-ci), il faut ajouter une section consacrée aux crédits de la page, voici le format :

---

## Crédits

* **Rédacteur :**
* **Relecteur :**

Tout d’abord, remarquez qu’il y a une ligne séparatrice (---) permettant de scinder le tutoriel et les crédits. Il y a ensuite les différents champs qui sont à compléter :

• Rédacteur : C’est vous ! Il peut il y avoir plusieurs auteurs, séparés par des virgules.
• Relecteur : Ce sont les personnes qui ont relu votre tutoriel et vous ont proposé des suggestions. Inutile de vous indiquer comme tel si vous êtes rédacteur. Si vous n’avez pas de relecteurs, le champ peut être laissé vide, mais il doit être présent dans tous les cas.

Demande de relecture des changements#

Satisfait de votre tutoriel ? Il ne vous reste plus qu’à réaliser une pull request afin qu’un collaborateur puisse vérifier le tutoriel ! Le titre de la pull request doit être explicite, par exemple :

• “Ajout du tutoriel “Initiation à Python” - FR”
• “Suggestion de correction dans le tutoriel “Using the terminal” - EN”
• “Amélioration de l’interface de visualisation des tutoriels”
• etc.

La description de la pull request doit expliquer brièvement les modifications apportées ou les ajouts par cette dernière. Une fois la pull request envoyée, un contributeur viendra vérifier que tous les points expliqués dans cette page sont vérifiés. Dans le cas contraire, vous recevrez un message vous expliquant ce qu’il faut modifier pour que votre pull request soit acceptée. Si tout est correct, les modifications seront directement intégrées au site principal.

Bravo et merci !

Crédits#

• Rédacteur : Ousmane THIONGANE
• Relecteur :