MDX 组件

iflux-next 项目包含 blog 和 docs 两个内容站点。MDX 让我们可以在 Markdown 中直接使用 React 组件，极大扩展了内容创作的可能性。

所有自定义 MDX 组件统一封装在 @iflux/mdx-components 包中，通过 mdxComponents 映射注册到 MDX 渲染管线。使用标准 Markdown 语法（链接、图片、代码块、表格等）会自动命中对应的增强组件；交互型组件则通过 JSX 标签调用。

接下来按功能分类逐一说明每个组件的用法。

Frontmatter 字段参考

每篇文章的 frontmatter（YAML 头部）支持以下字段：

字段	类型	必填	说明
`title`	string	是	文章标题
`date`	string	否	发布日期，格式 `YYYY-MM-DD`
`description`	string	否	文章摘要，用于 SEO 和列表页
`excerpt`	string	否	文章简介，显示在列表卡片中
`category`	string	否	文章分类，显示在侧边栏和元信息中
`tags`	string[]	否	标签数组，用于筛选和相关推荐
`cover`	string	否	封面图 URL，显示在列表卡片和文章顶部
`draft`	boolean	否	设为 `true` 则不在列表中显示
`series`	string	否	系列名称，同系列文章自动组织为教程
`seriesOrder`	number	否	在系列中的排序，数字越小越靠前

文章系列（series）

将多篇相关文章组织为教程系列：

yaml

---title: "第一章：环境搭建"series: "Next.js 全栈教程"seriesOrder: 1---

yaml

---title: "第二章：数据库设计"series: "Next.js 全栈教程"seriesOrder: 2---

设置了相同 series 的文章会自动：

在文章底部显示系列导航（进度条 + 文章列表 + 上下篇跳转）
在首页按系列分组展示
在归档页显示系列标签

一、Badge — 状态徽章

Badge 用于标注版本、状态、标签等信息，支持多种颜色变体。

jsx

<Badge>默认</Badge><Badge variant="info">信息</Badge><Badge variant="success">成功</Badge><Badge variant="warning">警告</Badge><Badge variant="danger">危险</Badge><Badge variant="outline">边框</Badge>

实际效果：

默认信息成功警告危险边框

支持的 variant 值：

值	效果
`default`	灰色（默认）
`info`	蓝色
`success`	绿色
`warning`	黄色
`danger`	红色
`outline`	无背景，仅边框

Badge 常用于标注文章版本、API 状态、功能标签等场景：

React 19 稳定版
Bun 1.3 推荐
Node.js 23 实验性
Python 2 已废弃

二、Callout — 提示卡片

Callout 用于在内容中插入醒目的提示信息。

jsx

<Callout type="info" title="自定义标题">这是通过 JSX 标签创建的提示卡片。</Callout><Callout type="tip">这是一条没有标题的提示，只显示图标和内容。</Callout>

实际效果：

自定义标题

这是通过 JSX 标签创建的提示卡片。

这是一条没有标题的提示，只显示图标和内容。

注意事项

这是一条警告，用于提醒读者注意潜在问题。

错误提示

这是一条错误提示，用于标记不可操作或危险的内容。

操作成功

这是一条成功提示，用于确认操作已完成。

支持的类型

type 属性	效果
`info`	蓝色信息提示
`tip`	紫色技巧提示
`warning`	黄色警告提示
`error`	红色错误提示
`success`	绿色成功提示

三、Steps / Step — 步骤指引

Steps 组件用于展示有先后顺序的操作流程。

jsx

<Steps><Step title="安装依赖">使用包管理器安装项目依赖：    pnpm install</Step><Step title="配置环境变量">复制 `.env.example` 为 `.env.local`，填入必要的配置项。</Step><Step title="启动开发服务器">运行 `pnpm dev`，访问 http://localhost:3000 查看效果。</Step></Steps>

实际效果：

安装依赖

使用包管理器安装项目依赖：

pnpm install

配置环境变量

复制 .env.example 为 .env.local，填入必要的配置项。

启动开发服务器

运行 pnpm dev，访问 http://localhost:3000 查看效果。

Step 组件支持 completed 属性，已完成步骤会显示勾号：

已完成

这个步骤已经完成，会显示绿色勾号。

