gatsby-plugin-mdx

gatsby-plugin-mdx is the official integration for using MDX with Gatsby.

MDX is markdown for the component era. It lets you write JSX embedded inside markdown. It’s a great combination because it allows you to use markdown’s often terse syntax (such as # heading) for the little things and JSX for more advanced components.

Installation

``shell
npm install gatsby-plugin-mdx gatsby-source-filesystem @mdx-js/react
`

Usage

> This README assumes you're using gatsby@5.3.0 or later. If you're using an older Gatsby version or don't want to use ESM for your Gatsby files, refer to this older version of the README.

After installing gatsby-plugin-mdx you can add it to your plugins list in your gatsby-config.

We highly recommend using ES Modules (ESM) syntax for your gatsby-config file as it'll enable you to use the latest packages from the unified ecosystem.

You'll also want to configure gatsby-source-filesystem to point at your src/pages directory.

`js:title=gatsby-config.mjs
import { dirname } from "path"
import { fileURLToPath } from "url"

const __dirname = dirname(fileURLToPath(import.meta.url))

const config = {
plugins: [
gatsby-plugin-mdx,
{
resolve: gatsby-source-filesystem,
options: {
name: pages,
path: ${__dirname}/src/pages,
},
},
],
}

export default config
`

By default, this configuration will allow you to automatically create pages with .mdx files in src/pages.

If you have MDX files in another location than src/pages you'll need to add another instance of gatsby-source-filesystem and configure the path to point at this folder. This is necessary for MDX files that you want to import into React components or for files you want to query via GraphQL.

Please Note:

- gatsby-plugin-mdx requires gatsby-source-filesystem to be present and configured to process local MDX files in order to generate the resulting Gatsby nodes (gatsby-source-filesystem needs to discover all MDX files in order to create MDX nodes and allow the processing for each of them).
- MDX syntax differs from Markdown as it only supports CommonMark by default. Nonstandard markdown features like GitHub flavored markdown (GFM) can be enabled with plugins (see mdxOptions instructions). GFM includes features like tables or footnotes.
- Certain features like HTML syntax doesn't work in MDX. Read the "What is MDX?" guide to learn more.

To automatically create pages from MDX files outside of src/pages you'll need to configure gatsby-plugin-page-creator and gatsby-source-filesystem to point to this folder of files.

`js:title=gatsby-config.mjs
import { dirname } from "path"
import { fileURLToPath } from "url"

const __dirname = dirname(fileURLToPath(import.meta.url))

const config = {
plugins: [
gatsby-plugin-mdx,
{
resolve: gatsby-source-filesystem,
options: {
name: posts,
path: ${__dirname}/src/posts,
},
},
{
resolve: gatsby-plugin-page-creator,
options: {
path: ${__dirname}/src/posts,
},
},
],
}

export default config
`

Also check out the guide Adding MDX Pages for more details.

Configuration

gatsby-plugin-mdx exposes a configuration API that can be used similarly to any other Gatsby plugin. You can define MDX extensions, layouts, global scope, and more.

| Key | Default | Description |
| ------------------------------------------------ | ---------- | ------------------------------------------------------------------- |
| extensions | [".mdx"] | Configure the file extensions that gatsby-plugin-mdx will process |
| gatsbyRemarkPlugins | [] | Use Gatsby-specific remark plugins |
| mdxOptions | {} | Options directly passed to compile() of @mdx-js/mdx |

$3

By default, only files with the .mdx file extension are treated as MDX when
using gatsby-source-filesystem. To use .md or other file extensions, you can
define an array of file extensions in the gatsby-plugin-mdx section of your
gatsby-config.js.

`js:title=gatsby-config.mjs
const config = {
plugins: [
{
resolve: gatsby-plugin-mdx,
options: {
extensions: [.mdx, .md],
},
},
],
}

export default config
`

$3

This config option is used for compatibility with a set of plugins many people use with remark that require the Gatsby environment to function properly. In some cases, like gatsby-remark-prismjs, it makes more sense to use a library like prism-react-renderer to render codeblocks using a React component. In other cases, like gatsby-remark-images, the interaction with the Gatsby APIs is well deserved because the images can be optimized by Gatsby and you should continue using it.

When using these gatsby-remark-* plugins, be sure to also install their required peer dependencies. You can find that information in their respective README.

`js:title=gatsby-config.mjs
const config = {
plugins: [
{
resolve: gatsby-plugin-mdx,
options: {
gatsbyRemarkPlugins: [
{
resolve: gatsby-remark-images,
options: {
maxWidth: 590,
},
},
],
},
},
],
}

export default config
`

Using a string reference is also supported for gatsbyRemarkPlugins.

`js
gatsbyRemarkPlugins: [gatsby-remark-images]
`

$3

These configuration options are directly passed into the MDX compiler.

See all available options in the official documentation of @mdx-js/mdx.

`js:title=gatsby-config.mjs
import remarkGfm from "remark-gfm"
import remarkExternalLinks from "remark-external-links"
import rehypeSlug from "rehype-slug"
import rehypeAutolinkHeadings from "rehype-autolink-headings"

const config = {
plugins: [
{
resolve: gatsby-plugin-mdx,
options: {
mdxOptions: {
remarkPlugins: [
// Add GitHub Flavored Markdown (GFM) support
remarkGfm,
// To pass options, use a 2-element array with the
// configuration in an object in the second element
[remarkExternalLinks, { target: false }],
],
rehypePlugins: [
// Generate heading ids for rehype-autolink-headings
rehypeSlug,
// To pass options, use a 2-element array with the
// configuration in an object in the second element
[rehypeAutolinkHeadings, { behavior: wrap }],
],
},
},
},
],
}

export default config
`

Please Note: Most of the remark/rehype/unified ecosystem is published as ESM which means that you have to use ES Modules (ESM) and Gatsby.

Imports

When importing a React component into your MDX, you can import it using the import statement like in JavaScript.

`mdx
import { SketchPicker } from "react-color"

Hello, world!

Here's a color picker!


`

Note: You should restart gatsby develop to update imports in MDX files. Otherwise, you'll get a ReferenceError for new imports. You can use the shortcodes approach if that is an issue for you.

Layouts

You can use regular layout components to apply layout to your sub pages.

To inject them, you have several options:

1. Use the wrapPageElement API including its SSR counterpart.
1. Add an export default Layout statement to your MDX file, see MDX documentation on Layout.
1. When using the createPage action to programatically create pages, you should use the following URI pattern for your page component: your-layout-component.js?__contentFilePath=absolute-path-to-your-mdx-file.mdx. To learn more about this, head to the programmatically creating pages guide.

Programmatically create MDX pages

Read the MDX documentation on programmatically creating pages to learn more.

GraphQL MDX Node structure

In your GraphQL schema, you will discover several additional data related to your MDX content. While your local GraphiQL will give you the most recent data, here are the most relevant properties of the Mdx entities:

| Property | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| frontmatter | Sub-entity with all frontmatter data. Regular Gatsby transformations apply, like you can format dates directly within the query. |
| excerpt | A pruned variant of your content. By default trimmed to 140 characters. Based on rehype-infer-description-meta. |
| tableOfContents | Generates a recursive object structure to reflect a table of contents. Based on mdast-util-toc. |
| body | The raw MDX body (so the MDX file without frontmatter) |
| internal.contentFilePath | The absolute path to the MDX file (useful for passing it to ?__contentFilePath query param for layouts). Equivalent to the absolutePath on File nodes. |

Extending the GraphQL MDX nodes

Use the createNodeField action to extend MDX nodes. All new items will be placed under the fields key. You can alias your fields to have them at the root of the GraphQL node.

$3

1. Install reading-time into your project:
`shell
npm install reading-time
`
1. In your gatsby-node add a new field:

`js:title=gatsby-node.mjs
import readingTime from "reading-time"

export const onCreateNode = ({ node, actions }) => {
const { createNodeField } = actions
if (node.internal.type === Mdx) {
createNodeField({
node,
name: timeToRead,
value: readingTime(node.body)
})
}
}
`

1. You're now able to query the information on the MDX node:
`graphql
query {
mdx {
fields {
timeToRead {
minutes
text
time
words
}
}
}
}
`

$3

See timeToRead. It returns timeToRead.words.

$3

This largely comes down to your own preference and how you want to wire things up. This here is one of many possible solutions to this:

1. Install @sindresorhus/slugify into your project:
`shell
npm install @sindresorhus/slugify
`
1. In your gatsby-node add a new field:

`js:title=gatsby-node.mjs
import slugify from "@sindresorhus/slugify"

export const onCreateNode = ({ node, actions }) => {
const { createNodeField } = actions
if (node.internal.type === Mdx) {
createNodeField({
node,
name: slug,
value: /${slugify(node.frontmatter.title)}
})
}
}
`

1. You're now able to query the information on the MDX node:
`graphql
query {
mdx {
fields {
slug
}
}
}
`

If you don't want to use the frontmatter.title, adjust what you input to slugify(). For example, if you want information from the File node, you could use getNode(node.parent).

$3

1. Install necessary dependencies into your project:
`shell
npm install mdast-util-to-string unist-util-visit
`
1. Create a new file called remark-headings-plugin.mjs at the site root:

`js:title=remark-headings-plugin.mjs
import { visit } from "unist-util-visit"
import { toString } from "mdast-util-to-string"

const transformer = (tree, file) => {
let headings = []

visit(tree, heading, heading => {
headings.push({
value: toString(heading),
depth: heading.depth,
})
})

const mdxFile = file
if (!mdxFile.data.meta) {
mdxFile.data.meta = {}
}

mdxFile.data.meta.headings = headings
}

const remarkHeadingsPlugin = () => transformer

export default remarkHeadingsPlugin
`

1. Add a new headings field resolver to your Mdx nodes through createSchemaCustomization API:

`js:title=gatsby-node.mjs
import { compileMDXWithCustomOptions } from "gatsby-plugin-mdx"
import remarkHeadingsPlugin from "./remark-headings-plugin.mjs"

export const createSchemaCustomization = async ({ getNode, getNodesByType, pathPrefix, reporter, cache, actions, schema, store }) => {
const { createTypes } = actions

const headingsResolver = schema.buildObjectType({
name: Mdx,
fields: {
headings: {
type: [MdxHeading],
async resolve(mdxNode) {
const fileNode = getNode(mdxNode.parent)

if (!fileNode) {
return null
}

const result = await compileMDXWithCustomOptions(
{
source: mdxNode.body,
absolutePath: fileNode.absolutePath,
},
{
pluginOptions: {},
customOptions: {
mdxOptions: {
remarkPlugins: [remarkHeadingsPlugin],
},
},
getNode,
getNodesByType,
pathPrefix,
reporter,
cache,
store,
}
)

if (!result) {
return null
}

return result.metadata.headings
}
}
}
})

createTypes([

type MdxHeading {
value: String
depth: Int
}
,
headingsResolver,
])
}
`

1. You're now able to query the information on the MDX node:
`graphql
query {
mdx {
headings {
value
depth
}
}
}
`

Components

MDX and gatsby-plugin-mdx use components for different things like rendering and component mappings.

$3

MDXProvider is a React component that allows you to replace the
rendering of tags in MDX content. It does this by providing a list of
components via context to the internal MDXTag component that handles
rendering of base tags like p and h1.

`jsx
import { MDXProvider } from "@mdx-js/react"

const MyH1 = props =>

tomato }} {...props} />
const MyParagraph = props => (

)

