Writing Pages in MDX
gatsby-plugin-mdx, MDX files
src/pages will turn into pages.
Pages are rendered at a URL that is constructed from the filesystem
src/pages. An MDX file at
result in a page being rendered at
gatsby-plugin-mdxlooks for MDX files and automatically transpiles them so that Gatsby internals can render them.
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
MDXcontent, it must be included in the node system using a source like the
gatsby-source-filesystemplugin first. Instructions for sourcing content from somewhere like your
/src/pagesdirectory can be found on the plugin’s README.
Frontmatter is also available in
can be accessed in blocks of JSX in your MDX document:
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.
<Chart /> component coming from a
.js file would be written like any
other React component, while the
<FAQ /> component coming from an
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.
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:
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.
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:
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):
If you have provided a default layout in your
gatsby-plugin-mdx plugin options, the exported component you define
from this file will replace the default.
<PurpleBorder /> component might look something like this, wrapping the MDX
document in a
<div> with a 1px purple border:
You can fetch data to use in your MDX file by exporting a
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
Note: For now, this only works if the
.mdxfile exporting the query is placed in
src/pages. Exporting GraphQL queries from
.mdxfiles that are used for programmatic page creation in
actions.createPageis not currently supported.