Alpinux c52652f07e Éclater « Contribuer » en pages dédiées, et documenter la forge

La page de contribution portait tout : le parcours web, la syntaxe
Markdown, la ligne de commande et Obsidian. Chacun de ces morceaux a
maintenant sa page, et la page d'accueil de la contribution garde ce
qu'elle sait faire — expliquer le processus de bout en bout.

Nouvelle page « Le Git d'Alpinux » : l'inscription est fermée et passe
par AlpID, ce que rien n'indiquait jusqu'ici.

Le coffre Obsidian est configuré en liens Markdown relatifs, comme la
page le décrit : MkDocs ne comprend pas les [[wikilinks]].

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BE4rvHVETRoWnYNDTGssdo

2026-09-19 22:52:22 +02:00

4.8 KiB

Raw Blame History

wiki.alpinux.org

Documentation, guides et ressources du LUG Alpinux — Savoie. Accessible sur https://wiki.alpinux.org.

Construit avec MkDocs Material. Les sources sont des fichiers Markdown ; le site HTML est généré sur le serveur, à chaque push sur main.

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
Écrire un article, travailler hors ligne	Bifurquer, cloner, une branche par sujet, pull request	Rédiger en ligne de commande
Rédiger dans Obsidian	Ouvrir le clone comme coffre — il est déjà configuré — sur une branche	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

Personne n'a de build à lancer ni de fichier à copier sur le serveur. Publier, c'est fusionner une pull request : le contenu arrive sur main, le reste est automatique.

La pull request est la règle, pour tout le monde. On ne modifie pas main directement, même quand on en a le droit : c'est ce qui permet la relecture, garde une trace des discussions, et laisse le temps à un texte de reposer avant d'être publié.

Ce qui se passe une fois sur `main`

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

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é.

Les deux pièges à connaître

Un commit sur main est une publication. Pas de relecture, pas d'étape de validation : le site est reconstruit dans la foulée. D'où la règle ci-dessus — les brouillons vivent sur une branche. Attention en particulier à la sauvegarde automatique d'Obsidian Git, qui commite et pousse toute seule sur la branche courante.

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.

Structure des sources

.
├── mkdocs.yml          # Configuration MkDocs (nav, thème, plugins)
├── docs/               # Pages Markdown
│   ├── index.md
│   ├── alpinux/        # Présentation, FAQ, événements
│   ├── guides/         # Guides pratiques (Linux Mint, Docker, chiffrement…)
│   ├── presentations/  # Supports de présentations passées
│   ├── technique/      # Documentation technique (déploiement, serveur…)
│   └── communication/
├── 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)
└── .obsidian/          # Réglages du coffre Obsidian (partagés)

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.

Développement local

python3 -m venv venv && source venv/bin/activate
pip install mkdocs-material
mkdocs serve
# → http://localhost:8000  (rechargement automatique à chaque modification)

Pour vérifier que le build est propre (liens, structure) avant de pousser :

mkdocs build --strict -d /tmp/wiki-build

Le -d est nécessaire en local : le site_dir de mkdocs.yml pointe vers le DocumentRoot Apache du serveur, pas vers un chemin local.

Déploiement serveur (ISPConfig)

Le wiki est servi statiquement par Apache via ISPConfig :

DocumentRoot : /var/www/clients/client1/web2/web/wiki-static
Let's Encrypt SSL activé
Aucun service à redémarrer après un déploiement

Voir aussi

Ce dépôt se suffit à lui-même : ~/Projects/alpinux.wiki, rien à cloner à côté.

Pour les autres projets de l'association (les applications Flask, le CDN, l'infra) et leurs procédures de déploiement : ~/Projects/org.alpinux.owni/README.md.

4.8 KiB Raw Blame History