const components = {
h1: MyH1,
p: MyParagraph,
}

export const ComponentsWrapper = ({ children }) => (
{children}
)
`

The following components can be customized with the MDXProvider:

| Tag | Name | Syntax |
| --------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
| p | Paragraph | |
| h1 | Heading 1 | # |
| h2 | Heading 2 | ## |
| h3 | Heading 3 | ### |
| h4 | Heading 4 | #### |
| h5 | Heading 5 | ##### |
| h6 | Heading 6 | ###### |
| thematicBreak | Thematic break | * |
| blockquote | Blockquote | > |
| ul | List | - |
| ol | Ordered list | 1. |
| li | List item | |
| table | Table | --- | --- | --- |
| tr | Table row | This | is | a | table row |
| td/th | Table cell | |
| pre | Pre | |
| code | Code | |
| em | Emphasis | _emphasis_ |
| strong | Strong | strong |
| delete | Delete | ~~strikethrough~~ |
| hr | Break | --- |
| a | Link | or MDX |
| img | Image | !alt |


It's important to define the components you pass in a stable way
so that the references don't change if you want to be able to navigate
to a hash. That's why we defined components outside of any render
functions in these examples.

$3

If you want to allow usage of a component from anywhere (often referred to as a shortcode), you can pass it to the MDXProvider.

`jsx:title=src/components/layout.jsx
import React from "react"
import { MDXProvider } from "@mdx-js/react"
import { Link } from "gatsby"
import { YouTube, Twitter, TomatoBox } from "./ui"

