Voici comment rédiger et publier un article sur le site.

Table des matières

Pré-requis

  • Avoir tous les accès nécessaires : demander lors d’une séance de l’association ou au directeur de la publication
  • Installer git et hugo

Ajouter sa clef ssh

Cette étape est facultative mais permet d’utiliser git bien plus souplement.

  1. se connecter à https://gitea.agu3l.org
  2. cliquer sur l’avatar tout en haut à droite pour afficher le menu déroulant
  3. sélectionner Configuration et choisir l’onglet Clefs SSH/GPG
  4. renseigner votre clef ssh (le contenu de ~/.ssh/id_rsa.pub sur votre machine)

Créer un post

  1. cloner le projet du site avec la commande git clone gitea@gitea.agu3l.org:agu3l/site.git site-agu3l, ou si il a déjà été cloné, le mettre à jour avec git pull
  2. aller dans le dossier : cd site-agu3l
  3. créer une nouvelle page : hugo new posts/mon_titre_de_post.md ou hugo new -k 4-lignes posts/Les-4-lignes-vendredi-DATE.md si c’est pour un résumé d’une séance
  4. hugo indique où le fichier a été créé. Éditer ce fichier avec votre éditeur de texte préféré.

Éditer le post

Les posts sont composés d’un en-tête et d’un corps. L’en-tête permet de configurer comment la page doit être affichée et ses différentes options. Le corps est le contenu de la page.

Configurer l’en-tête

L’en-tête est délimité par des lignes ne comportant que trois tirets : — Tout le contenu de l’en-tête est composé de couples clé-valeur. Leur ordre n’est pas important.

Il ne faut rien y ajouter qui ne soit pas détaillé dans la documentation du thème.

Voici un en-tête typique :

---
title: "Rédiger un article"
author: "Hexdump"
date: 2022-03-13T09:11:45+01:00
categories:
- Outils
tags:
- site
- hugo
- git
- ci/cd
keywords:
metaAlignment: center
coverImage: "images/hugo_logo.png"
thumbnailImage: "images/affiche_lol_thumbnail.jpg"
thumbnailImagePosition: left
summary: "Rédiger et publier un article sur Hugo"
---

Il définit un titre, un auteur et une date comme des valeurs simples.

Les propriétés categories et tags sont elles composées d’une liste de valeurs. Cela se représente par une valeur par ligne, préfixée d’un tiret.

La coverImage permet d’indiquer l’image à utiliser en fond pour le titre. Elle peut être vide si aucune image n’est souhaitée. Les propriétés thumbnailImage et thumbnailImagePosition permettent de définir une vignette à afficher dans la liste des posts, et de choisir où afficher la vignette (à droite, à gauche, au-dessus, en-dessous du texte). Si thumbnailImage n’est pas indiqué mais qu’il y a une coverImage, la vignette est automatiquement générée. Les images de couverture ou de vignette doivent se mettre dans le dossier static/ du projet (ici, dans static/images/).

La propriété summary permet d’indiquer le texte à utiliser comme résumé du post dans la liste principale (voir aussi more dans le corps).

Si la propriété draft (brouillon) est à true (vrai), le post ne sera pas affiché dans la version définitive.

Il existe d’autres propriétés disponibles, se reporter à la documentation du thème.

Rédiger le post

Le corps se rédige en markdown, sous l’en-tête. Le site de ionos propose un tuto en français assez bien fait.

En particulier, commencer les lignes par # pour les titres de niveau 1, # pour ceux de niveau 2, etc.

Le mot-clef <!–more–> permet d’indiquer qu’il faut arrêter ici le résumé automatique.

Le tag {{<alert [type]>}}…texte….{{}} permet de générer un encart. Les types disponibles sont info, success, warning, danger, no-icon.

Ajouter des images

Pour ajouter une image :

![Texte alternatif](./my_image.png)

Pensez à toujours mettre un texte altenatif pertinent : les personnes ayant des déficiences visuelles utilisent des lecteurs d’écran qui lisent ces textes et leur permettent de comprendre l’article !

Le chemin relatif est par rapport au fichier contenant le texte de l’article.

Ajouter une table des matières

Pour les longs posts, une table des matières en début d’article est toujours plaisante :

{{< toc >}}

Ajouter des liens

On peut ajouter des liens vers d’autres pages comme cela :

[Titre à afficher]({{<ref "/posts/mon_article/index.md" >}})

Valider le post

  1. compiler et démarrer localement le site pour le tester avec la commande hugo server -D --buildFuture
  2. ouvir l’adresse indiquée (normalement http://localhost:1313/) avec le navigateur
  3. valider que le nouveau post apparait bien et que son rendu est satisfaisant
  4. arrêter le serveur hugo avec CTRL+C

Publier le post

  1. ajouter les nouveaux fichiers avec la commande git add . (noter le point à la fin)
  2. ajouter les modification avec la commande git commit -a -m "mon commentaire". Le commentaire doit décrire ce qui a été modifié. Par exemple : “Ajout du compte-rendu du vendredi 2022-03-11”
  3. pousser les modifications sur le serveur avec la commande git push
  4. au bout d’une ou deux minutes, et si tout est validé, le site est mis à jour automatiquement. Utiliser F5 pour rafraichir la page.

Vérifier le déploiement

Si le site ne se met pas à jour tout seul, c’est peut-être que les fichiers contiennent une erreur. Dans ce cas, la validation automatique empêche le déploiement pour ne pas casser le site. Pour vérifier les logs et comprendre la cause, il faut aller voir dans drone :

  1. se rendre sur https://drone.agu3l.org
  2. il faut être connecté sur gitea pour accéder à drone. Si nécessaire, drone renvoie automatiquement sur la page de connexion de gitea. Il retourne ensuite tout seul sur drone.
  3. dans repositories (dépôts), cliquer sur agu3l/site
  4. dans l’onglet builds (celui ouvert par défaut), cliquer sur le dernier build dans la liste des éxecutions
  5. le pipeline se compose de trois étapes, clone, build et deploy. Identifier celui qui est rouge et cliquer dessus pour voir les logs
  6. corriger le problème
  7. cliquer sur la flèche retour ou sur builds tout en haut de la fenêtre pour retourner à la page des builds
  8. cliquer sur le bouton en haut à droite + new build pour relancer la vérification et le déploiement