【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 在前端开发中最常见的舞台是构建技术文档站点和组件演示库技术文档/博客为文档嵌入实时交互的Demo、代码示例。几个主流框架都有成熟的解决方案Next.js: 官方通过next/mdx提供了完整的支持配置后可以直接将.mdx文件当作页面使用。Rspress: 基于 Rspack 的静态站点生成器对 MDX 有天然支持适合构建高性能文档站。UI 组件库文档用 MDX 来编写组件文档可以一边写文档一边展示组件甚至能直接编辑代码并预览效果。像Docz、Storybook等工具都利用了 MDX 的这一特性让组件库文档变得生动起来。⚙️ 以 Next.js 为例的配置以 Next.js 为例一个基础的 MDX 配置通常包含以下几步安装依赖npminstallnext/mdx mdx-js/loader mdx-js/react types/mdx修改next.config.mjs引入next/mdx插件并将mdx添加到pageExtensions中。importcreateMDXfromnext/mdxconstnextConfig{pageExtensions:[js,jsx,md,mdx,ts,tsx],}constwithMDXcreateMDX()exportdefaultwithMDX(nextConfig)创建mdx-components.tsx在项目根目录创建此文件用于定义全局的 MDX 组件如自定义的h1、img等这是 App Router 模式下必须的步骤。完成这些设置后你就可以在app目录下创建.mdx文件它会自动成为一个页面路由。 注意事项使用 MDX 时有几个细节需要注意文件后缀默认情况下只有.mdx文件会被编译。如果需要处理.md文件需要额外配置。Frontmatternext/mdx默认不支持 Frontmatter文件开头的---区域。你可以使用remark-frontmatter等插件来解析它。语法差异MDX 是 Markdown 和 JSX 的混合体所以一些纯 Markdown 的语法可能不适用例如缩进代码块和自动链接在 MDX 中是不支持的。MDX 通过将 Markdown 的易写性与 React 的灵活性相结合为构建现代 Web 内容提供了一种非常强大的模式。它让前端开发者能够更高效地创建出既内容详实又功能丰富的页面。