mdx

Markdown for the component era

17,381

1,138

17,381

View on GitHub View on NPM

Top Related Projects

gatsby

55,199

The best React-based framework with performance, scalability and security built in.

docusaurus

56,173

Easy to maintain open source documentation websites.

astro

46,206

The web framework for content-driven websites. ⭐️ Star to support our work!

vuepress

22,531

📝 Minimalistic Vue-powered static site generator

content

3,105

The file-based CMS for your Nuxt application, powered by Markdown and Vue components.

Quick Overview

MDX is a powerful and flexible format that combines Markdown with JSX, allowing you to seamlessly integrate React components into your Markdown content. It provides a way to write long-form content with interactive and dynamic elements, making it ideal for documentation, blogs, and other content-heavy applications.

Pros

Combines the simplicity of Markdown with the power of React components
Enables the creation of interactive and dynamic content
Supports a wide range of plugins and customizations
Integrates well with various static site generators and React frameworks

Cons

Requires knowledge of both Markdown and JSX/React
Can have a steeper learning curve for non-developers
May introduce complexity in content management for larger projects
Performance can be impacted if overused or not optimized properly

Code Examples

Basic MDX usage:

# Welcome to my MDX file

This is a paragraph with some **bold** text.

<Button onClick={() => alert('Hello!')}>Click me</Button>

Here's a list:
- Item 1
- Item 2
- Item 3

Using imports and custom components:

import { Chart } from './components/Chart'
import data from './data/sales.json'

# Sales Report

Here's a chart of our monthly sales:

<Chart data={data} />

As you can see, our sales have been increasing steadily.

Using MDX expressions:

export const year = new Date().getFullYear()

# Copyright Notice

All content on this site is copyright © {year} by Our Company.

{['React', 'Vue', 'Angular'].map(framework => (
  <li key={framework}>{framework}</li>
))}

Getting Started

To start using MDX in your project:

Install the necessary dependencies:

npm install @mdx-js/react @mdx-js/loader

Configure your bundler (e.g., webpack) to use the MDX loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: [
          'babel-loader',
          '@mdx-js/loader'
        ]
      }
    ]
  }
}

Create an MDX file (e.g., content.mdx) and import it in your React component:

import Content from './content.mdx'

function App() {
  return (
    <div>
      <h1>My App</h1>
      <Content />
    </div>
  )
}

Now you can start writing your content in MDX format and use it in your React application!

Competitor Comparisons

next.js

124,777

The React Framework

Pros of Next.js

Full-featured React framework with built-in routing, server-side rendering, and API routes
Extensive ecosystem and community support
Optimized for performance with automatic code splitting and image optimization

Cons of Next.js

Steeper learning curve for beginners due to its comprehensive feature set
More opinionated structure, which may limit flexibility in some cases
Larger bundle size compared to MDX for simple projects

Code Comparison

Next.js (pages/index.js):

import Head from 'next/head'

export default function Home() {
  return (
    <div>
      <Head><title>My Next.js App</title></Head>
      <h1>Welcome to Next.js!</h1>
    </div>
  )
}

MDX (example.mdx):

import { MyComponent } from './components'

# Welcome to MDX!

<MyComponent />

This is a paragraph with **bold** text.

Key Differences

Next.js is a full-stack React framework, while MDX is focused on combining Markdown with JSX
Next.js provides a complete application structure, whereas MDX is typically integrated into existing projects
MDX excels in content-heavy applications, while Next.js shines in building complex web applications

Use Cases

Choose Next.js for building full-featured web applications with server-side rendering and routing
Opt for MDX when working on content-rich projects that require a mix of Markdown and React components

gatsby

55,199

The best React-based framework with performance, scalability and security built in.

Pros of Gatsby

Full-featured static site generator with a rich ecosystem of plugins and themes
Built-in performance optimizations, including code splitting and image optimization
GraphQL data layer for efficient data management and querying

Cons of Gatsby

Steeper learning curve due to its complex architecture and GraphQL requirement
Slower build times for large sites compared to simpler static site generators
More opinionated structure, which may limit flexibility for some projects

Code Comparison

MDX:

import { MDXProvider } from '@mdx-js/react'
import components from './components'

<MDXProvider components={components}>
  <MDXContent />
</MDXProvider>

Gatsby:

import { Link } from 'gatsby'
import Layout from '../components/layout'

export default function Home() {
  return (
    <Layout>
      <h1>Welcome to my Gatsby site!</h1>
      <Link to="/about/">About</Link>
    </Layout>
  )
}

While MDX focuses on enhancing Markdown with JSX, Gatsby provides a complete framework for building static sites. MDX can be integrated into Gatsby projects, allowing developers to leverage the strengths of both. Gatsby offers more built-in features and optimizations, but MDX provides a simpler, more focused approach to content authoring with React components.

docusaurus

56,173

Easy to maintain open source documentation websites.

Pros of Docusaurus

Full-featured static site generator with built-in themes and plugins
Integrated search functionality and versioning support
Easier setup for complete documentation websites

Cons of Docusaurus

