In the world of web development, documentation is king. Good docs can make or break a library, framework, or API. For years, Markdown has been the undisputed champion for writing this content—it's simple, clean, and universally understood. But as our applications have become more interactive and component-driven, Markdown has started to show its age.
Static text, images, and code blocks are no longer enough. We need documentation that lives and breathes, that showcases interactive examples, and that uses the very same components our applications are built with.
This is where MDX comes in. It’s a game-changer for content, and a new service, mdx.do, makes it easier than ever to use, even in the most dynamic environments.
Markdown is fantastic for what it was designed for: structuring static text. But have you ever tried to:
With traditional Markdown, these tasks are impossible or require clunky HTML hacks and dangerouslySetInnerHTML. You lose the elegance of Markdown and the safety of modern frameworks. Your content becomes decoupled from your application's design system.
MDX is a superset of Markdown that lets you write JSX directly inside your content. It seamlessly blends the simplicity of Markdown with the power of React components.
CONTENT AS CODE
Imagine writing content like this:
# Our Design System
Here is our primary button component in action. Go ahead, click it!
<Button onClick={() => alert('Clicked!')}>Click Me</Button>
And here's a chart displaying last month's usage:
<LineChart data={...} />
With MDX, your content is no longer just static text; it's a living, breathing part of your application. You can import and render any React component, pass props, and even handle state directly within your documentation or blog posts. This is the essence of component-driven content: building rich experiences with reusable, interactive blocks.
While frameworks like Next.js and Gatsby have excellent support for MDX, they typically rely on a build step. Your .mdx files must be present locally when you compile your site.
But what if your content isn't in your Git repository? What if it's pulled from a:
This is where the traditional MDX workflow breaks down. You can't run a build process every time a piece of content is updated in your CMS. You need a way to compile MDX on the fly.
mdx.do is a simple yet powerful API designed to solve this exact problem. It allows you to dynamically compile MDX to React in real-time, completely decoupling your content from your build process.
Here’s how it works: You send a string of MDX content to the mdx.do API, and it returns compiled, executable JavaScript code that you can safely evaluate and render in your React app.
Let's see it in action.
import { mdx } from ".do";
const mdxContent = `
# Hello, MDX!
This is a JSX component rendered from a string:
<MyCustomComponent title="Welcome" />
And you can use expressions: {2024 - 1984} years have passed.
`;
// 1. Send the MDX string to the mdx.do API
const { code, frontmatter } = await mdx.compile(mdxContent);
// 2. The returned 'code' can now be safely evaluated
// and rendered in your React application.
With this approach, your MDX content can come from anywhere.
The web is moving towards more modular, dynamic, and interactive experiences. Our content shouldn't be left behind in a static past.
MDX provides the bridge between content and components. Services like mdx.do make this powerful technology accessible for any architecture, freeing your content from the constraints of build steps and enabling truly dynamic, Markdown JSX experiences.
Ready to supercharge your content? Stop writing boring documentation and start building interactive experiences.
Visit mdx.do to learn more and start compiling MDX on the fly!