Situation. Vous maintenez un dépôt : un README, des specs, des plans, un AGENTS.md, un dossier docs/. Le texte doit rester du Markdown propre, parce que Git, votre équipe et vos outils le lisent directement.
Ce que vous obtenez à la fin. Une documentation à jour, un diff Git lisible, et aucune conversion à expliquer en revue.
1. Ouvrir le dépôt comme espace de travail
Fichier > Ouvrir… (⌘O), puis choisissez le dossier du dépôt plutôt qu’un fichier.
Balise l’indexe et affiche à gauche deux vues : Fichiers et Plan.
Ajoutez ce dossier aux Favoris depuis le menu d’emplacements de la barre d’outils. Vous le rouvrirez ensuite en deux clics, sans repasser par le panneau macOS.
2. Écrire dans le mode qui convient au moment
Le sélecteur Visuel et Source bascule à tout moment sur le même document.
Le mode Visuel est plus confortable pour structurer, remplir un tableau, cocher des tâches. Le mode Source est plus rapide pour corriger une syntaxe précise ou coller du contenu technique.
Ce qui est enregistré reste du Markdown, quel que soit le mode.
3. Garder les liens vivants
L’inspecteur Document signale les liens vers un fichier absent, les images absentes et les ancres absentes. C’est le moyen le plus simple de ne pas laisser pourrir une documentation qui grossit.
4. Renommer sans casser
Renommez un document depuis la liste de fichiers, jamais depuis le Finder.
Balise affiche d’abord un aperçu complet : le nouveau nom, le déplacement éventuel du dossier de ressources, la liste des fichiers qui contiennent des liens à mettre à jour, et le numéro de ligne de chaque modification.
Le renommage et la mise à jour des liens sont ensuite appliqués ensemble.
5. Insérer un diagramme quand une phrase ne suffit pas
Insérer ouvre la galerie Mermaid et pose la source dans le document, en une seule modification annulable.
Le diagramme est rendu localement, sans requête réseau. Il reste du texte dans votre fichier, donc il se relit dans un diff Git.
Voir Maintenir un diagramme à côté du code.
6. Relire son diff avant de commiter
Ouvrez le diff du fichier dans vos outils Git habituels avant de commiter. Vous voyez exactement ce que le commit contiendra.
Balise n’écrit jamais dans Git. Le commit se fait avec vos outils habituels.
Transmettre le contexte à un assistant
Dans la barre d’outils, choisissez Copier le contexte, puis collez le résultat dans Codex, Claude Code ou votre agent local habituel. Le dernier résumé préparé apparaît d’abord, puis le nom du fichier lié à son chemin absolu. La source Markdown et le fichier lui-même ne sont jamais joints ; un résumé antérieur aux modifications non enregistrées est signalé.
Si ça ne se passe pas comme prévu
- Enregistrement refusé après une opération Git : Quand l’enregistrement est refusé
- Le dossier ne s’ouvre plus : Quand Balise ne peut plus lire un fichier ou un dossier
- Détail de chaque commande : L’espace Markdown