Firefly 博客官方指南

目录#

Markdown 基础语法
代码块与 Expressive Code
Markdown 扩展功能
MDX 格式文章

1. Markdown 基础语法#

来源：[[markdown-tutorial]]

Firefly 完整支持 CommonMark 与 GFM（GitHub Flavored Markdown）规范。

1.1 块级元素#

段落与换行#

段落之间用空行分隔，段内换行在行末添加两个空格。

标题#

支持两种写法：

1
# ATX 风格标题（推荐）
2
###### 最多支持六级
3

4
Setext 风格标题
5
================（h1 用 =）
6
Setext 风格标题
7
----------------（h2 用 -）

引用块#

1
> 单层引用
2
>
3
> > 嵌套引用
4
>
5
> 引用中可以包含 **Markdown** 语法、列表、代码块等。

列表#

1
- 无序列表（*、+、- 均可）
2
- 嵌套列表
3
  - 子项
4

5
1. 有序列表
6
2. 第二项
7
   1. 嵌套有序列表

注意：数字后紧跟 . 可能被误识别为有序列表（如 1986.），需转义为 1986\.。

代码块#

1
```javascript
2
// 带语法高亮的围栏代码块
3
console.log('Hello Firefly!');
4
```
5

6
    // 缩进式代码块（4空格或1Tab）
7
    indent code here

表格#

1
| 左对齐 | 居中对齐 | 右对齐 |
2
| :----- | :------: | -----: |
3
| cell   |  cell    |   cell |

水平分割线#

1
---
2
***
3
___

1.2 行内元素#

元素	语法	效果
斜体	`text` 或 `_text_`	text
粗体	`text` 或 `__text__`	text
行内代码	`code`	`code`
删除线	`~~text~~`（GFM）	~~text~~
链接	`[text](url "title")`	text
图片	`![alt](url "title")`	图片
自动链接	`<https://example.com>`	自动生成链接

参考式链接#

1
[链接文本][id]
2

3
[id]: https://example.com "可选标题"

1.3 转义字符#

以下字符可用反斜杠转义：

1
\   `   *   _   { }   [ ]   ( )   #   +   -   .   !

1.4 内嵌 HTML#

Markdown 中可直接使用 HTML 标签：

块级标签（如 <div>）内部的 Markdown 语法不会被解析
行内标签（如 <span>）内部的 Markdown 语法正常解析

2. 代码块与 Expressive Code#

来源：[[code-examples]]

Firefly 集成 Expressive Code，提供强大的代码展示能力。

2.1 语法高亮#

支持所有主流语言的语法高亮，以及 ANSI 转义序列渲染：

1
标准颜色: [31m红色[0m [32m绿色[0m [33m黄色[0m
2
256色:    [38;5;82m亮绿[0m [38;5;200m亮紫[0m
3
24位真彩:  [38;2;255;128;0m橙色渐变[0m
4
字体样式:  [1m粗体[0m [2m暗淡[0m [3m斜体[0m [4m下划线[0m [7m反转[0m [9m删除线[0m

2.2 编辑器与终端框架#

1
```js title="config.js"
2
// 自动显示为编辑器框架（带文件名标签）
3
```
4

5
```bash title="安装依赖"
6
npm install
7
```
8

9
```text frame="none"
10
// frame="none" 隐藏框架
11
```

2.3 行标记与文本标记#

1
```js {1, 3-5} mark={2} ins={6} del={7}
2
// 支持按行号标记
3
// mark - 高亮行
4
// ins - 插入行（绿色）
5
// del - 删除行（红色）
6
```

还支持：

Diff 语法：+ 标记新增，- 标记删除
行内文本标记：用 // [!code highlight] 等指令标记具体文本
标签标注：为标记行添加自定义标签
正则匹配：用正则表达式匹配并标记文本

2.4 自动换行与折叠#

1
```js wrap=true preserveIndent=true
2
// 自动换行 + 保持缩进
3
```
4

5
```js collapse={2-10}
6
// 折叠指定行范围
7
```

2.5 行号控制#

1
```js showLineNumbers=false
2
// 隐藏行号
3
```
4

5
```js startLineNumber=42
6
// 从第 42 行开始编号
7
```

3. Markdown 扩展功能#

来源：[[markdown-extended]]

3.1 GitHub 仓库卡片#

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

页面加载时自动从 GitHub API 获取仓库信息，展示为精美卡片。

3.2 提示框 / 告示框（Admonitions）#

Firefly 支持三种主题风格，配置于 src/config/siteConfig.ts：

GitHub 主题#

1
> [!NOTE]
2
> 这是注释
3

4
> [!TIP]
5
> 自定义标题
6
> 这是提示
7

8
> [!IMPORTANT]
9
> 这是重要信息
10

11
> [!WARNING]
12
> 这是警告
13

14
> [!CAUTION]
15
> 这是注意

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

VitePress 主题#

与 GitHub 主题相同的 5 种类型，采用现代扁平化设计风格。

Docusaurus 语法兼容#

1
:::note
2
Docusaurus 风格语法，视觉效果复用上述三种主题。
3
:::
4

5
:::tip 自定义标题
6
带自定义标题的提示框。
7
:::

3.3 剧透文本#

1
:spoiler[这是隐藏内容，鼠标悬停可见]

支持内部 Markdown 格式化。

3.4 图片画廊网格#

1
[grid]
2
图片1
3
图片2
4
图片3
5
[/grid]

最多支持 4 张图片并排显示，自动高度匹配，支持灯箱放大查看。

4. MDX 格式文章#

来源：[[mdx-example]]

Firefly 同时支持 .md 和 .mdx 格式。MDX 允许在 Markdown 中使用 JSX 和组件导入。

4.1 MDX vs Markdown#

特性	Markdown (.md)	MDX (.mdx)
基础语法（CommonMark）	✅	✅
HTML 标签	✅	✅
组件导入	❌	✅
动态数据	❌	✅
样式定制	基础	完整

4.2 使用组件#

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

3
<Icon name="rocket" class="w-6 h-6 text-blue-500" />

4.3 JSX 表达式#

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

3
当前年份是 {year}

4.4 自定义样式#

1
<div className="bg-blue-100 p-4 rounded-lg">
2
  注意：MDX 中使用 `className` 而非 `class`
3
</div>

建议：如果不需要组件和动态数据，优先使用 .md 格式更简洁。

本文融合自以下官方示例文章：

[[markdown-tutorial]] — Markdown 基础语法教程

[[code-examples]] — 代码块示例

[[markdown-extended]] — 扩展功能

[[mdx-example]] — MDX 格式示例

音乐

音乐

目录#