当前步骤

这是当前正在进行的步骤。

四、Accordion — 手风琴折叠

Accordion 用于可折叠的内容区域，适合 FAQ、可选阅读等场景。

jsx

<Accordion><AccordionItem title="什么是 MDX？">MDX 是 Markdown 的超集，允许在 Markdown 文档中直接使用 JSX 组件。</AccordionItem><AccordionItem title="为什么要自定义组件？">原生 Markdown 只支持有限的 HTML 标签，无法实现复杂交互。通过自定义组件，可以统一设计语言、增强内容表现力。</AccordionItem></Accordion>

实际效果：

MDX 是 Markdown 的超集，允许在 Markdown 文档中直接使用 JSX 组件。

原生 Markdown 只支持有限的 HTML 标签，无法实现复杂交互。通过自定义组件，可以统一设计语言、增强内容表现力。

多个折叠面板默认只展开一个（手风琴模式），支持同时展开多个。

五、Card / CardGrid — 卡片布局

卡片组件用于展示链接或信息块，CardGrid 提供响应式网格容器。

jsx

<CardGrid cols={3}><Card title="Next.js" description="React 全栈框架，支持 SSR、SSG 和 App Router。" href="https://nextjs.org" external /><Card title="Tailwind CSS" description="实用优先的 CSS 框架，快速构建自定义设计。" href="https://tailwindcss.com" external /><Card title="shadcn/ui" description="可复用的 UI 组件，基于 @base-ui/react 和 Tailwind CSS。" href

实际效果：

Next.js

React 全栈框架，支持 SSR、SSG 和 App Router。

Tailwind CSS

实用优先的 CSS 框架，快速构建自定义设计。

shadcn/ui

可复用的 UI 组件，基于 @base-ui/react 和 Tailwind CSS。

CardGrid 的 cols 属性控制列数（默认 2，最大 4），响应式自动适配。设置 external 属性时外部链接自动在新标签页打开。

六、Tree / TreeItem — 树形结构

用于展示文件目录或层级关系，自动根据嵌套计算缩进。

jsx

<Tree><TreeItem name="iflux-next" type="folder">  <TreeItem name="apps" type="folder">    <TreeItem name="blog" type="folder">      <TreeItem name="src" type="folder"

实际效果：

iflux-next

apps

blog

src

app

components

content

package.json

docs

文件夹以蓝色图标显示并加粗，文件以灰色图标显示。嵌套层级自动递增缩进。

七、Mermaid — 图表渲染

支持在 MDX 中使用 Mermaid 语法绘制流程图、时序图、甘特图等，自动跟随主题切换明暗。

直接写 Mermaid 代码块，语言标注为 mermaid：

mermaid

graph TD    A[MDX 文件] --> B[remark 插件]    B --> C[rehype 插件]    C --> D[Shiki 语法高亮]    D --> E[MDX 组件渲染]    E --> F[最终页面]

实际效果：

mermaid

graph TD    A[MDX 文件] --> B[remark 插件]    B --> C[rehype 插件]    C --> D[Shiki 语法高亮]    D --> E[MDX 组件渲染]    E --> F[最终页面]

八、Embed — 外部内容嵌入

将外部平台的视频、音乐、社交媒体等内容直接嵌入页面，自动将原始链接转换为可嵌入的 iframe 地址。

jsx

<Embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="示例视频" /><Embed url="https://player.bilibili.com/player.html?bvid=BV1GJ411x7h7" title="Bilibili 视频" /><Embed url="https://music.163.com/#/song?id=186016" title="网易云音乐" height="80px" />

支持的平台

分类	平台
视频	Bilibili、YouTube、Vimeo、TikTok、优酷、爱奇艺、Loom、Twitch
社交	Twitter/X、Reddit
音乐	Spotify、Apple Music、SoundCloud、网易云音乐、QQ音乐
开发	CodeSandbox、StackBlitz、GitHub Gist
设计	Figma、Canva
演示	Google Slides、SlideShare

通过 aspect 属性设置宽高比（默认 16/9），或用 height 设置固定高度。

九、数学公式

基于 KaTeX 实现数学公式渲染，支持行内和块级两种。

行内公式：

质能方程 $E = mc^2$ 是物理学中最著名的公式之一。

