# `@mdx-js/mdx`
[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]
MDX compiler.
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`compile(file, options?)`](#compilefile-options)
* [`compileSync(file, options?)`](#compilesyncfile-options)
* [`createProcessor(options?)`](#createprocessoroptions)
* [`evaluate(file, options)`](#evaluatefile-options)
* [`evaluateSync(file, options)`](#evaluatesyncfile-options)
* [`nodeTypes`](#nodetypes)
* [`run(code, options)`](#runcode-options)
* [`runSync(code, options)`](#runsynccode-options)
* [`CompileOptions`](#compileoptions)
* [`EvaluateOptions`](#evaluateoptions)
* [`Fragment`](#fragment)
* [`Jsx`](#jsx)
* [`JsxDev`](#jsxdev)
* [`ProcessorOptions`](#processoroptions)
* [`RunOptions`](#runoptions)
* [`UseMdxComponents`](#usemdxcomponents)
* [Types](#types)
* [Architecture](#architecture)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [License](#license)
## What is this?
This package is a compiler that turns MDX into JavaScript.
It can also evaluate MDX code.
## When should I use this?
This is the core compiler for turning MDX into JavaScript which gives you the
most control.
If you’re using a bundler (Rollup, esbuild, webpack), a site builder (Next.js),
or build system (Vite) which comes with a bundler, you’re better off using an
integration: see [§ Integrations][integrations].
## Install
This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:
```sh
npm install @mdx-js/mdx
```
In Deno with [`esm.sh`][esmsh]:
```tsx
import {compile} from 'https://esm.sh/@mdx-js/mdx@3'
```
In browsers with [`esm.sh`][esmsh]:
```html
```
## Use
Say we have an MDX document, `example.mdx`:
```mdx
export function Thing() {
return <>World!
}
# Hello,
```
…and some code in `example.js` to compile `example.mdx` to JavaScript:
```tsx
import fs from 'node:fs/promises'
import {compile} from '@mdx-js/mdx'
const compiled = await compile(await fs.readFile('example.mdx'))
console.log(String(compiled))
```
Yields roughly:
```tsx
import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
export function Thing() {
return _jsx(_Fragment, {children: 'World!'})
}
function _createMdxContent(props) {
const _components = {h1: 'h1', ...props.components}
return _jsxs(_components.h1, {children: ['Hello, ', _jsx(Thing, {})]})
}
export default function MDXContent(props = {}) {
const {wrapper: MDXLayout} = props.components || {}
return MDXLayout
? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {...props})})
: _createMdxContent(props)
}
```
See [§ Using MDX][using-mdx] for more on how MDX work and how to use the result.
## API
This package exports the following identifiers:
[`compile`][api-compile],
[`compileSync`][api-compile-sync],
[`createProcessor`][api-create-processor],
[`evaluate`][api-evaluate],
[`evaluateSync`][api-evaluate-sync],
[`nodeTypes`][api-node-types],
[`run`][api-run], and
[`runSync`][api-run-sync].
There is no default export.
### `compile(file, options?)`
Compile MDX to JS.
###### Parameters
* `file` ([`Compatible` from `vfile`][vfile-compatible])
— MDX document to parse
* `options` ([`CompileOptions`][api-compile-options], optional)
— compile configuration
###### Returns
Promise to compiled file ([`Promise`][vfile]).
###### Examples
The input value for `file` can be many different things.
You can pass a `string`, `Uint8Array` in UTF-8, [`VFile`][vfile], or anything
that can be given to `new VFile`.
```tsx
import {compile} from '@mdx-js/mdx'
import {VFile} from 'vfile'
await compile(':)')
await compile(Buffer.from(':-)'))
await compile({path: 'path/to/file.mdx', value: '🥳'})
await compile(new VFile({path: 'path/to/file.mdx', value: '🤭'}))
```
The output `VFile` can be used to access more than the generated code:
```tsx
import {compile} from '@mdx-js/mdx'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent' // Lint rules to check for consistent markdown.
import {reporter} from 'vfile-reporter'
const file = await compile('*like this* or _like this_?', {remarkPlugins: [remarkPresetLintConsistent]})
console.error(reporter(file))
```
Yields:
```txt
1:16-1:27 warning Emphasis should use `*` as a marker emphasis-marker remark-lint
⚠ 1 warning
```
### `compileSync(file, options?)`
Synchronously compile MDX to JS.
When possible please use the async [`compile`][api-compile].
###### Parameters
* `file` ([`Compatible` from `vfile`][vfile-compatible])
— MDX document to parse
* `options` ([`CompileOptions`][api-compile-options], optional)
— compile configuration
###### Returns
Compiled file ([`VFile`][vfile]).
### `createProcessor(options?)`
Create a processor to compile markdown or MDX to JavaScript.
> **Note**: `format: 'detect'` is not allowed in `ProcessorOptions`.
###### Parameters
* `options` ([`ProcessorOptions`][api-processor-options], optional)
— process configuration
###### Returns
Processor ([`Processor` from `unified`][unified-processor]).
### `evaluate(file, options)`
[Compile][api-compile] and [run][api-run] MDX.
When you trust your content, `evaluate` can work.
When possible, use [`compile`][api-compile], write to a file, and then run with
Node or use one of the [§ Integrations][integrations].
> ☢️ **Danger**: it’s called **evaluate** because it `eval`s JavaScript.
###### Parameters
* `file` ([`Compatible` from `vfile`][vfile-compatible])
— MDX document to parse
* `options` ([`EvaluateOptions`][api-evaluate-options], **required**)
— configuration
###### Returns
Promise to a module ([`Promise` from
`mdx/types.js`][mdx-types-module]).
The result is an object with a `default` field set to the component;
anything else that was exported is available too.
For example, assuming the contents of `example.mdx` from [§ Use][use] was in
`file`, then:
```tsx
import {evaluate} from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'
console.log(await evaluate(file, runtime))
```
…yields:
```tsx
{Thing: [Function: Thing], default: [Function: MDXContent]}
```
###### Notes
Compiling (and running) MDX takes time.
If you are live-rendering a string of MDX that often changes using a virtual DOM
based framework (such as React), one performance improvement is to call the
`MDXContent` component yourself.
The reason is that the `evaluate` creates a new function each time, which cannot
be diffed:
```diff
const {default: MDXContent} = await evaluate('…')
-
+MDXContent(props)
```
### `evaluateSync(file, options)`
Compile and run MDX, synchronously.
When possible please use the async [`evaluate`][api-evaluate].
> ☢️ **Danger**: it’s called **evaluate** because it `eval`s JavaScript.
###### Parameters
* `file` ([`Compatible` from `vfile`][vfile-compatible])
— MDX document to parse
* `options` ([`EvaluateOptions`][api-evaluate-options], **required**)
— configuration
###### Returns
Module ([`MDXModule` from `mdx/types.js`][mdx-types-module]).
### `nodeTypes`
List of node types made by `mdast-util-mdx`, which have to be passed
through untouched from the mdast tree to the hast tree (`Array`).
### `run(code, options)`
Run code compiled with `outputFormat: 'function-body'`.
> ☢️ **Danger**: this `eval`s JavaScript.
###### Parameters
* `code` ([`VFile`][vfile] or `string`)
— JavaScript function body to run
* `options` ([`RunOptions`][api-run-options], **required**)
— configuration
###### Returns
Promise to a module ([`Promise` from
`mdx/types.js`][mdx-types-module]);
the result is an object with a `default` field set to the component;
anything else that was exported is available too.
###### Example
On the server:
```tsx
import {compile} from '@mdx-js/mdx'
const code = String(await compile('# hi', {outputFormat: 'function-body'}))
// To do: send `code` to the client somehow.
```
On the client:
```tsx
import {run} from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'
const code = '' // To do: get `code` from server somehow.
const {default: Content} = await run(code, {...runtime, baseUrl: import.meta.url})
console.log(Content)
```
…yields:
```tsx
[Function: MDXContent]
```
### `runSync(code, options)`
Run code, synchronously.
When possible please use the async [`run`][api-run].
> ☢️ **Danger**: this `eval`s JavaScript.
###### Parameters
* `code` ([`VFile`][vfile] or `string`)
— JavaScript function body to run
* `options` ([`RunOptions`][api-run-options], **required**)
— configuration
###### Returns
Module ([`MDXModule` from `mdx/types.js`][mdx-types-module]).
### `CompileOptions`
Configuration for `compile` (TypeScript type).
`CompileOptions` is the same as [`ProcessorOptions`][api-processor-options]
with the exception that the `format` option supports a `'detect'` value,
which is the default.
The `'detect'` format means to use `'md'` for files with an extension in
`mdExtensions` and `'mdx'` otherwise.
###### Type
```tsx
/**
* Configuration for `compile`
*/
type CompileOptions = Omit & {
/**
* Format of `file` (default: `'detect'`).
*/
format?: 'detect' | 'md' | 'mdx' | null | undefined
}
```
### `EvaluateOptions`
Configuration for `evaluate` (TypeScript type).
`EvaluateOptions` is the same as [`CompileOptions`][api-compile-options],
except that the options `baseUrl`, `jsx`, `jsxImportSource`, `jsxRuntime`,
`outputFormat`, `pragma`, `pragmaFrag`, `pragmaImportSource`, and
`providerImportSource` are not allowed, and that
[`RunOptions`][api-run-options] are also used.
###### Type
```tsx
/**
* Configuration for `evaluate`.
*/
type EvaluateOptions = Omit<
CompileOptions,
| 'baseUrl' // Note that this is also in `RunOptions`.
| 'jsx'
| 'jsxImportSource'
| 'jsxRuntime'
| 'outputFormat'
| 'pragma'
| 'pragmaFrag'
| 'pragmaImportSource'
| 'providerImportSource'
> &
RunOptions
```
### `Fragment`
Represent the children, typically a symbol (TypeScript type).
###### Type
```ts
type Fragment = unknown
```
### `Jsx`
Create a production element (TypeScript type).
###### Parameters
* `type` (`unknown`)
— element type: `Fragment` symbol, tag name (`string`), component
* `properties` (`Properties`)
— element properties and `children`
* `key` (`string` or `undefined`)
— key to use
###### Returns
Element from your framework (`JSX.Element`).
### `JsxDev`
Create a development element (TypeScript type).
###### Parameters
* `type` (`unknown`)
— element type: `Fragment` symbol, tag name (`string`), component
* `properties` (`Properties`)
— element properties and `children`
* `key` (`string` or `undefined`)
— key to use
* `isStaticChildren` (`boolean`)
— whether two or more children are passed (in an array), which is whether
`jsxs` or `jsx` would be used
* `source` (`Source`)
— info about source
* `self` (`unknown`)
— context object (`this`)
### `ProcessorOptions`
Configuration for `createProcessor` (TypeScript type).
###### Fields
* `SourceMapGenerator` (`SourceMapGenerator` from [`source-map`][source-map],
optional)
— add a source map (object form) as the `map` field on the resulting file
Expand example
Assuming `example.mdx` from [§ Use][use] exists, then:
```tsx
import fs from 'node:fs/promises'
import {compile} from '@mdx-js/mdx'
import {SourceMapGenerator} from 'source-map'
const file = await compile(
{path: 'example.mdx', value: await fs.readFile('example.mdx')},
{SourceMapGenerator}
)
console.log(file.map)
```
…yields:
```tsx
{
file: 'example.mdx',
mappings: ';;aAAaA,QAAQ;YAAQ;;;;;;;;iBAE3B',
names: ['Thing'],
sources: ['example.mdx'],
version: 3
}
```
Expand example
Say we have a module `example.js`:
```tsx
import {compile} from '@mdx-js/mdx'
const code = 'export {number} from "./data.js"\n\n# hi'
const baseUrl = 'https://a.full/url' // Typically `import.meta.url`
console.log(String(await compile(code, {baseUrl})))
```
…now running `node example.js` yields:
```tsx
import {jsx as _jsx} from 'react/jsx-runtime'
export {number} from 'https://a.full/data.js'
function _createMdxContent(props) { /* … */ }
export default function MDXContent(props = {}) { /* … */ }
```
Expand example
Say we had some MDX that references a component that can be passed or
provided at runtime:
```mdx
**Note**: some stuff.
```
And a module to evaluate that:
```tsx
import fs from 'node:fs/promises'
import {evaluate} from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'
const path = 'example.mdx'
const value = await fs.readFile(path)
const MDXContent = (await evaluate({path, value}, {...runtime, baseUrl: import.meta.url})).default
console.log(MDXContent({}))
```
…running that would normally (production) yield:
```txt
Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it.
at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9)
at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20)
at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9)
at main (…/example.js:11:15)
```
…but if we add `development: true` to our example:
```diff
@@ -7,6 +7,6 @@
import fs from 'node:fs/promises'
-import * as runtime from 'react/jsx-runtime'
+import * as runtime from 'react/jsx-dev-runtime'
import {evaluate} from '@mdx-js/mdx'
const path = 'example.mdx'
const value = await fs.readFile(path)
-const MDXContent = (await evaluate({path, value}, {...runtime, baseUrl: import.meta.url})).default
+const MDXContent = (await evaluate({path, value}, {development: true, ...runtime, baseUrl: import.meta.url})).default
console.log(MDXContent({}))
```
…and we’d run it again, we’d get:
```txt
Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it.
It’s referenced in your code at `1:9-1:21` in `example.mdx`
provide it.
at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9)
at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20)
at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9)
at main (…/example.js:11:15)
```
Expand example
```tsx
compile('…') // Seen as MDX.
compile('…', {format: 'mdx'}) // Seen as MDX.
compile('…', {format: 'md'}) // Seen as markdown.
```
Expand example
If `file` is the contents of `example.mdx` from [§ Use][use], then:
```tsx
compile(file, {jsx: true})
```
…yields this difference:
```diff
-import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
+/*@jsxRuntime automatic*/
+/*@jsxImportSource react*/
export function Thing() {
- return _jsx(_Fragment, {children: 'World'})
+ return <>World!
}
function _createMdxContent(props) {
const _components = {
h1: 'h1',
...props.components
}
- return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]})
+ return <_components.h1>{"Hello "}
}
export default function MDXContent(props = {}) {
const {wrapper: MDXLayout} = props.components || {}
return MDXLayout
- ? _jsx(MDXLayout, {
- ...props,
- children: _jsx(_createMdxContent, props)
- })
+ ? <_createMdxContent {...props} />
: _createMdxContent(props)
}
}
```
Expand example
If `file` is the contents of `example.mdx` from [§ Use][use], then:
```tsx
compile(file, {jsxImportSource: 'preact'})
```
…yields this difference:
```diff
-import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
+import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from 'preact/jsx-runtime'
```
Expand example
If `file` is the contents of `example.mdx` from [§ Use][use], then:
```tsx
compile(file, {jsxRuntime: 'classic'})
```
…yields this difference:
```diff
-import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
+import React from 'react'
export function Thing() {
- return _jsx(_Fragment, {children: 'World'})
+ return React.createElement(React.Fragment, null, 'World!')
}
…
```
Expand example
With a module `example.js`:
```tsx
import {compile} from '@mdx-js/mdx'
const code = 'export const no = 3.14\n\n# hi {no}'
console.log(String(await compile(code, {outputFormat: 'program'}))) // Default.
console.log(String(await compile(code, {outputFormat: 'function-body'})))
```
…yields:
```tsx
import {jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
export const no = 3.14
function _createMdxContent(props) { /* … */ }
export default function MDXContent(props = {}) { /* … */ }
```
```tsx
'use strict'
const {Fragment: _Fragment, jsx: _jsx} = arguments[0]
const no = 3.14
function _createMdxContent(props) { /* … */ }
function MDXContent(props = {}) { /* … */ }
return {no, default: MDXContent}
```
The `'program'` format will use import statements to import the runtime (and
optionally provider) and use an export statement to yield the `MDXContent`
component.
The `'function-body'` format will get the runtime (and optionally provider)
from `arguments[0]`, rewrite export statements, and use a return statement to
yield what was exported.
Expand example
If `file` is the contents of `example.mdx` from [§ Use][use], then:
```tsx
compile(file, {
jsxRuntime: 'classic',
pragma: 'preact.createElement',
pragmaFrag: 'preact.Fragment',
pragmaImportSource: 'preact/compat'
})
```
…yields this difference:
```diff
-import React from 'react'
+import preact from 'preact/compat'
export function Thing() {
- return React.createElement(React.Fragment, null, 'World!')
+ return preact.createElement(preact.Fragment, null, 'World!')
}
…
```
Expand example
If `file` is the contents of `example.mdx` from [§ Use][use], then:
```tsx
compile(file, {providerImportSource: '@mdx-js/react'})
```
…yields this difference:
```diff
import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'
+import {useMDXComponents as _provideComponents} from '@mdx-js/react'
export function Thing() {
return _jsx(_Fragment, {children: 'World'})
}
function _createMdxContent(props) {
const _components = {
h1: 'h1',
+ ..._provideComponents(),
...props.components
}
return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]})
}
export default function MDXContent(props = {}) {
- const {wrapper: MDXLayout} = props.components || {}
+ const {wrapper: MDXLayout} = {
+ ..._provideComponents(),
+ ...props.components
+ }
return MDXLayout
? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {})})
: _createMdxContent()
```
Expand example
```tsx
import recmaMdxIsMdxComponent from 'recma-mdx-is-mdx-component'
await compile(file, {recmaPlugins: [recmaMdxIsMdxComponent]})
```
Expand example
```tsx
import rehypeKatex from 'rehype-katex' // Render math with KaTeX.
import remarkMath from 'remark-math' // Support math like `$so$`.
await compile(file, {rehypePlugins: [rehypeKatex], remarkPlugins: [remarkMath]})
await compile(file, {
// A plugin with options:
rehypePlugins: [[rehypeKatex, {strict: true, throwOnError: true}]],
remarkPlugins: [remarkMath]
})
```
Expand example
```tsx
import remarkFrontmatter from 'remark-frontmatter' // YAML and such.
import remarkGfm from 'remark-gfm' // Tables, footnotes, strikethrough, task lists, literal URLs.
await compile(file, {remarkPlugins: [remarkGfm]}) // One plugin.
await compile(file, {remarkPlugins: [[remarkFrontmatter, 'toml']]}) // A plugin with options.
await compile(file, {remarkPlugins: [remarkGfm, remarkFrontmatter]}) // Two plugins.
await compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFrontmatter]}) // Two plugins, first w/ options.
```
Expand example
```tsx
compile({value: '…'}, {remarkRehypeOptions: {clobberPrefix: 'comment-1'}})
```