Firefly Markdown 文章格式指南

3185 字
16 分钟
Firefly Markdown 文章格式指南

Firefly Markdown 文章格式指南#

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


目录#


Front Matter 头部元数据#

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

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

必填字段#

字段类型说明
titlestring文章标题
publishedstring发布日期,格式 YYYY-MM-DD
descriptionstring文章描述(SEO 和摘要用)
tagsarray标签数组
categorystring分类名称
draftboolean是否为草稿,false 表示发布

可选字段#

字段类型说明
pinnedboolean是否置顶,默认为 false
imagestring封面图片路径或 "api"
licenseNamestring许可证名称
authorstring作者名称
sourceLinkstring原文链接
passwordstring文章密码(加密文章)
passwordHintstring密码提示信息

基础 Markdown 语法#

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

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

扩展语法组件#

GitHub 仓库卡片#

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

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

示例效果:

CuteLeaf
/
Firefly
Waiting for api.github.com...
00K
0K
0K
Waiting...

提醒框 (Admonitions)#

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

1. GitHub 主题风格#

> [!NOTE] NOTE
> 突出显示用户应该考虑的信息。
> [!TIP] TIP
> 可选信息,帮助用户更成功。
> [!IMPORTANT] IMPORTANT
> 用户成功所必需的关键信息。
> [!WARNING] WARNING
> 关键内容,需要立即注意。
> [!CAUTION] CAUTION
> 行动的负面潜在后果。
> [!NOTE] 自定义标题
> 这是一个带有自定义标题的示例。

2. Obsidian 主题风格#

支持的类型:NOTEABSTRACTSUMMARYTLDRINFOTODOTIPHINTIMPORTANTSUCCESSCHECKDONEQUESTIONHELPFAQWARNINGCAUTIONATTENTIONFAILUREFAILMISSINGDANGERERRORBUGEXAMPLEQUOTECITE

> [!NOTE] NOTE
> 通用的笔记块。
> [!TIP] TIP
> 实用技巧或提示。
> [!WARNING] WARNING
> 警告信息。

3. VitePress 主题风格#

仅支持 5 种基础类型。

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

4. Docusaurus 风格语法#

使用 ::: 标记。

:::note
突出显示用户应该考虑的信息。
:::
:::tip
可选信息,帮助用户更成功。
:::
:::important
用户成功所必需的关键信息。
:::
:::warning
由于潜在风险需要用户立即注意的关键内容。
:::
:::caution
行动的负面潜在后果。
:::
:::tip[自定义标题]
可选信息,帮助用户更成功。
:::

剧透#

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

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

效果: 内容 被隐藏了 哈哈


图片画廊网格#

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

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

特性:

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

Expressive Code 代码块#

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

基础语法高亮#

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

ANSI 颜色渲染#

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

