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. 🌐
- Fast
- No runtime compilation
- Pluggable
- Element to React component mapping
- React component
import/export - Simpler image syntax
- Webpack loader
npm install --save-dev @mdx-js/loader @mdx-js/mdxNote: mdx requires a version of node that is >=
v8.5
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']
}
]
}
}
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
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;
}
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 />Similarly to JSX, components can be rendered after an import:
import Graph from './components/graph'
## Here's a graph
<Graph />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 />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>
)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>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
}}
/>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>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.
| 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 |
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'}]]
}
}
]
}
]
}
}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
}
}If you're using the MDX library directly, you might want to process an MDX string synchronously.
const jsx = mdx.sync('# Hello, world!')See the related projects in the MDX specification
- John Otander (@4lpine) – Compositor + Clearbit
- Tim Neutkens (@timneutkens) – ZEIT
- Guillermo Rauch (@rauchg) – ZEIT
- Brent Jackson (@jxnblk) – Compositor