MDX is a JSX in Markdown loader, parser, and renderer for ambitious projects. It combines the readability of Markdown with the expressivity of JSX. The best of both worlds. 🌐

See the MDX specification

Features

• Fast
• No runtime compilation
• Pluggable
• Element to React component mapping
• React component import/export
• Simpler image syntax
• Webpack loader

Installation

npm install --save-dev @mdx-js/loader @mdx-js/mdx

Note: mdx requires a version of node that is >= v8.5

Configuring with Webpack

You'll need to specify the @mdx-js/loader webpack loader and follow it with the babel-loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.md$/,
        use: ['babel-loader', '@mdx-js/loader']
      }
    ]
  }
}

Examples

• next.js
• x0

Configuring with Parcel

You'll need to install the @mdx-js/parcel-plugin-mdx plugin to transpile MDX.

{
  "scripts": {
    "start": "parcel index.html --no-cache"
  },
  "dependencies": {
    "react": "16.4.1",
    "react-dom": "16.4.1",
    "@mdx-js/tag": "latest"
  },
  "devDependencies": {
    "@mdx-js/parcel-plugin-mdx": "latest",
    "parcel-bundler": "1.9.0"
  }
}

Examples

• Parcel

Configuring TypeScript

If you're getting errors from TypeScript related to imports with an *.mdx extension, create an mdx.d.ts file in your types directory and include inside your tsconfig.json

// types/mdx.d.ts
declare module '*.mdx' {
  let MDXComponent: (props) => JSX.Element;
  export default MDXComponent;
}

Usage

Create an md file, hello.md:

# Hello, world!

And import it from a component, pages/index.js:

import React from 'react'
import Hello from '../hello.md'

export default () => <Hello />

MDX syntax

Imports

Similarly to JSX, components can be rendered after an import:

import Graph from './components/graph'

## Here's a graph

<Graph />

Markdown file transclusion

You can transclude Markdown files by importing one .md file into another:

import License from './license.md'
import Contributing from './docs/contributing.md'

# Hello, world!

<License />

---

<Contributing />

Exports

You can use exports to export metadata like layout or authors. It's a mechanism for an imported MDX file to communicate with its parent. It works similarly to frontmatter, but uses ES2015 syntax.

// posts/post.mdx
import { fred, sue } from '../data/authors'
import Layout from '../components/blog-layout'

export const meta = {
  authors: [fred, sue],
  layout: Layout
}

# Post about MDX

MDX is a JSX in Markdown loader, parser, and renderer for ambitious projects.

// index.js
import React from 'react'
import Mdx, { meta } from 'posts/post.mdx'

const { authors, layout } = meta

export default () => (
  <layout>
    <Mdx />
    By: {authors.map(author => author.name)}
  </layout>
)

export default

The ES default export is used to provide a layout component which will wrap the transpiled JSX.

You can export it as a function:

import Layout from './Layout'

export default ({children}) => <Layout some='metadata' >{children}</Layout>

# Hello, world!

Or directly as a component:

import Layout from './Layout'

export default Layout

# Hello, world!

Any additional props passed to the imported MDX component will be passed to its default export:

// index.js
import Mdx from './posts/post.mdx'

export default () => (
  <Mdx someProp="value" />
)

// posts/post.mdx
import Layout from '../components/blog-layout'

# Hello, world!

export default ({ children, someProp }) => <Layout someProp={someProp}>{children}</Layout>

Component customization

You can pass in components for any html element that Markdown compiles to. This allows you to use your existing components and use CSS-in-JS like styled-components.

import React from 'react'
import Hello from '../hello.md'

import {
  Text,
  Heading,
  Code,
  InlineCode
} from '../ui'

export default () =>
  <Hello
    components={{
      h1: Heading,
      p: Text,
      code: Code,
      inlineCode: InlineCode
    }}
  />

MDXProvider

If you're using an app layout that wraps your JSX, you can use the MDXProvider to only pass your components in one place:

import React from 'react'
import { MDXProvider } from '@mdx-js/tag'

import * as components from './markdown-components'

export default props =>
  <MDXProvider components={components}>
    <main {...props} />
  </MDXProvider>

Plugins

Since MDX uses the remark/rehype ecosystems, you can use plugins to modify the AST at different stages of the transpilation process.

If you look at the next example, it shows you to pass plugins as options to the MDX loader.

Options

Name	Type	Required	Description
mdPlugins	Array[]	false	Array of remark plugins to manipulate the MDXAST
hastPlugins	Array[]	false	Array of rehype plugins to manipulate the MDXHAST
skipExport	Boolean	false	Skip export default wrapper on transpiled JSX

Specifying plugins

Plugins need to be passed to the MDX loader via webpack options.

If a plugin needs specific options, use the [plugin, pluginOptions] syntax.

const images = require('remark-images')
const emoji = require('remark-emoji')
const toc = require('remark-toc')

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          {
            loader: 'babel-loader'
          },
          {
            loader: '@mdx-js/loader',
            options: {
              mdPlugins: [images, emoji, [toc, {heading: 'intro'}]]
            }
          }
        ]
      }
    ]
  }
}

Next.js

If you're using Next.js, you can specify options in your next.config.js.

const images = require('remark-images')
const emoji = require('remark-emoji')

module.exports = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx'],
  webpack: (config, { defaultLoaders }) => {
    config.module.rules.push({
      test: /\.md$/,
      use: [
        defaultLoaders.babel,
        {
          loader: '@mdx-js/loader',
          options: {
            mdPlugins: [images, emoji]
          }
        }
      ]
    })

    return config
  }
}

Sync API

If you're using the MDX library directly, you might want to process an MDX string synchronously.

const jsx = mdx.sync('# Hello, world!')

Related

See the related projects in the MDX specification

Authors

• John Otander (@4lpine) – Compositor + Clearbit
• Tim Neutkens (@timneutkens) – ZEIT
• Guillermo Rauch (@rauchg) – ZEIT
• Brent Jackson (@jxnblk) – Compositor