🧠 Obsidian · & le vault autoportant

Chapitre 01
Le vault : un dossier de fichiers, rien de plus

Objectifs du chapitre

1. Un éditeur, pas une application

La plupart des outils de prise de notes stockent tes notes chez eux : une base de données interne, un format binaire, un serveur. Tu écris dans l'application, et récupérer tes données demande une fonction d'export.

Obsidian fait l'inverse. Tu lui désignes un dossier de ton disque, et il édite les fichiers qui s'y trouvent. Une note est un fichier .md. Un dossier de notes est un dossier. Il n'y a pas de couche cachée entre les deux.

$ ls -A ~/vault
.gitattributes  10-journal/  30-projets/  90-meta/   README.md
.gitignore      20-notes/    80-assets/   99-archive/
.obsidian/      00-inbox/

Rien dans cette liste n'appartient à Obsidian, sauf .obsidian/. Le reste, ce sont tes fichiers, lisibles par n'importe quoi.

Le test qui résume tout : désinstalle Obsidian, et demande-toi ce que tu as perdu. Avec un vault, la réponse est « un éditeur confortable ». Tes notes sont toujours là, en texte, lisibles dans n'importe quel éditeur, indexables par grep, versionnables par git.

Cette propriété n'est pas un détail de confort, c'est le socle de tout le cours. Parce que les notes sont des fichiers, on peut les mettre sous git. Parce qu'elles sont en texte, on peut les valider par un script. Et parce que la configuration d'Obsidian est aussi faite de fichiers, on pourra la décrire, la vérifier et la reconstruire — c'est l'objet de la partie II.

2. Ouvrir un dossier comme vault

Au premier lancement, Obsidian propose de créer un vault ou d'en ouvrir un. « Ouvrir un dossier comme vault » prend n'importe quel dossier existant : s'il contient déjà des .md, ils apparaissent immédiatement dans l'explorateur de fichiers de la barre latérale.

Tu peux avoir plusieurs vaults et passer de l'un à l'autre. Chacun est indépendant : ses plugins, ses réglages, son thème. C'est le principal levier de cloisonnement d'Obsidian — un vault professionnel et un vault personnel ne partagent rien, pas même la liste des plugins installés.

Un vault dans un dossier synchronisé par un service tiers (OneDrive, Dropbox, Google Drive) est une source classique de corruption. Ces services synchronisent fichier par fichier, sans transaction : ils peuvent capturer un .obsidian/ à moitié écrit, ou faire diverger deux machines sur le même fichier. Si en plus tu versionnes le vault avec git, le service touchera à .git/ en arrière-plan — et là, la corruption n'est plus hypothétique.

Choisis un mécanisme de synchronisation et un seul. Le chapitre 7 traite du choix git.

3. Anatomie d'un vault

Trois familles de contenu cohabitent dans le dossier.

Les notes

Des fichiers .md, en markdown, avec parfois un bloc de métadonnées en tête (le front-matter, chapitre 3). Le nom du fichier sert de titre et d'identifiant de lien.

Les pièces jointes

Images, PDF, tout ce que tu glisses dans une note. Obsidian les copie dans le vault et insère un lien. Le dossier de destination se règle une fois pour toutes — dans le vault de référence de ce cours, c'est 80-assets/. Sans ce réglage, les pièces jointes atterrissent à côté de la note qui les référence et l'arborescence se salit vite.

La configuration

Tout est dans .obsidian/, à la racine du vault. C'est un dossier caché, mais c'est du JSON parfaitement lisible :

$ ls -1 ~/vault/.obsidian
app.json
appearance.json
community-plugins.json
core-plugins.json
daily-notes.json
hotkeys.json
plugins/
templates.json
types.json
workspace.json

Chacun a un rôle précis. Les connaître te servira dès le chapitre 4, et deviendra indispensable en partie II.

FichierContenuNature
core-plugins.jsonQuels plugins intégrés sont actifs ({"daily-notes": true, "publish": false, …})configuration
community-plugins.jsonLa liste des plugins tiers activés, un tableau d'identifiantsconfiguration
appearance.jsonThème, taille de police, thème CSS éventuelconfiguration
hotkeys.jsonLes raccourcis que tu as personnalisés — pas les raccourcis par défautconfiguration
app.json, types.jsonPréférences de l'éditeur, types des propriétés de front-matterconfiguration
daily-notes.json, templates.jsonLes réglages des plugins intégrés du même nomconfiguration
plugins/<id>/Un dossier par plugin tiers : main.js, manifest.json, parfois styles.css, et data.json pour ses réglagescode + configuration
themes/, snippets/Thèmes communautaires et feuilles CSS que tu ajoutes toi-mêmetes fichiers
workspace.jsonQuels panneaux sont ouverts, à quelle taille, quel onglet est actifétat

Retiens la distinction de la dernière colonne, elle structure toute la partie II. La configuration décrit des décisions : tu veux ce plugin, ce thème, ce raccourci. L'état décrit une situation passagère : quels panneaux étaient ouverts hier soir.

La configuration mérite d'être décrite, versionnée et rejouée. L'état, non — le versionner ne produit que du bruit et des conflits.