欧拉公式 $e^{i\pi} + 1 = 0$ 被誉为最美的数学公式。

块级公式：

\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{(x-\mu)^2}{2\sigma^2}}

十、ImageZoom — 图片点击放大

ImageZoom 包装图片，支持点击放大查看，基于 react-medium-image-zoom 实现。

jsx

<ImageZoom>  <img src="https://example.com/image.png" alt="可放大的图片" /></ImageZoom>

点击图片后会以模态框形式展示大图，点击空白区域或按 ESC 键关闭。

十一、标题自动锚点

所有 h2、h3 标题会自动生成锚点 ID，并在鼠标悬停时显示 🔗 链接图标。点击图标可复制当前标题的 URL 锚点。

将鼠标悬停到本文档的任何 h2 或 h3 标题上，左侧会出现链接图标。

如需自定义锚点 ID，可使用 Heading 组件：

jsx

<Heading level={2} id="custom-anchor">自定义锚点标题</Heading>

十二、PrevNext — 上下篇导航

jsx

<PrevNext  prev={{ title: "上一篇标题", href: "/posts/prev" }}  next={{ title: "下一篇标题", href: "/posts/next" }}/>

只设置单侧时也正常工作：

jsx

<PrevNext next={{ title: "下一篇", href: "/posts/next" }} />

实际效果示例：

十三、LastUpdated — 最后更新时间

显示文档的最后更新时间，可选标注作者。

jsx

<LastUpdated date="2026-05-07" /><LastUpdated date="2026-05-07" author="iflux" />

实际效果：

最后更新：2026年5月7日 · iflux

十四、HTML 元素覆盖

以下组件覆盖了原生 HTML 标签，在 MDX 中使用对应的 Markdown 语法即可自动生效。

链接 — MDXLink

普通 Markdown 链接语法即可，内部链接走 Next.js 客户端导航，外部链接自动在新标签页打开并显示外链图标。

内部链接 — 使用 Next.js Link 组件，不会整页刷新。

外部链接 — 自动在新标签页打开，并显示外链图标。

图片 — MDXImg

标准 Markdown 图片语法，基于 Next.js Image 自动优化（懒加载、响应式尺寸）。alt 中包含 "hero" 或 "cover" 的图片会自动预加载。

引用块 — MDXBlockquote

标准 Markdown 引用语法，自动添加引用图标和左侧边框。

这是一段普通引用文字，带有左侧边框和引用图标。

键盘按键 — MDXKbd

使用 HTML <kbd> 标签：

快捷键：Ctrl + C 复制，Ctrl + V 粘贴，Ctrl + S 保存。macOS 上使用 Cmd 键。

代码块

标准 Markdown 代码块和行内代码语法，构建时通过 Shiki 自动注入语法高亮。代码块标题栏显示语言标签和复制按钮。

行内代码使用反引号：npm install 安装依赖。

基础代码块

语言标签自动显示在标题栏：

bash

pnpm installpnpm dev

typescript

interface Config {  port: number;  host: string;  debug: boolean;}const config: Config = {  port: 3000,  host: "localhost",  debug: false,};

文件名标题

在代码块元数据中使用 title="..." 指定文件名，会显示在标题栏替代语言标签：

server.ts

import { serve } from "bun";serve({  fetch(req) {    return new Response("Hello");  },  port: 3000,});

行高亮

使用 Shiki 的 notation 语法在代码注释中高亮指定行：

// [!code highlight] 或 // [!code hl] — 高亮单行
// [!code highlight:3] — 高亮当前行及接下来 2 行

const a = 1;const b = 2;const c = 3; const d = 4;

Diff 注解

使用 // [!code ++] 和 // [!code --] 标记新增和删除的行：

const framework = "Next.js";const bundler = "Turbopack"; const bundler = "Webpack"; const runtime = "Bun";

行聚焦

使用 // [!code focus] 聚焦特定行，其他行变暗：

import { Button } from "@iflux/ui"; export default function Page() {  return <Button>点击</Button>;}

列表

标准 Markdown 列表语法，统一的间距和缩进样式：

第一项内容
第二项内容
- 嵌套子项
- 另一个子项
第三项内容

第一步操作
第二步操作
第三步操作

表格

