Firefly Markdown 文章格式指南
Firefly Markdown 文章格式指南
本文档说明 Firefly 主题的 Markdown 文章格式要求。
目录
- Firefly Markdown 文章格式指南
Front Matter 头部元数据
每篇文章顶部必须包含 YAML 格式的 Front Matter,用于配置文章属性。
---title: 文章标题published: 2025-5-8pinned: falsedescription: 文章描述tags: [标签1, 标签2]category: 文章分类draft: false---必填字段
| 字段 | 类型 | 说明 |
|---|---|---|
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)行内链接和引用式链接 - 图片:
语法 - 删除线:
~~删除线~~ - 强调:
**粗体**和*斜体* - 自动链接:
<URL>格式 - 转义:反斜杠
\转义特殊字符
扩展语法组件
GitHub 仓库卡片
使用 ::github{repo="用户/仓库名"} 语法创建动态仓库卡片。
::github{repo="CuteLeaf/Firefly"}示例效果:
提醒框 (Admonitions)
Firefly 支持四种提醒框主题:GitHub、Obsidian、VitePress、Docusaurus。
1. GitHub 主题风格
> [!NOTE] NOTE> 突出显示用户应该考虑的信息。
> [!TIP] TIP> 可选信息,帮助用户更成功。
> [!IMPORTANT] IMPORTANT> 用户成功所必需的关键信息。
> [!WARNING] WARNING> 关键内容,需要立即注意。
> [!CAUTION] CAUTION> 行动的负面潜在后果。
> [!NOTE] 自定义标题> 这是一个带有自定义标题的示例。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。
> [!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][/grid]特性:
- 响应式网格布局
- 高度不一的图片自动使用
object-cover中心裁剪 - 图注底端对齐
Expressive Code 代码块
Firefly 使用 Expressive Code 引擎渲染代码块,提供强大的代码展示功能。
基础语法高亮
console.log('此代码有语法高亮!')ANSI 颜色渲染
使用 ansi 语言标识渲染终端颜色。
[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框架与标题
添加标题
console.log('标题属性示例')终端框架
echo "此终端框架没有标题"Write-Output "这个有标题!"无框架
echo "看,没有框架!"文本和行标记
标记整行和行范围
// 第1行 - 通过行号定位// 第2行// 第3行// 第4行 - 通过行号定位// 第5行// 第6行// 第7行 - 通过范围 "7-8" 定位// 第8行 - 通过范围 "7-8" 定位选择行标记类型 (mark, ins, del)
function demo() { console.log('此行标记为已删除') // 此行和下一行标记为已插入 console.log('这是第二个插入行')
return '此行使用中性默认标记类型'}为行标记添加标签
<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('单词 yes 和 yep 将被标记。')选择内联标记类型
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 = 13 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)
时序图 (sequenceDiagram)
甘特图 (gantt)
类图 (classDiagram)
状态图 (stateDiagram-v2)
饼图 (pie)
PlantUML 图表
使用 ```plantuml 代码块。
活动图
状态图
时序图
用例图
ER 图
C4 风格容器图
数学公式 (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 | |
| Beta | \beta | |
| Gamma | \Gamma | |
| Pi | \pi | |
| Infinity | \infty | |
| Right Arrow | \rightarrow | |
| 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 中的 password 和 passwordHint 字段加密文章。
---title: 加密文章示例published: 1970-01-02description: 这是一篇密码保护的示例文章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 的区别
| 特性 | 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%") 以适配不同屏幕
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!