4. Le fichier n'est pas tout à fait la note

Une nuance qui surprend au début : Obsidian raisonne en notes, pas en chemins. Un lien s'écrit [[Rétraction de bras]], sans dossier ni extension. Obsidian résout ce nom dans tout le vault.

Conséquences directes :

Explorateur de fichiers dans la barre latérale gauche pour voir l'arborescence réelle, recherche rapide avec Ctrl+O pour ouvrir une note par son nom sans savoir où elle est. Le second est le vrai mode de navigation ; le premier sert surtout à ranger.

5. Ce que ça permet immédiatement

Parce que tout est fichier, les outils que tu connais déjà s'appliquent sans adaptateur :

$ grep -rl "PROFINET" ~/vault/20-notes | head -3
/home/moi/vault/20-notes/profinet-rt.md
/home/moi/vault/20-notes/topologie-anneau-mrp.md
/home/moi/vault/20-notes/temps-de-cycle.md

$ cd ~/vault && git log --oneline -3
158993d fix: active le declenchement Templater sur creation
8d2d676 feat: reglages de plugins geres a la carte
adbf23c fix: signale les liaisons multiples

Sauvegarde, historique, recherche, scripts de validation, génération de documents : tout est accessible sans qu'Obsidian soit lancé, et sans API.

6. La faille

Reprends le tableau de la section 3 et pose-toi la question du versionnement.

Tes notes sous git : évident, c'est du texte. Mais .obsidian/ ? Il contient à la fois de la configuration qui mérite d'être conservée, de l'état qui produirait des conflits à chaque fermeture, et des binaires de plugins — plusieurs mégaoctets de JavaScript compilé qu'un plugin réécrit à chaque mise à jour.

Le versionner en entier pollue l'historique et fait diverger deux machines sur workspace.json. Ne pas le versionner du tout, c'est perdre la configuration au premier changement de machine. Et le documenter dans un README, c'est une documentation qui ment dès la première modification faite à la souris.

C'est exactement le problème que résout la partie II : un fichier manifeste lisible qui décrit la configuration voulue, un .obsidian/ traité comme jetable et régénéré à la demande, et un outil qui vérifie que les deux concordent. Garde la distinction configuration/état en tête, tout en découle.

Récapitulatif

Exercices

Exercice 1 — Classer les fichiers de configuration

Sans regarder le tableau : parmi workspace.json, community-plugins.json, hotkeys.json et plugins/dataview/main.js, lesquels mettrais-tu sous git, et pourquoi ?

Voir la solution

community-plugins.json et hotkeys.json : oui sur le principe, ce sont des décisions. Petits, en texte, ils décrivent ce que tu veux.

workspace.json : non. C'est de l'état d'interface, réécrit à chaque fermeture de panneau. Le versionner produit un commit à chaque session et un conflit dès qu'on travaille sur deux machines.

plugins/dataview/main.js : non. C'est du JavaScript compilé de plusieurs centaines de kilooctets, réécrit intégralement à chaque mise à jour du plugin. Le versionner gonfle le dépôt pour un contenu qu'on peut retélécharger — à condition de savoir quelle version. C'est précisément ce que le manifeste de la partie II enregistre.

Réponse plus fine, celle que le cours défend : aucun des quatre. On ne versionne pas .obsidian/, on versionne une description de ce qu'il doit contenir.

Exercice 2 — Prédire l'effet d'un déplacement

Tu as 30-projets/supervision.md, cité par trois notes quotidiennes avec [[supervision]]. Tu déplaces le fichier dans 99-archive/ depuis l'explorateur d'Obsidian. Que deviennent les trois liens ? Et si tu déplaces le fichier avec mv depuis un terminal, Obsidian étant fermé ?

Voir la solution

Depuis Obsidian : rien à faire, les trois liens continuent de fonctionner. Ils visent le nom supervision, qu'Obsidian résout où qu'il soit dans le vault. Aucun fichier n'est réécrit.

Avec mv, Obsidian fermé : exactement pareil. C'est contre-intuitif quand on vient d'un outil à chemins, mais la résolution se fait au nom, à l'ouverture. Obsidian relira l'arborescence au démarrage et retrouvera la note.

La différence apparaît au renommage, pas au déplacement : renommer depuis Obsidian réécrit les liens des notes citantes ; renommer avec mv les casse, puisque personne n'a mis à jour le texte des trois notes.

Exercice 3 — Trouver la trace d'une décision

Tu as changé le thème d'Obsidian en clair il y a deux semaines, puis tu es revenu au sombre. Aucun de ces deux changements n'est dans ton historique git, alors que ton vault est versionné. Pourquoi, et qu'est-ce que ça révèle ?

Voir la solution

Le thème est dans .obsidian/appearance.json, et .obsidian/ est dans le .gitignore — la pratique standard, justement pour éviter le bruit de workspace.json et les binaires de plugins.

Ce que ça révèle : en excluant le dossier en bloc, on jette la configuration avec l'état. Il n'existe aucune trace de tes décisions de configuration, ni moyen de les rejouer sur une autre machine. C'est le problème que le manifeste résout — non pas en versionnant .obsidian/, mais en versionnant sa description.