1. Introduction to MDX and React Components
Markdown is popular due to its clean syntax. MDX extends Markdown to support more content and layouts. The MDX Loader transforms Markdown files into React components. The MDX provider allows us to override default components and customize the rendering. The wrapper component provides access to the content of the Markdown file as React elements. We can extract information or modify elements using the MDX type.
2. MDX and Steps
In MDX, we can extract data from children and render it in a specific way. If performance is a concern, we can move the extraction to a build-time plugin. MDX allows us to introduce our own syntax for looping things in steps. The Step Component is used for grouping elements. MDX is a syntax extension for Markdown, often used for embedding interactive components.
In all of them, first we extract some data from the children and then we 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.
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 looping things in steps, but we can use MDX to extend Markdown and introduce our syntax.
The 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, but here we are taking a different approach and using it more as a syntax extension for Markdown.
3. MDX File Steps and Layouts
Now, based on the MDX file that has steps, we can write another wrapper component. In this case, we get one React element for each step, so we can keep track of the current step and let the user change it with a button. Let's implement a scroll-italing layout where some parts stick to the screen while the rest scrolls away. We can add sticker content to the MDX file and use a layout component to show the corresponding sticker when the user scrolls to a new step. We can also synchronize steps with media like a video or audio using the TalkLayout component.
Now, based on the MDX file that has steps, we can write another wrapper component. In this case, in the children prob, 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.
Now, I want to show the same content, but with a different layout. There's a technique called scroll-italing. You might have seen it on some websites. As the user scrolls down, there's some part of the layout that sticks to the screen, while the rest scrolls away. So, let's do that. Since this is a lightning talk, I'll import the scroll-italing-layout component. I shared the link to the repo later, if you want to see how it works. The scroll-italing-layout component takes two props, one for the left side that can be scrolled and the other for the sticky part on the right. 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 this sticky part of the layout. There isn't any specific syntax for this so we need to create our own convention. Like 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 to the same layout component. So when the user scrolls the code on the right should change accordingly. 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. To do that in the mdx file we need to specify the media 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 on the wrapper and pass it to another React component. This time it's the TalkLayout component that will solve all the syncing for us. And 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. And it is. This talk was built using the same technique. It's all MDX. For example, here on the left you can see the code for the steps you are currently watching. And here is the next step.
4. Key Takeaways and Codehike
You can use MDX to build your own dialect for any layout. Links to the talk's repo are provided. Run Yarn dev to watch the talk again. Check out my Twitter and the components from Codehike, a project focused on code wall tools and explaining code.
And that's all I have. The takeaways. You can use MDX to build your own dialect tailored for any specific layout.
I leave you here the links to the repo of the talk. Not the slide, but the talk itself. You run Yarn dev and you can watch this talk again.
And there's my Twitter and the components we used. Most of them come from a new project I'm working on. It's called Codehike. And it focuses on code wall tools. And tools for making it easy to explain code.