alpinux.presentations/README.md

Présentations d'Alpinux

Les diaporamas des réunions d'Alpinux, le groupe d'utilisateurs de logiciels libres de Savoie — publiés sur https://presentations.alpinux.org et projetés depuis ce site le soir de la réunion.

Chaque présentation est un fichier Markdown. Marp en fait un diaporama HTML autonome, et le build génère la page d'accueil qui les liste toutes.

Vous voulez proposer une présentation ? Tout est dans CONTRIBUER.md.

---

Je veux…

Ce que vous voulez faire	Ce que vous faites
Proposer une présentation	Suivre CONTRIBUER.md
Voir mes diapos pendant que j'écris	npm run dev, puis http://localhost:8080
Vérifier que tout est bon avant de pousser	npm run build
Obtenir un PDF d'un diaporama	npm run pdf -- pdf-signer
Mettre en ligne	Fusionner sur main — le déploiement suit, en une minute
Comprendre pourquoi ce n'est pas en ligne	tail -30 /var/log/presentations-deploy.log sur le serveur
Installer ou réparer le déploiement	Lire deploy/webhook.md

---

Installation

Il faut Node.js 24 LTS — c'est la version du serveur, indiquée dans .nvmrc. La 22 LTS convient aussi. Rien d'autre : ni Python, ni navigateur pour le build.

git clone git@gitea.alpinux.org:alpinux.cedrica5l/alpinux.presentations.git
cd alpinux.presentations
npm ci

Deux dépendances, aux versions figées dans package.json et package-lock.json :

• @marp-team/marp-cli — convertit le Markdown en diaporama ;
• js-yaml — lit la fiche de chaque présentation. Marp l'embarque déjà : elle n'ajoute rien à l'installation.

---

Commandes

npm run dev — aperçu local

Sert slides/ sur http://localhost:8080 avec le thème commun, et recharge la page à chaque enregistrement. Les brouillons et le modèle y sont visibles.

npm run build — build complet

npm run build                # vers public/
npm run build -- /un/chemin  # vers un autre répertoire

1. Parcourt slides/*/slides.md, en ignorant les dossiers qui commencent par _ et les présentations marquées brouillon: true.
2. Valide la fiche de chacune.
3. Génère <sortie>/<identifiant>/index.html et copie son dossier images/.
4. Génère <sortie>/index.html, la page d'accueil.
5. Génère <sortie>/presentations.json et <sortie>/.htaccess.

Le build est strict, comme mkdocs build --strict pour le wiki. Il échoue, avec un message qui nomme le fichier et le défaut, sur :

• un champ obligatoire manquant, une valeur invalide, un champ inconnu (une faute de frappe sur brouillon publierait sinon un diaporama inachevé) ;
• une image introuvable, ou rangée ailleurs que dans images/ ;
• une ressource chargée depuis un autre site — image, police, script, feuille de style.

En cas d'échec, le répertoire de sortie n'est pas touché : tout est construit à part, puis mis en place d'un seul coup.

npm run pdf -- <identifiant> — export PDF

npm run pdf -- pdf-signer    # écrit public/pdf-signer/pdf-signer.pdf

À lancer sur un poste de travail : Marp pilote un navigateur installé (Chromium, Chrome ou Firefox) pour imprimer le diaporama, et le serveur n'en a pas. Le PDF n'est ni versionné ni publié par le déploiement.

---

Organisation du dépôt

alpinux.presentations/
├── README.md
├── CONTRIBUER.md              le guide du contributeur
├── package.json               dépendances, versions figées
├── theme/alpinux.css          le thème Marp commun
├── slides/
│   ├── _modele/               le modèle à copier — jamais publié
│   └── pdf-signer/
│       ├── slides.md          le diaporama
│       └── images/            ses images
├── scripts/
│   ├── build.mjs              le build
│   └── deploy-presentations.sh    ce que le serveur exécute après un push
├── deploy/                    la chaîne de déploiement, versionnée avec le site
│   ├── webhook.md                 mise en place côté serveur
│   ├── installer.sh               pose tout sur le serveur (root)
│   ├── webhook.py                 service d'écoute, 127.0.0.1:9878
│   ├── presentations-webhook.service
│   └── apache-vhost.exemple.conf
└── public/                    sortie locale du build, ignorée par git

---

La fiche d'une présentation

Chaque slides.md commence par un front matter : les réglages de Marp, puis la fiche.

---
marp: true
theme: alpinux
paginate: true

title: Lire, remplir et signer ses PDF
description: Remplir, signer, assembler et alléger un dossier PDF sous Linux Mint.
auteur: Alpinux
date: 2026-10-15            # date de la séance
niveau: debutant            # debutant | intermediaire | confirme
format: court               # eclair | court | long
tags: [pdf, bureautique]
wiki: https://wiki.alpinux.org/…    # facultatif
brouillon: true                      # facultatif : exclut de la publication
---

---

Le thème

theme/alpinux.css est pensé pour la vidéoprojection : gros corps de texte, fort contraste, logo et numéro de page en pied de diapo. Les polices sont celles du système ; rien n'est téléchargé.

Deux classes, à poser sur une diapo avec <!-- _class: nom --> :

Classe	Usage
titre	La diapo d'ouverture, les intercalaires, la diapo de fin
demo	L'annonce d'une démonstration en direct

Les citations (> …) servent d'encadrés « à retenir » ou « piège », et <kbd> dessine une touche de clavier.

---

Ce que le build publie pour alpinux.org

presentations.json, à la racine du site, liste toutes les présentations publiées, de la plus récente à la plus ancienne :

{
  "genere": "2026-10-10T19:39:31.061Z",
  "site": "https://presentations.alpinux.org/",
  "presentations": [
    {
      "id": "pdf-signer",
      "titre": "Lire, remplir et signer ses PDF",
      "description": "…",
      "auteur": "Alpinux",
      "date": "2026-10-15",
      "niveau": "debutant",
      "format": "court",
      "tags": ["pdf", "bureautique"],
      "url": "https://presentations.alpinux.org/pdf-signer/",
      "wiki": null
    }
  ]
}

Le .htaccess généré pose Access-Control-Allow-Origin sur ce seul fichier, pour qu'alpinux.org puisse le lire depuis le navigateur du visiteur — comme le wiki le fait avec derniers-articles.json.

---

Vie privée et autonomie

Aucun traceur, aucune police ni aucun script chargés depuis un service tiers. Une fois la page chargée, un diaporama fonctionne sans réseau : son style et son code sont dans le fichier HTML, ses images à côté.

La seule ressource prise ailleurs est le logo, servi par static.alpinux.org — un serveur de l'association. Le build refuse toute autre adresse externe.

---

Déploiement

git push  (sur main)
       │
Gitea  ──  webhook  ──▶  https://presentations.alpinux.org/deploy
                               │  service d'écoute, signature HMAC vérifiée
                               ▼
deploy-presentations.sh :  git pull  →  npm ci  →  build dans un staging  →  rsync
                               ▼
                 https://presentations.alpinux.org

Les contributions arrivent par pull request sur main. À la fusion, le serveur construit le site dans un répertoire de staging et ne le copie vers le DocumentRoot que si le build a réussi : une fiche invalide ne casse pas le site en ligne.

Le journal est dans /var/log/presentations-deploy.log ; une exécution réussie y est encadrée par Deploy started et Deploy done.

L'installation côté serveur, la déclaration du webhook et les pièges à connaître sont décrits dans deploy/webhook.md.