För en Markdown-anteckning som du redigerar i Obsidian på en Mac och läser på GitHub använder du vanliga Markdown-länkar och unika rubriknamn med gemener. Enstaka ord som setup ger båda renderarna samma mål; rubriker med mellanslag kräver lite mer uppmärksamhet.

Den här guiden fokuserar på navigering inom en anteckning och mellan två Markdown-filer. Målet är att underhålla ett lättläst dokument utan att anta att alla Markdown-renderare tolkar rubrikmål på samma sätt.

Varför kan en giltig Markdown-länk missa sin rubrik?

En rubriklänk har två separata krav: Markdown-tolken måste känna igen länken, och renderaren måste hitta dess mål. En klickbar länk visar att det första kravet är uppfyllt. Att hamna i det avsedda avsnittet visar att det andra är uppfyllt.

CommonMark definierar rubriksyntax och länkar med fragment, inklusive [link](#fragment). Rubrikexemplen fastställer ingen universell algoritm för att skapa rubrik-ID:n. Den skillnaden förklarar varför korrekt Markdown-syntax i sig inte garanterar att avsnittsnavigeringen fungerar likadant i olika program. Se CommonMarks rubrikspecifikation och länkspecifikation.

GitHub skapar rubrikankare genom att göra bokstäver gemena, ersätta mellanslag med bindestreck, ta bort annan interpunktion och formatering samt skilja dubbletter åt med numeriska suffix. Obsidian dokumenterar rubriklänkar utifrån rubriktexten efter #. Det här är olika målkonventioner. Se GitHubs regler för avsnittslänkar och Obsidians dokumentation om interna länkar.

Obsidian stöder CommonMark och GitHub Flavored Markdown samt egna tillägg. Det stödet gör inte alla programspecifika länkar utbytbara: Obsidian varnar uttryckligen för att vissa tillägg kan visas som vanlig text i andra appar. Obsidians dokumentation om Markdown-kompatibilitet beskriver den här begränsningen.

Vilken rubrikkonvention ger båda renderarna samma mål?

För en ny delad anteckning väljer du unika rubriknamn med gemena ASCII-bokstäver, helst ett enda ord när det passar. För längre namn är en form som desk-layout ett användbart alternativ: den synliga rubriktexten motsvarar redan ett fragment i GitHub-stil.

Det här är en konvention som bygger på de dokumenterade reglerna, inte en separat kompatibilitetsfunktion. Med setup finns det inga mellanslag, versaler eller någon formatering som renderarna kan tolka olika. Det är enkelt att jämföra den synliga rubriken med målet.

Rubrik i filen Obsidian-mål baserat på rubriktext, URL-kodat GitHub-skapat mål
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

Tabellen följer Obsidians anvisningar om rubriktext och URL-kodning och GitHubs regler för ankare. Den utgår inte från att Obsidian godtar alla fragment som normaliserats av GitHub.

Det finns en tydlig avvägning: desk-layout ser mer ut som en identifierare än en vanlig avsnittsrubrik. Om naturliga rubriker är viktigare behåller du dem och kontrollerar de resulterande länkarna i båda apparna. Byt inte namn på hela dokumentet innan du har bestämt vilken avvägning som passar läsarna.

Ett komplett exempel på en anteckning

Skapa en anteckning med namnet desk-notes.md och klistra in följande Markdown. Det här är ett komplett exempeldokument med syntetiskt innehåll; kodblocket finns bara för att visa källtexten.

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

Observera att länktexten kan innehålla vanliga mellanslag: [desk layout](#desk-layout) visas som läsbar text medan målet bevaras. Du behöver inte utforma varje navigeringsetikett som en rubrikidentifierare.

Ge avsnitten i en riktig anteckning tillräckligt med innehåll för att navigeringen ska märkas. I ett mycket kort dokument kanske ett lyckat hopp knappt märks, eftersom hela anteckningen redan får plats i fönstret.

Hur konfigurerar och testar du Obsidian på en Mac?

Börja med själva anteckningen och justera sedan hur Obsidian skapar framtida länkar. Det här är separata kontroller: att ändra en inställning för länkskapande ersätter inte en granskning av Markdown som redan finns.

  1. Öppna Settings i sidofältet.
  2. Inaktivera Use Wikilinks under Files and links så att skapade länkar använder Markdown-syntax.
  3. Ställ in New link format på Relative path to file för länkar mellan delade filer.
  4. Granska befintliga mål innan du förlitar dig på de nya inställningarna.

Obsidian beskriver var inställningarna finns i datorversionen och båda inställningarna för länkskapande i Settings. Relativa sökvägar passar bra här eftersom mappstrukturen för de delade filerna blir tydlig.

Växla exempelnedteckningen till Reading view med Command+E och klicka sedan på varje navigeringslänk. Obsidian dokumenterar det kortkommandot för macOS och förklarar att läsvyn döljer Markdown-syntax. Använd samma vy när du gör upprepade kontroller, så att du inte blandar redigering med navigeringstester. Se Views and editing mode.

Granska sedan den renderade filen på GitHub. Håll pekaren över en rubrik och klicka på dess länkikon för att se det faktiska fragmentet. Jämför fragmentet med texten efter # i källänken. GitHub beskriver den här granskningsmetoden i Section links.

Använd en kort checklista: länken visas som en länk, öppnar rätt fil och leder till rätt rubrik. Anteckna fel för varje mål i stället för att ändra flera rubriker samtidigt. Då blir det lättare att avgöra om du har rättat ett filnamn, en sökväg eller ett fragment.

Hur länkar du till en rubrik i en annan fil?

Börja med det enklaste exemplet: lägg två filer bredvid varandra. Skapa index.md i samma mapp som desk-notes.md och ge filen följande fullständiga innehåll:

Desk index

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

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

Målet består av två delar: desk-notes.md väljer filen och #setup väljer avsnittet. GitHub utgår från den aktuella filen när relativa fillänkar tolkas; Obsidian har en inställning för att skapa länkar med relativa sökvägar. De här dokumenterade funktionerna stöder den här lösningen med filer i samma mapp. Se GitHubs relativa länkar och Obsidians länkinställningar.

Behåll samma relativa placering när du läser dokumenten. Om du flyttar endast index.md till en undermapp beskriver den befintliga destinationen till syskonfil inte längre den ursprungliga placeringen. Beräkna om sökvägen innan du undersöker rubriken.

Behåll filändelsen .md i delade fillänkar. För filnamn som innehåller mellanslag använder du %20 i Markdown-mål, enligt Obsidians anvisningar om URL-kodning. Kodning av ett mellanslag bevarar ett mellanslag; den omvandlar inte en rubrik till ett ankare med bindestreck i GitHub-stil.

Vad ska du göra med befintliga rubriker och trasiga länkar?

Följ den här felsökningsordningen innan du lägger till insticksprogram eller extra ankarfunktioner. Den hjälper dig att hitta den minsta felande delen av dokumentet.

  1. Kontrollera rubrikkällan. Bekräfta att målet är en faktisk Markdown-rubrik, till exempel ## setup, med ett mellanslag efter inledande hashtecken. CommonMark kräver den avgränsningen för en rubrik med text. Se ATX-rubriker.
  2. Kontrollera länksyntaxen. Använd [setup](#setup). Ha den avslutande hakparentesen intill den inledande parentesen; [setup] (#setup) är inte en infogad länk enligt CommonMarks länkregler.
  3. Skilj mellan filsökning och avsnittssökning. Om en länk till en annan fil inte fungerar kan du tillfälligt testa en länk till filen utan fragmentet. Om det misslyckas rättar du först sökvägen.
  4. Jämför rubriktexten med fragmentet. För en naturlig rubrik som Desk Layout går du tillbaka till jämförelsen mellan renderarna ovan. Om du ändrar %20 till - ändras målets konvention.
  5. Kontrollera om det finns upprepade mål. Föredra unika namn som notebook-setup och tray-setup. GitHubs numeriska suffix beror på ordningen för ankardubbletter, så omordning kan ändra målen. Se GitHubs avsnittslänkar.

Om ett dokument redan använder naturliga avsnittsrubriker börjar du med att rätta den viktigaste navigeringslänken. Om rubrikerna skulle bli otympliga av att fragmenten matchar kan du använda separata mål för varje renderare där det behövs, i stället för att hävda att en obekräftad stavning fungerar överallt. Testa den exakta källtext du tänker behålla.

Kontrollera inkommande avsnittslänkar på nytt varje gång du byter namn på en rubrik. Obsidians inställning Automatically update internal links anger att interna länkar uppdateras när en fil byter namn. Den beskrivningen räcker inte i sig som belägg för att varje ändring av en rubrik också lagar inkommande länkar. Se Obsidians beskrivning av inställningen.

För en liten delad anteckning blir resultatet oftast enklast att underhålla med uttryckliga Markdown-fillänkar, unika rubrikmål och en kort kontroll i varje renderare efter strukturella ändringar. Börja med exempelformatet, behåll filernas placering och lägg bara till komplexitet när ett konkret navigeringsbehov kräver det.

Källor