This course has been updated! We now recommend you take the Introduction to Gatsby, v2 course.

Check out a free preview of the full Introduction to Gatsby course:
The "Rendering Components in MDX" Lesson is part of the full, Introduction to Gatsby course featured in this preview video. Here's what you'd learn in this lesson:

Jason walks through the process of rendering full React components inside Markdown with MDX.

Get Unlimited Access Now

Transcript from the "Rendering Components in MDX" Lesson

>> Jason Lengstorf: MDX, it doesn't actually stand for anything I don't think. The way that React used JSX which gives you the ability to write HTML inside of your JavaScript templates. MDX is a way to enable using React components inside of mark down. So it's sort of a riff on JSX is MDX.

[00:00:22] And so what we're gonna do is build a page, and then once we get that page built, and we're reading MDX, we're also gonna write a React component and kinda play with what MDX is capable of. So to start, we're gonna stop our server if we haven't already, and we're going to install some dependencies.

[00:00:40] So we need to get gatsby mdx not at symbol just gatsby-mdx. And then we also need mdx-js/mdx and mdx-js/react. So these are the pieces that we're gonna need to install to get MDX up and running. So let's go ahead and do that.
>> Jason Lengstorf: And then,
>> Jason Lengstorf: We're going to get into our Gatsby config, and we need to configure gatsby-mdx.

[00:01:20] And to do that, I'm gonna add in,
>> Jason Lengstorf: Another component. And so up till now, we've been including all of our plugins by just name because none of them need any configuration. Gatsby-mdx requires a little bit of configuration, cuz we gotta tell it what's going on. So what we're gonna do is we're going to say we're resolving gatsby-mdx and this is a shortcut for this.

[00:01:47] Resolve gatsby-mdx and just typing out the name of the plugin are functionally equivalent. The reason that we're doing the resolve here is because we also want to pass in options, and that's gonna be an object. And the option that we want to pass is what layout do we wanna use in our MDX files.

[00:02:07] We wanna be able to use this header and shared footer. So I'm going to set up a default,
>> Jason Lengstorf: Layouts option. And I want the default one to be, we're gonna use require resolve so that we get the path name, the absolute path name. And we're gonna get source, components and layout.

[00:02:35] And so this is going to give us any MDX files that we load will be loaded into the layout template for us. So we don't have to set that up or deal with it.
>> Jason Lengstorf: Then, we're going to just create an MDX file. So in pages, I'm gonna create a new file and let's make this a contact page.

[00:02:59] And instead of a JS, I'm gonna call it contact.mdx.
>> Jason Lengstorf: And then inside of it let's just tell people how to contact us. So let's say, let's see you can get in touch with me,
>> Jason Lengstorf: By opening the nearest window and yelling out of it,
>> Jason Lengstorf: Real loud.

>> Jason Lengstorf: Let me turn on text wrapping so that you can see.
>> Jason Lengstorf: And I'm gonna save this.
>> Jason Lengstorf: And so then,
>> Jason Lengstorf: I'm gonna run develop, and assuming I didn't typo anything, it's just gonna boot up, okay? And now, I should be able to visit a contact page, there we go.

[00:03:56] So now that we've installed the plugin, the plugin is looking for MDX files in the pages directory. And anything that we add there is just gonna work. And one immediate advantage here is that there's no ceremony here. If we want to add a heading and a paragraph tag,

>> Jason Lengstorf: There's a lot of extra setup in a React component that just goes away in here. But what if we wanna add some kind of interactivity? That's the whole reason of using MDX is because we wanna do something. So I want to create a way for people to wave.

[00:04:36] So I want somebody to be able to wave at me from my home page. So let's build a component to do that. So let's go up into our components. We're gonna create a new file, and we're gonna call this wave.js. And this one is gonna be a React component, we're gonna use a little bit of state.

[00:04:54] So we're gonna use the use state hook, and react. We wanna be able to style this up a bit, so let's do the css prop from emotion core. And then I'm gonna call this component wave. It's not gonna take any props.
>> Jason Lengstorf: And then down here, I'm going to export default wave.

