# 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 depuis son ordinateur](https://wiki.alpinux.org/contribuer/#rediger-depuis-son-ordinateur) |
| 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`.