【MDX】 Markdown 和 JSX 融合

MDX 是一种将 Markdown 和 JSX 融合在一起的格式，它让你能在Markdown文档里直接使用React等框架的组件。这为编写交互式的技术文档、博客和组件库文档带来了全新的可能性。

✍️ MDX 核心语法

你可以在一个 .mdx 文件中同时使用Markdown和JSX。

Markdown 的简洁：像写普通文档一样，使用标题、列表、链接等语法。
JSX 的强大 ：通过 import 引入React组件，并像使用HTML标签一样在Markdown中使用它们。

mdx 复制代码

import { Button } from './components/Button'

# 这是一个普通的Markdown标题

你可以像使用HTML标签一样使用这个按钮组件：

<Button>点我</Button>

✨ 关键特性

MDX 有几个非常实用的特性，能让你的内容创作更加灵活：

嵌入式 JavaScript 表达式 ：在花括号 {} 中直接写 JavaScript 表达式，比如 {1 + 1} 或 {Math.PI}。
ES Module 支持 ：使用 import 和 export 语句来管理依赖和数据。
组件复用与组合：这是 MDX 的核心优势。你可以把复杂的交互逻辑封装在组件里，然后在不同的 MDX 文件中反复使用，真正实现"内容与逻辑分离"。

🚀 常见应用场景

MDX 在前端开发中最常见的舞台是构建技术文档站点 和组件演示库：

技术文档/博客：为文档嵌入实时交互的Demo、代码示例。几个主流框架都有成熟的解决方案：
- Next.js : 官方通过 @next/mdx 提供了完整的支持，配置后可以直接将 .mdx 文件当作页面使用。
- Rspress: 基于 Rspack 的静态站点生成器，对 MDX 有天然支持，适合构建高性能文档站。
UI 组件库文档 ：用 MDX 来编写组件文档，可以一边写文档一边展示组件，甚至能直接编辑代码并预览效果。像 Docz 、Storybook 等工具都利用了 MDX 的这一特性，让组件库文档变得生动起来。

⚙️ 以 Next.js 为例的配置

以 Next.js 为例，一个基础的 MDX 配置通常包含以下几步：

安装依赖：

bash 复制代码

npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

修改 next.config.mjs ：引入 @next/mdx 插件，并将 mdx 添加到 pageExtensions 中。

js 复制代码

import createMDX from '@next/mdx'

const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
}

const withMDX = createMDX()
export default withMDX(nextConfig)

创建 mdx-components.tsx ：在项目根目录创建此文件，用于定义全局的 MDX 组件（如自定义的 h1、img 等），这是 App Router 模式下必须的步骤。

完成这些设置后，你就可以在 app 目录下创建 .mdx 文件，它会自动成为一个页面路由。

📝 注意事项

使用 MDX 时，有几个细节需要注意：

文件后缀 ：默认情况下，只有 .mdx 文件会被编译。如果需要处理 .md 文件，需要额外配置。
Frontmatter ：@next/mdx 默认不支持 Frontmatter（文件开头的 --- 区域）。你可以使用 remark-frontmatter 等插件来解析它。
语法差异 ：MDX 是 Markdown 和 JSX 的混合体，所以一些纯 Markdown 的语法可能不适用，例如缩进代码块 和自动链接在 MDX 中是不支持的。

MDX 通过将 Markdown 的易写性与 React 的灵活性相结合，为构建现代 Web 内容提供了一种非常强大的模式。它让前端开发者能够更高效地创建出既内容详实又功能丰富的页面。