MDX 组件完整指南

组件总览

博客提供 20+ 个自定义 MDX 组件，涵盖代码展示、交互、嵌入、数学公式等场景。

标题 (H1-H6)

MDX 中的标题会自动生成锚点 ID，支持中英文。

## 二级标题
### 三级标题
#### 四级标题

标题 ID 规则：移除特殊字符，中文保留，空格替换为连字符。例如 ## MDX 组件 生成 ID mdx-组件。

Callout

不带标题的 Callout：

Steps

MDXTabs

CodeGroup

CodeGroup 会自动为每个代码块添加文件名标签页：

Accordion / Accordions

单个折叠面板：

多个折叠面板：

Mermaid

流程图示例：

时序图示例：

Tree

MDXTable

MDXKbd

按 Ctrl + C 复制，按 Cmd + K 打开命令面板。

MDXCard

卡片组：

MDXBlockquote

引用标准 MDX 语法即可：

好的代码本身就是文档，清晰的命名就是最好的注释。

带链接的引用：

学习 MDX 最好的方式是写一个博客来实践它。—— MDX 官方

MDXHr

分隔线用于分隔内容区域：

上面是第一段内容。

下面是第二段内容。

MDXCode

独立的代码展示框（非代码块）：

运行状态

pnpm dev

MDXPre

代码块会自动添加标题栏和复制按钮：

function greet(name: string) {
  console.log("Hello, " + name + "!")
}

greet("World")

def fibonacci(n: int) -> int:
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

MDXLink

链接分为内部链接和外部链接：

• 内部链接：博客首页 会自动使用 Next.js Link 组件
• 外部链接：React 官网 会添加外部链接标记和新窗口打开

直接写普通链接即可，会自动使用 MDXLink 组件。

MDXImg

图片自动支持懒加载：

MDXEmbed

嵌入外部内容，自动识别平台并生成 iframe：

视频

YouTube 视频：

Bilibili 视频：

Vimeo 视频：

开发工具

CodeSandbox 项目：

StackBlitz 项目：

支持的平台

MDXMathInline

行内数学公式使用 <MDXMathInline> 组件：

质能方程 $E = mc^2$，正态分布 $\frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}$ 是统计学中最重要的公式之一。

MDXMathBlock

块级数学公式使用 <MDXMathBlock> 组件：

高斯积分的完整推导：

矩阵运算示例：

列表 (ul/ol/li)

无序列表：

• 第一项
• 第二项
  • 嵌套项一
  • 嵌套项二
• 第三项

有序列表：

1. 第一步：安装依赖
2. 第二步：配置环境变量
3. 第三步：启动开发服务器

混合列表：

1. 前端
   • React
   • Vue
   • Svelte
2. 后端
   • Node.js
   • Python
   • Rust

最佳实践

代码块嵌套

当在 CodeGroup 里展示代码块时，直接使用三个反引号即可。但如果你想在文档中展示 "包含代码块的 CodeGroup 示例本身"，需要使用更多反引号包裹外层（例如 4 或 5 个），这样内部的 3 个反引号才被当作代码内容。

示例写法结构示意：

• 外层：用 4+ 个反引号开始
• 内部：正常写 3 个反引号的代码块
• 结尾：用与开头相同数量的反引号闭合

Math 语法注意

• 行内公式使用 <MDXMathInline math="..." />
• 块级公式使用 <MDXMathBlock math="..." />
• 不要用 $...$ 语法，其中的 {} 字符会被 MDX 解析为 JSX 表达式

组件选择指南