MDX Documentation Example

MDX allows you to use JSX components directly in Markdown. Write interactive docs with live examples, custom components, and rich formatting.

What is MDX?

MDX is a format that combines Markdown and JSX. It allows you to import and use React components directly in your markdown content, making it perfect for interactive documentation.

Key Features

  • Write in Markdown syntax
  • Import and use React components
  • Create interactive examples
  • Syntax highlighting for code blocks
  • Fully typed with TypeScript

Using Components in MDX

You can import and use any React component directly in MDX:

Example Card Component
This card is rendered using the Card component from our UI library.

MDX makes it easy to embed interactive components within your documentation.

Code Example

Here's how the card above was created:

<Card>
  <CardHeader>
    <CardTitle>Example Card Component</CardTitle>
    <CardDescription>
      This card is rendered using the Card component
    </CardDescription>
  </CardHeader>
  <CardContent>
    <p>MDX makes it easy to embed components!</p>
  </CardContent>
</Card>

Interactive Demos

Create live, interactive examples with full functionality:

Interactive Button Demo

Click the button to see it in action

Alerts and Callouts

Use custom components to create rich callouts:

Tabs for Multi-part Content

Getting Started

MDX combines the simplicity of Markdown with the power of React components. Perfect for documentation, blogs, and content-rich websites.

Inline Components

You can also use inline components like NEW or BREAKING directly within text.

Try combining multiple components:

Code Blocks with Syntax Highlighting

MDX supports code blocks with syntax highlighting:

TypeScript Example

import type { MDXComponents } from 'mdx/types';

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    h1: ({ children }) => (
      <h1 className="text-3xl font-bold">{children}</h1>
    ),
    ...components,
  };
}

React Component Example

// React Component Example
export default function MyComponent() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </button>
  );
}

CSS Example

/* CSS Example */
.custom-class {
  display: flex;
  align-items: center;
  gap: 1rem;
  padding: 1rem;
  border-radius: 0.5rem;
  background: hsl(var(--primary));
}

Tables

FeatureMarkdownMDXHTML
Easy to write✅✅❌
Components❌✅✅
Interactive❌✅✅
Type-safe❌✅❌

Lists

Unordered List

  • First item
  • Second item with bold text
  • Third item with code
  • Nested item 1
  • Nested item 2
  • Fourth item with a link

Ordered List

  1. Step one: Install dependencies
  2. Step two: Configure the project
  3. Step three: Start building
  4. Step four: Deploy to production

Blockquotes

This is a blockquote. Use it to emphasize important information or quotes.

You can have multiple paragraphs in a blockquote.

Note: MDX supports all standard Markdown syntax including bold, italic, bold italic, inline code, and links.

Advantages of MDX

Developer Experience
Write content in familiar Markdown syntax while having access to the full power of React components when needed.
Interactive Docs
Create living documentation with working examples, interactive demos, and real component previews.
Type Safety
Full TypeScript support ensures your components and props are correctly used throughout your documentation.
Maintainable
Update your component library and the documentation automatically reflects the changes. No duplicate code!

Conclusion

MDX is a powerful tool for creating interactive documentation. It combines the simplicity of Markdown with the flexibility of React components, making it perfect for:

  • Documentation sites - Create living docs with working examples
  • Blog posts - Add interactive elements to enhance your content
  • Tutorial content - Build step-by-step guides with embedded demos
  • Component showcases - Display components with live previews

Ready to start? Check out the official MDX documentation for more information!

Learn MoreView on GitHub