const shortcodes = { Link, YouTube, Twitter, TomatoBox }

export const Layout = ({ children }) => (
{children}
)
`

Then, in any MDX file, you can navigate using Link and render YouTube, Twitter, and TomatoBox components without
an import.

`mdx


Hello, world!

Here's a YouTube embed




`

Read more about injecting your own components in the official MDX provider guide.

Migrating from v3 to v4

gatsby-plugin-mdx@^4.0.0 is a complete rewrite of the original plugin with the goal of making the plugin faster, compatible with MDX v2, leaner, and more maintainable. While doing this rewrite we took the opportunity to fix long-standing issues and remove some functionalities that we now think should be handled by the user, not the plugin. In doing so there will be of course breaking changes you'll have to handle – but with the help of this migration guide and the codemods you'll be on the new version in no time!

$3

`shell
npm remove @mdx-js/mdx
npm install gatsby-plugin-mdx@latest @mdx-js/react@latest
`

If you used any related plugins like gatsby-remark-images, also update them to their @latest version.

$3

- Move your remarkPlugins and rehypePlugins keys into the new mdxOptions config option:

`diff
const config = {
plugins: [
{
resolve: gatsby-plugin-mdx,
options: {
- remarkPlugins: [],
- rehypePlugins: [],
+ mdxOptions: {
+ remarkPlugins: [],
+ rehypePlugins: [],
+ },
},
},
],
}

