Pour une note Markdown que vous modifiez dans Obsidian sur un Mac et consultez sur GitHub, utilisez des liens Markdown standard et des noms de titres uniques en minuscules. Les mots isolés comme setup donnent la même cible dans les deux moteurs de rendu ; les titres contenant des espaces demandent davantage d’attention.

Ce guide porte sur la navigation au sein d’une note et entre deux fichiers Markdown. L’objectif pratique est de conserver un document lisible sans supposer que tous les moteurs de rendu Markdown interprètent les destinations des titres de la même façon.

Pourquoi un lien Markdown valide peut-il ne pas atteindre son titre ?

Un lien vers un titre répond à deux exigences distinctes : l’analyseur Markdown doit reconnaître le lien et le moteur de rendu doit résoudre sa destination. Un lien cliquable démontre que la première exigence est remplie. L’arrivée à la section visée démontre que la seconde l’est aussi.

CommonMark définit la syntaxe des titres et les liens contenant des fragments, notamment [link](#fragment). Ses exemples de titres ne définissent pas d’algorithme universel de génération des identifiants de titre. Cette distinction explique pourquoi une syntaxe Markdown valide ne suffit pas à garantir une navigation identique entre les sections dans différentes applications. Consultez la spécification des titres de CommonMark et la spécification des liens.

GitHub génère des ancres de titre en convertissant les lettres en minuscules, en remplaçant les espaces par des traits d’union, en supprimant les autres signes de ponctuation et la mise en forme, puis en ajoutant des suffixes numériques aux ancres répétées pour les différencier. Obsidian documente les liens vers les titres en utilisant le texte du titre après #. Ces conventions de destination sont différentes. Consultez les règles de GitHub pour les liens vers des sections et la documentation d’Obsidian sur les liens internes.

Obsidian prend en charge CommonMark et GitHub Flavored Markdown, ainsi que ses propres extensions. Cette prise en charge ne rend pas pour autant interchangeables tous les liens propres à une application : Obsidian précise que certaines extensions peuvent apparaître comme du texte brut dans d’autres applications. Sa documentation sur la compatibilité Markdown décrit cette limite.

Quelle convention de titre donne la même cible dans les deux moteurs de rendu ?

Pour une nouvelle note partagée, choisissez des noms de titres uniques composés de lettres ASCII minuscules, en privilégiant un seul mot lorsque c’est possible. Pour les noms plus longs, une forme comme desk-layout est une bonne option : le texte du titre affiché correspond déjà au fragment de type GitHub.

Il s’agit d’une convention déduite des règles documentées, et non d’une fonctionnalité de compatibilité distincte. Avec setup, aucun espace, aucune majuscule et aucune mise en forme ne peuvent être interprétés différemment par les deux moteurs de rendu. Il est facile de comparer le titre affiché et la destination.

Titre dans le fichier Destination fondée sur le texte du titre dans Obsidian, encodée pour les URL Destination générée par GitHub
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

Le tableau applique les indications d’Obsidian sur le texte des titres et l’encodage des URL ainsi que les règles d’ancrage de GitHub. Il évite délibérément de supposer qu’Obsidian accepte tous les fragments normalisés par GitHub.

Il y a un compromis visible : desk-layout ressemble davantage à un identifiant qu’à un titre de section conventionnel. Si les titres naturels comptent davantage, conservez-les et vérifiez les liens dans les deux applications. Ne renommez pas tout un document avant d’avoir décidé quel compromis convient à ses lecteurs.

Exemple de note complète

Créez une note nommée desk-notes.md et collez-y le Markdown suivant. Il s’agit d’un exemple de document complet au contenu fictif ; le bloc délimité sert uniquement à montrer le code source.

Desk notes

Jump to [setup](#setup), [materials](#materials), or
[desk layout](#desk-layout).

## setup

Place the notebook beside the keyboard.

## materials

Use a notebook, a pencil, and a desk tray.

## desk-layout

Keep the tray beside the notebook.

Return to [setup](#setup).

Remarquez que le libellé du lien peut contenir des espaces ordinaires : [desk layout](#desk-layout) affiche un texte lisible tout en conservant la destination. Vous n’avez pas besoin de donner à chaque libellé de navigation l’apparence de l’identifiant du titre.

Dans une vraie note, donnez aux sections suffisamment de contenu pour que la navigation soit perceptible. Dans un document très court, le saut peut entraîner peu de déplacement, car toute la note tient déjà dans la fenêtre.

Comment configurer et tester Obsidian sur un Mac ?

Commencez par la note elle-même, puis réglez la façon dont Obsidian génère les futurs liens. Il s’agit de vérifications distinctes : modifier une préférence de génération des liens ne remplace pas l’inspection du Markdown déjà présent.

  1. Ouvrez Settings dans la barre latérale.
  2. Sous Files and links, désactivez Use Wikilinks pour que les liens générés utilisent la syntaxe Markdown.
  3. Réglez New link format sur Relative path to file pour les liens entre fichiers partagés.
  4. Inspectez les destinations existantes avant de vous fier aux nouveaux paramètres.

Obsidian documente l’accès aux paramètres de bureau et les deux préférences de génération des liens dans Settings. Les chemins relatifs sont utiles ici, car ils rendent explicite la structure des dossiers partagés.

Passez la note d’exemple en Reading view avec Command+E, puis cliquez sur chaque lien de navigation. Obsidian indique que ce raccourci fonctionne sous macOS et explique que le mode lecture masque la syntaxe Markdown. Pour des vérifications reproductibles, utilisez toujours cette même vue plutôt que de mêler les gestes d’édition aux tests de navigation. Consultez Views and editing mode.

Ensuite, inspectez le fichier affiché sur GitHub. Survolez un titre et cliquez sur son icône de lien pour examiner le fragment réel. Comparez ce fragment au texte qui suit # dans votre lien source. GitHub documente cette méthode d’inspection dans Section links.

Utilisez une courte liste de contrôle : le lien s’affiche comme un lien, ouvre le bon fichier et mène au bon titre. Notez les échecs par destination au lieu de modifier plusieurs titres à la fois. Vous pourrez ainsi déterminer plus facilement si une correction concernait un nom de fichier, un chemin ou un fragment.

Comment créer un lien vers un titre dans un autre fichier ?

Commencez par le cas le plus simple : placez deux fichiers côte à côte. Créez index.md dans le même dossier que desk-notes.md, puis donnez-lui le contenu complet suivant :

Desk index

Read the [setup notes](desk-notes.md#setup).

Review the [desk layout](desk-notes.md#desk-layout).

La destination comporte deux éléments : desk-notes.md sélectionne le fichier et #setup sélectionne la section. GitHub résout les liens relatifs vers des fichiers depuis le fichier courant ; Obsidian propose un paramètre de génération des liens avec chemin relatif. Ces comportements documentés permettent cette organisation dans un même dossier. Consultez les liens relatifs de GitHub et les paramètres des liens d’Obsidian.

Conservez la même organisation relative lorsque vous consultez ces documents. Si vous déplacez uniquement index.md dans un sous-dossier, la destination existante vers le fichier voisin ne correspond plus à l’organisation initiale. Recalculez le chemin avant d’examiner le titre.

Conservez explicitement l’extension .md dans les liens vers les fichiers partagés. Pour les noms de fichiers contenant des espaces, utilisez %20 dans les destinations Markdown, conformément aux indications d’Obsidian sur l’encodage des URL. Encoder un espace préserve cet espace ; cela ne transforme pas un titre en ancre avec trait d’union comme sur GitHub.

Que faire des titres et des liens brisés existants ?

Suivez cette séquence de diagnostic avant d’ajouter des extensions ou d’autres mécanismes d’ancrage. Elle permet d’isoler le plus petit élément défectueux du document.

  1. Vérifiez le code source du titre. Confirmez que la cible est un véritable titre Markdown, par exemple ## setup, avec une espace après les dièses d’ouverture. CommonMark exige cette séparation pour un titre contenant du texte. Consultez les titres ATX.
  2. Vérifiez la syntaxe du lien. Utilisez [setup](#setup). Gardez la parenthèse ouvrante juste après le crochet fermant ; [setup] (#setup) n’est pas un lien intégré selon les règles de CommonMark sur les liens.
  3. Distinguez la résolution du fichier de celle de la section. En cas d’échec d’un lien entre fichiers, testez temporairement un lien vers le fichier sans fragment. S’il échoue, corrigez d’abord le chemin.
  4. Comparez le texte du titre et le fragment. Pour un titre naturel comme Desk Layout, revenez à la comparaison des moteurs de rendu ci-dessus. Remplacer %20 par - modifie la convention de destination.
  5. Recherchez les cibles répétées. Préférez des noms distincts comme notebook-setup et tray-setup. Les suffixes numériques de GitHub dépendent de l’ordre des ancres en double ; leur réorganisation peut donc modifier les destinations. Consultez les liens vers des sections de GitHub.

Si un document utilise déjà des titres de section naturels, commencez par corriger le lien de navigation le plus utile. Si des fragments identiques rendent les titres maladroits, conservez au besoin des destinations propres à chaque moteur de rendu au lieu de présenter une graphie non vérifiée comme portable. Testez exactement le code source que vous comptez garder.

Vérifiez à nouveau les liens entrants vers une section chaque fois que vous renommez un titre. Le paramètre d’Obsidian Automatically update internal links indique que les liens sont mis à jour quand un fichier est renommé ; cette description ne suffit pas à prouver que chaque modification de titre corrigera les liens entrants. Consultez la description du paramètre d’Obsidian.

Pour une petite note partagée, le résultat le plus facile à maintenir consiste généralement en des liens Markdown explicites vers les fichiers, des cibles de titre uniques et une brève vérification dans chaque moteur de rendu après les modifications structurelles. Commencez par la convention de l’exemple, conservez l’organisation des fichiers et n’ajoutez de complexité que si un besoin concret de navigation le justifie.

Sources