The X in MDX

Rate this content

Markdown is great for content-driven sites. MDX is even better, letting you embed interactive components directly from your markup. It's usually used for the same linear layouts you often see on many blogs, readmes, and documentation sites. But it doesn't need to be like this.

In this talk, we'll see how to reshape MDX so we can use it for very different layouts, things like scrollytelling, slide decks, and more.

9 min
17 Jun, 2021

Video Summary and Transcription

Markdown is extended by MDX to support more content and layouts. MDX allows for customization of rendering and extraction of data. It is often used for embedding interactive components. MDX can be used to create custom layouts and synchronize steps with media. Codehike is a project focused on code wall tools and explaining code.

Available in Español

1. Introduction to MDX and React Components

Short description:

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.

Let's start with this Markdown file. I'm assuming we all know Markdown. There's a 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. And that's why we have MDX, right? We have 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. We're going to start with this small React app. This is using XJS. But the same applies to any app that has the MDX Loader. Most of the magic comes from this import. Here, the MDX Loader transformed the markdown file into a React component that we can use anywhere. And you can see it renders what you expect here on the right. If we want to change what's rendered, we can use the MDX provider component. It has a components probe that let us override any of the default components. For example, here we are changing all the h1's, and adding a purple border. A special component we can override is the wrapper. The wrapper is the component that wraps the content. Here, we are just adding a border to it, but the cool thing about this component is that in the children probe, we get all the content from the markdown file as react elements. And react are JavaScript options. So, here you can see what's inside the children probe. We are rendering the wrapper children as JSON and filtering some properties to make it easier to read. You will see that it is an array. The first element is an H1, the second a paragraph. Each element comes with an MDX type. We can and will use that MDX type to extract information about the content or to change the element. For example, we could get a list of all the H1s from the children and render it as a table of contents. This is a simple example, but it illustrates the pattern we are going to use on the rest of the examples.

2. MDX and Steps

Short description:

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

Short description:

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

Short description:

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.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

React Advanced Conference 2022React Advanced Conference 2022
25 min
A Guide to React Rendering Behavior
Top Content
React is a library for "rendering" UI from components, but many users find themselves confused about how React rendering actually works. What do terms like "rendering", "reconciliation", "Fibers", and "committing" actually mean? When do renders happen? How does Context affect rendering, and how do libraries like Redux cause updates? In this talk, we'll clear up the confusion and provide a solid foundation for understanding when, why, and how React renders. We'll look at: - What "rendering" actually is - How React queues renders and the standard rendering behavior - How keys and component types are used in rendering - Techniques for optimizing render performance - How context usage affects rendering behavior| - How external libraries tie into React rendering
React Summit Remote Edition 2021React Summit Remote Edition 2021
33 min
Building Better Websites with Remix
Top Content
Remix is a new web framework from the creators of React Router that helps you build better, faster websites through a solid understanding of web fundamentals. Remix takes care of the heavy lifting like server rendering, code splitting, prefetching, and navigation and leaves you with the fun part: building something awesome!
React Advanced Conference 2023React Advanced Conference 2023
33 min
React Compiler - Understanding Idiomatic React (React Forget)
React provides a contract to developers- uphold certain rules, and React can efficiently and correctly update the UI. In this talk we'll explore these rules in depth, understanding the reasoning behind them and how they unlock new directions such as automatic memoization. 
React Advanced Conference 2022React Advanced Conference 2022
30 min
Using useEffect Effectively
Top Content
Can useEffect affect your codebase negatively? From fetching data to fighting with imperative APIs, side effects are one of the biggest sources of frustration in web app development. And let’s be honest, putting everything in useEffect hooks doesn’t help much. In this talk, we'll demystify the useEffect hook and get a better understanding of when (and when not) to use it, as well as discover how declarative effects can make effect management more maintainable in even the most complex React apps.
React Summit 2022React Summit 2022
20 min
Routing in React 18 and Beyond
Top Content
Concurrent React and Server Components are changing the way we think about routing, rendering, and fetching in web applications. Next.js recently shared part of its vision to help developers adopt these new React features and take advantage of the benefits they unlock.In this talk, we’ll explore the past, present and future of routing in front-end applications and discuss how new features in React and Next.js can help us architect more performant and feature-rich applications.
React Advanced Conference 2021React Advanced Conference 2021
27 min
(Easier) Interactive Data Visualization in React
Top Content
If you’re building a dashboard, analytics platform, or any web app where you need to give your users insight into their data, you need beautiful, custom, interactive data visualizations in your React app. But building visualizations hand with a low-level library like D3 can be a huge headache, involving lots of wheel-reinventing. In this talk, we’ll see how data viz development can get so much easier thanks to tools like Plot, a high-level dataviz library for quick & easy charting, and Observable, a reactive dataviz prototyping environment, both from the creator of D3. Through live coding examples we’ll explore how React refs let us delegate DOM manipulation for our data visualizations, and how Observable’s embedding functionality lets us easily repurpose community-built visualizations for our own data & use cases. By the end of this talk we’ll know how to get a beautiful, customized, interactive data visualization into our apps with a fraction of the time & effort!

