alpinux-wiki/docs/contribuer/index.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

```
Compte AlpID → Bifurcation → Branche → Pull request → Mainteneurs → Wiki
Vous connecte  Votre copie   Vos       Vous la        Relisent et   MkDocs
à la forge     personnelle   modifs    proposez       fusionnent    publie
               du wiki       y sont    au wiki                      la fusion
                             isolées
```

Le point important : **vous n'écrivez jamais dans le dépôt du wiki**. Vous écrivez dans
votre bifurcation — votre copie personnelle, où vous ne risquez rien — puis vous
proposez ce travail par une pull request. Un mainteneur relit, fusionne, et le site se
met à jour tout seul dans les secondes qui suivent.

!!! note "Et si j'ai les droits d'écriture sur le dépôt ?"
    La règle reste la même : une branche, puis une pull request, même pour les
    mainteneurs. La bifurcation devient alors facultative, rien d'autre ne change.

!!! 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) a sa propre page :
    [Rédiger en ligne de commande](ligne-de-commande.md) ou
    [Rédiger avec Obsidian](obsidian.md).

---

## Avant de commencer — avoir un compte

Les contributions passent par la forge de l'association, et il faut donc y avoir un
compte. Il se crée en quelques minutes avec **AlpID**, l'identifiant unique d'Alpinux :
la marche à suivre est décrite dans [Le Git d'Alpinux](../guides/git-alpinux.md#creer-son-compte).

!!! note "Déjà un compte sur le cloud ou le portail membres ?"
    C'est le même : connectez-vous sur
    [gitea.alpinux.org](https://gitea.alpinux.org) avec le bouton **« Se connecter avec
    AlpID »**, votre compte sur la forge est créé au passage.

---

## Étape 1a — Modifier une page existante {#etape-modifier-une-page}

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 »**.

!!! info "Si Gitea vous parle de « bifurcation »"
    Selon vos droits sur le dépôt, deux situations :

    - **Vous êtes membre de l'équipe du wiki** : l'éditeur s'ouvre directement et vous
      créez une branche dans le dépôt, comme décrit ci-dessus.
    - **Vous n'avez pas encore les droits d'écriture** : Gitea vous propose de créer une
      **bifurcation** (*fork*), c'est-à-dire votre copie personnelle du dépôt. Acceptez :
      votre modification y est enregistrée, et la pull request la propose au wiki. Le
      résultat est le même, la copie sert juste de brouillon qui vous appartient.

    Dans les deux cas, vous n'écrivez jamais directement sur le site en ligne : c'est la
    fusion de la pull request par un mainteneur qui publie.

---

## Étape 1b — Proposer un nouvel article {#etape-nouvel-article}

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

### Partir de sa bifurcation

Un nouvel article ne se crée pas dans le dépôt du wiki, mais dans **votre bifurcation**.
Si vous n'en avez pas encore, créez-la : sur
[le dépôt du wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki), bouton
**« Bifurcation »** (*Fork*) en haut à droite. Vous obtenez une copie complète du wiki
dans votre espace personnel sur la forge, sur laquelle vous avez tous les droits.

!!! warning "Une bifurcation vieillit"
    Votre copie ne se met pas à jour toute seule : elle reste figée au jour où vous
    l'avez créée. **Avant d'écrire, récupérez l'état actuel du wiki**, sinon votre
    article partira d'une version dépassée et la pull request risque le conflit.

    - **Depuis la forge** : sur votre bifurcation, le bandeau
      *« Cette branche est en retard de N commits »* propose un bouton de
      synchronisation — cliquez-le.
    - **Depuis votre ordinateur** : `git pull upstream main`, après avoir déclaré le
      dépôt du wiki comme `upstream`. La marche à suivre complète est dans
      [Rédiger en ligne de commande](ligne-de-commande.md#1-bifurquer-puis-cloner).

    Pour un article un peu long, travailler depuis son ordinateur est nettement plus
    confortable que l'éditeur du navigateur — et c'est la même pull request au bout.

### 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. Dans **votre bifurcation** (et non dans le dépôt du wiki), naviguez 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 — la syntaxe disponible est détaillée dans [Écrire en Markdown](markdown.md).

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 2 — Ouvrir la pull request {#etape-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 3 — La publication avec MkDocs {#etape-publication}

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

**Moins d'une minute.** 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.

---

## Aller plus loin

Une fois le mécanisme compris, trois pages pour approfondir :

<div class="grid cards" markdown>

- :material-language-markdown: **[Écrire en Markdown](markdown.md)**

    Toute la syntaxe utilisable ici : titres, listes, liens, images, blocs de code,
    alertes, tableaux, notes de bas de page — et ce qui n'est pas activé.

- :material-console: **[Rédiger en ligne de commande](ligne-de-commande.md)**

    Bifurquer, cloner, travailler sur une branche, voir le rendu en local avec MkDocs,
    proposer une pull request, et se sortir d'un conflit.

- :material-notebook-edit: **[Rédiger avec Obsidian](obsidian.md)**

    Le dépôt est un coffre Obsidian prêt à l'emploi : réglages, publication depuis
    l'éditeur, et le piège de la sauvegarde automatique.

- :material-check-decagram: **[Relire et fusionner](mainteneurs.md)**

    Pour l'équipe du wiki : relire une pull request, vérifier le build, fusionner —
    et ce que ça publie.

</div>

---

## 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
- Parcourez le dépôt : [gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki)