diff --git a/.obsidian/app.json b/.obsidian/app.json index 148ad9a..c600495 100644 --- a/.obsidian/app.json +++ b/.obsidian/app.json @@ -5,5 +5,7 @@ "margin": "0", "downscalePercent": 100 }, - "alwaysUpdateLinks": true -} \ No newline at end of file + "alwaysUpdateLinks": true, + "useMarkdownLinks": true, + "newLinkFormat": "relative" +} diff --git a/README.md b/README.md index 5be747b..9c3399b 100644 --- a/README.md +++ b/README.md @@ -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 | |---|---|---| | 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 | | 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/) | diff --git a/docs/contribuer.md b/docs/contribuer/index.md similarity index 55% rename from docs/contribuer.md rename to docs/contribuer/index.md index eb9a611..04006da 100644 --- a/docs/contribuer.md +++ b/docs/contribuer/index.md @@ -29,52 +29,26 @@ jour tout seul — en quelques secondes, sans intervention de personne. 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). + é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). --- -## É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)**. - -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. +!!! 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 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 +## É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. @@ -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. @@ -170,13 +144,13 @@ Avant de créer votre fichier, identifiez dans quelle section il a sa place : 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 »**. --- -## É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). @@ -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. @@ -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 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 -confortable de travailler sur une copie locale du wiki. +Une fois le mécanisme compris, trois pages pour approfondir : -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 +- :material-language-markdown: **[Écrire en Markdown](markdown.md)** -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. + 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é. -Clonez ensuite **votre** copie, et gardez un lien vers le dépôt d'origine pour pouvoir -vous mettre à jour : +- :material-console: **[Rédiger en ligne de commande](ligne-de-commande.md)** -```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 -``` + Bifurquer, cloner, travailler sur une branche, voir le rendu en local avec MkDocs, + proposer une pull request, et se sortir d'un conflit. -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`). +- :material-notebook-edit: **[Rédiger avec Obsidian](obsidian.md)** -### 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 : - -```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 -![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) +
--- @@ -455,3 +264,4 @@ Résultat : - 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) diff --git a/docs/contribuer/ligne-de-commande.md b/docs/contribuer/ligne-de-commande.md new file mode 100644 index 0000000..a0e5276 --- /dev/null +++ b/docs/contribuer/ligne-de-commande.md @@ -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). diff --git a/docs/contribuer/markdown.md b/docs/contribuer/markdown.md new file mode 100644 index 0000000..901a11a --- /dev/null +++ b/docs/contribuer/markdown.md @@ -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 +![Texte alternatif décrivant l'image](https://static.alpinux.org/wiki/exemple.png) +``` + +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 +![Logo Alpinux](https://static.alpinux.org/logo/alpinux-logo.png){ 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. diff --git a/docs/contribuer/obsidian.md b/docs/contribuer/obsidian.md new file mode 100644 index 0000000..e115cce --- /dev/null +++ b/docs/contribuer/obsidian.md @@ -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). diff --git a/docs/guides/git-alpinux.md b/docs/guides/git-alpinux.md new file mode 100644 index 0000000..c0d7502 --- /dev/null +++ b/docs/guides/git-alpinux.md @@ -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. diff --git a/docs/index.md b/docs/index.md index 4539132..f0cae9b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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. 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 ?" Commencez par la [FAQ](alpinux/faq.md) ou le guide [Installer Linux Mint depuis Windows](guides/linux-mint-depuis-windows.md). diff --git a/mkdocs.yml b/mkdocs.yml index 73f2906..d493a1d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,7 +62,11 @@ copyright: "© Alpinux — LUG de Savoie |