标准 Markdown 表格语法，自动添加圆角边框和悬停高亮：

组件	类型	说明
Callout	提示卡片	信息/警告/错误提示
Steps	步骤指引	有先后顺序的流程
Accordion	折叠面板	手风琴式折叠
Badge	状态徽章	版本/状态标签
Card	卡片	链接或信息块
Tabs	标签页	通用标签切换
Tree	树形结构	文件目录展示
Mermaid	图表	流程图/时序图
Embed	内容嵌入	外部平台嵌入

分隔线

标准 Markdown 分隔线语法 --- 即可。

组件速查表

组件	用途	示例
Callout	提示/警告/错误卡片	`<Callout type="info" title="标题">`
Badge	状态徽章/标签	`<Badge variant="info">`
Steps / Step	步骤指引流程	`<Steps><Step title="...">`
Accordion / AccordionItem	手风琴折叠面板	`<Accordion><AccordionItem title="...">`
Card / CardGrid	卡片布局	`<CardGrid cols={3}><Card title="...">`
Tree / TreeItem	树形目录结构	`<Tree><TreeItem name="..." type="folder">`
Mermaid	图表渲染	```mermaid 代码块
Embed	外部内容嵌入	`<Embed url="...">`
ImageZoom	图片点击放大	`<ImageZoom>`

总结

所有交互型组件通过 JSX 标签 调用；HTML 元素覆盖类组件（链接、图片、代码块、表格等）直接使用 标准 Markdown 语法 即可自动命中增强版本。无需额外学习成本。

iflux-next 项目包含 blog 和 docs 两个内容站点。MDX 让我们可以在 Markdown 中直接使用 React 组件，极大扩展了内容创作的可能性。

接下来按功能分类逐一说明每个组件的用法。

Frontmatter 字段参考

每篇文章的 frontmatter（YAML 头部）支持以下字段：

字段	类型	必填	说明
`title`	string	是	文章标题
`date`	string	否	发布日期，格式 `YYYY-MM-DD`
`description`	string	否	文章摘要，用于 SEO 和列表页
`excerpt`	string	否	文章简介，显示在列表卡片中
`category`	string	否	文章分类，显示在侧边栏和元信息中
`tags`	string[]	否	标签数组，用于筛选和相关推荐
`cover`	string	否	封面图 URL，显示在列表卡片和文章顶部
`draft`	boolean	否	设为 `true` 则不在列表中显示
`series`	string	否	系列名称，同系列文章自动组织为教程
`seriesOrder`	number	否	在系列中的排序，数字越小越靠前

文章系列（series）

将多篇相关文章组织为教程系列：

yaml

---title: "第一章：环境搭建"series: "Next.js 全栈教程"seriesOrder: 1---

yaml

---title: "第二章：数据库设计"series: "Next.js 全栈教程"seriesOrder: 2---

设置了相同 series 的文章会自动：

在文章底部显示系列导航（进度条 + 文章列表 + 上下篇跳转）
在首页按系列分组展示
在归档页显示系列标签

一、Badge — 状态徽章

Badge 用于标注版本、状态、标签等信息，支持多种颜色变体。

jsx

<Badge>默认</Badge><Badge variant="info">信息</Badge><Badge variant="success">成功</Badge><Badge variant="warning">警告</Badge><Badge variant="danger">危险</Badge><Badge variant="outline">边框</Badge>

实际效果：

默认信息成功警告危险边框

支持的 variant 值：

值	效果
`default`	灰色（默认）
`info`	蓝色
`success`	绿色
`warning`	黄色
`danger`	红色
`outline`	无背景，仅边框

Badge 常用于标注文章版本、API 状态、功能标签等场景：

React 19 稳定版
Bun 1.3 推荐
Node.js 23 实验性
Python 2 已废弃

二、Callout — 提示卡片

Callout 用于在内容中插入醒目的提示信息。

jsx

<Callout type="info" title="自定义标题">这是通过 JSX 标签创建的提示卡片。</Callout><Callout type="tip">这是一条没有标题的提示，只显示图标和内容。</Callout>

实际效果：

自定义标题

这是通过 JSX 标签创建的提示卡片。

这是一条没有标题的提示，只显示图标和内容。

注意事项

这是一条警告，用于提醒读者注意潜在问题。

错误提示

这是一条错误提示，用于标记不可操作或危险的内容。

操作成功

这是一条成功提示，用于确认操作已完成。

支持的类型

type 属性	效果
`info`	蓝色信息提示
`tip`	紫色技巧提示
`warning`	黄色警告提示
`error`	红色错误提示
`success`	绿色成功提示

三、Steps / Step — 步骤指引

Steps 组件用于展示有先后顺序的操作流程。

jsx

<Steps><Step title="安装依赖">使用包管理器安装项目依赖：    pnpm install</Step><Step title="配置环境变量">复制 `.env.example` 为 `.env.local`，填入必要的配置项。</Step><Step title="启动开发服务器">运行 `pnpm dev`，访问 http://localhost:3000 查看效果。</Step></Steps>

实际效果：

安装依赖

使用包管理器安装项目依赖：

pnpm install

配置环境变量

复制 .env.example 为 .env.local，填入必要的配置项。

启动开发服务器

运行 pnpm dev，访问 http://localhost:3000 查看效果。

Step 组件支持 completed 属性，已完成步骤会显示勾号：

已完成

这个步骤已经完成，会显示绿色勾号。

当前步骤

这是当前正在进行的步骤。

四、Accordion — 手风琴折叠

Accordion 用于可折叠的内容区域，适合 FAQ、可选阅读等场景。

jsx

<Accordion><AccordionItem title="什么是 MDX？">MDX 是 Markdown 的超集，允许在 Markdown 文档中直接使用 JSX 组件。</AccordionItem><AccordionItem title="为什么要自定义组件？">原生 Markdown 只支持有限的 HTML 标签，无法实现复杂交互。通过自定义组件，可以统一设计语言、增强内容表现力。</AccordionItem></Accordion>

实际效果：

MDX 是 Markdown 的超集，允许在 Markdown 文档中直接使用 JSX 组件。

原生 Markdown 只支持有限的 HTML 标签，无法实现复杂交互。通过自定义组件，可以统一设计语言、增强内容表现力。

多个折叠面板默认只展开一个（手风琴模式），支持同时展开多个。

五、Card / CardGrid — 卡片布局

卡片组件用于展示链接或信息块，CardGrid 提供响应式网格容器。

jsx

<CardGrid cols={3}><Card title="Next.js" description="React 全栈框架，支持 SSR、SSG 和 App Router。" href="https://nextjs.org" external /><Card title="Tailwind CSS" description="实用优先的 CSS 框架，快速构建自定义设计。" href="https://tailwindcss.com" external /><Card title="shadcn/ui" description="可复用的 UI 组件，基于 @base-ui/react 和 Tailwind CSS。" href

实际效果：

Next.js

React 全栈框架，支持 SSR、SSG 和 App Router。

Tailwind CSS

实用优先的 CSS 框架，快速构建自定义设计。

shadcn/ui

可复用的 UI 组件，基于 @base-ui/react 和 Tailwind CSS。

CardGrid 的 cols 属性控制列数（默认 2，最大 4），响应式自动适配。设置 external 属性时外部链接自动在新标签页打开。

六、Tree / TreeItem — 树形结构

用于展示文件目录或层级关系，自动根据嵌套计算缩进。

jsx

<Tree><TreeItem name="iflux-next" type="folder">  <TreeItem name="apps" type="folder">    <TreeItem name="blog" type="folder">      <TreeItem name="src" type="folder"

实际效果：

iflux-next

apps

blog

src

app

components

content

package.json

docs

文件夹以蓝色图标显示并加粗，文件以灰色图标显示。嵌套层级自动递增缩进。

七、Mermaid — 图表渲染

支持在 MDX 中使用 Mermaid 语法绘制流程图、时序图、甘特图等，自动跟随主题切换明暗。

直接写 Mermaid 代码块，语言标注为 mermaid：

mermaid

graph TD    A[MDX 文件] --> B[remark 插件]    B --> C[rehype 插件]    C --> D[Shiki 语法高亮]    D --> E[MDX 组件渲染]    E --> F[最终页面]

实际效果：

mermaid

graph TD    A[MDX 文件] --> B[remark 插件]    B --> C[rehype 插件]    C --> D[Shiki 语法高亮]    D --> E[MDX 组件渲染]    E --> F[最终页面]

八、Embed — 外部内容嵌入

将外部平台的视频、音乐、社交媒体等内容直接嵌入页面，自动将原始链接转换为可嵌入的 iframe 地址。

jsx

<Embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="示例视频" /><Embed url="https://player.bilibili.com/player.html?bvid=BV1GJ411x7h7" title="Bilibili 视频" /><Embed url="https://music.163.com/#/song?id=186016" title="网易云音乐" height="80px" />

支持的平台

分类	平台
视频	Bilibili、YouTube、Vimeo、TikTok、优酷、爱奇艺、Loom、Twitch
社交	Twitter/X、Reddit
音乐	Spotify、Apple Music、SoundCloud、网易云音乐、QQ音乐
开发	CodeSandbox、StackBlitz、GitHub Gist
设计	Figma、Canva
演示	Google Slides、SlideShare

通过 aspect 属性设置宽高比（默认 16/9），或用 height 设置固定高度。

九、数学公式

基于 KaTeX 实现数学公式渲染，支持行内和块级两种。

行内公式：

质能方程 $E = mc^2$ 是物理学中最著名的公式之一。

欧拉公式 $e^{i\pi} + 1 = 0$ 被誉为最美的数学公式。

块级公式：

\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{(x-\mu)^2}{2\sigma^2}}

十、ImageZoom — 图片点击放大

ImageZoom 包装图片，支持点击放大查看，基于 react-medium-image-zoom 实现。

jsx

<ImageZoom>  <img src="https://example.com/image.png" alt="可放大的图片" /></ImageZoom>

点击图片后会以模态框形式展示大图，点击空白区域或按 ESC 键关闭。

十一、标题自动锚点

所有 h2、h3 标题会自动生成锚点 ID，并在鼠标悬停时显示 🔗 链接图标。点击图标可复制当前标题的 URL 锚点。

将鼠标悬停到本文档的任何 h2 或 h3 标题上，左侧会出现链接图标。

如需自定义锚点 ID，可使用 Heading 组件：

jsx

<Heading level={2} id="custom-anchor">自定义锚点标题</Heading>

十二、PrevNext — 上下篇导航

jsx

<PrevNext  prev={{ title: "上一篇标题", href: "/posts/prev" }}  next={{ title: "下一篇标题", href: "/posts/next" }}/>

只设置单侧时也正常工作：

jsx

<PrevNext next={{ title: "下一篇", href: "/posts/next" }} />

实际效果示例：

十三、LastUpdated — 最后更新时间

显示文档的最后更新时间，可选标注作者。

jsx

<LastUpdated date="2026-05-07" /><LastUpdated date="2026-05-07" author="iflux" />

实际效果：

最后更新：2026年5月7日 · iflux

十四、HTML 元素覆盖

以下组件覆盖了原生 HTML 标签，在 MDX 中使用对应的 Markdown 语法即可自动生效。

链接 — MDXLink

普通 Markdown 链接语法即可，内部链接走 Next.js 客户端导航，外部链接自动在新标签页打开并显示外链图标。

内部链接 — 使用 Next.js Link 组件，不会整页刷新。

外部链接 — 自动在新标签页打开，并显示外链图标。

图片 — MDXImg

标准 Markdown 图片语法，基于 Next.js Image 自动优化（懒加载、响应式尺寸）。alt 中包含 "hero" 或 "cover" 的图片会自动预加载。

引用块 — MDXBlockquote

标准 Markdown 引用语法，自动添加引用图标和左侧边框。

这是一段普通引用文字，带有左侧边框和引用图标。

键盘按键 — MDXKbd

使用 HTML <kbd> 标签：

快捷键：Ctrl + C 复制，Ctrl + V 粘贴，Ctrl + S 保存。macOS 上使用 Cmd 键。

代码块

标准 Markdown 代码块和行内代码语法，构建时通过 Shiki 自动注入语法高亮。代码块标题栏显示语言标签和复制按钮。

行内代码使用反引号：npm install 安装依赖。

基础代码块

语言标签自动显示在标题栏：

bash

pnpm installpnpm dev

typescript

interface Config {  port: number;  host: string;  debug: boolean;}const config: Config = {  port: 3000,  host: "localhost",  debug: false,};

文件名标题

在代码块元数据中使用 title="..." 指定文件名，会显示在标题栏替代语言标签：

server.ts

import { serve } from "bun";serve({  fetch(req) {    return new Response("Hello");  },  port: 3000,});

行高亮

使用 Shiki 的 notation 语法在代码注释中高亮指定行：

// [!code highlight] 或 // [!code hl] — 高亮单行
// [!code highlight:3] — 高亮当前行及接下来 2 行

const a = 1;const b = 2;const c = 3; const d = 4;

Diff 注解

使用 // [!code ++] 和 // [!code --] 标记新增和删除的行：

const framework = "Next.js";const bundler = "Turbopack"; const bundler = "Webpack"; const runtime = "Bun";

行聚焦

使用 // [!code focus] 聚焦特定行，其他行变暗：

import { Button } from "@iflux/ui"; export default function Page() {  return <Button>点击</Button>;}

列表

标准 Markdown 列表语法，统一的间距和缩进样式：

第一项内容
第二项内容
- 嵌套子项
- 另一个子项
第三项内容

第一步操作
第二步操作
第三步操作

表格

标准 Markdown 表格语法，自动添加圆角边框和悬停高亮：

组件	类型	说明
Callout	提示卡片	信息/警告/错误提示
Steps	步骤指引	有先后顺序的流程
Accordion	折叠面板	手风琴式折叠
Badge	状态徽章	版本/状态标签
Card	卡片	链接或信息块
Tabs	标签页	通用标签切换
Tree	树形结构	文件目录展示
Mermaid	图表	流程图/时序图
Embed	内容嵌入	外部平台嵌入

分隔线

标准 Markdown 分隔线语法 --- 即可。

组件速查表

组件	用途	示例
Callout	提示/警告/错误卡片	`<Callout type="info" title="标题">`
Badge	状态徽章/标签	`<Badge variant="info">`
Steps / Step	步骤指引流程	`<Steps><Step title="...">`
Accordion / AccordionItem	手风琴折叠面板	`<Accordion><AccordionItem title="...">`
Card / CardGrid	卡片布局	`<CardGrid cols={3}><Card title="...">`
Tree / TreeItem	树形目录结构	`<Tree><TreeItem name="..." type="folder">`
Mermaid	图表渲染	```mermaid 代码块
Embed	外部内容嵌入	`<Embed url="...">`
ImageZoom	图片点击放大	`<ImageZoom>`

