【MDX】 Markdown 和 JSX 融合

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

✍️ MDX 核心语法

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

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

import { Button } from './components/Button' # 这是一个普通的Markdown标题 你可以像使用HTML标签一样使用这个按钮组件： <Button>点我</Button>

✨ 关键特性

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

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

🚀 常见应用场景

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

1. 技术文档/博客：为文档嵌入实时交互的Demo、代码示例。几个主流框架都有成熟的解决方案：

   • Next.js: 官方通过@next/mdx提供了完整的支持，配置后可以直接将.mdx文件当作页面使用。
   • Rspress: 基于 Rspack 的静态站点生成器，对 MDX 有天然支持，适合构建高性能文档站。

2. UI 组件库文档：用 MDX 来编写组件文档，可以一边写文档一边展示组件，甚至能直接编辑代码并预览效果。像Docz、Storybook等工具都利用了 MDX 的这一特性，让组件库文档变得生动起来。

⚙️ 以 Next.js 为例的配置

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

1. 安装依赖：

   npminstall@next/mdx @mdx-js/loader @mdx-js/react @types/mdx

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

   importcreateMDXfrom'@next/mdx'constnextConfig={pageExtensions:['js','jsx','md','mdx','ts','tsx'],}constwithMDX=createMDX()exportdefaultwithMDX(nextConfig)

3. 创建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 内容提供了一种非常强大的模式。它让前端开发者能够更高效地创建出既内容详实又功能丰富的页面。