export default config
`

- There's a new option called mdxOptions which is passed directly to the MDX compiler. See all available options in the official documentation of @mdx-js/mdx.
- Only extensions, gatsbyRemarkPlugins, and mdxOptions exist as options now. Every other option got removed, including defaultLayouts. See the layouts guide to learn how to use layouts with gatsby-plugin-mdx@^4.0.0.
- Make sure that any gatsby-remark-* plugins are only listed inside the gatsbyRemarkPlugins array of gatsby-plugin-mdx, not inside the plugins array of gatsby-config or in any other place.

$3

- GitHub flavored markdown (GFM) support was removed from MDX v2. You can re-enable it with mdxOptions (you have to install remark-gfm)
- Most of the remark ecosystem is ESM so just using the latest package version of remark-/rehype- most probably won't work. Check out the workarounds mentioned in mdxOptions

$3

In most cases the changes necessary here are related to the removal of defaultLayouts option and the new way how layouts are done. See the layouts guide to learn how to use layouts with gatsby-plugin-mdx@^4.0.0.

You'll need to do two things to continue using your old layout file:

1. You need to query the absolute path to the MDX file
1. You have to attach this MDX file via the __contentFilePath query param to your layout file

`diff
const postTemplate = path.resolve(./src/templates/post.jsx)

actions.createPage({
- component: postTemplate,
+ component: ${postTemplate}?__contentFilePath=/path/to/content.mdx,
})
`

Or a more complete example:

`js
const postTemplate = path.resolve(./src/templates/post.jsx)

// Rest of createPages API...

const { data } = await graphql(
{
allMdx {
nodes {
id
frontmatter {
slug
}
// highlight-start
internal {
contentFilePath
}
// highlight-end
}
}
}
)

data.allMdx.nodes.forEach(node => {
actions.createPage({
path: node.frontmatter.slug,
component: ${postTemplate}?__contentFilePath=${node.internal.contentFilePath}, // highlight-line
context: {
id: node.id,
},
})
})
`

You'll also need to update your template file itself, see the next section Updating page templates.

Note: You could also directly pass the MDX file to the component like this:

`js
actions.createPage({
component: /path/to/content.mdx,
// If you don't want to construct it yourself, use internal.contentFilePath
// component: node.internal.contentFilePath
})
`

However, we'd recommend placing such files into the src/pages directory and gatsby-plugin-mdx will handle the page creation itself.

$3

1. Instead of querying for the body on the MDX node, the page template now receives the transformed MDX as children property.
1. You no longer need to use as you can use {children} directly.

`diff
import React from "react"
import { graphql } from "gatsby"
- import { MDXRenderer } from "gatsby-plugin-mdx"

