Firefly 主题使用指南与 Markdown 高级语法#

Tip

基于 Firefly 模板自带文章示例拼接而成

Firefly 简单使用指南#

这个博客模板是基于 Astro 构建的。对于本指南中未提及的内容，您可以在 Astro 文档中找到答案。

文章的 Front-matter#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
description: 这是我新 Astro 博客的第一篇文章。
5
image: ./cover.jpg
6
tags: [前端, 开发]
7
category: 前端开发
8
draft: false
9
---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`updated`	文章更新日期。如果未设置，将默认使用发布日期。
`pinned`	是否将此文章置顶在文章列表顶部。
`description`	文章的简短描述。显示在首页上。
`image`	文章封面图片路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：`public` 目录中的图片 3. 不带任何前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`lang`	文章语言代码（如 `zh-CN`）。仅当文章语言与站点默认语言不同时设置。
`licenseName`	文章内容的许可证名称。
`licenseUrl`	文章内容的许可证链接。
`author`	文章作者。
`sourceLink`	文章内容的来源链接或参考。
`draft`	如果这篇文章仍是草稿，则不会显示。
`comment`	是否启用此文章的评论功能。默认为 `true`。
`slug`	自定义文章 URL 路径。如果不设置，将使用文件名作为 URL。
`password`	文章密码。设置后文章内容将被 AES-256-GCM 加密，访客需输入密码才能查看。
`passwordHint`	密码提示。显示在密码输入框上方，帮助访客回忆密码，也可以不加。

文章文件的放置位置#

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 是文章 URL 路径的自定义部分。如果不设置 slug，系统将使用文件名作为 URL。

Slug 使用示例#

示例 1：使用文件名作为 URL#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/my-first-blog-post

示例 2：自定义 Slug#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
slug: hello-world
5
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/hello-world

示例 3：其他语言文件名使用Slug#

1
---
2
title: 如何使用 Firefly 博客主题
3
published: 2023-09-09
4
slug: how-to-use-firefly-blog-theme
5
---

文件：src/content/posts/如何使用Firefly博客主题.md

URL：/posts/how-to-use-firefly-blog-theme

Slug 使用建议#

使用英文和连字符：my-awesome-post 而不是 my awesome post
保持简洁：避免过长的 slug
具有描述性：让 URL 能够反映文章内容
避免特殊字符：只使用字母、数字和连字符
保持一致性：在整个博客中使用相似的命名模式

注意事项#

Slug 一旦设置并发布，建议不要随意更改，以免影响 SEO 和已存在的链接
如果多个文章使用相同的 slug，后面的文章会覆盖前面的
Slug 会自动转换为小写

Markdown 扩展功能#

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

基本语法

1
[grid]
2
![示例图片一](./images/cover.avif)
3
![示例图片二](./images/cover.avif)
4
![示例图片三](./images/cover.avif)
5
[/grid]

Firefly 代码块示例#

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

1
console.log('标题属性示例')

1
<div>文件名注释示例</div>

终端框架#

1
echo "此终端框架没有标题"

1
Write-Output "这个有标题!"

覆盖框架类型#

1
echo "看，没有框架!"

1
# 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

为行标记添加标签#

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}</span> : children)}
12
</button>

在单独行上添加长标签#

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}</span> : children)}
15
</button>

使用类似 diff 的语法#

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

标记行内的单独文本#

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

正则表达式#

1
console.log('单词 yes 和 yep 将被标记。')

转义正斜杠#

1
echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

为每个块配置自动换行#

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

配置换行的缩进#

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

可折叠部分#

可折叠部分


5 collapsed lines
1
// 所有这些样板设置代码将被折叠
2
import { someBoilerplateEngine } from '@example/some-boilerplate'
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
4

5
const engine = someBoilerplateEngine(evenMoreBoilerplate())
6

7
// 这部分代码默认可见
8
engine.doSomething(1, 2, 3, calcFn)
9

10
function calcFn() {
11
  // 您可以有多个折叠部分
3 collapsed lines
12
  const a = 1
13
  const b = 2
14
  const c = a + b
15

16
  // 这将保持可见
17
  console.log(`计算结果: ${a} + ${b} = ${c}`)
18
  return c
19
}
20

4 collapsed lines
21
// 直到块末尾的所有代码将再次被折叠
22
engine.closeConnection()
23
engine.freeMemory()
24
engine.shutdown({ reason: '示例样板代码结束' })

行号#

行号

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

Tab 代码块#

由 rehype-code-group 提供，语法与 VitePress 代码组一致：用 ::: code-group labels=[...] 包裹多个代码块，即可合并成一组标签页。

Note

labels=[...] 中的标签按顺序对应组内的代码块，用英文逗号分隔；::: 与 code-group 之间的空格不能省略。

基本用法#

1
::: code-group labels=[code.js, code.py, code.html]
2

3
```js
4
export function greet(name) {
5
  return `Hello, ${name}!`;
6
}
7
```
8

