JS Compiler

@next/mdx ：底层使用MDX (基于unified) 编译 MDX → JS

• 注册 MDX Loader
  • 内部调用 @mdx-js/loader（它再调用 @mdx-js/mdx）来把 .mdx 编译成 React 组件。
• 整合 Next.js 构建系统
  • 自动把 .mdx 文件纳入 Next.js 的编译和路由体系（包括热更新、SSR、静态生成）。
• 保留 Next.js 特性
  • 让 MDX 页面依然支持 getStaticProps / getServerSideProps 等 Next.js API。

MDX 源文件
   ↓ @mdx-js/mdx 解析（基于 micromark/remark）
MDAST (Markdown AST)
   ↓ mdast-util-to-hast（remark → rehype 过渡）
HAST (HTML AST)
   ↓ rehype 插件处理 HTML 节点
   ↓ hast-util-to-estree（HTML AST → JS AST）
JSX / React.createElement 代码
   ↓ 编译为 JS 模块
React 组件
   ↓ 使用 mdx-components.tsx 里提供的组件替换默认标签 
HTML DOM

Markdown (.md / .mdx)
  ↓ 解析（remark-parse / micromark；此处也会应用「语法类」remark 插件like remark-gfm）
MDAST（已生成）
  ↓ 「变换类」remark 插件在 MDAST 上运行（增删改节点, 锚点、TOC、链接重写）
  ↓ mdast-util-to-hast / remark-rehype
HAST
  ↓ rehype 插件在 HAST 上运行 (标签/属性/结构/代码高亮)
  ↓（hast-util-to-estree / to-jsx）
JSX / JS 模块（供 React 使用）

remark 和 rehype 都是 JavaScript 里的AST（抽象语法树）处理框架，但处理的对象和用途不同

Global styles and components

使用 mdx-components.tsx，映射发生在“编译成 JSX 之后、React 渲染之前/之中”

• 替换内置标签的渲染（比如把 h1、p、img 映射到你自己的组件/样式）
• 提供全局可用的组件名（俗称 shortcode），使 MDX 里可以直接写 <Callout/> 等而不额外 import，注入可用组件

Local styles and components

import Welcome from '@/markdown/welcome.mdx'
 
function CustomH1({ children }) {
  return <h1 style={{ color: 'blue', fontSize: '100px' }}>{children}</h1>
}
 
const overrideComponents = {
  h1: CustomH1,
}
 
export default function Page() {
  return <Welcome components={overrideComponents} />
}

Rust Compiler

• mdxRs (mdxjs-rs): Compile MDX to JavaScript in Rust, using markdown-rs under the hood, not support unified (remark and rehype) ecosystem plugins yet
• Please do not enable this if you want to use plugins:

  experimental: {
    mdxRs: true,
  }

Installation