alpinux.cedrica5l/alpinux.presentations
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
alpinux.presentations/README.md
Cédrix 9ecf1973b8 Suivre le nom réel du dépôt : alpinux.presentations 
Le dépôt a été créé sur la forge sous le nom alpinux.presentations, et non
alpinux-presentations : adresses de clonage, lien de la page d'accueil et
consignes d'installation sont alignés.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M713yNBL8cssBA1Zri5QLT
2026-10-10 22:06:47 +02:00

226 lines
8.4 KiB
Markdown
Raw Blame History

# 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).
Reference in a new issue View git blame Copy permalink