9
```py
10
def greet(name):
11
    return f"Hello, {name}!"
12
```
13

14
```html
15
<p>Hello, world!</p>
16
```
17

18
:::

渲染效果：

1
export function greet(name) {
2
  return `Hello, ${name}!`;
3
}

1
def greet(name):
2
    return f"Hello, {name}!"

1
<p>Hello, world!</p>

标签中使用 Emoji#

标签支持 emoji 短代码，构建时会自动转换成 emoji：

1
::: code-group labels=[:package: npm, :package: pnpm, :yarn: yarn]

1
npm create astro@latest

1
pnpm create astro@latest

1
yarn create astro

与其他代码块特性组合#

组内仍是普通的 Expressive Code 代码块，标题、行号、行标记、折叠、终端框架等特性都可以照常使用。

1
export default {
2
  theme: "firefly",
3
  codeGroup: true,
4
};

1
pnpm build && pnpm preview


3 collapsed lines
1
// 这三行默认折叠
2
import { a } from "a";
3
import { b } from "b";
4

5
console.log(a, b);

不止是代码块#

标签页内可以放任意内容，例如文字、列表或图片：

这是一段普通的段落内容。

Tip

标签栏在构建期生成，默认展开第一项；支持鼠标点击与键盘 ← / → / Home / End 切换。

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、ER 图、类图、状态图和 XY 图。

Mermaid 图表由 Merman 实现。Firefly 在 Astro 构建阶段生成亮色和深色两套静态 SVG，无需在浏览器中加载 Mermaid 渲染运行时。可以前往 Merman Playground 实时编辑语法并预览渲染结果。

流程图示例#

流程图非常适合表示流程或算法步骤。

时序图示例#

时序图显示对象之间随时间的交互。

ER 图示例#

ER 图（实体关系图）非常适合表示数据库结构。

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

XY 图示例#

XY 图表非常适合展示趋势和对比数据。

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、ER 图、类图、状态图和 XY 图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。图表会在构建时自动渲染为 SVG，无需客户端 JavaScript 加载。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml

活动图示例#

@startuml
start
:用户提交订单;
if (库存充足?) then (是)
:冻结库存;
:创建支付单;
if (支付成功?) then (是)
:生成发货单;
:通知仓库拣货;
else (否)
:取消订单;
:释放库存;
endif
else (否)
:提示缺货;
endif
stop
@enduml

状态图示例#

@startuml
[*] --> 草稿

草稿 --> 待审核 : 提交
待审核 --> 草稿 : 驳回
待审核 --> 已发布 : 审核通过
已发布 --> 已归档 : 到期归档
已发布 --> 草稿 : 撤回修改

state 已发布 {
[*] --> 可见
可见 --> 隐藏 : 手动隐藏
隐藏 --> 可见 : 恢复展示
}

已归档 --> [*]
@enduml

用例图示例#

@startuml
left to right direction
actor 游客
actor 用户
actor 管理员