总结

Frontmatter 字段参考

文章系列（series）

一、Badge — 状态徽章

二、Callout — 提示卡片

支持的类型

三、Steps / Step — 步骤指引

四、Accordion — 手风琴折叠

五、Card / CardGrid — 卡片布局

六、Tree / TreeItem — 树形结构

七、Mermaid — 图表渲染

八、Embed — 外部内容嵌入

支持的平台

九、数学公式

十、ImageZoom — 图片点击放大

十一、标题自动锚点

十二、PrevNext — 上下篇导航

十三、LastUpdated — 最后更新时间

十四、HTML 元素覆盖

链接 — MDXLink

图片 — MDXImg

引用块 — MDXBlockquote

键盘按键 — MDXKbd

代码块

基础代码块

文件名标题

行高亮

Diff 注解

行聚焦

列表

表格

分隔线

组件速查表

项目说明

Frontmatter 字段参考

文章系列（series）

一、Badge — 状态徽章

二、Callout — 提示卡片

支持的类型

三、Steps / Step — 步骤指引

四、Accordion — 手风琴折叠

五、Card / CardGrid — 卡片布局

六、Tree / TreeItem — 树形结构

七、Mermaid — 图表渲染

八、Embed — 外部内容嵌入

支持的平台

九、数学公式

十、ImageZoom — 图片点击放大

十一、标题自动锚点

十二、PrevNext — 上下篇导航

十三、LastUpdated — 最后更新时间

十四、HTML 元素覆盖

链接 — MDXLink

图片 — MDXImg

引用块 — MDXBlockquote

键盘按键 — MDXKbd

代码块

基础代码块

文件名标题

行高亮

Diff 注解

行聚焦

列表

表格

分隔线

组件速查表