Что такое MDX

MDX (Markdown for JSX) представляет собой расширение стандартного Markdown, позволяющее интегрировать компоненты React прямо в текстовый контент. Основное отличие MDX от обычного Markdown заключается в возможности смешивания разметки с интерактивными элементами, компонентами и логикой на JavaScript.

В основе MDX лежат три ключевых элемента:

  1. Markdown-разметка — используется привычная синтаксическая структура: заголовки, списки, таблицы, ссылки, изображения.
  2. JSX-компоненты — любой React-компонент может быть встроен в MDX-документ как тег.
  3. Экспорт и импорты — MDX-файлы поддерживают стандартные конструкции ES Modules (import, export), что позволяет подключать внешние библиотеки и компоненты.

Структура MDX-документа

MDX-документ можно представить как сочетание обычного Markdown и React-компонентов. Простейший пример структуры:

import { Alert } from './components/Alert'

# Заголовок документа

Текстовое содержимое с **Markdown**-разметкой.


  Это предупреждение, реализованное через React-компонент.

Здесь:

  • import { Alert } from './components/Alert' подключает внешний компонент.
  • # Заголовок документа — стандартный заголовок Markdown.
  • ... — JSX-компонент, встроенный в текст.

MDX позволяет не только отображать компоненты, но и использовать их свойства, передавать динамические данные и комбинировать с обычной Markdown-разметкой.

Импорты и экспорт в MDX

MDX поддерживает полные возможности ES Modules:

import Button from './Button'
import { Card, Header } from './UI'

export const meta = {
  title: 'Пример документа MDX',
  date: '2026-03-23'
}
  • import позволяет подключать компоненты, утилиты и даже данные.
  • export используется для метаданных документа или экспортирования функций, которые могут быть использованы в других частях приложения.

Использование экспорта метаданных особенно полезно в системах статической генерации, например Next.js или Gatsby, где можно динамически формировать списки страниц и SEO-данные.

Интеграция React-компонентов

MDX позволяет вставлять компоненты React как элементы JSX. Встроенные компоненты могут быть как простыми визуальными блоками, так и интерактивными элементами с состоянием.

Пример динамического компонента:

import { Counter } from './Counter'

Здесь компонент Counter может содержать локальное состояние и обработчики событий, полностью функционируя внутри MDX-документа.

MDX автоматически преобразует JSX в React-код при сборке, поэтому компоненты работают без дополнительной настройки.

Переопределение стандартных Markdown-компонентов

MDX предоставляет возможность кастомизации стандартных HTML-тегов, генерируемых Markdown. Например, можно заменить все заголовки или ссылки на собственные компоненты:

// components/MDXComponents.js
import { H1, H2, CustomLink } from './UI'

export const components = {
  h1: H1,
  h2: H2,
  a: CustomLink
}

Затем при рендеринге MDX можно передать этот объект:

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

В результате все # и ## будут использовать кастомные React-компоненты H1 и H2, а ссылки — CustomLink.

Использование динамических данных

MDX поддерживает JavaScript внутри документа, что позволяет внедрять динамический контент:

export const today = new Date().toLocaleDateString()

Сегодняшняя дата: {today}

Также можно использовать функции и массивы:

const items = ['Первый', 'Второй', 'Третий']


    
  {items.map(item => (
    
  • {item}
    • 
  ))}

MDX автоматически превращает JavaScript-выражения в JSX и рендерит результат.

Преимущества MDX

  • Интерактивность: возможность вставлять React-компоненты в документацию.
  • Универсальность: можно использовать в проектах Next.js, Gatsby, Remix и других React-приложениях.
  • Расширяемость: поддержка импортов, экспортов и кастомизации компонентов.
  • Динамический контент: интеграция JavaScript позволяет создавать интерактивные таблицы, графики и виджеты прямо внутри Markdown-документа.

Инструменты и экосистема

Для работы с MDX существует несколько ключевых инструментов:

  • @mdx-js/mdx — основной компилятор MDX, преобразует файлы .mdx в React-код.
  • @mdx-js/react — предоставляет MDXProvider для рендеринга MDX-документов в React.
  • Next.js / Gatsby — нативная поддержка MDX через плагины (@next/mdx, gatsby-plugin-mdx).
  • MDX Deck — генерация презентаций на основе MDX.

Каждый инструмент обеспечивает поддержку различных функций, от простой документации до сложных интерактивных интерфейсов.

Оглавление