Docs
MDX 组件
系统梳理 iflux-next 项目中 20+ 自定义 MDX 组件的用法，涵盖 Callout、Steps、Accordion、Badge、Card、Tabs 等组件的 JSX 标签写法。
3.5k 字12 分钟
系统梳理 iflux-next 项目中 20+ 自定义 MDX 组件的用法，涵盖 Callout、Steps、Accordion、Badge、Card、Tabs 等组件的 JSX 标签写法。
iflux-next 项目包含 blog 和 docs 两个内容站点。MDX 让我们可以在 Markdown 中直接使用 React 组件，极大扩展了内容创作的可能性。
所有自定义 MDX 组件统一封装在 @iflux/ui/mdx 包中，通过 mdxComponents 映射注册到 MDX 渲染管线。使用标准 Markdown 语法（链接、图片、代码块、表格等）会自动命中对应的增强组件；交互型组件则通过 JSX 标签调用。
接下来按功能分类逐一说明每个组件的用法。
每篇文章的 frontmatter（YAML 头部）支持以下字段：
将多篇相关文章组织为教程系列：
设置了相同 series 的文章会自动：
Badge 用于标注版本、状态、标签等信息，支持多种颜色变体。
实际效果：
默认 信息 成功 警告 危险 边框支持的 variant 值：
Badge 常用于标注文章版本、API 状态、功能标签等场景：
Callout 用于在内容中插入醒目的提示信息。
实际效果：
这是通过 JSX 标签创建的提示卡片。
这是一条没有标题的提示，只显示图标和内容。
这是一条警告，用于提醒读者注意潜在问题。
这是一条错误提示，用于标记不可操作或危险的内容。
这是一条成功提示，用于确认操作已完成。
Steps 组件用于展示有先后顺序的操作流程。
实际效果：
使用包管理器安装项目依赖：
pnpm install
复制 .env.example 为 .env.local，填入必要的配置项。
运行 pnpm dev，访问 http://localhost:3000 查看效果。
Step 组件支持 completed 属性，已完成步骤会显示勾号：
这个步骤已经完成，会显示绿色勾号。
这是当前正在进行的步骤。
Accordion 用于可折叠的内容区域，适合 FAQ、可选阅读等场景。
实际效果：
MDX 是 Markdown 的超集，允许在 Markdown 文档中直接使用 JSX 组件。
原生 Markdown 只支持有限的 HTML 标签，无法实现复杂交互。通过自定义组件，可以统一设计语言、增强内容表现力。
多个折叠面板默认只展开一个（手风琴模式），支持同时展开多个。
卡片组件用于展示链接或信息块，CardGrid 提供响应式网格容器。
实际效果：
CardGrid 的 cols 属性控制列数（默认 2，最大 4），响应式自动适配。设置 external 属性时外部链接自动在新标签页打开。
用于展示文件目录或层级关系，自动根据嵌套计算缩进。
实际效果：
文件夹以蓝色图标显示并加粗，文件以灰色图标显示。嵌套层级自动递增缩进。
支持在 MDX 中使用 Mermaid 语法绘制流程图、时序图、甘特图等，自动跟随主题切换明暗。
直接写 Mermaid 代码块，语言标注为 mermaid：
实际效果：
将外部平台的视频、音乐、社交媒体等内容直接嵌入页面，自动将原始链接转换为可嵌入的 iframe 地址。
通过 aspect 属性设置宽高比（默认 16/9），或用 height 设置固定高度。
基于 KaTeX 实现数学公式渲染，支持行内和块级两种。
行内公式：
质能方程 是物理学中最著名的公式之一。
欧拉公式 被誉为最美的数学公式。
块级公式：
ImageZoom 包装图片，支持点击放大查看，基于 react-medium-image-zoom 实现。
点击图片后会以模态框形式展示大图，点击空白区域或按 ESC 键关闭。
所有 h2、h3 标题会自动生成锚点 ID，并在鼠标悬停时显示 🔗 链接图标。点击图标可复制当前标题的 URL 锚点。
将鼠标悬停到本文档的任何 h2 或 h3 标题上，左侧会出现链接图标。
如需自定义锚点 ID，可使用 Heading 组件：
在文章底部显示上一篇和下一篇的导航链接。
只设置单侧时也正常工作：
实际效果示例：
显示文档的最后更新时间，可选标注作者。
实际效果：
以下组件覆盖了原生 HTML 标签，在 MDX 中使用对应的 Markdown 语法即可自动生效。
普通 Markdown 链接语法即可，内部链接走 Next.js 客户端导航，外部链接自动在新标签页打开并显示外链图标。
内部链接 — 使用 Next.js Link 组件，不会整页刷新。
外部链接 — 自动在新标签页打开，并显示外链图标。
标准 Markdown 图片语法，基于 Next.js Image 自动优化（懒加载、响应式尺寸）。alt 中包含 "hero" 或 "cover" 的图片会自动预加载。
标准 Markdown 引用语法，自动添加引用图标和左侧边框。
这是一段普通引用文字，带有左侧边框和引用图标。
使用 HTML <kbd> 标签：
快捷键：Ctrl + C 复制，Ctrl + V 粘贴，Ctrl + S 保存。macOS 上使用 Cmd 键。
标准 Markdown 代码块和行内代码语法，构建时通过 Shiki 自动注入语法高亮。代码块标题栏显示语言标签和复制按钮。
行内代码使用反引号：npm install 安装依赖。
语言标签自动显示在标题栏：
在代码块元数据中使用 title="..." 指定文件名，会显示在标题栏替代语言标签：
使用 Shiki 的 notation 语法在代码注释中高亮指定行：
// [!code highlight] 或 // [!code hl] — 高亮单行// [!code highlight:3] — 高亮当前行及接下来 2 行使用 // [!code ++] 和 // [!code --] 标记新增和删除的行：
使用 // [!code focus] 聚焦特定行，其他行变暗：
标准 Markdown 列表语法，统一的间距和缩进样式：
标准 Markdown 表格语法，自动添加圆角边框和悬停高亮：
标准 Markdown 分隔线语法 --- 即可。
所有交互型组件通过 JSX 标签 调用；HTML 元素覆盖类组件（链接、图片、代码块、表格等）直接使用 标准 Markdown 语法 即可自动命中增强版本。无需额外学习成本。
| PrevNext |
| 上下篇导航 |
<PrevNext prev={{}} next={{}}/> |
| LastUpdated | 最后更新时间 | <LastUpdated date="" author=""/> |
| MathInline | 行内数学公式 | <MathInline math="..."/> |
| MathBlock | 块级数学公式 | <MathBlock math="..."/> |
| MDXLink | 智能链接 | [text](url) |
| MDXImg | 优化图片 |  |
| MDXKbd | 键盘按键 | <kbd>key</kbd> |
| Heading | 自动锚点标题 | ## / ### |
| 表格 | 增强表格 | 标准 Markdown 表格 |
| 列表 | 增强列表 | 标准 Markdown 列表 |
| 引用块 | 增强引用 | > 引用 |
| 分隔线 | 统一分隔线 | --- |