Getting started

6-9 minutes read
By Titus Wormer

Getting started

This article explains how to integrate MDX into your project. It shows how to use MDX with your bundler and JSX runtime of choice. To understand how the MDX format works, we recommend that you start with § What is MDX. See § Using MDX when you’re all set up and ready to use MDX.

Prerequisites
Quick start
Integrations
Further reading

Prerequisites

MDX relies on JSX, so it’s required that your project supports JSX as well. Any JSX runtime (React, Preact, Vue, etc.) will do. Note that we do compile JSX to JavaScript for you so you don’t have to set that up.

All @mdx-js/* packages are written in modern JavaScript. A Node.js version of 16.0 or later is needed to use them. Our packages are also ESM only, so they have to be imported instead of required.

Note: Using Rust instead of Node.js? Try mdxjs-rs!

Quick start

Bundler

MDX is a language that’s compiled to JavaScript. (We also compile regular markdown to JavaScript.) The easiest way to get started is to use an integration for your bundler if you have one:

if you use esbuild (or Bun), install and configure @mdx-js/esbuild
if you use Rollup (or Vite), install and configure @mdx-js/rollup
if you use webpack (or Next.js), install and configure @mdx-js/loader

You can also use MDX without bundlers:

you can import MDX files in Node.js with @mdx-js/node-loader
you can use our core compiler @mdx-js/mdx to compile MDX files
you can use our core compiler @mdx-js/mdx to evaluate (compile and run) MDX files

For more info on these tools, see their dedicated sections: ¶ Next.js, ¶ Node.js, ¶ Rollup, ¶ Vite, ¶ esbuild, and ¶ webpack.

JSX

Now you’ve set up an integration or @mdx-js/mdx itself, it’s time to configure your JSX runtime.

if you use React, that’s the default; optionally install and configure @mdx-js/react
if you use Preact, set jsxImportSource in ProcessorOptions to 'preact'; optionally install and configure @mdx-js/preact
if you use Svelte, install svelte-jsx, and set jsxImportSource in ProcessorOptions to 'svelte-jsx'
if you use Vue, set jsxImportSource in ProcessorOptions to 'vue'; optionally install and configure @mdx-js/vue
if you use Solid, set jsxImportSource in ProcessorOptions to 'solid-js/h'
if you use Emotion, set jsxImportSource in ProcessorOptions to '@emotion/react'
if you use Theme UI, install and configure @mdx-js/react, then wrap your MDX content in a <ThemeProvider />

Other JSX runtimes are supported by setting jsxImportSource in ProcessorOptions.

For more info on these tools, see their dedicated sections: ¶ Emotion, ¶ Preact, ¶ React, ¶ Solid, ¶ Svelte, ¶ Theme UI, and ¶ Vue.

Editor

You can enhance the experience of using MDX by adding support of it to your editor:

if you use VS Code, try mdx-js/mdx-analyzer
if you use Vim, try jxnblk/vim-mdx-js
if you use Sublime Text, try jonsuh/mdx-sublime
if you use JetBrains IntelliJ/WebStorm, try JetBrains/mdx-intellij-plugin

The syntax highlighting that powers our VS Code extension and that is used to highlight code blocks on GitHub is maintained at wooorm/markdown-tm-language.

Types

Expand example of typed imports

First install the package:

Shell

npm install @types/mdx

…TypeScript should automatically pick it up:

example.js

import Post from './post.mdx' // `Post` is now typed.

(alias) function Post(props: MDXProps): JSX.Element
import Post

Our packages are typed with TypeScript. For types to work, the JSX namespace must be typed. This is done by installing and using the types of your framework, such as @types/react.

To enable types for imported .mdx, .md, etc., install and use @types/mdx. This package also exports several useful types, such as MDXComponents which represents the components prop. You can import them like so:

example.ts

import type {MDXComponents} from 'mdx/types.js'

(alias) type MDXComponents = NestedMDXComponents & {
    [x: string]: Component<JSX.IntrinsicElements> | undefined;
} & {
    wrapper?: Component<any>;
}
import MDXComponents

Security

MDX is a programming language. If you trust your authors, that’s fine. If you don’t, it’s unsafe.

Do not let random people from the internet write MDX. If you do, you might want to look into using <iframe>s with sandbox, but security is hard, and that doesn’t seem to be 100%. For Node.js, vm2 sounds interesting. But you should probably also sandbox the whole OS using Docker or similar, perform rate limiting, and make sure processes can be killed when taking too long.

Integrations

Bundlers

esbuild

Expand example

example.js

import mdx from '@mdx-js/esbuild'
import esbuild from 'esbuild'

await esbuild.build({
  entryPoints: ['index.mdx'],
  format: 'esm',
  outfile: 'output.js',
  plugins: [mdx({/* jsxImportSource: …, otherOptions… */})]
})