Terminal window
[1;4mStandard ANSI colors:[0m
- 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
- Foreground: [30m Black [31m Red [32m Green [33m Yellow [34m Blue [35m Magenta [36m Cyan [37m White [0m

框架与标题#

添加标题#

my-test-file.js
console.log('标题属性示例')

终端框架#

Terminal window
echo "此终端框架没有标题"
PowerShell 终端示例
Write-Output "这个有标题!"

无框架#

echo "看,没有框架!"

文本和行标记#

标记整行和行范围#

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

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

line-markers.js
function demo() {
console.log('此行标记为已删除')
// 此行和下一行标记为已插入
console.log('这是第二个插入行')
return '此行使用中性默认标记类型'
}

为行标记添加标签#

labeled-line-markers.jsx
<button
role="button"
{...props}
value={value}
className={buttonClassName}
disabled={disabled}
active={active}
>
{children &&
!active &&
(typeof children === 'string' ? <span>{children}</span> : children)}
</button>

使用类似 diff 的语法#

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

结合语法高亮和 diff 标记#

function thisIsJavaScript() {
console.log('要删除的旧代码')
console.log('新的闪亮代码!')
}

标记行内的单独文本#

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

正则表达式标记#

console.log('单词 yesyep 将被标记。')

选择内联标记类型#

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

自动换行#

启用换行#

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

禁用换行#

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

保留缩进#

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

可折叠部分#

5 collapsed lines
// 所有这些样板设置代码将被折叠
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
const engine = someBoilerplateEngine(evenMoreBoilerplate())
// 这部分代码默认可见
engine.doSomething(1, 2, 3, calcFn)
function calcFn() {
const a = 1
3 collapsed lines
const b = 2
const c = a + b
console.log(`计算结果: ${a} + ${b} = ${c}`)
return c
}
// 直到块末尾的所有代码将再次被折叠
engine.closeConnection()
engine.freeMemory()
1 collapsed line
engine.shutdown({ reason: '示例样板代码结束' })

行号显示#

显示行号#

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

禁用行号#

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

更改起始行号#

console.log('来自第5行的问候!')
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 代码块。

活动图#

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

状态图#

@startuml
[*] --> 草稿
草稿 --> 待审核 : 提交
待审核 --> 草稿 : 驳回
待审核 --> 已发布 : 审核通过
已发布 --> 已归档 : 到期归档

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

时序图#

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

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

用例图#

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

rectangle 博客系统 {
    usecase "浏览文章" as UC1
    usecase "发表评论" as UC3
    usecase "审核评论" as UC5
}

用户 --> UC1
用户 --> UC3
管理员 --> UC5
@enduml

ER 图#

@startuml
entity User {
    *id : uuid <<PK>>
    --
    username : varchar
    email : varchar
}

entity Post {
    *id : uuid <<PK>>
    --
    author_id : uuid <<FK>>
    title : varchar
}

User ||

C4 风格容器图#

@startuml
!includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "博客访客", "阅读文章与搜索内容")

System_Boundary(system, "Firefly Blog") {
    Container

数学公式 (KaTeX)#

Firefly 支持 KaTeX 数学公式渲染。

行内公式#

使用单个 $ 符号包裹。

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

块级公式#

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

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

复杂公式#

矩阵#

$$
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
\begin{pmatrix}
\alpha & \beta \\
\gamma & \delta
\end{pmatrix}
$$

极限与求和#

$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$
$$
\lim_{x \to 0} \frac{\sin x}{x} = 1
$$

方程组#

$$
\begin{aligned}
\nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\
\nabla \cdot \mathbf{B} &= 0 \\
\nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t}
\end{aligned}
$$

化学方程式#

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

常用符号对照表#

符号代码渲染结果
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 等视频平台的嵌入代码。

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

示例:

Bilibili 嵌入:

<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 中的 passwordpasswordHint 字段加密文章。

---
title: 加密文章示例
published: 1970-01-02
description: 这是一篇密码保护的示例文章
tags: [示例, 密码保护]
category: 文章示例
password: "123456"
passwordHint: "示例文章密码123456"
---

特性:

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

MDX 扩展#

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

组件导入#

import { Icon } from 'astro-icon/components'
<div class="flex items-center gap-2">
<Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
<span>火箭发射!</span>
</div>

JSX 表达式#

export const year = new Date().getFullYear()
今年是 {year} 年。

与标准 Markdown 的区别#

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

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


附录#

代码块语言标识参考#

语言标识
JavaScriptjavascript, js
TypeScripttypescript, ts
Pythonpython, py
Rubyruby, rb
Gogo, golang
Javajava
Cc
C++cpp, c++
Bash/Shellbash, sh, shell, ps, powershell
JSONjson
YAMLyaml, yml
HTMLhtml
CSScss
SQLsql
Markdownmarkdown, md
Diffdiff
ANSIansi
Mermaidmermaid
PlantUMLplantuml

注意事项#

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

文章分享

如果这篇文章对你有帮助,欢迎分享给更多人!

Firefly Markdown 文章格式指南
https://reedz.icu/posts/mardown-syntax-summary/
作者
ReedZheng
发布于
2026-05-08
许可协议
CC BY-NC-SA 4.0
随机文章 随机推荐

评论区

Profile Image of the Author
ReedZheng
Hello, I'm ReedZheng.
音乐
封面

音乐

暂未播放

0:00 0:00
暂无歌词
分类
标签
站点统计
文章
2
分类
2
标签
5
总字数
6,126
运行时长
0
最后活动
0 天前

文章目录