Laurie Barth walks us through MDX v2's syntax by trying to break it. She starts at markdown syntax and takes us through increasingly complex applications of MDX, including passing dynamic props to .mdx files imported into other .mdx files.

MDX v2 Syntax

Laurie Barth: [0:01] Hi, everyone. I am Laurie Barth, a maintainer for MDX. I'm here to play around with MDX v2. It should be coming to soon, complete with a brand-new parser under the hood and a couple really nice new features.

[0:15] Today, I am going to work with a super barebone's Gatsby site to try and break MDX. I'm going to try a ton of different of things, some things you've probably seen before, maybe a handful of things you haven't, and see what power lies in this really, really awesome language.

[0:36] I have an MDX file open right now. The only thing in this Gatsby site is gatsby-plugin-mdx and I've installed a couple of other packages for imports I want to use later. Other than that, nothing fancy, no magic.

[0:52] The first thing we know about MDX is that it's based on markdown and you can use markdown syntax in it. That means Some header should work. So far, so good. Some text. OK. How about bullet points, or alt link? Of course, I wrote in image. That's good. [alt link text for google] (www.google.com). I should have made this mdxjs.com.

[1:43] Everything that we would expect to work in markdown, so far, so good.

[1:48] How about some JSX? This is going to get a little more complicated. Let me just make the screen slightly bigger for a second. Let's try in h2. Cool. Now some styles. Maybe some padding, 10px and 30px. In honor of John Otander, background color has to be tomato, just has to be. JSX works. That's good.

[2:39] What about code snippets? A lot of us have blogs. Maybe if I write that I'm breaking things, it'll actually break things. Nope. Still seems to work, and it's got that nice little different text font for code fences.

[3:08] Sometimes I write docs and I want to show people how to write MDX. This is a little known trick. If you put four backticks, and then I'll just copy and paste this for ease. Then include the example. It shows you the MDX itself. Still working. Why did they make this parser so good?

[3:33] What if I put invalid stuff? Let's say in my style, I do exactly what I did before, except maybe a little bit simpler. Purple. This should break. I genuinely believe this. Yes! Invalid JSX will break. That seems expected and what I would want, to be perfectly honest. It won't default to text.

[4:19] I tried this the other day, and I'm pretty sure this breaks, too. Let's just put some function with the div inside of it. Text, maybe? That breaks, too. That's probably a weird edge case that we wouldn't really want.

[4:42] To be perfectly honest, I've already told them this is broken and we're going to fix it. It should show up as text or attempt to show up as code. That's what it did in the previous version. If we put code fences around it, we're still fine.

[4:55] So far, this is all in one file, which seems admittedly kind of boring. Let's try and import some stuff. I'll start with something that already existed from an external source. There are headings in rebase, which I downloaded ahead of time. If I want to use it, external component, it works.

[5:34] How about I make a local component? It's a pretty common use case. Example.js. We're going to need to import React. How many times a day do you write from as form? For me, it's quite a bit.

[5:52] Function. We'll call it just a div, because that's exactly what it's going to be. We'll return a div with text, just the word text. If we come over here, we can import it. That's saying components/example. This breaks. This is known to break. We've got to leave some space for our imports. Even our linting VS Code extension knows that that won't be valid. That's cool.

[6:30] We'll add example at the end. The import seems to work. What about if we reference it? We have text. It's a component. Can I pass text to it? "Whatever Laurie says." I'm very inventive with my text here. Whatever Laurie says, seems to work.

[7:04] External imports work. Internal imports work. We can pass data to them. How about including other MDX? another-file.mdx. "Whatever we want to type." Then we import AnotherFile from "./another-file.mdx". All the way at the bottom, we'll include AnotherFile as if it were a component. It's an MDX component. That works.

[7:51] If it's a component, can I pass it information? I should be able to. Let's say the name of this is MDX. I want there to be a header in here. That's props.name. That's what I called it, name. That's pretty cool. Let's try passing it other stuff. Can I pass it? I don't know. Some Boolean value maybe? isTrue={true}. What do I get? What happens, nothing? Interesting.

[8:58] What if I make it "true"? Now it shows up. All right. That seems somewhat reasonable. It's just a Boolean. It doesn't render as anything.

[9:15] What else can I do? What about going the other way? This is one of those things nobody ever uses but is admittedly pretty cool. You can export information from within the file to use in its parent. Export data. We'll call it {fun}. We'll say, "This is fun." Up here, when I import another file, I also have to import data. Then down here, data.fun. We'll just display it. This is fun.

[9:55] I feel like there should be a div here. Give nice space. Will all of this still work? I've broken a couple of things, but this works in a bunch of different directions. It's basically completely componentized at this point. I can pass props. I can listen to things from my children. The worst situation was I kept giving it invalid stuff and it broke, and that seems reasonable.

[10:31] It's marked down. It's JSX. It's honestly incredibly powerful. MDX has always been cool, but I am really excited for v2. This is cool stuff.

[10:45] I hope you had fun watching this. I now want to try a bunch of other things. Let me know what you think. I'll be around.

MDX v2 Syntax

Share this video with your friends