Check out a free preview of the full Intermediate Gatsby with Gatsby Themes course:
The "Creating an MDX Page" 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 explains what Gatsby looks for and executes when rendering a page. How to render a page, its MDX content, and its layout is also discussed.

Get Unlimited Access Now

Transcript from the "Creating an MDX Page" Lesson

[00:00:00]
>> Once we have the template, we can define a component to use the query. And so that is gonna get the result of this query as data. So the way that Gatsby works during the build is it's gonna look for this exported query. And it will actually executed, get the data and then inject that data as a data prop to this component.

[00:00:23] This is all done during the build so there is kind of a rewrite process. Again, another reason to keep these templates separate so that it's clear that they get special handling. That data then is going to be put somewhere and what I like to do is just pass it directly to a component that we'll use it.

[00:00:43] And so I'm just gonna do that, I'm gonna go straight into the data.docsPage can go in. And now we have to define that but first, let's export this DocsPage. Okay, so we're gonna need to go get this, this DocsPage. I'm gonna put it in components. We'll call it doc's-page.js and inside of this one we're going to import react from react.

[00:01:12] We will import the MDXRenderer. And the MDXRenderer is used to actually make this into something readable. So all this code that MDX generates, we wanna be able to use it, and the MDXRenderer makes that possible for us. I'm also gonna pull in the Layout that we used, so let me get that.

[00:01:41] And then, we can do a DocsPage component. We will then put this layout in here, do an h1, do page title, and then put in the MDXRenderer, page dot body goes inside of that. And then we'll put a little note at the bottom that says this page was updated.

[00:02:13] Whenever the updated value is, and again, it's plain language, so we can just drop it right into the sentence. So we're gonna export default Doc'sPage. And then I can save that, come back here and let's Import this so that we can use it. Import Doc'sPage from components, Doc'sPage.

[00:02:39] And now, if I stop and restart, or what I need to, before we stop and restart, we need to actually use these templates. So we've defined them, but now we need to run the Create Page API hook. So back in our gatsby-node, all the way down at the bottom here.

[00:02:57] We're going to use exports, createPages. And because we're gonna make a request for data, we're gonna mark this as an async function. And the createPages API gives us a few things. The first is an actions object that gives us a bunch of helper functions. A graphqL function that'll allow us to get some data.

[00:03:22] And then we also have a reporter in case we wanna output anything to the console, and then the second argument is gonna be the options from the theme. So, We're not really using the options. So I'm gonna just skip that actually. So we're gonna get an object full of actions, the graphqL function and a reporter function.

[00:03:51] And then inside, we start out by getting our data. So we want to do a graphql query. And inside the createPages graphql is a function, not a template tag. That's a little bit of a gotcha at the beginning. And inside I'm gonna get all the DocsPages. And I want all the nodes, and all I need in here is the id and the path.

[00:04:14] So the id I'm gonna use to pass in this context and the path I'm gonna use as a definition for the URL. So we've awaited that result. Then we're just gonna do a quick check to see if anything wrong. So if result.errors, we will panic. So we'll do reporter.panic and we'll say, error loading docs and just pass in the errors.

[00:04:48] If we get through that, we can assume everything's okay. So we'll just grab out our pages by diving into our data here. So we'll do result.data.allDocsPage.nodes. And then once we've got those pages, we can loop through them so we'll do a forEach because we're not returning anything. And forEach page, we're going to run an action called createPage.

[00:05:13] And that accepts an object which has two required fields and one optional field that we're gonna use. The first required field is path. And for that, we're gonna use the page path. And that's again what we defined using the base path, the relative directory and then the file name.

[00:05:32] Next, we need to give it a component. And that component is gonna be the template that we just defined. So we'll do a require.resolve, go into our source templates, and the docs-page template. And finally, we need to set some context. And the context is an object. This is arbitrary, we can put whatever we want.

[00:05:51] There are a few reserved fields, but for the most part, it should be okay. In the context you'll you'll get a big warning if you use a reserved field. So in the context, I'm gonna pass in this pageID and I want that to be the page.id. And whatever name I give it now, it will become available as a graph qL variable.

[00:06:15] So we defined in here pageID. So by defining pageID in the context, we're able to access it. And once we've done this, we are fingers crossed, ready to rock and roll. So let's build some pages. That's promising, we're getting two pages. Let's give it a look. Hey, there we go.

[00:06:43] So now we've got our Home page. It shows the MDX content. It shows our layout, and it shows us when the page was updated. So that means that we've got data coming in getting customized through Gatsby's data layer and now it's on the screen. So this is pretty powerful, right?

[00:07:01] We're in pretty good shape here. So our next move here is going to be to make this look slightly less terrible. And in a way that's more extensible. What's up?
>> Why did it put up two pages I thought it was only the one MDX file.
>> So there's only the one MDX file, but Gatsby will always give you a 404 page.

[00:07:22] So if we go to a page that I have it disabled if we go to a page that doesn't exist, so let me boot this up. It will also give us this 404 page. So this is the page that's being referenced as the second one. And that's a really nice thing to have during development because especially if you haven't set up your navigation or something yet.

[00:07:47] You can get to the point where like, you've created a bunch of pages but you haven't built the list to show them all. Well this will give you that list. So it's a nice little convenience thing to have when you're still in progress and things are kind of in various stages of flux to make sure that you don't forget to link to certain pages.