Setup Pages in MDX

[00:00:00]
>> Let's actually add this MDX support here we're going to add a few different things. The first thing that we're gonna add is a, let's stop this development server. We're going to install some stuff. So we're going to install a source plugin for the file system. The reason for that Is we're gonna keep our posts in another folder here.

[00:00:22]
So let me close the open editors. And we're going to create a folder called posts. Now I want this folder to work just like the pages folder where, whatever we put in here becomes a page in Gatsby. In order to do that, we need to like Gatsby only looks for pages.

[00:00:43]
So we need to make this a special directory. And we're gonna do that with a combination of Gatsby source file system, which will let us look up files and then we're also going to use a plugin called page creator. And what page creator does, is it lets us set any page in the site, to have the same properties as the pages directory.

[00:01:09]
So anything inside of this should be created as a page. We also are gonna need the Gatsby plugin for MDX. And then we need MDX itself so MDXjs/MDX. We're also going to need the react flavor of MDX, so, MDX j s react, right? So this seems like a lot of stuff.

[00:01:32]
This one is so that we can actually load files into the into the Gatsby data layer. This one is so that we can turn any folder into a special folder of files that will get turned into pages. The Gatsby plugin MDX which is going to turn our files from just plain old files, it'll actually enable MDX support.

[00:01:58]
And then the MDX things so that we can use the MDX core and the react additional things that we need to use it in a react project. So let's get those installed. And next, once we've got those installed, we're gonna go into our Gatsby config and add support for these.

[00:02:22]
So inside of this array, we're going to, let me get this scaffolded and then I'll talk about what it actually is. So, by default, if you just put in the name of a plug in, Gatsby will run that plugin with no options. This is a shorthand. It's for convenience so that you don't have to write out these big old objects every time you wanna do a plugin.

[00:02:48]
But, if a plugin does need configuration, then we tell it to resolve the name of the plugin. So in our case, we're gonna start with Gatsby source file system. And then we can pass options to it. So in our case, we're going to give this group of files a name, we're gonna call them posts, and we're going to give them a path of the dirname, that's the current directory name and we're looking source and posts.

[00:03:18]
So we're trying to find this directory and load all the files into Gatsby's file system. So then we wanna make sure that Gatsby will actually create pages, from the pages that are found in there. So we're going to set up Gatsby plug in page creator. And for the options on that, we're actually gonna pass in the same path we want this dirname source posts.

[00:03:48]
And that will cause Gatsby to not only find these and load them into GraphQL but actually turned them into pages with their own address that matches the name of the file. Next, we want to transform those files from just plain old files into MDX nodes, and we do that using Gatsby plug in MDX.

[00:04:12]
Let me scroll up here, and for the options on this, we're going to start by giving it a default layout. Actually, you know what, let's start without a default layout and then we'll come back in and look at it so that we can how the difference so we'll add that in.

[00:04:29]
Okay, so now that we've got this, we've got our file system, we've got the page creator, we've got plugin MDX. Let's go ahead and add our first blog post. So let's add to I'm gonna add one called first blog and we use the dot MDX extension to signify that it is in fact MDX.

[00:04:50]
So we'll give this some basic markdown. This is my first blog post. All right, we can save that. Two exclamation boys is too many. All right, let's go in here and do another blog. Dot MDX, and in this one we will say, dang, this blog is even better than the last one.

[00:05:15]
All right, so now we've got two blog posts both are MDX And you can see here, we're not using any MDX features, we've just added in a plain old markdown. And one of the reasons to use MDX, it will actually add some react stuff a little bit later on, but, I really like this setup, because what we've just done if we start the server here again, is we have created the ability to now add these files in.

[00:05:45]
And again, all we've done here is we've said hey, Gatsby look in the file system, in this post folder, and create something called posts, and then use your page creator, to make pages out of anything ,in this post directory, and look for MDX. So, now that we've created this, if we look in here, everything is running.

[00:06:09]
Now I'm gonna go to that 404 page again. So I can just type in 404 and it'll say, hey, that's not a page. And down here, I can see here's our first blog and our another blog that we created. Okay. So this is fine, ish. It looks like it picked up our default styles, but it's not quite what we're after, we're missing our header and all those things.

[00:06:33]
And what we could do, and this is a pain, is we could go in here and we could say let's import layout from components layout.js, and then we will export default layout. Is that gonna work? No, it wouldn't be like that. It would be like this. It has to be a component like this.