Workshops on related topic

React Summit 2023React Summit 2023
170 min
React Performance Debugging Masterclass
Featured WorkshopFree
Ivan’s first attempts at performance debugging were chaotic. He would see a slow interaction, try a random optimization, see that it didn't help, and keep trying other optimizations until he found the right one (or gave up).
Back then, Ivan didn’t know how to use performance devtools well. He would do a recording in Chrome DevTools or React Profiler, poke around it, try clicking random things, and then close it in frustration a few minutes later. Now, Ivan knows exactly where and what to look for. And in this workshop, Ivan will teach you that too.
Here’s how this is going to work. We’ll take a slow app → debug it (using tools like Chrome DevTools, React Profiler, and why-did-you-render) → pinpoint the bottleneck → and then repeat, several times more. We won’t talk about the solutions (in 90% of the cases, it’s just the ol’ regular useMemo() or memo()). But we’ll talk about everything that comes before – and learn how to analyze any React performance problem, step by step.
(Note: This workshop is best suited for engineers who are already familiar with how useMemo() and memo() work – but want to get better at using the performance tools around React. Also, we’ll be covering interaction performance, not load speed, so you won’t hear a word about Lighthouse 🤐)
React Advanced Conference 2021React Advanced Conference 2021
132 min
Concurrent Rendering Adventures in React 18
Top Content
Featured WorkshopFree
With the release of React 18 we finally get the long awaited concurrent rendering. But how is that going to affect your application? What are the benefits of concurrent rendering in React? What do you need to do to switch to concurrent rendering when you upgrade to React 18? And what if you don’t want or can’t use concurrent rendering yet?

There are some behavior changes you need to be aware of! In this workshop we will cover all of those subjects and more.

Join me with your laptop in this interactive workshop. You will see how easy it is to switch to concurrent rendering in your React application. You will learn all about concurrent rendering, SuspenseList, the startTransition API and more.
React Summit Remote Edition 2021React Summit Remote Edition 2021
177 min
React Hooks Tips Only the Pros Know
Top Content
Featured Workshop
The addition of the hooks API to React was quite a major change. Before hooks most components had to be class based. Now, with hooks, these are often much simpler functional components. Hooks can be really simple to use. Almost deceptively simple. Because there are still plenty of ways you can mess up with hooks. And it often turns out there are many ways where you can improve your components a better understanding of how each React hook can be used.You will learn all about the pros and cons of the various hooks. You will learn when to use useState() versus useReducer(). We will look at using useContext() efficiently. You will see when to use useLayoutEffect() and when useEffect() is better.
React Advanced Conference 2021React Advanced Conference 2021
174 min
React, TypeScript, and TDD
Top Content
Featured WorkshopFree
ReactJS is wildly popular and thus wildly supported. TypeScript is increasingly popular, and thus increasingly supported.

The two together? Not as much. Given that they both change quickly, it's hard to find accurate learning materials.

React+TypeScript, with JetBrains IDEs? That three-part combination is the topic of this series. We'll show a little about a lot. Meaning, the key steps to getting productive, in the IDE, for React projects using TypeScript. Along the way we'll show test-driven development and emphasize tips-and-tricks in the IDE.
React Advanced Conference 2021React Advanced Conference 2021
145 min
Web3 Workshop - Building Your First Dapp
Top Content
Featured WorkshopFree
In this workshop, you'll learn how to build your first full stack dapp on the Ethereum blockchain, reading and writing data to the network, and connecting a front end application to the contract you've deployed. By the end of the workshop, you'll understand how to set up a full stack development environment, run a local node, and interact with any smart contract using React, HardHat, and Ethers.js.
React Summit 2023React Summit 2023
151 min
Designing Effective Tests With React Testing Library
Featured Workshop
React Testing Library is a great framework for React component tests because there are a lot of questions it answers for you, so you don’t need to worry about those questions. But that doesn’t mean testing is easy. There are still a lot of questions you have to figure out for yourself: How many component tests should you write vs end-to-end tests or lower-level unit tests? How can you test a certain line of code that is tricky to test? And what in the world are you supposed to do about that persistent act() warning?
In this three-hour workshop we’ll introduce React Testing Library along with a mental model for how to think about designing your component tests. This mental model will help you see how to test each bit of logic, whether or not to mock dependencies, and will help improve the design of your components. You’ll walk away with the tools, techniques, and principles you need to implement low-cost, high-value component tests.
Table of contents- The different kinds of React application tests, and where component tests fit in- A mental model for thinking about the inputs and outputs of the components you test- Options for selecting DOM elements to verify and interact with them- The value of mocks and why they shouldn’t be avoided- The challenges with asynchrony in RTL tests and how to handle them
Prerequisites- Familiarity with building applications with React- Basic experience writing automated tests with Jest or another unit testing framework- You do not need any experience with React Testing Library- Machine setup: Node LTS, Yarn