c52652f07e
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
119 lines
4.8 KiB
Markdown
119 lines
4.8 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 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](https://wiki.alpinux.org/contribuer/) |
|
|
| Écrire un article, travailler hors ligne | **Bifurquer**, cloner, une branche par sujet, pull request | [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 | 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
|
|
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
|
|
|
|
```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.
|
|
|
|
---
|
|
|
|
## 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`.
|