- function PostTemplate({ data: { mdx } }) {
+ function PostTemplate({ data: { mdx }, children }) {

return (


{mdx.frontmatter.title}

-
- {mdx.body}
-
+ {children}

)
}

export const pageQuery = graphql
query PostTemplate($id: String!) {
mdx(id: { eq: $id }) {
frontmatter {
title
}
- body
}
}

export default PostTemplate
`

$3

As MDX v2 changed the way it handles content you might need to update your MDX files to be valid MDX now. See their Update MDX content guide for all details. In What is MDX? it is also laid out which features don't work. Most importantly for this migration:

- HTML syntax doesn’t work in MDX as it’s replaced by JSX ( to ). Instead of HTML comments, you can use JavaScript comments in braces: {/ comment! /}
- Unescaped left angle bracket / less than (<) and left curly brace ({) have to be escaped: \< or \{ (or use expressions: {'<'}, {'{'})
- If you're using the enableCustomId option from gatsby-remark-autolink-headers you'll run into problems due to the above. You need to disable this option and use rehype-slug-custom-id instead.

In our testing, most of the time the issue were curly brackets that needed to be escaped with backticks:

`diff
- You can upload this to Git{Hub,Lab}
+ You can upload this to Git{Hub,Lab}
`

You can also use eslint-mdx to find all culprits and in some cases automatically fix them through ESLint.

$3

Since most MDX nodes are moved to userland you'll have to extend the GraphQL MDX nodes and update your queries accordingly. However, you can alias your fields to have them at the root of the GraphQL node.

Here's an example of an updated query (if you re-implemented most features):

`diff
{
- timeToRead
- rawBody
- slug
headings
- html
- mdxAST
- wordCount
- fileAbsolutePath
+ body
+ fields {
+ timeToRead
+ slug
+ }
+ internal {
+ contentFilePath
+ }
}
`

Here's an example on how you'd alias your fields to keep the shape of the MDX node the same:

`js:title=gatsby-node.mjs
import readingTime from "reading-time"

export const onCreateNode = ({ node, actions }) => {
const { createNodeField } = actions
if (node.internal.type === Mdx) {
createNodeField({
node,
name: timeToRead,
value: readingTime(node.body)
})
}
}

export const createSchemaCustomization = ({ actions }) => {
const { createTypes } = actions

createTypes(#graphql
type Mdx implements Node {
# You can also use other keys from fields.timeToRead if you don't want "minutes"
timeToRead: Float @proxy(from: "fields.timeToRead.minutes")
wordCount: Int @proxy(from: "fields.timeToRead.words")
}
)
}
`

$3

- Removed plugin options: defaultLayouts, mediaTypes, lessBabel, shouldBlockNodeFromTransformation, commonmark
- Moved plugin options remarkPlugins and rehypePlugins into mdxOptions
- Removed timeToRead, rawBody, slug, headings, html, mdxAST, wordCount, fileAbsolutePath from the query result. You can check Extending the GraphQL MDX nodes to learn how to re-implement some of them on your own. Also check Updating MDX nodes for guidance on changing your queries
- gatsby-plugin-mdx only applies to local files (that are sourced with gatsby-source-filesystem)
- Removed the ability to use js and json in frontmatter
- Loading MDX from other sources as the filesystem is not supported. If you have a need for that, please comment in the GitHub Discussion
- All MDX v2 migration notes apply

As mentioned above the html field was removed from the GraphQL node. We know that some of you used this for e.g. gatsby-plugin-feed. Unfortunately, for compatibility and performance reasons we had to remove it. We recommend using the excerpt` field in the meantime until we find a feasible solution to provide MDX rendered as HTML. If you have any suggestions, please comment on the GitHub Discussion.

Why MDX?

Before MDX, some of the benefits of writing Markdown were lost when integrating with JSX. Implementations were often template string-based which required lots of escaping and cumbersome syntax.

MDX seeks to make writing with Markdown and JSX simpler while being more expressive. Writing is fun again when you combine components, that can even be dynamic or load data, with the simplicity of Markdown for long-form content.

Related

- What is MDX
- Using MDX
- Troubleshooting MDX
- Adding MDX Pages