(alias) function mdx(options?: Readonly<Options> | null | undefined): esbuild.Plugin
import mdx

import esbuild

import esbuild

function build<{
    entryPoints: string[];
    format: "esm";
    outfile: string;
    plugins: esbuild.Plugin[];
}>(options: esbuild.SameShape<esbuild.BuildOptions, {
    entryPoints: string[];
    format: "esm";
    outfile: string;
    plugins: esbuild.Plugin[];
}>): Promise<...>

(property) entryPoints: string[]

(property) format: "esm"

(property) outfile: string

(property) plugins: esbuild.Plugin[]

(alias) mdx(options?: Readonly<Options> | null | undefined): esbuild.Plugin
import mdx

We support esbuild. Install and configure the esbuild plugin @mdx-js/esbuild. Configure your JSX runtime depending on which one (React, Preact, Vue, etc.) you use.

To use more modern JavaScript features than what your users support, configure esbuild’s target.

See also ¶ Bun, which you might be using, for more info.

Rollup

Expand example

rollup.config.js

/**
 * @import {RollupOptions} from 'rollup'
 */

import mdx from '@mdx-js/rollup'
import {babel} from '@rollup/plugin-babel'

/** @type {RollupOptions} */
const config = {
  // …
  plugins: [
    // …
    mdx({/* jsxImportSource: …, otherOptions… */}),
    // Babel is optional:
    babel({
      // Also run on what used to be `.mdx` (but is now JS):
      extensions: ['.js', '.jsx', '.cjs', '.mjs', '.md', '.mdx'],
      // Other options…
    })
  ]
}

export default config

(alias) function mdx(options?: Readonly<Options> | null | undefined): Plugin
import mdx

(alias) function babel(options?: RollupBabelInputPluginOptions): Plugin
import babel

const config: RollupOptions

(property) InputOptions.plugins?: InputPluginOption

(alias) mdx(options?: Readonly<Options> | null | undefined): Plugin
import mdx

(alias) babel(options?: RollupBabelInputPluginOptions): Plugin
import babel

(property) RollupBabelInputPluginOptions.extensions?: string[]

const config: RollupOptions

We support Rollup. Install and configure the Rollup plugin @mdx-js/rollup. Configure your JSX runtime depending on which one (React, Preact, Vue, etc.) you use.

To use more modern JavaScript features than what your users support, install and configure @rollup/plugin-babel.

See also ¶ Vite, if you use Rollup through it, for more info.

Webpack

Expand example

webpack.config.js

/**
 * @import {Options} from '@mdx-js/loader'
 * @import {Configuration} from 'webpack'
 */

/** @type {Configuration} */
const webpackConfig = {
  module: {
    // …
    rules: [
      // …
      {
        test: /\.mdx?$/,
        use: [
          // Babel is optional:
          {loader: 'babel-loader', options: {}},
          {
            loader: '@mdx-js/loader',
            /** @type {Options} */
            options: {/* jsxImportSource: …, otherOptions… */}
          }
        ]
      }
    ]
  }
}

export default webpackConfig

const webpackConfig: Configuration

(property) Configuration.module?: ModuleOptions

(property) ModuleOptions.rules?: (false | "" | 0 | RuleSetRule | "..." | null | undefined)[]

(property) RuleSetRule.test?: string | RegExp | ((value: string) => boolean) | RuleSetLogicalConditionsAbsolute | RuleSetConditionAbsolute[]

(property) RuleSetRule.use?: string | (string | false | 0 | {
    ident?: string;
    loader?: string;
    options?: string | {
        [index: string]: any;
    };
} | ((data: object) => string | {
    ident?: string;
    loader?: string;
    options?: string | {
        [index: string]: any;
    };
} | __TypeWebpackOptions | __Type_2[]) | null | undefined)[] | ((data: {
    resource: string;
    realResource: string;
    resourceQuery: string;
    issuer: string;
    compiler: string;
}) => __Type_2[]) | {
    ...;
} | __TypeWebpackOptions

(property) loader?: string

(property) options?: string | {
    [index: string]: any;
}

(property) loader?: string

(property) options?: string | {
    [index: string]: any;
}

