alpinux-wiki/docs/contribuer.md

---
description: Comment contribuer au wiki Alpinux — créer un compte AlpID, modifier ou créer une page sur Gitea, ouvrir une pull request et comprendre la publication MkDocs.
---

# Contribuer au wiki

Ce wiki appartient à toute la communauté Alpinux. Si vous repérez une faute, une information dépassée, ou si vous avez envie de partager un guide — vous êtes au bon endroit.

!!! tip "Pas besoin d'être développeur"
    Tout se fait depuis le navigateur web, sans installer quoi que ce soit. Le seul prérequis est de savoir écrire du texte.

---

## Vue d'ensemble du processus

```
Vous              →  AlpID          →  Gitea           →  Mainteneurs     →  Wiki en ligne
Créez un compte      Vous connecte     Vous éditez        Relisent et        MkDocs publie
sur AlpID            à Gitea           la page            acceptent          automatiquement
                                       + ouvrez une       votre
                                       pull request       contribution
```

En résumé : vous proposez une modification, un mainteneur la valide, et le wiki se met à
jour tout seul — en quelques secondes, sans intervention de personne.

!!! note "Deux façons de contribuer"
    Ce guide décrit la voie **depuis le navigateur**, celle qui ne demande aucune
    installation et convient à une correction ponctuelle.

    Si vous rédigez régulièrement, la voie **depuis votre ordinateur** (dépôt cloné,
    éditeur Markdown ou Obsidian) est décrite en fin de page :
    [Rédiger depuis son ordinateur](#rediger-depuis-son-ordinateur).

---

## Étape 1 — Créer un compte AlpID

**AlpID** est le système d'authentification unique d'Alpinux. Un seul compte vous donne accès à Gitea, Nextcloud, et aux autres services de l'association.

1. Ouvrez votre navigateur et allez sur **[https://alpid.alpinux.org](https://alpid.alpinux.org)**.

2. Cliquez sur **« Créer un compte »** (ou *Register*).

3. Remplissez le formulaire :
    - **Nom d'utilisateur** : choisissez quelque chose de simple, sans accent ni espace (ex. `prenom.nom`)
    - **Adresse e-mail** : une adresse que vous consultez régulièrement
    - **Mot de passe** : au moins 8 caractères

4. Validez avec le bouton **« S'inscrire »**.

5. Vérifiez votre boîte mail et cliquez sur le lien de confirmation.

!!! note "Déjà membre Alpinux ?"
    Si vous avez déjà un compte sur le portail membres, vos identifiants fonctionnent peut-être déjà. Essayez de vous connecter directement.

---

## Étape 2 — Se connecter à Gitea

**Gitea** est la forge logicielle où sont hébergées les sources du wiki.

1. Allez sur **[https://gitea.alpinux.org](https://gitea.alpinux.org)**.

2. Cliquez sur **« Connexion »** en haut à droite.

3. Choisissez **« Se connecter via AlpID »** (bouton avec le logo Alpinux).

4. Vous êtes redirigé vers AlpID, qui confirme votre identité, puis revient sur Gitea.
   Vous êtes maintenant connecté — votre nom apparaît en haut à droite.

!!! success "C'est bon !"
    Pas besoin de créer un second compte sur Gitea. AlpID fait le lien automatiquement.

---

## Étape 3a — Modifier une page existante

C'est la façon la plus simple de contribuer : corriger une faute, compléter une section, mettre à jour une information.

### Trouver la page dans le dépôt

1. Allez sur le dépôt du wiki :
   **[https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki)**

2. Cliquez sur le dossier **`docs/`** — c'est là que se trouvent toutes les pages du wiki.

3. Les pages sont organisées par section :
    - `alpinux/` → pages sur l'association
    - `guides/` → tutoriels pratiques
    - `presentations/` → comptes-rendus de réunions
    - `technique/` → administration système

4. Naviguez jusqu'à la page que vous souhaitez modifier et cliquez dessus.

### Ouvrir l'éditeur

5. En haut à droite du contenu du fichier, cliquez sur l'icône **crayon** ✏️ (*Modifier ce fichier*).

    L'éditeur s'ouvre directement dans le navigateur. Vous pouvez basculer entre l'onglet **Édition** et l'onglet **Aperçu** pour voir le rendu de vos modifications.

6. Faites vos modifications dans l'éditeur.

!!! tip "Raccourcis utiles dans l'éditeur"
    - `Ctrl+Z` annule la dernière action
    - L'onglet **Aperçu** affiche le rendu final avant de soumettre

### Proposer la modification

7. Faites défiler la page vers le bas jusqu'à la section **« Valider les modifications »** (*Commit Changes*).

8. Remplissez le champ **« Message de commit »** : décrivez en une ligne ce que vous avez changé.
   Exemple : `Correction faute de frappe dans le guide Linux Mint`

9. Sélectionnez l'option **« Créer une nouvelle branche et ouvrir une pull request »**.
   - Gitea propose un nom de branche automatique — vous pouvez le garder tel quel.

10. Cliquez sur **« Proposer la modification »**.

---

## Étape 3b — Proposer un nouvel article

Vous avez rédigé un guide ou un compte-rendu et souhaitez l'ajouter au wiki.

### Choisir le bon dossier

Avant de créer votre fichier, identifiez dans quelle section il a sa place :

| Section | Dossier | Exemples |
|---|---|---|
| Guides pratiques | `docs/guides/` | Installer un logiciel, sauvegarder ses données |
| Présentations | `docs/presentations/` | Compte-rendu d'une présentation en réunion |
| Alpinux | `docs/alpinux/` | Informations sur l'association |
| Technique | `docs/technique/` | Administration système, serveurs |

### Créer le fichier

1. Naviguez dans le dépôt vers le bon dossier (ex. `docs/guides/`).

2. Cliquez sur le bouton **« + »** ou **« Nouveau fichier »** en haut à droite de la liste des fichiers.

3. **Donnez un nom à votre fichier** dans le champ en haut :
    - Utilisez des minuscules, des tirets à la place des espaces, sans accent.
    - Terminez toujours par `.md` (extension Markdown).
    - Exemples : `installer-inkscape.md`, `utiliser-keepassxc.md`

4. **Commencez votre article** par un titre de niveau 1 :

    ```markdown
    # Titre de mon article

    Introduction en une ou deux phrases.

    ## Première section

    Contenu...
    ```

5. Rédigez votre contenu (voir la section [Écrire en Markdown](#ecrire-en-markdown) plus bas).

6. Faites défiler vers le bas, remplissez un message de commit descriptif, choisissez **« Créer une nouvelle branche et ouvrir une pull request »**, et cliquez sur **« Proposer le nouveau fichier »**.

---

## Étape 4 — Ouvrir la pull request

Après avoir cliqué sur « Proposer la modification » ou « Proposer le nouveau fichier », Gitea vous amène automatiquement sur la page de création de la *pull request* (PR).

!!! info "C'est quoi une pull request ?"
    Une pull request (ou *demande de fusion*) est une proposition formelle de modification. Elle permet aux mainteneurs de relire votre travail avant qu'il soit intégré au wiki. C'est le mécanisme standard de collaboration sur les forges comme Gitea ou GitHub.

### Remplir la pull request

1. **Titre** : Gitea le pré-remplit avec votre message de commit — vous pouvez le modifier pour qu'il soit plus clair.
   Exemple : `Ajout d'un guide sur KeePassXC`

2. **Description** (optionnelle mais utile) : expliquez en quelques mots ce que vous avez fait et pourquoi.
   Exemple :
   ```
   Ajout d'un guide d'utilisation de KeePassXC pour débutants.
   Couvre : installation, création d'une base, ajout d'un mot de passe.
   ```

3. Cliquez sur **« Créer la pull request »**.

### Et après ?

- Les mainteneurs reçoivent une notification par e-mail.
- Ils reliront votre contribution et pourront laisser des commentaires directement sur la PR.
- Si des ajustements sont demandés, vous pouvez modifier à nouveau le fichier — la PR se met à jour automatiquement.
- Une fois validée, un mainteneur clique sur **« Fusionner »** (*Merge*), et votre contribution rejoint la branche principale.

!!! tip "Patience !"
    Les mainteneurs sont bénévoles. Si votre PR n'a pas de retour sous quelques jours, n'hésitez pas à en parler lors d'une réunion ou sur Matrix.

---

## Étape 5 — La publication avec MkDocs

Une fois votre pull request fusionnée, voici ce qui se passe dans les coulisses pour que votre article apparaisse sur le wiki.

### 1. Le Markdown devient du HTML

**MkDocs** est l'outil qui transforme les fichiers `.md` (texte brut) en un site web complet. C'est l'équivalent d'une imprimerie automatique : vous écrivez le texte, MkDocs fabrique les pages.

La commande lancée sur le serveur est simplement :

```bash
mkdocs build
```

Elle lit tous les fichiers `.md` dans `docs/`, applique le thème (Material for MkDocs), et génère un dossier `site/` contenant du HTML, du CSS et du JavaScript prêts à être servis.

### 2. Le thème appliqué

Le wiki utilise le thème **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)**, qui ajoute automatiquement :

- la barre de navigation et les onglets,
- la barre de recherche,
- la mise en forme des blocs de code, des tableaux, des alertes (`!!! tip`, `!!! warning`…),
- la compatibilité mobile.

Vous n'avez pas à vous en préoccuper : il suffit d'écrire du Markdown valide.

### 3. Les fichiers sont déployés

Le dossier généré est copié dans le répertoire servi par Apache :

```
/var/www/clients/client1/web2/web/wiki-static/
```

C'est ce que votre navigateur lit quand vous visitez `https://wiki.alpinux.org`.

### 4. Délai de publication

**Quelques secondes.** Personne n'a de bouton à presser : dès que votre pull request est
fusionnée, Gitea prévient le serveur, qui récupère les sources et reconstruit le site.
Rafraîchissez la page une minute plus tard, votre texte y est.

Si le build échoue — un lien mort, une page absente de la navigation — **rien n'est mis en
ligne** : le site reste dans son état précédent, et c'est la version fautive qui attend
une correction. Vous ne risquez donc pas de casser le wiki en vous trompant.

Les mainteneurs peuvent consulter la [procédure de déploiement](technique/deploiement-wiki.md) pour les détails techniques.

---

## Rédiger depuis son ordinateur {#rediger-depuis-son-ordinateur}

Pour un article long, une série de corrections ou un travail hors connexion, il est plus
confortable de travailler sur une copie locale du wiki.

### Récupérer le wiki

```bash
git clone git@gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki.git
cd alpinux-wiki
```

Le dépôt contient les pages (`docs/`), les articles longs (`articles/`), les exemples de
code cités dans le wiki (`code/`) et la configuration du site (`mkdocs.yml`).

### Voir le rendu avant de publier

```bash
python3 -m venv venv && source venv/bin/activate
pip install mkdocs-material
mkdocs serve
```

Ouvrez `http://localhost:8000` : la page se recharge à chaque enregistrement. C'est le
meilleur moyen de vérifier un tableau, une image ou un bloc de code avant de proposer
quoi que ce soit.

### Proposer vos modifications

Comme depuis le navigateur, le travail passe par une branche et une pull request :

```bash
git switch -c mon-article           # une branche par sujet
git add .
git commit -m "Article : sauvegarder ses photos sur un disque externe"
git push -u origin mon-article
```

Gitea affiche alors un lien pour ouvrir la pull request. La suite est identique à
l'[étape 4](#etape-4-ouvrir-la-pull-request).

!!! warning "Pousser sur `main` publie immédiatement"
    Les mainteneurs peuvent pousser directement sur `main`. Dans ce cas il n'y a ni
    relecture, ni filet : le site est reconstruit dans la minute. Pour un brouillon,
    utilisez une branche.

### Avec Obsidian

Le dépôt est aussi un coffre [Obsidian](https://obsidian.md) : ouvrez le dossier cloné
comme coffre, les réglages et extensions sont déjà versionnés (mise à jour automatique
des liens internes, et *Linter* pour la mise en forme).

L'extension **Obsidian Git** y est installée. Si vous activez sa sauvegarde automatique,
retenez bien ce qu'elle implique : chaque sauvegarde est un commit poussé sur la branche
courante — donc, sur `main`, une publication en ligne. Rédigez vos brouillons sur une
branche, ou laissez la sauvegarde automatique désactivée et poussez quand le texte est
prêt.

---

## Écrire en Markdown {#ecrire-en-markdown}

Le Markdown est un format texte très simple. Voici l'essentiel pour rédiger une page wiki.

### Titres

```markdown
# Titre principal (H1) — un seul par page
## Section (H2)
### Sous-section (H3)
```

### Mise en forme

```markdown
**texte en gras**
*texte en italique*
`code en ligne`
```

### Listes

```markdown
- Élément
- Autre élément
    - Sous-élément (4 espaces d'indentation)

1. Premier
2. Deuxième
3. Troisième
```

### Liens

```markdown
[Texte du lien](https://exemple.com)
[Lien vers une autre page du wiki](../guides/linux-mint-depuis-windows.md)
```

### Images

```markdown
![Texte alternatif](https://static.alpinux.org/logo/alpinux-logo.png)
```

### Blocs de code

Entourez le code de trois accents graves et précisez le langage :

````markdown
```bash
sudo apt update
sudo apt install inkscape
```
````

### Alertes (admonitions)

Ces blocs colorés attirent l'attention du lecteur :

```markdown
!!! tip "Astuce"
    Texte de l'astuce. (4 espaces d'indentation)

!!! warning "Attention"
    Quelque chose d'important à ne pas rater.

!!! note
    Une note informative.
```

Résultat :

!!! tip "Astuce"
    Indentez le contenu d'une admonition avec 4 espaces.

!!! warning "Attention"
    Gardez vos titres H1 uniques par page.

### Tableaux

```markdown
| Colonne A | Colonne B | Colonne C |
|---|---|---|
| Valeur 1  | Valeur 2  | Valeur 3  |
| Valeur 4  | Valeur 5  | Valeur 6  |
```

---

## Ressources complémentaires

- [Éditeur Markdown en ligne (aperçu temps réel)](https://markdownlivepreview.com/)
- [Référence complète Markdown](https://www.markdownguide.org/basic-syntax/)
- [Documentation MkDocs Material](https://squidfunk.github.io/mkdocs-material/reference/)
- Dépôt du wiki : [gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki)

---

## Une question ? Un problème ?

- Posez votre question lors d'une **réunion Alpinux** (1er et 3e jeudis du mois)
- Ouvrez une **issue** directement sur Gitea : [Nouvelle issue](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki/issues/new)
- Rejoignez le salon **Matrix** de l'association