Rédiger en ligne de commande¶

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 : votre éditeur habituel, l'aperçu du site en direct, et la possibilité de tout relire avant de proposer quoi que ce soit.

Besoin d'un compte

Comme pour la contribution depuis le navigateur, il faut un compte sur la forge de l'association — voir Le Git d'Alpinux. Configurez au passage votre clé SSH : vous n'aurez plus à taper de mot de passe.

La règle est la même que depuis le navigateur : on ne modifie jamais main directement. On travaille sur une branche, et on propose son travail par une pull request. Cela vaut pour tout le monde, mainteneurs compris.

1. Bifurquer, puis cloner¶

Créez votre bifurcation (fork) du wiki : sur le dépôt, bouton Bifurcation en haut à droite. Vous obtenez votre propre copie, dans laquelle vous pouvez tout faire sans rien risquer.

Clonez ensuite votre copie, et ajoutez un lien vers le dépôt d'origine — appelé upstream par convention — pour pouvoir vous mettre à jour :

git clone git@gitea.alpinux.org:VOTRE-COMPTE/alpinux-wiki.git
cd alpinux-wiki
git remote add upstream git@gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki.git

Vous avez maintenant deux dépôts distants : origin, votre copie, où vous poussez ; et upstream, le wiki de l'association, d'où vous tirez les nouveautés.

git remote -v      # pour vérifier

Ce que contient le dépôt¶

Dossier	Contenu
`docs/`	les pages publiées, organisées en sections
`articles/`	textes longs hors navigation principale
`code/`	exemples de code cités dans les pages
`overrides/`	personnalisations du thème
`mkdocs.yml`	configuration du site, dont la navigation

Une page ajoutée dans docs/ n'apparaît dans le menu que si elle est déclarée dans la section nav: de mkdocs.yml. C'est l'oubli classique — et mkdocs build --strict le signale.

2. Partir du wiki à jour, sur une branche¶

Avant chaque nouveau sujet :

git switch main
git pull upstream main                  # récupérer ce qui a été publié entre-temps
git switch -c sauvegarder-ses-photos    # une branche par sujet, au nom parlant

Une branche par sujet permet de proposer une correction de faute aujourd'hui sans entraîner avec elle l'article commencé la semaine dernière.

3. Voir le rendu¶

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, vérifiez que rien n'est cassé :

mkdocs build --strict -d /tmp/wiki-build

--strict transforme le moindre avertissement en erreur : lien vers une page inexistante, fichier absent de la navigation. Si cette commande passe, votre contribution se publiera sans encombre.

Le -d n'est pas optionnel

Sans lui, mkdocs build écrit dans le site_dir configuré — qui désigne le répertoire du serveur, pas un chemin local.

4. Proposer la pull request¶

git add .
git commit -m "Article : sauvegarder ses photos sur un disque externe"
git push -u origin sauvegarder-ses-photos

Gitea affiche alors un lien pour ouvrir la pull request vers le wiki — ou rendez-vous sur votre bifurcation, la proposition y est suggérée en haut de page. La suite est décrite à l'étape 2 du guide de contribution : un mainteneur relit, fusionne, et la publication se fait toute seule.

Écrire un message de commit utile¶

Le message est lu par la personne qui relit, et par vous-même dans six mois. Une ligne qui dit ce qui change et pourquoi :

Guide Linux Mint : seuil Xfce relevé à 4 Go

Retour des install parties : en dessous de 4 Go, Cinnamon rame.

Évitez mise à jour, correction, wip : ils n'apprennent rien à personne.

5. Après la fusion¶

git switch main
git pull upstream main
git push origin main                      # votre bifurcation reste à jour
git branch -d sauvegarder-ses-photos      # la branche a fait son travail
git push origin --delete sauvegarder-ses-photos

Garder ses branches fusionnées ne sert à rien et finit par encombrer la liste. Le git push origin main évite l'écueil décrit dans Proposer un nouvel article : une bifurcation qu'on laisse vieillir repart d'une version dépassée au sujet suivant.

Quand ça coince¶

« Votre branche est en retard sur upstream/main » — quelqu'un a publié pendant que vous écriviez. Rapatriez et rejouez votre travail par-dessus :

git pull --rebase upstream main

Un conflit — deux modifications du même passage. Git encadre les deux versions dans le fichier par <<<<<<<, ======= et >>>>>>> : gardez le texte voulu, effacez les marqueurs, puis git add le fichier et git rebase --continue. En cas de doute, git rebase --abort annule tout et vous ramène au point de départ.

Vous avez modifié main par mégarde — rien n'est perdu tant que vous n'avez pas poussé. Créez la branche depuis l'état actuel, puis remettez main en place :

git switch -c ma-branche      # emporte les modifications avec vous
git switch main
git reset --hard upstream/main

Avec Obsidian¶

Si vous préférez un éditeur au confort d'un traitement de texte, le dépôt est aussi un coffre Obsidian prêt à l'emploi : voir Rédiger avec Obsidian.