MDX is undeniably powerful. It gives developers an excess of flexibility and efficiency in authoring content. But it has enough challenges that suggest we may be ready for something better.
MDX is a very cool and useful piece of technology. But it's also not without its challenges.
Let's take a look at both the benefits and challenges of MDX. Then we'll dive into scenarios in which I'd use MDX today, along with alternatives for projects where MDX may not be a good fit.
One of the most valuable things MDX gave us was a conversation. The fact that I'm writing this post and thinking about the next generation of web content is, in large part, because MDX popularized a particular type of content editing.
MDX was the manifestation of several technologies that can be synthesized into a simple idea: markdown isn't enough.
If I consider foundational changes with markdown since it was released by John Gruber and Aaron Swartz in 2004, four pivotal moments come to mind:
When looking at the history of markdown, MDX is one of the most powerful unlocks of its usage in the last two decades.
MDX led to the ability for developers to create rich and interactive content at speeds they had never known before.
To be able to work with interactive components (backed by a component framework) among plain text content was a truly powerful idea. Anyone who has worked on a project with interactive components and MDX files as the content source has certainly felt this.
Part of the reason MDX is so fast to author is because of its flexibility. If I need to move a component around, I just move the (plain text) content around and it works. I don't have to worry about structure. I'm working with an open markdown file, so my bounds seem limitless.
I'm no expert with abstract syntax trees or unist, but I love that it's taking plain text content and turning it into structured content. It's a powerful concept, because it's providing structure to something that is flexible.
The best we could get with Markdown was to build structured content using YAML frontmatter. That is gross (to edit manually).
The innovation and the power of MDX are absolutely impossible to deny. It's been an incredible step forward. And now we're ready for the next step.
First off, let's step back before Markdown to understand why Markdown exists, which comes from the first sentence on the v1.0.1 Markdown project page:
Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
Markdown was built to get us away from authoring content in HTML, which is actually the worst. MDX has taken us right back into it. If you look at almost any MDX file, you will immediately feel like it's more HTML than Markdown.
You might say that if you can be disciplined about your components and have sensible global defaults, you can minimize the "markup" (JSX code, or the X in MDX) needed to make an MDX file more legible.
I would agree. 100%.
The challenge is discipline on that level is extremely difficult to accomplish, precisely because it goes against why MDX is so great — because it's flexible. Developers can create rich content quickly. And what happens when developers move fast?
Things get messy.
Part of this challenge is because MDX gets parsed on the server, which produces code that can be run on a client. (It's technically a bit more complicated than that.) Because of this, I can't build a component that renders other MDX files, which is a fairly basic feature of content being processed on the server.
That means that if I want to share content in an MDX project, I either have to put the content in components (very bad) or build some other mechanism to manage shared content (worse).
Even though there is an AST, it's very difficult to see and parse that structure.
This makes transferring the content to a new source extremely difficult when compared to other solutions. I would argue that it's definitely easier than having a ton of Mustache or Nunjucks components. But it's definitely not easier than plain makrdown or structured frontmatter.
You don't need to be weighed down by obsessing on the next step of your site. But if you're building a site and hoping to outgrow it someday, it is at least worth considering the debt you're incurring when writing in a syntax from which it is difficult to escape.
Given my conflicted feelings on MDX, I do still work with it regularly today.
If you aren't already working with it, I recommend MDX as a legitimately great solution when all of the following conditions are met:
If you're considering using MDX, I'd also encourage you to consider the following:
Like many tools, MDX suits a greay many projects perfectly well, while it isn't a great fit for other projects. Regardless, it is difficult to deny that MDX has moved the content editing experience for developers forward.
Choose what's right for you today, but understand the debt that you may be digging for yourself. And let's use this conversation to work toward the next generation of content editing for developers.
Bear is one of the best editors out there, but lacks workflows for your content. Here's how to programmatically write Bear notes to local markdown files.
A quick tip for making ordered lists in markdown easier to write.
Make a bulk conversion of markdown images to HTML strings using a regex find and replace with VS Code.