Gebruik voor een Markdown-notitie die je op een Mac in Obsidian bewerkt en op GitHub leest standaard Markdown-koppelingen en unieke kopnamen in kleine letters. Losse woorden zoals setup geven beide weergaveprogramma’s hetzelfde doel; bij koppen met spaties is extra aandacht nodig.

Deze handleiding richt zich op navigatie binnen een notitie en tussen twee Markdown-bestanden. Het praktische doel is één leesbaar document te onderhouden zonder ervan uit te gaan dat elke Markdown-weergaveprogramma bestemmingen van koppen op dezelfde manier interpreteert.

Waarom kan een geldige Markdown-koppeling de kop missen?

Een koppeling naar een kop stelt twee aparte eisen: de Markdown-parser moet de koppeling herkennen en het weergaveprogramma moet de bestemming ervan bepalen. Een klikbare koppeling toont aan dat aan de eerste eis is voldaan. Op de bedoelde sectie terechtkomen toont aan dat ook aan de tweede eis is voldaan.

CommonMark definieert kopsyntaxis en koppelingen met fragmenten, waaronder [link](#fragment). De kopvoorbeelden leggen geen universeel algoritme vast voor het genereren van kop-ID’s. Dat verklaart waarom geldige Markdown-syntaxis op zichzelf geen overeenkomende sectienavigatie in verschillende toepassingen garandeert. Zie de CommonMark-specificatie voor koppen en de specificatie voor koppelingen.

GitHub genereert ankers voor koppen door letters om te zetten naar kleine letters, spaties te vervangen door koppeltekens, overige leestekens en opmaak te verwijderen en herhaalde ankers uniek te maken met numerieke achtervoegsels. Obsidian documenteert koppelingen naar koppen met de koptekst na #. Dit zijn verschillende conventies voor bestemmingen. Zie GitHubs regels voor sectiekoppelingen en Obsidian-documentatie over interne koppelingen.

Obsidian ondersteunt naast de eigen uitbreidingen ook CommonMark en GitHub Flavored Markdown. Die ondersteuning maakt niet elke toepassingsspecifieke koppeling uitwisselbaar: Obsidian waarschuwt expliciet dat sommige uitbreidingen in andere apps als gewone tekst kunnen verschijnen. De documentatie over Markdown-compatibiliteit beschrijft deze grens.

Welke kopconventie geeft beide weergaveprogramma’s hetzelfde doel?

Kies voor een nieuwe gedeelde notitie unieke kopnamen met kleine ASCII-letters, en gebruik waar praktisch één woord. Voor langere namen is een vorm zoals desk-layout een handige optie: de zichtbare koptekst komt dan al overeen met het GitHub-fragment.

Dit is een conventie die is afgeleid van de gedocumenteerde regels, geen aparte compatibiliteitsfunctie. Met setup zijn er geen spaties, hoofdletters of opmaak die de weergaveprogramma’s verschillend kunnen interpreteren. De zichtbare kop en de bestemming blijven eenvoudig met elkaar te vergelijken.

Kop in het bestand Obsidian-bestemming op basis van koptekst, URL-gecodeerd Door GitHub gegenereerde bestemming
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

De tabel volgt de richtlijnen van Obsidian voor kopteksten en URL-codering en de ankerregels van GitHub. Er wordt bewust niet van uitgegaan dat Obsidian elk door GitHub genormaliseerd fragment accepteert.

Er is een zichtbaar compromis: desk-layout leest meer als een identificatie dan als een gebruikelijke sectietitel. Als natuurlijke titels belangrijker zijn, behoud ze dan en controleer de resulterende koppelingen in beide toepassingen. Hernoem niet meteen een heel document voordat je hebt bepaald welk compromis het beste past bij de lezers.

Een volledige notitie om uit te proberen

Maak een notitie met de naam desk-notes.md en plak de volgende Markdown erin. Dit is een volledig voorbeelddocument met synthetische inhoud; het codeblok is er alleen om de bron te tonen.

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

Je ziet dat het koppelingslabel gewone spaties kan bevatten: [desk layout](#desk-layout) toont leesbare tekst en behoudt tegelijk de bestemming. Je hoeft niet elk navigatielabel op een kopidentificatie te laten lijken.

Zorg er bij een echte notitie voor dat secties genoeg inhoud hebben om navigatie zichtbaar te maken. In een heel kort document kan een geslaagde sprong weinig beweging opleveren, omdat de hele notitie al in het venster past.

Hoe configureer en test je Obsidian op een Mac?

Begin bij de notitie zelf en pas daarna aan hoe Obsidian toekomstige koppelingen genereert. Dit zijn afzonderlijke controles: een voorkeur voor het genereren van koppelingen wijzigen is geen vervanging voor het inspecteren van de Markdown die er al staat.

  1. Open Instellingen in de zijbalk.
  2. Schakel onder Bestanden en koppelingen de optie Wikilinks gebruiken uit, zodat gegenereerde koppelingen Markdown-syntaxis gebruiken.
  3. Stel Nieuwe koppelingsindeling in op Relatief pad naar bestand voor koppelingen tussen gedeelde bestanden.
  4. Inspecteer bestaande bestemmingen voordat je op de nieuwe instellingen vertrouwt.

Obsidian documenteert waar je de desktopinstellingen opent en beschrijft beide voorkeuren voor het genereren van koppelingen in Instellingen. Relatieve paden zijn hier een handige keuze, omdat daarmee de gedeelde mapstructuur expliciet wordt.

Schakel de voorbeelddocumentnotitie met Command+E over naar Leesweergave en klik vervolgens op elke navigatiekoppeling. Obsidian documenteert deze macOS-sneltoets en legt uit dat de leesweergave Markdown-syntaxis verbergt. Gebruik voor herhaalbare controles steeds dezelfde weergave, in plaats van bewerkingshandelingen te combineren met navigatietests. Zie Weergaven en bewerkingsmodus.

Bekijk daarna het weergegeven bestand op GitHub. Beweeg de aanwijzer over een kop en klik op het koppelingspictogram om het daadwerkelijke fragment te inspecteren. Vergelijk dat fragment met de tekst na # in je bronkoppeling. GitHub documenteert deze inspectiemethode bij Sectiekoppelingen.

Gebruik een korte acceptatiechecklist: de koppeling wordt als koppeling weergegeven, opent het bedoelde bestand en gaat naar de bedoelde kop. Noteer fouten per bestemming in plaats van meerdere koppen tegelijk te wijzigen. Zo kun je gemakkelijker nagaan of een correctie het probleem met een bestandsnaam, een pad of een fragment heeft opgelost.

Hoe koppel je naar een kop in een ander bestand?

Houd het eerste voorbeeld eenvoudig: zet twee bestanden naast elkaar. Maak index.md in dezelfde map als desk-notes.md en geef het vervolgens deze volledige inhoud:

Desk index

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

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

De bestemming bestaat uit twee delen: desk-notes.md selecteert het bestand en #setup selecteert de sectie. GitHub bepaalt relatieve bestandskoppelingen op basis van het huidige bestand; Obsidian biedt een instelling om relatieve paden te genereren. Deze gedocumenteerde gedragingen ondersteunen deze indeling met bestanden in dezelfde map. Zie Relatieve koppelingen van GitHub en Koppelingsinstellingen van Obsidian.

Behoud dezelfde relatieve indeling overal waar je deze documenten leest. Als je alleen index.md naar een submap verplaatst, beschrijft de bestaande bestemming naar het andere bestand niet langer de oorspronkelijke indeling. Bereken het pad opnieuw voordat je de kop onderzoekt.

Behoud de extensie .md expliciet in gedeelde bestandskoppelingen. Gebruik voor bestandsnamen met spaties %20 in Markdown-bestemmingen, volgens de richtlijnen van Obsidian voor URL-codering. Een spatie coderen behoudt die spatie; het verandert een kop niet in het koppeltekenanker van GitHub.

Wat doe je met bestaande koppen en kapotte koppelingen?

Volg deze diagnosevolgorde voordat je plug-ins of extra ankermethoden toevoegt. Zo kun je het kleinste falende deel van het document afzonderlijk controleren.

  1. Controleer de kop in de bron. Bevestig dat het doel een echte Markdown-kop is, zoals ## setup, met een spatie na de eerste hekjes. CommonMark vereist die scheiding voor een kop met tekst. Zie ATX-koppen.
  2. Controleer de koppelingssyntaxis. Gebruik [setup](#setup). Laat de afsluitende rechte haak direct aansluiten op het openingshaakje; [setup] (#setup) is volgens de CommonMark-koppelingsregels geen inlinekoppeling.
  3. Controleer de bestandsverwijzing los van de sectieverwijzing. Test bij een koppeling naar een ander bestand tijdelijk een koppeling naar het bestand zonder fragment. Als die niet werkt, corrigeer dan eerst het pad.
  4. Vergelijk de koptekst met het fragment. Ga bij een natuurlijke titel zoals Desk Layout terug naar de vergelijking tussen weergaveprogramma’s hierboven. %20 wijzigen in - verandert de doelconventie.
  5. Controleer op dubbele doelen. Gebruik bij voorkeur verschillende namen, zoals notebook-setup en tray-setup. De numerieke achtervoegsels van GitHub zijn afhankelijk van de volgorde van dubbele ankers, dus bij herschikken kunnen bestemmingen veranderen. Zie Sectiekoppelingen van GitHub.

Als een document al natuurlijke sectietitels gebruikt, begin dan met de handigste navigatiekoppeling te herstellen. Als overeenkomende fragmenten de koppen onhandig zouden maken, gebruik dan waar nodig bestemmingen die specifiek zijn voor elk weergaveprogramma, in plaats van een niet-gecontroleerde spelling als draagbaar te omschrijven. Test precies de bron die je wilt behouden.

Controleer inkomende sectiekoppelingen opnieuw wanneer je een kop hernoemt. De instelling Interne koppelingen automatisch bijwerken van Obsidian documenteert dat koppelingen worden bijgewerkt wanneer een bestand wordt hernoemd; die beschrijving alleen is onvoldoende bewijs dat elke wijziging van een kop de inkomende koppelingen herstelt. Zie de beschrijving van de instelling in Obsidian.

Voor een kleine gedeelde notitie is het resultaat dat doorgaans het eenvoudigst te onderhouden is: expliciete Markdown-bestandskoppelingen, unieke kopdoelen en na structurele wijzigingen een korte controle in elk weergaveprogramma. Begin met de voorbeeldconventie, behoud de bestandsindeling en voeg alleen meer complexiteit toe wanneer een concrete navigatiebehoefte daarom vraagt.

Bronnen