本站 MDX 组件介绍与使用方法
本站 MDX 组件使用说明:介绍 MDX 如何在 Markdown 中嵌入 Astro 组件,系统整理行级与行内组件的用途、参数和写法,并为每个组件提供可直接复制的语法示例与渲染演示,方便在文章、关于页和项目记录中快速选用与组合。

MDX 是 Markdown 的超集:在普通 Markdown 里可以直接写 JSX/Astro 组件,让文章从纯文本变成可交互的内容。本站把常用的正文能力封装成 MDX 组件,写文章时用一套简短的指令即可插入提示框、标签页、时间线、链接卡片、图片和视频等内容。
组件按写法分为两类:
- 行级:以
::name{...}或:::name{...}独占一行,适合提示框、时间线、标签页、链接卡片等块状内容。 - 行内:以
:name[文字]{...}嵌在句子中,适合徽章、键帽、术语提示、复制、艺术字等文字级标记。
本站目前提供的组件:
行级组件
| 组件 | 说明 |
|---|---|
| 手风琴 Accordion | 分组卡片,适合技术栈和入口列表 |
| 时间线 Timeline | 可展开的时间线记录 |
| 对话 Chat | 用户、助手和系统消息气泡 |
| 社交链接 SocialLinks | 行级容器,渲染为行内社交头像组 |
| 折叠面板 Folding | 纸面折叠内容,带展开过渡 |
| 卡片列表 CardList | 把 Markdown 列表渲染成卡片 |
| 链接卡片 LinkCard | 站外链接卡片,可组成响应式网格 |
| 链接横幅 LinkBanner | 横向大图链接横幅 |
| 提示框 Alert | 带类型配色的提示块,支持 card 和 flat |
| 标签页 Tabs | 多标签内容容器 |
| 金句 Quote | 带装饰图标的引用块 |
| 标题装饰 Title | 带装饰线的标题块 |
| 图片画廊 Pic | 单图与多种宫格画廊 |
| 视频嵌入 VideoEmbed | 嵌入 Bilibili 或 YouTube 视频 |
| 表情包背景 EmojiTail | 正文后方堆叠表情装饰 |
行内组件
| 组件 | 说明 |
|---|---|
| 徽章 Badge | 行内胶囊标签 |
| 键帽 Key | 键帽样式,适合快捷键说明 |
| 术语提示 Tip | 术语下划线加悬停解释 |
| 行内复制 Copy | 点击复制正文内容 |
| 代码语言标 CodeLang | 带语言标签的行内代码 |
| 人物名片 ProfileCard | 悬停或聚焦展开的人物名片 |
| 模糊 Blur | 悬停或聚焦后显现,支持块级 |
| 艺术字 ArtText | 四种行内艺术字变体 |
使用前有三条约定:
- 组件要在 MDX 顶部
import,指令只负责生成对应的组件。 - 非字符串参数用
$变量,变量在顶层 import 或export const定义。 {}会被 MDX 当作表达式,Accordion / Timeline 的行式 DSL 必须放在代码围栏内。
行级组件
手风琴 Accordion
分组卡片手风琴。分组行控制标题和默认展开状态,卡品行定义名称、描述、链接和图标。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
label | 否 | 组件 aria-label,默认“手风琴” |
| 分组行 | 是 | {标题 · open};open 控制默认展开 |
| 卡品行 | 是 | 依次填写名称、描述、URL、图标、颜色、深色颜色;最后一项可省略 |
语法
:::accordion{label="MDX 组件速查"}```accordion{基础组件 · open}- Badge | 行内小标签 | https://mdxjs.com | material-symbols:label | #00a29b- Key | 键帽样式 | https://developer.mozilla.org/docs/Web/HTML/Element/kbd | material-symbols:keyboard-arrow-up-rounded | #8b5cf6
{内容容器}- Folding | 折叠面板 | https://developer.mozilla.org/docs/Web/HTML/Element/details | material-symbols:folder-outline | #2563eb- CardList | 卡片式列表 | https://developer.mozilla.org/docs/Web/HTML/Element/ul | material-symbols:format-list-bulleted-rounded | #d97706```:::演示
时间线 Timeline
可展开的时间线。每条记录包含时间、标题、可选标签、图标和色调,详情写在记录行下方。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
label | 否 | 组件 aria-label,默认“时间线” |
| 记录行 | 是 | {时间 · 标题 · 可选标签 · icon=图标 · tone=色调} |
| 详情 | 是 | 记录行下方的文本,多行合并成一段 |
tone | 否 | neutral、success、danger |
语法
:::timeline{label="MDX 组件时间线"}```timeline{2026.05 · 建立组件目录 · 起点 · icon=mdi:source-fork}把散落在关于页的专属组件收进统一的 MDX 组件库。
{2026.10 · 接入指令糖 · icon=material-symbols:auto-awesome · tone=success}::: 容器与 :badge[] 行内指令可以直接映射到 Astro 组件。
{2026.10 · 补齐通用组件 · icon=material-symbols:sync-rounded}新增 Chat、Folding、LinkCard 等正文组件。```:::演示
把散落在关于页的专属组件收进统一的 MDX 组件库。
::: 容器与 :badge[] 行内指令可以直接映射到 Astro 组件。
新增 Chat、Folding、LinkCard 等正文组件。
对话 Chat
对话气泡。角色行区分用户、助手和系统消息,消息文本按纯文本渲染。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
:u | 是 | 用户消息 |
:a | 是 | 助手回复 |
:s | 否 | 系统提示 |
:u{name="..."} | 否 | 指定用户显示名 |
| 消息文本 | 是 | 写在角色前缀之后,不解析 Markdown |
语法
::chat:s 下面是一段组件演示:u{name="访客"} 这些指令需要提前 import 吗:a 要的,指令只负责换节点,组件作用域还得自己建。::演示
社交链接 SocialLinks
社交头像组。账号行按固定字段顺序填写,渲染时并入前一段末尾;超过 max 会折叠为 +N。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
label | 否 | 组件 aria-label,默认“社交账号” |
max | 否 | 最多显示数量,默认 4 |
| 账号行 | 是 | 依次填写平台、昵称、备注、URL、图标、brand、状态;备注、brand、状态可空 |
brand | 否 | github、bilibili、qq |
status | 否 | online、offline、none |
语法
头像组会自动接在上一段文字末尾,适合放在一句介绍之后:
:::social-links{label="演示社交账号"}- GitHub | MmzMing | 代码与项目 | https://github.com/MmzMing | fa7-brands:github | github | online- B站 | Mmz明崽 | 关注一下 | https://space.bilibili.com/15446538 | fa7-brands:bilibili | bilibili | offline- QQ群 | 加入群聊 | 吹水摸鱼 | https://qm.qq.com/q/2R07cjGTZ0 | fa7-brands:qq | qq | none:::演示
头像组会自动接在上一段文字末尾,适合放在一句介绍之后:
折叠面板 Folding
纸面折叠面板,正文支持普通 Markdown;沿用 Accordion 的毛边纸面,但内边距、字号和展开动效更轻量。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
title | 否 | 折叠标题,默认“展开查看” |
| 内容 | 是 | 容器内的 Markdown |
语法
:::folding{title="展开查看参数说明"}- `title`:折叠标题,默认“展开查看”。- 正文支持列表、代码块、链接等 Markdown 语法。:::演示
title:折叠标题,默认“展开查看”。- 正文支持列表、代码块、链接等 Markdown 语法。
卡片列表 CardList
把一组 Markdown 列表项渲染成卡片,桌面默认三列,窄屏自动降为两列或一列。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 内容 | 是 | 容器内的 Markdown 列表 |
语法
:::card-list- **行级指令**:`::` 或 `:::` 开头的指令独占一行,渲染为块级组件。- **行内指令**:`:name[文字]` 嵌在段落中,适合标签、键帽、术语解释。- **数据驱动**:Accordion、Timeline 只接收结构化数据,内容仍留在 MDX。:::演示
- 行级指令:
::或:::开头的指令独占一行,渲染为块级组件。 - 行内指令:
:name[文字]嵌在段落中,适合标签、键帽、术语解释。 - 数据驱动:Accordion、Timeline 只接收结构化数据,内容仍留在 MDX。
链接卡片 LinkCard
站外链接卡片。外观与友链卡片一致:1px 边框、卡片底色、双层投影,悬停时放大到 1.03 并加深背景、边框和阴影。单张最大宽度 24rem 并水平居中;连续写多个会自动合并为水平居中的网格,网格宽度 ≥ 44rem 时 3 列,≥ 29rem 时 2 列,其余 1 列;末行未占满时整体居中。
设置 banner 后,封面固定高度 9.5rem,图片居中裁切,下方保留图标、标题和描述;无图卡片保持紧凑横向布局。连续卡片之间插入段落、标题等块级内容会打断自动合并。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
link | 是 | 跳转地址,新标签页打开 |
title | 否 | 卡片标题,缺省时使用域名 |
desc | 否 | 卡片描述,缺省时使用域名 |
icon | 否 | 图标名或图片地址,显示在标题左侧 |
banner | 否 | 封面图地址;固定高度 9.5rem,直接作为 <img src>,不走 Astro 图片优化 |
语法
::link-card{link="https://astro.build/" title="Astro 官方站点" desc="内容驱动的静态站点框架" icon="simple-icons:astro" banner="/assets/images/example.webp"}
::link-card{link="https://mdxjs.com/" title="MDX 官方文档" desc="在 Markdown 中直接写 JSX" icon="simple-icons:mdx" banner="/assets/images/example.webp"}
::link-card{link="https://github.com/MmzMing/my-blog" title="博客源码" desc="本站的完整实现" icon="fa7-brands:github" banner="/assets/images/example.webp"}
::link-card{link="https://developer.mozilla.org/" title="MDN Web Docs" desc="Web 开发文档" icon="simple-icons:mdnwebdocs"}演示
链接横幅 LinkBanner
横向大图链接横幅,适合展示站点入口或专题;外观与友链卡片一致。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
link | 是 | 跳转地址,新标签页打开 |
title | 否 | 横幅标题,缺省时使用域名 |
desc | 否 | 横幅描述,缺省时使用域名 |
banner | 否 | 横幅图片地址,固定高度 12rem |
icon | 否 | 图标名或图片地址 |
语法
::link-banner{link="https://astro.build/" title="Astro 官方站点" desc="内容驱动的静态站点框架" banner="/assets/images/example.webp" icon="simple-icons:astro"}演示
提示框 Alert
带类型配色的提示块,支持普通、卡片和轻量三种外观。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
type | 否 | tip、info、question、warning、error,默认 tip |
title | 否 | 覆盖类型默认标题 |
card | 否 | 卡片风格,带顶部光晕与阴影 |
flat | 否 | 轻量风格;与 card 同时设置时优先 |
color | 否 | 自定义主题色,支持 hex、rgb、hsl、oklch、var |
icon | 否 | 覆盖默认图标,写 Iconify 名称 |
text | 否 | 无正文时的回落内容 |
语法
:::alert{type="tip" title="小提示"}这里是提示框正文,支持 **加粗** 与 [链接](/about)。:::
:::alert{type="warning" title="自定义配色" color="#7c3aed" card}卡片风格使用顶部光晕和阴影,适合放在重点段落前。:::演示
这里是提示框正文,支持 加粗 与 链接。
卡片风格使用顶部光晕和阴影,适合放在重点段落前。
标签页 Tabs
多标签内容容器。提供 pill、underline 两种样式:pill 为胶囊分段,underline 为底部下划线。标签由子 Tab 提供;外层用 4 个冒号包裹内层 :::tab。设置 centered 可让标签栏水平居中,切换标签时指示器会平滑滑动到目标标签,面板按方向淡入淡出,容器高度平滑过渡。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
Tabs.label | 否 | 标签栏 aria-label,默认“标签页” |
Tabs.variant | 否 | pill、underline,默认 underline |
Tabs.centered | 否 | 标签栏水平居中,默认关闭 |
Tab.label | 是 | 子标签标题 |
语法
**Pill**
::::tabs{label="Pill 示例" variant="pill"}:::tab{label="概览"}高层摘要。::::::tab{label="动态"}最近的用户活动与日志。::::::tab{label="设置"}管理账户偏好。:::::::
**Underline**
::::tabs{label="Underline 示例"}:::tab{label="全部"}显示全部工单。::::::tab{label="进行中"}显示需要处理的工单。::::::tab{label="已关闭"}已归档和已解决的请求。:::::::
**Pill + centered**
::::tabs{label="居中示例" variant="pill" centered}:::tab{label="概览"}标签栏在容器内水平居中。::::::tab{label="设置"}切换标签后内容同步更新。:::::::演示
Pill
高层摘要。
最近的用户活动与日志。
管理账户偏好。
Underline
显示全部工单。
显示需要处理的工单。
已归档和已解决的请求。
Pill + centered
标签栏在容器内水平居中。
切换标签后内容同步更新。
金句 Quote
带装饰图标的引用块,正文支持 Markdown。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
icon | 否 | 装饰图标,默认消息气泡图标 |
| 内容 | 是 | 容器内的 Markdown |
语法
:::quote知识要能被重新发现,而不是只靠标题记忆。:::演示
知识要能被重新发现,而不是只靠标题记忆。
标题装饰 Title
在正文中插入带装饰线的标题块。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 内容 | 是 | 标题文字 |
语法
:::title这里是装饰标题:::演示
这里是装饰标题
图片画廊 Pic
单图或宫格图片。单图默认限制在 36rem × 24rem 内完整显示,设置 full 可取消上限;宫格提供 duo 双列、feature 首图放大两种布局,图片按格子裁切填充。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
src | 单图 | 图片地址 |
layout | 否 | 宫格布局:duo、feature,默认 duo |
caption | 否 | 单图说明 |
mirror | 否 | 单图水平镜像 |
full | 否 | 单图取消默认尺寸上限,按内容宽度完整显示 |
语法
::pic{src="/assets/images/example.webp" caption="示例图片"}演示