const webpackConfig: Configuration

We support webpack. Install and configure the webpack loader @mdx-js/loader. Configure your JSX runtime depending on which one (React, Preact, Vue, etc.) you use.

To use more modern JavaScript features than what your users support, install and configure babel-loader.

See also ¶ Next.js, if you use webpack through it, for more info.

Build systems

Vite

Expand example

vite.config.js

import mdx from '@mdx-js/rollup'
import {defineConfig} from 'vite'

const viteConfig = defineConfig({
  plugins: [
    mdx(/* jsxImportSource: …, otherOptions… */)
  ]
})

export default viteConfig

(alias) function mdx(options?: Readonly<Options> | null | undefined): Plugin
import mdx

(alias) function defineConfig(config: UserConfig): UserConfig (+3 overloads)
import defineConfig

const viteConfig: UserConfig

(alias) defineConfig(config: UserConfig): UserConfig (+3 overloads)
import defineConfig

(property) UserConfig.plugins?: PluginOption[]

(alias) mdx(options?: Readonly<Options> | null | undefined): Plugin
import mdx

const viteConfig: UserConfig

We support Vite. Install and configure the Rollup plugin @mdx-js/rollup. Configure your JSX runtime depending on which one (React, Preact, Vue, etc.) you use.

To use more modern JavaScript features than what your users support, configure Vite’s build.target.

Note: If you also use @vitejs/plugin-react, you must force @mdx-js/rollup to run in the pre phase before it:

vite.config.js

// …
const viteConfig = defineConfig({
  plugins: [
    {enforce: 'pre', ...mdx({/* jsxImportSource: …, otherOptions… */})},
    react({include: /\.(jsx|js|mdx|md|tsx|ts)$/})
  ]
})
// …

const viteConfig: UserConfig

(alias) defineConfig(config: UserConfig): UserConfig (+3 overloads)
import defineConfig

(property) UserConfig.plugins?: PluginOption[]

(property) Plugin<any>.enforce?: "pre" | "post"

(alias) mdx(options?: Readonly<Options> | null | undefined): Plugin
import mdx

(alias) react(opts?: Options): PluginOption[]
import react

(property) Options.include?: string | RegExp | (string | RegExp)[]

See also ¶ Rollup which is used in Vite and see ¶ Vue if you’re using that, for more info.

Compilers

Babel

Expand plugin and sample use

This plugin:

plugin.js

/**
 * @import {ParseResult, ParserOptions} from '@babel/parser'
 * @import {File} from '@babel/types'
 * @import {Program} from 'estree'
 * @import {Plugin} from 'unified'
 */

import parser from '@babel/parser'
import {compileSync} from '@mdx-js/mdx'
import estreeToBabel from 'estree-to-babel'

/**
 * Plugin that tells Babel to use a different parser.
 */
export function babelPluginSyntaxMdx() {
  return {parserOverride: babelParserWithMdx}
}

/**
 * Parser that handles MDX with `@mdx-js/mdx` and passes other things through
 * to the normal Babel parser.
 *
 * @param {string} value
 * @param {ParserOptions} options
 * @returns {ParseResult<File>}
 */
function babelParserWithMdx(value, options) {
  /** @type {string | undefined} */
  // @ts-expect-error: babel changed the casing at some point and the types are out of date.
  const filename = options.sourceFilename || options.sourceFileName

  if (filename && /\.mdx?$/.test(filename)) {
    // Babel does not support async parsers, unfortunately.
    const file = compileSync(
      {value, path: options.sourceFilename},
      {recmaPlugins: [recmaBabel] /* jsxImportSource: …, otherOptions… */}
    )
    return /** @type {ParseResult<File>} */ (file.result)
  }

  return parser.parse(value, options)
}

/**
 * A “recma” plugin is a unified plugin that runs on the estree (used by
 * `@mdx-js/mdx` and much of the JS ecosystem but not Babel).
 * This plugin defines `'estree-to-babel'` as the compiler,
 * which means that the resulting Babel tree is given back by `compileSync`.
 *
 * @type {Plugin<[], Program, unknown>}
 */
function recmaBabel() {
  // @ts-expect-error: `Program` is similar enough to a unist node.
  this.compiler = compiler

  /**
   * @param {Program} tree
   * @returns {unknown}
   */
  function compiler(tree) {
    // @ts-expect-error TS2349: This expression *is* callable, `estreeToBabel` types are wrong.
    return estreeToBabel(tree)
  }
}

import parser

(alias) function compileSync(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): VFile
import compileSync

import estreeToBabel

function babelPluginSyntaxMdx(): {
    parserOverride: (value: string, options: parser.ParserOptions) => parser.ParseResult<File>;
}

(property) parserOverride: (value: string, options: parser.ParserOptions) => parser.ParseResult<File>

function babelParserWithMdx(value: string, options: parser.ParserOptions): parser.ParseResult<File>

function babelParserWithMdx(value: string, options: parser.ParserOptions): parser.ParseResult<File>

(parameter) value: string

(parameter) options: parser.ParserOptions

const filename: string | undefined

(parameter) options: parser.ParserOptions

(property) ParserOptions.sourceFilename?: string | undefined

(parameter) options: parser.ParserOptions

any

const filename: string | undefined

(method) RegExp.test(string: string): boolean

const filename: string

const file: VFile

(alias) compileSync(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): VFile
import compileSync

(property) value: string

(property) path: string | undefined

(parameter) options: parser.ParserOptions

(property) ParserOptions.sourceFilename?: string | undefined

(property) recmaPlugins?: PluggableList | null | undefined

class recmaBabel
function recmaBabel(this: Processor): void | Transformer<Program, Node> | undefined

const file: VFile

(property) VFile.result: unknown

import parser

(alias) parse(input: string, options?: ParserOptions): ParseResult<File>
export parse

(parameter) value: string

(parameter) options: parser.ParserOptions

function recmaBabel(this: Processor): void | Transformer<Program, Node> | undefined

(property) recmaBabel.compiler: (tree: Program) => unknown

(local function) compiler(tree: Program): unknown

(local function) compiler(tree: Program): unknown

(parameter) tree: Program

import estreeToBabel

(parameter) tree: Program

…can be used like so with the Babel API:

example.js

import babel from '@babel/core'
import {babelPluginSyntaxMdx} from './plugin.js'

const document = '# Hello, world!'

// Note that a filename must be set for our plugin to know it’s MDX instead of JS.
const result = await babel.transformAsync(document, {
  filename: 'example.mdx',
  plugins: [babelPluginSyntaxMdx]
})

console.log(result)

import babel

(alias) function babelPluginSyntaxMdx(): {
    parserOverride: (value: string, options: babel.ParserOptions) => ParseResult<babel.types.File>;
}
import babelPluginSyntaxMdx

const document: "# Hello, world!"

const result: babel.BabelFileResult | null

import babel

function transformAsync(code: string, opts?: babel.TransformOptions): Promise<babel.BabelFileResult | null>

const document: "# Hello, world!"

(property) TransformOptions.filename?: string | null | undefined

(property) TransformOptions.plugins?: babel.PluginItem[] | null | undefined

(alias) function babelPluginSyntaxMdx(): {
    parserOverride: (value: string, options: babel.ParserOptions) => ParseResult<babel.types.File>;
}
import babelPluginSyntaxMdx

namespace console
var console: Console

The console module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers.

The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and process.stderr. The global console can be used without calling require('console').

Warning: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the note on process I/O for more information.

Example using the global console:

console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr

Example using the Console class:

const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err

@see source

(method) Console.log(message?: any, ...optionalParams: any[]): void

Prints to stdout with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to printf(3) (the arguments are all passed to util.format()).

const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout

See util.format() for more information.

@since v0.1.100

const result: babel.BabelFileResult | null

You should probably use Rollup or webpack instead of Babel directly as that gives the best interface. It is possible to use @mdx-js/mdx in Babel and it’s a bit faster, as it skips @mdx-js/mdx serialization and Babel parsing, if Babel is used anyway.

Babel does not support syntax extensions to its parser (it has “syntax” plugins but those only turn internal flags on or off). It does support setting a different parser. Which in turn lets us choose whether to use the @mdx-js/mdx or @babel/parser.

Site generators

Astro

Astro has its own MDX integration. You can add the integration with the Astro CLI: npx astro add mdx.

This base setup lets you import markdown, Astro components, and MDX files as components. See Astro’s Framework components guide for info on how to use components from frameworks in your MDX files.

For more on how to combine Astro and MDX, see Astro’s MDX integration docs.

Docusaurus

Docusaurus supports MDX by default. See Docusaurus’ MDX and React guide for info on how to use MDX with Docusaurus.

Gatsby

Gatsby has its own plugin to support MDX. See gatsby-plugin-mdx on how to use MDX with Gatsby.

Next.js

