Firefly Markdown 文章格式指南

Fri, 08 May 2026 00:00:00 GMT

Firefly Markdown 文章格式指南#

本文档说明 Firefly 主题的 Markdown 文章格式要求。

目录#

Firefly Markdown 文章格式指南

Front Matter 头部元数据#

每篇文章顶部必须包含 YAML 格式的 Front Matter，用于配置文章属性。

1
---
2
title: 文章标题
3
published: 2025-5-8
4
pinned: false
5
description: 文章描述
6
tags: [标签1, 标签2]
7
category: 文章分类
8
draft: false
9
---

必填字段#

字段	类型	说明
`title`	string	文章标题
`published`	string	发布日期，格式 `YYYY-MM-DD`
`description`	string	文章描述（SEO 和摘要用）
`tags`	array	标签数组
`category`	string	分类名称
`draft`	boolean	是否为草稿，`false` 表示发布

可选字段#

字段	类型	说明
`pinned`	boolean	是否置顶，默认为 `false`
`image`	string	封面图片路径或 `"api"`
`licenseName`	string	许可证名称
`author`	string	作者名称
`sourceLink`	string	原文链接
`password`	string	文章密码（加密文章）
`passwordHint`	string	密码提示信息

基础 Markdown 语法#

Firefly 支持标准 CommonMark 和 GFM (GitHub Flavored Markdown) 语法：

段落与换行：空行分隔段落，行末双空格换行
标题：Setext 风格（=、-）和 atx 风格（#）
引用：> 符号，支持嵌套
列表：无序（*、+、-）和有序列表
代码块：缩进代码块和围栏代码块
表格：GFM 表格语法
链接：[文本](URL) 行内链接和引用式链接
图片：![Alt](URL) 语法
删除线：~~删除线~~
强调：**粗体** 和 *斜体*
自动链接：<URL> 格式
转义：反斜杠 \ 转义特殊字符

扩展语法组件#

GitHub 仓库卡片#

使用 ::github{repo="用户/仓库名"} 语法创建动态仓库卡片。

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

示例效果：

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

提醒框 (Admonitions)#

Firefly 支持四种提醒框主题：GitHub、Obsidian、VitePress、Docusaurus。

1. GitHub 主题风格#

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 主题风格#

支持的类型：NOTE、ABSTRACT、SUMMARY、TLDR、INFO、TODO、TIP、HINT、IMPORTANT、SUCCESS、CHECK、DONE、QUESTION、HELP、FAQ、WARNING、CAUTION、ATTENTION、FAILURE、FAIL、MISSING、DANGER、ERROR、BUG、EXAMPLE、QUOTE、CITE。

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

4
> [!TIP] TIP
5
> 实用技巧或提示。
6

7
> [!WARNING] WARNING
8
> 警告信息。

3. VitePress 主题风格#

仅支持 5 种基础类型。

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

4. Docusaurus 风格语法#

使用 ::: 标记。

1
:::note
2
突出显示用户应该考虑的信息。
3
:::
4

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

9
:::important
10
用户成功所必需的关键信息。
11
:::
12

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

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

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

展开收起

剧透#

使用 :spoiler[...] 语法，文本支持 Markdown。

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

效果： 内容被隐藏了哈哈！

图片画廊网格#

使用 [grid] 和 [/grid] 标签将多张图片并排展示（最多 4 张）。

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

特性：

响应式网格布局
高度不一的图片自动使用 object-cover 中心裁剪
图注底端对齐

Expressive Code 代码块#

Firefly 使用 Expressive Code 引擎渲染代码块，提供强大的代码展示功能。

基础语法高亮#

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

ANSI 颜色渲染#

使用 ansi 语言标识渲染终端颜色。

Terminal window

