Prérequis

Télécharger les logiciels

Afin de pouvoir travailler correctement, vous allez avoir besoin d’une petite liste de logiciel :

• Hugo : l’outil de génération de site statique. Il permet d’obtenir des pages web navigable à partir des articles markdown.
• Git : l’outil de gestion de version. Il permet le travail collaboratif, nous permettant de travailler de manière asynchrone sur les contenus.
• Un éditeur de texte au choix. Voici quelques suggestions :
  • Ghostwriter : Un éditeur spécialisé dans la rédaction markdown, avec un rendu immédiat et quelques outils de syntaxe.
  • VSCodium : Base libre de VSCode de microsoft, un éditeur populaire chez les développeurs et très extensible pour couvrir tout les besoins.
  • Neovim : Réécriture de vim, un éditeur plus difficile à apprendre mais permettant des manipulations très efficaces, il est également très extensible. De plus, vi(m) est un éditeur présent sur la plupart des distributions linux par défaut.
• Un navigateur internet au choix. Il permet d’accéder au portail collaboratif et de tester son travail.
  • Firefox : Le navigateur libre de l’association Mozilla, acteur majeur dans la libération du web.
  • Chromium : Navigateur libre, base de Chrome, le navigateur de Google et leader du marché.

Tous ces logiciels peuvent être trouvés dans le gestionnaire de paquet de votre distribution Linux, leur installation ne devrait donc pas poser de problème.

Obtenir un compte sur le portail de l’association

Pour pouvoir soumettre vos modifications à publication, vous allez avoir besoin d’un compte sur le portail collaboratif de l’association. L’inscription n’est pas automatique et est réservée aux adhérents de l’association.

Pour obtenir votre compte, veuillez me faire la demande lors d’une rencontre de l’axul, ou bien par courriel auprès de contact(at)axul.org avec le nom d’utilisateur que vous souhaitez utiliser et l’adresse e-mail lié au compte.

Une fois que j’aurais créé votre compte, je vous renverrai un mail contenant la confirmation de création du compte avec un mot de passe généré. Lors de votre première connexion, il vous sera demandé de changer ce mot de passe pour y entrer le vôtre.

Configurer les logiciels

Vous aurez besoin de configurer Git pour signer vos modifications.

git config --global user.name "Votre nom"
git config --global user.email "votre.email@example.com"

Et également pour le support des fichiers volumineux

git lfs install

Ensuite, si vous utilisez un éditeur de texte extensible, je vous conseille de télécharger une extension Markdown, et éventuellement une extension HTML/CSS/JS si vous avez prévu de travailler sur le theme du site.

Récupérer le dépôt

Connectez-vous au portail de collaboration et rendez-vous sur le dépôt officiel du site.
Cliquez sur le bouton “bifurquer” (fork) pour obtenir votre propre dépôt.

Vous pourrez ensuite récupérer l’URL de votre dépôt dans votre presse-papier.

Vous pouvez maintenant ouvrir un terminal dans le dossier dans lequel vous voulez récupérer les sources.
Avec la commande (en remplaçant bien sûr l’URL par celle acquise plus tôt)

git clone --recurse-submodules https://git.axul.org/votrenom/axul-site.git

vous devriez pouvoir télécharger les sources du site.

Maintenant que les sources sont récupérées, on va configurer le dépôt pour garder un lien vers les sources officielles, cela nous permettra de rester à jour par rapport à celles-ci.

git remote add upstream https://git.axul.org/AXUL/axul-site.git

Voilà, notre environnement de travail est fin prêt ! Nous ne devrions plus avoir à refaire ces étapes tant que nous ne changeons pas de poste de travail.

Mettre à jour son dépôt

Avant de se lancer dans des modifications, il est préférable de se synchroniser avec l’état actuel du site. Pour cela on va faire une fois de plus appel à Git.

git pull -r upstream main
git push --force-with-lease

Ajouter son article

Créer le fichier d’article

On va demander à Hugo de générer la nouvelle entrée avec la commande suivante

hugo new content content/blog/monarticle.md

Si votre version de Hugo ne permet pas cette commande car trop ancienne, vous pouvez copier le fichier archetype

cp achetypes/blog.md content/blog/monarticle.md

Modifier les métadonnées

Vous pouvez maintenant ouvrir votre fichier avec l’éditeur de texte. Vous remarquerez qu’il contient déjà quelque chose.
Il s’agit des métadonnées. Ce sont des informations qui permettent de trier et retrouver votre article sur le site.

Veuillez remplir les informations. Pensez à vous créditer en tant qu’auteur.
Attention à la date, si vous n’avez pas pu la générer à l’aide de Hugo, allez voir dans les autres fichiers voisins comment l’écrire, car elle suit un format précis.

Rédiger le corps de l’article

Vous pouvez à présent laisser libre cours à votre plume. Écrivez votre article sous les métadonnées (donc sous la séparation ---).

La rédaction se fait en Markdown, un format de balisage léger pouvant se lire comme du texte brute.

# Un titre

## Un sous-titre

### Un petit titre

Un paragraphe

 - une
 - liste
 - à
 - bulle

Une ligne et un  
retour à la ligne avec un mot en **gras** et un en _italique_

> Une citation

[Un lien vers l'axul](https://axul.org/)

![Texte alternatif d'une image](img/monimage.jpeg)

| Un tableau  | à trois | colonnes |
|-------------|---------|----------|
| avec entête |         |          |
| et trois    |         |          |
| lignes      |         |          |

N’hésitez pas à rechercher sur internet pour les précisions, le Markdown est un format très répandu.

Tester son travail

Une fois que vous avez fini de rédiger votre article, vous pouvez voir un aperçu du rendu du site. Pour cela, entrez la commande :

hugo server --config hugo.toml

Elle va rendre disponible sur un serveur local les fichiers générés. Vous pourrez ainsi ouvrir votre navigateur et accéder à l’adresse http://localhost:1313/ pour avoir un aperçu de votre version modifiée du site.

Confirmer ses modifications

Une fois que vous êtes satisfait de votre travail, vous pouvez le sauvegarder dans votre dépôt.
(Vous n’êtes d’ailleurs pas obligé d’attendre d’avoir complètement terminé pour exécuter ces commandes, vous pouvez vous en servir pour sauvegarder par étape si votre rédaction vous prend beaucoup de temps)

git add content/blog/monarticle.md
git commit -m "message résumé"
git push

Demander la publication

Lorsque votre travail de rédaction est finalement terminé et sauvegardé dans votre dépôt, vous pouvez demander la publication sur le site officiel.

Pour cela, reconnectez vous sur le portail collaboratif de l’axul, rendez vous sur votre dépôt et cliquez sur le bouton “Nouvelle demande d’ajout”.

Veillez à indiquer que vous souhaitez fusionner votre dépôt dans celui de l’axul.
Vous arriverez alors sur une page dans laquelle vous pouvez justifier et commenter votre modification.

Validez et c’est fait !
À partir de là ce sera mon travail de relire, vous poser des questions si nécessaire, puis intégrer le nouveau contenu pour enfin le déployer sur le serveur officiel.

Merci pour votre contribution ! J’espère que ce guide vous a aidé dans les démarches, sinon n’hésitez pas à m’interpeller lors d’un rendez-vous de l’axul.