🧩 MDX 组件库

Hey，同学！想让文档更「好看」更「好用」吗？这一篇给你详细介绍 Docs 提供的 MDX 组件库～ 🎨

🤔 什么是 MDX 组件？

MDX 组件是在 Markdown 中可以使用的 React 组件。它们让文档不再只是「文字」，而是「交互式内容」！

📦 可用组件一览

1. Callout 提示框

用途：突出重要信息

{"<"}Callout type="info">
  这是一个信息提示，用于补充说明。
{"<"}/Callout>

{"<"}Callout type="warning">
  这是一个警告，提示需要注意。
{"<"}/Callout>

{"<"}Callout type="error">
  这是一个错误提示，说明出了问题。
{"<"}/Callout>

{"<"}Callout type="success">
  这是一个成功提示，说明操作成功。
{"<"}/Callout>

类型：

2. Steps 步骤条

用途：展示步骤流程

{"<"}Steps>
  {"<"}Step>
    第一步：安装依赖

    ```bash
    pnpm install

/Step> Step> 第二步：配置环境

创建 .env 文件... /Step> Step> 第三步：启动项目

pnpm dev

/Step> /Steps>

---

### 3. MDXTabs 标签页

**用途**：对比不同选项（如不同操作系统）

MDXTabs> MDXTab label="macOS">

macOS 安装

brew install node

/MDXTab> MDXTab label="Windows">

Windows 安装

winget install NodeJS

/MDXTab> MDXTab label="Linux">

Linux 安装

sudo apt install nodejs

/MDXTab> /MDXTabs>

---

### 4. CodeGroup 代码组

**用途**：多个代码片段对比展示

CodeGroup> MDXTab label="pnpm">

pnpm add package

/MDXTab> MDXTab label="npm">

npm install package

/MDXTab> MDXTab label="yarn">

yarn add package

/MDXTab> /CodeGroup>

---

### 5. Tree 树形结构

**用途**：展示文件/目录结构

Tree> TreeItem label="src/"> TreeItem label="app/"> TreeItem label="page.tsx" /} TreeItem label="layout.tsx" /} /TreeItem> TreeItem label="components/"> TreeItem label="Button.tsx" /} TreeItem label="Card.tsx" /} /TreeItem> /TreeItem> /Tree>

---

### 6. Mermaid 图表

**用途**：用文本绘制图表

mermaid> graph TD A[开始] --> B B -->|是| C[执行A] B -->|否| D[执行B] C --> E[结束] D --> E /mermaid>

**支持类型**：
- 流程图 (graph)
- 时序图 (sequenceDiagram)
- 类图 (classDiagram)
- 状态图 (stateDiagram)
- 甘特图 (gantt)

---

### 7. Accordion / Accordions 手风琴

**用途**：可折叠的详细信息

Accordions> Accordion title="点击查看更多"> 这里是隐藏的内容... /Accordion> Accordion title="另一个可折叠项"> 更多的内容... /Accordion> /Accordions>

---

### 8. Card / CardGrid 卡片

**用途**：展示信息卡片

MDXCardGrid> MDXCard title="快速开始" href="/docs/quick-start"> 5分钟快速上手 /MDXCard> MDXCard title="MDX 组件" href="/docs/components"> 组件使用指南 /MDXCard> /MDXCardGrid>

---

### 9. Embed 嵌入

**用途**：嵌入视频、网页等

MDXEmbed url="https://www.youtube.com/watch?v=xxxxx" />

---

### 10. Kbd 键盘按键

**用途**：展示键盘快捷键

```mdx
按 <kbd>Ctrl</kbd> + <kbd>C</kbd> 复制

🎯 使用建议

1. 适度使用

组件很好，但不要滥用：

• 每个页面 2-3 个关键组件就够了
• 过多的组件会分散注意力

2. 内容优先

组件是「包装」，内容才是「内核」。先把文字写清楚，再考虑加组件。

3. 保持一致

在整个文档库中保持相同的组件使用风格。

🔧 自定义组件

如果需要自定义组件，可以在：

apps/docs/src/components/mdx/mdx-components.tsx

中添加自定义组件。

📖 下一步

• 分类管理 —— 组织文档结构
• 导航配置 —— 配置搜索和导航
• SEO 优化 —— 让文档更容易被找到