Steeper learning curve due to more complex architecture
Less flexibility for custom layouts and designs
Heavier bundle size compared to MDX-only solutions

Code Comparison

MDX:

import { MDXProvider } from '@mdx-js/react'
import components from './components'

<MDXProvider components={components}>
  <MDXContent />
</MDXProvider>

Docusaurus:

import Layout from '@theme/Layout'
import MDXContent from '@theme/MDXContent'

<Layout>
  <MDXContent />
</Layout>

Summary

MDX is a lightweight solution for adding JSX to Markdown, offering flexibility and ease of integration into existing projects. Docusaurus, on the other hand, is a comprehensive documentation framework built on top of MDX, providing a full suite of features for creating documentation websites.

While MDX allows for more customization and lighter implementation, Docusaurus offers a more opinionated and feature-rich approach to documentation. The choice between the two depends on project requirements, with MDX being ideal for simple integrations and Docusaurus excelling in full-scale documentation site creation.

astro

46,206

The web framework for content-driven websites. ⭐️ Star to support our work!

Pros of Astro

Full-featured static site generator with built-in components and routing
Supports multiple frontend frameworks (React, Vue, Svelte) in the same project
Optimized performance with partial hydration and zero-JS by default

Cons of Astro

Steeper learning curve due to its comprehensive feature set
Less flexibility for integrating with existing build systems
Potentially overkill for simple content-focused websites

Code Comparison

MDX:

import { MDXProvider } from '@mdx-js/react'
import components from './components'

<MDXProvider components={components}>
  <MDXContent />
</MDXProvider>

Astro:

---
import Layout from '../layouts/Layout.astro';
import Card from '../components/Card.astro';
---

<Layout title="Welcome to Astro.">
  <main>
    <Card />
  </main>
</Layout>

Key Differences

MDX focuses on enhancing Markdown with JSX, while Astro is a complete static site generator
Astro has a more opinionated structure and built-in optimizations
MDX is more flexible and can be integrated into various build systems and frameworks

Use Cases

Choose MDX for adding interactive components to Markdown-heavy content
Opt for Astro when building full websites with multiple pages and performance optimization needs

vuepress

22,531

📝 Minimalistic Vue-powered static site generator

Pros of VuePress

Built-in Vue.js integration for dynamic content and components
Out-of-the-box theme system with default theme optimized for documentation
Automatic service worker generation for offline support

Cons of VuePress

Steeper learning curve for developers not familiar with Vue.js
Less flexibility in content structure compared to MDX's component-based approach
Limited to Vue.js ecosystem, while MDX is framework-agnostic

Code Comparison

VuePress:

<template>
  <div class="custom-component">
    {{ message }}
  </div>
</template>

<script>
export default {
  data() {
    return {
      message: 'Hello from VuePress!'
    }
  }
}
</script>

MDX:

import { CustomComponent } from './components'

# My MDX Page

<CustomComponent message="Hello from MDX!" />

Regular markdown content here...

Summary

VuePress excels in creating documentation sites with Vue.js integration, offering a robust theme system and built-in features. MDX provides more flexibility for content creation, allowing seamless integration of JSX components within Markdown. VuePress is ideal for Vue.js developers building documentation, while MDX is better suited for projects requiring a more customizable content structure across different frameworks.

content

3,105

The file-based CMS for your Nuxt application, powered by Markdown and Vue components.

Pros of Content

Integrated with Nuxt.js framework, providing seamless content management for Nuxt applications
Built-in full-text search functionality
Supports multiple content formats (Markdown, CSV, YAML, JSON)

Cons of Content

Limited to Nuxt.js ecosystem, less flexible for other frameworks
Steeper learning curve for developers not familiar with Nuxt.js
Less community-driven extensions and plugins compared to MDX

Code Comparison

MDX:

import { MDXProvider } from '@mdx-js/react'
import components from './components'

<MDXProvider components={components}>
  <MDXContent />
</MDXProvider>

Content:

<template>
  <NuxtContent :document="article" />
</template>

<script>
export default {
  async asyncData({ $content }) {
    const article = await $content('articles').fetch()
    return { article }
  }
}
</script>

MDX is a more generic solution for using JSX in Markdown, while Content is tightly integrated with Nuxt.js, offering a streamlined content management system for Nuxt applications. MDX provides greater flexibility across different frameworks, whereas Content offers a more opinionated and feature-rich solution specifically for Nuxt projects. The choice between the two depends on the project requirements and the developer's familiarity with the respective ecosystems.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Markdown for the component era

MDX is an authorable format that lets you seamlessly write JSX in your markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast. ð

import {Chart} from './snowfall.js'
export const year = 2013

# Last yearâs snowfall

In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.

<Chart year={year} color="#fcb32c" />

See Â§ What is MDX for more info on the format. See Â§ Playground to try it out.

What is this?

This GitHub repository contains several packages for compiling the MDX format to JavaScript, integrating with bundlers such as webpack and Rollup, and for using it with frameworks such as React, Preact, and Vue.

See Â§ Getting started for how to integrate MDX into your project.