Éclater « Contribuer » en pages dédiées, et documenter la forge
La page de contribution portait tout : le parcours web, la syntaxe Markdown, la ligne de commande et Obsidian. Chacun de ces morceaux a maintenant sa page, et la page d'accueil de la contribution garde ce qu'elle sait faire — expliquer le processus de bout en bout. Nouvelle page « Le Git d'Alpinux » : l'inscription est fermée et passe par AlpID, ce que rien n'indiquait jusqu'ici. Le coffre Obsidian est configuré en liens Markdown relatifs, comme la page le décrit : MkDocs ne comprend pas les [[wikilinks]]. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BE4rvHVETRoWnYNDTGssdo
This commit is contained in:
Alpinux
parent
fd3c8b41b4
commit
c52652f07e
9 changed files with 827 additions and 226 deletions
6
.obsidian/app.json
vendored
6
.obsidian/app.json
vendored
|
|
@ -5,5 +5,7 @@
|
||||||
"margin": "0",
|
"margin": "0",
|
||||||
"downscalePercent": 100
|
"downscalePercent": 100
|
||||||
},
|
},
|
||||||
"alwaysUpdateLinks": true
|
"alwaysUpdateLinks": true,
|
||||||
}
|
"useMarkdownLinks": true,
|
||||||
|
"newLinkFormat": "relative"
|
||||||
|
}
|
||||||
|
|
|
||||||
|
|
@ -12,7 +12,7 @@ Construit avec **MkDocs Material**. Les sources sont des fichiers Markdown ; le
|
||||||
| Ce que vous voulez faire | Ce que vous faites | Détail |
|
| 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/) |
|
| 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) |
|
| Écrire un article, travailler hors ligne | **Bifurquer**, cloner, une branche par sujet, pull request | [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 | idem |
|
| 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 |
|
| 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/) |
|
| 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/) |
|
||||||
|
|
|
||||||
|
|
@ -29,52 +29,26 @@ jour tout seul — en quelques secondes, sans intervention de personne.
|
||||||
installation et convient à une correction ponctuelle.
|
installation et convient à une correction ponctuelle.
|
||||||
|
|
||||||
Si vous rédigez régulièrement, la voie **depuis votre ordinateur** (dépôt cloné,
|
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 :
|
éditeur Markdown ou Obsidian) a sa propre page :
|
||||||
[Rédiger depuis son ordinateur](#rediger-depuis-son-ordinateur).
|
[Rédiger en ligne de commande](ligne-de-commande.md) ou
|
||||||
|
[Rédiger avec Obsidian](obsidian.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Étape 1 — Créer un compte AlpID
|
## Avant de commencer — avoir un compte
|
||||||
|
|
||||||
**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.
|
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).
|
||||||
|
|
||||||
1. Ouvrez votre navigateur et allez sur **[https://alpid.alpinux.org](https://alpid.alpinux.org)**.
|
!!! note "Déjà un compte sur le cloud ou le portail membres ?"
|
||||||
|
C'est le même : connectez-vous sur
|
||||||
2. Cliquez sur **« Créer un compte »** (ou *Register*).
|
[gitea.alpinux.org](https://gitea.alpinux.org) avec le bouton **« Se connecter avec
|
||||||
|
AlpID »**, votre compte sur la forge est créé au passage.
|
||||||
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
|
## Étape 1a — Modifier une page existante {#etape-modifier-une-page}
|
||||||
|
|
||||||
**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.
|
C'est la façon la plus simple de contribuer : corriger une faute, compléter une section, mettre à jour une information.
|
||||||
|
|
||||||
|
|
@ -132,7 +106,7 @@ C'est la façon la plus simple de contribuer : corriger une faute, compléter un
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Étape 3b — Proposer un nouvel article
|
## É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.
|
Vous avez rédigé un guide ou un compte-rendu et souhaitez l'ajouter au wiki.
|
||||||
|
|
||||||
|
|
@ -170,13 +144,13 @@ Avant de créer votre fichier, identifiez dans quelle section il a sa place :
|
||||||
Contenu...
|
Contenu...
|
||||||
```
|
```
|
||||||
|
|
||||||
5. Rédigez votre contenu (voir la section [Écrire en Markdown](#ecrire-en-markdown) plus bas).
|
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 »**.
|
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
|
## É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).
|
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).
|
||||||
|
|
||||||
|
|
@ -209,7 +183,7 @@ Après avoir cliqué sur « Proposer la modification » ou « Proposer le nouvea
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Étape 5 — La publication avec MkDocs
|
## É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.
|
Une fois votre pull request fusionnée, voici ce qui se passe dans les coulisses pour que votre article apparaisse sur le wiki.
|
||||||
|
|
||||||
|
|
@ -256,197 +230,32 @@ Si le build échoue — un lien mort, une page absente de la navigation — **ri
|
||||||
ligne** : le site reste dans son état précédent, et c'est la version fautive qui attend
|
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.
|
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.
|
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}
|
## Aller plus loin
|
||||||
|
|
||||||
Pour un article long, une série de corrections ou un travail hors connexion, il est plus
|
Une fois le mécanisme compris, trois pages pour approfondir :
|
||||||
confortable de travailler sur une copie locale du wiki.
|
|
||||||
|
|
||||||
La règle est la même que depuis le navigateur : **on ne modifie jamais `main`
|
<div class="grid cards" markdown>
|
||||||
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
|
- :material-language-markdown: **[Écrire en Markdown](markdown.md)**
|
||||||
|
|
||||||
Créez votre **bifurcation** (*fork*) du wiki : sur
|
Toute la syntaxe utilisable ici : titres, listes, liens, images, blocs de code,
|
||||||
[le dépôt](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki), bouton
|
alertes, tableaux, notes de bas de page — et ce qui n'est pas activé.
|
||||||
**Bifurcation** en haut à droite. Vous obtenez votre propre copie, dans laquelle vous
|
|
||||||
pouvez tout faire sans rien risquer.
|
|
||||||
|
|
||||||
Clonez ensuite **votre** copie, et gardez un lien vers le dépôt d'origine pour pouvoir
|
- :material-console: **[Rédiger en ligne de commande](ligne-de-commande.md)**
|
||||||
vous mettre à jour :
|
|
||||||
|
|
||||||
```bash
|
Bifurquer, cloner, travailler sur une branche, voir le rendu en local avec MkDocs,
|
||||||
git clone git@gitea.alpinux.org:VOTRE-COMPTE/alpinux-wiki.git
|
proposer une pull request, et se sortir d'un conflit.
|
||||||
cd alpinux-wiki
|
|
||||||
git remote add upstream git@gitea.alpinux.org:alpinux.cedrica5l/alpinux-wiki.git
|
|
||||||
```
|
|
||||||
|
|
||||||
Le dépôt contient les pages (`docs/`), les articles longs (`articles/`), les exemples de
|
- :material-notebook-edit: **[Rédiger avec Obsidian](obsidian.md)**
|
||||||
code cités dans le wiki (`code/`) et la configuration du site (`mkdocs.yml`).
|
|
||||||
|
|
||||||
### 2. Partir du wiki à jour, sur une branche
|
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.
|
||||||
|
|
||||||
Avant chaque nouveau sujet :
|
</div>
|
||||||
|
|
||||||
```bash
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Voir le rendu avant de proposer
|
|
||||||
|
|
||||||
```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. Pour s'assurer que
|
|
||||||
rien n'est cassé (lien mort, page absente de la navigation) :
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdocs build --strict -d /tmp/wiki-build
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Proposer la pull request
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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. La suite est
|
|
||||||
identique à l'[étape 4](#etape-4-ouvrir-la-pull-request) : un mainteneur relit, fusionne,
|
|
||||||
et la publication se fait toute seule.
|
|
||||||
|
|
||||||
!!! warning "Pourquoi ne pas pousser sur `main`"
|
|
||||||
Un commit qui arrive sur `main` est publié dans la minute, sans relecture et sans
|
|
||||||
retour en arrière possible autre qu'un nouveau commit. Même quand on en a le droit,
|
|
||||||
passer par une branche et une pull request donne trois choses : un regard extérieur,
|
|
||||||
une trace de la discussion, et la possibilité de laisser un texte reposer sans qu'il
|
|
||||||
soit en ligne.
|
|
||||||
|
|
||||||
Réservez le push direct aux urgences — une information fausse à retirer tout de suite.
|
|
||||||
|
|
||||||
### 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. Elle commite et pousse sur la branche
|
|
||||||
courante — donc :
|
|
||||||
|
|
||||||
- **placez-vous sur votre branche de travail** avant d'écrire (`git switch -c mon-sujet`,
|
|
||||||
ou le sélecteur de branche dans le panneau *Source Control* d'Obsidian) ;
|
|
||||||
- si vous activez la sauvegarde automatique, elle poussera vos brouillons au fil de la
|
|
||||||
frappe : c'est confortable sur une branche, et à proscrire sur `main`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## É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
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
### 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)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -455,3 +264,4 @@ Résultat :
|
||||||
- Posez votre question lors d'une **réunion Alpinux** (1er et 3e jeudis du mois)
|
- 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)
|
- 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
|
- 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)
|
||||||
173
docs/contribuer/ligne-de-commande.md
Normal file
173
docs/contribuer/ligne-de-commande.md
Normal file
|
|
@ -0,0 +1,173 @@
|
||||||
|
---
|
||||||
|
description: Contribuer au wiki Alpinux depuis son ordinateur avec git — bifurcation, branche, aperçu local avec MkDocs, pull request.
|
||||||
|
---
|
||||||
|
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
!!! note "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](../guides/git-alpinux.md#creer-son-compte).
|
||||||
|
Configurez au passage votre [clé SSH](../guides/git-alpinux.md#par-cle-ssh-recommande) :
|
||||||
|
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](https://gitea.alpinux.org/alpinux.cedrica5l/alpinux-wiki), 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 :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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 :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
|
||||||
|
```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, vérifiez que rien n'est cassé :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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.
|
||||||
|
|
||||||
|
!!! warning "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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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](index.md#etape-pull-request) : 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git switch main
|
||||||
|
git pull upstream main
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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 :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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 :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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](obsidian.md).
|
||||||
294
docs/contribuer/markdown.md
Normal file
294
docs/contribuer/markdown.md
Normal file
|
|
@ -0,0 +1,294 @@
|
||||||
|
---
|
||||||
|
description: Toute la syntaxe utilisable dans le wiki Alpinux — titres, listes, liens, images, code, alertes, tableaux, blocs dépliables, notes de bas de page.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Écrire en Markdown
|
||||||
|
|
||||||
|
Le **Markdown** est un langage de mise en forme qui s'écrit en texte brut : on indique la
|
||||||
|
structure avec quelques caractères, et le site s'occupe de l'apparence. Pas de police à
|
||||||
|
choisir, pas de taille de titre à régler — vous écrivez le fond, le thème fait la forme.
|
||||||
|
|
||||||
|
Cette page recense ce qui fonctionne **sur ce wiki**. Certaines syntaxes présentées
|
||||||
|
ailleurs sur Internet n'y sont pas activées : si un élément ne s'affiche pas comme prévu,
|
||||||
|
vérifiez d'abord qu'il figure ici.
|
||||||
|
|
||||||
|
!!! tip "Voir avant de publier"
|
||||||
|
L'éditeur de la forge a un onglet **Aperçu**. En local, `mkdocs serve` affiche le
|
||||||
|
rendu réel, thème compris — voir
|
||||||
|
[Rédiger en ligne de commande](ligne-de-commande.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## L'en-tête de la page
|
||||||
|
|
||||||
|
Chaque page commence idéalement par un bloc encadré de `---`, qui n'apparaît pas à
|
||||||
|
l'écran mais alimente les moteurs de recherche et les liens partagés :
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
description: Une phrase qui résume la page, affichée dans les résultats de recherche.
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
Puis vient le titre principal, et lui seul : le `#` de niveau 1 ne s'emploie **qu'une
|
||||||
|
fois par page**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Titres
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Titre principal (H1) — un seul par page
|
||||||
|
## Section (H2)
|
||||||
|
### Sous-section (H3)
|
||||||
|
#### Détail (H4)
|
||||||
|
```
|
||||||
|
|
||||||
|
Les titres construisent le sommaire affiché à droite de chaque page. Pas de saut de
|
||||||
|
niveau : après un `##`, on met un `###`, pas un `####`.
|
||||||
|
|
||||||
|
Pour fixer soi-même l'ancre d'un titre — utile quand on veut un lien stable malgré une
|
||||||
|
reformulation future :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Un titre un peu long {#ancre-courte}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mise en forme du texte
|
||||||
|
|
||||||
|
| Ce que vous écrivez | Résultat |
|
||||||
|
|---|---|
|
||||||
|
| `**important**` | **important** |
|
||||||
|
| `*nuance*` | *nuance* |
|
||||||
|
| `` `code` `` | `code` |
|
||||||
|
|
||||||
|
Le barré (`~~texte~~`) et le surligné (`==texte==`) ne sont pas activés sur ce wiki : ils
|
||||||
|
s'afficheraient tels quels, avec leurs tildes ou leurs signes égal.
|
||||||
|
|
||||||
|
Pour aller à la ligne sans changer de paragraphe, terminez la ligne par deux espaces.
|
||||||
|
Une ligne vide crée un nouveau paragraphe.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Listes
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
- Premier élément
|
||||||
|
- Deuxième élément
|
||||||
|
- Sous-élément (quatre espaces d'indentation)
|
||||||
|
|
||||||
|
1. Première étape
|
||||||
|
2. Deuxième étape
|
||||||
|
```
|
||||||
|
|
||||||
|
L'indentation d'une sous-liste est de **quatre espaces**. Avec deux, la liste est
|
||||||
|
ignorée : c'est l'erreur la plus fréquente.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Liens
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
[Texte du lien](https://example.org)
|
||||||
|
[Lien vers une autre page du wiki](../guides/linux-mint-depuis-windows.md)
|
||||||
|
[Lien vers une section précise](../guides/docker.md#installer-docker-engine)
|
||||||
|
```
|
||||||
|
|
||||||
|
Pour les pages du wiki, **liez le fichier `.md`, pas l'adresse du site** : MkDocs
|
||||||
|
transforme le chemin en URL et vous prévient si la page n'existe pas. Un lien écrit en
|
||||||
|
dur vers `https://wiki.alpinux.org/…` continuera de pointer dans le vide après un
|
||||||
|
renommage, sans que personne ne s'en aperçoive.
|
||||||
|
|
||||||
|
Les chemins sont relatifs à la page courante : `../guides/…` depuis une page de
|
||||||
|
`contribuer/`, `docker.md` depuis une autre page de `guides/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Images
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
Les images ne sont pas stockées dans le dépôt : elles sont hébergées sur
|
||||||
|
**static.alpinux.org** et appelées par leur adresse complète. Pour ajouter une image à un
|
||||||
|
article, demandez à un bénévole de la déposer.
|
||||||
|
|
||||||
|
Le texte alternatif n'est pas décoratif : il est lu par les lecteurs d'écran et s'affiche
|
||||||
|
si l'image ne charge pas. Décrivez ce qu'on y voit, pas « capture d'écran ».
|
||||||
|
|
||||||
|
Pour une largeur maîtrisée :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
{ width="200" }
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Citations
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
> Le logiciel libre, c'est une question de liberté, pas de prix.
|
||||||
|
```
|
||||||
|
|
||||||
|
> Le logiciel libre, c'est une question de liberté, pas de prix.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Blocs de code
|
||||||
|
|
||||||
|
Encadrez par trois accents graves, en précisant le langage — c'est lui qui déclenche la
|
||||||
|
coloration :
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
```bash
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install mon-paquet
|
||||||
|
```
|
||||||
|
````
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install mon-paquet
|
||||||
|
```
|
||||||
|
|
||||||
|
Langages courants : `bash`, `python`, `yaml`, `json`, `html`, `css`, `sql`, `ini`. Sans
|
||||||
|
langage, le bloc reste lisible mais sans couleurs — utile pour un affichage de terminal
|
||||||
|
ou un arbre de fichiers.
|
||||||
|
|
||||||
|
Pour attirer l'œil sur une ligne précise :
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
```bash hl_lines="2"
|
||||||
|
cd /etc/apache2
|
||||||
|
sudo nano apache2.conf
|
||||||
|
sudo systemctl reload apache2
|
||||||
|
```
|
||||||
|
````
|
||||||
|
|
||||||
|
```bash hl_lines="2"
|
||||||
|
cd /etc/apache2
|
||||||
|
sudo nano apache2.conf
|
||||||
|
sudo systemctl reload apache2
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! warning "Commandes à recopier"
|
||||||
|
Dans un bloc destiné à être recopié, ne mettez pas le `$` du prompt : le lecteur qui
|
||||||
|
copie la ligne collerait un `$` qui fait échouer la commande.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Alertes
|
||||||
|
|
||||||
|
Les alertes (*admonitions*) mettent en valeur une remarque. Syntaxe : `!!!`, le type, et
|
||||||
|
un titre entre guillemets — facultatif.
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
!!! note "Bon à savoir"
|
||||||
|
Le contenu est indenté de quatre espaces.
|
||||||
|
|
||||||
|
!!! tip "Astuce"
|
||||||
|
Un raccourci qui fait gagner du temps.
|
||||||
|
|
||||||
|
!!! warning "Attention"
|
||||||
|
Un piège fréquent, une manipulation à ne pas rater.
|
||||||
|
|
||||||
|
!!! danger "Danger"
|
||||||
|
Une action destructrice : effacer un disque, supprimer des données.
|
||||||
|
|
||||||
|
!!! success "C'est bon"
|
||||||
|
Confirmation que tout s'est bien passé.
|
||||||
|
|
||||||
|
!!! info "Information"
|
||||||
|
Un complément, une précision de contexte.
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note "Bon à savoir"
|
||||||
|
Le contenu est indenté de quatre espaces.
|
||||||
|
|
||||||
|
!!! warning "Attention"
|
||||||
|
Un piège fréquent, une manipulation à ne pas rater.
|
||||||
|
|
||||||
|
### Blocs dépliables
|
||||||
|
|
||||||
|
En remplaçant `!!!` par `???`, le bloc est replié ; avec `???+`, il est déplié au
|
||||||
|
chargement. Pratique pour une explication longue qui ne doit pas couper la lecture :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
??? info "Pourquoi cette commande fonctionne"
|
||||||
|
L'explication détaillée, que le lecteur ouvre s'il le souhaite.
|
||||||
|
```
|
||||||
|
|
||||||
|
??? info "Pourquoi cette commande fonctionne"
|
||||||
|
L'explication détaillée, que le lecteur ouvre s'il le souhaite.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tableaux
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
| Colonne 1 | Colonne 2 |
|
||||||
|
|---|---|
|
||||||
|
| Valeur A | Valeur B |
|
||||||
|
```
|
||||||
|
|
||||||
|
Les tirets de la deuxième ligne séparent l'en-tête du corps ; leur nombre n'a pas
|
||||||
|
d'importance. Pour aligner une colonne, placez un `:` du côté voulu : `|---:|` à droite,
|
||||||
|
`|:---:|` au centre.
|
||||||
|
|
||||||
|
Un tableau large devient illisible sur téléphone : au-delà de quatre ou cinq colonnes,
|
||||||
|
préférez une liste.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes de bas de page
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Le noyau Linux est publié sous licence GPLv2[^1].
|
||||||
|
|
||||||
|
[^1]: GNU General Public License, version 2.
|
||||||
|
```
|
||||||
|
|
||||||
|
Le noyau Linux est publié sous licence GPLv2[^1].
|
||||||
|
|
||||||
|
[^1]: GNU General Public License, version 2.
|
||||||
|
|
||||||
|
La note s'affiche en bas de page, quel que soit l'endroit où vous l'écrivez.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Boutons
|
||||||
|
|
||||||
|
Avec un attribut `{ .md-button }`, un lien devient un bouton :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
[Télécharger Linux Mint](https://linuxmint.com/download.php){ .md-button }
|
||||||
|
```
|
||||||
|
|
||||||
|
[Télécharger Linux Mint](https://linuxmint.com/download.php){ .md-button }
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conseils de rédaction
|
||||||
|
|
||||||
|
Au-delà de la syntaxe, ce qui rend une page utile :
|
||||||
|
|
||||||
|
- **Une page, un sujet.** Si le titre contient « et », il y a peut-être deux pages.
|
||||||
|
- **Écrivez pour qui ne sait pas.** Ce qui vous paraît évident est précisément ce que le
|
||||||
|
lecteur cherche. Indiquez où cliquer, ce qui doit s'afficher, comment vérifier que
|
||||||
|
l'étape a réussi.
|
||||||
|
- **Datez ce qui vieillit.** Une version de logiciel, une capture d'écran, une adresse :
|
||||||
|
précisez à quelle date c'était vrai.
|
||||||
|
- **Préférez la phrase courte.** Un guide se lit un ordinateur en panne sur les genoux.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pour aller plus loin
|
||||||
|
|
||||||
|
- [Éditeur Markdown en ligne, avec aperçu](https://markdownlivepreview.com/)
|
||||||
|
- [Référence Markdown complète](https://www.markdownguide.org/basic-syntax/)
|
||||||
|
- [Documentation du thème Material](https://squidfunk.github.io/mkdocs-material/reference/) —
|
||||||
|
toutes les possibilités du thème ; certaines demandent d'activer une extension dans
|
||||||
|
`mkdocs.yml`, à discuter avec les mainteneurs.
|
||||||
143
docs/contribuer/obsidian.md
Normal file
143
docs/contribuer/obsidian.md
Normal file
|
|
@ -0,0 +1,143 @@
|
||||||
|
---
|
||||||
|
description: Rédiger les pages du wiki Alpinux dans Obsidian — ouvrir le coffre, régler les liens, travailler sur une branche avec Obsidian Git.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Rédiger avec Obsidian
|
||||||
|
|
||||||
|
[Obsidian](https://obsidian.md) est un éditeur de notes en Markdown, gratuit et
|
||||||
|
disponible sur Linux, Windows, macOS et mobile. Il travaille directement sur des fichiers
|
||||||
|
`.md` posés dans un dossier — ce qui tombe bien : le wiki en est un.
|
||||||
|
|
||||||
|
C'est la façon la plus confortable de rédiger un article long : volet d'aperçu,
|
||||||
|
navigation entre les pages, recherche instantanée, et aucune ligne de commande pour
|
||||||
|
écrire.
|
||||||
|
|
||||||
|
!!! note "À faire une fois"
|
||||||
|
Cette page suppose que le wiki est déjà cloné sur votre machine. Si ce n'est pas le
|
||||||
|
cas, faites d'abord la bifurcation et le clone décrits dans
|
||||||
|
[Rédiger en ligne de commande](ligne-de-commande.md#1-bifurquer-puis-cloner).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ouvrir le wiki comme coffre
|
||||||
|
|
||||||
|
Au lancement, **Ouvrir un dossier comme coffre** (*Open folder as vault*), puis
|
||||||
|
sélectionnez le dossier cloné.
|
||||||
|
|
||||||
|
Les réglages et extensions sont déjà dans le dépôt : ils s'appliquent à l'ouverture, vous
|
||||||
|
n'avez rien à installer. Obsidian demandera simplement d'autoriser les extensions
|
||||||
|
tierces, puisqu'elles proviennent du coffre.
|
||||||
|
|
||||||
|
Deux extensions sont fournies :
|
||||||
|
|
||||||
|
| Extension | Rôle |
|
||||||
|
|---|---|
|
||||||
|
| **Obsidian Git** | versionner et publier sans quitter l'éditeur |
|
||||||
|
| **Linter** | uniformiser la mise en forme à l'enregistrement |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Le réglage qui compte : les liens
|
||||||
|
|
||||||
|
Par défaut, Obsidian crée des liens internes de la forme `[[Nom de la page]]`. **MkDocs
|
||||||
|
ne les comprend pas** : ils s'afficheraient tels quels, crochets compris, sur le site
|
||||||
|
publié.
|
||||||
|
|
||||||
|
Le coffre est donc configuré pour produire des liens Markdown classiques. Vérifiez dans
|
||||||
|
**Paramètres → Fichiers et liens** :
|
||||||
|
|
||||||
|
| Réglage | Valeur attendue |
|
||||||
|
|---|---|
|
||||||
|
| Utiliser les liens `[[Wikilink]]` | **désactivé** |
|
||||||
|
| Type de lien nouveau | **Chemin relatif au fichier** |
|
||||||
|
| Mettre à jour les liens internes automatiquement | activé |
|
||||||
|
|
||||||
|
Avec ces réglages, déplacer ou renommer une page depuis Obsidian corrige les liens des
|
||||||
|
autres pages — un confort que l'édition dans le navigateur n'offre pas.
|
||||||
|
|
||||||
|
!!! warning "Les liens doivent pointer vers le fichier `.md`"
|
||||||
|
`[le guide Docker](../guides/docker.md)` et non `https://wiki.alpinux.org/guides/docker/`.
|
||||||
|
MkDocs convertit le chemin en URL et signale les liens morts au moment du build.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ce qu'Obsidian n'affiche pas comme le site
|
||||||
|
|
||||||
|
L'aperçu d'Obsidian n'est pas celui du wiki. Certaines syntaxes propres au thème du site
|
||||||
|
n'y ressemblent à rien :
|
||||||
|
|
||||||
|
- les **alertes** (`!!! note`) apparaissent comme du texte indenté ;
|
||||||
|
- les **blocs dépliables** (`??? info`) de même ;
|
||||||
|
- les **boutons** (`{ .md-button }`) restent des liens ordinaires ;
|
||||||
|
- la **coloration** des blocs de code diffère.
|
||||||
|
|
||||||
|
Ce n'est pas un problème tant que la syntaxe est correcte — voir
|
||||||
|
[Écrire en Markdown](markdown.md). Pour voir le rendu réel avant de proposer une page,
|
||||||
|
lancez `mkdocs serve` en parallèle.
|
||||||
|
|
||||||
|
À l'inverse, certaines fonctions d'Obsidian n'existent pas sur le wiki : les liens
|
||||||
|
`[[…]]`, les blocs de transclusion `![[…]]`, les tags `#sujet` et les propriétés de note.
|
||||||
|
Évitez-les dans `docs/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Travailler sur une branche
|
||||||
|
|
||||||
|
C'est le point à retenir : **Obsidian Git commite et pousse sur la branche courante**.
|
||||||
|
Si cette branche est `main`, chaque sauvegarde publie en ligne, sans relecture.
|
||||||
|
|
||||||
|
Avant d'écrire, placez-vous donc sur votre branche de travail. Deux façons :
|
||||||
|
|
||||||
|
- dans Obsidian, ouvrez le panneau **Source Control** (icône de branche dans la barre
|
||||||
|
latérale), puis le sélecteur de branche en bas ;
|
||||||
|
- ou en ligne de commande dans le dossier du coffre :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git switch main
|
||||||
|
git pull upstream main
|
||||||
|
git switch -c mon-article
|
||||||
|
```
|
||||||
|
|
||||||
|
Le nom de la branche courante est affiché dans la barre d'état d'Obsidian, en bas de la
|
||||||
|
fenêtre. Prenez l'habitude d'y jeter un œil avant de commencer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Publier son travail
|
||||||
|
|
||||||
|
Dans le panneau **Source Control** :
|
||||||
|
|
||||||
|
1. les fichiers modifiés apparaissent ; le **+** les met en attente (*stage*) ;
|
||||||
|
2. saisissez un message décrivant ce qui change, puis **Commit** ;
|
||||||
|
3. **Push** envoie la branche sur votre bifurcation.
|
||||||
|
|
||||||
|
Rendez-vous ensuite sur la forge pour ouvrir la pull request — voir
|
||||||
|
[l'étape 2 du guide de contribution](index.md#etape-pull-request).
|
||||||
|
|
||||||
|
### La sauvegarde automatique
|
||||||
|
|
||||||
|
Obsidian Git peut committer et pousser tout seul, à intervalle régulier. C'est pratique
|
||||||
|
sur une branche de travail : votre brouillon est sauvegardé hors de votre machine au fil
|
||||||
|
de la frappe.
|
||||||
|
|
||||||
|
!!! danger "Jamais en sauvegarde automatique sur `main`"
|
||||||
|
Sur `main`, chaque sauvegarde automatique est une publication immédiate : une phrase
|
||||||
|
à moitié écrite peut se retrouver en ligne. Si vous activez cette option, vérifiez
|
||||||
|
systématiquement votre branche avant d'ouvrir le coffre.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Images et pièces jointes
|
||||||
|
|
||||||
|
Obsidian propose de copier les images collées dans un dossier du coffre. Ne l'utilisez
|
||||||
|
pas pour le wiki : les images ne sont pas versionnées, elles sont hébergées sur
|
||||||
|
**static.alpinux.org** et appelées par leur adresse complète. Demandez à un bénévole de
|
||||||
|
déposer votre capture d'écran, et insérez le lien qu'il vous donne.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## En cas de doute
|
||||||
|
|
||||||
|
Le coffre, c'est le dépôt : tout ce qui est possible en ligne de commande l'est ici, et
|
||||||
|
inversement. Si Obsidian Git se bloque — conflit, branche divergente — la réponse se
|
||||||
|
trouve dans [Rédiger en ligne de commande](ligne-de-commande.md#quand-ca-coince).
|
||||||
174
docs/guides/git-alpinux.md
Normal file
174
docs/guides/git-alpinux.md
Normal file
|
|
@ -0,0 +1,174 @@
|
||||||
|
---
|
||||||
|
description: Créer son compte sur le Git d'Alpinux (Forgejo), y héberger ses propres dépôts, et y envoyer son travail en SSH ou en HTTPS.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Le Git d'Alpinux
|
||||||
|
|
||||||
|
L'association héberge sa propre **forge logicielle** à l'adresse
|
||||||
|
**[gitea.alpinux.org](https://gitea.alpinux.org)**. C'est l'équivalent associatif de
|
||||||
|
GitHub ou GitLab : un endroit où déposer du code, le versionner, le partager, suivre des
|
||||||
|
tickets.
|
||||||
|
|
||||||
|
Elle est ouverte aux membres pour leurs **projets personnels** : un script bricolé un
|
||||||
|
dimanche, la configuration de sa machine, les sources d'un site, des notes — tout ce qui
|
||||||
|
gagne à être versionné et à ne pas vivre uniquement sur un disque dur.
|
||||||
|
|
||||||
|
!!! info "Gitea ou Forgejo ?"
|
||||||
|
L'adresse dit `gitea`, la page affiche *Forgejo*. Forgejo est la suite du projet
|
||||||
|
Gitea, dont il est issu ; l'adresse historique a été conservée. Si une documentation
|
||||||
|
trouvée sur Internet parle de Gitea, elle s'applique presque toujours telle quelle.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Créer son compte
|
||||||
|
|
||||||
|
**Il n'y a pas d'inscription directe sur la forge** : le formulaire est désactivé et
|
||||||
|
affiche *« Registration is disabled »*. C'est normal. Tous les comptes passent par
|
||||||
|
**AlpID**, l'authentification unique de l'association — un seul identifiant pour la forge,
|
||||||
|
le wiki, le cloud et les autres services.
|
||||||
|
|
||||||
|
### 1. Créer son compte AlpID
|
||||||
|
|
||||||
|
1. 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** : simple, sans accent ni espace (ex. `prenom.nom`) — il
|
||||||
|
servira aussi d'adresse à vos dépôts ;
|
||||||
|
- **Adresse e-mail** : une adresse que vous consultez régulièrement ;
|
||||||
|
- **Mot de passe** : au moins 8 caractères.
|
||||||
|
|
||||||
|
4. Validez, puis cliquez sur le lien de confirmation reçu par courriel.
|
||||||
|
|
||||||
|
!!! note "Déjà membre ?"
|
||||||
|
Si vous avez déjà un compte sur le portail membres ou le cloud de l'association, c'est
|
||||||
|
le même : inutile d'en créer un second, passez directement à l'étape suivante.
|
||||||
|
|
||||||
|
### 2. Première connexion à la forge
|
||||||
|
|
||||||
|
1. Allez sur **[https://gitea.alpinux.org](https://gitea.alpinux.org)**.
|
||||||
|
|
||||||
|
2. Cliquez sur **« Connexion »** en haut à droite.
|
||||||
|
|
||||||
|
3. Choisissez **« Se connecter avec AlpID »**.
|
||||||
|
|
||||||
|
4. AlpID confirme votre identité et vous ramène sur la forge.
|
||||||
|
|
||||||
|
Votre compte y est créé automatiquement à cette première connexion : vous avez maintenant
|
||||||
|
votre espace, à l'adresse `gitea.alpinux.org/votre-nom-dutilisateur`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Créer son premier dépôt
|
||||||
|
|
||||||
|
1. En haut à droite, cliquez sur **+** puis **Nouveau dépôt**.
|
||||||
|
|
||||||
|
2. Remplissez :
|
||||||
|
|
||||||
|
| Champ | Conseil |
|
||||||
|
|---|---|
|
||||||
|
| **Nom du dépôt** | court, en minuscules, sans espace — `mes-scripts`, `config-i3` |
|
||||||
|
| **Description** | une phrase : dans six mois, elle vous rappellera de quoi il s'agit |
|
||||||
|
| **Visibilité** | **Privé** dans le doute : un dépôt se rend public plus tard, l'inverse n'efface pas ce qui a été vu |
|
||||||
|
| **Initialiser avec un README** | oui — un dépôt vide est pénible à cloner |
|
||||||
|
| **.gitignore** | choisissez le modèle correspondant à votre langage |
|
||||||
|
| **Licence** | pour un projet destiné à être partagé, la GPL ou la MIT selon vos préférences |
|
||||||
|
|
||||||
|
3. **Créer le dépôt**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Y envoyer son travail
|
||||||
|
|
||||||
|
Deux façons de vous authentifier. La clé SSH est à configurer une fois pour toutes ; le
|
||||||
|
jeton HTTPS dépanne partout.
|
||||||
|
|
||||||
|
### Par clé SSH (recommandé)
|
||||||
|
|
||||||
|
Générez une clé si vous n'en avez pas déjà une :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh-keygen -t ed25519 -C "prenom@ma-machine"
|
||||||
|
```
|
||||||
|
|
||||||
|
Acceptez le chemin proposé et choisissez une phrase de passe. Affichez la partie
|
||||||
|
**publique** — celle qui se termine par `.pub`, la seule qui se partage :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat ~/.ssh/id_ed25519.pub
|
||||||
|
```
|
||||||
|
|
||||||
|
Copiez la ligne entière, puis sur la forge : votre avatar → **Paramètres** → **Clés SSH /
|
||||||
|
GPG** → **Ajouter une clé**. Donnez-lui un nom qui identifie la machine (`portable`,
|
||||||
|
`tour-du-salon`), collez, validez.
|
||||||
|
|
||||||
|
Vérifiez :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh -T git@gitea.alpinux.org
|
||||||
|
```
|
||||||
|
|
||||||
|
La forge répond `Hi there, votre-nom !… Forgejo does not provide shell access` — c'est le
|
||||||
|
message attendu : l'authentification fonctionne, et la forge ne donne pas d'accès au
|
||||||
|
shell, ce qui est voulu.
|
||||||
|
|
||||||
|
Vous pouvez alors cloner et pousser :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone git@gitea.alpinux.org:votre-nom/mes-scripts.git
|
||||||
|
```
|
||||||
|
|
||||||
|
### Par HTTPS avec un jeton
|
||||||
|
|
||||||
|
Utile depuis une machine où vous ne voulez pas déposer de clé, ou pour un script.
|
||||||
|
|
||||||
|
1. Avatar → **Paramètres** → **Applications** → **Générer un nouveau jeton**.
|
||||||
|
|
||||||
|
2. Donnez-lui un nom parlant et **cochez seulement les portées nécessaires** — pour
|
||||||
|
pousser du code, `repository` suffit.
|
||||||
|
|
||||||
|
3. Copiez le jeton : **il ne sera plus affiché ensuite**.
|
||||||
|
|
||||||
|
Le jeton remplace le mot de passe :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://gitea.alpinux.org/votre-nom/mes-scripts.git
|
||||||
|
# utilisateur : votre nom d'utilisateur
|
||||||
|
# mot de passe : le jeton
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! danger "Un jeton est un mot de passe"
|
||||||
|
Ne le placez jamais dans un fichier versionné, ni dans l'URL d'un dépôt que vous
|
||||||
|
partagez. S'il vous échappe, révoquez-le depuis la même page : il cesse
|
||||||
|
immédiatement de fonctionner.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quelques repères
|
||||||
|
|
||||||
|
**Ce qui n'a pas sa place dans un dépôt** : mots de passe, jetons, clés privées,
|
||||||
|
fichiers `.env`. Une fois poussé, un secret reste dans l'historique même après
|
||||||
|
suppression du fichier — il faut le considérer comme compromis et le changer. Les gros
|
||||||
|
fichiers binaires (vidéos, machines virtuelles) n'y ont pas leur place non plus : git
|
||||||
|
conserve chaque version, le dépôt gonfle et ne dégonfle jamais.
|
||||||
|
|
||||||
|
**Gardez une copie ailleurs.** La forge est un service rendu par des bénévoles, pas un
|
||||||
|
service de sauvegarde. Un dépôt cloné sur votre machine *est* une copie complète de
|
||||||
|
l'historique : c'est déjà une bonne assurance.
|
||||||
|
|
||||||
|
**Public ou privé ?** Un dépôt public est lisible par tout Internet, moteurs de recherche
|
||||||
|
compris. Privé par défaut, publié quand c'est prêt : c'est le sens de la marche.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Et pour le wiki ?
|
||||||
|
|
||||||
|
Le wiki que vous lisez est lui-même hébergé sur cette forge. Pour y contribuer — corriger
|
||||||
|
une faute, proposer un article — la marche à suivre est décrite dans
|
||||||
|
[Contribuer au wiki](../contribuer/index.md).
|
||||||
|
|
||||||
|
## Une question ?
|
||||||
|
|
||||||
|
Posez-la lors d'une [rencontre Alpinux](../alpinux/evenements.md) : la forge est un
|
||||||
|
service de l'association, les bénévoles sont les mieux placés pour vous aider à démarrer.
|
||||||
|
|
@ -55,7 +55,7 @@ Ici vous trouverez des guides pratiques, des comptes-rendus de présentations et
|
||||||
Ce wiki est collaboratif : tout membre peut proposer une modification ou un nouvel article.
|
Ce wiki est collaboratif : tout membre peut proposer une modification ou un nouvel article.
|
||||||
Les pages sont écrites en [Markdown](https://www.markdownguide.org/basic-syntax/) et hébergées sur notre [Gitea](https://gitea.alpinux.org).
|
Les pages sont écrites en [Markdown](https://www.markdownguide.org/basic-syntax/) et hébergées sur notre [Gitea](https://gitea.alpinux.org).
|
||||||
|
|
||||||
[:octicons-arrow-right-24: Guide de contribution pas à pas](contribuer.md)
|
[:octicons-arrow-right-24: Guide de contribution pas à pas](contribuer/index.md)
|
||||||
|
|
||||||
!!! tip "Première visite ?"
|
!!! tip "Première visite ?"
|
||||||
Commencez par la [FAQ](alpinux/faq.md) ou le guide [Installer Linux Mint depuis Windows](guides/linux-mint-depuis-windows.md).
|
Commencez par la [FAQ](alpinux/faq.md) ou le guide [Installer Linux Mint depuis Windows](guides/linux-mint-depuis-windows.md).
|
||||||
|
|
|
||||||
|
|
@ -62,7 +62,11 @@ copyright: "© Alpinux — LUG de Savoie | <a href='https://portail.alpinux.org'
|
||||||
|
|
||||||
nav:
|
nav:
|
||||||
- Accueil: index.md
|
- Accueil: index.md
|
||||||
- Contribuer: contribuer.md
|
- Contribuer:
|
||||||
|
- contribuer/index.md
|
||||||
|
- Écrire en Markdown: contribuer/markdown.md
|
||||||
|
- Rédiger en ligne de commande: contribuer/ligne-de-commande.md
|
||||||
|
- Rédiger avec Obsidian: contribuer/obsidian.md
|
||||||
- Alpinux:
|
- Alpinux:
|
||||||
- alpinux/index.md
|
- alpinux/index.md
|
||||||
- FAQ: alpinux/faq.md
|
- FAQ: alpinux/faq.md
|
||||||
|
|
@ -80,6 +84,7 @@ nav:
|
||||||
- guides/linux-mint-parametres.md
|
- guides/linux-mint-parametres.md
|
||||||
- guides/linux-mint-trousse.md
|
- guides/linux-mint-trousse.md
|
||||||
- guides/utiliser-linux-mint.md
|
- guides/utiliser-linux-mint.md
|
||||||
|
- guides/git-alpinux.md
|
||||||
- guides/docker.md
|
- guides/docker.md
|
||||||
- guides/chiffrement.md
|
- guides/chiffrement.md
|
||||||
- guides/sauvegardes.md
|
- guides/sauvegardes.md
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue