Check out a free preview of the full Intermediate Gatsby with Gatsby Themes course:
The "Loading MDX Files" Lesson is part of the full, Intermediate Gatsby with Gatsby Themes course featured in this preview video. Here's what you'd learn in this lesson:

Jason demonstrates how to create an mdx file, and how to install the Gatsby source file system, the necessary Gatsby mdx dependencies, and the use External MDX hook to determine if MDX should be used inside a theme. MDX is a markdown that allows the use of embedded JSX.

Get Unlimited Access Now

Transcript from the "Loading MDX Files" Lesson

>> Jason Lengstorf: So when we create an MDX file, and I'm gonna create this in our theme dev in that docs folder, and we're just gnna call it index because I want a kind of a homepage, right? So, the default way of writing MDX is we can just say, Hello and that's a page, right?

[00:00:16] Like that could be a page on the Internet. We wanna add a little more information than that. So I'm actually gonna start with some front matter. And the way that front matter works in Markdown is we use these triple dashes as a kind of fenced code block. And then we use YAML syntax to say what our front matter is.

[00:00:38] So we want a field called title to show up on a front matter, and this will be what the value of it is and these are arbitrary. You can set whatever you want in here and most YAML syntax should work. And then below our code block, we can say something like, These are docs!

>> Jason Lengstorf: And on saving that, we've got a completely valid MDX file that we can use however we want. So let's get this loaded into the site using the theme so that we can show it. So the first thing that we're gonna do is we're going to install some things in the theme.

[00:01:19] So we'll go yarn workspace gatsby-theme-docs, and we will add the gatsby-source-file-system. And what Gatsby-source-file-system does is it allows us to use a folder in the project itself as a data source. So it'll put it in the GraphQL layer so we can do stuff with it. Then we're going to use gatsby-plugin-mdx and what Gatsby plugin MDX will do is it'll look for any files that are of the type dot MDX And it will convert them into MDX nodes, which means that we can get at the content of that file.

[00:01:55] And then gatsby-plugin-mdx has some dependencies, so we need to use the mdx-js/mdx package and then we also need to use the mdx-js/react package.
>> Jason Lengstorf: So we'll get those installed.
>> Jason Lengstorf: And now, we can get those configured in our gatsby-config for the theme. So we're gonna create a gatsby-config next to our gatsby-node,

>> Jason Lengstorf: And again, we're going to do module.exports. Now the standard way that you would write a config file is you would have just an object, right? But because we're in a theme, this becomes a function that receives those options. And because we're receiving options, we wanna use our defaults.

[00:02:48] So let's import that, we're gonna import with defaults and require utility file.
>> Jason Lengstorf: And so up here we're going to get the things we need. So we're gonna use the contentPath cuz we need to tell the file system where to look and we're going to use external MDX because we need to know whether or not we should load the MDX plugin inside the theme.

[00:03:13] So we'll say withDefaults(options), and then we can return our config object. And in this case, we're just gonna return some plugins. The first one is always gonna be used and that is resolve gatsby-source-file-system.
>> Jason Lengstorf: And the options that we wanna send it first is name, and I'm gonna use the plugin name.

[00:03:37] And we'll talk more about why in a minute, but the general idea is that we wanna be able to identify which files were loaded by this theme. Because when we go to create pages from it, if another theme uses MDX, we wouldn't want to create docs pages out of some a blog themes, MDX files.

[00:04:01] And we wanna grab those from the contentPath. So, this will give us the files that we want in our file system. And,
>> Jason Lengstorf: Let's get the Markdown here. So we'll go useExternalMDX. So if useExternalMDX is set to true we're just gonna skip this whole step. So that's what we're checking here.

[00:04:29] And so if it is false, we're going to say resolve gatsby-plugin-mdx and for the options, we will use defaultLayouts. And we haven't defined this yet, but we're gonna set up a default layout for our MDX files. And what this means is that when we load an MDX file, Gatsby is going to look for this wrapper component and put the MDX files inside of it.

[00:05:00] And that gives us a way to control the output without having to write a bunch of custom code inside of the MDX files themselves. And so we will put that at source/components/layout.js.
>> Jason Lengstorf: And finally, once we get down here, because there's a chance that this is gonna be false, we are going to filter our plugin array because we wanna make sure that we don't send back just a false value that'll cause Gatsby to complain.

[00:05:32] So we're gonna filter for Boolean so that it drops any false values. That's kind of a hacky way to say like if it exists
>> Jason Lengstorf: But I really like this as a way of kind of keeping it terse when you're doing that sort of thing.