The X in MDX

Rodrigo Pombo: [0:01] Let's start with this Markdown file. I'm assuming we all know Markdown. The reason why it's so popular, it has a very clean syntax. I'm sure I'm not the only one who likes to move as much content as possible to Markdown, even content that doesn't originally belong to Markdown.

[0:20] That's why we have MDX. We had to extend the original format so we could put more things on it. In this talk, we'll take this to the extreme. We'll use MDX for more unusual content and layouts, but first, I need to show you how this works.

[0:42] We're going to start with this small React app. This is using Next.js, but the same applies to any app that has the MDX loader. Most of the magic comes from this import. Here, the MDX loader transform the Markdown File into a React component that we can use anywhere. You can see it renders what to expect here on the right.

[1:11] If we want to change what's rendered, we can use the MDXProvider component. It has a component prop that let us override any of the default components. For example, here we are changing all the h1s, and adding a purple border.

[1:32] A special component we can override is the wrapper. The wrapper is the component that wraps content. Here, we are just adding a border to it. The cool thing about this component is that in the children prop, we get all the content from the Markdown file as React elements. React elements are just JavaScript options.

[2:01] Here, you can see what's inside the children prop. We are rendering the wrapper children as JSON, and we're doing some properties to make it easier to read. You'll see that it is an array, the first element is an h1, the second a paragraph.

[2:22] Each element comes with an mdxType. We can and we will use that mdxType to extract information about the content or to change the elements. For example, we could get a list of all the H1s from the children, and render it as a table of content.

[2:43] This is a simple example, but it illustrates the pattern we are going to use on the rest of the examples. In all of them, first, we extract some data from the children, and then we'll render it in a specific way. Keep in mind that this runs on every render. In most cases, it isn't a performance problem, but if it is, you can move it to a plugin and run the transformation on build-time.

[3:12] I usually write content that has steps like tutorials or any type of walkthrough, where you explain something step-by-step. Markdown doesn't have any specific syntax for grouping things in steps, but we can use MDX to extend Markdown and introduce our syntax.

[3:35] Implementation of the Step component we are using here doesn't matter, we are just using it for grouping elements. If you are new to MDX, this may not be the best introduction. The typical use case for MDX is embedding interactive components in Markdown. Here, we are taking a different approach and using it more as a syntax extension for Markdown.

[4:00] Now, based on the MDX file that has steps, we can write another wrapper component. In this case, in the children prop, we get one React element for each step so we can keep track of what step we are showing using React state, and let the user change the current step with a button.

[4:24] Now, I want to show the same content but with a different layout. There's a technique called scrollytelling. You may have seen it on some websites. As the user scrolls down, there are some parts of the layout that sticks to the screen while the rest is scrolled away. Let's do that.

[4:47] Since this is a lightning talk, I'll import the ScrollytellingLayout component. I'll share the link to the repo later, if you want to see how it works. The ScrollytellingLayout component takes two props -- one for the left-side that can be scrolled, and the other for the sticky part on the right.

[5:10] When the user scrolls to a new step, we show the corresponding element from the sticker list. Now, instead of showing the step number, let's add the sticker content to the MDX file. Suppose we want to show some code in the sticky part of the layout, there isn't any specific syntax for this, so we need to create our own convention.

[5:44] For example, we put the sticky part of the step as the first element. Now, doing some array transformation, we get the list of steps and the list of stickers and pass them through the same layout component. When the user scrolls, the code on the right should change accordingly.

[6:08] Just for fun, I have a Terminal component that animates between code transitions, so we can use it for the stickers. I've been experimenting with another layout for walkthroughs. Instead of changing the steps using the scroll like in this example, we can synchronize these steps with some media like a video or an audio, maybe a podcast, and change the steps as the media progress.

[6:50] To do that, in the MDX file, we need to specify the media file and the time range for each step. Once we have that, we can extract the information from the children of the wrapper and pass it to another React component.

[7:08] This time is the TalkLayout component that will solve all the synching for us. You should see the steps changing every time I snap the fingers. Some of you might have noticed that this looks similar to the layout of this talk that I'm giving right now. This talk was built using this same technique. It's all MDX.

[7:42] For example, here on the left, you can see the code for the steps you're currently watching, and here is the next step. That's all I have. The takeaways you can use MDX to build your own dialect tailored for any specific layer. I leave you here the links to the repo of the talk, not the slides, but the talk itself. You'll run yarn dev, and you can watch this talk again.

[8:16] Also, there's my Twitter and the components we used. Most of them come from a new project I'm working on, it's called Code Hike. It focuses on code walkthroughs and tools for making it easy to explain code. Thank you.