diff --git a/README.md b/README.md index 0e421cd..86fe91e 100644 --- a/README.md +++ b/README.md @@ -7,25 +7,47 @@ Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le --- -## Flux de publication +## Je veux… + +| Ce que vous voulez faire | Ce que vous faites | Détail | +|---|---|---| +| Corriger une faute, mettre à jour une info | Éditer la page dans Gitea, ouvrir une **pull request** | [Contribuer](https://wiki.alpinux.org/contribuer/) | +| Écrire un article, travailler hors ligne | Cloner le dépôt, **une branche par sujet**, pull request | [Rédiger depuis son ordinateur](https://wiki.alpinux.org/contribuer/#rediger-depuis-son-ordinateur) | +| Rédiger dans Obsidian | Ouvrir ce dossier comme coffre — il est déjà configuré | idem | +| Relire et publier une contribution | Fusionner la pull request : la publication suit | ci-dessous | +| Comprendre pourquoi ça n'est pas en ligne | Lire le journal de déploiement sur le serveur | [Déploiement du wiki](https://wiki.alpinux.org/technique/deploiement-wiki/) | + +**Personne n'a de build à lancer ni de fichier à copier sur le serveur.** Publier, c'est +faire arriver du contenu sur la branche `main` de ce dépôt — que ce soit par une pull +request fusionnée ou par un push direct. + +--- + +## Ce qui se passe une fois sur `main` ``` -Modifier → git commit → git push → webhook Gitea → git pull + mkdocs build sur le serveur +main (Gitea) + │ webhook ──▶ service d'écoute sur le serveur (signature vérifiée) + ▼ +deploy-wiki.sh : git pull → mkdocs build --strict → staging + │ + │ build réussi ? ── non ──▶ le site en ligne reste tel quel + ▼ oui +rsync vers le DocumentRoot Apache ──▶ https://wiki.alpinux.org ``` -```bash -git add . -git commit -m "..." -git push # → gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki -``` +Compter **une minute** entre le push et la page à jour. Le build passe par un répertoire +de staging : une erreur — lien mort, page absente de la navigation — laisse le site en +ligne intact plutôt que de le publier à moitié. -C'est tout : le push suffit. Le webhook déclenche `deploy-wiki.sh` sur le serveur, qui -construit le site dans un répertoire de staging et ne le met en ligne que si le build a -réussi. La procédure complète, et quoi faire quand le webhook ne répond pas, sont -décrites dans [Déploiement du wiki](docs/technique/deploiement-wiki.md). +### Les deux pièges à connaître -> Le webhook est attaché à **ce** dépôt. Un push dans l'ancien monorepo -> `alpinux.site.2026` ne publie rien. +> **Un push sur `main` est une publication.** Pas de relecture, pas d'étape de validation : +> le site est reconstruit dans la foulée. Les brouillons vont sur une branche. Cela vaut +> aussi pour la sauvegarde automatique d'Obsidian Git, qui commite et pousse toute seule. + +> **Le webhook est attaché à ce dépôt.** Un push dans l'ancien monorepo +> `alpinux.site.2026`, qui a longtemps hébergé le wiki, ne publie plus rien. --- @@ -44,11 +66,14 @@ décrites dans [Déploiement du wiki](docs/technique/deploiement-wiki.md). ├── overrides/ # Surcharges du thème Material ├── articles/ # Articles longs (hors nav principale) ├── code/ # Exemples de code référencés dans le wiki -└── scripts/ # Scripts utilitaires (build-assets.py) +├── scripts/ # Scripts utilitaires (build-assets.py) +└── .obsidian/ # Réglages du coffre Obsidian (partagés) ``` -Les images des articles ne sont pas versionnées : elles sont hébergées sur -`static.alpinux.org`. Le logo PNG est généré depuis le SVG par `scripts/build-assets.py`. +Aucune image n'est versionnée ici : le logo et les illustrations sont servis depuis +`static.alpinux.org`, les pages y pointent par leur URL complète. `scripts/build-assets.py` +sert à fabriquer les fichiers du logo à y téléverser quand le SVG source change — il ne +tourne pas au déploiement. --- diff --git a/docs/contribuer.md b/docs/contribuer.md index 306cc86..31aaa8d 100644 --- a/docs/contribuer.md +++ b/docs/contribuer.md @@ -21,7 +21,16 @@ sur AlpID à Gitea la page acceptent au pull request contribution ``` -En résumé : vous proposez une modification, un mainteneur la valide, et le wiki se met à jour automatiquement. +En résumé : vous proposez une modification, un mainteneur la valide, et le wiki se met à +jour tout seul — en quelques secondes, sans intervention de personne. + +!!! note "Deux façons de contribuer" + Ce guide décrit la voie **depuis le navigateur**, celle qui ne demande aucune + installation et convient à une correction ponctuelle. + + Si vous rédigez régulièrement, la voie **depuis votre ordinateur** (dépôt cloné, + éditeur Markdown ou Obsidian) est décrite en fin de page : + [Rédiger depuis son ordinateur](#rediger-depuis-son-ordinateur). --- @@ -216,7 +225,7 @@ Vous n'avez pas à vous en préoccuper : il suffit d'écrire du Markdown valide. ### 3. Les fichiers sont déployés -Le dossier `site/` généré est copié dans le répertoire servi par Apache : +Le dossier généré est copié dans le répertoire servi par Apache : ``` /var/www/clients/client1/web2/web/wiki-static/ @@ -226,12 +235,78 @@ C'est ce que votre navigateur lit quand vous visitez `https://wiki.alpinux.org`. ### 4. Délai de publication -La publication n'est pas instantanée : un mainteneur doit déclencher le build après la fusion de votre PR. En pratique, les nouveaux articles apparaissent **dans les 24 à 48 heures** suivant la fusion. +**Quelques secondes.** Personne n'a de bouton à presser : dès que votre pull request est +fusionnée, Gitea prévient le serveur, qui récupère les sources et reconstruit le site. +Rafraîchissez la page une minute plus tard, votre texte y est. + +Si le build échoue — un lien mort, une page absente de la navigation — **rien n'est mis en +ligne** : le site reste dans son état précédent, et c'est la version fautive qui attend +une correction. Vous ne risquez donc pas de casser le wiki en vous trompant. Les mainteneurs peuvent consulter la [procédure de déploiement](technique/deploiement-wiki.md) pour les détails techniques. --- +## Rédiger depuis son ordinateur {#rediger-depuis-son-ordinateur} + +Pour un article long, une série de corrections ou un travail hors connexion, il est plus +confortable de travailler sur une copie locale du wiki. + +### Récupérer le wiki + +```bash +git clone git@gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki.git +cd alpinux-wiki +``` + +Le dépôt contient les pages (`docs/`), les articles longs (`articles/`), les exemples de +code cités dans le wiki (`code/`) et la configuration du site (`mkdocs.yml`). + +### Voir le rendu avant de publier + +```bash +python3 -m venv venv && source venv/bin/activate +pip install mkdocs-material +mkdocs serve +``` + +Ouvrez `http://localhost:8000` : la page se recharge à chaque enregistrement. C'est le +meilleur moyen de vérifier un tableau, une image ou un bloc de code avant de proposer +quoi que ce soit. + +### Proposer vos modifications + +Comme depuis le navigateur, le travail passe par une branche et une pull request : + +```bash +git switch -c mon-article # une branche par sujet +git add . +git commit -m "Article : sauvegarder ses photos sur un disque externe" +git push -u origin mon-article +``` + +Gitea affiche alors un lien pour ouvrir la pull request. La suite est identique à +l'[étape 4](#etape-4-ouvrir-la-pull-request). + +!!! warning "Pousser sur `main` publie immédiatement" + Les mainteneurs peuvent pousser directement sur `main`. Dans ce cas il n'y a ni + relecture, ni filet : le site est reconstruit dans la minute. Pour un brouillon, + utilisez une branche. + +### Avec Obsidian + +Le dépôt est aussi un coffre [Obsidian](https://obsidian.md) : ouvrez le dossier cloné +comme coffre, les réglages et extensions sont déjà versionnés (mise à jour automatique +des liens internes, et *Linter* pour la mise en forme). + +L'extension **Obsidian Git** y est installée. Si vous activez sa sauvegarde automatique, +retenez bien ce qu'elle implique : chaque sauvegarde est un commit poussé sur la branche +courante — donc, sur `main`, une publication en ligne. Rédigez vos brouillons sur une +branche, ou laissez la sauvegarde automatique désactivée et poussez quand le texte est +prêt. + +--- + ## Écrire en Markdown {#ecrire-en-markdown} Le Markdown est un format texte très simple. Voici l'essentiel pour rédiger une page wiki.