>> Jason Lengstorf: So inside of this component, we wanna do, basically, the goal of this component is I want somebody to be able to click a button and it will tell them that they waved, and I wanna know how many times they wave. So we wanna keep track of how many waves have happened, cuz really what I'm looking for is I want people to be yelling out the nearest window and doing this, right?

[00:05:40] So that's what we're going for. So let's, let's set this up we're gonna do waves and set waves. And that's going to equal use state, and by default they have a wave, so the number is 0.
>> Jason Lengstorf: And then we're also gonna set up some labeling here. So I wanna be aware of whether or not we need a plural version of waves.

[00:06:07] So let's set up a label, and that is going to be template train, and we'll use the wave emoji. We did use emoji actually
>> Jason Lengstorf: So you've got the wave emoji, and then I'm going to set in the waves.
>> Jason Lengstorf: And then depending on whether or not waves equals 1.

[00:06:34] I'm going to either say wave or waves.
>> Jason Lengstorf: And that's my label component. So now that we've got that, I can just send back a button.
>> Jason Lengstorf: My button is going to hold the label.
>> Jason Lengstorf: And then I'm gonna set two props on this. The first one is gonna be some styles.

>> Jason Lengstorf: And the styles that I wanna send our, let's just make this noticeable. So our background is gonna be rebeccaPurple. And our border is none, so that we get rid of the defaults borders that happen. We'll make the color white so we have enough contrast with the text.

[00:07:24] And lets make the text just a little bit bigger so we'll do 1.2rem. And the next prop that we need is gonna be a click handler. So once somebody clicks this button, what happens? So let's set an onClick and we will tell it to set the waves, 2 waves plus 1.

>> Jason Lengstorf: Okay, so this is our component. It is set up to track the number of clicks and tell us how many times somebody has waved. So to use this we can just go back into our MDX component. And I'm going to add a new section for this. Let's have an H2 say or you can wave to me, just click this button to simulate a friendly wave.

[00:08:20] And then we need to figure out how to click the button in and then let's add a little disclaimer. So please note that I may not wave back. This is because I am very far away. And probably didn't see you click this button. So how do we get our wave component in here?

[00:08:44] Really what we want, is we wanna be able to just type wave. And really that's all we have to do. We just have to import it at the top. So we can import wave from,
>> Jason Lengstorf: Components/wave.
>> Jason Lengstorf: And we don't need the extension, we can just use that.

[00:09:04] So now, when I save this,
>> Jason Lengstorf: It's gonna hot reload. We can see our button in here, and if I click it, it's gonna say how many times I've waved.
>> Jason Lengstorf: And that's the power of MDX is there's no wackiness involved, it's just writing some mark down. And then if you wanna use React, you just write some React.

[00:09:33] And what's really powerful about this too is let's say I wanted to do something custom. I'll do, let's say, a div and we'll do a style. And set the background to,
>> Jason Lengstorf: Red or something. And then I wanna add some content in here, if I write like regular mark down,

>> Jason Lengstorf: It still reads that as mark down inside of the JSX. Now, importantly, you have to leave that extra space, cuz otherwise it won't parse it. So you do need to have a full line break to get that JSX to keep the markdown parts inside. But,
>> Jason Lengstorf: There we go, now it's working.

[00:10:27] I think I had a stray space in there. So basically this is something that's really flexible, where you can do a combination of markdown and React. This is really useful, for example if you wanna use like images where you can use the markdown syntax for displaying the image, but you can wrap it in a React component.

[00:10:45] That will add a figure caption or additional, maybe you wanted to add a gallery where you can show thumbnails and click them to show the full size version. There's a lot of flexibility here.
>> Jason Lengstorf: So that's great for a contact page. But what if we wanna use this for something else?

[00:11:05] What if we want to write our blog in MDX? And that's what we're gonna do in the next section. So at this point you would be checking out, let's see, we just finished, step three MDX. And we're gonna start moving into step four which is the the MDX blog.