alpinux-wiki/docs/contribuer/obsidian.md

---
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 votre coffre est un clone du dépôt du wiki et que cette branche est `main`, chaque
sauvegarde publie en ligne, sans relecture — c'est la situation des mainteneurs. Depuis
une bifurcation, le risque est moindre : vous ne poussez que chez vous. Dans les deux
cas, la règle ne change pas — **une branche par sujet, puis une pull request**.

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).