Expand example

next.config.js

import nextMdx from '@next/mdx'

const withMdx = nextMdx({
  // By default only the `.mdx` extension is supported.
  extension: /\.mdx?$/,
  options: {/* otherOptions… */}
})

const nextConfig = withMdx({
  // Support MDX files as pages:
  pageExtensions: ['md', 'mdx', 'tsx', 'ts', 'jsx', 'js'],
})

export default nextConfig

(alias) function nextMdx(options?: nextMdx.NextMDXOptions): WithMDX
(alias) namespace nextMdx
import nextMdx

const withMdx: WithMDX

(alias) nextMdx(options?: nextMdx.NextMDXOptions): WithMDX
import nextMdx

(property) nextMDX.NextMDXOptions.extension?: RuleSetConditionAbsolute

(property) nextMDX.NextMDXOptions.options?: Options

const nextConfig: NextConfig

const withMdx: (config: NextConfig) => NextConfig

(property) pageExtensions: string[]

const nextConfig: NextConfig

Next.js has its own MDX integration. Install and configure @next/mdx.

Do not use providerImportSource and @mdx-js/react with Next to inject components. Add an mdx-components.tsx (in src/ or /) file instead. See Configuring MDX on nextjs.org for more info.

Parcel

Parcel has its own plugin to support MDX. See @parcel/transformer-mdx on how to use MDX with Parcel.

JSX runtimes

Emotion

Expand example

example.js

import {compile} from '@mdx-js/mdx'

const js = String(await compile('# hi', {jsxImportSource: '@emotion/react', /* otherOptions… */}))

(alias) function compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const js: string

var String: StringConstructor
(value?: any) => string

(alias) compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

(property) jsxImportSource?: string | null | undefined

Emotion is supported when jsxImportSource in ProcessorOptions is set to '@emotion/react'. You can optionally install and configure @mdx-js/react to support context based component passing.

See also ¶ React, which is used in Emotion, and see ¶ Rollup and ¶ webpack, which you might be using, for more info.

Ink

Expand example

example.mdx

# Hi!

example.js

import React from 'react'
import {Text, render} from 'ink'
import Content from './example.mdx' // Assumes an integration is used to compile MDX -> JS.

render(
  React.createElement(Content, {
    components: {
      h1(properties) {
        // @ts-expect-error: `Ink` types don’t match w/ `exactOptionalPropertyTypes: true`
        return React.createElement(Text, {bold: true, ...properties})
      },
      p: Text
    }
  })
)

(alias) namespace React
import React

