ce1f58d652
Le README et les pages de contribution se contredisaient : « éditer la page dans Gitea » ignorait la bifurcation devenue la règle, le tableau d'aiguillage ne connaissait pas trois des pages existantes, et le délai de publication n'était pas le même des deux côtés. Le README oriente désormais, le wiki explique — une seule source de vérité par sujet. Nouvelle page « Relire et fusionner » : ce que fusionner publie, la relecture, la vérification du build, les pièges du poste — renommer une page casse son adresse, aucune redirection n'est installée. Au passage, trois points où les pages ne se répondaient pas : la publication immédiate depuis Obsidian ne concerne que le clone du dépôt du wiki, la bifurcation se remet à jour après chaque fusion, et l'accueil renvoyait au Markdown générique plutôt qu'à notre page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BE4rvHVETRoWnYNDTGssdo
136 lines
6.3 KiB
Markdown
136 lines
6.3 KiB
Markdown
# 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](https://wiki.alpinux.org/contribuer/)**.
|
|
|
|
---
|
|
|
|
## 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](https://wiki.alpinux.org/guides/git-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](https://wiki.alpinux.org/contribuer/#etape-modifier-une-page) |
|
|
| Écrire un article | **Bifurquer**, la remettre à jour, une branche par sujet, pull request | [Proposer un nouvel article](https://wiki.alpinux.org/contribuer/#etape-nouvel-article) |
|
|
| Travailler hors ligne | Cloner sa bifurcation, `upstream` vers ce dépôt, rendu local | [Rédiger en ligne de commande](https://wiki.alpinux.org/contribuer/ligne-de-commande/) |
|
|
| Rédiger dans Obsidian | Ouvrir le clone comme coffre — il est déjà configuré — sur une branche | [Rédiger avec Obsidian](https://wiki.alpinux.org/contribuer/obsidian/) |
|
|
| Retrouver une syntaxe Markdown | Consulter la référence des extensions réellement activées ici | [Écrire en Markdown](https://wiki.alpinux.org/contribuer/markdown/) |
|
|
| Relire et publier une contribution | Relire, vérifier le build, fusionner : la publication suit | [Guide du mainteneur](https://wiki.alpinux.org/contribuer/mainteneurs/) |
|
|
| 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
|
|
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
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
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](https://wiki.alpinux.org/contribuer/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.
|