如果你在 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 在设置中说明了桌面版的设置入口和上述两项链接生成偏好。相对路径在这里很有用，因为它能明确表示共享文件夹结构。

按 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)。右方括号要紧挨着左括号；[setup] (#setup) 不符合 CommonMark 链接规则中的行内链接语法。
  3. 分别检查文件解析和章节解析。 如果跨文件链接失效，先临时测试不带片段的文件链接。如果这也失败，先修正路径。
  4. 比较标题文本与片段。 对于 Desk Layout 这样的自然标题，请回到上面的渲染器对比。将 %20 改为 - 会改变目标约定。
  5. 检查是否有重复目标。 优先使用 notebook-setup 和 tray-setup 这样名称各异的标题。GitHub 的数字后缀取决于重复锚点的顺序，因此调整顺序可能会改变目标。请参阅 GitHub 章节链接。

如果文档已经使用自然的章节标题，就先修复最重要的导航链接。如果为了匹配片段而让标题显得别扭，就在必要时维护各渲染器专用的目标，不要把未经验证的写法说成通用写法。测试你准备保留的确切源文本。

重命名标题后，要重新检查所有指向该标题的章节链接。Obsidian 的 Automatically update internal links 设置说明了重命名文件时会更新链接；仅凭这一说明，不能证明每次编辑标题都会自动修复指向该标题的链接。请参阅 Obsidian 对该设置的说明。

对于小型共享笔记，最易于维护的做法通常是使用明确的 Markdown 文件链接、唯一的标题目标，并在结构性编辑后分别用每种渲染器做一次简短检查。从示例约定开始，保持文件排列不变，只有在具体导航需求出现时才增加复杂度。

来源