(alias) function Text({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props): React.JSX.Element | null
import Text

(alias) const render: (node: React.ReactNode, options?: NodeJS.WriteStream | RenderOptions) => Instance
import render

(alias) function Content(props: MDXProps): Element
import Content

(alias) render(node: React.ReactNode, options?: NodeJS.WriteStream | RenderOptions): Instance
import render

(alias) namespace React
import React

function React.createElement(type: "input", props?: (React.InputHTMLAttributes<HTMLInputElement> & React.ClassAttributes<HTMLInputElement>) | null, ...children: React.ReactNode[]): React.DetailedReactHTMLElement<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement> (+6 overloads)

(alias) function Content(props: MDXProps): Element
import Content

(property) components: {
    h1(properties: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>): React.DetailedReactHTMLElement<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>;
    p: ({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props) => React.JSX.Element | null;
}

(method) h1(properties: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>): React.DetailedReactHTMLElement<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>

(parameter) properties: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>

(alias) namespace React
import React

function React.createElement(type: "input", props?: (React.InputHTMLAttributes<HTMLInputElement> & React.ClassAttributes<HTMLInputElement>) | null, ...children: React.ReactNode[]): React.DetailedReactHTMLElement<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement> (+6 overloads)

(alias) function Text({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props): React.JSX.Element | null
import Text

(property) bold: boolean

(parameter) properties: React.DetailedHTMLProps<React.HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>

No overload matches this call.
  The last overload gave the following error.
    Type '({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props) => Element | null' is not assignable to type 'Component<DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>> | undefined'.
      Type '({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props) => Element | null' is not assignable to type '(props: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>) => ReactNode'.
        Types of parameters '__0' and 'props' are incompatible.
          Type 'DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>' is not assignable to type 'Props' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
            Types of property 'color' are incompatible.
              Type 'string | undefined' is not assignable to type 'LiteralUnion<keyof ForegroundColor, string>'.
                Type 'undefined' is not assignable to type 'LiteralUnion<keyof ForegroundColor, string>'. (2769)

(property) p: ({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props) => React.JSX.Element | null

(alias) function Text({ color, backgroundColor, dimColor, bold, italic, underline, strikethrough, inverse, wrap, children, }: Props): React.JSX.Element | null
import Text

Can be used with:

Shell

node --loader=@mdx-js/node-loader example.js

Ink uses the React JSX runtime, so set that up. You will need to swap HTML elements out for Ink’s components. See § Table of components for what those are and Ink’s docs on what they can be replaced with.

See also ¶ Node.js and ¶ React for more info.

Preact

Expand example

example.js

import {compile} from '@mdx-js/mdx'

const js = String(await compile('# hi', {jsxImportSource: 'preact', /* otherOptions… */}))

(alias) function compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const js: string

var String: StringConstructor
(value?: any) => string

(alias) compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

(property) jsxImportSource?: string | null | undefined

Preact is supported when jsxImportSource in ProcessorOptions is set to 'preact'. You can optionally install and configure @mdx-js/preact to support context based component passing.

See also ¶ Rollup, ¶ esbuild, and ¶ webpack, which you might be using, for more info.

React

React is supported by default. You can optionally install and configure @mdx-js/react to support context based component passing.

See also ¶ Rollup, ¶ esbuild, and ¶ webpack, which you might be using, for more info.

Theme UI

Theme UI has its own plugin to support MDX. See @theme-ui/mdx on how to use MDX with Theme UI.

Svelte

Expand example

example.js

import {compile} from '@mdx-js/mdx'

const js = String(await compile('# hi', {jsxImportSource: 'svelte-jsx', /* otherOptions… */}))

(alias) function compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const js: string

var String: StringConstructor
(value?: any) => string

(alias) compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

(property) jsxImportSource?: string | null | undefined

Svelte is supported when jsxImportSource in ProcessorOptions is set to 'svelte-jsx'.

See also ¶ Rollup, ¶ esbuild, and ¶ webpack, which you might be using, for more info.

Vue

Expand example

example.js

import {compile} from '@mdx-js/mdx'

const js = String(await compile('# hi', {jsxImportSource: 'vue', /* otherOptions… */}))

(alias) function compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const js: string

var String: StringConstructor
(value?: any) => string

(alias) compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

(property) jsxImportSource?: string | null | undefined

Vue is supported when jsxImportSource in ProcessorOptions is set to 'vue'. You can optionally install and configure @mdx-js/vue to support context based component passing.

See also ¶ Vite, which you might be using, for more info.

Solid

Expand example

example.js

import {compile} from '@mdx-js/mdx'

const js = String(await compile('# hi', {jsxImportSource: 'solid-js/h', /* otherOptions… */}))

(alias) function compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const js: string

var String: StringConstructor
(value?: any) => string

(alias) compile(vfileCompatible: any, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

(property) jsxImportSource?: string | null | undefined

Solid is supported when jsxImportSource in ProcessorOptions is set to 'solid-js/h'.

See also ¶ Rollup and ¶ Vite, which you might be using, for more info.

JavaScript engines

Node.js

MDX files can be imported in Node by using @mdx-js/node-loader. See its readme on how to configure it.

Bun

MDX files can be imported in Bun by using @mdx-js/esbuild.

Expand example

bunfig.toml

preload = ["./bun-mdx.ts"]

bun-mdx.ts

import mdx from '@mdx-js/esbuild'
import {type BunPlugin, plugin} from 'bun'

await plugin(mdx() as unknown as BunPlugin)

(alias) function mdx(options?: Readonly<Options> | null | undefined): Plugin
import mdx

(alias) interface BunPlugin
import BunPlugin

(alias) const plugin: BunRegisterPlugin
import plugin

(alias) plugin<BunPlugin>(options: BunPlugin): void | Promise<void>
import plugin

(alias) mdx(options?: Readonly<Options> | null | undefined): Plugin
import mdx

(alias) interface BunPlugin
import BunPlugin

Getting started

Contents

Prerequisites

Quick start

Bundler

JSX

Editor

Types

Security

Integrations

Bundlers

esbuild

Rollup

Webpack

Build systems

Vite

Compilers

Babel

Site generators

Astro

Docusaurus

Gatsby

Next.js

Parcel

JSX runtimes

Emotion

Ink

Preact

React

Theme UI

Svelte

Vue

Solid

JavaScript engines

Node.js

Bun

Further reading