1
[1;4mStandard ANSI colors:[0m
2
- Dimmed:     [2;30m Black [2;31m Red [2;32m Green [2;33m Yellow [2;34m Blue [2;35m Magenta [2;36m Cyan [2;37m White [0m
3
- Foreground: [30m Black [31m Red [32m Green [33m Yellow [34m Blue [35m Magenta [36m Cyan [37m White [0m

框架与标题#

添加标题#

my-test-file.js

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

终端框架#

Terminal window

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

PowerShell 终端示例

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

无框架#

1
echo "看，没有框架!"

文本和行标记#

标记整行和行范围#

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

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

line-markers.js

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

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

为行标记添加标签#

labeled-line-markers.jsx

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>

使用类似 diff 的语法#

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

结合语法高亮和 diff 标记#

1
function thisIsJavaScript() {
2
  console.log('要删除的旧代码')
3
  console.log('新的闪亮代码！')
4
}

标记行内的单独文本#

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

正则表达式标记#

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

选择内联标记类型#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  return true;
4
}

自动换行#

启用换行#

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

禁用换行#

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

保留缩进#

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

可折叠部分#


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
  const a = 1
3 collapsed lines
12
  const b = 2
13
  const c = a + b
14
  console.log(`计算结果: ${a} + ${b} = ${c}`)
15
  return c
16
}
17

18
// 直到块末尾的所有代码将再次被折叠
19
engine.closeConnection()
20
engine.freeMemory()
1 collapsed line
21
engine.shutdown({ reason: '示例样板代码结束' })

展开收起

行号显示#

显示行号#

1
console.log('此代码块将显示行号')
2
console.log('我在第2行')

禁用行号#

console.log('此块禁用行号')

更改起始行号#

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

图表渲染#

Mermaid 图表#

使用 ```mermaid 代码块。

流程图 (graph)#

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤 1] B -->|否| D[处理步骤 2] C --> E[子过程] D --> E subgraph E [子过程详情] E1[子步骤 1] --> E2[子步骤 2] end E --> F{另一个决策} F -->|选项 1| G[结果 1] F -->|选项 2| H[结果 2]

时序图 (sequenceDiagram)#

sequenceDiagram participant User as 用户 participant WebApp as 网页应用 participant Server as 服务器 User->>WebApp: 提交登录请求 WebApp->>Server: 发送认证请求 Server-->>WebApp: 返回认证结果 alt 认证成功 WebApp->>User: 显示欢迎页面 else 认证失败 WebApp->>User: 显示错误消息 end

甘特图 (gantt)#

gantt title 项目时间线 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段需求分析 :a1, 2023-10-01, 7d UI设计 :a2, after a1, 10d section 开发阶段前端开发 :b1, 2023-10-20, 15d 后端开发 :b2, after a2, 18d

类图 (classDiagram)#

classDiagram class User { +String username +String email +login() +logout() } class Article { +String title +publish() +delete() } User "1" -- "*" Article : 写作 Article "1" -- "*" Comment : 拥有

状态图 (stateDiagram-v2)#

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 草稿 : 拒绝审核中 --> 已批准 : 批准已批准 --> 已发布 : 发布 state 已发布 { [*] --> 活跃活跃 --> 隐藏 : 临时隐藏隐藏 --> 活跃 : 恢复 }

饼图 (pie)#

pie title 网站流量来源 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3

PlantUML 图表#

使用 ```plantuml 代码块。

活动图#

状态图#

时序图#

用例图#

ER 图#

C4 风格容器图#

数学公式 (KaTeX)#

Firefly 支持 KaTeX 数学公式渲染。

行内公式#

使用单个 $ 符号包裹。

1
欧拉公式 $e^{i\pi} + 1 = 0$ 是数学中最优美的公式之一。
2
质能方程 $E = mc^2$ 也是家喻户晓。

块级公式#

使用两个 $$ 符号包裹，居中显示。

1
$$
2
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
3
$$
4

5
$$
6
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
7
$$

复杂公式#

矩阵#

1
$$
2
\begin{pmatrix}
3
a & b \\
4
c & d
5
\end{pmatrix}
6
\begin{pmatrix}
7
\alpha & \beta \\
8
\gamma & \delta
9
\end{pmatrix}
10
$$

极限与求和#

1
$$
2
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
3
$$
4

5
$$
6
\lim_{x \to 0} \frac{\sin x}{x} = 1
7
$$

方程组#

1
$$
2
\begin{aligned}
3
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
4
\nabla \cdot \mathbf{B} &= 0 \\
5
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t}
6
\end{aligned}
7
$$

化学方程式#

1
$$
2
\ce{CH4 + 2O2 -> CO2 + 2H2O}
3
$$

常用符号对照表#

符号	代码	渲染结果
Alpha	`\alpha`	α\alphaα
Beta	`\beta`	β\betaβ
Gamma	`\Gamma`	Γ\GammaΓ
Pi	`\pi`	π\piπ
Infinity	`\infty`	∞\infty∞
Right Arrow	`\rightarrow`	→\rightarrow→
Partial	`\partial`	∂\partial∂

视频嵌入#

使用 <iframe> 嵌入 YouTube、Bilibili 等视频平台的嵌入代码。

1
<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

示例：

Bilibili 嵌入：

1
<iframe width="100%" height="468" src="//player.bilibili.com/player.html?bvid=BV1fK4y1s7Qf&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"></iframe>

文章加密#

通过 Front Matter 中的 password 和 passwordHint 字段加密文章。

1
---
2
title: 加密文章示例
3
published: 1970-01-02
4
description: 这是一篇密码保护的示例文章
5
tags: [示例, 密码保护]
6
category: 文章示例
7
password: "123456"
8
passwordHint: "示例文章密码123456"
9
---

特性：

构建时加密：使用 AES-256-GCM 算法加密
客户端解密：通过 Web Crypto API 在浏览器本地解密
会话缓存：密码保存在 sessionStorage，刷新页面无需重复输入
关闭即失效：关闭浏览器后缓存清除

MDX 扩展#

Firefly 支持 MDX 格式文章，可在 Markdown 中使用 JSX 组件和 JavaScript 表达式。

组件导入#

1
import { Icon } from 'astro-icon/components'
2

3
<div class="flex items-center gap-2">
4
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
5
  <span>火箭发射！</span>
6
</div>

JSX 表达式#

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

与标准 Markdown 的区别#

特性	Markdown	MDX
基础语法	CommonMark	CommonMark
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持
动态数据	不支持	支持
样式定制	有限	灵活

注意：如果没有特别复杂的内容和需求，推荐使用标准 Markdown 格式。

附录#

代码块语言标识参考#

语言	标识
JavaScript	`javascript`, `js`
TypeScript	`typescript`, `ts`
Python	`python`, `py`
Ruby	`ruby`, `rb`
Go	`go`, `golang`
Java	`java`
C	`c`
C++	`cpp`, `c++`
Bash/Shell	`bash`, `sh`, `shell`, `ps`, `powershell`
JSON	`json`
YAML	`yaml`, `yml`
HTML	`html`
CSS	`css`
SQL	`sql`
Markdown	`markdown`, `md`
Diff	`diff`
ANSI	`ansi`
Mermaid	`mermaid`
PlantUML	`plantuml`

注意事项#

更改配置后需重启开发服务器才能生效（特别是主题配置）
Mermaid 和 PlantUML 在构建阶段编码并生成 SVG 地址，页面端根据主题自动切换图源
加密文章的密码建议使用强密码，并妥善保管
视频嵌入建议使用响应式高度 (width="100%") 以适配不同屏幕

芦苇の小窝

Firefly Markdown 文章格式指南

Firefly Markdown 文章格式指南#

目录#

Front Matter 头部元数据#

必填字段#

可选字段#

基础 Markdown 语法#

扩展语法组件#

GitHub 仓库卡片#

提醒框 (Admonitions)#

1. GitHub 主题风格#

2. Obsidian 主题风格#

3. VitePress 主题风格#

4. Docusaurus 风格语法#

剧透#

图片画廊网格#

Expressive Code 代码块#

基础语法高亮#

ANSI 颜色渲染#

框架与标题#

添加标题#

终端框架#

无框架#

文本和行标记#

标记整行和行范围#

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

为行标记添加标签#

使用类似 diff 的语法#

结合语法高亮和 diff 标记#

标记行内的单独文本#

正则表达式标记#

选择内联标记类型#

自动换行#

启用换行#

禁用换行#

保留缩进#

可折叠部分#

行号显示#

显示行号#

禁用行号#

更改起始行号#

图表渲染#

Mermaid 图表#

流程图 (graph)#

时序图 (sequenceDiagram)#

甘特图 (gantt)#

类图 (classDiagram)#

状态图 (stateDiagram-v2)#

饼图 (pie)#

PlantUML 图表#

活动图#

状态图#

时序图#

用例图#

ER 图#

C4 风格容器图#

数学公式 (KaTeX)#

行内公式#

块级公式#

复杂公式#

矩阵#

极限与求和#

方程组#

化学方程式#

常用符号对照表#

视频嵌入#

文章加密#

MDX 扩展#

组件导入#

JSX 表达式#

与标准 Markdown 的区别#

附录#

代码块语言标识参考#

注意事项#

图像频域滤波实验报告