MDX 格式文章示例

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

Firefly 内置的专属 MDX UI 组件#

这里列出 Firefly 内置的 MDX UI 组件，方便在 MDX 文章中直接使用。

Tab分组：`TabGroup`#

用于创建可切换的标签页，方便在文章中展示不同语言或不同版本的代码等等。

1
<TabGroup labels={["test.js", "test.py"]} client:load>
2
  ```js
3
  console.log(1)
4
  ```
5

6
  ```py
7
  print("hello world")
8
  ```
9
</TabGroup>

1
console.log(1)

1
print("hello world")

时间线：`Timeline` / `TimelineItem`#

属性	必填	说明
`date`	否	时间标签，如 “2024-03-10”
`title`	否	条目标题
`type`	否	节点颜色，default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）
`icon`	否	内置图标名，显示在圆点内：star / rocket / git / flag / book / heart / zap / bug / tag / calendar / code / edit
正文	否	`<TimelineItem>` 标签内的内容，支持 Markdown

1
<Timeline>
2
  <TimelineItem date="2026-08-16" title="新版本发布" icon="rocket">
3
    发布了全新版本，带来以下更新：
4

5
    - 新增时间线组件
6
    - 改进暗色主题
7

8
    正文里支持 **Markdown** 内容。
9
  </TimelineItem>
10
  <TimelineItem date="2025-11-02" title="站点上线" type="tip" icon="flag">
11
    欢迎来到我的博客。
12
  </TimelineItem>
13
  <TimelineItem date="2025-06-15" title="项目立项" type="note">
14
    开始规划 Firefly 主题。
15
  </TimelineItem>
16
</Timeline>

2026-08-16
新版本发布
发布了全新版本，带来以下更新：
- 新增时间线组件
- 改进暗色主题
正文里支持 Markdown 内容。
2025-11-02
站点上线
欢迎来到我的博客。
2025-06-15
项目立项
开始规划 Firefly 主题。

步骤条：`Steps` / `StepItem`#

编号步骤条，适合教程、部署流程。编号自动生成，无需手动传序号。

属性	必填	说明
`title`	否	步骤标题
`type`	否	编号圆颜色，default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）
`icon`	否	内置图标名，有图标时显示图标而非数字（star / rocket / git / flag / book / heart / zap / bug / tag / calendar / code / edit）
正文	否	`<StepItem>` 标签内的内容，支持 Markdown

1
<Steps>
2
  <StepItem title="安装依赖">
3
    运行 `pnpm install`。
4
  </StepItem>
5
  <StepItem title="启动开发服务器" type="tip" icon="rocket">
6
    运行 `pnpm dev`，打开 `localhost:4321`。
7
  </StepItem>
8
  <StepItem title="编写文章">
9
    在 `src/content/posts/` 新建 `.mdx` 文章。
10
  </StepItem>
11
</Steps>

安装依赖
运行 pnpm install。
启动开发服务器
运行 pnpm dev，打开 localhost:4321。
编写文章
在 src/content/posts/ 新建 .mdx 文章。

徽章：`Badge`#

内联彩色小徽章，可嵌在段落或标题里。

属性	必填	说明
`type`	否	default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）

1
<Badge type="tip">提示</Badge> <Badge type="warning">注意</Badge>

新功能提示笔记重要注意危险

更多信息，请查看 MDX 文档

音乐

音乐

Markdown 和 MDX 的区别#

Firefly 内置的专属 MDX UI 组件#

Tab分组：`TabGroup`#

时间线：`Timeline` / `TimelineItem`#

步骤条：`Steps` / `StepItem`#

徽章：`Badge`#

支持与分享

音乐

Markdown 和 MDX 的区别#

Firefly 内置的专属 MDX UI 组件#

Tab分组：TabGroup#

时间线：Timeline / TimelineItem#

步骤条：Steps / StepItem#

徽章：Badge#

支持与分享

Tab分组：`TabGroup`#

时间线：`Timeline` / `TimelineItem`#

步骤条：`Steps` / `StepItem`#

徽章：`Badge`#