如果你在 Mac 上用 Obsidian 編輯 Markdown 筆記，並在 GitHub 上閱讀，請使用標準 Markdown 連結和獨特的小寫標題名稱。像 setup 這樣的單字能讓兩種呈現器指向相同目標；含空格的標題則需要多加留意。

本指南著重於筆記內部以及兩個 Markdown 檔案之間的導覽。實際目標是維護一份易讀的文件，同時不假設每種 Markdown 呈現器對標題目的地的解讀都相同。

為什麼有效的 Markdown 連結會找不到標題？

標題連結有兩項獨立要求：Markdown 剖析器必須辨識連結，而呈現器必須解析其目的地。連結可點擊表示符合第一項要求；連結抵達預期區段則表示符合第二項要求。

CommonMark 定義了標題語法以及包含片段識別碼的連結，包括 [link](#fragment)。其標題範例並未制定通用的標題 ID 產生演算法。這項差異說明，只有有效的 Markdown 語法，並不能保證不同應用程式中的區段導覽都一致。請參閱 CommonMark 標題規格和連結規格。

GitHub 產生標題錨點時會將字母轉成小寫、以連字號取代空格、移除其他標點符號和格式標記，並以數字後綴區分重複的錨點。Obsidian 說明，標題連結會使用 # 後方的標題文字。這是兩種不同的目的地慣例。請參閱 GitHub 的區段連結規則和 Obsidian 的內部連結說明文件。

Obsidian 支援 CommonMark、GitHub Flavored Markdown，以及自身的擴充功能。這項支援並不代表每種應用程式專屬的連結都能互通：Obsidian 明確提醒，有些擴充語法在其他應用程式中可能只會顯示為純文字。其 Markdown 相容性說明文件說明了這個界線。

哪種標題慣例能讓兩種呈現器指向相同目標？

建立新的共用筆記時，請選用由小寫 ASCII 字母組成且名稱獨特的標題，並在可行時使用單字。較長的名稱可以採用 desk-layout 這種形式：可見的標題文字本身就符合 GitHub 風格的片段識別碼。

這是根據已記載規則歸納出的慣例，不是另一項獨立的相容性功能。使用 setup 時，兩種呈現器都不必以不同方式解讀空格、大寫字母或格式標記。可見標題和目的地也容易互相比對。

檔案中的標題 Obsidian 標題文字目的地，經 URL 編碼 GitHub 產生的目的地
## setup #setup #setup
## desk-layout #desk-layout #desk-layout
## Desk Layout #Desk%20Layout #desk-layout

此表採用Obsidian 的標題文字與 URL 編碼指引和 GitHub 錨點規則。它刻意不假設 Obsidian 接受所有經 GitHub 正規化的片段識別碼。

這種做法有個明顯的取捨：desk-layout 看起來比較像識別碼，而不是常見的區段標題。如果自然的標題更重要，就保留原有標題，並在兩種應用程式中確認連結結果。先決定哪種取捨更適合讀者，再重新命名整份文件。

可直接試用的完整筆記

建立名為 desk-notes.md 的筆記，並將以下 Markdown 貼入其中。這是一份使用虛構內容的完整範例文件；程式碼區塊只是用來呈現原始碼。

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

請注意，連結標籤可以使用一般空格：[desk layout](#desk-layout) 會顯示易讀文字，同時保留目的地。你不必讓每個導覽標籤看起來都像標題識別碼。

在實際筆記中，請為各區段加入足夠內容，讓導覽效果清楚可見。在非常短的文件中，即使成功跳轉，也可能看不出明顯變化，因為整篇筆記原本就能顯示在同一個視窗裡。

如何在 Mac 上設定並測試 Obsidian？

先檢查筆記本身，再調整 Obsidian 產生後續連結的方式。這是兩項獨立檢查：變更連結產生偏好設定，不能取代對現有 Markdown 內容的檢視。

  1. 從側邊欄開啟 Settings。
  2. 在 Files and links 下方，停用 Use Wikilinks，讓產生的連結使用 Markdown 語法。
  3. 將 New link format 設為 Relative path to file，用於共用檔案之間的連結。
  4. 先檢查現有目的地，再依賴新設定。

Obsidian 在 Settings 中說明了桌面版設定入口以及這兩項連結產生偏好設定。相對路徑在此很實用，因為它能明確呈現共用資料夾的結構。

按下 Command+E，將範例筆記切換至 Reading view，然後點選每個導覽連結。Obsidian 說明了這個 macOS 快捷鍵，並指出閱讀檢視會隱藏 Markdown 語法。請使用相同檢視進行可重複的檢查，避免將編輯操作和導覽測試混在一起。請參閱檢視與編輯模式。

接著，在 GitHub 上檢視呈現後的檔案。將游標移到標題上，點選其連結圖示以查看實際片段識別碼。將該識別碼與來源連結中 # 後方的文字比較。GitHub 在區段連結中說明了這種檢查方式。

使用簡短的驗收清單：連結是否顯示為連結、是否選取預期檔案，以及是否抵達預期標題。依目的地記錄失敗項目，不要一次變更多個標題。這樣更容易判斷修正的是檔名、路徑還是片段識別碼。

如何連結到另一個檔案中的標題？

先從簡單的範例開始：將兩個檔案放在同一個資料夾中。在 desk-notes.md 所在的資料夾裡建立 index.md，然後貼入以下完整內容：

Desk index

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

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

目的地分為兩部分：desk-notes.md 用來選取檔案，而 #setup 用來選取區段。GitHub 會以目前檔案為基準解析相對檔案連結；Obsidian 則提供相對路徑產生設定。這些已記載的行為支援此種同資料夾配置。請參閱 GitHub 相對連結和 Obsidian 連結設定。

閱讀這些文件時，請保留相同的相對位置安排。如果你只將 index.md 移到子資料夾，原有的同層檔案目的地就不再符合一開始的配置。請先重新計算路徑，再調查標題問題。

在共用檔案連結中，請明確保留 .md 副檔名。檔名含空格時，請依照 Obsidian 的 URL 編碼指引，在 Markdown 目的地中使用 %20。編碼空格只是保留空格，並不會將標題轉成 GitHub 使用的連字號錨點。

遇到現有標題和失效連結時該怎麼處理？

在加入外掛或額外的錨點機制前，先依照以下診斷順序逐項檢查。這能找出文件中最小的故障環節。

  1. 檢查標題原始碼。 確認目標確實是 Markdown 標題，例如 ## setup，而且開頭井字號後方有空格。CommonMark 規定，含文字的標題必須有這個分隔。請參閱 ATX 標題。
  2. 檢查連結語法。 使用 [setup](#setup)。右方括號必須緊接左括號；依照 CommonMark 連結規則，[setup] (#setup) 並不是行內連結。
  3. 分開檢查檔案解析和區段解析。 跨檔案連結失效時，先暫時測試不含片段識別碼的檔案連結。如果仍然失效，先修正路徑。
  4. 比對標題文字與片段識別碼。 遇到 Desk Layout 這類自然標題時，請回頭參閱上方的呈現器比較。將 %20 改成 - 會改變目標慣例。
  5. 檢查是否有重複目標。 優先使用 notebook-setup 和 tray-setup 這類不同名稱。GitHub 的數字後綴取決於重複錨點的順序，因此重新排列可能會改變目的地。請參閱 GitHub 區段連結。

如果文件已使用自然的區段標題，請先修正最實用的導覽連結。如果為了讓片段識別碼一致而使標題變得不自然，必要時請保留各呈現器專用的目的地，不要將未經驗證的拼法說成通用格式。請測試你打算保留的實際原始碼。

每次重新命名標題後，都要重新檢查指向該標題的區段連結。Obsidian 的 Automatically update internal links 設定說明，重新命名檔案時會更新連結；單憑這項說明，還不足以證明每次編輯標題時都會修復指向它的連結。請參閱 Obsidian 的設定說明。

對於小型共用筆記，最容易維護的做法通常是使用明確的 Markdown 檔案連結、獨特的標題目標，並在結構變更後於每種呈現器中簡短檢查。先採用範例中的慣例並維持檔案配置；只有在具體的導覽需求出現時，才增加複雜度。

來源