rectangle 博客系统 {
usecase "浏览文章" as UC1
usecase "搜索内容" as UC2
usecase "发表评论" as UC3
usecase "点赞收藏" as UC4
usecase "审核评论" as UC5
usec

组件图示例#

@startuml
package "Firefly Site" {
[Astro App] as App
[Markdown Parser] as Parser
[PlantUML Encoder] as Encoder
[Theme Switcher] as Theme
[Search Indexer] as Search
}

cloud "PlantUML Server" as

部署图示例#

@startuml
node "User Device" {
artifact "Browser"
}

node "CDN / Edge" {
artifact "Static Assets"
}

node "Cloudflare Worker" {
artifact "SSR Handler"
}

node "PlantUML Service" {
artifact "SVG Re

ER 图示例#

$@startuml entity User { *id : uuid <<PK>> -- username : varchar email : varchar created_at : datetime } entity Post { *id : uuid <<PK>> -- author_id : uuid <<FK>> title : varchar content :$

时序图示例（登录与刷新令牌）#

@startuml
autonumber
actor User as 用户
participant Web as 前端页面
participant API as 网关接口
participant Auth as 认证服务
database Redis as 会话缓存

用户 -> 前端页面 : 输入账号密码并提交
前端页面 -> 网关接口 : POST /login
网关接口 -> 认证服务 :

C4 风格容器图示例#

$@startuml !includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml Person(user, "博客访客", "阅读文章与搜索内容") System_Boundary(system, "Firefly Blog") { Container(we$

Firefly Wiki Link 内部链接示例#

Firefly 支持在 Markdown、MDX 文章中使用 Obsidian 风格的 Wiki Link 内部链接。链接目标填写文章的 slug 或文件路径，都不需要包含扩展名，具体匹配规则见下文「链接目标的三种写法」。

文章链接卡片#

[[slug]] 单独成段时，会自动读取目标文章的标题、描述、发布时间、分类、标签和封面，渲染为链接卡片：

1
[[firefly]]
2

3
[[guide/index]]
4

5
[[markdown-extended]]

firefly

guide/index

markdown-extended

行内链接#

[[slug]] 出现在正文中间时，渲染为普通链接，链接文字自动使用目标文章的标题

1
请参阅 [[firefly]] 了解主题特性。

请参阅 firefly 了解主题特性。

自定义显示标题#

在 | 后填写链接的显示文字。行内链接会用它替换文章标题；单独成段时依然渲染为卡片，卡片标题使用自定义文字，描述、时间、分类、标签和封面仍然读取目标文章：

1
请参阅 [[firefly|主题介绍]] 了解主题特性。
2

3
[[firefly|Firefly 主题介绍]]

请参阅主题介绍了解主题特性。

Firefly 主题介绍

一个例外：如果 | 后的文字只是把链接目标又抄了一遍（[[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 插入的链接才会带上目录：

1
[[guide/firefly-layout-system|firefly-layout-system]]

guide/firefly-layout-system

因为仓库根目录就是 src/content/posts，Obsidian 写出的这个路径和 Firefly 需要的路径完全一致，不需要任何额外转换。

上面这行末尾的 |firefly-layout-system 是 Obsidian 自动补的别名，Firefly 会忽略它，卡片标题仍然取文章的 title，除非你把它修改和文件名不一致，才会变成你修改后的别名。

内部链接类型下拉框里的基于当前笔记的相对路径只在同目录内可用：它给同目录文章生成的是裸文件名，能正常匹配；但跨目录时会生成 ../ 前缀，Firefly 无法解析，链接会按原文显示。

第三种：裸文件名#

「内部链接类型」的默认值就是尽可能简短的形式：只要文件名在整个仓库里唯一，Obsidian 插入的链接就只有文件名，不带目录。这种写法不需要改任何设置，效果和写完整路径完全一致：

1
[[firefly-layout-system]]

firefly-layout-system

文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 Obsidian 内部链接类型设置为基于仓库根目录的绝对路径，使用第二种文件路径写法，一劳永逸

链接到其他文章的标题#

在文章 slug 后添加 #标题。带标题锚点的链接始终渲染为普通链接：

查看代码块语法高亮

guide/firefly-layout-system#相关链接#相关链接

1
[[code-examples#语法高亮|查看代码块语法高亮]]
2

3
[[guide/firefly-layout-system#相关链接|firefly-layout-system]]

标题锚点使用与页面标题相同的 slug 规则，因此中文、空格和大小写都会按页面实际生成的 ID 处理。

链接到本页标题#

省略文章 slug，只填写标题即可链接到当前文章：

跳转到本页目标

1
[[#本页目标|跳转到本页目标]]

本页目标#

这是本页 Wiki Link 指向的标题。

不支持附件嵌入#

附件嵌入语法目前不会被转换，会按原文显示：

![[image.png]]

行内代码和代码块中的 [[firefly]] 也不会被转换。

音乐

Firefly 主题使用指南与 Markdown 高级语法

Firefly 主题使用指南与 Markdown 高级语法#

Firefly 简单使用指南#

文章的 Front-matter#

文章文件的放置位置#

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 使用示例#

示例 1：使用文件名作为 URL#

示例 2：自定义 Slug#

示例 3：其他语言文件名使用Slug#

Slug 使用建议#

注意事项#

Markdown 扩展功能#

GitHub 仓库卡片#

提醒框(Admonitions)配置#

1. GitHub 主题风格#

2. Obsidian 主题风格#

3. VitePress 主题风格#

4. Docusaurus 主题风格#

剧透#

图片画廊网格 (Image Grid)#

Firefly 代码块示例#

表达性代码#

语法高亮#

常规语法高亮#

渲染 ANSI 转义序列#

编辑器和终端框架#

代码编辑器框架#

终端框架#

覆盖框架类型#

文本和行标记#

标记整行和行范围#

选择行标记类型 (mark, ins, del)#

为行标记添加标签#

在单独行上添加长标签#

使用类似 diff 的语法#

结合语法高亮和类似 diff 的语法#

标记行内的单独文本#

正则表达式#

转义正斜杠#

选择内联标记类型 (mark, ins, del)#

自动换行#

为每个块配置自动换行#

配置换行的缩进#

可折叠部分#

行号#

为每个块显示行号#

更改起始行号#

Tab 代码块#

基本用法#

标签中使用 Emoji#

与其他代码块特性组合#

不止是代码块#

Markdown 中 Mermaid 图表完整指南#

流程图示例#

时序图示例#

ER 图示例#

类图示例#

状态图示例#

XY 图示例#

总结#

Markdown 中 PlantUML 图表指南#

活动图示例#

状态图示例#

用例图示例#

组件图示例#

部署图示例#

ER 图示例#

时序图示例（登录与刷新令牌）#

C4 风格容器图示例#

Firefly Wiki Link 内部链接示例#

文章链接卡片#

行内链接#

自定义显示标题#

链接目标的三种写法#

第一种：slug#

第二种：文件路径（推荐）#

第三种：裸文件名#