MDX 语法

MDX 是 Markdown 的扩展，允许在文档中直接使用 JSX 组件，实现更丰富的交互体验。

什么是 MDX

MDX = Markdown + JSX。它让你可以在 Markdown 文档中：

导入和使用 React 组件
编写内联 JSX 代码
在组件中嵌入 Markdown 内容

基础语法

导入组件

在文档顶部（frontmatter 之后）导入需要的组件：

---
title: 我的文档
description: 我的文档简介
icon: PenTool
---

import { Button } from '@/components/ui/button';
import { Briefcase, Layers } from 'lucide-react';

Frontmatter 配置

MDX 文件顶部的 YAML 配置：

---
title: 页面标题          # 必填，显示在侧边栏和页面顶部
description: 页面描述    # 可选，用于 SEO 和预览
icon: Home              # 可选，侧边栏图标（Lucide 图标名）
full: true              # 可选，全宽布局
---

Lucide 图标库

项目集成了 Lucide 图标库，可直接导入使用：

import { Home, Settings, User, Search, Mail } from 'lucide-react';

<Home className="w-6 h-6" />
<Settings className="w-6 h-6 text-blue-500" />

常用图标：Home Settings User Search Mail Info AlertCircle CheckCircle XCircle Briefcase Layers Terminal Sparkles

组件内嵌 Markdown

组件内容支持 Markdown 语法：

<Callout>
  这是一段**加粗**的提示文字，支持 `代码` 和 [链接](https://example.com)
</Callout>

Fumadocs 内置组件

本项目基于 Fumadocs 构建，以下是常用的内置组件：

Callout 提示框

用于高亮显示重要信息：

<Callout title="提示框" type="info">
  默认提示框内容。这是一段**加粗**的提示文字，支持 `代码` 和 [链接](https://example.com)
</Callout>

<Callout title="警告框" type="warn">
  警告类型提示框。这是一段**加粗**的提示文字，支持 `代码` 和 [链接](https://example.com)
</Callout>

<Callout title="错误框" type="error">
  错误类型提示框。这是一段**加粗**的提示文字，支持 `代码` 和 [链接](https://example.com)
</Callout>

提示框

默认提示框内容。这是一段加粗的提示文字，支持 代码 和链接

警告框

警告类型提示框。这是一段加粗的提示文字，支持 代码 和链接

错误框

错误类型提示框。这是一段加粗的提示文字，支持 代码 和链接

Cards 卡片组

用于展示导航或功能入口：

import { Briefcase, Layers, Terminal } from 'lucide-react';

<Cards>
  <Card icon={<Briefcase />} title="办公系统" href="/docs/corp-wiki/000SystemIntroduction">
    新人入职指引与办公常用流程
  </Card>
  <Card icon={<Layers />} title="业务系统" href="/docs/corp-wiki/011AssetLeasing">
    公司核心业务系统操作指南
  </Card>
  <Card icon={<Terminal />} title="IT 专用" href="/docs/corp-wiki/021ITFAQ">
    技术规范与 IT 运维文档
  </Card>
</Cards>

办公系统

新人入职指引与办公常用流程

业务系统

公司核心业务系统操作指南

IT 专用

技术规范与 IT 运维文档

Tabs 选项卡

用于展示多种同类内容：

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

<Tabs items={['npm', 'pnpm', 'yarn']}>
  <Tab value="npm">
    ```bash
    npm install package-name
    ```
  </Tab>
  <Tab value="pnpm">
    ```bash
    pnpm add package-name
    ```
  </Tab>
  <Tab value="yarn">
    ```bash
    yarn add package-name
    ```
  </Tab>
</Tabs>

npm install package-name

pnpm add package-name

yarn add package-name

Steps 步骤

用于展示操作步骤：

<Steps>
  <Step>
    #### 安装依赖
    运行 `pnpm install` 安装项目依赖
  </Step>
  <Step>
    #### 启动开发服务器
    运行 `pnpm dev` 启动本地开发环境
  </Step>
  <Step>
    #### 构建项目
    运行 `pnpm build` 构建生产版本
  </Step>
</Steps>

安装依赖

运行 pnpm install 安装项目依赖

启动开发服务器

运行 pnpm dev 启动本地开发环境

构建项目

运行 pnpm build 构建生产版本

Files 文件树

用于展示目录结构：

<Files>
  <Folder name="src" defaultOpen>
    <Folder name="components">
      <File name="Button.tsx" />
      <File name="Card.tsx" />
    </Folder>
    <Folder name="pages">
      <File name="index.tsx" />
    </Folder>
    <File name="App.tsx" />
  </Folder>
  <File name="package.json" />
</Files>

App.tsx

package.json

Accordion 折叠面板

用于展示可折叠内容：

<Accordions>
  <Accordion title="什么是 MDX？">
    MDX 是 Markdown 的扩展，支持在文档中使用 JSX 组件。
  </Accordion>
  <Accordion title="如何安装？">
    运行 `pnpm add @mdx-js/mdx` 安装 MDX 支持。
  </Accordion>
</Accordions>

图片加 Wrapper

<Wrapper>
![](/ai-lab/001.png)
</Wrapper>

代码块高级功能

添加标题

为代码块添加文件名或标题：

```js title="next.config.js"
const config = {
  reactStrictMode: true,
};
```

next.config.js

const config = {
  reactStrictMode: true,
};

高亮指定行

使用 // [!code highlight] 高亮某一行：

```tsx
<div>普通行</div>
<div>高亮行</div>  `// [!code highlight]`
<div>普通行</div>
```

<div>普通行</div>
<div>高亮行</div>  
<div>普通行</div>

高亮指定单词

使用 // [!code word:关键词] 高亮特定单词：

```js
`// [!code word:config]`
const config = {
  reactStrictMode: true,
};
```

const config = {
  reactStrictMode: true,
};

显示代码差异

使用 // [!code ++] 和 // [!code --] 显示增删：

```ts
console.log('旧代码');  `// [!code --]`
console.log('新代码');  `// [!code ++]`
```

console.log('旧代码');  
console.log('新代码');

注意事项

组件名大写：JSX 组件名必须以大写字母开头
属性用花括号：传递 JS 表达式需用 {}，如 icon={<Home />}
自闭合标签：无内容的组件使用自闭合，如 <InlineTOC />
空行分隔：组件与 Markdown 内容之间需要空行
导入位置：import 语句必须在 frontmatter 之后、内容之前