宫格布局
feature 首图占左侧两行,右侧由一张宽图和两张小图填充;duo 是等宽双列。容器内每行一张图片,格式为 - 地址 | 说明 | alt,说明和 alt 可省略;宫格图片不带外框和背景,说明文字居中排在图片下方。
语法
:::pic{layout="feature"}- /assets/images/example.webp | 示例图片一- /assets/images/example.webp | 示例图片二- /assets/images/example.webp | 示例图片三- /assets/images/example.webp | 示例图片四:::
:::pic{layout="duo"}- /assets/images/example.webp | 示例图片一- /assets/images/example.webp | 示例图片二- /assets/images/example.webp | 示例图片三- /assets/images/example.webp | 示例图片四:::演示








视频嵌入 VideoEmbed
嵌入白名单域名下的视频,目前支持 Bilibili 与 YouTube;其他地址回退为原链接。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
src | 是 | 视频页面地址,仅支持 Bilibili 与 YouTube |
title | 否 | iframe 标题,默认“嵌入视频” |
语法
::video-embed{src="https://www.bilibili.com/video/BV1GJ411x7h7"}演示
表情包背景 EmojiTail
表情堆叠在正文后方,悬停时整体提亮并轻微上浮。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
emojis | 否 | 表情列表,逗号分隔或 JSON 数组,最多 6 个 |
| 内容 | 是 | 容器内的 Markdown |
语法
:::emoji-tail{emojis="📄,🦌,🙌"}这是配了表情包背景装饰的正文,透明底无边框,hover 会让表情轻轻上浮。:::演示
这是配了表情包背景装饰的正文,透明底无边框,hover 会让表情轻轻上浮。
行内组件
行内组件直接嵌在句子里,适合强调、标注和补充信息。
徽章 Badge
胶囊标签,可选外链。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 文字 | 是 | 徽章内容,写在 :badge[...] 中 |
link | 否 | 外链地址 |
语法
状态标签 :badge[Astro 7]、:badge[MDX],带链接的 :badge[组件文档]{link="https://docs.astro.build/"}。演示
状态标签 Astro 7、MDX,带链接的 组件文档。
键帽 Key
键帽样式,适合快捷键说明。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 文字 | 是 | 键帽内容 |
语法
在编辑器里按 :key[Ctrl] + :key[K] 打开命令面板。演示
在编辑器里按 Ctrl + K 打开命令面板。
术语提示 Tip
术语下划线加悬停提示。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 文字 | 是 | 术语文字 |
tip | 否 | 悬停提示;缺省时只保留普通文本 |
语法
Astro 的岛屿架构会把交互组件单独 :tip[水合]{tip="浏览器接管静态 HTML 并绑定事件的过程"},其余部分保持静态。演示
Astro 的岛屿架构会把交互组件单独 水合,其余部分保持静态。
行内复制 Copy
点击复制正文内容,适合命令和短代码。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 内容 | 是 | 要显示并复制的文本 |
语法
构建命令::copy[npm run build]。演示
构建命令:。
代码语言标 CodeLang
带语言标签的行内代码。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
lang | 否 | 语言标签 |
| 内容 | 是 | 行内代码内容 |
语法
构建命令::code[npm run build]{lang="bash"}。演示
构建命令:npm run buildbash。
人物名片 ProfileCard
人物名片。正文里显示触发词,悬停或聚焦后展开姓名、身份和简介。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
id | 是 | 全篇唯一标识 |
name | 是 | 姓名 |
role | 是 | 身份或职位 |
description | 是 | 简介 |
trigger | 否 | 触发词,默认使用 name |
avatar | 否 | 头像图片,用 $变量 传入 |
语法
有没有想过,这个博客背后其实是一个 :profile-card{id="owner" trigger="全干工程师" name="MmzMing" role="全干工程师" description="白天处理业务代码,空闲时折腾 AI、博客和各种小项目。" avatar="$ownerAvatar"} 在维护?演示
有没有想过,这个博客背后其实是一个 全干工程师MmzMing全干工程师白天处理业务代码,空闲时折腾 AI、博客和各种小项目。 在维护?
模糊 Blur
模糊文字,悬停或键盘聚焦后显现;支持行内与块级。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 内容 | 是 | 行内文字或容器内的 Markdown |
语法
遇到报错时,正确的顺序是 :blur[先看文档再改代码]。整段内容也可以隐藏:
:::blur块级模糊会把整段内容一起遮住,适合答案、剧透或折叠前的提示。:::演示
遇到报错时,正确的顺序是 先看文档再改代码。整段内容也可以隐藏:
块级模糊会把整段内容一起遮住,适合答案、剧透或折叠前的提示。
艺术字 ArtText
四种行内艺术字变体:cre 流动渐变、story 衬线批注、zoom 滚动放大、repeat 跟手回声(悬停拖影,点击扩散)。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
variant | 是 | cre、story、zoom、repeat |
| 内容 | 是 | 文字 |
语法
四种效果:[!cre:流动渐变] [!story:故事感] [!zoom:放大] [!repeat:回声]。演示
四种效果:流动渐变 故事感 放大 回声。
以上是本站 MDX 组件的完整说明。::github、callout、Mermaid 属于 Markdown 扩展,不在这批组件范围内。
参考来源
本文的组件设计参考了 RAGnote 的组件语法指南:
RAGnote 组件语法完全指南参考来源:RAGnote 富文本组件说明



