Writing Pages in MDX

After installing gatsby-plugin-mdx, MDX files located in src/pages will turn into pages.

Pages are rendered at a URL that is constructed from the filesystem path inside src/pages. An MDX file at src/pages/awesome.mdx will result in a page being rendered at mysite.com/awesome.

gatsby-plugin-mdx looks for MDX files and automatically transpiles them so that Gatsby internals can render them.

Using frontmatter in MDX

By default, gatsby-plugin-mdx supports frontmatter so you can define things like titles and paths to use in your GraphQL queries. You can declare frontmatter at the beginning of your MDX document:

Which can then be queried with GraphQL:

Note: To query MDX content, it must be included in the node system using a source like the gatsby-source-filesystem plugin first. Instructions for sourcing content from somewhere like your /src/pages directory can be found on the plugin’s README.

Frontmatter is also available in props.pageContext.frontmatter and can be accessed in blocks of JSX in your MDX document:

Importing JSX components and MDX documents

Similarly to what you’d do in plain React, you can import and render JSX components directly in MDX files. You can also import other MDX documents.

The <Chart /> component coming from a .js file would be written like any other React component, while the <FAQ /> component coming from an .mdx file might look something like this:

Note: the default export concept used in this code block is explained in more detail in the docs below on defining layouts

You can read more about using React components from other libraries in the Importing and Using components in MDX guide.

Combining frontmatter and imports

If you would like to include frontmatter metadata and import components, the frontmatter needs to appear at the top of the file and then imports can follow:

Using JavaScript exports

MDX supports export syntax as well, which enables specific use cases like providing data for queries and rendering or overriding the default layout on MDX documents. You don’t need to export MDX documents to import them in other files.

Exporting page metadata

You can provide additional data about a given document by exporting. gatsby-plugin-mdx will automatically add it to the GraphQL schema so you can use the exported data in your queries and in rendering.

Data exported in MDX documents in this manner is also made available on the variable name you’ve assigned it.

You can export variables, objects, or other data structures:

The fields name and path defined on metadata could now alternatively be accessed on MDX nodes in other areas of your Gatsby project by a GraphQL query like this (this query fetches all MDX nodes and the data exports associated with them):

Defining a layout

If you have provided a default layout in your gatsby-config.js through the gatsby-plugin-mdx plugin options, the exported component you define from this file will replace the default.

The <PurpleBorder /> component might look something like this, wrapping the MDX document in a <div> with a 1px purple border:

GraphQL queries

You can fetch data to use in your MDX file by exporting a pageQuery in the same way you would for a .js page. The queried data is passed as a prop, and can be accessed inside any JSX block when writing in MDX:

Note: For now, this only works if the .mdx file exporting the query is placed in src/pages. Exporting GraphQL queries from .mdx files that are used for programmatic page creation in gatsby-node.js via actions.createPage is not currently supported.