8 KiB
| title | summary | tags | author |
|---|---|---|---|
| Publier un billet ou contribuer au site | Les étapes à suivre | Olivier |
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.
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/)
| 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 commit -am "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.