MDX

The @mdx-js/mdx package is the core MDX compiler. Its primary responsibilities are:

1. Turning MDX content into JavaScript.
2. Evaluating MDX code.

When to use this package directly: Use this package when you need maximum control over the compilation process.

When to use an integration instead: If you are using a bundler (Rollup, esbuild, webpack), a site builder (Next.js), or a build system (Vite), use the specific integration designed for that tool rather than calling this API directly.

The MDX monorepo consists of the core compiler, a remark plugin for syntax support, and various integrations for bundlers and frontend frameworks. The primary packages include:

• @mdx-js/mdx: The core MDX compiler.
• remark-mdx: The remark plugin that enables support for MDX syntax.
• Bundler/Framework Integrations: Various packages to integrate MDX into build tools and UI libraries, such as @mdx-js/esbuild, @mdx-js/rollup, @mdx-js/react, @mdx-js/preact, and @mdx-js/vue.

MDX is a format that allows you to use JSX in your markdown content. It enables you to import and embed interactive components (like charts, alerts, or custom UI elements) directly within markdown files.

Key characteristics:

• Blends Markdown and JSX: Use standard markdown for text and JSX for components.
• Everything is a component: You can use existing components in MDX and even import other MDX files as components.
• Customizable: You can map specific markdown constructs to custom components (e.g., replacing standard h1 with a custom MyHeading component).
• No runtime: MDX is compiled to JavaScript during the build stage, meaning there is no heavy runtime overhead.
• Framework agnostic: It compiles to JavaScript that can be used in any framework supporting JSX (React, Preact, Vue, etc.).

MDX works by compiling MDX syntax into serialized JavaScript. An integration (like @mdx-js/rollup or @mdx-js/esbuild) transforms the MDX file into a JavaScript module that exports a default component (the content) and any other values defined via export statements.

Key characteristics of the compiled output:

• The content is exported as a default function (e.g., MDXContent).
• JSX is compiled away into function calls (e.g., _jsx).
• It is a complete module with imports and exports.
• It is not coupled to React; it can be used with Preact, Vue, and other frameworks.

export function Thing() {
  return <>World</>
}

# Hello <Thing />

// Roughly becomes:

export function Thing() {
  return <>World</>
}

export default function MDXContent(props) {
  return <h1>Hello <Thing /></h1>
}

MDX 3 now supports placing block expressions immediately adjacent to block JSX tags without requiring a newline between the angle brackets and the braces. This resolves previous syntax errors.

<style>{`

  h1 {
    color: blue;
  }

`}</style>

MDX does not support YAML frontmatter by default because it follows standard CommonMark syntax. Instead, MDX provides a native way to define metadata using ESM export statements. These exports are available as named exports when you import the compiled MDX module in JavaScript.

This approach is dynamic and allows you to use JavaScript logic (like string concatenation) within your metadata definitions.

export const name = 'World'
export const title = 'Hi, ' + name + '!'

# {title}

import * as Post from './example.mdx'

console.log(Post.title) // Prints 'Hi, World!'

MDX supports JSX, allowing you to use components directly within your content. Components can be imported via ESM, defined locally, or passed in via a provider.

Usage Patterns:

• Standard Components: <MyComponent id="123" />
• Object Properties: <myComponents.thisOne />
• Passing JSX as Props: <Component icon={<Icon />} />

Note that the specific syntax for attributes (like className vs class) depends on the target framework (React, Vue, Preact, etc.) you are using with MDX.

<MyComponent id="123" />

<myComponents.thisOne />

<Component
  open
  x={1}
  label={'this is a string, *not* markdown!'}
  icon={<Icon />}
/>

MDX is a programming language. Because it allows executing code, it is unsafe if you do not trust the authors of the MDX files.

Mitigation strategies:

• Use <iframe sandbox> for web environments (though not 100% foolproof).
• For Node.js, consider using vm2.
• Sandbox the entire OS using Docker.
• Implement rate limiting and process timeouts to prevent resource exhaustion.

You can embed JavaScript expressions inside curly braces {}. These expressions can contain any JavaScript code that evaluates to something renderable. This includes complex logic using Immediately Invoked Function Expressions (IIFE).

Two 🍰 is: {Math.PI * 2}

{(function () {
  const guess = Math.random()
  if (guess > 0.66) {
    return <span style={{color: 'tomato'}}>Look at us.</span>
  }
  return <span>Not so much.</span>
})()}

MDX v2 supports JavaScript expressions using curly braces {}. This can be used to embed logic or as an escape hatch to render raw strings or JSX without markdown interference.

{
  <h1>
    This just JSX, these *asterisks* have no meaning.
  </h1>
}

This is just {'`text`'}, not code.