[00:06:58]
So we would do layout, and then inside we would send the children, which means we have to get the children as a prop. I don't ever do this. So I'm, I'm trying to remember exactly how it works. There it is. Okay. So, upon doing this by doing a default.

[00:07:15]
We've provided a kind of a layout here. And if we wanted to do something like, this is part of my blog. Then we can add like custom markup. And this is all fine, right? But this is kind of I want to do that for every blog post. So instead what we can do is we can get rid of that entirely.

[00:07:38]
And we can come back out here and I wanna set a default layout. So inside of Gatsby plugin MDX, one of the options that I have is to set a default layout. And so I'm gonna say default layouts and four posts. This needs to match this, that's how that works.

[00:08:00]
And we're going to say require dot resolve, require dot resolve is a way to get the node internals to give you like the absolute path to a file. So what we're doing is we are doing the required resolve to source components, layout.js, right? So now we've got a default layout set and see our Gatsby saying we need to restart because we change the config.

[00:08:27]
I love this feature so we can hit OK. And it's gonna restart the development server for us. And when it's done, which we can watch happen over here. What we should see happen is the page in the background is gonna refresh. And it will actually use that layout.

[00:08:46]
So check that out. We have our first blog post. So, I'm happy about this. We've got our blog post is here, it has the header, and again, we did not have to add the layout, it's just there. And if we go to the other ones, so let me go back to this 404 page, click through to another blog, and there it is, no changes to another blog, which again, no layout included, but because we set a default it brings it in.

[00:09:16]
Now we can override this if we wanted to go back into the first blog, and instead of using the layout, I could just set it like a div and get rid of this layout. Then this one stays the same because we didn't edit it. But the first blog now it doesn't have that setup, right?

[00:09:39]
So we can optionally override whenever we need to if we need custom layouts, but by default, it'll use the same one. And that is a really nice feature. That's a really slick way to get this up and running. So this to me is a really powerful workflow because with fairly minimal config, we had to get into Gatsby config here and we had three plugins and this can feel like a lot.

[00:10:05]
I think that one of the most overwhelming parts of working with Gatsby can be, there's a lot of config, it can start to feel like it's hard to track what's going on. One way that you can group this is you can actually just go in here and start adding comments to let yourself know, this set of plugins is to enable creating MDX blog posts from the source posts folder, right?

[00:10:35]
And then down here you can do like end of MDX config. And then more config down here. So if you start to notice that you're getting overwhelmed by the amount of things you're putting into your Gatsby config. Leave yourself some signposts like let yourself know why you did something or why it's configured the way it is.

[00:10:52]
Our site is not particularly complex, so I'm not gonna stress too much about doing all of that. But
>> Is there a way to make that generic so that it would pick up multiple folders not just posts would I have to double that config?
>> The the part that gets tricky about this is the more generic these are the harder they are to track.

[00:11:13]
So there's there's something to be said for being pretty explicit about what you're loading and why. But, you know, again this this kind of comes down to personal preference. The other thing to consider is like, if you just did that it would work. But then you'd have in your GraphQL layer a bunch of extra stuff.

[00:11:36]
But if we create another folder inside of posts. Like, let's call this like a series and let's copy one of these. Call this one post one. This will get picked up in here, so if I go here now to series post one, it works. So if you put a folder in all of the sub folders will also get parsed.

[00:12:08]
And that's where this ignore option comes in like if you want it to ignore specialty stuff like this one saying ignore anything with a dot that starts with dot. You could say like, I only want to get things that have the dot page dot j s suffix, if you wanted to do something kind of mixed.

[00:12:28]
It's generally speaking easier to be pretty explicit about like this is a folder for pages, so that then your folder directories tend to line up pretty one to one like, okay, I'm in posts, so this means that the URL will be slash series, post one. And that way you don't have to remember like, yeah, it'll work like that except for this one that we ignored because it's for utilities.

[00:12:50]
Like if you've got utilities, pull them out of the post folder and put them somewhere else. And in that way, you don't have to have these like exclusions and special cases. Generally speaking, the easier you make it on yourself, the happier you'll be in the long term for maintenance.

[00:13:06]
>> Is there any way to pass like metadata with the config other than just wrapping it in a layout tag and then passing it to the props?
>> Yep, we're actually gonna do that right now I think.