Vol. II
不期而至🎁 惊喜礼盒
🎁 Surprise · 不定期 · 随缘更新
Firefly Wiki Link 内部链接示例
1172 字
6 分钟
Firefly 支持在 Markdown、MDX 文章中使用 Obsidian 风格的 Wiki Link 内部链接。链接目标填写文章的 slug 或文件路径，都不需要包含扩展名，具体匹配规则见下文「链接目标的三种写法」。
文章链接卡片
[[slug]] 单独成段时，会自动读取目标文章的标题、描述、发布时间、分类、标签和封面，渲染为链接卡片：
[[firefly]]
[[guide/index]]
[[markdown-extended]]Firefly 一款清新美观的 Astro 博客主题模板
Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。
Firefly 简单使用指南
如何使用 Firefly 博客模板。
Markdown 扩展功能
了解 Firefly 中的 Markdown 功能
行内链接
[[slug]] 出现在正文中间时，渲染为普通链接，链接文字自动使用目标文章的标题
请参阅 [[firefly]] 了解主题特性。请参阅 Firefly 一款清新美观的 Astro 博客主题模板 了解主题特性。
自定义显示标题
在 | 后填写链接的显示文字。行内链接会用它替换文章标题；单独成段时依然渲染为卡片，卡片标题使用自定义文字，描述、时间、分类、标签和封面仍然读取目标文章：
请参阅 [[firefly|主题介绍]] 了解主题特性。
[[firefly|Firefly 主题介绍]]请参阅 主题介绍 了解主题特性。
Firefly 主题介绍
Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。
一个例外：如果 | 后的文字只是把链接目标又抄了一遍（[[guide/index|index]]），会被当作无效别名忽略，仍然显示文章标题。Obsidian 在插入的链接时会自动补上这样的别名，避免笔记里显示一长串路径，这个例外就是为它准备的。
链接目标的三种写法
用 Obsidian 管理文章时，把 src/content/posts 目录本身作为 Obsidian 仓库（vault）打开。下文提到的「仓库根目录」都指这个目录，它正好也是 Firefly 解析链接路径的起点。
链接目标按以下顺序匹配：
| 写法 | 示例 | 在 Obsidian 中 |
|---|---|---|
frontmatter 的 slug | [[firefly-wiki-link]] | ✗ 不支持 |
| 文件路径（相对仓库根目录） | [[guide/firefly-layout-system]] | ✓ 需改设置（推荐） |
| 裸文件名（仓库内唯一时） | [[firefly-layout-system]] | ✓ 默认即是 |
第一种：slug
slug 写法在 Obsidian 中不支持，slug 是 Firefly 自己的概念，Obsidian 不读取 frontmatter 里的 slug，所以按 slug 写的链接在 Obsidian 里既不会自动补全，也点不动，只有构建出的站点上能正常跳转。如果你主要在 Obsidian 里写作，用下面两种写法。
第二种：文件路径（推荐）
文件路径写法需要改 Obsidian 设置，在 设置 → 文件与链接 → 链接 → 内部链接类型 中选择基于仓库根目录的绝对路径，Obsidian 插入的链接才会带上目录：
[[guide/firefly-layout-system|firefly-layout-system]]Firefly 布局系统详解
深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。
因为仓库根目录就是 src/content/posts，Obsidian 写出的这个路径和 Firefly 需要的路径完全一致，不需要任何额外转换。
上面这行末尾的 |firefly-layout-system 是 Obsidian 自动补的别名，Firefly 会忽略它，卡片标题仍然取文章的 title，除非你把它修改和文件名不一致，才会变成你修改后的别名。
内部链接类型下拉框里的基于当前笔记的相对路径只在同目录内可用：它给同目录文章生成的是裸文件名，能正常匹配；但跨目录时会生成 ../ 前缀，Firefly 无法解析，链接会按原文显示。
第三种：裸文件名
「内部链接类型」的默认值就是尽可能简短的形式：只要文件名在整个仓库里唯一，Obsidian 插入的链接就只有文件名，不带目录。这种写法不需要改任何设置，效果和写完整路径完全一致：
[[firefly-layout-system]]Firefly 布局系统详解
深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。
文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 Obsidian 内部链接类型设置为基于仓库根目录的绝对路径，使用第二种文件路径写法，一劳永逸
链接到其他文章的标题
在文章 slug 后添加 #标题。带标题锚点的链接始终渲染为普通链接：
[[code-examples#语法高亮|查看代码块语法高亮]]
[[guide/firefly-layout-system#相关链接|firefly-layout-system]]标题锚点使用与页面标题相同的 slug 规则，因此中文、空格和大小写都会按页面实际生成的 ID 处理。
链接到本页标题
省略文章 slug，只填写标题即可链接到当前文章：
[[#本页目标|跳转到本页目标]]本页目标
这是本页 Wiki Link 指向的标题。
不支持附件嵌入
附件嵌入语法目前不会被转换，会按原文显示：
![[image.png]]
行内代码和代码块中的 [[firefly]] 也不会被转换。
评论区
像发消息一样写就好：点工具栏插入表情 / 图片，表情会直接显示。插图 ≤5MB。
