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