No descriptionhttps://kinley7.cn/Firefly6.16.8https://github.com/CuteLeaf/Firefly2026年9月25日 13:51:00https://kinley7.cn/posts/guide/firefly-wiki-link/https://kinley7.cn/posts/guide/firefly-wiki-link/在 Firefly 文章中使用 Obsidian 风格的 Wiki Link 内部链接，并自动生成文章链接卡片。Sat, 03 Jan 1970 00:00:00 GMT<p>Firefly 支持在 Markdown、MDX 文章中使用 Obsidian 风格的 Wiki Link 内部链接。链接目标填写文章的 slug 或文件路径，都不需要包含扩展名，具体匹配规则见下文「链接目标的三种写法」。</p> <section><h2>文章链接卡片<a href="#文章链接卡片"><span>#</span></a></h2><p><code>[[slug]]</code> 单独成段时，会自动读取目标文章的标题、描述、发布时间、分类、标签和封面，渲染为链接卡片：</p><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>[</span><span>[</span><span>firefly</span><span>]</span><span>]</span></div></div><div><div><div>2</div></div><div> </div></div><div><div><div>3</div></div><div><span>[</span><span>[</span><span>guide/index</span><span>]</span><span>]</span></div></div><div><div><div>4</div></div><div> </div></div><div><div><div>5</div></div><div><span>[</span><span>[</span><span>markdown-extended</span><span>]</span><span>]</span></div></div></code></pre><div><div></div><div></div></div></figure></div><p><a href="/posts/firefly/">firefly</a></p><p><a href="/posts/guide/">guide/index</a></p><p><a href="/posts/markdown-extended/">markdown-extended</a></p></section> <section><h2>行内链接<a href="#行内链接"><span>#</span></a></h2><p><code>[[slug]]</code> 出现在正文中间时，渲染为普通链接，链接文字自动使用目标文章的标题</p><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>请参阅 [</span><span>[</span><span>firefly</span><span>]</span><span>] 了解主题特性。</span></div></div></code></pre><div><div></div><div></div></div></figure></div><p>请参阅 <a href="/posts/firefly/">firefly</a> 了解主题特性。</p></section> <section><h2>自定义显示标题<a href="#自定义显示标题"><span>#</span></a></h2><p>在 <code>|</code> 后填写链接的显示文字。行内链接会用它替换文章标题；单独成段时依然渲染为卡片，卡片标题使用自定义文字，描述、时间、分类、标签和封面仍然读取目标文章：</p><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>请参阅 [</span><span>[</span><span>firefly|主题介绍</span><span>]</span><span>] 了解主题特性。</span></div></div><div><div><div>2</div></div><div> </div></div><div><div><div>3</div></div><div><span>[[firefly|Firefly 主题介绍]]</span></div></div></code></pre><div><div></div><div></div></div></figure></div><p>请参阅 <a href="/posts/firefly/">主题介绍</a> 了解主题特性。</p><p><a href="/posts/firefly/">Firefly 主题介绍</a></p><p>一个例外：如果 <code>|</code> 后的文字只是把链接目标又抄了一遍（<code>[[guide/index|index]]</code>），会被当作无效别名忽略，仍然显示文章标题。Obsidian 在插入的链接时会自动补上这样的别名，避免笔记里显示一长串路径，这个例外就是为它准备的。</p></section> <section><h2>链接目标的三种写法<a href="#链接目标的三种写法"><span>#</span></a></h2><p>用 Obsidian 管理文章时，把 <code>src/content/posts</code> 目录本身作为 Obsidian 仓库（vault）打开。下文提到的「仓库根目录」都指这个目录，它正好也是 Firefly 解析链接路径的起点。</p><p>链接目标按以下顺序匹配：</p> <table><thead><tr><th>写法</th><th>示例</th><th>在 Obsidian 中</th></tr></thead><tbody><tr><td>frontmatter 的 <code>slug</code></td><td><code>[[firefly-wiki-link]]</code></td><td>✗ 不支持</td></tr><tr><td>文件路径（相对仓库根目录）</td><td><code>[[guide/firefly-layout-system]]</code></td><td>✓ 需改设置（推荐）</td></tr><tr><td>裸文件名（仓库内唯一时）</td><td><code>[[firefly-layout-system]]</code></td><td>✓ 默认即是</td></tr></tbody></table><section><h3>第一种：slug<a href="#第一种slug"><span>#</span></a></h3><p><code>slug</code> 写法在 Obsidian 中不支持，<code>slug</code> 是 Firefly 自己的概念，Obsidian 不读取 frontmatter 里的 <code>slug</code>，所以按 slug 写的链接在 Obsidian 里既不会自动补全，也点不动，只有构建出的站点上能正常跳转。如果你主要在 Obsidian 里写作，用下面两种写法。</p></section><section><h3>第二种：文件路径（推荐）<a href="#第二种文件路径推荐"><span>#</span></a></h3><p>文件路径写法需要改 Obsidian 设置，在 <code>设置 → 文件与链接 → 链接 → 内部链接类型</code> 中选择<strong>基于仓库根目录的绝对路径</strong>，Obsidian 插入的链接才会带上目录：</p><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>[</span><span>[</span><span>guide/firefly-layout-system|firefly-layout-system</span><span>]</span><span>]</span></div></div></code></pre><div><div></div><div></div></div></figure></div><p><a href="/posts/guide/firefly-layout-system/">guide/firefly-layout-system</a></p><p>因为仓库根目录就是 <code>src/content/posts</code>，Obsidian 写出的这个路径和 Firefly 需要的路径完全一致，不需要任何额外转换。</p><p>上面这行末尾的 <code>|firefly-layout-system</code> 是 Obsidian 自动补的别名，Firefly 会忽略它，卡片标题仍然取文章的 title，除非你把它修改和文件名不一致，才会变成你修改后的别名。</p><p>内部链接类型下拉框里的<strong>基于当前笔记的相对路径</strong>只在同目录内可用：它给同目录文章生成的是裸文件名，能正常匹配；但跨目录时会生成 <code>../</code> 前缀，Firefly 无法解析，链接会按原文显示。</p></section><section><h3>第三种：裸文件名<a href="#第三种裸文件名"><span>#</span></a></h3><p>「内部链接类型」的默认值就是<strong>尽可能简短的形式</strong>：只要文件名在整个仓库里唯一，Obsidian 插入的链接就只有文件名，不带目录。这种写法不需要改任何设置，效果和写完整路径完全一致：</p><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>[</span><span>[</span><span>firefly-layout-system</span><span>]</span><span>]</span></div></div></code></pre><div><div></div><div></div></div></figure></div><p><a href="/posts/firefly-layout-system/">firefly-layout-system</a></p><p>文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 Obsidian 内部链接类型设置为<strong>基于仓库根目录的绝对路径</strong>，使用第二种文件路径写法，一劳永逸</p></section></section> <section><h2>链接到其他文章的标题<a href="#链接到其他文章的标题"><span>#</span></a></h2><p>在文章 slug 后添加 <code>#标题</code>。带标题锚点的链接始终渲染为普通链接：</p><p><a href="/posts/code-examples/#%E8%AF%AD%E6%B3%95%E9%AB%98%E4%BA%AE">查看代码块语法高亮</a></p><p><a href="/posts/guide/firefly-layout-system/#%E7%9B%B8%E5%85%B3%E9%93%BE%E6%8E%A5">guide/firefly-layout-system#相关链接#相关链接</a></p><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>[</span><span>[</span><span>code-examples#语法高亮|查看代码块语法高亮</span><span>]</span><span>]</span></div></div><div><div><div>2</div></div><div> </div></div><div><div><div>3</div></div><div><span>[</span><span>[</span><span>guide/firefly-layout-system#相关链接|firefly-layout-system</span><span>]</span><span>]</span></div></div></code></pre><div><div></div><div></div></div></figure></div><p>标题锚点使用与页面标题相同的 slug 规则，因此中文、空格和大小写都会按页面实际生成的 ID 处理。</p></section> <section><h2>链接到本页标题<a href="#链接到本页标题"><span>#</span></a></h2><p>省略文章 slug，只填写标题即可链接到当前文章：</p><p><a href="#%E6%9C%AC%E9%A1%B5%E7%9B%AE%E6%A0%87">跳转到本页目标</a></p><div><figure><figcaption></figcaption><pre><code><div><div><div>1</div></div><div><span>[</span><span>[</span><span>#本页目标|跳转到本页目标</span><span>]</span><span>]</span></div></div></code></pre><div><div></div><div></div></div></figure></div></section> <section><h2>本页目标<a href="#本页目标"><span>#</span></a></h2><p>这是本页 Wiki Link 指向的标题。</p></section> <section><h2>不支持附件嵌入<a href="#不支持附件嵌入"><span>#</span></a></h2><p>附件嵌入语法目前不会被转换，会按原文显示：</p><p>![[image.png]]</p><p>行内代码和代码块中的 <code>[[firefly]]</code> 也不会被转换。</p></section>