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 fois que des commits arrivent sur main — c'est-à-dire à chaque pull request fusionnée.

Ce fichier s'adresse à qui ouvre le dépôt. Les procédures de contribution, elles, vivent dans le wiki lui-même et n'ont qu'un seul endroit où être à jour : Contribuer au wiki.

---

Je veux…

Ce que vous voulez faire	Ce que vous faites	Détail
Avoir un compte pour contribuer	Créer un AlpID, puis se connecter à la forge	Le Git d'Alpinux
Corriger une faute, mettre à jour une info	Éditer la page depuis le navigateur — Gitea crée votre bifurcation au passage — puis pull request	Modifier une page
Écrire un article	Bifurquer, la remettre à jour, une branche par sujet, pull request	Proposer un nouvel article
Travailler hors ligne	Cloner sa bifurcation, upstream vers ce dépôt, rendu local	Rédiger en ligne de commande
Rédiger dans Obsidian	Ouvrir le clone comme coffre — il est déjà configuré — sur une branche	Rédiger avec Obsidian
Retrouver une syntaxe Markdown	Consulter la référence des extensions réellement activées ici	Écrire en Markdown
Relire et publier une contribution	Relire, vérifier le build, fusionner : la publication suit	Guide du mainteneur
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é.

Sans droit d'écriture sur ce dépôt, on travaille dans sa bifurcation (fork) — sa copie personnelle — et la pull request part de là. C'est le cas le plus courant, et Gitea le propose de lui-même dès qu'on édite une page.

---

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 moins d'une minute entre la fusion 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.

Le déroulé complet — bifurcation, upstream, branche, rendu local, pull request — est décrit dans Rédiger en ligne de commande.

---

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 : ~/Projects/org.alpinux.owni/README.md sert d'index. Ceux qui ont leur propre dépôt — alpinux.admin, alpinux.dynamic — décrivent leur déploiement dans leur propre README.