Rédiger avec Obsidian¶

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

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

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.

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

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 :

les fichiers modifiés apparaissent ; le + les met en attente (stage) ;
saisissez un message décrivant ce qui change, puis Commit ;
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.

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.

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.