Convert the Gatsby starter blog to use MDX part two
This is a private post 🤫
This means it's probably incomplete and not intended for public consumption.
Since publishing my last post on this Chris Biscardi has released an awesome MDX egghead.io course that goes over using MDX in a Gatsby application. If you want to see how the pros do it then take a look at the play list, it’s an egghead community resource so you can watch it for free.
What’s new in this guide
I’ve already covered the conversion here if you want to check that out, I’ll be going over that again here but also adding:
- Code blocks 🎉
- Using components for page elements
I’ve gone and made a video of the conversion as well, here:
video: https://www.youtube.com/watch?v=gck4RjaX5D4
Versions:
This guide is being used with the following dependency versions.
- @mdx-js/mdx: 1.0.27
- @mdx-js/react: 1.0.27
- gatsby-plugin-mdx: 1.0.13
- gatsby: 2.13.8
- react: 16.9.0
- react-dom: 16.9.0
You can also check out the example code.
We’re going to need some links, which are:
Import to CodeSandbox
If you want to follow along then go grab the URL for the Gatsby starter blog paste it into the CodeSandbox import wizard this will open the representation of the code on GitHub.
Click on the fork button so we can start making changes.
Now we’re going to go about moving from using Gatsby transformer remark over to MDX.
For the initial conversion the majority of the changes will be
replacing MarkdownRemark
with Mdx
and allMarkdownRemark
with allMdx
.
First we’re going to need to import some dependencies to get MDX running in our Gatsby project.
With the add dependency button in CodeSandbox add the following dependencies:
gatsby-plugin-mdx
@mdx-js/mdx
@mdx-js/react
yarn add gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react
Ok, the files to change are:
gatsby-node.js
gatsby-config.js
index.js
blog-post.js
Let’s start editing them! 🚲
gatsby-node.js
Change allMarkdownRemark
occurrences with allMdx
, and change the node.internal.type
from MarkdownRemark
to Mdx
.
gatsby-config.js
Here we’re going to replace gatsby-transformer-remark
with gatsby-plugin-mdx
and add in the extensions array for both .mdx
and .md
file types.
extensions: [`.mdx`, `.md`],
Then rename the plugins
array to gatsbyRemarkPlugins
we also need
to add a plugins
array to cater for gatsby-remark-images
as well.
plugins: [
{
resolve: `gatsby-remark-images`,
options: {
maxWidth: 590,
},
},
],
index.js
Here we’re going to alter the posts
variable to take the Mdx
edges.
The Mdx
edges are taken from the page query, which is also altered
to use allMdx
in place of allMarkdownRemark
.
Replace the dangerouslySetInnerHTML
prop with a normal <p>
tag:
<p
dangerouslySetInnerHTML={{
__html: node.frontmatter.description || node.excerpt,
}}
/>
Replace with:
<p>{node.frontmatter.description || node.excerpt}</p>
blog-post.js
Now last on the list to get MDX working is the blog post template,
we’re going to need to import MDXRenderer
from gatsby-plugin-mdx
we’re going to replace dangerouslySetInnerHTML
with this shortly.
Here’s where we use it, we’ll come onto post.code.body
.
Again in the query we’re replacing markdownRemark
with mdx
and
this time also doing away with html
from the query and adding in body
which we’re using in our render method.
<div dangerouslySetInnerHTML={{ __html: post.html }} />
<MDXRenderer>{post.body}</MDXRenderer>
Now we’re using MDX!
So now we can create a .mdx
post, and import a react component into
it.
First let’s make an index.mdx
file in content/blog/
and add some
frontmatter and some content:
---
title: Hello MDX!
date: 2019-07-14
---
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
---
We’re going to use this component in a .mdx
document, first the
component:
import styled from 'styled-components'
export const Butt = styled.button`
background-color: red;
height: 40px;
width: 80px;
`
Spicy, right! 🌶
Now we can include this component in a .mdx
document so let’s go
ahead and create that, in content/blog
make a new directory, I’m
giving mine the imaginative name first-mdx-post
, in there create a index.mdx
file and use the frontmatter from one of the other posts
as an example of what to use:
---
title: My First MDX Post!
date: '2019-04-07T23:46:37.121Z'
---
# make a site they said, it'll be fun they said
more content yo!
This will render a h1
and a p
and we should see it render in our
CodeSandbox preview.
Now we can go ahead and import our beautifully crafted button:
---
title: My First MDX Post!
date: '2019-04-07T23:46:37.121Z'
---
import { Butt } from '../../../src/components/button'
# make a site they said, it'll be fun they said
more content yo!
<Butt>yoyoyo</Butt>
MDXProvider
If you want to change the rendering of any of the page elements, i.e. H1
, H2
, p
, a
, li
etc. Then we can use the MDXProvider
, MDXProvider
is a component that we can place anywhere in the
component tree but it make sense to have it as high up the component
tree as possible.
The MDXProvider
is what we’re going to use to override our page
elements by using the Gatsby browser and Gatsby SSR API wrapRootElement
, this will allow us to wrap the entire application
with an MDXProvider
.
Wrap up!
Ok, we’ve gone and converted the Gatsby starter blog from using Markdown Remark over to using MDX and added some custom components for the page elements
Thanks for reading 🙏
I hope you found this guide helpful.
Please take a look at my other content if you enjoyed this.
Follow me on Twitter or Ask Me Anything on GitHub.
There's a reactions leaderboard you can check out too.