02cf82447b
Un dossier par présentation en Markdown, converti en diaporama HTML autonome par Marp CLI, et une page d'accueil générée qui les liste toutes. - scripts/build.mjs : build strict (fiche validée, images vérifiées, aucune ressource externe hormis le logo), page d'accueil filtrable, presentations.json et .htaccess pour l'en-tête CORS - theme/alpinux.css : thème commun pour la vidéoprojection, classes titre et demo - slides/_modele : modèle commenté, non publié - slides/pdf-signer : « Lire, remplir et signer ses PDF », avec notes d'orateur - scripts/deploy-presentations.sh et deploy/ : déploiement par webhook Gitea, sur le modèle du wiki et de www Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M713yNBL8cssBA1Zri5QLT
226 lines
8.4 KiB
Markdown
226 lines
8.4 KiB
Markdown
# Présentations d'Alpinux
|
|
|
|
Les diaporamas des réunions d'[Alpinux](https://alpinux.org), 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](https://marp.app) 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](CONTRIBUER.md).
|
|
|
|
---
|
|
|
|
## Je veux…
|
|
|
|
| Ce que vous voulez faire | Ce que vous faites |
|
|
|-------------------------------------------|-----------------------------------------------------------------|
|
|
| Proposer une présentation | Suivre [CONTRIBUER.md](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](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.
|
|
|
|
```bash
|
|
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`](https://github.com/marp-team/marp-cli) — convertit le
|
|
Markdown en diaporama ;
|
|
- [`js-yaml`](https://github.com/nodeca/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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```yaml
|
|
---
|
|
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 :
|
|
|
|
```json
|
|
{
|
|
"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](deploy/webhook.md).
|