alpinux.presentations/CONTRIBUER.md

Proposer une présentation

Vous présentez un sujet à une réunion d'Alpinux ? Votre diaporama a sa place ici. Il s'écrit dans un simple fichier texte, en Markdown : pas de logiciel de présentation à maîtriser, et le résultat s'affiche dans n'importe quel navigateur.

Vous n'avez jamais utilisé Git ? Ce n'est pas un obstacle : la méthode sans rien installer se fait entièrement depuis le site de la forge. Et si vous bloquez, demandez de l'aide en réunion ou sur la liste de diffusion — quelqu'un mettra votre fichier en ligne avec vous.

---

En bref

1. Copier le dossier slides/_modele sous un nouveau nom.
2. Écrire vos diapos dans slides.md.
3. Prévisualiser sur votre ordinateur.
4. Ouvrir une pull request : un mainteneur relit, fusionne, et le site se met à jour tout seul.

---

1. Copier le modèle

Chaque présentation vit dans son dossier, sous slides/. Le nom du dossier devient l'adresse du diaporama : slides/pdf-signer/ est publié sur presentations.alpinux.org/pdf-signer/.

Choisissez un nom court, en minuscules, sans accent ni espace, avec des tirets : sauvegardes, nextcloud-quotidien, kicad-debuter.

cp -r slides/_modele slides/mon-sujet

Vous obtenez :

slides/mon-sujet/
├── slides.md      votre diaporama
└── images/        vos images (supprimez exemple.svg)

---

2. Écrire

Ouvrez slides/mon-sujet/slides.md dans un éditeur de texte. Le modèle est commenté : il montre une diapo de titre, une liste, du code, un tableau, une image et une diapo de démonstration.

La fiche, en haut du fichier

Le bloc entre les deux lignes --- décrit votre présentation. C'est lui qui alimente la page d'accueil du site.

Champ	Obligatoire	Ce qu'on y met
title	oui	Le titre
description	oui	Une phrase : ce qu'on saura faire en sortant
auteur	oui	Votre nom, ou un pseudonyme
date	oui	La date de la séance, AAAA-MM-JJ — par exemple 2026-10-15
niveau	oui	debutant, intermediaire ou confirme
format	oui	eclair, court ou long
tags	oui	Des mots-clés : [pdf, bureautique]
wiki	non	L'adresse de la fiche du wiki, s'il y en a une
brouillon	non	true tant que le diaporama n'est pas prêt à être publié

Laissez tels quels marp, theme et paginate. Et pensez à retirer brouillon: true quand vous avez fini : le modèle le contient, et une présentation en brouillon n'est pas publiée.

Les diapos

• Trois tirets seuls sur une ligne (---) séparent deux diapos.
• ## Un titre donne le titre de la diapo.
• Un commentaire <!-- … --> est une note d'orateur : invisible à l'écran, affichée dans la vue présentateur.
• <!-- _class: titre --> en tête d'une diapo lui donne la mise en page de titre ; <!-- _class: demo --> annonce une démonstration.

Quelques conseils pour la vidéoprojection

• Peu de texte. Trois à cinq lignes par diapo. Ce que vous direz va dans les notes.
• Pas plus de six ou sept lignes de code par diapo.
• Des tableaux étroits : deux ou trois colonnes.
• Des images à vous, ou sous licence libre, rangées dans images/. Une image chargée depuis un autre site est refusée : le diaporama doit fonctionner sans réseau dans la salle.
• Pas de données personnelles dans les captures d'écran : adresse, nom de machine, courriel.

---

3. Prévisualiser

Il faut Node.js (version 22 ou plus récente). Une seule fois, à la racine du dépôt :

npm ci

Puis, à chaque séance de travail :

npm run dev

Ouvrez http://localhost:8080, cliquez sur votre dossier puis sur slides.md. La page se recharge toute seule à chaque enregistrement du fichier. Ctrl + C dans le terminal arrête l'aperçu.

Dans le diaporama : les flèches pour avancer, F pour le plein écran, P pour la vue présentateur avec vos notes.

Avant de proposer votre travail, lancez le build complet :

npm run build

Il vérifie votre fiche et vos images, et dit précisément ce qui ne va pas :

ÉCHEC du build — 1 erreur(s) dans les sources :
  - slides/mon-sujet/slides.md : « niveau » invalide : « expert » — attendu debutant | intermediaire | confirme

Le site complet est alors dans public/ : ouvrez public/index.html pour voir votre présentation dans la liste. Si elle n'y est pas, c'est qu'il reste brouillon: true.

Vous utilisez VS Code ou VSCodium ? L'extension Marp for VS Code affiche l'aperçu à côté du texte. Indiquez-lui le thème dans les réglages (markdown.marp.themes : ./theme/alpinux.css).

---

4. Ouvrir une pull request

Une pull request est une proposition de modification : vous ne touchez pas directement au site, un mainteneur relit d'abord.

1. Créez un compte sur https://gitea.alpinux.org si vous n'en avez pas.

2. Sur la page du dépôt alpinux.presentations, cliquez sur Bifurcation (Fork) : vous obtenez votre copie du dépôt.

3. Récupérez-la, et créez une branche pour votre présentation :

   git clone https://gitea.alpinux.org/VOTRE-COMPTE/alpinux.presentations.git
   cd alpinux.presentations
   git switch -c mon-sujet
   

4. Faites votre travail (étapes 1 à 3), puis enregistrez-le et envoyez-le :

   git add slides/mon-sujet
   git commit -m "Ajouter la présentation « Mon sujet »"
   git push origin mon-sujet
   

5. Retournez sur la forge : un bandeau propose Nouvelle demande d'ajout. Validez, en visant la branche main du dépôt d'Alpinux.

Un mainteneur relit, vous répond dans la pull request si quelque chose est à reprendre, puis fusionne. Le site est à jour dans la minute qui suit.

Le guide Git chez Alpinux du wiki détaille chacune de ces étapes.

La méthode sans rien installer

Tout peut se faire depuis le navigateur, sur https://gitea.alpinux.org :

1. Faites une bifurcation du dépôt.
2. Dans votre copie, ouvrez slides/_modele/slides.md, copiez son contenu.
3. Ajouter un fichier → Nouveau fichier, nommez-le slides/mon-sujet/slides.md (taper les / crée les dossiers), collez, adaptez.
4. Pour les images : Ajouter un fichier → Téléverser, dans slides/mon-sujet/images/.
5. En bas de la page, choisissez « Créer une nouvelle branche », puis ouvrez la demande d'ajout.

Vous n'aurez pas d'aperçu : dites-le dans la pull request, un mainteneur vérifiera le rendu pour vous.

---

Corriger une présentation existante

Une faute, un lien mort, une commande qui a changé ? Même chemin : modifiez le slides.md concerné et ouvrez une pull request. Sur la forge, le crayon en haut du fichier suffit pour une petite correction.